/ Hex Artifact Content
Login

Artifact 0a87152a6dde55381afb8f1cf37f337b2f32fd06:


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 77 69 74 68 20 6d 75 74 65 78 69  iled with mutexi
1be0: 6e 67 20 63 6f 64 65 20 6f 6d 69 74 74 65 64 20  ng code omitted 
1bf0: 64 75 65 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 53  due to the.** [S
1c00: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
1c10: 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
1c20: 70 74 69 6f 6e 20 62 65 69 6e 67 20 73 65 74 20  ption being set 
1c30: 74 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  to 0..**.** SQLi
1c40: 74 65 20 63 61 6e 20 62 65 20 63 6f 6d 70 69 6c  te can be compil
1c50: 65 64 20 77 69 74 68 20 6f 72 20 77 69 74 68 6f  ed with or witho
1c60: 75 74 20 6d 75 74 65 78 65 73 2e 20 20 57 68 65  ut mutexes.  Whe
1c70: 6e 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  n.** the [SQLITE
1c80: 5f 54 48 52 45 41 44 53 41 46 45 5d 20 43 20 70  _THREADSAFE] C p
1c90: 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  reprocessor macr
1ca0: 6f 20 69 73 20 31 20 6f 72 20 32 2c 20 6d 75 74  o is 1 or 2, mut
1cb0: 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62  exes.** are enab
1cc0: 6c 65 64 20 61 6e 64 20 53 51 4c 69 74 65 20 69  led and SQLite i
1cd0: 73 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 57  s threadsafe.  W
1ce0: 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  hen the.** [SQLI
1cf0: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d  TE_THREADSAFE] m
1d00: 61 63 72 6f 20 69 73 20 30 2c 20 0a 2a 2a 20 74  acro is 0, .** t
1d10: 68 65 20 6d 75 74 65 78 65 73 20 61 72 65 20 6f  he mutexes are o
1d20: 6d 69 74 74 65 64 2e 20 20 57 69 74 68 6f 75 74  mitted.  Without
1d30: 20 74 68 65 20 6d 75 74 65 78 65 73 2c 20 69 74   the mutexes, it
1d40: 20 69 73 20 6e 6f 74 20 73 61 66 65 0a 2a 2a 20   is not safe.** 
1d50: 74 6f 20 75 73 65 20 53 51 4c 69 74 65 20 63 6f  to use SQLite co
1d60: 6e 63 75 72 72 65 6e 74 6c 79 20 66 72 6f 6d 20  ncurrently from 
1d70: 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 74 68  more than one th
1d80: 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e 61 62  read..**.** Enab
1d90: 6c 69 6e 67 20 6d 75 74 65 78 65 73 20 69 6e 63  ling mutexes inc
1da0: 75 72 73 20 61 20 6d 65 61 73 75 72 61 62 6c 65  urs a measurable
1db0: 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 70 65 6e   performance pen
1dc0: 61 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69 66 20 73  alty..** So if s
1dd0: 70 65 65 64 20 69 73 20 6f 66 20 75 74 6d 6f 73  peed is of utmos
1de0: 74 20 69 6d 70 6f 72 74 61 6e 63 65 2c 20 69 74  t importance, it
1df0: 20 6d 61 6b 65 73 20 73 65 6e 73 65 20 74 6f 20   makes sense to 
1e00: 64 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 6d  disable.** the m
1e10: 75 74 65 78 65 73 2e 20 20 42 75 74 20 66 6f 72  utexes.  But for
1e20: 20 6d 61 78 69 6d 75 6d 20 73 61 66 65 74 79 2c   maximum safety,
1e30: 20 6d 75 74 65 78 65 73 20 73 68 6f 75 6c 64 20   mutexes should 
1e40: 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 5e  be enabled..** ^
1e50: 54 68 65 20 64 65 66 61 75 6c 74 20 62 65 68 61  The default beha
1e60: 76 69 6f 72 20 69 73 20 66 6f 72 20 6d 75 74 65  vior is for mute
1e70: 78 65 73 20 74 6f 20 62 65 20 65 6e 61 62 6c 65  xes to be enable
1e80: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e  d..**.** This in
1e90: 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75  terface can be u
1ea0: 73 65 64 20 62 79 20 61 6e 20 61 70 70 6c 69 63  sed by an applic
1eb0: 61 74 69 6f 6e 20 74 6f 20 6d 61 6b 65 20 73 75  ation to make su
1ec0: 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 76  re that the.** v
1ed0: 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65  ersion of SQLite
1ee0: 20 74 68 61 74 20 69 74 20 69 73 20 6c 69 6e 6b   that it is link
1ef0: 69 6e 67 20 61 67 61 69 6e 73 74 20 77 61 73 20  ing against was 
1f00: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
1f10: 20 74 68 65 20 64 65 73 69 72 65 64 20 73 65 74   the desired set
1f20: 74 69 6e 67 20 6f 66 20 74 68 65 20 5b 53 51 4c  ting of the [SQL
1f30: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20  ITE_THREADSAFE] 
1f40: 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  macro..**.** Thi
1f50: 73 20 69 6e 74 65 72 66 61 63 65 20 6f 6e 6c 79  s interface only
1f60: 20 72 65 70 6f 72 74 73 20 6f 6e 20 74 68 65 20   reports on the 
1f70: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 75 74  compile-time mut
1f80: 65 78 20 73 65 74 74 69 6e 67 0a 2a 2a 20 6f 66  ex setting.** of
1f90: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
1fa0: 45 41 44 53 41 46 45 5d 20 66 6c 61 67 2e 20 20  EADSAFE] flag.  
1fb0: 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
1fc0: 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 53 51  piled with.** SQ
1fd0: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
1fe0: 31 20 6f 72 20 3d 32 20 74 68 65 6e 20 6d 75 74  1 or =2 then mut
1ff0: 65 78 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64  exes are enabled
2000: 20 62 79 20 64 65 66 61 75 6c 74 20 62 75 74 0a   by default but.
2010: 2a 2a 20 63 61 6e 20 62 65 20 66 75 6c 6c 79 20  ** can be fully 
2020: 6f 72 20 70 61 72 74 69 61 6c 6c 79 20 64 69 73  or partially dis
2030: 61 62 6c 65 64 20 75 73 69 6e 67 20 61 20 63 61  abled using a ca
2040: 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ll to [sqlite3_c
2050: 6f 6e 66 69 67 28 29 5d 0a 2a 2a 20 77 69 74 68  onfig()].** with
2060: 20 74 68 65 20 76 65 72 62 73 20 5b 53 51 4c 49   the verbs [SQLI
2070: 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
2080: 54 48 52 45 41 44 5d 2c 20 5b 53 51 4c 49 54 45  THREAD], [SQLITE
2090: 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
20a0: 45 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c  EAD],.** or [SQL
20b0: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
20c0: 5d 2e 20 20 5e 28 54 68 65 20 72 65 74 75 72 6e  ].  ^(The return
20d0: 20 76 61 6c 75 65 20 6f 66 20 74 68 65 0a 2a 2a   value of the.**
20e0: 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73   sqlite3_threads
20f0: 61 66 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 73  afe() function s
2100: 68 6f 77 73 20 6f 6e 6c 79 20 74 68 65 20 63 6f  hows only the co
2110: 6d 70 69 6c 65 2d 74 69 6d 65 20 73 65 74 74 69  mpile-time setti
2120: 6e 67 20 6f 66 0a 2a 2a 20 74 68 72 65 61 64 20  ng of.** thread 
2130: 73 61 66 65 74 79 2c 20 6e 6f 74 20 61 6e 79 20  safety, not any 
2140: 72 75 6e 2d 74 69 6d 65 20 63 68 61 6e 67 65 73  run-time changes
2150: 20 74 6f 20 74 68 61 74 20 73 65 74 74 69 6e 67   to that setting
2160: 20 6d 61 64 65 20 62 79 0a 2a 2a 20 73 71 6c 69   made by.** sqli
2170: 74 65 33 5f 63 6f 6e 66 69 67 28 29 2e 20 49 6e  te3_config(). In
2180: 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
2190: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66  e return value f
21a0: 72 6f 6d 20 73 71 6c 69 74 65 33 5f 74 68 72 65  rom sqlite3_thre
21b0: 61 64 73 61 66 65 28 29 0a 2a 2a 20 69 73 20 75  adsafe().** is u
21c0: 6e 63 68 61 6e 67 65 64 20 62 79 20 63 61 6c 6c  nchanged by call
21d0: 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e  s to sqlite3_con
21e0: 66 69 67 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53  fig().)^.**.** S
21f0: 65 65 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e  ee the [threadin
2200: 67 20 6d 6f 64 65 5d 20 64 6f 63 75 6d 65 6e 74  g mode] document
2210: 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69  ation for additi
2220: 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
2230: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
2240: 5f 74 68 72 65 61 64 73 61 66 65 28 76 6f 69 64  _threadsafe(void
2250: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2260: 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e  EF: Database Con
2270: 6e 65 63 74 69 6f 6e 20 48 61 6e 64 6c 65 0a 2a  nection Handle.*
2280: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 64 61 74  * KEYWORDS: {dat
2290: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
22a0: 7d 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  } {database conn
22b0: 65 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45  ections}.**.** E
22c0: 61 63 68 20 6f 70 65 6e 20 53 51 4c 69 74 65 20  ach open SQLite 
22d0: 64 61 74 61 62 61 73 65 20 69 73 20 72 65 70 72  database is repr
22e0: 65 73 65 6e 74 65 64 20 62 79 20 61 20 70 6f 69  esented by a poi
22f0: 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61  nter to an insta
2300: 6e 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6f 70  nce of.** the op
2310: 61 71 75 65 20 73 74 72 75 63 74 75 72 65 20 6e  aque structure n
2320: 61 6d 65 64 20 22 73 71 6c 69 74 65 33 22 2e 20  amed "sqlite3". 
2330: 20 49 74 20 69 73 20 75 73 65 66 75 6c 20 74 6f   It is useful to
2340: 20 74 68 69 6e 6b 20 6f 66 20 61 6e 20 73 71 6c   think of an sql
2350: 69 74 65 33 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  ite3.** pointer 
2360: 61 73 20 61 6e 20 6f 62 6a 65 63 74 2e 20 20 54  as an object.  T
2370: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  he [sqlite3_open
2380: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
2390: 65 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20  en16()], and.** 
23a0: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
23b0: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 61  ()] interfaces a
23c0: 72 65 20 69 74 73 20 63 6f 6e 73 74 72 75 63 74  re its construct
23d0: 6f 72 73 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65  ors, and [sqlite
23e0: 33 5f 63 6c 6f 73 65 28 29 5d 0a 2a 2a 20 61 6e  3_close()].** an
23f0: 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  d [sqlite3_close
2400: 5f 76 32 28 29 5d 20 61 72 65 20 69 74 73 20 64  _v2()] are its d
2410: 65 73 74 72 75 63 74 6f 72 73 2e 20 20 54 68 65  estructors.  The
2420: 72 65 20 61 72 65 20 6d 61 6e 79 20 6f 74 68 65  re are many othe
2430: 72 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  r.** interfaces 
2440: 28 73 75 63 68 20 61 73 0a 2a 2a 20 5b 73 71 6c  (such as.** [sql
2450: 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
2460: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  )], [sqlite3_cre
2470: 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 2c  ate_function()],
2480: 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
2490: 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d  _busy_timeout()]
24a0: 20 74 6f 20 6e 61 6d 65 20 62 75 74 20 74 68 72   to name but thr
24b0: 65 65 29 20 74 68 61 74 20 61 72 65 20 6d 65 74  ee) that are met
24c0: 68 6f 64 73 20 6f 6e 20 61 6e 0a 2a 2a 20 73 71  hods on an.** sq
24d0: 6c 69 74 65 33 20 6f 62 6a 65 63 74 2e 0a 2a 2f  lite3 object..*/
24e0: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
24f0: 73 71 6c 69 74 65 33 20 73 71 6c 69 74 65 33 3b  sqlite3 sqlite3;
2500: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2510: 3a 20 36 34 2d 42 69 74 20 49 6e 74 65 67 65 72  : 64-Bit Integer
2520: 20 54 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52   Types.** KEYWOR
2530: 44 53 3a 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  DS: sqlite_int64
2540: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 0a 2a   sqlite_uint64.*
2550: 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65  *.** Because the
2560: 72 65 20 69 73 20 6e 6f 20 63 72 6f 73 73 2d 70  re is no cross-p
2570: 6c 61 74 66 6f 72 6d 20 77 61 79 20 74 6f 20 73  latform way to s
2580: 70 65 63 69 66 79 20 36 34 2d 62 69 74 20 69 6e  pecify 64-bit in
2590: 74 65 67 65 72 20 74 79 70 65 73 0a 2a 2a 20 53  teger types.** S
25a0: 51 4c 69 74 65 20 69 6e 63 6c 75 64 65 73 20 74  QLite includes t
25b0: 79 70 65 64 65 66 73 20 66 6f 72 20 36 34 2d 62  ypedefs for 64-b
25c0: 69 74 20 73 69 67 6e 65 64 20 61 6e 64 20 75 6e  it signed and un
25d0: 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 73 2e  signed integers.
25e0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
25f0: 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c  e3_int64 and sql
2600: 69 74 65 33 5f 75 69 6e 74 36 34 20 61 72 65 20  ite3_uint64 are 
2610: 74 68 65 20 70 72 65 66 65 72 72 65 64 20 74 79  the preferred ty
2620: 70 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 2e 0a  pe definitions..
2630: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 5f 69 6e  ** The sqlite_in
2640: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 75  t64 and sqlite_u
2650: 69 6e 74 36 34 20 74 79 70 65 73 20 61 72 65 20  int64 types are 
2660: 73 75 70 70 6f 72 74 65 64 20 66 6f 72 20 62 61  supported for ba
2670: 63 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d 70 61  ckwards.** compa
2680: 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e 0a 2a  tibility only..*
2690: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
26a0: 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69  3_int64 and sqli
26b0: 74 65 5f 69 6e 74 36 34 20 74 79 70 65 73 20 63  te_int64 types c
26c0: 61 6e 20 73 74 6f 72 65 20 69 6e 74 65 67 65 72  an store integer
26d0: 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65   values.** betwe
26e0: 65 6e 20 2d 39 32 32 33 33 37 32 30 33 36 38 35  en -922337203685
26f0: 34 37 37 35 38 30 38 20 61 6e 64 20 2b 39 32 32  4775808 and +922
2700: 33 33 37 32 30 33 36 38 35 34 37 37 35 38 30 37  3372036854775807
2710: 20 69 6e 63 6c 75 73 69 76 65 2e 20 20 5e 54 68   inclusive.  ^Th
2720: 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 69 6e  e.** sqlite3_uin
2730: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 75  t64 and sqlite_u
2740: 69 6e 74 36 34 20 74 79 70 65 73 20 63 61 6e 20  int64 types can 
2750: 73 74 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61  store integer va
2760: 6c 75 65 73 20 0a 2a 2a 20 62 65 74 77 65 65 6e  lues .** between
2770: 20 30 20 61 6e 64 20 2b 31 38 34 34 36 37 34 34   0 and +18446744
2780: 30 37 33 37 30 39 35 35 31 36 31 35 20 69 6e 63  073709551615 inc
2790: 6c 75 73 69 76 65 2e 0a 2a 2f 0a 23 69 66 64 65  lusive..*/.#ifde
27a0: 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54  f SQLITE_INT64_T
27b0: 59 50 45 0a 20 20 74 79 70 65 64 65 66 20 53 51  YPE.  typedef SQ
27c0: 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20  LITE_INT64_TYPE 
27d0: 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20  sqlite_int64;.  
27e0: 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64  typedef unsigned
27f0: 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59   SQLITE_INT64_TY
2800: 50 45 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  PE sqlite_uint64
2810: 3b 0a 23 65 6c 69 66 20 64 65 66 69 6e 65 64 28  ;.#elif defined(
2820: 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64 65 66  _MSC_VER) || def
2830: 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f  ined(__BORLANDC_
2840: 5f 29 0a 20 20 74 79 70 65 64 65 66 20 5f 5f 69  _).  typedef __i
2850: 6e 74 36 34 20 73 71 6c 69 74 65 5f 69 6e 74 36  nt64 sqlite_int6
2860: 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73  4;.  typedef uns
2870: 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20 73 71  igned __int64 sq
2880: 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c  lite_uint64;.#el
2890: 73 65 0a 20 20 74 79 70 65 64 65 66 20 6c 6f 6e  se.  typedef lon
28a0: 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74  g long int sqlit
28b0: 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64  e_int64;.  typed
28c0: 65 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f 6e 67  ef unsigned long
28d0: 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65   long int sqlite
28e0: 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69 66 0a  _uint64;.#endif.
28f0: 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f 69  typedef sqlite_i
2900: 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 69 6e 74  nt64 sqlite3_int
2910: 36 34 3b 0a 74 79 70 65 64 65 66 20 73 71 6c 69  64;.typedef sqli
2920: 74 65 5f 75 69 6e 74 36 34 20 73 71 6c 69 74 65  te_uint64 sqlite
2930: 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a  3_uint64;../*.**
2940: 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20 66 6f   If compiling fo
2950: 72 20 61 20 70 72 6f 63 65 73 73 6f 72 20 74 68  r a processor th
2960: 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74 69 6e  at lacks floatin
2970: 67 20 70 6f 69 6e 74 20 73 75 70 70 6f 72 74 2c  g point support,
2980: 0a 2a 2a 20 73 75 62 73 74 69 74 75 74 65 20 69  .** substitute i
2990: 6e 74 65 67 65 72 20 66 6f 72 20 66 6c 6f 61 74  nteger for float
29a0: 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69  ing-point..*/.#i
29b0: 66 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54  fdef SQLITE_OMIT
29c0: 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a  _FLOATING_POINT.
29d0: 23 20 64 65 66 69 6e 65 20 64 6f 75 62 6c 65 20  # define double 
29e0: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a 23 65  sqlite3_int64.#e
29f0: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ndif../*.** CAPI
2a00: 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20 41 20  3REF: Closing A 
2a10: 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
2a20: 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ion.**.** ^The s
2a30: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 61  qlite3_close() a
2a40: 6e 64 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  nd sqlite3_close
2a50: 5f 76 32 28 29 20 72 6f 75 74 69 6e 65 73 20 61  _v2() routines a
2a60: 72 65 20 64 65 73 74 72 75 63 74 6f 72 73 0a 2a  re destructors.*
2a70: 2a 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74  * for the [sqlit
2a80: 65 33 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e  e3] object..** ^
2a90: 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  Calls to sqlite3
2aa0: 5f 63 6c 6f 73 65 28 29 20 61 6e 64 20 73 71 6c  _close() and sql
2ab0: 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20  ite3_close_v2() 
2ac0: 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b  return SQLITE_OK
2ad0: 20 69 66 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69   if.** the [sqli
2ae0: 74 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 73  te3] object is s
2af0: 75 63 63 65 73 73 66 75 6c 6c 79 20 64 65 73 74  uccessfully dest
2b00: 72 6f 79 65 64 20 61 6e 64 20 61 6c 6c 20 61 73  royed and all as
2b10: 73 6f 63 69 61 74 65 64 0a 2a 2a 20 72 65 73 6f  sociated.** reso
2b20: 75 72 63 65 73 20 61 72 65 20 64 65 61 6c 6c 6f  urces are deallo
2b30: 63 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  cated..**.** ^If
2b40: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
2b50: 6e 6e 65 63 74 69 6f 6e 20 69 73 20 61 73 73 6f  nnection is asso
2b60: 63 69 61 74 65 64 20 77 69 74 68 20 75 6e 66 69  ciated with unfi
2b70: 6e 61 6c 69 7a 65 64 20 70 72 65 70 61 72 65 64  nalized prepared
2b80: 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 20 6f  .** statements o
2b90: 72 20 75 6e 66 69 6e 69 73 68 65 64 20 73 71 6c  r unfinished sql
2ba0: 69 74 65 33 5f 62 61 63 6b 75 70 20 6f 62 6a 65  ite3_backup obje
2bb0: 63 74 73 20 74 68 65 6e 20 73 71 6c 69 74 65 33  cts then sqlite3
2bc0: 5f 63 6c 6f 73 65 28 29 0a 2a 2a 20 77 69 6c 6c  _close().** will
2bd0: 20 6c 65 61 76 65 20 74 68 65 20 64 61 74 61 62   leave the datab
2be0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f  ase connection o
2bf0: 70 65 6e 20 61 6e 64 20 72 65 74 75 72 6e 20 5b  pen and return [
2c00: 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a  SQLITE_BUSY]..**
2c10: 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6c 6f   ^If sqlite3_clo
2c20: 73 65 5f 76 32 28 29 20 69 73 20 63 61 6c 6c 65  se_v2() is calle
2c30: 64 20 77 69 74 68 20 75 6e 66 69 6e 61 6c 69 7a  d with unfinaliz
2c40: 65 64 20 70 72 65 70 61 72 65 64 20 73 74 61 74  ed prepared stat
2c50: 65 6d 65 6e 74 73 0a 2a 2a 20 61 6e 64 20 75 6e  ements.** and un
2c60: 66 69 6e 69 73 68 65 64 20 73 71 6c 69 74 65 33  finished sqlite3
2c70: 5f 62 61 63 6b 75 70 73 2c 20 74 68 65 6e 20 74  _backups, then t
2c80: 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
2c90: 65 63 74 69 6f 6e 20 62 65 63 6f 6d 65 73 0a 2a  ection becomes.*
2ca0: 2a 20 61 6e 20 75 6e 75 73 61 62 6c 65 20 22 7a  * an unusable "z
2cb0: 6f 6d 62 69 65 22 20 77 68 69 63 68 20 77 69 6c  ombie" which wil
2cc0: 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  l automatically 
2cd0: 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 77  be deallocated w
2ce0: 68 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 73 74 20  hen the.** last 
2cf0: 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2d00: 6e 74 20 69 73 20 66 69 6e 61 6c 69 7a 65 64 20  nt is finalized 
2d10: 6f 72 20 74 68 65 20 6c 61 73 74 20 73 71 6c 69  or the last sqli
2d20: 74 65 33 5f 62 61 63 6b 75 70 20 69 73 0a 2a 2a  te3_backup is.**
2d30: 20 66 69 6e 69 73 68 65 64 2e 20 20 54 68 65 20   finished.  The 
2d40: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32  sqlite3_close_v2
2d50: 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
2d60: 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65  intended for use
2d70: 20 77 69 74 68 0a 2a 2a 20 68 6f 73 74 20 6c 61   with.** host la
2d80: 6e 67 75 61 67 65 73 20 74 68 61 74 20 61 72 65  nguages that are
2d90: 20 67 61 72 62 61 67 65 20 63 6f 6c 6c 65 63 74   garbage collect
2da0: 65 64 2c 20 61 6e 64 20 77 68 65 72 65 20 74 68  ed, and where th
2db0: 65 20 6f 72 64 65 72 20 69 6e 20 77 68 69 63 68  e order in which
2dc0: 0a 2a 2a 20 64 65 73 74 72 75 63 74 6f 72 73 20  .** destructors 
2dd0: 61 72 65 20 63 61 6c 6c 65 64 20 69 73 20 61 72  are called is ar
2de0: 62 69 74 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 41  bitrary..**.** A
2df0: 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75  pplications shou
2e00: 6c 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ld [sqlite3_fina
2e10: 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 5d  lize | finalize]
2e20: 20 61 6c 6c 20 5b 70 72 65 70 61 72 65 64 20 73   all [prepared s
2e30: 74 61 74 65 6d 65 6e 74 73 5d 2c 0a 2a 2a 20 5b  tatements],.** [
2e40: 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f  sqlite3_blob_clo
2e50: 73 65 20 7c 20 63 6c 6f 73 65 5d 20 61 6c 6c 20  se | close] all 
2e60: 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20  [BLOB handles], 
2e70: 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  and .** [sqlite3
2e80: 5f 62 61 63 6b 75 70 5f 66 69 6e 69 73 68 20 7c  _backup_finish |
2e90: 20 66 69 6e 69 73 68 5d 20 61 6c 6c 20 5b 73 71   finish] all [sq
2ea0: 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62  lite3_backup] ob
2eb0: 6a 65 63 74 73 20 61 73 73 6f 63 69 61 74 65 64  jects associated
2ec0: 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 73 71  .** with the [sq
2ed0: 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 70 72  lite3] object pr
2ee0: 69 6f 72 20 74 6f 20 61 74 74 65 6d 70 74 69 6e  ior to attemptin
2ef0: 67 20 74 6f 20 63 6c 6f 73 65 20 74 68 65 20 6f  g to close the o
2f00: 62 6a 65 63 74 2e 20 20 5e 49 66 0a 2a 2a 20 73  bject.  ^If.** s
2f10: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28  qlite3_close_v2(
2f20: 29 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61  ) is called on a
2f30: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
2f40: 63 74 69 6f 6e 5d 20 74 68 61 74 20 73 74 69 6c  ction] that stil
2f50: 6c 20 68 61 73 0a 2a 2a 20 6f 75 74 73 74 61 6e  l has.** outstan
2f60: 64 69 6e 67 20 5b 70 72 65 70 61 72 65 64 20 73  ding [prepared s
2f70: 74 61 74 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f  tatements], [BLO
2f80: 42 20 68 61 6e 64 6c 65 73 5d 2c 20 61 6e 64 2f  B handles], and/
2f90: 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  or.** [sqlite3_b
2fa0: 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74 73 20 74  ackup] objects t
2fb0: 68 65 6e 20 69 74 20 72 65 74 75 72 6e 73 20 53  hen it returns S
2fc0: 51 4c 49 54 45 5f 4f 4b 20 62 75 74 20 74 68 65  QLITE_OK but the
2fd0: 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a   deallocation.**
2fe0: 20 6f 66 20 72 65 73 6f 75 72 63 65 73 20 69 73   of resources is
2ff0: 20 64 65 66 65 72 72 65 64 20 75 6e 74 69 6c 20   deferred until 
3000: 61 6c 6c 20 5b 70 72 65 70 61 72 65 64 20 73 74  all [prepared st
3010: 61 74 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42  atements], [BLOB
3020: 20 68 61 6e 64 6c 65 73 5d 2c 0a 2a 2a 20 61 6e   handles],.** an
3030: 64 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75  d [sqlite3_backu
3040: 70 5d 20 6f 62 6a 65 63 74 73 20 61 72 65 20 61  p] objects are a
3050: 6c 73 6f 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a  lso destroyed..*
3060: 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 5b 73 71 6c  *.** ^If an [sql
3070: 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20  ite3] object is 
3080: 64 65 73 74 72 6f 79 65 64 20 77 68 69 6c 65 20  destroyed while 
3090: 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73  a transaction is
30a0: 20 6f 70 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72   open,.** the tr
30b0: 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 61 75 74  ansaction is aut
30c0: 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65  omatically rolle
30d0: 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68  d back..**.** Th
30e0: 65 20 43 20 70 61 72 61 6d 65 74 65 72 20 74 6f  e C parameter to
30f0: 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28   [sqlite3_close(
3100: 43 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  C)] and [sqlite3
3110: 5f 63 6c 6f 73 65 5f 76 32 28 43 29 5d 0a 2a 2a  _close_v2(C)].**
3120: 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20   must be either 
3130: 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65  a NULL.** pointe
3140: 72 20 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65 33  r or an [sqlite3
3150: 5d 20 6f 62 6a 65 63 74 20 70 6f 69 6e 74 65 72  ] object pointer
3160: 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f   obtained.** fro
3170: 6d 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  m [sqlite3_open(
3180: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  )], [sqlite3_ope
3190: 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73  n16()], or.** [s
31a0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
31b0: 5d 2c 20 61 6e 64 20 6e 6f 74 20 70 72 65 76 69  ], and not previ
31c0: 6f 75 73 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a  ously closed..**
31d0: 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65   ^Calling sqlite
31e0: 33 5f 63 6c 6f 73 65 28 29 20 6f 72 20 73 71 6c  3_close() or sql
31f0: 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20  ite3_close_v2() 
3200: 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  with a NULL poin
3210: 74 65 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  ter.** argument 
3220: 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f  is a harmless no
3230: 2d 6f 70 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  -op..*/.int sqli
3240: 74 65 33 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65  te3_close(sqlite
3250: 33 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  3*);.int sqlite3
3260: 5f 63 6c 6f 73 65 5f 76 32 28 73 71 6c 69 74 65  _close_v2(sqlite
3270: 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20  3*);../*.** The 
3280: 74 79 70 65 20 66 6f 72 20 61 20 63 61 6c 6c 62  type for a callb
3290: 61 63 6b 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a  ack function..**
32a0: 20 54 68 69 73 20 69 73 20 6c 65 67 61 63 79 20   This is legacy 
32b0: 61 6e 64 20 64 65 70 72 65 63 61 74 65 64 2e 20  and deprecated. 
32c0: 20 49 74 20 69 73 20 69 6e 63 6c 75 64 65 64 20   It is included 
32d0: 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 0a 2a  for historical.*
32e0: 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20  * compatibility 
32f0: 61 6e 64 20 69 73 20 6e 6f 74 20 64 6f 63 75 6d  and is not docum
3300: 65 6e 74 65 64 2e 0a 2a 2f 0a 74 79 70 65 64 65  ented..*/.typede
3310: 66 20 69 6e 74 20 28 2a 73 71 6c 69 74 65 33 5f  f int (*sqlite3_
3320: 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c  callback)(void*,
3330: 69 6e 74 2c 63 68 61 72 2a 2a 2c 20 63 68 61 72  int,char**, char
3340: 2a 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  **);../*.** CAPI
3350: 33 52 45 46 3a 20 4f 6e 65 2d 53 74 65 70 20 51  3REF: One-Step Q
3360: 75 65 72 79 20 45 78 65 63 75 74 69 6f 6e 20 49  uery Execution I
3370: 6e 74 65 72 66 61 63 65 0a 2a 2a 0a 2a 2a 20 54  nterface.**.** T
3380: 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  he sqlite3_exec(
3390: 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 61  ) interface is a
33a0: 20 63 6f 6e 76 65 6e 69 65 6e 63 65 20 77 72 61   convenience wra
33b0: 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b  pper around.** [
33c0: 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
33d0: 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  v2()], [sqlite3_
33e0: 73 74 65 70 28 29 5d 2c 20 61 6e 64 20 5b 73 71  step()], and [sq
33f0: 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
3400: 5d 2c 0a 2a 2a 20 74 68 61 74 20 61 6c 6c 6f 77  ],.** that allow
3410: 73 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  s an application
3420: 20 74 6f 20 72 75 6e 20 6d 75 6c 74 69 70 6c 65   to run multiple
3430: 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 66 20 53   statements of S
3440: 51 4c 0a 2a 2a 20 77 69 74 68 6f 75 74 20 68 61  QL.** without ha
3450: 76 69 6e 67 20 74 6f 20 75 73 65 20 61 20 6c 6f  ving to use a lo
3460: 74 20 6f 66 20 43 20 63 6f 64 65 2e 20 0a 2a 2a  t of C code. .**
3470: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
3480: 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66 61 63  _exec() interfac
3490: 65 20 72 75 6e 73 20 7a 65 72 6f 20 6f 72 20 6d  e runs zero or m
34a0: 6f 72 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 65  ore UTF-8 encode
34b0: 64 2c 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d  d,.** semicolon-
34c0: 73 65 70 61 72 61 74 65 20 53 51 4c 20 73 74 61  separate SQL sta
34d0: 74 65 6d 65 6e 74 73 20 70 61 73 73 65 64 20 69  tements passed i
34e0: 6e 74 6f 20 69 74 73 20 32 6e 64 20 61 72 67 75  nto its 2nd argu
34f0: 6d 65 6e 74 2c 0a 2a 2a 20 69 6e 20 74 68 65 20  ment,.** in the 
3500: 63 6f 6e 74 65 78 74 20 6f 66 20 74 68 65 20 5b  context of the [
3510: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
3520: 69 6f 6e 5d 20 70 61 73 73 65 64 20 69 6e 20 61  ion] passed in a
3530: 73 20 69 74 73 20 31 73 74 0a 2a 2a 20 61 72 67  s its 1st.** arg
3540: 75 6d 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 20  ument.  ^If the 
3550: 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
3560: 6e 20 6f 66 20 74 68 65 20 33 72 64 20 61 72 67  n of the 3rd arg
3570: 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c 69  ument to.** sqli
3580: 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 6e 6f  te3_exec() is no
3590: 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 69 74 20  t NULL, then it 
35a0: 69 73 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 65  is invoked for e
35b0: 61 63 68 20 72 65 73 75 6c 74 20 72 6f 77 0a 2a  ach result row.*
35c0: 2a 20 63 6f 6d 69 6e 67 20 6f 75 74 20 6f 66 20  * coming out of 
35d0: 74 68 65 20 65 76 61 6c 75 61 74 65 64 20 53 51  the evaluated SQ
35e0: 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 20 20 5e  L statements.  ^
35f0: 54 68 65 20 34 74 68 20 61 72 67 75 6d 65 6e 74  The 4th argument
3600: 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65   to.** sqlite3_e
3610: 78 65 63 28 29 20 69 73 20 72 65 6c 61 79 65 64  xec() is relayed
3620: 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68 65 20   through to the 
3630: 31 73 74 20 61 72 67 75 6d 65 6e 74 20 6f 66 20  1st argument of 
3640: 65 61 63 68 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b  each.** callback
3650: 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 20 20 5e 49   invocation.  ^I
3660: 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 70  f the callback p
3670: 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ointer to sqlite
3680: 33 5f 65 78 65 63 28 29 0a 2a 2a 20 69 73 20 4e  3_exec().** is N
3690: 55 4c 4c 2c 20 74 68 65 6e 20 6e 6f 20 63 61 6c  ULL, then no cal
36a0: 6c 62 61 63 6b 20 69 73 20 65 76 65 72 20 69 6e  lback is ever in
36b0: 76 6f 6b 65 64 20 61 6e 64 20 72 65 73 75 6c 74  voked and result
36c0: 20 72 6f 77 73 20 61 72 65 0a 2a 2a 20 69 67 6e   rows are.** ign
36d0: 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ored..**.** ^If 
36e0: 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20  an error occurs 
36f0: 77 68 69 6c 65 20 65 76 61 6c 75 61 74 69 6e 67  while evaluating
3700: 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
3710: 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74 6f 0a  nts passed into.
3720: 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  ** sqlite3_exec(
3730: 29 2c 20 74 68 65 6e 20 65 78 65 63 75 74 69 6f  ), then executio
3740: 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74  n of the current
3750: 20 73 74 61 74 65 6d 65 6e 74 20 73 74 6f 70 73   statement stops
3760: 20 61 6e 64 0a 2a 2a 20 73 75 62 73 65 71 75 65   and.** subseque
3770: 6e 74 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72  nt statements ar
3780: 65 20 73 6b 69 70 70 65 64 2e 20 20 5e 49 66 20  e skipped.  ^If 
3790: 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65  the 5th paramete
37a0: 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65  r to sqlite3_exe
37b0: 63 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55  c().** is not NU
37c0: 4c 4c 20 74 68 65 6e 20 61 6e 79 20 65 72 72 6f  LL then any erro
37d0: 72 20 6d 65 73 73 61 67 65 20 69 73 20 77 72 69  r message is wri
37e0: 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79  tten into memory
37f0: 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f   obtained.** fro
3800: 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
3810: 63 28 29 5d 20 61 6e 64 20 70 61 73 73 65 64 20  c()] and passed 
3820: 62 61 63 6b 20 74 68 72 6f 75 67 68 20 74 68 65  back through the
3830: 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 2e 0a   5th parameter..
3840: 2a 2a 20 54 6f 20 61 76 6f 69 64 20 6d 65 6d 6f  ** To avoid memo
3850: 72 79 20 6c 65 61 6b 73 2c 20 74 68 65 20 61 70  ry leaks, the ap
3860: 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64  plication should
3870: 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33   invoke [sqlite3
3880: 5f 66 72 65 65 28 29 5d 0a 2a 2a 20 6f 6e 20 65  _free()].** on e
3890: 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72  rror message str
38a0: 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 74 68  ings returned th
38b0: 72 6f 75 67 68 20 74 68 65 20 35 74 68 20 70 61  rough the 5th pa
38c0: 72 61 6d 65 74 65 72 20 6f 66 0a 2a 2a 20 6f 66  rameter of.** of
38d0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
38e0: 61 66 74 65 72 20 74 68 65 20 65 72 72 6f 72 20  after the error 
38f0: 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 69  message string i
3900: 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64  s no longer need
3910: 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 35  ed..** ^If the 5
3920: 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
3930: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69  sqlite3_exec() i
3940: 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 6e  s not NULL and n
3950: 6f 20 65 72 72 6f 72 73 0a 2a 2a 20 6f 63 63 75  o errors.** occu
3960: 72 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  r, then sqlite3_
3970: 65 78 65 63 28 29 20 73 65 74 73 20 74 68 65 20  exec() sets the 
3980: 70 6f 69 6e 74 65 72 20 69 6e 20 69 74 73 20 35  pointer in its 5
3990: 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  th parameter to.
39a0: 2a 2a 20 4e 55 4c 4c 20 62 65 66 6f 72 65 20 72  ** NULL before r
39b0: 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  eturning..**.** 
39c0: 5e 49 66 20 61 6e 20 73 71 6c 69 74 65 33 5f 65  ^If an sqlite3_e
39d0: 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 72  xec() callback r
39e0: 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c  eturns non-zero,
39f0: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65   the sqlite3_exe
3a00: 63 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72  c().** routine r
3a10: 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 41 42  eturns SQLITE_AB
3a20: 4f 52 54 20 77 69 74 68 6f 75 74 20 69 6e 76 6f  ORT without invo
3a30: 6b 69 6e 67 20 74 68 65 20 63 61 6c 6c 62 61 63  king the callbac
3a40: 6b 20 61 67 61 69 6e 20 61 6e 64 0a 2a 2a 20 77  k again and.** w
3a50: 69 74 68 6f 75 74 20 72 75 6e 6e 69 6e 67 20 61  ithout running a
3a60: 6e 79 20 73 75 62 73 65 71 75 65 6e 74 20 53 51  ny subsequent SQ
3a70: 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  L statements..**
3a80: 0a 2a 2a 20 5e 54 68 65 20 32 6e 64 20 61 72 67  .** ^The 2nd arg
3a90: 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c  ument to the sql
3aa0: 69 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c  ite3_exec() call
3ab0: 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 69 73  back function is
3ac0: 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f   the.** number o
3ad0: 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65  f columns in the
3ae0: 20 72 65 73 75 6c 74 2e 20 20 5e 54 68 65 20 33   result.  ^The 3
3af0: 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  rd argument to t
3b00: 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  he sqlite3_exec(
3b10: 29 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 73  ).** callback is
3b20: 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69   an array of poi
3b30: 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73  nters to strings
3b40: 20 6f 62 74 61 69 6e 65 64 20 61 73 20 69 66 20   obtained as if 
3b50: 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  from.** [sqlite3
3b60: 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c  _column_text()],
3b70: 20 6f 6e 65 20 66 6f 72 20 65 61 63 68 20 63 6f   one for each co
3b80: 6c 75 6d 6e 2e 20 20 5e 49 66 20 61 6e 20 65 6c  lumn.  ^If an el
3b90: 65 6d 65 6e 74 20 6f 66 20 61 0a 2a 2a 20 72 65  ement of a.** re
3ba0: 73 75 6c 74 20 72 6f 77 20 69 73 20 4e 55 4c 4c  sult row is NULL
3bb0: 20 74 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73   then the corres
3bc0: 70 6f 6e 64 69 6e 67 20 73 74 72 69 6e 67 20 70  ponding string p
3bd0: 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 65 0a 2a  ointer for the.*
3be0: 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  * sqlite3_exec()
3bf0: 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 4e   callback is a N
3c00: 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54  ULL pointer.  ^T
3c10: 68 65 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20  he 4th argument 
3c20: 74 6f 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65  to the.** sqlite
3c30: 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63  3_exec() callbac
3c40: 6b 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66  k is an array of
3c50: 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72   pointers to str
3c60: 69 6e 67 73 20 77 68 65 72 65 20 65 61 63 68 0a  ings where each.
3c70: 2a 2a 20 65 6e 74 72 79 20 72 65 70 72 65 73 65  ** entry represe
3c80: 6e 74 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  nts the name of 
3c90: 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 72 65  corresponding re
3ca0: 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 61 73 20 6f  sult column as o
3cb0: 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  btained.** from 
3cc0: 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
3cd0: 6e 61 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  name()]..**.** ^
3ce0: 49 66 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  If the 2nd param
3cf0: 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
3d00: 65 78 65 63 28 29 20 69 73 20 61 20 4e 55 4c 4c  exec() is a NULL
3d10: 20 70 6f 69 6e 74 65 72 2c 20 61 20 70 6f 69 6e   pointer, a poin
3d20: 74 65 72 0a 2a 2a 20 74 6f 20 61 6e 20 65 6d 70  ter.** to an emp
3d30: 74 79 20 73 74 72 69 6e 67 2c 20 6f 72 20 61 20  ty string, or a 
3d40: 70 6f 69 6e 74 65 72 20 74 68 61 74 20 63 6f 6e  pointer that con
3d50: 74 61 69 6e 73 20 6f 6e 6c 79 20 77 68 69 74 65  tains only white
3d60: 73 70 61 63 65 20 61 6e 64 2f 6f 72 20 0a 2a 2a  space and/or .**
3d70: 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 73 2c 20 74   SQL comments, t
3d80: 68 65 6e 20 6e 6f 20 53 51 4c 20 73 74 61 74 65  hen no SQL state
3d90: 6d 65 6e 74 73 20 61 72 65 20 65 76 61 6c 75 61  ments are evalua
3da0: 74 65 64 20 61 6e 64 20 74 68 65 20 64 61 74 61  ted and the data
3db0: 62 61 73 65 0a 2a 2a 20 69 73 20 6e 6f 74 20 63  base.** is not c
3dc0: 68 61 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65  hanged..**.** Re
3dd0: 73 74 72 69 63 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a  strictions:.**.*
3de0: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54  * <ul>.** <li> T
3df0: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
3e00: 75 73 74 20 69 6e 73 75 72 65 20 74 68 61 74 20  ust insure that 
3e10: 74 68 65 20 31 73 74 20 70 61 72 61 6d 65 74 65  the 1st paramete
3e20: 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65  r to sqlite3_exe
3e30: 63 28 29 0a 2a 2a 20 20 20 20 20 20 69 73 20 61  c().**      is a
3e40: 20 76 61 6c 69 64 20 61 6e 64 20 6f 70 65 6e 20   valid and open 
3e50: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
3e60: 74 69 6f 6e 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 54  tion]..** <li> T
3e70: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
3e80: 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20 5b 64  ust not close [d
3e90: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
3ea0: 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20 62 79  on] specified by
3eb0: 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 31 73 74  .**      the 1st
3ec0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
3ed0: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 77 68 69  lite3_exec() whi
3ee0: 6c 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  le sqlite3_exec(
3ef0: 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a  ) is running..**
3f00: 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 63   <li> The applic
3f10: 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 6d  ation must not m
3f20: 6f 64 69 66 79 20 74 68 65 20 53 51 4c 20 73 74  odify the SQL st
3f30: 61 74 65 6d 65 6e 74 20 74 65 78 74 20 70 61 73  atement text pas
3f40: 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 20 20 20 20  sed into.**     
3f50: 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
3f60: 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 65 78  er of sqlite3_ex
3f70: 65 63 28 29 20 77 68 69 6c 65 20 73 71 6c 69 74  ec() while sqlit
3f80: 65 33 5f 65 78 65 63 28 29 20 69 73 20 72 75 6e  e3_exec() is run
3f90: 6e 69 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  ning..** </ul>.*
3fa0: 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78  /.int sqlite3_ex
3fb0: 65 63 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20  ec(.  sqlite3*, 
3fc0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3fd0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3fe0: 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61   /* An open data
3ff0: 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  base */.  const 
4000: 63 68 61 72 20 2a 73 71 6c 2c 20 20 20 20 20 20  char *sql,      
4010: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4020: 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62       /* SQL to b
4030: 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20  e evaluated */. 
4040: 20 69 6e 74 20 28 2a 63 61 6c 6c 62 61 63 6b 29   int (*callback)
4050: 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a  (void*,int,char*
4060: 2a 2c 63 68 61 72 2a 2a 29 2c 20 20 2f 2a 20 43  *,char**),  /* C
4070: 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
4080: 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c 20 20 20   */.  void *,   
4090: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
40a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
40b0: 20 2f 2a 20 31 73 74 20 61 72 67 75 6d 65 6e 74   /* 1st argument
40c0: 20 74 6f 20 63 61 6c 6c 62 61 63 6b 20 2a 2f 0a   to callback */.
40d0: 20 20 63 68 61 72 20 2a 2a 65 72 72 6d 73 67 20    char **errmsg 
40e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
40f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
4100: 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65  Error msg writte
4110: 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a  n here */.);../*
4120: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
4130: 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45  sult Codes.** KE
4140: 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 4f  YWORDS: SQLITE_O
4150: 4b 20 7b 65 72 72 6f 72 20 63 6f 64 65 7d 20 7b  K {error code} {
4160: 65 72 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20  error codes}.** 
4170: 4b 45 59 57 4f 52 44 53 3a 20 7b 72 65 73 75 6c  KEYWORDS: {resul
4180: 74 20 63 6f 64 65 7d 20 7b 72 65 73 75 6c 74 20  t code} {result 
4190: 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e  codes}.**.** Man
41a0: 79 20 53 51 4c 69 74 65 20 66 75 6e 63 74 69 6f  y SQLite functio
41b0: 6e 73 20 72 65 74 75 72 6e 20 61 6e 20 69 6e 74  ns return an int
41c0: 65 67 65 72 20 72 65 73 75 6c 74 20 63 6f 64 65  eger result code
41d0: 20 66 72 6f 6d 20 74 68 65 20 73 65 74 20 73 68   from the set sh
41e0: 6f 77 6e 0a 2a 2a 20 68 65 72 65 20 69 6e 20 6f  own.** here in o
41f0: 72 64 65 72 20 74 6f 20 69 6e 64 69 63 61 74 65  rder to indicate
4200: 20 73 75 63 63 65 73 73 20 6f 72 20 66 61 69 6c   success or fail
4210: 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65  ure..**.** New e
4220: 72 72 6f 72 20 63 6f 64 65 73 20 6d 61 79 20 62  rror codes may b
4230: 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72  e added in futur
4240: 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  e versions of SQ
4250: 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  Lite..**.** See 
4260: 61 6c 73 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f  also: [SQLITE_IO
4270: 45 52 52 5f 52 45 41 44 20 7c 20 65 78 74 65 6e  ERR_READ | exten
4280: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
4290: 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76  ],.** [sqlite3_v
42a0: 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28  tab_on_conflict(
42b0: 29 5d 20 5b 53 51 4c 49 54 45 5f 52 4f 4c 4c 42  )] [SQLITE_ROLLB
42c0: 41 43 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f 64  ACK | result cod
42d0: 65 73 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  es]..*/.#define 
42e0: 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20 20 20 20  SQLITE_OK       
42f0: 20 20 20 20 30 20 20 20 2f 2a 20 53 75 63 63 65      0   /* Succe
4300: 73 73 66 75 6c 20 72 65 73 75 6c 74 20 2a 2f 0a  ssful result */.
4310: 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 2d 6f 66 2d  /* beginning-of-
4320: 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 23  error-codes */.#
4330: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 52  define SQLITE_ER
4340: 52 4f 52 20 20 20 20 20 20 20 20 31 20 20 20 2f  ROR        1   /
4350: 2a 20 53 51 4c 20 65 72 72 6f 72 20 6f 72 20 6d  * SQL error or m
4360: 69 73 73 69 6e 67 20 64 61 74 61 62 61 73 65 20  issing database 
4370: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4380: 45 5f 49 4e 54 45 52 4e 41 4c 20 20 20 20 20 32  E_INTERNAL     2
4390: 20 20 20 2f 2a 20 49 6e 74 65 72 6e 61 6c 20 6c     /* Internal l
43a0: 6f 67 69 63 20 65 72 72 6f 72 20 69 6e 20 53 51  ogic error in SQ
43b0: 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  Lite */.#define 
43c0: 53 51 4c 49 54 45 5f 50 45 52 4d 20 20 20 20 20  SQLITE_PERM     
43d0: 20 20 20 20 33 20 20 20 2f 2a 20 41 63 63 65 73      3   /* Acces
43e0: 73 20 70 65 72 6d 69 73 73 69 6f 6e 20 64 65 6e  s permission den
43f0: 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ied */.#define S
4400: 51 4c 49 54 45 5f 41 42 4f 52 54 20 20 20 20 20  QLITE_ABORT     
4410: 20 20 20 34 20 20 20 2f 2a 20 43 61 6c 6c 62 61     4   /* Callba
4420: 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 71 75 65  ck routine reque
4430: 73 74 65 64 20 61 6e 20 61 62 6f 72 74 20 2a 2f  sted an abort */
4440: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4450: 42 55 53 59 20 20 20 20 20 20 20 20 20 35 20 20  BUSY         5  
4460: 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 65   /* The database
4470: 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b 65 64 20   file is locked 
4480: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4490: 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 36  E_LOCKED       6
44a0: 20 20 20 2f 2a 20 41 20 74 61 62 6c 65 20 69 6e     /* A table in
44b0: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73   the database is
44c0: 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69   locked */.#defi
44d0: 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20  ne SQLITE_NOMEM 
44e0: 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 41 20         7   /* A 
44f0: 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 65 64 20  malloc() failed 
4500: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4510: 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 38  E_READONLY     8
4520: 20 20 20 2f 2a 20 41 74 74 65 6d 70 74 20 74 6f     /* Attempt to
4530: 20 77 72 69 74 65 20 61 20 72 65 61 64 6f 6e 6c   write a readonl
4540: 79 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64  y database */.#d
4550: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54  efine SQLITE_INT
4560: 45 52 52 55 50 54 20 20 20 20 39 20 20 20 2f 2a  ERRUPT    9   /*
4570: 20 4f 70 65 72 61 74 69 6f 6e 20 74 65 72 6d 69   Operation termi
4580: 6e 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33  nated by sqlite3
4590: 5f 69 6e 74 65 72 72 75 70 74 28 29 2a 2f 0a 23  _interrupt()*/.#
45a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
45b0: 45 52 52 20 20 20 20 20 20 20 31 30 20 20 20 2f  ERR       10   /
45c0: 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f 66 20 64  * Some kind of d
45d0: 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72 20 6f 63  isk I/O error oc
45e0: 63 75 72 72 65 64 20 2a 2f 0a 23 64 65 66 69 6e  curred */.#defin
45f0: 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54  e SQLITE_CORRUPT
4600: 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 68 65       11   /* The
4610: 20 64 61 74 61 62 61 73 65 20 64 69 73 6b 20 69   database disk i
4620: 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f 72 6d 65  mage is malforme
4630: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
4640: 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 20 20 20  ITE_NOTFOUND    
4650: 31 32 20 20 20 2f 2a 20 55 6e 6b 6e 6f 77 6e 20  12   /* Unknown 
4660: 6f 70 63 6f 64 65 20 69 6e 20 73 71 6c 69 74 65  opcode in sqlite
4670: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
4680: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4690: 54 45 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 31  TE_FULL        1
46a0: 33 20 20 20 2f 2a 20 49 6e 73 65 72 74 69 6f 6e  3   /* Insertion
46b0: 20 66 61 69 6c 65 64 20 62 65 63 61 75 73 65 20   failed because 
46c0: 64 61 74 61 62 61 73 65 20 69 73 20 66 75 6c 6c  database is full
46d0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
46e0: 54 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20 20 31  TE_CANTOPEN    1
46f0: 34 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20 74 6f  4   /* Unable to
4700: 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61   open the databa
4710: 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69  se file */.#defi
4720: 6e 65 20 53 51 4c 49 54 45 5f 50 52 4f 54 4f 43  ne SQLITE_PROTOC
4730: 4f 4c 20 20 20 20 31 35 20 20 20 2f 2a 20 44 61  OL    15   /* Da
4740: 74 61 62 61 73 65 20 6c 6f 63 6b 20 70 72 6f 74  tabase lock prot
4750: 6f 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a 23 64  ocol error */.#d
4760: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 4d 50  efine SQLITE_EMP
4770: 54 59 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a  TY       16   /*
4780: 20 44 61 74 61 62 61 73 65 20 69 73 20 65 6d 70   Database is emp
4790: 74 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ty */.#define SQ
47a0: 4c 49 54 45 5f 53 43 48 45 4d 41 20 20 20 20 20  LITE_SCHEMA     
47b0: 20 31 37 20 20 20 2f 2a 20 54 68 65 20 64 61 74   17   /* The dat
47c0: 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 61  abase schema cha
47d0: 6e 67 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nged */.#define 
47e0: 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 20 20 20  SQLITE_TOOBIG   
47f0: 20 20 20 31 38 20 20 20 2f 2a 20 53 74 72 69 6e     18   /* Strin
4800: 67 20 6f 72 20 42 4c 4f 42 20 65 78 63 65 65 64  g or BLOB exceed
4810: 73 20 73 69 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a  s size limit */.
4820: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
4830: 4f 4e 53 54 52 41 49 4e 54 20 20 31 39 20 20 20  ONSTRAINT  19   
4840: 2f 2a 20 41 62 6f 72 74 20 64 75 65 20 74 6f 20  /* Abort due to 
4850: 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61  constraint viola
4860: 74 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20  tion */.#define 
4870: 53 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43 48 20  SQLITE_MISMATCH 
4880: 20 20 20 32 30 20 20 20 2f 2a 20 44 61 74 61 20     20   /* Data 
4890: 74 79 70 65 20 6d 69 73 6d 61 74 63 68 20 2a 2f  type mismatch */
48a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
48b0: 4d 49 53 55 53 45 20 20 20 20 20 20 32 31 20 20  MISUSE      21  
48c0: 20 2f 2a 20 4c 69 62 72 61 72 79 20 75 73 65 64   /* Library used
48d0: 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 2a 2f 0a   incorrectly */.
48e0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e  #define SQLITE_N
48f0: 4f 4c 46 53 20 20 20 20 20 20 20 32 32 20 20 20  OLFS       22   
4900: 2f 2a 20 55 73 65 73 20 4f 53 20 66 65 61 74 75  /* Uses OS featu
4910: 72 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 65  res not supporte
4920: 64 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23 64 65  d on host */.#de
4930: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54 48  fine SQLITE_AUTH
4940: 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20          23   /* 
4950: 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 64 65  Authorization de
4960: 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nied */.#define 
4970: 53 51 4c 49 54 45 5f 46 4f 52 4d 41 54 20 20 20  SQLITE_FORMAT   
4980: 20 20 20 32 34 20 20 20 2f 2a 20 41 75 78 69 6c     24   /* Auxil
4990: 69 61 72 79 20 64 61 74 61 62 61 73 65 20 66 6f  iary database fo
49a0: 72 6d 61 74 20 65 72 72 6f 72 20 2a 2f 0a 23 64  rmat error */.#d
49b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 41 4e  efine SQLITE_RAN
49c0: 47 45 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a  GE       25   /*
49d0: 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74   2nd parameter t
49e0: 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 20 6f  o sqlite3_bind o
49f0: 75 74 20 6f 66 20 72 61 6e 67 65 20 2a 2f 0a 23  ut of range */.#
4a00: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
4a10: 54 41 44 42 20 20 20 20 20 20 32 36 20 20 20 2f  TADB      26   /
4a20: 2a 20 46 69 6c 65 20 6f 70 65 6e 65 64 20 74 68  * File opened th
4a30: 61 74 20 69 73 20 6e 6f 74 20 61 20 64 61 74 61  at is not a data
4a40: 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65  base file */.#de
4a50: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49  fine SQLITE_NOTI
4a60: 43 45 20 20 20 20 20 20 32 37 20 20 20 2f 2a 20  CE      27   /* 
4a70: 4e 6f 74 69 66 69 63 61 74 69 6f 6e 73 20 66 72  Notifications fr
4a80: 6f 6d 20 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29  om sqlite3_log()
4a90: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4aa0: 54 45 5f 57 41 52 4e 49 4e 47 20 20 20 20 20 32  TE_WARNING     2
4ab0: 38 20 20 20 2f 2a 20 57 61 72 6e 69 6e 67 73 20  8   /* Warnings 
4ac0: 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6c 6f 67  from sqlite3_log
4ad0: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
4ae0: 4c 49 54 45 5f 52 4f 57 20 20 20 20 20 20 20 20  LITE_ROW        
4af0: 20 31 30 30 20 20 2f 2a 20 73 71 6c 69 74 65 33   100  /* sqlite3
4b00: 5f 73 74 65 70 28 29 20 68 61 73 20 61 6e 6f 74  _step() has anot
4b10: 68 65 72 20 72 6f 77 20 72 65 61 64 79 20 2a 2f  her row ready */
4b20: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4b30: 44 4f 4e 45 20 20 20 20 20 20 20 20 31 30 31 20  DONE        101 
4b40: 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70   /* sqlite3_step
4b50: 28 29 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  () has finished 
4b60: 65 78 65 63 75 74 69 6e 67 20 2a 2f 0a 2f 2a 20  executing */./* 
4b70: 65 6e 64 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64  end-of-error-cod
4b80: 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  es */../*.** CAP
4b90: 49 33 52 45 46 3a 20 45 78 74 65 6e 64 65 64 20  I3REF: Extended 
4ba0: 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20  Result Codes.** 
4bb0: 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e  KEYWORDS: {exten
4bc0: 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 7d 20  ded error code} 
4bd0: 7b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20  {extended error 
4be0: 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52  codes}.** KEYWOR
4bf0: 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 72 65  DS: {extended re
4c00: 73 75 6c 74 20 63 6f 64 65 7d 20 7b 65 78 74 65  sult code} {exte
4c10: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
4c20: 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 69 74 73 20  s}.**.** In its 
4c30: 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72  default configur
4c40: 61 74 69 6f 6e 2c 20 53 51 4c 69 74 65 20 41 50  ation, SQLite AP
4c50: 49 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  I routines retur
4c60: 6e 20 6f 6e 65 20 6f 66 20 32 36 20 69 6e 74 65  n one of 26 inte
4c70: 67 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  ger.** [SQLITE_O
4c80: 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65 73  K | result codes
4c90: 5d 2e 20 20 48 6f 77 65 76 65 72 2c 20 65 78 70  ].  However, exp
4ca0: 65 72 69 65 6e 63 65 20 68 61 73 20 73 68 6f 77  erience has show
4cb0: 6e 20 74 68 61 74 20 6d 61 6e 79 20 6f 66 0a 2a  n that many of.*
4cc0: 2a 20 74 68 65 73 65 20 72 65 73 75 6c 74 20 63  * these result c
4cd0: 6f 64 65 73 20 61 72 65 20 74 6f 6f 20 63 6f 61  odes are too coa
4ce0: 72 73 65 2d 67 72 61 69 6e 65 64 2e 20 20 54 68  rse-grained.  Th
4cf0: 65 79 20 64 6f 20 6e 6f 74 20 70 72 6f 76 69 64  ey do not provid
4d00: 65 20 61 73 0a 2a 2a 20 6d 75 63 68 20 69 6e 66  e as.** much inf
4d10: 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 70  ormation about p
4d20: 72 6f 62 6c 65 6d 73 20 61 73 20 70 72 6f 67 72  roblems as progr
4d30: 61 6d 6d 65 72 73 20 6d 69 67 68 74 20 6c 69 6b  ammers might lik
4d40: 65 2e 20 20 49 6e 20 61 6e 20 65 66 66 6f 72 74  e.  In an effort
4d50: 20 74 6f 0a 2a 2a 20 61 64 64 72 65 73 73 20 74   to.** address t
4d60: 68 69 73 2c 20 6e 65 77 65 72 20 76 65 72 73 69  his, newer versi
4d70: 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 28 76  ons of SQLite (v
4d80: 65 72 73 69 6f 6e 20 33 2e 33 2e 38 20 61 6e 64  ersion 3.3.8 and
4d90: 20 6c 61 74 65 72 29 20 69 6e 63 6c 75 64 65 0a   later) include.
4da0: 2a 2a 20 73 75 70 70 6f 72 74 20 66 6f 72 20 61  ** support for a
4db0: 64 64 69 74 69 6f 6e 61 6c 20 72 65 73 75 6c 74  dditional result
4dc0: 20 63 6f 64 65 73 20 74 68 61 74 20 70 72 6f 76   codes that prov
4dd0: 69 64 65 20 6d 6f 72 65 20 64 65 74 61 69 6c 65  ide more detaile
4de0: 64 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a  d information.**
4df0: 20 61 62 6f 75 74 20 65 72 72 6f 72 73 2e 20 54   about errors. T
4e00: 68 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 75  he extended resu
4e10: 6c 74 20 63 6f 64 65 73 20 61 72 65 20 65 6e 61  lt codes are ena
4e20: 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64  bled or disabled
4e30: 0a 2a 2a 20 6f 6e 20 61 20 70 65 72 20 64 61 74  .** on a per dat
4e40: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
4e50: 20 62 61 73 69 73 20 75 73 69 6e 67 20 74 68 65   basis using the
4e60: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 74  .** [sqlite3_ext
4e70: 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64  ended_result_cod
4e80: 65 73 28 29 5d 20 41 50 49 2e 0a 2a 2a 0a 2a 2a  es()] API..**.**
4e90: 20 53 6f 6d 65 20 6f 66 20 74 68 65 20 61 76 61   Some of the ava
4ea0: 69 6c 61 62 6c 65 20 65 78 74 65 6e 64 65 64 20  ilable extended 
4eb0: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65  result codes are
4ec0: 20 6c 69 73 74 65 64 20 68 65 72 65 2e 0a 2a 2a   listed here..**
4ed0: 20 4f 6e 65 20 6d 61 79 20 65 78 70 65 63 74 20   One may expect 
4ee0: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 78  the number of ex
4ef0: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
4f00: 64 65 73 20 77 69 6c 6c 20 62 65 20 65 78 70 61  des will be expa
4f10: 6e 64 0a 2a 2a 20 6f 76 65 72 20 74 69 6d 65 2e  nd.** over time.
4f20: 20 20 53 6f 66 74 77 61 72 65 20 74 68 61 74 20    Software that 
4f30: 75 73 65 73 20 65 78 74 65 6e 64 65 64 20 72 65  uses extended re
4f40: 73 75 6c 74 20 63 6f 64 65 73 20 73 68 6f 75 6c  sult codes shoul
4f50: 64 20 65 78 70 65 63 74 0a 2a 2a 20 74 6f 20 73  d expect.** to s
4f60: 65 65 20 6e 65 77 20 72 65 73 75 6c 74 20 63 6f  ee new result co
4f70: 64 65 73 20 69 6e 20 66 75 74 75 72 65 20 72 65  des in future re
4f80: 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65  leases of SQLite
4f90: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49  ..**.** The SQLI
4fa0: 54 45 5f 4f 4b 20 72 65 73 75 6c 74 20 63 6f 64  TE_OK result cod
4fb0: 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 62 65 20  e will never be 
4fc0: 65 78 74 65 6e 64 65 64 2e 20 20 49 74 20 77 69  extended.  It wi
4fd0: 6c 6c 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65 20  ll always.** be 
4fe0: 65 78 61 63 74 6c 79 20 7a 65 72 6f 2e 0a 2a 2f  exactly zero..*/
4ff0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5000: 49 4f 45 52 52 5f 52 45 41 44 20 20 20 20 20 20  IOERR_READ      
5010: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5020: 49 4f 45 52 52 20 7c 20 28 31 3c 3c 38 29 29 0a  IOERR | (1<<8)).
5030: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5040: 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 20  OERR_SHORT_READ 
5050: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
5060: 4f 45 52 52 20 7c 20 28 32 3c 3c 38 29 29 0a 23  OERR | (2<<8)).#
5070: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5080: 45 52 52 5f 57 52 49 54 45 20 20 20 20 20 20 20  ERR_WRITE       
5090: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
50a0: 45 52 52 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64  ERR | (3<<8)).#d
50b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
50c0: 52 52 5f 46 53 59 4e 43 20 20 20 20 20 20 20 20  RR_FSYNC        
50d0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
50e0: 52 52 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65  RR | (4<<8)).#de
50f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
5100: 52 5f 44 49 52 5f 46 53 59 4e 43 20 20 20 20 20  R_DIR_FSYNC     
5110: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
5120: 52 20 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65 66  R | (5<<8)).#def
5130: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5140: 5f 54 52 55 4e 43 41 54 45 20 20 20 20 20 20 20  _TRUNCATE       
5150: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5160: 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64 65 66 69   | (6<<8)).#defi
5170: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5180: 46 53 54 41 54 20 20 20 20 20 20 20 20 20 20 20  FSTAT           
5190: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
51a0: 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (7<<8)).#defin
51b0: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 55  e SQLITE_IOERR_U
51c0: 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20  NLOCK           
51d0: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
51e0: 20 28 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (8<<8)).#define
51f0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 44   SQLITE_IOERR_RD
5200: 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 20  LOCK            
5210: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
5220: 28 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (9<<8)).#define 
5230: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 45 4c  SQLITE_IOERR_DEL
5240: 45 54 45 20 20 20 20 20 20 20 20 20 20 20 20 28  ETE            (
5250: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5260: 31 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  10<<8)).#define 
5270: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f  SQLITE_IOERR_BLO
5280: 43 4b 45 44 20 20 20 20 20 20 20 20 20 20 20 28  CKED           (
5290: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
52a0: 31 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  11<<8)).#define 
52b0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4e 4f 4d  SQLITE_IOERR_NOM
52c0: 45 4d 20 20 20 20 20 20 20 20 20 20 20 20 20 28  EM             (
52d0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
52e0: 31 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  12<<8)).#define 
52f0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 41 43 43  SQLITE_IOERR_ACC
5300: 45 53 53 20 20 20 20 20 20 20 20 20 20 20 20 28  ESS            (
5310: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5320: 31 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  13<<8)).#define 
5330: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 48 45  SQLITE_IOERR_CHE
5340: 43 4b 52 45 53 45 52 56 45 44 4c 4f 43 4b 20 28  CKRESERVEDLOCK (
5350: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5360: 31 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  14<<8)).#define 
5370: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4c 4f 43  SQLITE_IOERR_LOC
5380: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28  K              (
5390: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
53a0: 31 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  15<<8)).#define 
53b0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 4c 4f  SQLITE_IOERR_CLO
53c0: 53 45 20 20 20 20 20 20 20 20 20 20 20 20 20 28  SE             (
53d0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
53e0: 31 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  16<<8)).#define 
53f0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49 52  SQLITE_IOERR_DIR
5400: 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20 28  _CLOSE         (
5410: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5420: 31 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  17<<8)).#define 
5430: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d  SQLITE_IOERR_SHM
5440: 4f 50 45 4e 20 20 20 20 20 20 20 20 20 20 20 28  OPEN           (
5450: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5460: 31 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  18<<8)).#define 
5470: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d  SQLITE_IOERR_SHM
5480: 53 49 5a 45 20 20 20 20 20 20 20 20 20 20 20 28  SIZE           (
5490: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
54a0: 31 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  19<<8)).#define 
54b0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d  SQLITE_IOERR_SHM
54c0: 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 28  LOCK           (
54d0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
54e0: 32 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  20<<8)).#define 
54f0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d  SQLITE_IOERR_SHM
5500: 4d 41 50 20 20 20 20 20 20 20 20 20 20 20 20 28  MAP            (
5510: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5520: 32 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  21<<8)).#define 
5530: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 45 45  SQLITE_IOERR_SEE
5540: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28  K              (
5550: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5560: 32 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  22<<8)).#define 
5570: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 45 4c  SQLITE_IOERR_DEL
5580: 45 54 45 5f 4e 4f 45 4e 54 20 20 20 20 20 20 28  ETE_NOENT      (
5590: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
55a0: 32 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  23<<8)).#define 
55b0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4d 4d 41  SQLITE_IOERR_MMA
55c0: 50 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28  P              (
55d0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
55e0: 32 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  24<<8)).#define 
55f0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 5f 53 48  SQLITE_LOCKED_SH
5600: 41 52 45 44 43 41 43 48 45 20 20 20 20 20 20 28  AREDCACHE      (
5610: 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 7c 20  SQLITE_LOCKED | 
5620: 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (1<<8)).#define
5630: 20 53 51 4c 49 54 45 5f 42 55 53 59 5f 52 45 43   SQLITE_BUSY_REC
5640: 4f 56 45 52 59 20 20 20 20 20 20 20 20 20 20 20  OVERY           
5650: 28 53 51 4c 49 54 45 5f 42 55 53 59 20 20 20 7c  (SQLITE_BUSY   |
5660: 20 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e    (1<<8)).#defin
5670: 65 20 53 51 4c 49 54 45 5f 42 55 53 59 5f 53 4e  e SQLITE_BUSY_SN
5680: 41 50 53 48 4f 54 20 20 20 20 20 20 20 20 20 20  APSHOT          
5690: 20 28 53 51 4c 49 54 45 5f 42 55 53 59 20 20 20   (SQLITE_BUSY   
56a0: 7c 20 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69  |  (2<<8)).#defi
56b0: 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50  ne SQLITE_CANTOP
56c0: 45 4e 5f 4e 4f 54 45 4d 50 44 49 52 20 20 20 20  EN_NOTEMPDIR    
56d0: 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50    (SQLITE_CANTOP
56e0: 45 4e 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65  EN | (1<<8)).#de
56f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54  fine SQLITE_CANT
5700: 4f 50 45 4e 5f 49 53 44 49 52 20 20 20 20 20 20  OPEN_ISDIR      
5710: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54      (SQLITE_CANT
5720: 4f 50 45 4e 20 7c 20 28 32 3c 3c 38 29 29 0a 23  OPEN | (2<<8)).#
5730: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41  define SQLITE_CA
5740: 4e 54 4f 50 45 4e 5f 46 55 4c 4c 50 41 54 48 20  NTOPEN_FULLPATH 
5750: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41        (SQLITE_CA
5760: 4e 54 4f 50 45 4e 20 7c 20 28 33 3c 3c 38 29 29  NTOPEN | (3<<8))
5770: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5780: 43 4f 52 52 55 50 54 5f 56 54 41 42 20 20 20 20  CORRUPT_VTAB    
5790: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
57a0: 43 4f 52 52 55 50 54 20 7c 20 28 31 3c 3c 38 29  CORRUPT | (1<<8)
57b0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
57c0: 5f 52 45 41 44 4f 4e 4c 59 5f 52 45 43 4f 56 45  _READONLY_RECOVE
57d0: 52 59 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  RY       (SQLITE
57e0: 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 31 3c 3c  _READONLY | (1<<
57f0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5800: 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 43 41 4e 54  TE_READONLY_CANT
5810: 4c 4f 43 4b 20 20 20 20 20 20 20 28 53 51 4c 49  LOCK       (SQLI
5820: 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 32  TE_READONLY | (2
5830: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5840: 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 52 4f  LITE_READONLY_RO
5850: 4c 4c 42 41 43 4b 20 20 20 20 20 20 20 28 53 51  LLBACK       (SQ
5860: 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20  LITE_READONLY | 
5870: 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (3<<8)).#define 
5880: 53 51 4c 49 54 45 5f 41 42 4f 52 54 5f 52 4f 4c  SQLITE_ABORT_ROL
5890: 4c 42 41 43 4b 20 20 20 20 20 20 20 20 20 20 28  LBACK          (
58a0: 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 7c 20 28  SQLITE_ABORT | (
58b0: 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  2<<8)).#define S
58c0: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
58d0: 5f 43 48 45 43 4b 20 20 20 20 20 20 20 20 28 53  _CHECK        (S
58e0: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
58f0: 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69   | (1<<8)).#defi
5900: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52  ne SQLITE_CONSTR
5910: 41 49 4e 54 5f 43 4f 4d 4d 49 54 48 4f 4f 4b 20  AINT_COMMITHOOK 
5920: 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52    (SQLITE_CONSTR
5930: 41 49 4e 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23  AINT | (2<<8)).#
5940: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
5950: 4e 53 54 52 41 49 4e 54 5f 46 4f 52 45 49 47 4e  NSTRAINT_FOREIGN
5960: 4b 45 59 20 20 20 28 53 51 4c 49 54 45 5f 43 4f  KEY   (SQLITE_CO
5970: 4e 53 54 52 41 49 4e 54 20 7c 20 28 33 3c 3c 38  NSTRAINT | (3<<8
5980: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5990: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 46 55 4e  E_CONSTRAINT_FUN
59a0: 43 54 49 4f 4e 20 20 20 20 20 28 53 51 4c 49 54  CTION     (SQLIT
59b0: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28  E_CONSTRAINT | (
59c0: 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  4<<8)).#define S
59d0: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
59e0: 5f 4e 4f 54 4e 55 4c 4c 20 20 20 20 20 20 28 53  _NOTNULL      (S
59f0: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
5a00: 20 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65 66 69   | (5<<8)).#defi
5a10: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52  ne SQLITE_CONSTR
5a20: 41 49 4e 54 5f 50 52 49 4d 41 52 59 4b 45 59 20  AINT_PRIMARYKEY 
5a30: 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52    (SQLITE_CONSTR
5a40: 41 49 4e 54 20 7c 20 28 36 3c 3c 38 29 29 0a 23  AINT | (6<<8)).#
5a50: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
5a60: 4e 53 54 52 41 49 4e 54 5f 54 52 49 47 47 45 52  NSTRAINT_TRIGGER
5a70: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f        (SQLITE_CO
5a80: 4e 53 54 52 41 49 4e 54 20 7c 20 28 37 3c 3c 38  NSTRAINT | (7<<8
5a90: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5aa0: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 55 4e 49  E_CONSTRAINT_UNI
5ab0: 51 55 45 20 20 20 20 20 20 20 28 53 51 4c 49 54  QUE       (SQLIT
5ac0: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28  E_CONSTRAINT | (
5ad0: 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  8<<8)).#define S
5ae0: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
5af0: 5f 56 54 41 42 20 20 20 20 20 20 20 20 20 28 53  _VTAB         (S
5b00: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
5b10: 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66 69   | (9<<8)).#defi
5b20: 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45  ne SQLITE_NOTICE
5b30: 5f 52 45 43 4f 56 45 52 5f 57 41 4c 20 20 20 20  _RECOVER_WAL    
5b40: 20 20 28 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45    (SQLITE_NOTICE
5b50: 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69   | (1<<8)).#defi
5b60: 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45  ne SQLITE_NOTICE
5b70: 5f 52 45 43 4f 56 45 52 5f 52 4f 4c 4c 42 41 43  _RECOVER_ROLLBAC
5b80: 4b 20 28 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45  K (SQLITE_NOTICE
5b90: 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69   | (2<<8)).#defi
5ba0: 6e 65 20 53 51 4c 49 54 45 5f 57 41 52 4e 49 4e  ne SQLITE_WARNIN
5bb0: 47 5f 41 55 54 4f 49 4e 44 45 58 20 20 20 20 20  G_AUTOINDEX     
5bc0: 20 20 28 53 51 4c 49 54 45 5f 57 41 52 4e 49 4e    (SQLITE_WARNIN
5bd0: 47 20 7c 20 28 31 3c 3c 38 29 29 0a 0a 2f 2a 0a  G | (1<<8))../*.
5be0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61  ** CAPI3REF: Fla
5bf0: 67 73 20 46 6f 72 20 46 69 6c 65 20 4f 70 65 6e  gs For File Open
5c00: 20 4f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 0a 2a   Operations.**.*
5c10: 2a 20 54 68 65 73 65 20 62 69 74 20 76 61 6c 75  * These bit valu
5c20: 65 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20  es are intended 
5c30: 66 6f 72 20 75 73 65 20 69 6e 20 74 68 65 0a 2a  for use in the.*
5c40: 2a 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  * 3rd parameter 
5c50: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
5c60: 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72  open_v2()] inter
5c70: 66 61 63 65 20 61 6e 64 0a 2a 2a 20 69 6e 20 74  face and.** in t
5c80: 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72  he 4th parameter
5c90: 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
5ca0: 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68  _vfs.xOpen] meth
5cb0: 6f 64 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  od..*/.#define S
5cc0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f  QLITE_OPEN_READO
5cd0: 4e 4c 59 20 20 20 20 20 20 20 20 20 30 78 30 30  NLY         0x00
5ce0: 30 30 30 30 30 31 20 20 2f 2a 20 4f 6b 20 66 6f  000001  /* Ok fo
5cf0: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
5d00: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
5d10: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
5d20: 52 49 54 45 20 20 20 20 20 20 20 20 30 78 30 30  RITE        0x00
5d30: 30 30 30 30 30 32 20 20 2f 2a 20 4f 6b 20 66 6f  000002  /* Ok fo
5d40: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
5d50: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
5d60: 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
5d70: 45 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30  E           0x00
5d80: 30 30 30 30 30 34 20 20 2f 2a 20 4f 6b 20 66 6f  000004  /* Ok fo
5d90: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
5da0: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
5db0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54  QLITE_OPEN_DELET
5dc0: 45 4f 4e 43 4c 4f 53 45 20 20 20 20 30 78 30 30  EONCLOSE    0x00
5dd0: 30 30 30 30 30 38 20 20 2f 2a 20 56 46 53 20 6f  000008  /* VFS o
5de0: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
5df0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55  QLITE_OPEN_EXCLU
5e00: 53 49 56 45 20 20 20 20 20 20 20 20 30 78 30 30  SIVE        0x00
5e10: 30 30 30 30 31 30 20 20 2f 2a 20 56 46 53 20 6f  000010  /* VFS o
5e20: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
5e30: 51 4c 49 54 45 5f 4f 50 45 4e 5f 41 55 54 4f 50  QLITE_OPEN_AUTOP
5e40: 52 4f 58 59 20 20 20 20 20 20 20 20 30 78 30 30  ROXY        0x00
5e50: 30 30 30 30 32 30 20 20 2f 2a 20 56 46 53 20 6f  000020  /* VFS o
5e60: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
5e70: 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20 20  QLITE_OPEN_URI  
5e80: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
5e90: 30 30 30 30 34 30 20 20 2f 2a 20 4f 6b 20 66 6f  000040  /* Ok fo
5ea0: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
5eb0: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
5ec0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 45 4d 4f 52  QLITE_OPEN_MEMOR
5ed0: 59 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30  Y           0x00
5ee0: 30 30 30 30 38 30 20 20 2f 2a 20 4f 6b 20 66 6f  000080  /* Ok fo
5ef0: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
5f00: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
5f10: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f  QLITE_OPEN_MAIN_
5f20: 44 42 20 20 20 20 20 20 20 20 20 20 30 78 30 30  DB          0x00
5f30: 30 30 30 31 30 30 20 20 2f 2a 20 56 46 53 20 6f  000100  /* VFS o
5f40: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
5f50: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f  QLITE_OPEN_TEMP_
5f60: 44 42 20 20 20 20 20 20 20 20 20 20 30 78 30 30  DB          0x00
5f70: 30 30 30 32 30 30 20 20 2f 2a 20 56 46 53 20 6f  000200  /* VFS o
5f80: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
5f90: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53  QLITE_OPEN_TRANS
5fa0: 49 45 4e 54 5f 44 42 20 20 20 20 20 30 78 30 30  IENT_DB     0x00
5fb0: 30 30 30 34 30 30 20 20 2f 2a 20 56 46 53 20 6f  000400  /* VFS o
5fc0: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
5fd0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f  QLITE_OPEN_MAIN_
5fe0: 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30  JOURNAL     0x00
5ff0: 30 30 30 38 30 30 20 20 2f 2a 20 56 46 53 20 6f  000800  /* VFS o
6000: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
6010: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f  QLITE_OPEN_TEMP_
6020: 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30  JOURNAL     0x00
6030: 30 30 31 30 30 30 20 20 2f 2a 20 56 46 53 20 6f  001000  /* VFS o
6040: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
6050: 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f  QLITE_OPEN_SUBJO
6060: 55 52 4e 41 4c 20 20 20 20 20 20 20 30 78 30 30  URNAL       0x00
6070: 30 30 32 30 30 30 20 20 2f 2a 20 56 46 53 20 6f  002000  /* VFS o
6080: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
6090: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45  QLITE_OPEN_MASTE
60a0: 52 5f 4a 4f 55 52 4e 41 4c 20 20 20 30 78 30 30  R_JOURNAL   0x00
60b0: 30 30 34 30 30 30 20 20 2f 2a 20 56 46 53 20 6f  004000  /* VFS o
60c0: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
60d0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54  QLITE_OPEN_NOMUT
60e0: 45 58 20 20 20 20 20 20 20 20 20 20 30 78 30 30  EX          0x00
60f0: 30 30 38 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f  008000  /* Ok fo
6100: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
6110: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
6120: 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d  QLITE_OPEN_FULLM
6130: 55 54 45 58 20 20 20 20 20 20 20 20 30 78 30 30  UTEX        0x00
6140: 30 31 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f  010000  /* Ok fo
6150: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
6160: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
6170: 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45  QLITE_OPEN_SHARE
6180: 44 43 41 43 48 45 20 20 20 20 20 20 30 78 30 30  DCACHE      0x00
6190: 30 32 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f  020000  /* Ok fo
61a0: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
61b0: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
61c0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41  QLITE_OPEN_PRIVA
61d0: 54 45 43 41 43 48 45 20 20 20 20 20 30 78 30 30  TECACHE     0x00
61e0: 30 34 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f  040000  /* Ok fo
61f0: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
6200: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
6210: 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 20 20  QLITE_OPEN_WAL  
6220: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
6230: 30 38 30 30 30 30 20 20 2f 2a 20 56 46 53 20 6f  080000  /* VFS o
6240: 6e 6c 79 20 2a 2f 0a 0a 2f 2a 20 52 65 73 65 72  nly */../* Reser
6250: 76 65 64 3a 20 20 20 20 20 20 20 20 20 20 20 20  ved:            
6260: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
6270: 30 46 30 30 30 30 30 20 2a 2f 0a 0a 2f 2a 0a 2a  0F00000 */../*.*
6280: 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 76 69  * CAPI3REF: Devi
6290: 63 65 20 43 68 61 72 61 63 74 65 72 69 73 74 69  ce Characteristi
62a0: 63 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 44 65  cs.**.** The xDe
62b0: 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74  viceCharacterist
62c0: 69 63 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68  ics method of th
62d0: 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  e [sqlite3_io_me
62e0: 74 68 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74  thods].** object
62f0: 20 72 65 74 75 72 6e 73 20 61 6e 20 69 6e 74 65   returns an inte
6300: 67 65 72 20 77 68 69 63 68 20 69 73 20 61 20 76  ger which is a v
6310: 65 63 74 6f 72 20 6f 66 20 74 68 65 73 65 0a 2a  ector of these.*
6320: 2a 20 62 69 74 20 76 61 6c 75 65 73 20 65 78 70  * bit values exp
6330: 72 65 73 73 69 6e 67 20 49 2f 4f 20 63 68 61 72  ressing I/O char
6340: 61 63 74 65 72 69 73 74 69 63 73 20 6f 66 20 74  acteristics of t
6350: 68 65 20 6d 61 73 73 20 73 74 6f 72 61 67 65 0a  he mass storage.
6360: 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 68  ** device that h
6370: 6f 6c 64 73 20 74 68 65 20 66 69 6c 65 20 74 68  olds the file th
6380: 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  at the [sqlite3_
6390: 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72  io_methods].** r
63a0: 65 66 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20  efers to..**.** 
63b0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
63c0: 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79  _ATOMIC property
63d0: 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20   means that all 
63e0: 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79  writes of.** any
63f0: 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63   size are atomic
6400: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
6410: 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61  CAP_ATOMICnnn va
6420: 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61  lues.** mean tha
6430: 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63  t writes of bloc
6440: 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20  ks that are nnn 
6450: 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e  bytes in size an
6460: 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64  d.** are aligned
6470: 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77   to an address w
6480: 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67  hich is an integ
6490: 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a  er multiple of.*
64a0: 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63  * nnn are atomic
64b0: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
64c0: 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20  CAP_SAFE_APPEND 
64d0: 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74  value means.** t
64e0: 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69 73  hat when data is
64f0: 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66   appended to a f
6500: 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69 73  ile, the data is
6510: 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72   appended.** fir
6520: 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65  st then the size
6530: 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73 20   of the file is 
6540: 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20  extended, never 
6550: 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79  the other.** way
6560: 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51   around.  The SQ
6570: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45  LITE_IOCAP_SEQUE
6580: 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d  NTIAL property m
6590: 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66  eans that.** inf
65a0: 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74  ormation is writ
65b0: 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74  ten to disk in t
65c0: 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73  he same order as
65d0: 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72   calls.** to xWr
65e0: 69 74 65 28 29 2e 20 20 54 68 65 20 53 51 4c 49  ite().  The SQLI
65f0: 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41  TE_IOCAP_POWERSA
6600: 46 45 5f 4f 56 45 52 57 52 49 54 45 20 70 72 6f  FE_OVERWRITE pro
6610: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74  perty means that
6620: 0a 2a 2a 20 61 66 74 65 72 20 72 65 62 6f 6f 74  .** after reboot
6630: 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 72 61   following a cra
6640: 73 68 20 6f 72 20 70 6f 77 65 72 20 6c 6f 73 73  sh or power loss
6650: 2c 20 74 68 65 20 6f 6e 6c 79 20 62 79 74 65 73  , the only bytes
6660: 20 69 6e 20 61 0a 2a 2a 20 66 69 6c 65 20 74 68   in a.** file th
6670: 61 74 20 77 65 72 65 20 77 72 69 74 74 65 6e 20  at were written 
6680: 61 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  at the applicati
6690: 6f 6e 20 6c 65 76 65 6c 20 6d 69 67 68 74 20 68  on level might h
66a0: 61 76 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20 61  ave changed.** a
66b0: 6e 64 20 74 68 61 74 20 61 64 6a 61 63 65 6e 74  nd that adjacent
66c0: 20 62 79 74 65 73 2c 20 65 76 65 6e 20 62 79 74   bytes, even byt
66d0: 65 73 20 77 69 74 68 69 6e 20 74 68 65 20 73 61  es within the sa
66e0: 6d 65 20 73 65 63 74 6f 72 20 61 72 65 0a 2a 2a  me sector are.**
66f0: 20 67 75 61 72 61 6e 74 65 65 64 20 74 6f 20 62   guaranteed to b
6700: 65 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2f 0a  e unchanged..*/.
6710: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
6720: 4f 43 41 50 5f 41 54 4f 4d 49 43 20 20 20 20 20  OCAP_ATOMIC     
6730: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
6740: 30 30 30 30 30 31 0a 23 64 65 66 69 6e 65 20 53  000001.#define S
6750: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
6760: 49 43 35 31 32 20 20 20 20 20 20 20 20 20 20 20  IC512           
6770: 20 20 20 30 78 30 30 30 30 30 30 30 32 0a 23 64     0x00000002.#d
6780: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
6790: 41 50 5f 41 54 4f 4d 49 43 31 4b 20 20 20 20 20  AP_ATOMIC1K     
67a0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
67b0: 30 30 30 34 0a 23 64 65 66 69 6e 65 20 53 51 4c  0004.#define SQL
67c0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
67d0: 32 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  2K              
67e0: 20 30 78 30 30 30 30 30 30 30 38 0a 23 64 65 66   0x00000008.#def
67f0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
6800: 5f 41 54 4f 4d 49 43 34 4b 20 20 20 20 20 20 20  _ATOMIC4K       
6810: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
6820: 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  10.#define SQLIT
6830: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b  E_IOCAP_ATOMIC8K
6840: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
6850: 78 30 30 30 30 30 30 32 30 0a 23 64 65 66 69 6e  x00000020.#defin
6860: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
6870: 54 4f 4d 49 43 31 36 4b 20 20 20 20 20 20 20 20  TOMIC16K        
6880: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 34 30        0x00000040
6890: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
68a0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 20  IOCAP_ATOMIC32K 
68b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
68c0: 30 30 30 30 30 38 30 0a 23 64 65 66 69 6e 65 20  0000080.#define 
68d0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
68e0: 4d 49 43 36 34 4b 20 20 20 20 20 20 20 20 20 20  MIC64K          
68f0: 20 20 20 20 30 78 30 30 30 30 30 31 30 30 0a 23      0x00000100.#
6900: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
6910: 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20  CAP_SAFE_APPEND 
6920: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
6930: 30 30 32 30 30 0a 23 64 65 66 69 6e 65 20 53 51  00200.#define SQ
6940: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45  LITE_IOCAP_SEQUE
6950: 4e 54 49 41 4c 20 20 20 20 20 20 20 20 20 20 20  NTIAL           
6960: 20 20 30 78 30 30 30 30 30 34 30 30 0a 23 64 65    0x00000400.#de
6970: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
6980: 50 5f 55 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48  P_UNDELETABLE_WH
6990: 45 4e 5f 4f 50 45 4e 20 20 30 78 30 30 30 30 30  EN_OPEN  0x00000
69a0: 38 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  800.#define SQLI
69b0: 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41  TE_IOCAP_POWERSA
69c0: 46 45 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20  FE_OVERWRITE    
69d0: 30 78 30 30 30 30 31 30 30 30 0a 0a 2f 2a 0a 2a  0x00001000../*.*
69e0: 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69 6c 65  * CAPI3REF: File
69f0: 20 4c 6f 63 6b 69 6e 67 20 4c 65 76 65 6c 73 0a   Locking Levels.
6a00: 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65  **.** SQLite use
6a10: 73 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 69  s one of these i
6a20: 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 61 73  nteger values as
6a30: 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61   the second.** a
6a40: 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73  rgument to calls
6a50: 20 69 74 20 6d 61 6b 65 73 20 74 6f 20 74 68 65   it makes to the
6a60: 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e   xLock() and xUn
6a70: 6c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a  lock() methods.*
6a80: 2a 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33  * of an [sqlite3
6a90: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
6aa0: 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ect..*/.#define 
6ab0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45  SQLITE_LOCK_NONE
6ac0: 20 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 66            0.#def
6ad0: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ine SQLITE_LOCK_
6ae0: 53 48 41 52 45 44 20 20 20 20 20 20 20 20 31 0a  SHARED        1.
6af0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
6b00: 4f 43 4b 5f 52 45 53 45 52 56 45 44 20 20 20 20  OCK_RESERVED    
6b10: 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
6b20: 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20  TE_LOCK_PENDING 
6b30: 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20        3.#define 
6b40: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c  SQLITE_LOCK_EXCL
6b50: 55 53 49 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a  USIVE     4../*.
6b60: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 79 6e  ** CAPI3REF: Syn
6b70: 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70  chronization Typ
6b80: 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68  e Flags.**.** Wh
6b90: 65 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65  en SQLite invoke
6ba0: 73 20 74 68 65 20 78 53 79 6e 63 28 29 20 6d 65  s the xSync() me
6bb0: 74 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73  thod of an.** [s
6bc0: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
6bd0: 73 5d 20 6f 62 6a 65 63 74 20 69 74 20 75 73 65  s] object it use
6be0: 73 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20  s a combination 
6bf0: 6f 66 0a 2a 2a 20 74 68 65 73 65 20 69 6e 74 65  of.** these inte
6c00: 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68  ger values as th
6c10: 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
6c20: 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68  t..**.** When th
6c30: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41  e SQLITE_SYNC_DA
6c40: 54 41 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20 75  TAONLY flag is u
6c50: 73 65 64 2c 20 69 74 20 6d 65 61 6e 73 20 74 68  sed, it means th
6c60: 61 74 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f  at the.** sync o
6c70: 70 65 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65  peration only ne
6c80: 65 64 73 20 74 6f 20 66 6c 75 73 68 20 64 61 74  eds to flush dat
6c90: 61 20 74 6f 20 6d 61 73 73 20 73 74 6f 72 61 67  a to mass storag
6ca0: 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66  e.  Inode.** inf
6cb0: 6f 72 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f  ormation need no
6cc0: 74 20 62 65 20 66 6c 75 73 68 65 64 2e 20 49 66  t be flushed. If
6cd0: 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20   the lower four 
6ce0: 62 69 74 73 20 6f 66 20 74 68 65 20 66 6c 61 67  bits of the flag
6cf0: 0a 2a 2a 20 65 71 75 61 6c 20 53 51 4c 49 54 45  .** equal SQLITE
6d00: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68  _SYNC_NORMAL, th
6d10: 61 74 20 6d 65 61 6e 73 20 74 6f 20 75 73 65 20  at means to use 
6d20: 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 20 73  normal fsync() s
6d30: 65 6d 61 6e 74 69 63 73 2e 0a 2a 2a 20 49 66 20  emantics..** If 
6d40: 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62  the lower four b
6d50: 69 74 73 20 65 71 75 61 6c 20 53 51 4c 49 54 45  its equal SQLITE
6d60: 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 74 68 61 74  _SYNC_FULL, that
6d70: 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65   means.** to use
6d80: 20 4d 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20   Mac OS X style 
6d90: 66 75 6c 6c 73 79 6e 63 20 69 6e 73 74 65 61 64  fullsync instead
6da0: 20 6f 66 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 0a   of fsync()..**.
6db0: 2a 2a 20 44 6f 20 6e 6f 74 20 63 6f 6e 66 75 73  ** Do not confus
6dc0: 65 20 74 68 65 20 53 51 4c 49 54 45 5f 53 59 4e  e the SQLITE_SYN
6dd0: 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c  C_NORMAL and SQL
6de0: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c  ITE_SYNC_FULL fl
6df0: 61 67 73 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  ags.** with the 
6e00: 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e  [PRAGMA synchron
6e10: 6f 75 73 5d 3d 4e 4f 52 4d 41 4c 20 61 6e 64 20  ous]=NORMAL and 
6e20: 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e  [PRAGMA synchron
6e30: 6f 75 73 5d 3d 46 55 4c 4c 0a 2a 2a 20 73 65 74  ous]=FULL.** set
6e40: 74 69 6e 67 73 2e 20 20 54 68 65 20 5b 73 79 6e  tings.  The [syn
6e50: 63 68 72 6f 6e 6f 75 73 20 70 72 61 67 6d 61 5d  chronous pragma]
6e60: 20 64 65 74 65 72 6d 69 6e 65 73 20 77 68 65 6e   determines when
6e70: 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 0a 2a 2a   calls to the.**
6e80: 20 78 53 79 6e 63 20 56 46 53 20 6d 65 74 68 6f   xSync VFS metho
6e90: 64 20 6f 63 63 75 72 20 61 6e 64 20 61 70 70 6c  d occur and appl
6ea0: 69 65 73 20 75 6e 69 66 6f 72 6d 6c 79 20 61 63  ies uniformly ac
6eb0: 72 6f 73 73 20 61 6c 6c 20 70 6c 61 74 66 6f 72  ross all platfor
6ec0: 6d 73 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54  ms..** The SQLIT
6ed0: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e  E_SYNC_NORMAL an
6ee0: 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55  d SQLITE_SYNC_FU
6ef0: 4c 4c 20 66 6c 61 67 73 20 64 65 74 65 72 6d 69  LL flags determi
6f00: 6e 65 20 68 6f 77 0a 2a 2a 20 65 6e 65 72 67 65  ne how.** energe
6f10: 74 69 63 20 6f 72 20 72 69 67 6f 72 6f 75 73 20  tic or rigorous 
6f20: 6f 72 20 66 6f 72 63 65 66 75 6c 20 74 68 65 20  or forceful the 
6f30: 73 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e 73 20  sync operations 
6f40: 61 72 65 20 61 6e 64 0a 2a 2a 20 6f 6e 6c 79 20  are and.** only 
6f50: 6d 61 6b 65 20 61 20 64 69 66 66 65 72 65 6e 63  make a differenc
6f60: 65 20 6f 6e 20 4d 61 63 20 4f 53 58 20 66 6f 72  e on Mac OSX for
6f70: 20 74 68 65 20 64 65 66 61 75 6c 74 20 53 51 4c   the default SQL
6f80: 69 74 65 20 63 6f 64 65 2e 0a 2a 2a 20 28 54 68  ite code..** (Th
6f90: 69 72 64 2d 70 61 72 74 79 20 56 46 53 20 69 6d  ird-party VFS im
6fa0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 69  plementations mi
6fb0: 67 68 74 20 61 6c 73 6f 20 6d 61 6b 65 20 74 68  ght also make th
6fc0: 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a  e distinction.**
6fd0: 20 62 65 74 77 65 65 6e 20 53 51 4c 49 54 45 5f   between SQLITE_
6fe0: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20  SYNC_NORMAL and 
6ff0: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c  SQLITE_SYNC_FULL
7000: 2c 20 62 75 74 20 61 6d 6f 6e 67 20 74 68 65 0a  , but among the.
7010: 2a 2a 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  ** operating sys
7020: 74 65 6d 73 20 6e 61 74 69 76 65 6c 79 20 73 75  tems natively su
7030: 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74  pported by SQLit
7040: 65 2c 20 6f 6e 6c 79 20 4d 61 63 20 4f 53 58 0a  e, only Mac OSX.
7050: 2a 2a 20 63 61 72 65 73 20 61 62 6f 75 74 20 74  ** cares about t
7060: 68 65 20 64 69 66 66 65 72 65 6e 63 65 2e 29 0a  he difference.).
7070: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
7080: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20  E_SYNC_NORMAL   
7090: 20 20 20 20 20 30 78 30 30 30 30 32 0a 23 64 65       0x00002.#de
70a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43  fine SQLITE_SYNC
70b0: 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 20 20 30  _FULL          0
70c0: 78 30 30 30 30 33 0a 23 64 65 66 69 6e 65 20 53  x00003.#define S
70d0: 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f  QLITE_SYNC_DATAO
70e0: 4e 4c 59 20 20 20 20 20 20 30 78 30 30 30 31 30  NLY      0x00010
70f0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
7100: 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f  : OS Interface O
7110: 70 65 6e 20 46 69 6c 65 20 48 61 6e 64 6c 65 0a  pen File Handle.
7120: 2a 2a 0a 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65  **.** An [sqlite
7130: 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72  3_file] object r
7140: 65 70 72 65 73 65 6e 74 73 20 61 6e 20 6f 70 65  epresents an ope
7150: 6e 20 66 69 6c 65 20 69 6e 20 74 68 65 20 0a 2a  n file in the .*
7160: 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c  * [sqlite3_vfs |
7170: 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61   OS interface la
7180: 79 65 72 5d 2e 20 20 49 6e 64 69 76 69 64 75 61  yer].  Individua
7190: 6c 20 4f 53 20 69 6e 74 65 72 66 61 63 65 0a 2a  l OS interface.*
71a0: 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
71b0: 73 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74  s will.** want t
71c0: 6f 20 73 75 62 63 6c 61 73 73 20 74 68 69 73 20  o subclass this 
71d0: 6f 62 6a 65 63 74 20 62 79 20 61 70 70 65 6e 64  object by append
71e0: 69 6e 67 20 61 64 64 69 74 69 6f 6e 61 6c 20 66  ing additional f
71f0: 69 65 6c 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65  ields.** for the
7200: 69 72 20 6f 77 6e 20 75 73 65 2e 20 20 54 68 65  ir own use.  The
7210: 20 70 4d 65 74 68 6f 64 73 20 65 6e 74 72 79 20   pMethods entry 
7220: 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
7230: 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69  an.** [sqlite3_i
7240: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63  o_methods] objec
7250: 74 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 6d  t that defines m
7260: 65 74 68 6f 64 73 20 66 6f 72 20 70 65 72 66 6f  ethods for perfo
7270: 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65  rming.** I/O ope
7280: 72 61 74 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f  rations on the o
7290: 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70  pen file..*/.typ
72a0: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
72b0: 74 65 33 5f 66 69 6c 65 20 73 71 6c 69 74 65 33  te3_file sqlite3
72c0: 5f 66 69 6c 65 3b 0a 73 74 72 75 63 74 20 73 71  _file;.struct sq
72d0: 6c 69 74 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63  lite3_file {.  c
72e0: 6f 6e 73 74 20 73 74 72 75 63 74 20 73 71 6c 69  onst struct sqli
72f0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a  te3_io_methods *
7300: 70 4d 65 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65  pMethods;  /* Me
7310: 74 68 6f 64 73 20 66 6f 72 20 61 6e 20 6f 70 65  thods for an ope
7320: 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a  n file */.};../*
7330: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53  .** CAPI3REF: OS
7340: 20 49 6e 74 65 72 66 61 63 65 20 46 69 6c 65 20   Interface File 
7350: 56 69 72 74 75 61 6c 20 4d 65 74 68 6f 64 73 20  Virtual Methods 
7360: 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65  Object.**.** Eve
7370: 72 79 20 66 69 6c 65 20 6f 70 65 6e 65 64 20 62  ry file opened b
7380: 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  y the [sqlite3_v
7390: 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64  fs.xOpen] method
73a0: 20 70 6f 70 75 6c 61 74 65 73 20 61 6e 0a 2a 2a   populates an.**
73b0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
73c0: 6f 62 6a 65 63 74 20 28 6f 72 2c 20 6d 6f 72 65  object (or, more
73d0: 20 63 6f 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75 62   commonly, a sub
73e0: 63 6c 61 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20  class of the.** 
73f0: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f  [sqlite3_file] o
7400: 62 6a 65 63 74 29 20 77 69 74 68 20 61 20 70 6f  bject) with a po
7410: 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74  inter to an inst
7420: 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a  ance of this obj
7430: 65 63 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a  ect..** This obj
7440: 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20  ect defines the 
7450: 6d 65 74 68 6f 64 73 20 75 73 65 64 20 74 6f 20  methods used to 
7460: 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20  perform various 
7470: 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 67  operations.** ag
7480: 61 69 6e 73 74 20 74 68 65 20 6f 70 65 6e 20 66  ainst the open f
7490: 69 6c 65 20 72 65 70 72 65 73 65 6e 74 65 64 20  ile represented 
74a0: 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  by the [sqlite3_
74b0: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a  file] object..**
74c0: 0a 2a 2a 20 49 66 20 74 68 65 20 5b 73 71 6c 69  .** If the [sqli
74d0: 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d  te3_vfs.xOpen] m
74e0: 65 74 68 6f 64 20 73 65 74 73 20 74 68 65 20 73  ethod sets the s
74f0: 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74  qlite3_file.pMet
7500: 68 6f 64 73 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a  hods element .**
7510: 20 74 6f 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70   to a non-NULL p
7520: 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 74 68 65  ointer, then the
7530: 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68   sqlite3_io_meth
7540: 6f 64 73 2e 78 43 6c 6f 73 65 20 6d 65 74 68 6f  ods.xClose metho
7550: 64 0a 2a 2a 20 6d 61 79 20 62 65 20 69 6e 76 6f  d.** may be invo
7560: 6b 65 64 20 65 76 65 6e 20 69 66 20 74 68 65 20  ked even if the 
7570: 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70  [sqlite3_vfs.xOp
7580: 65 6e 5d 20 72 65 70 6f 72 74 65 64 20 74 68 61  en] reported tha
7590: 74 20 69 74 20 66 61 69 6c 65 64 2e 20 20 54 68  t it failed.  Th
75a0: 65 0a 2a 2a 20 6f 6e 6c 79 20 77 61 79 20 74 6f  e.** only way to
75b0: 20 70 72 65 76 65 6e 74 20 61 20 63 61 6c 6c 20   prevent a call 
75c0: 74 6f 20 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f 77  to xClose follow
75d0: 69 6e 67 20 61 20 66 61 69 6c 65 64 20 5b 73 71  ing a failed [sq
75e0: 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d  lite3_vfs.xOpen]
75f0: 0a 2a 2a 20 69 73 20 66 6f 72 20 74 68 65 20 5b  .** is for the [
7600: 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65  sqlite3_vfs.xOpe
7610: 6e 5d 20 74 6f 20 73 65 74 20 74 68 65 20 73 71  n] to set the sq
7620: 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68  lite3_file.pMeth
7630: 6f 64 73 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 74  ods element.** t
7640: 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68  o NULL..**.** Th
7650: 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74  e flags argument
7660: 20 74 6f 20 78 53 79 6e 63 20 6d 61 79 20 62 65   to xSync may be
7670: 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f   one of [SQLITE_
7680: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a  SYNC_NORMAL] or.
7690: 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f  ** [SQLITE_SYNC_
76a0: 46 55 4c 4c 5d 2e 20 20 54 68 65 20 66 69 72 73  FULL].  The firs
76b0: 74 20 63 68 6f 69 63 65 20 69 73 20 74 68 65 20  t choice is the 
76c0: 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 2e 0a  normal fsync()..
76d0: 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 63 68  ** The second ch
76e0: 6f 69 63 65 20 69 73 20 61 20 4d 61 63 20 4f 53  oice is a Mac OS
76f0: 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e   X style fullsyn
7700: 63 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  c.  The [SQLITE_
7710: 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a  SYNC_DATAONLY].*
7720: 2a 20 66 6c 61 67 20 6d 61 79 20 62 65 20 4f 52  * flag may be OR
7730: 65 64 20 69 6e 20 74 6f 20 69 6e 64 69 63 61 74  ed in to indicat
7740: 65 20 74 68 61 74 20 6f 6e 6c 79 20 74 68 65 20  e that only the 
7750: 64 61 74 61 20 6f 66 20 74 68 65 20 66 69 6c 65  data of the file
7760: 0a 2a 2a 20 61 6e 64 20 6e 6f 74 20 69 74 73 20  .** and not its 
7770: 69 6e 6f 64 65 20 6e 65 65 64 73 20 74 6f 20 62  inode needs to b
7780: 65 20 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20  e synced..**.** 
7790: 54 68 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75  The integer valu
77a0: 65 73 20 74 6f 20 78 4c 6f 63 6b 28 29 20 61 6e  es to xLock() an
77b0: 64 20 78 55 6e 6c 6f 63 6b 28 29 20 61 72 65 20  d xUnlock() are 
77c0: 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a  one of.** <ul>.*
77d0: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c  * <li> [SQLITE_L
77e0: 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c  OCK_NONE],.** <l
77f0: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
7800: 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e  SHARED],.** <li>
7810: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45   [SQLITE_LOCK_RE
7820: 53 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e  SERVED],.** <li>
7830: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45   [SQLITE_LOCK_PE
7840: 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c  NDING], or.** <l
7850: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
7860: 45 58 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c  EXCLUSIVE]..** <
7870: 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20  /ul>.** xLock() 
7880: 69 6e 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f  increases the lo
7890: 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29 20 64 65  ck. xUnlock() de
78a0: 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b  creases the lock
78b0: 2e 0a 2a 2a 20 54 68 65 20 78 43 68 65 63 6b 52  ..** The xCheckR
78c0: 65 73 65 72 76 65 64 4c 6f 63 6b 28 29 20 6d 65  eservedLock() me
78d0: 74 68 6f 64 20 63 68 65 63 6b 73 20 77 68 65 74  thod checks whet
78e0: 68 65 72 20 61 6e 79 20 64 61 74 61 62 61 73 65  her any database
78f0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20   connection,.** 
7900: 65 69 74 68 65 72 20 69 6e 20 74 68 69 73 20 70  either in this p
7910: 72 6f 63 65 73 73 20 6f 72 20 69 6e 20 73 6f 6d  rocess or in som
7920: 65 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73 2c  e other process,
7930: 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 52 45   is holding a RE
7940: 53 45 52 56 45 44 2c 0a 2a 2a 20 50 45 4e 44 49  SERVED,.** PENDI
7950: 4e 47 2c 20 6f 72 20 45 58 43 4c 55 53 49 56 45  NG, or EXCLUSIVE
7960: 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 66 69 6c   lock on the fil
7970: 65 2e 20 20 49 74 20 72 65 74 75 72 6e 73 20 74  e.  It returns t
7980: 72 75 65 0a 2a 2a 20 69 66 20 73 75 63 68 20 61  rue.** if such a
7990: 20 6c 6f 63 6b 20 65 78 69 73 74 73 20 61 6e 64   lock exists and
79a0: 20 66 61 6c 73 65 20 6f 74 68 65 72 77 69 73 65   false otherwise
79b0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 69 6c  ..**.** The xFil
79c0: 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 65 74 68 6f  eControl() metho
79d0: 64 20 69 73 20 61 20 67 65 6e 65 72 69 63 20 69  d is a generic i
79e0: 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 61 6c  nterface that al
79f0: 6c 6f 77 73 20 63 75 73 74 6f 6d 0a 2a 2a 20 56  lows custom.** V
7a00: 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  FS implementatio
7a10: 6e 73 20 74 6f 20 64 69 72 65 63 74 6c 79 20 63  ns to directly c
7a20: 6f 6e 74 72 6f 6c 20 61 6e 20 6f 70 65 6e 20 66  ontrol an open f
7a30: 69 6c 65 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a  ile using the.**
7a40: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
7a50: 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66  ontrol()] interf
7a60: 61 63 65 2e 20 20 54 68 65 20 73 65 63 6f 6e 64  ace.  The second
7a70: 20 22 6f 70 22 20 61 72 67 75 6d 65 6e 74 20 69   "op" argument i
7a80: 73 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20  s an.** integer 
7a90: 6f 70 63 6f 64 65 2e 20 20 54 68 65 20 74 68 69  opcode.  The thi
7aa0: 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  rd argument is a
7ab0: 20 67 65 6e 65 72 69 63 20 70 6f 69 6e 74 65 72   generic pointer
7ac0: 20 69 6e 74 65 6e 64 65 64 20 74 6f 0a 2a 2a 20   intended to.** 
7ad0: 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 75 63  point to a struc
7ae0: 74 75 72 65 20 74 68 61 74 20 6d 61 79 20 63 6f  ture that may co
7af0: 6e 74 61 69 6e 20 61 72 67 75 6d 65 6e 74 73 20  ntain arguments 
7b00: 6f 72 20 73 70 61 63 65 20 69 6e 20 77 68 69 63  or space in whic
7b10: 68 20 74 6f 0a 2a 2a 20 77 72 69 74 65 20 72 65  h to.** write re
7b20: 74 75 72 6e 20 76 61 6c 75 65 73 2e 20 20 50 6f  turn values.  Po
7b30: 74 65 6e 74 69 61 6c 20 75 73 65 73 20 66 6f 72  tential uses for
7b40: 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20   xFileControl() 
7b50: 6d 69 67 68 74 20 62 65 0a 2a 2a 20 66 75 6e 63  might be.** func
7b60: 74 69 6f 6e 73 20 74 6f 20 65 6e 61 62 6c 65 20  tions to enable 
7b70: 62 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73 20 77  blocking locks w
7b80: 69 74 68 20 74 69 6d 65 6f 75 74 73 2c 20 74 6f  ith timeouts, to
7b90: 20 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20 6c   change the.** l
7ba0: 6f 63 6b 69 6e 67 20 73 74 72 61 74 65 67 79 20  ocking strategy 
7bb0: 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 74 6f 20  (for example to 
7bc0: 75 73 65 20 64 6f 74 2d 66 69 6c 65 20 6c 6f 63  use dot-file loc
7bd0: 6b 73 29 2c 20 74 6f 20 69 6e 71 75 69 72 65 0a  ks), to inquire.
7be0: 2a 2a 20 61 62 6f 75 74 20 74 68 65 20 73 74 61  ** about the sta
7bf0: 74 75 73 20 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f  tus of a lock, o
7c00: 72 20 74 6f 20 62 72 65 61 6b 20 73 74 61 6c 65  r to break stale
7c10: 20 6c 6f 63 6b 73 2e 20 20 54 68 65 20 53 51 4c   locks.  The SQL
7c20: 69 74 65 0a 2a 2a 20 63 6f 72 65 20 72 65 73 65  ite.** core rese
7c30: 72 76 65 73 20 61 6c 6c 20 6f 70 63 6f 64 65 73  rves all opcodes
7c40: 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20 66   less than 100 f
7c50: 6f 72 20 69 74 73 20 6f 77 6e 20 75 73 65 2e 0a  or its own use..
7c60: 2a 2a 20 41 20 5b 53 51 4c 49 54 45 5f 46 43 4e  ** A [SQLITE_FCN
7c70: 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 7c 20 6c  TL_LOCKSTATE | l
7c80: 69 73 74 20 6f 66 20 6f 70 63 6f 64 65 73 5d 20  ist of opcodes] 
7c90: 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20 69 73  less than 100 is
7ca0: 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41   available..** A
7cb0: 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74  pplications that
7cc0: 20 64 65 66 69 6e 65 20 61 20 63 75 73 74 6f 6d   define a custom
7cd0: 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65   xFileControl me
7ce0: 74 68 6f 64 20 73 68 6f 75 6c 64 20 75 73 65 20  thod should use 
7cf0: 6f 70 63 6f 64 65 73 0a 2a 2a 20 67 72 65 61 74  opcodes.** great
7d00: 65 72 20 74 68 61 6e 20 31 30 30 20 74 6f 20 61  er than 100 to a
7d10: 76 6f 69 64 20 63 6f 6e 66 6c 69 63 74 73 2e 20  void conflicts. 
7d20: 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
7d30: 69 6f 6e 73 20 73 68 6f 75 6c 64 0a 2a 2a 20 72  ions should.** r
7d40: 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f  eturn [SQLITE_NO
7d50: 54 46 4f 55 4e 44 5d 20 66 6f 72 20 66 69 6c 65  TFOUND] for file
7d60: 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73   control opcodes
7d70: 20 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f   that they do no
7d80: 74 0a 2a 2a 20 72 65 63 6f 67 6e 69 7a 65 2e 0a  t.** recognize..
7d90: 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 65 63 74 6f  **.** The xSecto
7da0: 72 53 69 7a 65 28 29 20 6d 65 74 68 6f 64 20 72  rSize() method r
7db0: 65 74 75 72 6e 73 20 74 68 65 20 73 65 63 74 6f  eturns the secto
7dc0: 72 20 73 69 7a 65 20 6f 66 20 74 68 65 0a 2a 2a  r size of the.**
7dd0: 20 64 65 76 69 63 65 20 74 68 61 74 20 75 6e 64   device that und
7de0: 65 72 6c 69 65 73 20 74 68 65 20 66 69 6c 65 2e  erlies the file.
7df0: 20 20 54 68 65 20 73 65 63 74 6f 72 20 73 69 7a    The sector siz
7e00: 65 20 69 73 20 74 68 65 0a 2a 2a 20 6d 69 6e 69  e is the.** mini
7e10: 6d 75 6d 20 77 72 69 74 65 20 74 68 61 74 20 63  mum write that c
7e20: 61 6e 20 62 65 20 70 65 72 66 6f 72 6d 65 64 20  an be performed 
7e30: 77 69 74 68 6f 75 74 20 64 69 73 74 75 72 62 69  without disturbi
7e40: 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 62 79 74 65  ng.** other byte
7e50: 73 20 69 6e 20 74 68 65 20 66 69 6c 65 2e 20 20  s in the file.  
7e60: 54 68 65 20 78 44 65 76 69 63 65 43 68 61 72 61  The xDeviceChara
7e70: 63 74 65 72 69 73 74 69 63 73 28 29 0a 2a 2a 20  cteristics().** 
7e80: 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61  method returns a
7e90: 20 62 69 74 20 76 65 63 74 6f 72 20 64 65 73 63   bit vector desc
7ea0: 72 69 62 69 6e 67 20 62 65 68 61 76 69 6f 72 73  ribing behaviors
7eb0: 20 6f 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72   of the.** under
7ec0: 6c 79 69 6e 67 20 64 65 76 69 63 65 3a 0a 2a 2a  lying device:.**
7ed0: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
7ee0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
7ef0: 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  TOMIC].** <li> [
7f00: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
7f10: 4d 49 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20  MIC512].** <li> 
7f20: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
7f30: 4f 4d 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  OMIC1K].** <li> 
7f40: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
7f50: 4f 4d 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  OMIC2K].** <li> 
7f60: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
7f70: 4f 4d 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  OMIC4K].** <li> 
7f80: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
7f90: 4f 4d 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  OMIC8K].** <li> 
7fa0: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
7fb0: 4f 4d 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e  OMIC16K].** <li>
7fc0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
7fd0: 54 4f 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69  TOMIC32K].** <li
7fe0: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
7ff0: 41 54 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c  ATOMIC64K].** <l
8000: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
8010: 5f 53 41 46 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a  _SAFE_APPEND].**
8020: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
8030: 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 5d 0a  CAP_SEQUENTIAL].
8040: 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54  ** </ul>.**.** T
8050: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
8060: 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20  ATOMIC property 
8070: 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77  means that all w
8080: 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20  rites of.** any 
8090: 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e  size are atomic.
80a0: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
80b0: 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c  AP_ATOMICnnn val
80c0: 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74  ues.** mean that
80d0: 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b   writes of block
80e0: 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62  s that are nnn b
80f0: 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64  ytes in size and
8100: 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20  .** are aligned 
8110: 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77 68  to an address wh
8120: 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ich is an intege
8130: 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a  r multiple of.**
8140: 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e   nnn are atomic.
8150: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
8160: 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76  AP_SAFE_APPEND v
8170: 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68  alue means.** th
8180: 61 74 20 77 68 65 6e 20 64 61 74 61 20 69 73 20  at when data is 
8190: 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69  appended to a fi
81a0: 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69 73 20  le, the data is 
81b0: 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73  appended.** firs
81c0: 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20  t then the size 
81d0: 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 65  of the file is e
81e0: 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74  xtended, never t
81f0: 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20  he other.** way 
8200: 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c  around.  The SQL
8210: 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e  ITE_IOCAP_SEQUEN
8220: 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65  TIAL property me
8230: 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f  ans that.** info
8240: 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74  rmation is writt
8250: 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68  en to disk in th
8260: 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20  e same order as 
8270: 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69  calls.** to xWri
8280: 74 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 78  te()..**.** If x
8290: 52 65 61 64 28 29 20 72 65 74 75 72 6e 73 20 53  Read() returns S
82a0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52  QLITE_IOERR_SHOR
82b0: 54 5f 52 45 41 44 20 69 74 20 6d 75 73 74 20 61  T_READ it must a
82c0: 6c 73 6f 20 66 69 6c 6c 0a 2a 2a 20 69 6e 20 74  lso fill.** in t
82d0: 68 65 20 75 6e 72 65 61 64 20 70 6f 72 74 69 6f  he unread portio
82e0: 6e 73 20 6f 66 20 74 68 65 20 62 75 66 66 65 72  ns of the buffer
82f0: 20 77 69 74 68 20 7a 65 72 6f 73 2e 20 20 41 20   with zeros.  A 
8300: 56 46 53 20 74 68 61 74 0a 2a 2a 20 66 61 69 6c  VFS that.** fail
8310: 73 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73  s to zero-fill s
8320: 68 6f 72 74 20 72 65 61 64 73 20 6d 69 67 68 74  hort reads might
8330: 20 73 65 65 6d 20 74 6f 20 77 6f 72 6b 2e 20 20   seem to work.  
8340: 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 61 69 6c  However,.** fail
8350: 75 72 65 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c  ure to zero-fill
8360: 20 73 68 6f 72 74 20 72 65 61 64 73 20 77 69 6c   short reads wil
8370: 6c 20 65 76 65 6e 74 75 61 6c 6c 79 20 6c 65 61  l eventually lea
8380: 64 20 74 6f 0a 2a 2a 20 64 61 74 61 62 61 73 65  d to.** database
8390: 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a   corruption..*/.
83a0: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
83b0: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
83c0: 73 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74  s sqlite3_io_met
83d0: 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c  hods;.struct sql
83e0: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20  ite3_io_methods 
83f0: 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e  {.  int iVersion
8400: 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65  ;.  int (*xClose
8410: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29  )(sqlite3_file*)
8420: 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65 61 64 29  ;.  int (*xRead)
8430: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
8440: 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c  void*, int iAmt,
8450: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69   sqlite3_int64 i
8460: 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78  Ofst);.  int (*x
8470: 57 72 69 74 65 29 28 73 71 6c 69 74 65 33 5f 66  Write)(sqlite3_f
8480: 69 6c 65 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64  ile*, const void
8490: 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c  *, int iAmt, sql
84a0: 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74  ite3_int64 iOfst
84b0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 54 72 75 6e  );.  int (*xTrun
84c0: 63 61 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69  cate)(sqlite3_fi
84d0: 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  le*, sqlite3_int
84e0: 36 34 20 73 69 7a 65 29 3b 0a 20 20 69 6e 74 20  64 size);.  int 
84f0: 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 74 65 33  (*xSync)(sqlite3
8500: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 66 6c 61 67  _file*, int flag
8510: 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c  s);.  int (*xFil
8520: 65 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f 66  eSize)(sqlite3_f
8530: 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  ile*, sqlite3_in
8540: 74 36 34 20 2a 70 53 69 7a 65 29 3b 0a 20 20 69  t64 *pSize);.  i
8550: 6e 74 20 28 2a 78 4c 6f 63 6b 29 28 73 71 6c 69  nt (*xLock)(sqli
8560: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b  te3_file*, int);
8570: 0a 20 20 69 6e 74 20 28 2a 78 55 6e 6c 6f 63 6b  .  int (*xUnlock
8580: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
8590: 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78   int);.  int (*x
85a0: 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c 6f 63  CheckReservedLoc
85b0: 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  k)(sqlite3_file*
85c0: 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b  , int *pResOut);
85d0: 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 43 6f  .  int (*xFileCo
85e0: 6e 74 72 6f 6c 29 28 73 71 6c 69 74 65 33 5f 66  ntrol)(sqlite3_f
85f0: 69 6c 65 2a 2c 20 69 6e 74 20 6f 70 2c 20 76 6f  ile*, int op, vo
8600: 69 64 20 2a 70 41 72 67 29 3b 0a 20 20 69 6e 74  id *pArg);.  int
8610: 20 28 2a 78 53 65 63 74 6f 72 53 69 7a 65 29 28   (*xSectorSize)(
8620: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a  sqlite3_file*);.
8630: 20 20 69 6e 74 20 28 2a 78 44 65 76 69 63 65 43    int (*xDeviceC
8640: 68 61 72 61 63 74 65 72 69 73 74 69 63 73 29 28  haracteristics)(
8650: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a  sqlite3_file*);.
8660: 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f    /* Methods abo
8670: 76 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72  ve are valid for
8680: 20 76 65 72 73 69 6f 6e 20 31 20 2a 2f 0a 20 20   version 1 */.  
8690: 69 6e 74 20 28 2a 78 53 68 6d 4d 61 70 29 28 73  int (*xShmMap)(s
86a0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
86b0: 74 20 69 50 67 2c 20 69 6e 74 20 70 67 73 7a 2c  t iPg, int pgsz,
86c0: 20 69 6e 74 2c 20 76 6f 69 64 20 76 6f 6c 61 74   int, void volat
86d0: 69 6c 65 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  ile**);.  int (*
86e0: 78 53 68 6d 4c 6f 63 6b 29 28 73 71 6c 69 74 65  xShmLock)(sqlite
86f0: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 66 66  3_file*, int off
8700: 73 65 74 2c 20 69 6e 74 20 6e 2c 20 69 6e 74 20  set, int n, int 
8710: 66 6c 61 67 73 29 3b 0a 20 20 76 6f 69 64 20 28  flags);.  void (
8720: 2a 78 53 68 6d 42 61 72 72 69 65 72 29 28 73 71  *xShmBarrier)(sq
8730: 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20  lite3_file*);.  
8740: 69 6e 74 20 28 2a 78 53 68 6d 55 6e 6d 61 70 29  int (*xShmUnmap)
8750: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
8760: 69 6e 74 20 64 65 6c 65 74 65 46 6c 61 67 29 3b  int deleteFlag);
8770: 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62  .  /* Methods ab
8780: 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f  ove are valid fo
8790: 72 20 76 65 72 73 69 6f 6e 20 32 20 2a 2f 0a 20  r version 2 */. 
87a0: 20 69 6e 74 20 28 2a 78 46 65 74 63 68 29 28 73   int (*xFetch)(s
87b0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71  qlite3_file*, sq
87c0: 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73  lite3_int64 iOfs
87d0: 74 2c 20 69 6e 74 20 69 41 6d 74 2c 20 76 6f 69  t, int iAmt, voi
87e0: 64 20 2a 2a 70 70 29 3b 0a 20 20 69 6e 74 20 28  d **pp);.  int (
87f0: 2a 78 55 6e 66 65 74 63 68 29 28 73 71 6c 69 74  *xUnfetch)(sqlit
8800: 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65  e3_file*, sqlite
8810: 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 2c 20 76  3_int64 iOfst, v
8820: 6f 69 64 20 2a 70 29 3b 0a 20 20 2f 2a 20 4d 65  oid *p);.  /* Me
8830: 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20  thods above are 
8840: 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f  valid for versio
8850: 6e 20 33 20 2a 2f 0a 20 20 2f 2a 20 41 64 64 69  n 3 */.  /* Addi
8860: 74 69 6f 6e 61 6c 20 6d 65 74 68 6f 64 73 20 6d  tional methods m
8870: 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66  ay be added in f
8880: 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 2a  uture releases *
8890: 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.};../*.** CAPI
88a0: 33 52 45 46 3a 20 53 74 61 6e 64 61 72 64 20 46  3REF: Standard F
88b0: 69 6c 65 20 43 6f 6e 74 72 6f 6c 20 4f 70 63 6f  ile Control Opco
88c0: 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  des.**.** These 
88d0: 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74  integer constant
88e0: 73 20 61 72 65 20 6f 70 63 6f 64 65 73 20 66 6f  s are opcodes fo
88f0: 72 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72  r the xFileContr
8900: 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66 20  ol method.** of 
8910: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  the [sqlite3_io_
8920: 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20  methods] object 
8930: 61 6e 64 20 66 6f 72 20 74 68 65 20 5b 73 71 6c  and for the [sql
8940: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
8950: 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63  l()].** interfac
8960: 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51  e..**.** The [SQ
8970: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53  LITE_FCNTL_LOCKS
8980: 54 41 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20  TATE] opcode is 
8990: 75 73 65 64 20 66 6f 72 20 64 65 62 75 67 67 69  used for debuggi
89a0: 6e 67 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63  ng.  This.** opc
89b0: 6f 64 65 20 63 61 75 73 65 73 20 74 68 65 20 78  ode causes the x
89c0: 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68  FileControl meth
89d0: 6f 64 20 74 6f 20 77 72 69 74 65 20 74 68 65 20  od to write the 
89e0: 63 75 72 72 65 6e 74 20 73 74 61 74 65 20 6f 66  current state of
89f0: 0a 2a 2a 20 74 68 65 20 6c 6f 63 6b 20 28 6f 6e  .** the lock (on
8a00: 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  e of [SQLITE_LOC
8a10: 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45  K_NONE], [SQLITE
8a20: 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a  _LOCK_SHARED],.*
8a30: 2a 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52  * [SQLITE_LOCK_R
8a40: 45 53 45 52 56 45 44 5d 2c 20 5b 53 51 4c 49 54  ESERVED], [SQLIT
8a50: 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c  E_LOCK_PENDING],
8a60: 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b   or [SQLITE_LOCK
8a70: 5f 45 58 43 4c 55 53 49 56 45 5d 29 0a 2a 2a 20  _EXCLUSIVE]).** 
8a80: 69 6e 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20  into an integer 
8a90: 74 68 61 74 20 74 68 65 20 70 41 72 67 20 61 72  that the pArg ar
8aa0: 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f  gument points to
8ab0: 2e 20 54 68 69 73 20 63 61 70 61 62 69 6c 69 74  . This capabilit
8ac0: 79 0a 2a 2a 20 69 73 20 75 73 65 64 20 64 75 72  y.** is used dur
8ad0: 69 6e 67 20 74 65 73 74 69 6e 67 20 61 6e 64 20  ing testing and 
8ae0: 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 62 65  only needs to be
8af0: 20 73 75 70 70 6f 72 74 65 64 20 77 68 65 6e 20   supported when 
8b00: 53 51 4c 49 54 45 5f 54 45 53 54 0a 2a 2a 20 69  SQLITE_TEST.** i
8b10: 73 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 3c 75  s defined..** <u
8b20: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  l>.** <li>[[SQLI
8b30: 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49  TE_FCNTL_SIZE_HI
8b40: 4e 54 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  NT]].** The [SQL
8b50: 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48  ITE_FCNTL_SIZE_H
8b60: 49 4e 54 5d 20 6f 70 63 6f 64 65 20 69 73 20 75  INT] opcode is u
8b70: 73 65 64 20 62 79 20 53 51 4c 69 74 65 20 74 6f  sed by SQLite to
8b80: 20 67 69 76 65 20 74 68 65 20 56 46 53 0a 2a 2a   give the VFS.**
8b90: 20 6c 61 79 65 72 20 61 20 68 69 6e 74 20 6f 66   layer a hint of
8ba0: 20 68 6f 77 20 6c 61 72 67 65 20 74 68 65 20 64   how large the d
8bb0: 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 69 6c  atabase file wil
8bc0: 6c 20 67 72 6f 77 20 74 6f 20 62 65 20 64 75 72  l grow to be dur
8bd0: 69 6e 67 20 74 68 65 0a 2a 2a 20 63 75 72 72 65  ing the.** curre
8be0: 6e 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20  nt transaction. 
8bf0: 20 54 68 69 73 20 68 69 6e 74 20 69 73 20 6e 6f   This hint is no
8c00: 74 20 67 75 61 72 61 6e 74 65 65 64 20 74 6f 20  t guaranteed to 
8c10: 62 65 20 61 63 63 75 72 61 74 65 20 62 75 74 20  be accurate but 
8c20: 69 74 0a 2a 2a 20 69 73 20 6f 66 74 65 6e 20 63  it.** is often c
8c30: 6c 6f 73 65 2e 20 20 54 68 65 20 75 6e 64 65 72  lose.  The under
8c40: 6c 79 69 6e 67 20 56 46 53 20 6d 69 67 68 74 20  lying VFS might 
8c50: 63 68 6f 6f 73 65 20 74 6f 20 70 72 65 61 6c 6c  choose to preall
8c60: 6f 63 61 74 65 20 64 61 74 61 62 61 73 65 0a 2a  ocate database.*
8c70: 2a 20 66 69 6c 65 20 73 70 61 63 65 20 62 61 73  * file space bas
8c80: 65 64 20 6f 6e 20 74 68 69 73 20 68 69 6e 74 20  ed on this hint 
8c90: 69 6e 20 6f 72 64 65 72 20 74 6f 20 68 65 6c 70  in order to help
8ca0: 20 77 72 69 74 65 73 20 74 6f 20 74 68 65 20 64   writes to the d
8cb0: 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20  atabase.** file 
8cc0: 72 75 6e 20 66 61 73 74 65 72 2e 0a 2a 2a 0a 2a  run faster..**.*
8cd0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
8ce0: 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d  CNTL_CHUNK_SIZE]
8cf0: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
8d00: 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a  _FCNTL_CHUNK_SIZ
8d10: 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65  E] opcode is use
8d20: 64 20 74 6f 20 72 65 71 75 65 73 74 20 74 68 61  d to request tha
8d30: 74 20 74 68 65 20 56 46 53 0a 2a 2a 20 65 78 74  t the VFS.** ext
8d40: 65 6e 64 73 20 61 6e 64 20 74 72 75 6e 63 61 74  ends and truncat
8d50: 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  es the database 
8d60: 66 69 6c 65 20 69 6e 20 63 68 75 6e 6b 73 20 6f  file in chunks o
8d70: 66 20 61 20 73 69 7a 65 20 73 70 65 63 69 66 69  f a size specifi
8d80: 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 75 73 65  ed.** by the use
8d90: 72 2e 20 54 68 65 20 66 6f 75 72 74 68 20 61 72  r. The fourth ar
8da0: 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74  gument to [sqlit
8db0: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
8dc0: 29 5d 20 73 68 6f 75 6c 64 20 0a 2a 2a 20 70 6f  )] should .** po
8dd0: 69 6e 74 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  int to an intege
8de0: 72 20 28 74 79 70 65 20 69 6e 74 29 20 63 6f 6e  r (type int) con
8df0: 74 61 69 6e 69 6e 67 20 74 68 65 20 6e 65 77 20  taining the new 
8e00: 63 68 75 6e 6b 2d 73 69 7a 65 20 74 6f 20 75 73  chunk-size to us
8e10: 65 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6e 6f 6d  e.** for the nom
8e20: 69 6e 61 74 65 64 20 64 61 74 61 62 61 73 65 2e  inated database.
8e30: 20 41 6c 6c 6f 63 61 74 69 6e 67 20 64 61 74 61   Allocating data
8e40: 62 61 73 65 20 66 69 6c 65 20 73 70 61 63 65 20  base file space 
8e50: 69 6e 20 6c 61 72 67 65 0a 2a 2a 20 63 68 75 6e  in large.** chun
8e60: 6b 73 20 28 73 61 79 20 31 4d 42 20 61 74 20 61  ks (say 1MB at a
8e70: 20 74 69 6d 65 29 2c 20 6d 61 79 20 72 65 64 75   time), may redu
8e80: 63 65 20 66 69 6c 65 2d 73 79 73 74 65 6d 20 66  ce file-system f
8e90: 72 61 67 6d 65 6e 74 61 74 69 6f 6e 20 61 6e 64  ragmentation and
8ea0: 0a 2a 2a 20 69 6d 70 72 6f 76 65 20 70 65 72 66  .** improve perf
8eb0: 6f 72 6d 61 6e 63 65 20 6f 6e 20 73 6f 6d 65 20  ormance on some 
8ec0: 73 79 73 74 65 6d 73 2e 0a 2a 2a 0a 2a 2a 20 3c  systems..**.** <
8ed0: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
8ee0: 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 5d  L_FILE_POINTER]]
8ef0: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
8f00: 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54  FCNTL_FILE_POINT
8f10: 45 52 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73  ER] opcode is us
8f20: 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 61 20 70  ed to obtain a p
8f30: 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65  ointer.** to the
8f40: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
8f50: 6f 62 6a 65 63 74 20 61 73 73 6f 63 69 61 74 65  object associate
8f60: 64 20 77 69 74 68 20 61 20 70 61 72 74 69 63 75  d with a particu
8f70: 6c 61 72 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  lar database.** 
8f80: 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 53 65 65  connection.  See
8f90: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69   the [sqlite3_fi
8fa0: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 64 6f  le_control()] do
8fb0: 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a  cumentation for.
8fc0: 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e  ** additional in
8fd0: 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  formation..**.**
8fe0: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
8ff0: 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44  NTL_SYNC_OMITTED
9000: 5d 5d 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c  ]].** ^(The [SQL
9010: 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f  ITE_FCNTL_SYNC_O
9020: 4d 49 54 54 45 44 5d 20 6f 70 63 6f 64 65 20 69  MITTED] opcode i
9030: 73 20 67 65 6e 65 72 61 74 65 64 20 69 6e 74 65  s generated inte
9040: 72 6e 61 6c 6c 79 20 62 79 0a 2a 2a 20 53 51 4c  rnally by.** SQL
9050: 69 74 65 20 61 6e 64 20 73 65 6e 74 20 74 6f 20  ite and sent to 
9060: 61 6c 6c 20 56 46 53 65 73 20 69 6e 20 70 6c 61  all VFSes in pla
9070: 63 65 20 6f 66 20 61 20 63 61 6c 6c 20 74 6f 20  ce of a call to 
9080: 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68 6f 64  the xSync method
9090: 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 64 61 74  .** when the dat
90a0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
90b0: 20 68 61 73 20 5b 50 52 41 47 4d 41 20 73 79 6e   has [PRAGMA syn
90c0: 63 68 72 6f 6e 6f 75 73 5d 20 73 65 74 20 74 6f  chronous] set to
90d0: 20 4f 46 46 2e 29 5e 0a 2a 2a 20 53 6f 6d 65 20   OFF.)^.** Some 
90e0: 73 70 65 63 69 61 6c 69 7a 65 64 20 56 46 53 65  specialized VFSe
90f0: 73 20 6e 65 65 64 20 74 68 69 73 20 73 69 67 6e  s need this sign
9100: 61 6c 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 6f  al in order to o
9110: 70 65 72 61 74 65 20 63 6f 72 72 65 63 74 6c 79  perate correctly
9120: 0a 2a 2a 20 77 68 65 6e 20 5b 50 52 41 47 4d 41  .** when [PRAGMA
9130: 20 73 79 6e 63 68 72 6f 6e 6f 75 73 20 7c 20 50   synchronous | P
9140: 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75  RAGMA synchronou
9150: 73 3d 4f 46 46 5d 20 69 73 20 73 65 74 2c 20 62  s=OFF] is set, b
9160: 75 74 20 6d 6f 73 74 20 0a 2a 2a 20 56 46 53 65  ut most .** VFSe
9170: 73 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 68  s do not need th
9180: 69 73 20 73 69 67 6e 61 6c 20 61 6e 64 20 73 68  is signal and sh
9190: 6f 75 6c 64 20 73 69 6c 65 6e 74 6c 79 20 69 67  ould silently ig
91a0: 6e 6f 72 65 20 74 68 69 73 20 6f 70 63 6f 64 65  nore this opcode
91b0: 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e  ..** Application
91c0: 73 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c  s should not cal
91d0: 6c 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  l [sqlite3_file_
91e0: 63 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68 20  control()] with 
91f0: 74 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 61  this.** opcode a
9200: 73 20 64 6f 69 6e 67 20 73 6f 20 6d 61 79 20 64  s doing so may d
9210: 69 73 72 75 70 74 20 74 68 65 20 6f 70 65 72 61  isrupt the opera
9220: 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 70 65 63  tion of the spec
9230: 69 61 6c 69 7a 65 64 20 56 46 53 65 73 0a 2a 2a  ialized VFSes.**
9240: 20 74 68 61 74 20 64 6f 20 72 65 71 75 69 72 65   that do require
9250: 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69   it.  .**.** <li
9260: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
9270: 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d 5d  WIN32_AV_RETRY]]
9280: 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
9290: 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f  _FCNTL_WIN32_AV_
92a0: 52 45 54 52 59 5d 20 6f 70 63 6f 64 65 20 69 73  RETRY] opcode is
92b0: 20 75 73 65 64 20 74 6f 20 63 6f 6e 66 69 67 75   used to configu
92c0: 72 65 20 61 75 74 6f 6d 61 74 69 63 0a 2a 2a 20  re automatic.** 
92d0: 72 65 74 72 79 20 63 6f 75 6e 74 73 20 61 6e 64  retry counts and
92e0: 20 69 6e 74 65 72 76 61 6c 73 20 66 6f 72 20 63   intervals for c
92f0: 65 72 74 61 69 6e 20 64 69 73 6b 20 49 2f 4f 20  ertain disk I/O 
9300: 6f 70 65 72 61 74 69 6f 6e 73 20 66 6f 72 20 74  operations for t
9310: 68 65 0a 2a 2a 20 77 69 6e 64 6f 77 73 20 5b 56  he.** windows [V
9320: 46 53 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  FS] in order to 
9330: 70 72 6f 76 69 64 65 20 72 6f 62 75 73 74 6e 65  provide robustne
9340: 73 73 20 69 6e 20 74 68 65 20 70 72 65 73 65 6e  ss in the presen
9350: 63 65 20 6f 66 0a 2a 2a 20 61 6e 74 69 2d 76 69  ce of.** anti-vi
9360: 72 75 73 20 70 72 6f 67 72 61 6d 73 2e 20 20 42  rus programs.  B
9370: 79 20 64 65 66 61 75 6c 74 2c 20 74 68 65 20 77  y default, the w
9380: 69 6e 64 6f 77 73 20 56 46 53 20 77 69 6c 6c 20  indows VFS will 
9390: 72 65 74 72 79 20 66 69 6c 65 20 72 65 61 64 2c  retry file read,
93a0: 0a 2a 2a 20 66 69 6c 65 20 77 72 69 74 65 2c 20  .** file write, 
93b0: 61 6e 64 20 66 69 6c 65 20 64 65 6c 65 74 65 20  and file delete 
93c0: 6f 70 65 72 61 74 69 6f 6e 73 20 75 70 20 74 6f  operations up to
93d0: 20 31 30 20 74 69 6d 65 73 2c 20 77 69 74 68 20   10 times, with 
93e0: 61 20 64 65 6c 61 79 0a 2a 2a 20 6f 66 20 32 35  a delay.** of 25
93f0: 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 62 65   milliseconds be
9400: 66 6f 72 65 20 74 68 65 20 66 69 72 73 74 20 72  fore the first r
9410: 65 74 72 79 20 61 6e 64 20 77 69 74 68 20 74 68  etry and with th
9420: 65 20 64 65 6c 61 79 20 69 6e 63 72 65 61 73 69  e delay increasi
9430: 6e 67 0a 2a 2a 20 62 79 20 61 6e 20 61 64 64 69  ng.** by an addi
9440: 74 69 6f 6e 61 6c 20 32 35 20 6d 69 6c 6c 69 73  tional 25 millis
9450: 65 63 6f 6e 64 73 20 77 69 74 68 20 65 61 63 68  econds with each
9460: 20 73 75 62 73 65 71 75 65 6e 74 20 72 65 74 72   subsequent retr
9470: 79 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f  y.  This.** opco
9480: 64 65 20 61 6c 6c 6f 77 73 20 74 68 65 73 65 20  de allows these 
9490: 74 77 6f 20 76 61 6c 75 65 73 20 28 31 30 20 72  two values (10 r
94a0: 65 74 72 69 65 73 20 61 6e 64 20 32 35 20 6d 69  etries and 25 mi
94b0: 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 64 65  lliseconds of de
94c0: 6c 61 79 29 0a 2a 2a 20 74 6f 20 62 65 20 61 64  lay).** to be ad
94d0: 6a 75 73 74 65 64 2e 20 20 54 68 65 20 76 61 6c  justed.  The val
94e0: 75 65 73 20 61 72 65 20 63 68 61 6e 67 65 64 20  ues are changed 
94f0: 66 6f 72 20 61 6c 6c 20 64 61 74 61 62 61 73 65  for all database
9500: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20   connections.** 
9510: 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20  within the same 
9520: 70 72 6f 63 65 73 73 2e 20 20 54 68 65 20 61 72  process.  The ar
9530: 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e  gument is a poin
9540: 74 65 72 20 74 6f 20 61 6e 20 61 72 72 61 79 20  ter to an array 
9550: 6f 66 20 74 77 6f 0a 2a 2a 20 69 6e 74 65 67 65  of two.** intege
9560: 72 73 20 77 68 65 72 65 20 74 68 65 20 66 69 72  rs where the fir
9570: 73 74 20 69 6e 74 65 67 65 72 20 69 20 74 68 65  st integer i the
9580: 20 6e 65 77 20 72 65 74 72 79 20 63 6f 75 6e 74   new retry count
9590: 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 0a   and the second.
95a0: 2a 2a 20 69 6e 74 65 67 65 72 20 69 73 20 74 68  ** integer is th
95b0: 65 20 64 65 6c 61 79 2e 20 20 49 66 20 65 69 74  e delay.  If eit
95c0: 68 65 72 20 69 6e 74 65 67 65 72 20 69 73 20 6e  her integer is n
95d0: 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68  egative, then th
95e0: 65 20 73 65 74 74 69 6e 67 0a 2a 2a 20 69 73 20  e setting.** is 
95f0: 6e 6f 74 20 63 68 61 6e 67 65 64 20 62 75 74 20  not changed but 
9600: 69 6e 73 74 65 61 64 20 74 68 65 20 70 72 69 6f  instead the prio
9610: 72 20 76 61 6c 75 65 20 6f 66 20 74 68 61 74 20  r value of that 
9620: 73 65 74 74 69 6e 67 20 69 73 20 77 72 69 74 74  setting is writt
9630: 65 6e 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 61  en.** into the a
9640: 72 72 61 79 20 65 6e 74 72 79 2c 20 61 6c 6c 6f  rray entry, allo
9650: 77 69 6e 67 20 74 68 65 20 63 75 72 72 65 6e 74  wing the current
9660: 20 72 65 74 72 79 20 73 65 74 74 69 6e 67 73 20   retry settings 
9670: 74 6f 20 62 65 0a 2a 2a 20 69 6e 74 65 72 72 6f  to be.** interro
9680: 67 61 74 65 64 2e 20 20 54 68 65 20 7a 44 62 4e  gated.  The zDbN
9690: 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69 73  ame parameter is
96a0: 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20   ignored..**.** 
96b0: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
96c0: 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c 5d 5d  TL_PERSIST_WAL]]
96d0: 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
96e0: 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57  _FCNTL_PERSIST_W
96f0: 41 4c 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73  AL] opcode is us
9700: 65 64 20 74 6f 20 73 65 74 20 6f 72 20 71 75 65  ed to set or que
9710: 72 79 20 74 68 65 0a 2a 2a 20 70 65 72 73 69 73  ry the.** persis
9720: 74 65 6e 74 20 5b 57 41 4c 20 7c 20 57 72 69 74  tent [WAL | Writ
9730: 65 20 41 68 65 61 64 20 4c 6f 67 5d 20 73 65 74  e Ahead Log] set
9740: 74 69 6e 67 2e 20 20 42 79 20 64 65 66 61 75 6c  ting.  By defaul
9750: 74 2c 20 74 68 65 20 61 75 78 69 6c 69 61 72 79  t, the auxiliary
9760: 0a 2a 2a 20 77 72 69 74 65 20 61 68 65 61 64 20  .** write ahead 
9770: 6c 6f 67 20 61 6e 64 20 73 68 61 72 65 64 20 6d  log and shared m
9780: 65 6d 6f 72 79 20 66 69 6c 65 73 20 75 73 65 64  emory files used
9790: 20 66 6f 72 20 74 72 61 6e 73 61 63 74 69 6f 6e   for transaction
97a0: 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 61 72 65 20   control.** are 
97b0: 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65  automatically de
97c0: 6c 65 74 65 64 20 77 68 65 6e 20 74 68 65 20 6c  leted when the l
97d0: 61 74 65 73 74 20 63 6f 6e 6e 65 63 74 69 6f 6e  atest connection
97e0: 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65   to the database
97f0: 0a 2a 2a 20 63 6c 6f 73 65 73 2e 20 20 53 65 74  .** closes.  Set
9800: 74 69 6e 67 20 70 65 72 73 69 73 74 65 6e 74 20  ting persistent 
9810: 57 41 4c 20 6d 6f 64 65 20 63 61 75 73 65 73 20  WAL mode causes 
9820: 74 68 6f 73 65 20 66 69 6c 65 73 20 74 6f 20 70  those files to p
9830: 65 72 73 69 73 74 20 61 66 74 65 72 0a 2a 2a 20  ersist after.** 
9840: 63 6c 6f 73 65 2e 20 20 50 65 72 73 69 73 74 69  close.  Persisti
9850: 6e 67 20 74 68 65 20 66 69 6c 65 73 20 69 73 20  ng the files is 
9860: 75 73 65 66 75 6c 20 77 68 65 6e 20 6f 74 68 65  useful when othe
9870: 72 20 70 72 6f 63 65 73 73 65 73 20 74 68 61 74  r processes that
9880: 20 64 6f 20 6e 6f 74 0a 2a 2a 20 68 61 76 65 20   do not.** have 
9890: 77 72 69 74 65 20 70 65 72 6d 69 73 73 69 6f 6e  write permission
98a0: 20 6f 6e 20 74 68 65 20 64 69 72 65 63 74 6f 72   on the director
98b0: 79 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  y containing the
98c0: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77   database file w
98d0: 61 6e 74 0a 2a 2a 20 74 6f 20 72 65 61 64 20 74  ant.** to read t
98e0: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
98f0: 2c 20 61 73 20 74 68 65 20 57 41 4c 20 61 6e 64  , as the WAL and
9900: 20 73 68 61 72 65 64 20 6d 65 6d 6f 72 79 20 66   shared memory f
9910: 69 6c 65 73 20 6d 75 73 74 20 65 78 69 73 74 0a  iles must exist.
9920: 2a 2a 20 69 6e 20 6f 72 64 65 72 20 66 6f 72 20  ** in order for 
9930: 74 68 65 20 64 61 74 61 62 61 73 65 20 74 6f 20  the database to 
9940: 62 65 20 72 65 61 64 61 62 6c 65 2e 20 20 54 68  be readable.  Th
9950: 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
9960: 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  er to.** [sqlite
9970: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
9980: 5d 20 66 6f 72 20 74 68 69 73 20 6f 70 63 6f 64  ] for this opcod
9990: 65 20 73 68 6f 75 6c 64 20 62 65 20 61 20 70 6f  e should be a po
99a0: 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65  inter to an inte
99b0: 67 65 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e 74  ger..** That int
99c0: 65 67 65 72 20 69 73 20 30 20 74 6f 20 64 69 73  eger is 0 to dis
99d0: 61 62 6c 65 20 70 65 72 73 69 73 74 65 6e 74 20  able persistent 
99e0: 57 41 4c 20 6d 6f 64 65 20 6f 72 20 31 20 74 6f  WAL mode or 1 to
99f0: 20 65 6e 61 62 6c 65 20 70 65 72 73 69 73 74 65   enable persiste
9a00: 6e 74 0a 2a 2a 20 57 41 4c 20 6d 6f 64 65 2e 20  nt.** WAL mode. 
9a10: 20 49 66 20 74 68 65 20 69 6e 74 65 67 65 72 20   If the integer 
9a20: 69 73 20 2d 31 2c 20 74 68 65 6e 20 69 74 20 69  is -1, then it i
9a30: 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69  s overwritten wi
9a40: 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a  th the current.*
9a50: 2a 20 57 41 4c 20 70 65 72 73 69 73 74 65 6e 63  * WAL persistenc
9a60: 65 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a  e setting..**.**
9a70: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
9a80: 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56  NTL_POWERSAFE_OV
9a90: 45 52 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68  ERWRITE]].** ^Th
9aa0: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
9ab0: 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52  POWERSAFE_OVERWR
9ac0: 49 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75  ITE] opcode is u
9ad0: 73 65 64 20 74 6f 20 73 65 74 20 6f 72 20 71 75  sed to set or qu
9ae0: 65 72 79 20 74 68 65 0a 2a 2a 20 70 65 72 73 69  ery the.** persi
9af0: 73 74 65 6e 74 20 22 70 6f 77 65 72 73 61 66 65  stent "powersafe
9b00: 2d 6f 76 65 72 77 72 69 74 65 22 20 6f 72 20 22  -overwrite" or "
9b10: 50 53 4f 57 22 20 73 65 74 74 69 6e 67 2e 20 20  PSOW" setting.  
9b20: 54 68 65 20 50 53 4f 57 20 73 65 74 74 69 6e 67  The PSOW setting
9b30: 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 65 73 20 74  .** determines t
9b40: 68 65 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  he [SQLITE_IOCAP
9b50: 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57  _POWERSAFE_OVERW
9b60: 52 49 54 45 5d 20 62 69 74 20 6f 66 20 74 68 65  RITE] bit of the
9b70: 0a 2a 2a 20 78 44 65 76 69 63 65 43 68 61 72 61  .** xDeviceChara
9b80: 63 74 65 72 69 73 74 69 63 73 20 6d 65 74 68 6f  cteristics metho
9b90: 64 73 2e 20 54 68 65 20 66 6f 75 72 74 68 20 70  ds. The fourth p
9ba0: 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b  arameter to.** [
9bb0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
9bc0: 74 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 73  trol()] for this
9bd0: 20 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 62   opcode should b
9be0: 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  e a pointer to a
9bf0: 6e 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68  n integer..** Th
9c00: 61 74 20 69 6e 74 65 67 65 72 20 69 73 20 30 20  at integer is 0 
9c10: 74 6f 20 64 69 73 61 62 6c 65 20 7a 65 72 6f 2d  to disable zero-
9c20: 64 61 6d 61 67 65 20 6d 6f 64 65 20 6f 72 20 31  damage mode or 1
9c30: 20 74 6f 20 65 6e 61 62 6c 65 20 7a 65 72 6f 2d   to enable zero-
9c40: 64 61 6d 61 67 65 0a 2a 2a 20 6d 6f 64 65 2e 20  damage.** mode. 
9c50: 20 49 66 20 74 68 65 20 69 6e 74 65 67 65 72 20   If the integer 
9c60: 69 73 20 2d 31 2c 20 74 68 65 6e 20 69 74 20 69  is -1, then it i
9c70: 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69  s overwritten wi
9c80: 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a  th the current.*
9c90: 2a 20 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f  * zero-damage mo
9ca0: 64 65 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a  de setting..**.*
9cb0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
9cc0: 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d 5d  CNTL_OVERWRITE]]
9cd0: 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
9ce0: 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45  _FCNTL_OVERWRITE
9cf0: 5d 20 6f 70 63 6f 64 65 20 69 73 20 69 6e 76 6f  ] opcode is invo
9d00: 6b 65 64 20 62 79 20 53 51 4c 69 74 65 20 61 66  ked by SQLite af
9d10: 74 65 72 20 6f 70 65 6e 69 6e 67 0a 2a 2a 20 61  ter opening.** a
9d20: 20 77 72 69 74 65 20 74 72 61 6e 73 61 63 74 69   write transacti
9d30: 6f 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74  on to indicate t
9d40: 68 61 74 2c 20 75 6e 6c 65 73 73 20 69 74 20 69  hat, unless it i
9d50: 73 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 66 6f  s rolled back fo
9d60: 72 20 73 6f 6d 65 0a 2a 2a 20 72 65 61 73 6f 6e  r some.** reason
9d70: 2c 20 74 68 65 20 65 6e 74 69 72 65 20 64 61 74  , the entire dat
9d80: 61 62 61 73 65 20 66 69 6c 65 20 77 69 6c 6c 20  abase file will 
9d90: 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e 20 62  be overwritten b
9da0: 79 20 74 68 65 20 63 75 72 72 65 6e 74 20 0a 2a  y the current .*
9db0: 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 54  * transaction. T
9dc0: 68 69 73 20 69 73 20 75 73 65 64 20 62 79 20 56  his is used by V
9dd0: 41 43 55 55 4d 20 6f 70 65 72 61 74 69 6f 6e 73  ACUUM operations
9de0: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
9df0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41  LITE_FCNTL_VFSNA
9e00: 4d 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  ME]].** ^The [SQ
9e10: 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41  LITE_FCNTL_VFSNA
9e20: 4d 45 5d 20 6f 70 63 6f 64 65 20 63 61 6e 20 62  ME] opcode can b
9e30: 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e  e used to obtain
9e40: 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 0a 2a 2a   the names of.**
9e50: 20 61 6c 6c 20 5b 56 46 53 65 73 5d 20 69 6e 20   all [VFSes] in 
9e60: 74 68 65 20 56 46 53 20 73 74 61 63 6b 2e 20 20  the VFS stack.  
9e70: 54 68 65 20 6e 61 6d 65 73 20 61 72 65 20 6f 66  The names are of
9e80: 20 61 6c 6c 20 56 46 53 20 73 68 69 6d 73 20 61   all VFS shims a
9e90: 6e 64 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20  nd the.** final 
9ea0: 62 6f 74 74 6f 6d 2d 6c 65 76 65 6c 20 56 46 53  bottom-level VFS
9eb0: 20 61 72 65 20 77 72 69 74 74 65 6e 20 69 6e 74   are written int
9ec0: 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65  o memory obtaine
9ed0: 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69  d from .** [sqli
9ee0: 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e  te3_malloc()] an
9ef0: 64 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  d the result is 
9f00: 73 74 6f 72 65 64 20 69 6e 20 74 68 65 20 63 68  stored in the ch
9f10: 61 72 2a 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20  ar* variable.** 
9f20: 74 68 61 74 20 74 68 65 20 66 6f 75 72 74 68 20  that the fourth 
9f30: 70 61 72 61 6d 65 74 65 72 20 6f 66 20 5b 73 71  parameter of [sq
9f40: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
9f50: 6f 6c 28 29 5d 20 70 6f 69 6e 74 73 20 74 6f 2e  ol()] points to.
9f60: 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 65 72 20 69  .** The caller i
9f70: 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f  s responsible fo
9f80: 72 20 66 72 65 65 69 6e 67 20 74 68 65 20 6d 65  r freeing the me
9f90: 6d 6f 72 79 20 77 68 65 6e 20 64 6f 6e 65 2e 20  mory when done. 
9fa0: 20 41 73 20 77 69 74 68 0a 2a 2a 20 61 6c 6c 20   As with.** all 
9fb0: 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 61 63 74  file-control act
9fc0: 69 6f 6e 73 2c 20 74 68 65 72 65 20 69 73 20 6e  ions, there is n
9fd0: 6f 20 67 75 61 72 61 6e 74 65 65 20 74 68 61 74  o guarantee that
9fe0: 20 74 68 69 73 20 77 69 6c 6c 20 61 63 74 75 61   this will actua
9ff0: 6c 6c 79 0a 2a 2a 20 64 6f 20 61 6e 79 74 68 69  lly.** do anythi
a000: 6e 67 2e 20 20 43 61 6c 6c 65 72 73 20 73 68 6f  ng.  Callers sho
a010: 75 6c 64 20 69 6e 69 74 69 61 6c 69 7a 65 20 74  uld initialize t
a020: 68 65 20 63 68 61 72 2a 20 76 61 72 69 61 62 6c  he char* variabl
a030: 65 20 74 6f 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70  e to a NULL.** p
a040: 6f 69 6e 74 65 72 20 69 6e 20 63 61 73 65 20 74  ointer in case t
a050: 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c  his file-control
a060: 20 69 73 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e   is not implemen
a070: 74 65 64 2e 20 20 54 68 69 73 20 66 69 6c 65 2d  ted.  This file-
a080: 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 69 73 20 69 6e  control.** is in
a090: 74 65 6e 64 65 64 20 66 6f 72 20 64 69 61 67 6e  tended for diagn
a0a0: 6f 73 74 69 63 20 75 73 65 20 6f 6e 6c 79 2e 0a  ostic use only..
a0b0: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
a0c0: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d  TE_FCNTL_PRAGMA]
a0d0: 5d 0a 2a 2a 20 5e 57 68 65 6e 65 76 65 72 20 61  ].** ^Whenever a
a0e0: 20 5b 50 52 41 47 4d 41 5d 20 73 74 61 74 65 6d   [PRAGMA] statem
a0f0: 65 6e 74 20 69 73 20 70 61 72 73 65 64 2c 20 61  ent is parsed, a
a100: 6e 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  n [SQLITE_FCNTL_
a110: 50 52 41 47 4d 41 5d 20 0a 2a 2a 20 66 69 6c 65  PRAGMA] .** file
a120: 20 63 6f 6e 74 72 6f 6c 20 69 73 20 73 65 6e 74   control is sent
a130: 20 74 6f 20 74 68 65 20 6f 70 65 6e 20 5b 73 71   to the open [sq
a140: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
a150: 63 74 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  ct corresponding
a160: 0a 2a 2a 20 74 6f 20 74 68 65 20 64 61 74 61 62  .** to the datab
a170: 61 73 65 20 66 69 6c 65 20 74 6f 20 77 68 69 63  ase file to whic
a180: 68 20 74 68 65 20 70 72 61 67 6d 61 20 73 74 61  h the pragma sta
a190: 74 65 6d 65 6e 74 20 72 65 66 65 72 73 2e 20 5e  tement refers. ^
a1a0: 54 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  The argument.** 
a1b0: 74 6f 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46  to the [SQLITE_F
a1c0: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c  CNTL_PRAGMA] fil
a1d0: 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 61 6e 20  e control is an 
a1e0: 61 72 72 61 79 20 6f 66 0a 2a 2a 20 70 6f 69 6e  array of.** poin
a1f0: 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20  ters to strings 
a200: 28 63 68 61 72 2a 2a 29 20 69 6e 20 77 68 69 63  (char**) in whic
a210: 68 20 74 68 65 20 73 65 63 6f 6e 64 20 65 6c 65  h the second ele
a220: 6d 65 6e 74 20 6f 66 20 74 68 65 20 61 72 72 61  ment of the arra
a230: 79 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65  y.** is the name
a240: 20 6f 66 20 74 68 65 20 70 72 61 67 6d 61 20 61   of the pragma a
a250: 6e 64 20 74 68 65 20 74 68 69 72 64 20 65 6c 65  nd the third ele
a260: 6d 65 6e 74 20 69 73 20 74 68 65 20 61 72 67 75  ment is the argu
a270: 6d 65 6e 74 20 74 6f 20 74 68 65 0a 2a 2a 20 70  ment to the.** p
a280: 72 61 67 6d 61 20 6f 72 20 4e 55 4c 4c 20 69 66  ragma or NULL if
a290: 20 74 68 65 20 70 72 61 67 6d 61 20 68 61 73 20   the pragma has 
a2a0: 6e 6f 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e 54  no argument.  ^T
a2b0: 68 65 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61  he handler for a
a2c0: 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e  n.** [SQLITE_FCN
a2d0: 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20  TL_PRAGMA] file 
a2e0: 63 6f 6e 74 72 6f 6c 20 63 61 6e 20 6f 70 74 69  control can opti
a2f0: 6f 6e 61 6c 6c 79 20 6d 61 6b 65 20 74 68 65 20  onally make the 
a300: 66 69 72 73 74 20 65 6c 65 6d 65 6e 74 0a 2a 2a  first element.**
a310: 20 6f 66 20 74 68 65 20 63 68 61 72 2a 2a 20 61   of the char** a
a320: 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 20 74 6f  rgument point to
a330: 20 61 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e   a string obtain
a340: 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
a350: 5f 6d 70 72 69 6e 74 66 28 29 5d 0a 2a 2a 20 6f  _mprintf()].** o
a360: 72 20 74 68 65 20 65 71 75 69 76 61 6c 65 6e 74  r the equivalent
a370: 20 61 6e 64 20 74 68 61 74 20 73 74 72 69 6e 67   and that string
a380: 20 77 69 6c 6c 20 62 65 63 6f 6d 65 20 74 68 65   will become the
a390: 20 72 65 73 75 6c 74 20 6f 66 20 74 68 65 20 70   result of the p
a3a0: 72 61 67 6d 61 20 6f 72 0a 2a 2a 20 74 68 65 20  ragma or.** the 
a3b0: 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 69 66  error message if
a3c0: 20 74 68 65 20 70 72 61 67 6d 61 20 66 61 69 6c   the pragma fail
a3d0: 73 2e 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53  s. ^If the.** [S
a3e0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47  QLITE_FCNTL_PRAG
a3f0: 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  MA] file control
a400: 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
a410: 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74 68 65 6e  _NOTFOUND], then
a420: 20 6e 6f 72 6d 61 6c 20 0a 2a 2a 20 5b 50 52 41   normal .** [PRA
a430: 47 4d 41 5d 20 70 72 6f 63 65 73 73 69 6e 67 20  GMA] processing 
a440: 63 6f 6e 74 69 6e 75 65 73 2e 20 20 5e 49 66 20  continues.  ^If 
a450: 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  the [SQLITE_FCNT
a460: 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c  L_PRAGMA].** fil
a470: 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e  e control return
a480: 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74  s [SQLITE_OK], t
a490: 68 65 6e 20 74 68 65 20 70 61 72 73 65 72 20 61  hen the parser a
a4a0: 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a  ssumes that the.
a4b0: 2a 2a 20 56 46 53 20 68 61 73 20 68 61 6e 64 6c  ** VFS has handl
a4c0: 65 64 20 74 68 65 20 50 52 41 47 4d 41 20 69 74  ed the PRAGMA it
a4d0: 73 65 6c 66 20 61 6e 64 20 74 68 65 20 70 61 72  self and the par
a4e0: 73 65 72 20 67 65 6e 65 72 61 74 65 73 20 61 20  ser generates a 
a4f0: 6e 6f 2d 6f 70 0a 2a 2a 20 70 72 65 70 61 72 65  no-op.** prepare
a500: 64 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 49  d statement.  ^I
a510: 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  f the [SQLITE_FC
a520: 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65  NTL_PRAGMA] file
a530: 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73   control returns
a540: 0a 2a 2a 20 61 6e 79 20 72 65 73 75 6c 74 20 63  .** any result c
a550: 6f 64 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b  ode other than [
a560: 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 5b 53  SQLITE_OK] or [S
a570: 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c  QLITE_NOTFOUND],
a580: 20 74 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74   that means.** t
a590: 68 61 74 20 74 68 65 20 56 46 53 20 65 6e 63 6f  hat the VFS enco
a5a0: 75 6e 74 65 72 65 64 20 61 6e 20 65 72 72 6f 72  untered an error
a5b0: 20 77 68 69 6c 65 20 68 61 6e 64 6c 69 6e 67 20   while handling 
a5c0: 74 68 65 20 5b 50 52 41 47 4d 41 5d 20 61 6e 64  the [PRAGMA] and
a5d0: 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c 61 74   the.** compilat
a5e0: 69 6f 6e 20 6f 66 20 74 68 65 20 50 52 41 47 4d  ion of the PRAGM
a5f0: 41 20 66 61 69 6c 73 20 77 69 74 68 20 61 6e 20  A fails with an 
a600: 65 72 72 6f 72 2e 20 20 5e 54 68 65 20 5b 53 51  error.  ^The [SQ
a610: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d  LITE_FCNTL_PRAGM
a620: 41 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72  A].** file contr
a630: 6f 6c 20 6f 63 63 75 72 73 20 61 74 20 74 68 65  ol occurs at the
a640: 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 70 72   beginning of pr
a650: 61 67 6d 61 20 73 74 61 74 65 6d 65 6e 74 20 61  agma statement a
a660: 6e 61 6c 79 73 69 73 20 61 6e 64 20 73 6f 0a 2a  nalysis and so.*
a670: 2a 20 69 74 20 69 73 20 61 62 6c 65 20 74 6f 20  * it is able to 
a680: 6f 76 65 72 72 69 64 65 20 62 75 69 6c 74 2d 69  override built-i
a690: 6e 20 5b 50 52 41 47 4d 41 5d 20 73 74 61 74 65  n [PRAGMA] state
a6a0: 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  ments..**.** <li
a6b0: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
a6c0: 42 55 53 59 48 41 4e 44 4c 45 52 5d 5d 0a 2a 2a  BUSYHANDLER]].**
a6d0: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43   ^The [SQLITE_FC
a6e0: 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52 5d  NTL_BUSYHANDLER]
a6f0: 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c  .** file-control
a700: 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65 64 20   may be invoked 
a710: 62 79 20 53 51 4c 69 74 65 20 6f 6e 20 74 68 65  by SQLite on the
a720: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 68   database file h
a730: 61 6e 64 6c 65 0a 2a 2a 20 73 68 6f 72 74 6c 79  andle.** shortly
a740: 20 61 66 74 65 72 20 69 74 20 69 73 20 6f 70 65   after it is ope
a750: 6e 65 64 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  ned in order to 
a760: 70 72 6f 76 69 64 65 20 61 20 63 75 73 74 6f 6d  provide a custom
a770: 20 56 46 53 20 77 69 74 68 20 61 63 63 65 73 73   VFS with access
a780: 0a 2a 2a 20 74 6f 20 74 68 65 20 63 6f 6e 6e 65  .** to the conne
a790: 63 74 69 6f 6e 73 20 62 75 73 79 2d 68 61 6e 64  ctions busy-hand
a7a0: 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20 54 68  ler callback. Th
a7b0: 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 66  e argument is of
a7c0: 20 74 79 70 65 20 28 76 6f 69 64 20 2a 2a 29 0a   type (void **).
a7d0: 2a 2a 20 2d 20 61 6e 20 61 72 72 61 79 20 6f 66  ** - an array of
a7e0: 20 74 77 6f 20 28 76 6f 69 64 20 2a 29 20 76 61   two (void *) va
a7f0: 6c 75 65 73 2e 20 54 68 65 20 66 69 72 73 74 20  lues. The first 
a800: 28 76 6f 69 64 20 2a 29 20 61 63 74 75 61 6c 6c  (void *) actuall
a810: 79 20 70 6f 69 6e 74 73 0a 2a 2a 20 74 6f 20 61  y points.** to a
a820: 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 79 70   function of typ
a830: 65 20 28 69 6e 74 20 28 2a 29 28 76 6f 69 64 20  e (int (*)(void 
a840: 2a 29 29 2e 20 49 6e 20 6f 72 64 65 72 20 74 6f  *)). In order to
a850: 20 69 6e 76 6f 6b 65 20 74 68 65 20 63 6f 6e 6e   invoke the conn
a860: 65 63 74 69 6f 6e 73 0a 2a 2a 20 62 75 73 79 2d  ections.** busy-
a870: 68 61 6e 64 6c 65 72 2c 20 74 68 69 73 20 66 75  handler, this fu
a880: 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 62 65  nction should be
a890: 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74 68   invoked with th
a8a0: 65 20 73 65 63 6f 6e 64 20 28 76 6f 69 64 20 2a  e second (void *
a8b0: 29 20 69 6e 0a 2a 2a 20 74 68 65 20 61 72 72 61  ) in.** the arra
a8c0: 79 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 61 72  y as the only ar
a8d0: 67 75 6d 65 6e 74 2e 20 49 66 20 69 74 20 72 65  gument. If it re
a8e0: 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20  turns non-zero, 
a8f0: 74 68 65 6e 20 74 68 65 20 6f 70 65 72 61 74 69  then the operati
a900: 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20  on.** should be 
a910: 72 65 74 72 69 65 64 2e 20 49 66 20 69 74 20 72  retried. If it r
a920: 65 74 75 72 6e 73 20 7a 65 72 6f 2c 20 74 68 65  eturns zero, the
a930: 20 63 75 73 74 6f 6d 20 56 46 53 20 73 68 6f 75   custom VFS shou
a940: 6c 64 20 61 62 61 6e 64 6f 6e 20 74 68 65 0a 2a  ld abandon the.*
a950: 2a 20 63 75 72 72 65 6e 74 20 6f 70 65 72 61 74  * current operat
a960: 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ion..**.** <li>[
a970: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45  [SQLITE_FCNTL_TE
a980: 4d 50 46 49 4c 45 4e 41 4d 45 5d 5d 0a 2a 2a 20  MPFILENAME]].** 
a990: 5e 41 70 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e  ^Application can
a9a0: 20 69 6e 76 6f 6b 65 20 74 68 65 20 5b 53 51 4c   invoke the [SQL
a9b0: 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49  ITE_FCNTL_TEMPFI
a9c0: 4c 45 4e 41 4d 45 5d 20 66 69 6c 65 2d 63 6f 6e  LENAME] file-con
a9d0: 74 72 6f 6c 0a 2a 2a 20 74 6f 20 68 61 76 65 20  trol.** to have 
a9e0: 53 51 4c 69 74 65 20 67 65 6e 65 72 61 74 65 20  SQLite generate 
a9f0: 61 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20 66  a.** temporary f
aa00: 69 6c 65 6e 61 6d 65 20 75 73 69 6e 67 20 74 68  ilename using th
aa10: 65 20 73 61 6d 65 20 61 6c 67 6f 72 69 74 68 6d  e same algorithm
aa20: 20 74 68 61 74 20 69 73 20 66 6f 6c 6c 6f 77 65   that is followe
aa30: 64 20 74 6f 20 67 65 6e 65 72 61 74 65 0a 2a 2a  d to generate.**
aa40: 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 6e   temporary filen
aa50: 61 6d 65 73 20 66 6f 72 20 54 45 4d 50 20 74 61  ames for TEMP ta
aa60: 62 6c 65 73 20 61 6e 64 20 6f 74 68 65 72 20 69  bles and other i
aa70: 6e 74 65 72 6e 61 6c 20 75 73 65 73 2e 20 20 54  nternal uses.  T
aa80: 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73  he.** argument s
aa90: 68 6f 75 6c 64 20 62 65 20 61 20 63 68 61 72 2a  hould be a char*
aaa0: 2a 20 77 68 69 63 68 20 77 69 6c 6c 20 62 65 20  * which will be 
aab0: 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20  filled with the 
aac0: 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 77 72 69 74  filename.** writ
aad0: 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20  ten into memory 
aae0: 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73  obtained from [s
aaf0: 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
ab00: 2e 20 20 54 68 65 20 63 61 6c 6c 65 72 20 73 68  .  The caller sh
ab10: 6f 75 6c 64 0a 2a 2a 20 69 6e 76 6f 6b 65 20 5b  ould.** invoke [
ab20: 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20  sqlite3_free()] 
ab30: 6f 6e 20 74 68 65 20 72 65 73 75 6c 74 20 74 6f  on the result to
ab40: 20 61 76 6f 69 64 20 61 20 6d 65 6d 6f 72 79 20   avoid a memory 
ab50: 6c 65 61 6b 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  leak..**.** <li>
ab60: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d  [[SQLITE_FCNTL_M
ab70: 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54 68  MAP_SIZE]].** Th
ab80: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
ab90: 4d 4d 41 50 5f 53 49 5a 45 5d 20 66 69 6c 65 20  MMAP_SIZE] file 
aba0: 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65 64 20  control is used 
abb0: 74 6f 20 71 75 65 72 79 20 6f 72 20 73 65 74 20  to query or set 
abc0: 74 68 65 0a 2a 2a 20 6d 61 78 69 6d 75 6d 20 6e  the.** maximum n
abd0: 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 74  umber of bytes t
abe0: 68 61 74 20 77 69 6c 6c 20 62 65 20 75 73 65 64  hat will be used
abf0: 20 66 6f 72 20 6d 65 6d 6f 72 79 2d 6d 61 70 70   for memory-mapp
ac00: 65 64 20 49 2f 4f 2e 0a 2a 2a 20 54 68 65 20 61  ed I/O..** The a
ac10: 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69  rgument is a poi
ac20: 6e 74 65 72 20 74 6f 20 61 20 76 61 6c 75 65 20  nter to a value 
ac30: 6f 66 20 74 79 70 65 20 73 71 6c 69 74 65 33 5f  of type sqlite3_
ac40: 69 6e 74 36 34 20 74 68 61 74 0a 2a 2a 20 69 73  int64 that.** is
ac50: 20 61 6e 20 61 64 76 69 73 6f 72 79 20 6d 61 78   an advisory max
ac60: 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 62  imum number of b
ac70: 79 74 65 73 20 69 6e 20 74 68 65 20 66 69 6c 65  ytes in the file
ac80: 20 74 6f 20 6d 65 6d 6f 72 79 20 6d 61 70 2e 20   to memory map. 
ac90: 20 54 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20   The.** pointer 
aca0: 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77  is overwritten w
acb0: 69 74 68 20 74 68 65 20 6f 6c 64 20 76 61 6c 75  ith the old valu
acc0: 65 2e 20 20 54 68 65 20 6c 69 6d 69 74 20 69 73  e.  The limit is
acd0: 20 6e 6f 74 20 63 68 61 6e 67 65 64 20 69 66 0a   not changed if.
ace0: 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 6f 72 69  ** the value ori
acf0: 67 69 6e 61 6c 6c 79 20 70 6f 69 6e 74 65 64 20  ginally pointed 
ad00: 74 6f 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20  to is negative, 
ad10: 61 6e 64 20 73 6f 20 74 68 65 20 63 75 72 72 65  and so the curre
ad20: 6e 74 20 6c 69 6d 69 74 20 0a 2a 2a 20 63 61 6e  nt limit .** can
ad30: 20 62 65 20 71 75 65 72 69 65 64 20 62 79 20 70   be queried by p
ad40: 61 73 73 69 6e 67 20 69 6e 20 61 20 70 6f 69 6e  assing in a poin
ad50: 74 65 72 20 74 6f 20 61 20 6e 65 67 61 74 69 76  ter to a negativ
ad60: 65 20 6e 75 6d 62 65 72 2e 20 20 54 68 69 73 0a  e number.  This.
ad70: 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20  ** file-control 
ad80: 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61 6c  is used internal
ad90: 6c 79 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20  ly to implement 
ada0: 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a  [PRAGMA mmap_siz
adb0: 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 2f 75 6c 3e 0a  e]..**.** </ul>.
adc0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
add0: 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54  E_FCNTL_LOCKSTAT
ade0: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  E               
adf0: 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
ae00: 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49  _GET_LOCKPROXYFI
ae10: 4c 45 20 20 20 20 20 20 20 20 20 20 20 20 20 32  LE             2
ae20: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
ae30: 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c  SET_LOCKPROXYFIL
ae40: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 33 0a  E             3.
ae50: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
ae60: 41 53 54 5f 45 52 52 4e 4f 20 20 20 20 20 20 20  AST_ERRNO       
ae70: 20 20 20 20 20 20 20 20 20 20 20 20 20 34 0a 23               4.#
ae80: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
ae90: 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 20 20 20  NTL_SIZE_HINT   
aea0: 20 20 20 20 20 20 20 20 20 20 20 20 35 0a 23 64              5.#d
aeb0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
aec0: 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 20 20 20  TL_CHUNK_SIZE   
aed0: 20 20 20 20 20 20 20 20 20 20 20 36 0a 23 64 65             6.#de
aee0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
aef0: 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 20 20  L_FILE_POINTER  
af00: 20 20 20 20 20 20 20 20 20 20 37 0a 23 64 65 66            7.#def
af10: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
af20: 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 20 20 20  _SYNC_OMITTED   
af30: 20 20 20 20 20 20 20 20 20 38 0a 23 64 65 66 69           8.#defi
af40: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
af50: 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 20 20  WIN32_AV_RETRY  
af60: 20 20 20 20 20 20 20 20 39 0a 23 64 65 66 69 6e          9.#defin
af70: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50  e SQLITE_FCNTL_P
af80: 45 52 53 49 53 54 5f 57 41 4c 20 20 20 20 20 20  ERSIST_WAL      
af90: 20 20 20 20 20 20 31 30 0a 23 64 65 66 69 6e 65        10.#define
afa0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56   SQLITE_FCNTL_OV
afb0: 45 52 57 52 49 54 45 20 20 20 20 20 20 20 20 20  ERWRITE         
afc0: 20 20 20 20 20 31 31 0a 23 64 65 66 69 6e 65 20       11.#define 
afd0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53  SQLITE_FCNTL_VFS
afe0: 4e 41 4d 45 20 20 20 20 20 20 20 20 20 20 20 20  NAME            
aff0: 20 20 20 20 31 32 0a 23 64 65 66 69 6e 65 20 53      12.#define S
b000: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45  QLITE_FCNTL_POWE
b010: 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 20  RSAFE_OVERWRITE 
b020: 20 20 20 31 33 0a 23 64 65 66 69 6e 65 20 53 51     13.#define SQ
b030: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d  LITE_FCNTL_PRAGM
b040: 41 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  A               
b050: 20 20 31 34 0a 23 64 65 66 69 6e 65 20 53 51 4c    14.#define SQL
b060: 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41  ITE_FCNTL_BUSYHA
b070: 4e 44 4c 45 52 20 20 20 20 20 20 20 20 20 20 20  NDLER           
b080: 20 31 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   15.#define SQLI
b090: 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c  TE_FCNTL_TEMPFIL
b0a0: 45 4e 41 4d 45 20 20 20 20 20 20 20 20 20 20 20  ENAME           
b0b0: 31 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  16.#define SQLIT
b0c0: 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a  E_FCNTL_MMAP_SIZ
b0d0: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31  E              1
b0e0: 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  8../*.** CAPI3RE
b0f0: 46 3a 20 4d 75 74 65 78 20 48 61 6e 64 6c 65 0a  F: Mutex Handle.
b100: 2a 2a 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78 20  **.** The mutex 
b110: 6d 6f 64 75 6c 65 20 77 69 74 68 69 6e 20 53 51  module within SQ
b120: 4c 69 74 65 20 64 65 66 69 6e 65 73 20 5b 73 71  Lite defines [sq
b130: 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 74 6f 20  lite3_mutex] to 
b140: 62 65 20 61 6e 0a 2a 2a 20 61 62 73 74 72 61 63  be an.** abstrac
b150: 74 20 74 79 70 65 20 66 6f 72 20 61 20 6d 75 74  t type for a mut
b160: 65 78 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20  ex object.  The 
b170: 53 51 4c 69 74 65 20 63 6f 72 65 20 6e 65 76 65  SQLite core neve
b180: 72 20 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74 68  r looks.** at th
b190: 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65  e internal repre
b1a0: 73 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20  sentation of an 
b1b0: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 2e  [sqlite3_mutex].
b1c0: 20 20 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61    It only.** dea
b1d0: 6c 73 20 77 69 74 68 20 70 6f 69 6e 74 65 72 73  ls with pointers
b1e0: 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
b1f0: 5f 6d 75 74 65 78 5d 20 6f 62 6a 65 63 74 2e 0a  _mutex] object..
b200: 2a 2a 0a 2a 2a 20 4d 75 74 65 78 65 73 20 61 72  **.** Mutexes ar
b210: 65 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 20  e created using 
b220: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61  [sqlite3_mutex_a
b230: 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65  lloc()]..*/.type
b240: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
b250: 65 33 5f 6d 75 74 65 78 20 73 71 6c 69 74 65 33  e3_mutex sqlite3
b260: 5f 6d 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43  _mutex;../*.** C
b270: 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65  API3REF: OS Inte
b280: 72 66 61 63 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a  rface Object.**.
b290: 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f  ** An instance o
b2a0: 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66  f the sqlite3_vf
b2b0: 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73  s object defines
b2c0: 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 62   the interface b
b2d0: 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 53 51  etween.** the SQ
b2e0: 4c 69 74 65 20 63 6f 72 65 20 61 6e 64 20 74 68  Lite core and th
b2f0: 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65  e underlying ope
b300: 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20  rating system.  
b310: 54 68 65 20 22 76 66 73 22 0a 2a 2a 20 69 6e 20  The "vfs".** in 
b320: 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
b330: 6f 62 6a 65 63 74 20 73 74 61 6e 64 73 20 66 6f  object stands fo
b340: 72 20 22 76 69 72 74 75 61 6c 20 66 69 6c 65 20  r "virtual file 
b350: 73 79 73 74 65 6d 22 2e 20 20 53 65 65 0a 2a 2a  system".  See.**
b360: 20 74 68 65 20 5b 56 46 53 20 7c 20 56 46 53 20   the [VFS | VFS 
b370: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66  documentation] f
b380: 6f 72 20 66 75 72 74 68 65 72 20 69 6e 66 6f 72  or further infor
b390: 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68  mation..**.** Th
b3a0: 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 69  e value of the i
b3b0: 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 69 73  Version field is
b3c0: 20 69 6e 69 74 69 61 6c 6c 79 20 31 20 62 75 74   initially 1 but
b3d0: 20 6d 61 79 20 62 65 20 6c 61 72 67 65 72 20 69   may be larger i
b3e0: 6e 0a 2a 2a 20 66 75 74 75 72 65 20 76 65 72 73  n.** future vers
b3f0: 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 20  ions of SQLite. 
b400: 20 41 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c   Additional fiel
b410: 64 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64  ds may be append
b420: 65 64 20 74 6f 20 74 68 69 73 0a 2a 2a 20 6f 62  ed to this.** ob
b430: 6a 65 63 74 20 77 68 65 6e 20 74 68 65 20 69 56  ject when the iV
b440: 65 72 73 69 6f 6e 20 76 61 6c 75 65 20 69 73 20  ersion value is 
b450: 69 6e 63 72 65 61 73 65 64 2e 20 20 4e 6f 74 65  increased.  Note
b460: 20 74 68 61 74 20 74 68 65 20 73 74 72 75 63 74   that the struct
b470: 75 72 65 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71  ure.** of the sq
b480: 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74  lite3_vfs object
b490: 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20   changes in the 
b4a0: 74 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 74 77  transaction betw
b4b0: 65 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65  een.** SQLite ve
b4c0: 72 73 69 6f 6e 20 33 2e 35 2e 39 20 61 6e 64 20  rsion 3.5.9 and 
b4d0: 33 2e 36 2e 30 20 61 6e 64 20 79 65 74 20 74 68  3.6.0 and yet th
b4e0: 65 20 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64  e iVersion field
b4f0: 20 77 61 73 20 6e 6f 74 0a 2a 2a 20 6d 6f 64 69   was not.** modi
b500: 66 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  fied..**.** The 
b510: 73 7a 4f 73 46 69 6c 65 20 66 69 65 6c 64 20 69  szOsFile field i
b520: 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  s the size of th
b530: 65 20 73 75 62 63 6c 61 73 73 65 64 20 5b 73 71  e subclassed [sq
b540: 6c 69 74 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73  lite3_file].** s
b550: 74 72 75 63 74 75 72 65 20 75 73 65 64 20 62 79  tructure used by
b560: 20 74 68 69 73 20 56 46 53 2e 20 20 6d 78 50 61   this VFS.  mxPa
b570: 74 68 6e 61 6d 65 20 69 73 20 74 68 65 20 6d 61  thname is the ma
b580: 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 0a  ximum length of.
b590: 2a 2a 20 61 20 70 61 74 68 6e 61 6d 65 20 69 6e  ** a pathname in
b5a0: 20 74 68 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a   this VFS..**.**
b5b0: 20 52 65 67 69 73 74 65 72 65 64 20 73 71 6c 69   Registered sqli
b5c0: 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 73 20  te3_vfs objects 
b5d0: 61 72 65 20 6b 65 70 74 20 6f 6e 20 61 20 6c 69  are kept on a li
b5e0: 6e 6b 65 64 20 6c 69 73 74 20 66 6f 72 6d 65 64  nked list formed
b5f0: 20 62 79 0a 2a 2a 20 74 68 65 20 70 4e 65 78 74   by.** the pNext
b600: 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 5b   pointer.  The [
b610: 73 71 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69  sqlite3_vfs_regi
b620: 73 74 65 72 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b  ster()].** and [
b630: 73 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 65  sqlite3_vfs_unre
b640: 67 69 73 74 65 72 28 29 5d 20 69 6e 74 65 72 66  gister()] interf
b650: 61 63 65 73 20 6d 61 6e 61 67 65 20 74 68 69 73  aces manage this
b660: 20 6c 69 73 74 0a 2a 2a 20 69 6e 20 61 20 74 68   list.** in a th
b670: 72 65 61 64 2d 73 61 66 65 20 77 61 79 2e 20 20  read-safe way.  
b680: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  The [sqlite3_vfs
b690: 5f 66 69 6e 64 28 29 5d 20 69 6e 74 65 72 66 61  _find()] interfa
b6a0: 63 65 0a 2a 2a 20 73 65 61 72 63 68 65 73 20 74  ce.** searches t
b6b0: 68 65 20 6c 69 73 74 2e 20 20 4e 65 69 74 68 65  he list.  Neithe
b6c0: 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  r the applicatio
b6d0: 6e 20 63 6f 64 65 20 6e 6f 72 20 74 68 65 20 56  n code nor the V
b6e0: 46 53 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  FS.** implementa
b6f0: 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 20  tion should use 
b700: 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65  the pNext pointe
b710: 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e 65  r..**.** The pNe
b720: 78 74 20 66 69 65 6c 64 20 69 73 20 74 68 65 20  xt field is the 
b730: 6f 6e 6c 79 20 66 69 65 6c 64 20 69 6e 20 74 68  only field in th
b740: 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a  e sqlite3_vfs.**
b750: 20 73 74 72 75 63 74 75 72 65 20 74 68 61 74 20   structure that 
b760: 53 51 4c 69 74 65 20 77 69 6c 6c 20 65 76 65 72  SQLite will ever
b770: 20 6d 6f 64 69 66 79 2e 20 20 53 51 4c 69 74 65   modify.  SQLite
b780: 20 77 69 6c 6c 20 6f 6e 6c 79 20 61 63 63 65 73   will only acces
b790: 73 0a 2a 2a 20 6f 72 20 6d 6f 64 69 66 79 20 74  s.** or modify t
b7a0: 68 69 73 20 66 69 65 6c 64 20 77 68 69 6c 65 20  his field while 
b7b0: 68 6f 6c 64 69 6e 67 20 61 20 70 61 72 74 69 63  holding a partic
b7c0: 75 6c 61 72 20 73 74 61 74 69 63 20 6d 75 74 65  ular static mute
b7d0: 78 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63  x..** The applic
b7e0: 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76  ation should nev
b7f0: 65 72 20 6d 6f 64 69 66 79 20 61 6e 79 74 68 69  er modify anythi
b800: 6e 67 20 77 69 74 68 69 6e 20 74 68 65 20 73 71  ng within the sq
b810: 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a  lite3_vfs.** obj
b820: 65 63 74 20 6f 6e 63 65 20 74 68 65 20 6f 62 6a  ect once the obj
b830: 65 63 74 20 68 61 73 20 62 65 65 6e 20 72 65 67  ect has been reg
b840: 69 73 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  istered..**.** T
b850: 68 65 20 7a 4e 61 6d 65 20 66 69 65 6c 64 20 68  he zName field h
b860: 6f 6c 64 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  olds the name of
b870: 20 74 68 65 20 56 46 53 20 6d 6f 64 75 6c 65 2e   the VFS module.
b880: 20 20 54 68 65 20 6e 61 6d 65 20 6d 75 73 74 0a    The name must.
b890: 2a 2a 20 62 65 20 75 6e 69 71 75 65 20 61 63 72  ** be unique acr
b8a0: 6f 73 73 20 61 6c 6c 20 56 46 53 20 6d 6f 64 75  oss all VFS modu
b8b0: 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c  les..**.** [[sql
b8c0: 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 5d  ite3_vfs.xOpen]]
b8d0: 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75 61 72  .** ^SQLite guar
b8e0: 61 6e 74 65 65 73 20 74 68 61 74 20 74 68 65 20  antees that the 
b8f0: 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65  zFilename parame
b900: 74 65 72 20 74 6f 20 78 4f 70 65 6e 0a 2a 2a 20  ter to xOpen.** 
b910: 69 73 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c  is either a NULL
b920: 20 70 6f 69 6e 74 65 72 20 6f 72 20 73 74 72 69   pointer or stri
b930: 6e 67 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66  ng obtained.** f
b940: 72 6f 6d 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d  rom xFullPathnam
b950: 65 28 29 20 77 69 74 68 20 61 6e 20 6f 70 74 69  e() with an opti
b960: 6f 6e 61 6c 20 73 75 66 66 69 78 20 61 64 64 65  onal suffix adde
b970: 64 2e 0a 2a 2a 20 5e 49 66 20 61 20 73 75 66 66  d..** ^If a suff
b980: 69 78 20 69 73 20 61 64 64 65 64 20 74 6f 20 74  ix is added to t
b990: 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72  he zFilename par
b9a0: 61 6d 65 74 65 72 2c 20 69 74 20 77 69 6c 6c 0a  ameter, it will.
b9b0: 2a 2a 20 63 6f 6e 73 69 73 74 20 6f 66 20 61 20  ** consist of a 
b9c0: 73 69 6e 67 6c 65 20 22 2d 22 20 63 68 61 72 61  single "-" chara
b9d0: 63 74 65 72 20 66 6f 6c 6c 6f 77 65 64 20 62 79  cter followed by
b9e0: 20 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 0a 2a 2a   no more than.**
b9f0: 20 31 31 20 61 6c 70 68 61 6e 75 6d 65 72 69 63   11 alphanumeric
ba00: 20 61 6e 64 2f 6f 72 20 22 2d 22 20 63 68 61 72   and/or "-" char
ba10: 61 63 74 65 72 73 2e 0a 2a 2a 20 5e 53 51 4c 69  acters..** ^SQLi
ba20: 74 65 20 66 75 72 74 68 65 72 20 67 75 61 72 61  te further guara
ba30: 6e 74 65 65 73 20 74 68 61 74 0a 2a 2a 20 74 68  ntees that.** th
ba40: 65 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65  e string will be
ba50: 20 76 61 6c 69 64 20 61 6e 64 20 75 6e 63 68 61   valid and uncha
ba60: 6e 67 65 64 20 75 6e 74 69 6c 20 78 43 6c 6f 73  nged until xClos
ba70: 65 28 29 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64  e() is.** called
ba80: 2e 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 65  . Because of the
ba90: 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e   previous senten
baa0: 63 65 2c 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69  ce,.** the [sqli
bab0: 74 65 33 5f 66 69 6c 65 5d 20 63 61 6e 20 73 61  te3_file] can sa
bac0: 66 65 6c 79 20 73 74 6f 72 65 20 61 20 70 6f 69  fely store a poi
bad0: 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 66  nter to the.** f
bae0: 69 6c 65 6e 61 6d 65 20 69 66 20 69 74 20 6e 65  ilename if it ne
baf0: 65 64 73 20 74 6f 20 72 65 6d 65 6d 62 65 72 20  eds to remember 
bb00: 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 66 6f 72  the filename for
bb10: 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a   some reason..**
bb20: 20 49 66 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d   If the zFilenam
bb30: 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78  e parameter to x
bb40: 4f 70 65 6e 20 69 73 20 61 20 4e 55 4c 4c 20 70  Open is a NULL p
bb50: 6f 69 6e 74 65 72 20 74 68 65 6e 20 78 4f 70 65  ointer then xOpe
bb60: 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 76 65 6e 74  n.** must invent
bb70: 20 69 74 73 20 6f 77 6e 20 74 65 6d 70 6f 72 61   its own tempora
bb80: 72 79 20 6e 61 6d 65 20 66 6f 72 20 74 68 65 20  ry name for the 
bb90: 66 69 6c 65 2e 20 20 5e 57 68 65 6e 65 76 65 72  file.  ^Whenever
bba0: 20 74 68 65 20 0a 2a 2a 20 78 46 69 6c 65 6e 61   the .** xFilena
bbb0: 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  me parameter is 
bbc0: 4e 55 4c 4c 20 69 74 20 77 69 6c 6c 20 61 6c 73  NULL it will als
bbd0: 6f 20 62 65 20 74 68 65 20 63 61 73 65 20 74 68  o be the case th
bbe0: 61 74 20 74 68 65 0a 2a 2a 20 66 6c 61 67 73 20  at the.** flags 
bbf0: 70 61 72 61 6d 65 74 65 72 20 77 69 6c 6c 20 69  parameter will i
bc00: 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f  nclude [SQLITE_O
bc10: 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53  PEN_DELETEONCLOS
bc20: 45 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c  E]..**.** The fl
bc30: 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ags argument to 
bc40: 78 4f 70 65 6e 28 29 20 69 6e 63 6c 75 64 65 73  xOpen() includes
bc50: 20 61 6c 6c 20 62 69 74 73 20 73 65 74 20 69 6e   all bits set in
bc60: 0a 2a 2a 20 74 68 65 20 66 6c 61 67 73 20 61 72  .** the flags ar
bc70: 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74  gument to [sqlit
bc80: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 20  e3_open_v2()].  
bc90: 4f 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6f  Or if [sqlite3_o
bca0: 70 65 6e 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71  pen()].** or [sq
bcb0: 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20  lite3_open16()] 
bcc0: 69 73 20 75 73 65 64 2c 20 74 68 65 6e 20 66 6c  is used, then fl
bcd0: 61 67 73 20 69 6e 63 6c 75 64 65 73 20 61 74 20  ags includes at 
bce0: 6c 65 61 73 74 0a 2a 2a 20 5b 53 51 4c 49 54 45  least.** [SQLITE
bcf0: 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d  _OPEN_READWRITE]
bd00: 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f   | [SQLITE_OPEN_
bd10: 43 52 45 41 54 45 5d 2e 20 0a 2a 2a 20 49 66 20  CREATE]. .** If 
bd20: 78 4f 70 65 6e 28 29 20 6f 70 65 6e 73 20 61 20  xOpen() opens a 
bd30: 66 69 6c 65 20 72 65 61 64 2d 6f 6e 6c 79 20 74  file read-only t
bd40: 68 65 6e 20 69 74 20 73 65 74 73 20 2a 70 4f 75  hen it sets *pOu
bd50: 74 46 6c 61 67 73 20 74 6f 0a 2a 2a 20 69 6e 63  tFlags to.** inc
bd60: 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45  lude [SQLITE_OPE
bd70: 4e 5f 52 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74  N_READONLY].  Ot
bd80: 68 65 72 20 62 69 74 73 20 69 6e 20 2a 70 4f 75  her bits in *pOu
bd90: 74 46 6c 61 67 73 20 6d 61 79 20 62 65 20 73 65  tFlags may be se
bda0: 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 53 51 4c 69 74  t..**.** ^(SQLit
bdb0: 65 20 77 69 6c 6c 20 61 6c 73 6f 20 61 64 64 20  e will also add 
bdc0: 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f  one of the follo
bdd0: 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68  wing flags to th
bde0: 65 20 78 4f 70 65 6e 28 29 0a 2a 2a 20 63 61 6c  e xOpen().** cal
bdf0: 6c 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20  l, depending on 
be00: 74 68 65 20 6f 62 6a 65 63 74 20 62 65 69 6e 67  the object being
be10: 20 6f 70 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c   opened:.**.** <
be20: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  ul>.** <li>  [SQ
be30: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44  LITE_OPEN_MAIN_D
be40: 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  B].** <li>  [SQL
be50: 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f  ITE_OPEN_MAIN_JO
be60: 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  URNAL].** <li>  
be70: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d  [SQLITE_OPEN_TEM
be80: 50 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  P_DB].** <li>  [
be90: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50  SQLITE_OPEN_TEMP
bea0: 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69  _JOURNAL].** <li
beb0: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
bec0: 54 52 41 4e 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a  TRANSIENT_DB].**
bed0: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
bee0: 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a  PEN_SUBJOURNAL].
bef0: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
bf00: 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55  _OPEN_MASTER_JOU
bf10: 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  RNAL].** <li>  [
bf20: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 5d  SQLITE_OPEN_WAL]
bf30: 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a  .** </ul>)^.**.*
bf40: 2a 20 54 68 65 20 66 69 6c 65 20 49 2f 4f 20 69  * The file I/O i
bf50: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 63 61  mplementation ca
bf60: 6e 20 75 73 65 20 74 68 65 20 6f 62 6a 65 63 74  n use the object
bf70: 20 74 79 70 65 20 66 6c 61 67 73 20 74 6f 0a 2a   type flags to.*
bf80: 2a 20 63 68 61 6e 67 65 20 74 68 65 20 77 61 79  * change the way
bf90: 20 69 74 20 64 65 61 6c 73 20 77 69 74 68 20 66   it deals with f
bfa0: 69 6c 65 73 2e 20 20 46 6f 72 20 65 78 61 6d 70  iles.  For examp
bfb0: 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69  le, an applicati
bfc0: 6f 6e 0a 2a 2a 20 74 68 61 74 20 64 6f 65 73 20  on.** that does 
bfd0: 6e 6f 74 20 63 61 72 65 20 61 62 6f 75 74 20 63  not care about c
bfe0: 72 61 73 68 20 72 65 63 6f 76 65 72 79 20 6f 72  rash recovery or
bff0: 20 72 6f 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20   rollback might 
c000: 6d 61 6b 65 0a 2a 2a 20 74 68 65 20 6f 70 65 6e  make.** the open
c010: 20 6f 66 20 61 20 6a 6f 75 72 6e 61 6c 20 66 69   of a journal fi
c020: 6c 65 20 61 20 6e 6f 2d 6f 70 2e 20 20 57 72 69  le a no-op.  Wri
c030: 74 65 73 20 74 6f 20 74 68 69 73 20 6a 6f 75 72  tes to this jour
c040: 6e 61 6c 20 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73  nal would.** als
c050: 6f 20 62 65 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64  o be no-ops, and
c060: 20 61 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20   any attempt to 
c070: 72 65 61 64 20 74 68 65 20 6a 6f 75 72 6e 61 6c  read the journal
c080: 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 0a 2a 2a   would return.**
c090: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 2e 20 20   SQLITE_IOERR.  
c0a0: 4f 72 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74  Or the implement
c0b0: 61 74 69 6f 6e 20 6d 69 67 68 74 20 72 65 63 6f  ation might reco
c0c0: 67 6e 69 7a 65 20 74 68 61 74 20 61 20 64 61 74  gnize that a dat
c0d0: 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 77 69  abase.** file wi
c0e0: 6c 6c 20 62 65 20 64 6f 69 6e 67 20 70 61 67 65  ll be doing page
c0f0: 2d 61 6c 69 67 6e 65 64 20 73 65 63 74 6f 72 20  -aligned sector 
c100: 72 65 61 64 73 20 61 6e 64 20 77 72 69 74 65 73  reads and writes
c110: 20 69 6e 20 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20   in a random.** 
c120: 6f 72 64 65 72 20 61 6e 64 20 73 65 74 20 75 70  order and set up
c130: 20 69 74 73 20 49 2f 4f 20 73 75 62 73 79 73 74   its I/O subsyst
c140: 65 6d 20 61 63 63 6f 72 64 69 6e 67 6c 79 2e 0a  em accordingly..
c150: 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 69 67  **.** SQLite mig
c160: 68 74 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20  ht also add one 
c170: 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  of the following
c180: 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f   flags to the xO
c190: 70 65 6e 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a  pen method:.**.*
c1a0: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b  * <ul>.** <li> [
c1b0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45  SQLITE_OPEN_DELE
c1c0: 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c  TEONCLOSE].** <l
c1d0: 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  i> [SQLITE_OPEN_
c1e0: 45 58 43 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f  EXCLUSIVE].** </
c1f0: 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53  ul>.**.** The [S
c200: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54  QLITE_OPEN_DELET
c210: 45 4f 4e 43 4c 4f 53 45 5d 20 66 6c 61 67 20 6d  EONCLOSE] flag m
c220: 65 61 6e 73 20 74 68 65 20 66 69 6c 65 20 73 68  eans the file sh
c230: 6f 75 6c 64 20 62 65 0a 2a 2a 20 64 65 6c 65 74  ould be.** delet
c240: 65 64 20 77 68 65 6e 20 69 74 20 69 73 20 63 6c  ed when it is cl
c250: 6f 73 65 64 2e 20 20 5e 54 68 65 20 5b 53 51 4c  osed.  ^The [SQL
c260: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f  ITE_OPEN_DELETEO
c270: 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20  NCLOSE].** will 
c280: 62 65 20 73 65 74 20 66 6f 72 20 54 45 4d 50 20  be set for TEMP 
c290: 64 61 74 61 62 61 73 65 73 20 61 6e 64 20 74 68  databases and th
c2a0: 65 69 72 20 6a 6f 75 72 6e 61 6c 73 2c 20 74 72  eir journals, tr
c2b0: 61 6e 73 69 65 6e 74 0a 2a 2a 20 64 61 74 61 62  ansient.** datab
c2c0: 61 73 65 73 2c 20 61 6e 64 20 73 75 62 6a 6f 75  ases, and subjou
c2d0: 72 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  rnals..**.** ^Th
c2e0: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45  e [SQLITE_OPEN_E
c2f0: 58 43 4c 55 53 49 56 45 5d 20 66 6c 61 67 20 69  XCLUSIVE] flag i
c300: 73 20 61 6c 77 61 79 73 20 75 73 65 64 20 69 6e  s always used in
c310: 20 63 6f 6e 6a 75 6e 63 74 69 6f 6e 0a 2a 2a 20   conjunction.** 
c320: 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45  with the [SQLITE
c330: 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 20 66 6c  _OPEN_CREATE] fl
c340: 61 67 2c 20 77 68 69 63 68 20 61 72 65 20 62 6f  ag, which are bo
c350: 74 68 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 61  th directly.** a
c360: 6e 61 6c 6f 67 6f 75 73 20 74 6f 20 74 68 65 20  nalogous to the 
c370: 4f 5f 45 58 43 4c 20 61 6e 64 20 4f 5f 43 52 45  O_EXCL and O_CRE
c380: 41 54 20 66 6c 61 67 73 20 6f 66 20 74 68 65 20  AT flags of the 
c390: 50 4f 53 49 58 20 6f 70 65 6e 28 29 0a 2a 2a 20  POSIX open().** 
c3a0: 41 50 49 2e 20 20 54 68 65 20 53 51 4c 49 54 45  API.  The SQLITE
c3b0: 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20  _OPEN_EXCLUSIVE 
c3c0: 66 6c 61 67 2c 20 77 68 65 6e 20 70 61 69 72 65  flag, when paire
c3d0: 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 53  d with the .** S
c3e0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
c3f0: 45 2c 20 69 73 20 75 73 65 64 20 74 6f 20 69 6e  E, is used to in
c400: 64 69 63 61 74 65 20 74 68 61 74 20 66 69 6c 65  dicate that file
c410: 20 73 68 6f 75 6c 64 20 61 6c 77 61 79 73 0a 2a   should always.*
c420: 2a 20 62 65 20 63 72 65 61 74 65 64 2c 20 61 6e  * be created, an
c430: 64 20 74 68 61 74 20 69 74 20 69 73 20 61 6e 20  d that it is an 
c440: 65 72 72 6f 72 20 69 66 20 69 74 20 61 6c 72 65  error if it alre
c450: 61 64 79 20 65 78 69 73 74 73 2e 0a 2a 2a 20 49  ady exists..** I
c460: 74 20 69 73 20 3c 69 3e 6e 6f 74 3c 2f 69 3e 20  t is <i>not</i> 
c470: 75 73 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65  used to indicate
c480: 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64   the file should
c490: 20 62 65 20 6f 70 65 6e 65 64 20 0a 2a 2a 20 66   be opened .** f
c4a0: 6f 72 20 65 78 63 6c 75 73 69 76 65 20 61 63 63  or exclusive acc
c4b0: 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 74 20 6c  ess..**.** ^At l
c4c0: 65 61 73 74 20 73 7a 4f 73 46 69 6c 65 20 62 79  east szOsFile by
c4d0: 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 20 61 72  tes of memory ar
c4e0: 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 53  e allocated by S
c4f0: 51 4c 69 74 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64  QLite.** to hold
c500: 20 74 68 65 20 20 5b 73 71 6c 69 74 65 33 5f 66   the  [sqlite3_f
c510: 69 6c 65 5d 20 73 74 72 75 63 74 75 72 65 20 70  ile] structure p
c520: 61 73 73 65 64 20 61 73 20 74 68 65 20 74 68 69  assed as the thi
c530: 72 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74  rd.** argument t
c540: 6f 20 78 4f 70 65 6e 2e 20 20 54 68 65 20 78 4f  o xOpen.  The xO
c550: 70 65 6e 20 6d 65 74 68 6f 64 20 64 6f 65 73 20  pen method does 
c560: 6e 6f 74 20 68 61 76 65 20 74 6f 0a 2a 2a 20 61  not have to.** a
c570: 6c 6c 6f 63 61 74 65 20 74 68 65 20 73 74 72 75  llocate the stru
c580: 63 74 75 72 65 3b 20 69 74 20 73 68 6f 75 6c 64  cture; it should
c590: 20 6a 75 73 74 20 66 69 6c 6c 20 69 74 20 69 6e   just fill it in
c5a0: 2e 20 20 4e 6f 74 65 20 74 68 61 74 0a 2a 2a 20  .  Note that.** 
c5b0: 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64  the xOpen method
c5c0: 20 6d 75 73 74 20 73 65 74 20 74 68 65 20 73 71   must set the sq
c5d0: 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68  lite3_file.pMeth
c5e0: 6f 64 73 20 74 6f 20 65 69 74 68 65 72 0a 2a 2a  ods to either.**
c5f0: 20 61 20 76 61 6c 69 64 20 5b 73 71 6c 69 74 65   a valid [sqlite
c600: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62  3_io_methods] ob
c610: 6a 65 63 74 20 6f 72 20 74 6f 20 4e 55 4c 4c 2e  ject or to NULL.
c620: 20 20 78 4f 70 65 6e 20 6d 75 73 74 20 64 6f 0a    xOpen must do.
c630: 2a 2a 20 74 68 69 73 20 65 76 65 6e 20 69 66 20  ** this even if 
c640: 74 68 65 20 6f 70 65 6e 20 66 61 69 6c 73 2e 20  the open fails. 
c650: 20 53 51 4c 69 74 65 20 65 78 70 65 63 74 73 20   SQLite expects 
c660: 74 68 61 74 20 74 68 65 20 73 71 6c 69 74 65 33  that the sqlite3
c670: 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 0a 2a  _file.pMethods.*
c680: 2a 20 65 6c 65 6d 65 6e 74 20 77 69 6c 6c 20 62  * element will b
c690: 65 20 76 61 6c 69 64 20 61 66 74 65 72 20 78 4f  e valid after xO
c6a0: 70 65 6e 20 72 65 74 75 72 6e 73 20 72 65 67 61  pen returns rega
c6b0: 72 64 6c 65 73 73 20 6f 66 20 74 68 65 20 73 75  rdless of the su
c6c0: 63 63 65 73 73 0a 2a 2a 20 6f 72 20 66 61 69 6c  ccess.** or fail
c6d0: 75 72 65 20 6f 66 20 74 68 65 20 78 4f 70 65 6e  ure of the xOpen
c6e0: 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73   call..**.** [[s
c6f0: 71 6c 69 74 65 33 5f 76 66 73 2e 78 41 63 63 65  qlite3_vfs.xAcce
c700: 73 73 5d 5d 0a 2a 2a 20 5e 54 68 65 20 66 6c 61  ss]].** ^The fla
c710: 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78  gs argument to x
c720: 41 63 63 65 73 73 28 29 20 6d 61 79 20 62 65 20  Access() may be 
c730: 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45  [SQLITE_ACCESS_E
c740: 58 49 53 54 53 5d 0a 2a 2a 20 74 6f 20 74 65 73  XISTS].** to tes
c750: 74 20 66 6f 72 20 74 68 65 20 65 78 69 73 74 65  t for the existe
c760: 6e 63 65 20 6f 66 20 61 20 66 69 6c 65 2c 20 6f  nce of a file, o
c770: 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53  r [SQLITE_ACCESS
c780: 5f 52 45 41 44 57 52 49 54 45 5d 20 74 6f 0a 2a  _READWRITE] to.*
c790: 2a 20 74 65 73 74 20 77 68 65 74 68 65 72 20 61  * test whether a
c7a0: 20 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c   file is readabl
c7b0: 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65 2c 20  e and writable, 
c7c0: 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53  or [SQLITE_ACCES
c7d0: 53 5f 52 45 41 44 5d 0a 2a 2a 20 74 6f 20 74 65  S_READ].** to te
c7e0: 73 74 20 77 68 65 74 68 65 72 20 61 20 66 69 6c  st whether a fil
c7f0: 65 20 69 73 20 61 74 20 6c 65 61 73 74 20 72 65  e is at least re
c800: 61 64 61 62 6c 65 2e 20 20 20 54 68 65 20 66 69  adable.   The fi
c810: 6c 65 20 63 61 6e 20 62 65 20 61 0a 2a 2a 20 64  le can be a.** d
c820: 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20  irectory..**.** 
c830: 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77  ^SQLite will alw
c840: 61 79 73 20 61 6c 6c 6f 63 61 74 65 20 61 74 20  ays allocate at 
c850: 6c 65 61 73 74 20 6d 78 50 61 74 68 6e 61 6d 65  least mxPathname
c860: 2b 31 20 62 79 74 65 73 20 66 6f 72 20 74 68 65  +1 bytes for the
c870: 0a 2a 2a 20 6f 75 74 70 75 74 20 62 75 66 66 65  .** output buffe
c880: 72 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 2e  r xFullPathname.
c890: 20 20 54 68 65 20 65 78 61 63 74 20 73 69 7a 65    The exact size
c8a0: 20 6f 66 20 74 68 65 20 6f 75 74 70 75 74 20 62   of the output b
c8b0: 75 66 66 65 72 0a 2a 2a 20 69 73 20 61 6c 73 6f  uffer.** is also
c8c0: 20 70 61 73 73 65 64 20 61 73 20 61 20 70 61 72   passed as a par
c8d0: 61 6d 65 74 65 72 20 74 6f 20 62 6f 74 68 20 20  ameter to both  
c8e0: 6d 65 74 68 6f 64 73 2e 20 49 66 20 74 68 65 20  methods. If the 
c8f0: 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a  output buffer.**
c900: 20 69 73 20 6e 6f 74 20 6c 61 72 67 65 20 65 6e   is not large en
c910: 6f 75 67 68 2c 20 5b 53 51 4c 49 54 45 5f 43 41  ough, [SQLITE_CA
c920: 4e 54 4f 50 45 4e 5d 20 73 68 6f 75 6c 64 20 62  NTOPEN] should b
c930: 65 20 72 65 74 75 72 6e 65 64 2e 20 53 69 6e 63  e returned. Sinc
c940: 65 20 74 68 69 73 20 69 73 0a 2a 2a 20 68 61 6e  e this is.** han
c950: 64 6c 65 64 20 61 73 20 61 20 66 61 74 61 6c 20  dled as a fatal 
c960: 65 72 72 6f 72 20 62 79 20 53 51 4c 69 74 65 2c  error by SQLite,
c970: 20 76 66 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74   vfs implementat
c980: 69 6f 6e 73 20 73 68 6f 75 6c 64 20 65 6e 64 65  ions should ende
c990: 61 76 6f 72 0a 2a 2a 20 74 6f 20 70 72 65 76 65  avor.** to preve
c9a0: 6e 74 20 74 68 69 73 20 62 79 20 73 65 74 74 69  nt this by setti
c9b0: 6e 67 20 6d 78 50 61 74 68 6e 61 6d 65 20 74 6f  ng mxPathname to
c9c0: 20 61 20 73 75 66 66 69 63 69 65 6e 74 6c 79 20   a sufficiently 
c9d0: 6c 61 72 67 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a  large value..**.
c9e0: 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65  ** The xRandomne
c9f0: 73 73 28 29 2c 20 78 53 6c 65 65 70 28 29 2c 20  ss(), xSleep(), 
ca00: 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 2c 20  xCurrentTime(), 
ca10: 61 6e 64 20 78 43 75 72 72 65 6e 74 54 69 6d 65  and xCurrentTime
ca20: 49 6e 74 36 34 28 29 0a 2a 2a 20 69 6e 74 65 72  Int64().** inter
ca30: 66 61 63 65 73 20 61 72 65 20 6e 6f 74 20 73 74  faces are not st
ca40: 72 69 63 74 6c 79 20 61 20 70 61 72 74 20 6f 66  rictly a part of
ca50: 20 74 68 65 20 66 69 6c 65 73 79 73 74 65 6d 2c   the filesystem,
ca60: 20 62 75 74 20 74 68 65 79 20 61 72 65 0a 2a 2a   but they are.**
ca70: 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65   included in the
ca80: 20 56 46 53 20 73 74 72 75 63 74 75 72 65 20 66   VFS structure f
ca90: 6f 72 20 63 6f 6d 70 6c 65 74 65 6e 65 73 73 2e  or completeness.
caa0: 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e  .** The xRandomn
cab0: 65 73 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 61  ess() function a
cac0: 74 74 65 6d 70 74 73 20 74 6f 20 72 65 74 75 72  ttempts to retur
cad0: 6e 20 6e 42 79 74 65 73 20 62 79 74 65 73 0a 2a  n nBytes bytes.*
cae0: 2a 20 6f 66 20 67 6f 6f 64 2d 71 75 61 6c 69 74  * of good-qualit
caf0: 79 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74  y randomness int
cb00: 6f 20 7a 4f 75 74 2e 20 20 54 68 65 20 72 65 74  o zOut.  The ret
cb10: 75 72 6e 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20  urn value is.** 
cb20: 74 68 65 20 61 63 74 75 61 6c 20 6e 75 6d 62 65  the actual numbe
cb30: 72 20 6f 66 20 62 79 74 65 73 20 6f 66 20 72 61  r of bytes of ra
cb40: 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65  ndomness obtaine
cb50: 64 2e 0a 2a 2a 20 54 68 65 20 78 53 6c 65 65 70  d..** The xSleep
cb60: 28 29 20 6d 65 74 68 6f 64 20 63 61 75 73 65 73  () method causes
cb70: 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 74 68 72   the calling thr
cb80: 65 61 64 20 74 6f 20 73 6c 65 65 70 20 66 6f 72  ead to sleep for
cb90: 20 61 74 0a 2a 2a 20 6c 65 61 73 74 20 74 68 65   at.** least the
cba0: 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 63 72 6f   number of micro
cbb0: 73 65 63 6f 6e 64 73 20 67 69 76 65 6e 2e 20 20  seconds given.  
cbc0: 5e 54 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d  ^The xCurrentTim
cbd0: 65 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65  e().** method re
cbe0: 74 75 72 6e 73 20 61 20 4a 75 6c 69 61 6e 20 44  turns a Julian D
cbf0: 61 79 20 4e 75 6d 62 65 72 20 66 6f 72 20 74 68  ay Number for th
cc00: 65 20 63 75 72 72 65 6e 74 20 64 61 74 65 20 61  e current date a
cc10: 6e 64 20 74 69 6d 65 20 61 73 0a 2a 2a 20 61 20  nd time as.** a 
cc20: 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76  floating point v
cc30: 61 6c 75 65 2e 0a 2a 2a 20 5e 54 68 65 20 78 43  alue..** ^The xC
cc40: 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28  urrentTimeInt64(
cc50: 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73  ) method returns
cc60: 2c 20 61 73 20 61 6e 20 69 6e 74 65 67 65 72 2c  , as an integer,
cc70: 20 74 68 65 20 4a 75 6c 69 61 6e 0a 2a 2a 20 44   the Julian.** D
cc80: 61 79 20 4e 75 6d 62 65 72 20 6d 75 6c 74 69 70  ay Number multip
cc90: 6c 69 65 64 20 62 79 20 38 36 34 30 30 30 30 30  lied by 86400000
cca0: 20 28 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20   (the number of 
ccb0: 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 69 6e 20  milliseconds in 
ccc0: 0a 2a 2a 20 61 20 32 34 2d 68 6f 75 72 20 64 61  .** a 24-hour da
ccd0: 79 29 2e 20 20 0a 2a 2a 20 5e 53 51 4c 69 74 65  y).  .** ^SQLite
cce0: 20 77 69 6c 6c 20 75 73 65 20 74 68 65 20 78 43   will use the xC
ccf0: 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28  urrentTimeInt64(
cd00: 29 20 6d 65 74 68 6f 64 20 74 6f 20 67 65 74 20  ) method to get 
cd10: 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 64  the current.** d
cd20: 61 74 65 20 61 6e 64 20 74 69 6d 65 20 69 66 20  ate and time if 
cd30: 74 68 61 74 20 6d 65 74 68 6f 64 20 69 73 20 61  that method is a
cd40: 76 61 69 6c 61 62 6c 65 20 28 69 66 20 69 56 65  vailable (if iVe
cd50: 72 73 69 6f 6e 20 69 73 20 32 20 6f 72 20 0a 2a  rsion is 2 or .*
cd60: 2a 20 67 72 65 61 74 65 72 20 61 6e 64 20 74 68  * greater and th
cd70: 65 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74  e function point
cd80: 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 29 20  er is not NULL) 
cd90: 61 6e 64 20 77 69 6c 6c 20 66 61 6c 6c 20 62 61  and will fall ba
cda0: 63 6b 0a 2a 2a 20 74 6f 20 78 43 75 72 72 65 6e  ck.** to xCurren
cdb0: 74 54 69 6d 65 28 29 20 69 66 20 78 43 75 72 72  tTime() if xCurr
cdc0: 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 69  entTimeInt64() i
cdd0: 73 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a  s unavailable..*
cde0: 2a 0a 2a 2a 20 5e 54 68 65 20 78 53 65 74 53 79  *.** ^The xSetSy
cdf0: 73 74 65 6d 43 61 6c 6c 28 29 2c 20 78 47 65 74  stemCall(), xGet
ce00: 53 79 73 74 65 6d 43 61 6c 6c 28 29 2c 20 61 6e  SystemCall(), an
ce10: 64 20 78 4e 65 73 74 53 79 73 74 65 6d 43 61 6c  d xNestSystemCal
ce20: 6c 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  l() interfaces.*
ce30: 2a 20 61 72 65 20 6e 6f 74 20 75 73 65 64 20 62  * are not used b
ce40: 79 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72  y the SQLite cor
ce50: 65 2e 20 20 54 68 65 73 65 20 6f 70 74 69 6f 6e  e.  These option
ce60: 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  al interfaces ar
ce70: 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 62 79  e provided.** by
ce80: 20 73 6f 6d 65 20 56 46 53 65 73 20 74 6f 20 66   some VFSes to f
ce90: 61 63 69 6c 69 74 61 74 65 20 74 65 73 74 69 6e  acilitate testin
cea0: 67 20 6f 66 20 74 68 65 20 56 46 53 20 63 6f 64  g of the VFS cod
ceb0: 65 2e 20 42 79 20 6f 76 65 72 72 69 64 69 6e 67  e. By overriding
cec0: 20 0a 2a 2a 20 73 79 73 74 65 6d 20 63 61 6c 6c   .** system call
ced0: 73 20 77 69 74 68 20 66 75 6e 63 74 69 6f 6e 73  s with functions
cee0: 20 75 6e 64 65 72 20 69 74 73 20 63 6f 6e 74 72   under its contr
cef0: 6f 6c 2c 20 61 20 74 65 73 74 20 70 72 6f 67 72  ol, a test progr
cf00: 61 6d 20 63 61 6e 0a 2a 2a 20 73 69 6d 75 6c 61  am can.** simula
cf10: 74 65 20 66 61 75 6c 74 73 20 61 6e 64 20 65 72  te faults and er
cf20: 72 6f 72 20 63 6f 6e 64 69 74 69 6f 6e 73 20 74  ror conditions t
cf30: 68 61 74 20 77 6f 75 6c 64 20 6f 74 68 65 72 77  hat would otherw
cf40: 69 73 65 20 62 65 20 64 69 66 66 69 63 75 6c 74  ise be difficult
cf50: 0a 2a 2a 20 6f 72 20 69 6d 70 6f 73 73 69 62 6c  .** or impossibl
cf60: 65 20 74 6f 20 69 6e 64 75 63 65 2e 20 20 54 68  e to induce.  Th
cf70: 65 20 73 65 74 20 6f 66 20 73 79 73 74 65 6d 20  e set of system 
cf80: 63 61 6c 6c 73 20 74 68 61 74 20 63 61 6e 20 62  calls that can b
cf90: 65 20 6f 76 65 72 72 69 64 64 65 6e 0a 2a 2a 20  e overridden.** 
cfa0: 76 61 72 69 65 73 20 66 72 6f 6d 20 6f 6e 65 20  varies from one 
cfb0: 56 46 53 20 74 6f 20 61 6e 6f 74 68 65 72 2c 20  VFS to another, 
cfc0: 61 6e 64 20 66 72 6f 6d 20 6f 6e 65 20 76 65 72  and from one ver
cfd0: 73 69 6f 6e 20 6f 66 20 74 68 65 20 73 61 6d 65  sion of the same
cfe0: 20 56 46 53 20 74 6f 20 74 68 65 0a 2a 2a 20 6e   VFS to the.** n
cff0: 65 78 74 2e 20 20 41 70 70 6c 69 63 61 74 69 6f  ext.  Applicatio
d000: 6e 73 20 74 68 61 74 20 75 73 65 20 74 68 65 73  ns that use thes
d010: 65 20 69 6e 74 65 72 66 61 63 65 73 20 6d 75 73  e interfaces mus
d020: 74 20 62 65 20 70 72 65 70 61 72 65 64 20 66 6f  t be prepared fo
d030: 72 20 61 6e 79 0a 2a 2a 20 6f 72 20 61 6c 6c 20  r any.** or all 
d040: 6f 66 20 74 68 65 73 65 20 69 6e 74 65 72 66 61  of these interfa
d050: 63 65 73 20 74 6f 20 62 65 20 4e 55 4c 4c 20 6f  ces to be NULL o
d060: 72 20 66 6f 72 20 74 68 65 69 72 20 62 65 68 61  r for their beha
d070: 76 69 6f 72 20 74 6f 20 63 68 61 6e 67 65 0a 2a  vior to change.*
d080: 2a 20 66 72 6f 6d 20 6f 6e 65 20 72 65 6c 65 61  * from one relea
d090: 73 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 20  se to the next. 
d0a0: 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 75   Applications mu
d0b0: 73 74 20 6e 6f 74 20 61 74 74 65 6d 70 74 20 74  st not attempt t
d0c0: 6f 20 61 63 63 65 73 73 0a 2a 2a 20 61 6e 79 20  o access.** any 
d0d0: 6f 66 20 74 68 65 73 65 20 6d 65 74 68 6f 64 73  of these methods
d0e0: 20 69 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e   if the iVersion
d0f0: 20 6f 66 20 74 68 65 20 56 46 53 20 69 73 20 6c   of the VFS is l
d100: 65 73 73 20 74 68 61 6e 20 33 2e 0a 2a 2f 0a 74  ess than 3..*/.t
d110: 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
d120: 6c 69 74 65 33 5f 76 66 73 20 73 71 6c 69 74 65  lite3_vfs sqlite
d130: 33 5f 76 66 73 3b 0a 74 79 70 65 64 65 66 20 76  3_vfs;.typedef v
d140: 6f 69 64 20 28 2a 73 71 6c 69 74 65 33 5f 73 79  oid (*sqlite3_sy
d150: 73 63 61 6c 6c 5f 70 74 72 29 28 76 6f 69 64 29  scall_ptr)(void)
d160: 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  ;.struct sqlite3
d170: 5f 76 66 73 20 7b 0a 20 20 69 6e 74 20 69 56 65  _vfs {.  int iVe
d180: 72 73 69 6f 6e 3b 20 20 20 20 20 20 20 20 20 20  rsion;          
d190: 20 20 2f 2a 20 53 74 72 75 63 74 75 72 65 20 76    /* Structure v
d1a0: 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 28 63  ersion number (c
d1b0: 75 72 72 65 6e 74 6c 79 20 33 29 20 2a 2f 0a 20  urrently 3) */. 
d1c0: 20 69 6e 74 20 73 7a 4f 73 46 69 6c 65 3b 20 20   int szOsFile;  
d1d0: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 69 7a            /* Siz
d1e0: 65 20 6f 66 20 73 75 62 63 6c 61 73 73 65 64 20  e of subclassed 
d1f0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 2a 2f 0a  sqlite3_file */.
d200: 20 20 69 6e 74 20 6d 78 50 61 74 68 6e 61 6d 65    int mxPathname
d210: 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61  ;          /* Ma
d220: 78 69 6d 75 6d 20 66 69 6c 65 20 70 61 74 68 6e  ximum file pathn
d230: 61 6d 65 20 6c 65 6e 67 74 68 20 2a 2f 0a 20 20  ame length */.  
d240: 73 71 6c 69 74 65 33 5f 76 66 73 20 2a 70 4e 65  sqlite3_vfs *pNe
d250: 78 74 3b 20 20 20 20 20 20 2f 2a 20 4e 65 78 74  xt;      /* Next
d260: 20 72 65 67 69 73 74 65 72 65 64 20 56 46 53 20   registered VFS 
d270: 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
d280: 2a 7a 4e 61 6d 65 3b 20 20 20 20 20 20 20 2f 2a  *zName;       /*
d290: 20 4e 61 6d 65 20 6f 66 20 74 68 69 73 20 76 69   Name of this vi
d2a0: 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65  rtual file syste
d2b0: 6d 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70  m */.  void *pAp
d2c0: 70 44 61 74 61 3b 20 20 20 20 20 20 20 20 20 20  pData;          
d2d0: 2f 2a 20 50 6f 69 6e 74 65 72 20 74 6f 20 61 70  /* Pointer to ap
d2e0: 70 6c 69 63 61 74 69 6f 6e 2d 73 70 65 63 69 66  plication-specif
d2f0: 69 63 20 64 61 74 61 20 2a 2f 0a 20 20 69 6e 74  ic data */.  int
d300: 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 65   (*xOpen)(sqlite
d310: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
d320: 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74  ar *zName, sqlit
d330: 65 33 5f 66 69 6c 65 2a 2c 0a 20 20 20 20 20 20  e3_file*,.      
d340: 20 20 20 20 20 20 20 20 20 69 6e 74 20 66 6c 61           int fla
d350: 67 73 2c 20 69 6e 74 20 2a 70 4f 75 74 46 6c 61  gs, int *pOutFla
d360: 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65  gs);.  int (*xDe
d370: 6c 65 74 65 29 28 73 71 6c 69 74 65 33 5f 76 66  lete)(sqlite3_vf
d380: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
d390: 7a 4e 61 6d 65 2c 20 69 6e 74 20 73 79 6e 63 44  zName, int syncD
d3a0: 69 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78 41 63  ir);.  int (*xAc
d3b0: 63 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66  cess)(sqlite3_vf
d3c0: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
d3d0: 7a 4e 61 6d 65 2c 20 69 6e 74 20 66 6c 61 67 73  zName, int flags
d3e0: 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b  , int *pResOut);
d3f0: 0a 20 20 69 6e 74 20 28 2a 78 46 75 6c 6c 50 61  .  int (*xFullPa
d400: 74 68 6e 61 6d 65 29 28 73 71 6c 69 74 65 33 5f  thname)(sqlite3_
d410: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
d420: 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f 75   *zName, int nOu
d430: 74 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a  t, char *zOut);.
d440: 20 20 76 6f 69 64 20 2a 28 2a 78 44 6c 4f 70 65    void *(*xDlOpe
d450: 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  n)(sqlite3_vfs*,
d460: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69   const char *zFi
d470: 6c 65 6e 61 6d 65 29 3b 0a 20 20 76 6f 69 64 20  lename);.  void 
d480: 28 2a 78 44 6c 45 72 72 6f 72 29 28 73 71 6c 69  (*xDlError)(sqli
d490: 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42  te3_vfs*, int nB
d4a0: 79 74 65 2c 20 63 68 61 72 20 2a 7a 45 72 72 4d  yte, char *zErrM
d4b0: 73 67 29 3b 0a 20 20 76 6f 69 64 20 28 2a 28 2a  sg);.  void (*(*
d4c0: 78 44 6c 53 79 6d 29 28 73 71 6c 69 74 65 33 5f  xDlSym)(sqlite3_
d4d0: 76 66 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73  vfs*,void*, cons
d4e0: 74 20 63 68 61 72 20 2a 7a 53 79 6d 62 6f 6c 29  t char *zSymbol)
d4f0: 29 28 76 6f 69 64 29 3b 0a 20 20 76 6f 69 64 20  )(void);.  void 
d500: 28 2a 78 44 6c 43 6c 6f 73 65 29 28 73 71 6c 69  (*xDlClose)(sqli
d510: 74 65 33 5f 76 66 73 2a 2c 20 76 6f 69 64 2a 29  te3_vfs*, void*)
d520: 3b 0a 20 20 69 6e 74 20 28 2a 78 52 61 6e 64 6f  ;.  int (*xRando
d530: 6d 6e 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76  mness)(sqlite3_v
d540: 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20  fs*, int nByte, 
d550: 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 69  char *zOut);.  i
d560: 6e 74 20 28 2a 78 53 6c 65 65 70 29 28 73 71 6c  nt (*xSleep)(sql
d570: 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d  ite3_vfs*, int m
d580: 69 63 72 6f 73 65 63 6f 6e 64 73 29 3b 0a 20 20  icroseconds);.  
d590: 69 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69  int (*xCurrentTi
d5a0: 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  me)(sqlite3_vfs*
d5b0: 2c 20 64 6f 75 62 6c 65 2a 29 3b 0a 20 20 69 6e  , double*);.  in
d5c0: 74 20 28 2a 78 47 65 74 4c 61 73 74 45 72 72 6f  t (*xGetLastErro
d5d0: 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  r)(sqlite3_vfs*,
d5e0: 20 69 6e 74 2c 20 63 68 61 72 20 2a 29 3b 0a 20   int, char *);. 
d5f0: 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74   /*.  ** The met
d600: 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69  hods above are i
d610: 6e 20 76 65 72 73 69 6f 6e 20 31 20 6f 66 20 74  n version 1 of t
d620: 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62  he sqlite_vfs ob
d630: 6a 65 63 74 0a 20 20 2a 2a 20 64 65 66 69 6e 69  ject.  ** defini
d640: 74 69 6f 6e 2e 20 20 54 68 6f 73 65 20 74 68 61  tion.  Those tha
d650: 74 20 66 6f 6c 6c 6f 77 20 61 72 65 20 61 64 64  t follow are add
d660: 65 64 20 69 6e 20 76 65 72 73 69 6f 6e 20 32 20  ed in version 2 
d670: 6f 72 20 6c 61 74 65 72 0a 20 20 2a 2f 0a 20 20  or later.  */.  
d680: 69 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69  int (*xCurrentTi
d690: 6d 65 49 6e 74 36 34 29 28 73 71 6c 69 74 65 33  meInt64)(sqlite3
d6a0: 5f 76 66 73 2a 2c 20 73 71 6c 69 74 65 33 5f 69  _vfs*, sqlite3_i
d6b0: 6e 74 36 34 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a  nt64*);.  /*.  *
d6c0: 2a 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62  * The methods ab
d6d0: 6f 76 65 20 61 72 65 20 69 6e 20 76 65 72 73 69  ove are in versi
d6e0: 6f 6e 73 20 31 20 61 6e 64 20 32 20 6f 66 20 74  ons 1 and 2 of t
d6f0: 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62  he sqlite_vfs ob
d700: 6a 65 63 74 2e 0a 20 20 2a 2a 20 54 68 6f 73 65  ject..  ** Those
d710: 20 62 65 6c 6f 77 20 61 72 65 20 66 6f 72 20 76   below are for v
d720: 65 72 73 69 6f 6e 20 33 20 61 6e 64 20 67 72 65  ersion 3 and gre
d730: 61 74 65 72 2e 0a 20 20 2a 2f 0a 20 20 69 6e 74  ater..  */.  int
d740: 20 28 2a 78 53 65 74 53 79 73 74 65 6d 43 61 6c   (*xSetSystemCal
d750: 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  l)(sqlite3_vfs*,
d760: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
d770: 6d 65 2c 20 73 71 6c 69 74 65 33 5f 73 79 73 63  me, sqlite3_sysc
d780: 61 6c 6c 5f 70 74 72 29 3b 0a 20 20 73 71 6c 69  all_ptr);.  sqli
d790: 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 20  te3_syscall_ptr 
d7a0: 28 2a 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c  (*xGetSystemCall
d7b0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
d7c0: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
d7d0: 65 29 3b 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  e);.  const char
d7e0: 20 2a 28 2a 78 4e 65 78 74 53 79 73 74 65 6d 43   *(*xNextSystemC
d7f0: 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73  all)(sqlite3_vfs
d800: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
d810: 4e 61 6d 65 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a  Name);.  /*.  **
d820: 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f   The methods abo
d830: 76 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f  ve are in versio
d840: 6e 73 20 31 20 74 68 72 6f 75 67 68 20 33 20 6f  ns 1 through 3 o
d850: 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76 66 73  f the sqlite_vfs
d860: 20 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a 20 4e 65   object..  ** Ne
d870: 77 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20  w fields may be 
d880: 61 70 70 65 6e 64 65 64 20 69 6e 20 66 69 67 75  appended in figu
d890: 72 65 20 76 65 72 73 69 6f 6e 73 2e 20 20 54 68  re versions.  Th
d8a0: 65 20 69 56 65 72 73 69 6f 6e 0a 20 20 2a 2a 20  e iVersion.  ** 
d8b0: 76 61 6c 75 65 20 77 69 6c 6c 20 69 6e 63 72 65  value will incre
d8c0: 6d 65 6e 74 20 77 68 65 6e 65 76 65 72 20 74 68  ment whenever th
d8d0: 69 73 20 68 61 70 70 65 6e 73 2e 20 0a 20 20 2a  is happens. .  *
d8e0: 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.};../*.** CAPI
d8f0: 33 52 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20  3REF: Flags for 
d900: 74 68 65 20 78 41 63 63 65 73 73 20 56 46 53 20  the xAccess VFS 
d910: 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65  method.**.** The
d920: 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74  se integer const
d930: 61 6e 74 73 20 63 61 6e 20 62 65 20 75 73 65 64  ants can be used
d940: 20 61 73 20 74 68 65 20 74 68 69 72 64 20 70 61   as the third pa
d950: 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68  rameter to.** th
d960: 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64  e xAccess method
d970: 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f   of an [sqlite3_
d980: 76 66 73 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68  vfs] object.  Th
d990: 65 79 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20  ey determine.** 
d9a0: 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 70 65 72  what kind of per
d9b0: 6d 69 73 73 69 6f 6e 73 20 74 68 65 20 78 41 63  missions the xAc
d9c0: 63 65 73 73 20 6d 65 74 68 6f 64 20 69 73 20 6c  cess method is l
d9d0: 6f 6f 6b 69 6e 67 20 66 6f 72 2e 0a 2a 2a 20 57  ooking for..** W
d9e0: 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53  ith SQLITE_ACCES
d9f0: 53 5f 45 58 49 53 54 53 2c 20 74 68 65 20 78 41  S_EXISTS, the xA
da00: 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20  ccess method.** 
da10: 73 69 6d 70 6c 79 20 63 68 65 63 6b 73 20 77 68  simply checks wh
da20: 65 74 68 65 72 20 74 68 65 20 66 69 6c 65 20 65  ether the file e
da30: 78 69 73 74 73 2e 0a 2a 2a 20 57 69 74 68 20 53  xists..** With S
da40: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
da50: 44 57 52 49 54 45 2c 20 74 68 65 20 78 41 63 63  DWRITE, the xAcc
da60: 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68  ess method.** ch
da70: 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65  ecks whether the
da80: 20 6e 61 6d 65 64 20 64 69 72 65 63 74 6f 72 79   named directory
da90: 20 69 73 20 62 6f 74 68 20 72 65 61 64 61 62 6c   is both readabl
daa0: 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65 0a 2a  e and writable.*
dab0: 2a 20 28 69 6e 20 6f 74 68 65 72 20 77 6f 72 64  * (in other word
dac0: 73 2c 20 69 66 20 66 69 6c 65 73 20 63 61 6e 20  s, if files can 
dad0: 62 65 20 61 64 64 65 64 2c 20 72 65 6d 6f 76 65  be added, remove
dae0: 64 2c 20 61 6e 64 20 72 65 6e 61 6d 65 64 20 77  d, and renamed w
daf0: 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20 64 69 72  ithin.** the dir
db00: 65 63 74 6f 72 79 29 2e 0a 2a 2a 20 54 68 65 20  ectory)..** The 
db10: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
db20: 41 44 57 52 49 54 45 20 63 6f 6e 73 74 61 6e 74  ADWRITE constant
db30: 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 75 73   is currently us
db40: 65 64 20 6f 6e 6c 79 20 62 79 20 74 68 65 0a 2a  ed only by the.*
db50: 2a 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69  * [temp_store_di
db60: 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 2c  rectory pragma],
db70: 20 74 68 6f 75 67 68 20 74 68 69 73 20 63 6f 75   though this cou
db80: 6c 64 20 63 68 61 6e 67 65 20 69 6e 20 61 20 66  ld change in a f
db90: 75 74 75 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65  uture.** release
dba0: 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 57   of SQLite..** W
dbb0: 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53  ith SQLITE_ACCES
dbc0: 53 5f 52 45 41 44 2c 20 74 68 65 20 78 41 63 63  S_READ, the xAcc
dbd0: 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68  ess method.** ch
dbe0: 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65  ecks whether the
dbf0: 20 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c   file is readabl
dc00: 65 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 41  e.  The SQLITE_A
dc10: 43 43 45 53 53 5f 52 45 41 44 20 63 6f 6e 73 74  CCESS_READ const
dc20: 61 6e 74 20 69 73 0a 2a 2a 20 63 75 72 72 65 6e  ant is.** curren
dc30: 74 6c 79 20 75 6e 75 73 65 64 2c 20 74 68 6f 75  tly unused, thou
dc40: 67 68 20 69 74 20 6d 69 67 68 74 20 62 65 20 75  gh it might be u
dc50: 73 65 64 20 69 6e 20 61 20 66 75 74 75 72 65 20  sed in a future 
dc60: 72 65 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51  release of.** SQ
dc70: 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  Lite..*/.#define
dc80: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45   SQLITE_ACCESS_E
dc90: 58 49 53 54 53 20 20 20 20 30 0a 23 64 65 66 69  XISTS    0.#defi
dca0: 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  ne SQLITE_ACCESS
dcb0: 5f 52 45 41 44 57 52 49 54 45 20 31 20 20 20 2f  _READWRITE 1   /
dcc0: 2a 20 55 73 65 64 20 62 79 20 50 52 41 47 4d 41  * Used by PRAGMA
dcd0: 20 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65   temp_store_dire
dce0: 63 74 6f 72 79 20 2a 2f 0a 23 64 65 66 69 6e 65  ctory */.#define
dcf0: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52   SQLITE_ACCESS_R
dd00: 45 41 44 20 20 20 20 20 20 32 20 20 20 2f 2a 20  EAD      2   /* 
dd10: 55 6e 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a  Unused */../*.**
dd20: 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73   CAPI3REF: Flags
dd30: 20 66 6f 72 20 74 68 65 20 78 53 68 6d 4c 6f 63   for the xShmLoc
dd40: 6b 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a  k VFS method.**.
dd50: 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72  ** These integer
dd60: 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e   constants defin
dd70: 65 20 74 68 65 20 76 61 72 69 6f 75 73 20 6c 6f  e the various lo
dd80: 63 6b 69 6e 67 20 6f 70 65 72 61 74 69 6f 6e 73  cking operations
dd90: 0a 2a 2a 20 61 6c 6c 6f 77 65 64 20 62 79 20 74  .** allowed by t
dda0: 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68  he xShmLock meth
ddb0: 6f 64 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 69  od of [sqlite3_i
ddc0: 6f 5f 6d 65 74 68 6f 64 73 5d 2e 20 20 54 68 65  o_methods].  The
ddd0: 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 72  .** following ar
dde0: 65 20 74 68 65 20 6f 6e 6c 79 20 6c 65 67 61 6c  e the only legal
ddf0: 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 6f 66   combinations of
de00: 20 66 6c 61 67 73 20 74 6f 20 74 68 65 0a 2a 2a   flags to the.**
de10: 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64   xShmLock method
de20: 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
de30: 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d  <li>  SQLITE_SHM
de40: 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53  _LOCK | SQLITE_S
de50: 48 4d 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69  HM_SHARED.** <li
de60: 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f  >  SQLITE_SHM_LO
de70: 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f  CK | SQLITE_SHM_
de80: 45 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 6c 69  EXCLUSIVE.** <li
de90: 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e  >  SQLITE_SHM_UN
dea0: 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48  LOCK | SQLITE_SH
deb0: 4d 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e  M_SHARED.** <li>
dec0: 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c    SQLITE_SHM_UNL
ded0: 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d  OCK | SQLITE_SHM
dee0: 5f 45 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 2f  _EXCLUSIVE.** </
def0: 75 6c 3e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 75  ul>.**.** When u
df00: 6e 6c 6f 63 6b 69 6e 67 2c 20 74 68 65 20 73 61  nlocking, the sa
df10: 6d 65 20 53 48 41 52 45 44 20 6f 72 20 45 58 43  me SHARED or EXC
df20: 4c 55 53 49 56 45 20 66 6c 61 67 20 6d 75 73 74  LUSIVE flag must
df30: 20 62 65 20 73 75 70 70 6c 69 65 64 20 61 73 0a   be supplied as.
df40: 2a 2a 20 77 61 73 20 67 69 76 65 6e 20 6e 6f 20  ** was given no 
df50: 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
df60: 67 20 6c 6f 63 6b 2e 20 20 0a 2a 2a 0a 2a 2a 20  g lock.  .**.** 
df70: 54 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74  The xShmLock met
df80: 68 6f 64 20 63 61 6e 20 74 72 61 6e 73 69 74 69  hod can transiti
df90: 6f 6e 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63  on between unloc
dfa0: 6b 65 64 20 61 6e 64 20 53 48 41 52 45 44 20 6f  ked and SHARED o
dfb0: 72 0a 2a 2a 20 62 65 74 77 65 65 6e 20 75 6e 6c  r.** between unl
dfc0: 6f 63 6b 65 64 20 61 6e 64 20 45 58 43 4c 55 53  ocked and EXCLUS
dfd0: 49 56 45 2e 20 20 49 74 20 63 61 6e 6e 6f 74 20  IVE.  It cannot 
dfe0: 74 72 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65  transition betwe
dff0: 65 6e 20 53 48 41 52 45 44 0a 2a 2a 20 61 6e 64  en SHARED.** and
e000: 20 45 58 43 4c 55 53 49 56 45 2e 0a 2a 2f 0a 23   EXCLUSIVE..*/.#
e010: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48  define SQLITE_SH
e020: 4d 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 31  M_UNLOCK       1
e030: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
e040: 53 48 4d 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20  SHM_LOCK        
e050: 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   2.#define SQLIT
e060: 45 5f 53 48 4d 5f 53 48 41 52 45 44 20 20 20 20  E_SHM_SHARED    
e070: 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c     4.#define SQL
e080: 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56  ITE_SHM_EXCLUSIV
e090: 45 20 20 20 20 38 0a 0a 2f 2a 0a 2a 2a 20 43 41  E    8../*.** CA
e0a0: 50 49 33 52 45 46 3a 20 4d 61 78 69 6d 75 6d 20  PI3REF: Maximum 
e0b0: 78 53 68 6d 4c 6f 63 6b 20 69 6e 64 65 78 0a 2a  xShmLock index.*
e0c0: 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63  *.** The xShmLoc
e0d0: 6b 20 6d 65 74 68 6f 64 20 6f 6e 20 5b 73 71 6c  k method on [sql
e0e0: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
e0f0: 20 6d 61 79 20 75 73 65 20 76 61 6c 75 65 73 0a   may use values.
e100: 2a 2a 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64  ** between 0 and
e110: 20 74 68 69 73 20 75 70 70 65 72 20 62 6f 75 6e   this upper boun
e120: 64 20 61 73 20 69 74 73 20 22 6f 66 66 73 65 74  d as its "offset
e130: 22 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54  " argument..** T
e140: 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 77  he SQLite core w
e150: 69 6c 6c 20 6e 65 76 65 72 20 61 74 74 65 6d 70  ill never attemp
e160: 74 20 74 6f 20 61 63 71 75 69 72 65 20 6f 72 20  t to acquire or 
e170: 72 65 6c 65 61 73 65 20 61 0a 2a 2a 20 6c 6f 63  release a.** loc
e180: 6b 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 69  k outside of thi
e190: 73 20 72 61 6e 67 65 0a 2a 2f 0a 23 64 65 66 69  s range.*/.#defi
e1a0: 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4e 4c  ne SQLITE_SHM_NL
e1b0: 4f 43 4b 20 20 20 20 20 20 20 20 38 0a 0a 0a 2f  OCK        8.../
e1c0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49  *.** CAPI3REF: I
e1d0: 6e 69 74 69 61 6c 69 7a 65 20 54 68 65 20 53 51  nitialize The SQ
e1e0: 4c 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a  Lite Library.**.
e1f0: 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
e200: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75  initialize() rou
e210: 74 69 6e 65 20 69 6e 69 74 69 61 6c 69 7a 65 73  tine initializes
e220: 20 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20 6c   the.** SQLite l
e230: 69 62 72 61 72 79 2e 20 20 5e 54 68 65 20 73 71  ibrary.  ^The sq
e240: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
e250: 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 64 65 61 6c   routine.** deal
e260: 6c 6f 63 61 74 65 73 20 61 6e 79 20 72 65 73 6f  locates any reso
e270: 75 72 63 65 73 20 74 68 61 74 20 77 65 72 65 20  urces that were 
e280: 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c  allocated by sql
e290: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
e2a0: 29 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  )..** These rout
e2b0: 69 6e 65 73 20 61 72 65 20 64 65 73 69 67 6e 65  ines are designe
e2c0: 64 20 74 6f 20 61 69 64 20 69 6e 20 70 72 6f 63  d to aid in proc
e2d0: 65 73 73 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  ess initializati
e2e0: 6f 6e 20 61 6e 64 0a 2a 2a 20 73 68 75 74 64 6f  on and.** shutdo
e2f0: 77 6e 20 6f 6e 20 65 6d 62 65 64 64 65 64 20 73  wn on embedded s
e300: 79 73 74 65 6d 73 2e 20 20 57 6f 72 6b 73 74 61  ystems.  Worksta
e310: 74 69 6f 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  tion application
e320: 73 20 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 69 74  s using.** SQLit
e330: 65 20 6e 6f 72 6d 61 6c 6c 79 20 64 6f 20 6e 6f  e normally do no
e340: 74 20 6e 65 65 64 20 74 6f 20 69 6e 76 6f 6b 65  t need to invoke
e350: 20 65 69 74 68 65 72 20 6f 66 20 74 68 65 73 65   either of these
e360: 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a   routines..**.**
e370: 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74   A call to sqlit
e380: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
e390: 69 73 20 61 6e 20 22 65 66 66 65 63 74 69 76 65  is an "effective
e3a0: 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73 0a  " call if it is.
e3b0: 2a 2a 20 74 68 65 20 66 69 72 73 74 20 74 69 6d  ** the first tim
e3c0: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
e3d0: 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65  lize() is invoke
e3e0: 64 20 64 75 72 69 6e 67 20 74 68 65 20 6c 69 66  d during the lif
e3f0: 65 74 69 6d 65 20 6f 66 0a 2a 2a 20 74 68 65 20  etime of.** the 
e400: 70 72 6f 63 65 73 73 2c 20 6f 72 20 69 66 20 69  process, or if i
e410: 74 20 69 73 20 74 68 65 20 66 69 72 73 74 20 74  t is the first t
e420: 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  ime sqlite3_init
e430: 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f  ialize() is invo
e440: 6b 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67  ked.** following
e450: 20 61 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74   a call to sqlit
e460: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20  e3_shutdown().  
e470: 5e 28 4f 6e 6c 79 20 61 6e 20 65 66 66 65 63 74  ^(Only an effect
e480: 69 76 65 20 63 61 6c 6c 0a 2a 2a 20 6f 66 20 73  ive call.** of s
e490: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
e4a0: 65 28 29 20 64 6f 65 73 20 61 6e 79 20 69 6e 69  e() does any ini
e4b0: 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 20 20 41 6c  tialization.  Al
e4c0: 6c 20 6f 74 68 65 72 20 63 61 6c 6c 73 0a 2a 2a  l other calls.**
e4d0: 20 61 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f   are harmless no
e4e0: 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20  -ops.)^.**.** A 
e4f0: 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
e500: 73 68 75 74 64 6f 77 6e 28 29 20 69 73 20 61 6e  shutdown() is an
e510: 20 22 65 66 66 65 63 74 69 76 65 22 20 63 61 6c   "effective" cal
e520: 6c 20 69 66 20 69 74 20 69 73 20 74 68 65 20 66  l if it is the f
e530: 69 72 73 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20  irst.** call to 
e540: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
e550: 28 29 20 73 69 6e 63 65 20 74 68 65 20 6c 61 73  () since the las
e560: 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  t sqlite3_initia
e570: 6c 69 7a 65 28 29 2e 20 20 5e 28 4f 6e 6c 79 0a  lize().  ^(Only.
e580: 2a 2a 20 61 6e 20 65 66 66 65 63 74 69 76 65 20  ** an effective 
e590: 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
e5a0: 73 68 75 74 64 6f 77 6e 28 29 20 64 6f 65 73 20  shutdown() does 
e5b0: 61 6e 79 20 64 65 69 6e 69 74 69 61 6c 69 7a 61  any deinitializa
e5c0: 74 69 6f 6e 2e 0a 2a 2a 20 41 6c 6c 20 6f 74 68  tion..** All oth
e5d0: 65 72 20 76 61 6c 69 64 20 63 61 6c 6c 73 20 74  er valid calls t
e5e0: 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  o sqlite3_shutdo
e5f0: 77 6e 28 29 20 61 72 65 20 68 61 72 6d 6c 65 73  wn() are harmles
e600: 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a  s no-ops.)^.**.*
e610: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  * The sqlite3_in
e620: 69 74 69 61 6c 69 7a 65 28 29 20 69 6e 74 65 72  itialize() inter
e630: 66 61 63 65 20 69 73 20 74 68 72 65 61 64 73 61  face is threadsa
e640: 66 65 2c 20 62 75 74 20 73 71 6c 69 74 65 33 5f  fe, but sqlite3_
e650: 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 69 73  shutdown().** is
e660: 20 6e 6f 74 2e 20 20 54 68 65 20 73 71 6c 69 74   not.  The sqlit
e670: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 69 6e  e3_shutdown() in
e680: 74 65 72 66 61 63 65 20 6d 75 73 74 20 6f 6e 6c  terface must onl
e690: 79 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d  y be called from
e6a0: 20 61 0a 2a 2a 20 73 69 6e 67 6c 65 20 74 68 72   a.** single thr
e6b0: 65 61 64 2e 20 20 41 6c 6c 20 6f 70 65 6e 20 5b  ead.  All open [
e6c0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
e6d0: 69 6f 6e 73 5d 20 6d 75 73 74 20 62 65 20 63 6c  ions] must be cl
e6e0: 6f 73 65 64 20 61 6e 64 20 61 6c 6c 0a 2a 2a 20  osed and all.** 
e6f0: 6f 74 68 65 72 20 53 51 4c 69 74 65 20 72 65 73  other SQLite res
e700: 6f 75 72 63 65 73 20 6d 75 73 74 20 62 65 20 64  ources must be d
e710: 65 61 6c 6c 6f 63 61 74 65 64 20 70 72 69 6f 72  eallocated prior
e720: 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20   to invoking.** 
e730: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
e740: 28 29 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20  ()..**.** Among 
e750: 6f 74 68 65 72 20 74 68 69 6e 67 73 2c 20 5e 73  other things, ^s
e760: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
e770: 65 28 29 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a  e() will invoke.
e780: 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  ** sqlite3_os_in
e790: 69 74 28 29 2e 20 20 53 69 6d 69 6c 61 72 6c 79  it().  Similarly
e7a0: 2c 20 5e 73 71 6c 69 74 65 33 5f 73 68 75 74 64  , ^sqlite3_shutd
e7b0: 6f 77 6e 28 29 0a 2a 2a 20 77 69 6c 6c 20 69 6e  own().** will in
e7c0: 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f  voke sqlite3_os_
e7d0: 65 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  end()..**.** ^Th
e7e0: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
e7f0: 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 72  lize() routine r
e800: 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
e810: 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 2e 0a 2a  K] on success..*
e820: 2a 20 5e 49 66 20 66 6f 72 20 73 6f 6d 65 20 72  * ^If for some r
e830: 65 61 73 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 69  eason, sqlite3_i
e840: 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 75  nitialize() is u
e850: 6e 61 62 6c 65 20 74 6f 20 69 6e 69 74 69 61 6c  nable to initial
e860: 69 7a 65 0a 2a 2a 20 74 68 65 20 6c 69 62 72 61  ize.** the libra
e870: 72 79 20 28 70 65 72 68 61 70 73 20 69 74 20 69  ry (perhaps it i
e880: 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f  s unable to allo
e890: 63 61 74 65 20 61 20 6e 65 65 64 65 64 20 72 65  cate a needed re
e8a0: 73 6f 75 72 63 65 20 73 75 63 68 0a 2a 2a 20 61  source such.** a
e8b0: 73 20 61 20 6d 75 74 65 78 29 20 69 74 20 72 65  s a mutex) it re
e8c0: 74 75 72 6e 73 20 61 6e 20 5b 65 72 72 6f 72 20  turns an [error 
e8d0: 63 6f 64 65 5d 20 6f 74 68 65 72 20 74 68 61 6e  code] other than
e8e0: 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a   [SQLITE_OK]..**
e8f0: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
e900: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f  _initialize() ro
e910: 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20  utine is called 
e920: 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 6d 61  internally by ma
e930: 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69  ny other.** SQLi
e940: 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 73 6f  te interfaces so
e950: 20 74 68 61 74 20 61 6e 20 61 70 70 6c 69 63 61   that an applica
e960: 74 69 6f 6e 20 75 73 75 61 6c 6c 79 20 64 6f 65  tion usually doe
e970: 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 0a 2a 2a  s not need to.**
e980: 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f   invoke sqlite3_
e990: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72  initialize() dir
e9a0: 65 63 74 6c 79 2e 20 20 46 6f 72 20 65 78 61 6d  ectly.  For exam
e9b0: 70 6c 65 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ple, [sqlite3_op
e9c0: 65 6e 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73  en()].** calls s
e9d0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
e9e0: 65 28 29 20 73 6f 20 74 68 65 20 53 51 4c 69 74  e() so the SQLit
e9f0: 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 62  e library will b
ea00: 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a  e automatically.
ea10: 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 77  ** initialized w
ea20: 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  hen [sqlite3_ope
ea30: 6e 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 69  n()] is called i
ea40: 66 20 69 74 20 68 61 73 20 6e 6f 74 20 62 65 20  f it has not be 
ea50: 69 6e 69 74 69 61 6c 69 7a 65 64 0a 2a 2a 20 61  initialized.** a
ea60: 6c 72 65 61 64 79 2e 20 20 5e 48 6f 77 65 76 65  lready.  ^Howeve
ea70: 72 2c 20 69 66 20 53 51 4c 69 74 65 20 69 73 20  r, if SQLite is 
ea80: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68  compiled with th
ea90: 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41  e [SQLITE_OMIT_A
eaa0: 55 54 4f 49 4e 49 54 5d 0a 2a 2a 20 63 6f 6d 70  UTOINIT].** comp
eab0: 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c  ile-time option,
eac0: 20 74 68 65 6e 20 74 68 65 20 61 75 74 6f 6d 61   then the automa
ead0: 74 69 63 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  tic calls to sql
eae0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
eaf0: 29 0a 2a 2a 20 61 72 65 20 6f 6d 69 74 74 65 64  ).** are omitted
eb00: 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61   and the applica
eb10: 74 69 6f 6e 20 6d 75 73 74 20 63 61 6c 6c 20 73  tion must call s
eb20: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
eb30: 65 28 29 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20  e() directly.** 
eb40: 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61  prior to using a
eb50: 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20  ny other SQLite 
eb60: 69 6e 74 65 72 66 61 63 65 2e 20 20 46 6f 72 20  interface.  For 
eb70: 6d 61 78 69 6d 75 6d 20 70 6f 72 74 61 62 69 6c  maximum portabil
eb80: 69 74 79 2c 0a 2a 2a 20 69 74 20 69 73 20 72 65  ity,.** it is re
eb90: 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61  commended that a
eba0: 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 6c 77 61  pplications alwa
ebb0: 79 73 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65  ys invoke sqlite
ebc0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a  3_initialize().*
ebd0: 2a 20 64 69 72 65 63 74 6c 79 20 70 72 69 6f 72  * directly prior
ebe0: 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74   to using any ot
ebf0: 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72  her SQLite inter
ec00: 66 61 63 65 2e 20 20 46 75 74 75 72 65 20 72 65  face.  Future re
ec10: 6c 65 61 73 65 73 0a 2a 2a 20 6f 66 20 53 51 4c  leases.** of SQL
ec20: 69 74 65 20 6d 61 79 20 72 65 71 75 69 72 65 20  ite may require 
ec30: 74 68 69 73 2e 20 20 49 6e 20 6f 74 68 65 72 20  this.  In other 
ec40: 77 6f 72 64 73 2c 20 74 68 65 20 62 65 68 61 76  words, the behav
ec50: 69 6f 72 20 65 78 68 69 62 69 74 65 64 0a 2a 2a  ior exhibited.**
ec60: 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20   when SQLite is 
ec70: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53  compiled with [S
ec80: 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49  QLITE_OMIT_AUTOI
ec90: 4e 49 54 5d 20 6d 69 67 68 74 20 62 65 63 6f 6d  NIT] might becom
eca0: 65 20 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74  e the.** default
ecb0: 20 62 65 68 61 76 69 6f 72 20 69 6e 20 73 6f 6d   behavior in som
ecc0: 65 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  e future release
ecd0: 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a   of SQLite..**.*
ece0: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73  * The sqlite3_os
ecf0: 5f 69 6e 69 74 28 29 20 72 6f 75 74 69 6e 65 20  _init() routine 
ed00: 64 6f 65 73 20 6f 70 65 72 61 74 69 6e 67 2d 73  does operating-s
ed10: 79 73 74 65 6d 20 73 70 65 63 69 66 69 63 0a 2a  ystem specific.*
ed20: 2a 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  * initialization
ed30: 20 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20 6c   of the SQLite l
ed40: 69 62 72 61 72 79 2e 20 20 54 68 65 20 73 71 6c  ibrary.  The sql
ed50: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a  ite3_os_end().**
ed60: 20 72 6f 75 74 69 6e 65 20 75 6e 64 6f 65 73 20   routine undoes 
ed70: 74 68 65 20 65 66 66 65 63 74 20 6f 66 20 73 71  the effect of sq
ed80: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e  lite3_os_init().
ed90: 20 20 54 79 70 69 63 61 6c 20 74 61 73 6b 73 0a    Typical tasks.
eda0: 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 62 79 20  ** performed by 
edb0: 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 69  these routines i
edc0: 6e 63 6c 75 64 65 20 61 6c 6c 6f 63 61 74 69 6f  nclude allocatio
edd0: 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 69 6f  n or deallocatio
ede0: 6e 0a 2a 2a 20 6f 66 20 73 74 61 74 69 63 20 72  n.** of static r
edf0: 65 73 6f 75 72 63 65 73 2c 20 69 6e 69 74 69 61  esources, initia
ee00: 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 67 6c 6f 62  lization of glob
ee10: 61 6c 20 76 61 72 69 61 62 6c 65 73 2c 0a 2a 2a  al variables,.**
ee20: 20 73 65 74 74 69 6e 67 20 75 70 20 61 20 64 65   setting up a de
ee30: 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76  fault [sqlite3_v
ee40: 66 73 5d 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 73  fs] module, or s
ee50: 65 74 74 69 6e 67 20 75 70 0a 2a 2a 20 61 20 64  etting up.** a d
ee60: 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61  efault configura
ee70: 74 69 6f 6e 20 75 73 69 6e 67 20 5b 73 71 6c 69  tion using [sqli
ee80: 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a  te3_config()]..*
ee90: 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  *.** The applica
eea0: 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65  tion should neve
eeb0: 72 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20  r invoke either 
eec0: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
eed0: 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f  ).** or sqlite3_
eee0: 6f 73 5f 65 6e 64 28 29 20 64 69 72 65 63 74 6c  os_end() directl
eef0: 79 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 74  y.  The applicat
ef00: 69 6f 6e 20 73 68 6f 75 6c 64 20 6f 6e 6c 79 20  ion should only 
ef10: 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65  invoke.** sqlite
ef20: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61  3_initialize() a
ef30: 6e 64 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  nd sqlite3_shutd
ef40: 6f 77 6e 28 29 2e 20 20 54 68 65 20 73 71 6c 69  own().  The sqli
ef50: 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a  te3_os_init().**
ef60: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 63 61   interface is ca
ef70: 6c 6c 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c  lled automatical
ef80: 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e  ly by sqlite3_in
ef90: 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 0a 2a  itialize() and.*
efa0: 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  * sqlite3_os_end
efb0: 28 29 20 69 73 20 63 61 6c 6c 65 64 20 62 79 20  () is called by 
efc0: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
efd0: 28 29 2e 20 20 41 70 70 72 6f 70 72 69 61 74 65  ().  Appropriate
efe0: 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
eff0: 6f 6e 73 20 66 6f 72 20 73 71 6c 69 74 65 33 5f  ons for sqlite3_
f000: 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71  os_init() and sq
f010: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a  lite3_os_end().*
f020: 2a 20 61 72 65 20 62 75 69 6c 74 20 69 6e 74 6f  * are built into
f030: 20 53 51 4c 69 74 65 20 77 68 65 6e 20 69 74 20   SQLite when it 
f040: 69 73 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20  is compiled for 
f050: 55 6e 69 78 2c 20 57 69 6e 64 6f 77 73 2c 20 6f  Unix, Windows, o
f060: 72 20 4f 53 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20  r OS/2..** When 
f070: 5b 63 75 73 74 6f 6d 20 62 75 69 6c 64 73 20 7c  [custom builds |
f080: 20 62 75 69 6c 74 20 66 6f 72 20 6f 74 68 65 72   built for other
f090: 20 70 6c 61 74 66 6f 72 6d 73 5d 0a 2a 2a 20 28   platforms].** (
f0a0: 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54  using the [SQLIT
f0b0: 45 5f 4f 53 5f 4f 54 48 45 52 3d 31 5d 20 63 6f  E_OS_OTHER=1] co
f0c0: 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70  mpile-time.** op
f0d0: 74 69 6f 6e 29 20 74 68 65 20 61 70 70 6c 69 63  tion) the applic
f0e0: 61 74 69 6f 6e 20 6d 75 73 74 20 73 75 70 70 6c  ation must suppl
f0f0: 79 20 61 20 73 75 69 74 61 62 6c 65 20 69 6d 70  y a suitable imp
f100: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a  lementation for.
f110: 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  ** sqlite3_os_in
f120: 69 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  it() and sqlite3
f130: 5f 6f 73 5f 65 6e 64 28 29 2e 20 20 41 6e 20 61  _os_end().  An a
f140: 70 70 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c  pplication-suppl
f150: 69 65 64 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  ied.** implement
f160: 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33  ation of sqlite3
f170: 5f 6f 73 5f 69 6e 69 74 28 29 20 6f 72 20 73 71  _os_init() or sq
f180: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a  lite3_os_end().*
f190: 2a 20 6d 75 73 74 20 72 65 74 75 72 6e 20 5b 53  * must return [S
f1a0: 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63  QLITE_OK] on suc
f1b0: 63 65 73 73 20 61 6e 64 20 73 6f 6d 65 20 6f 74  cess and some ot
f1c0: 68 65 72 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  her [error code]
f1d0: 20 75 70 6f 6e 0a 2a 2a 20 66 61 69 6c 75 72 65   upon.** failure
f1e0: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
f1f0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 76 6f 69 64  _initialize(void
f200: 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73  );.int sqlite3_s
f210: 68 75 74 64 6f 77 6e 28 76 6f 69 64 29 3b 0a 69  hutdown(void);.i
f220: 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  nt sqlite3_os_in
f230: 69 74 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71  it(void);.int sq
f240: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 76 6f 69  lite3_os_end(voi
f250: 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  d);../*.** CAPI3
f260: 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 69 6e 67  REF: Configuring
f270: 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72   The SQLite Libr
f280: 61 72 79 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ary.**.** The sq
f290: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69  lite3_config() i
f2a0: 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64  nterface is used
f2b0: 20 74 6f 20 6d 61 6b 65 20 67 6c 6f 62 61 6c 20   to make global 
f2c0: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a  configuration.**
f2d0: 20 63 68 61 6e 67 65 73 20 74 6f 20 53 51 4c 69   changes to SQLi
f2e0: 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 74  te in order to t
f2f0: 75 6e 65 20 53 51 4c 69 74 65 20 74 6f 20 74 68  une SQLite to th
f300: 65 20 73 70 65 63 69 66 69 63 20 6e 65 65 64 73  e specific needs
f310: 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69   of.** the appli
f320: 63 61 74 69 6f 6e 2e 20 20 54 68 65 20 64 65 66  cation.  The def
f330: 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69  ault configurati
f340: 6f 6e 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  on is recommende
f350: 64 20 66 6f 72 20 6d 6f 73 74 0a 2a 2a 20 61 70  d for most.** ap
f360: 70 6c 69 63 61 74 69 6f 6e 73 20 61 6e 64 20 73  plications and s
f370: 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69  o this routine i
f380: 73 20 75 73 75 61 6c 6c 79 20 6e 6f 74 20 6e 65  s usually not ne
f390: 63 65 73 73 61 72 79 2e 20 20 49 74 20 69 73 0a  cessary.  It is.
f3a0: 2a 2a 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73  ** provided to s
f3b0: 75 70 70 6f 72 74 20 72 61 72 65 20 61 70 70 6c  upport rare appl
f3c0: 69 63 61 74 69 6f 6e 73 20 77 69 74 68 20 75 6e  ications with un
f3d0: 75 73 75 61 6c 20 6e 65 65 64 73 2e 0a 2a 2a 0a  usual needs..**.
f3e0: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63  ** The sqlite3_c
f3f0: 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63  onfig() interfac
f400: 65 20 69 73 20 6e 6f 74 20 74 68 72 65 61 64 73  e is not threads
f410: 61 66 65 2e 20 20 54 68 65 20 61 70 70 6c 69 63  afe.  The applic
f420: 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e  ation.** must in
f430: 73 75 72 65 20 74 68 61 74 20 6e 6f 20 6f 74 68  sure that no oth
f440: 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  er SQLite interf
f450: 61 63 65 73 20 61 72 65 20 69 6e 76 6f 6b 65 64  aces are invoked
f460: 20 62 79 20 6f 74 68 65 72 0a 2a 2a 20 74 68 72   by other.** thr
f470: 65 61 64 73 20 77 68 69 6c 65 20 73 71 6c 69 74  eads while sqlit
f480: 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 72  e3_config() is r
f490: 75 6e 6e 69 6e 67 2e 20 20 46 75 72 74 68 65 72  unning.  Further
f4a0: 6d 6f 72 65 2c 20 73 71 6c 69 74 65 33 5f 63 6f  more, sqlite3_co
f4b0: 6e 66 69 67 28 29 0a 2a 2a 20 6d 61 79 20 6f 6e  nfig().** may on
f4c0: 6c 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 72  ly be invoked pr
f4d0: 69 6f 72 20 74 6f 20 6c 69 62 72 61 72 79 20 69  ior to library i
f4e0: 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 75 73  nitialization us
f4f0: 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
f500: 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 6f 72  initialize()] or
f510: 20 61 66 74 65 72 20 73 68 75 74 64 6f 77 6e 20   after shutdown 
f520: 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74  by [sqlite3_shut
f530: 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 5e 49 66 20  down()]..** ^If 
f540: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
f550: 20 69 73 20 63 61 6c 6c 65 64 20 61 66 74 65 72   is called after
f560: 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61   [sqlite3_initia
f570: 6c 69 7a 65 28 29 5d 20 61 6e 64 20 62 65 66 6f  lize()] and befo
f580: 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  re.** [sqlite3_s
f590: 68 75 74 64 6f 77 6e 28 29 5d 20 74 68 65 6e 20  hutdown()] then 
f5a0: 69 74 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 53  it will return S
f5b0: 51 4c 49 54 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a  QLITE_MISUSE..**
f5c0: 20 4e 6f 74 65 2c 20 68 6f 77 65 76 65 72 2c 20   Note, however, 
f5d0: 74 68 61 74 20 5e 73 71 6c 69 74 65 33 5f 63 6f  that ^sqlite3_co
f5e0: 6e 66 69 67 28 29 20 63 61 6e 20 62 65 20 63 61  nfig() can be ca
f5f0: 6c 6c 65 64 20 61 73 20 70 61 72 74 20 6f 66 20  lled as part of 
f600: 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  the.** implement
f610: 61 74 69 6f 6e 20 6f 66 20 61 6e 20 61 70 70 6c  ation of an appl
f620: 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
f630: 5b 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74  [sqlite3_os_init
f640: 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  ()]..**.** The f
f650: 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
f660: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
f670: 29 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 0a  ) is an integer.
f680: 2a 2a 20 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f  ** [configuratio
f690: 6e 20 6f 70 74 69 6f 6e 5d 20 74 68 61 74 20 64  n option] that d
f6a0: 65 74 65 72 6d 69 6e 65 73 0a 2a 2a 20 77 68 61  etermines.** wha
f6b0: 74 20 70 72 6f 70 65 72 74 79 20 6f 66 20 53 51  t property of SQ
f6c0: 4c 69 74 65 20 69 73 20 74 6f 20 62 65 20 63 6f  Lite is to be co
f6d0: 6e 66 69 67 75 72 65 64 2e 20 20 53 75 62 73 65  nfigured.  Subse
f6e0: 71 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 0a  quent arguments.
f6f0: 2a 2a 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e  ** vary dependin
f700: 67 20 6f 6e 20 74 68 65 20 5b 63 6f 6e 66 69 67  g on the [config
f710: 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 0a  uration option].
f720: 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  ** in the first 
f730: 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  argument..**.** 
f740: 5e 57 68 65 6e 20 61 20 63 6f 6e 66 69 67 75 72  ^When a configur
f750: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20  ation option is 
f760: 73 65 74 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e  set, sqlite3_con
f770: 66 69 67 28 29 20 72 65 74 75 72 6e 73 20 5b 53  fig() returns [S
f780: 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e 49  QLITE_OK]..** ^I
f790: 66 20 74 68 65 20 6f 70 74 69 6f 6e 20 69 73 20  f the option is 
f7a0: 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c 69 74  unknown or SQLit
f7b0: 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 73  e is unable to s
f7c0: 65 74 20 74 68 65 20 6f 70 74 69 6f 6e 0a 2a 2a  et the option.**
f7d0: 20 74 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69   then this routi
f7e0: 6e 65 20 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e  ne returns a non
f7f0: 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64  -zero [error cod
f800: 65 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  e]..*/.int sqlit
f810: 65 33 5f 63 6f 6e 66 69 67 28 69 6e 74 2c 20 2e  e3_config(int, .
f820: 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ..);../*.** CAPI
f830: 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 65 20  3REF: Configure 
f840: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
f850: 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ions.**.** The s
f860: 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
f870: 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
f880: 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 63 6f 6e  used to make con
f890: 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68  figuration.** ch
f8a0: 61 6e 67 65 73 20 74 6f 20 61 20 5b 64 61 74 61  anges to a [data
f8b0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
f8c0: 2e 20 20 54 68 65 20 69 6e 74 65 72 66 61 63 65  .  The interface
f8d0: 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 0a 2a   is similar to.*
f8e0: 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
f8f0: 67 28 29 5d 20 65 78 63 65 70 74 20 74 68 61 74  g()] except that
f900: 20 74 68 65 20 63 68 61 6e 67 65 73 20 61 70 70   the changes app
f910: 6c 79 20 74 6f 20 61 20 73 69 6e 67 6c 65 0a 2a  ly to a single.*
f920: 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
f930: 65 63 74 69 6f 6e 5d 20 28 73 70 65 63 69 66 69  ection] (specifi
f940: 65 64 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  ed in the first 
f950: 61 72 67 75 6d 65 6e 74 29 2e 0a 2a 2a 0a 2a 2a  argument)..**.**
f960: 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   The second argu
f970: 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
f980: 64 62 5f 63 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e  db_config(D,V,..
f990: 2e 29 20 20 69 73 20 74 68 65 0a 2a 2a 20 5b 53  .)  is the.** [S
f9a0: 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c  QLITE_DBCONFIG_L
f9b0: 4f 4f 4b 41 53 49 44 45 20 7c 20 63 6f 6e 66 69  OOKASIDE | confi
f9c0: 67 75 72 61 74 69 6f 6e 20 76 65 72 62 5d 20 2d  guration verb] -
f9d0: 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65   an integer code
f9e0: 20 0a 2a 2a 20 74 68 61 74 20 69 6e 64 69 63 61   .** that indica
f9f0: 74 65 73 20 77 68 61 74 20 61 73 70 65 63 74 20  tes what aspect 
fa00: 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  of the [database
fa10: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20   connection] is 
fa20: 62 65 69 6e 67 20 63 6f 6e 66 69 67 75 72 65 64  being configured
fa30: 2e 0a 2a 2a 20 53 75 62 73 65 71 75 65 6e 74 20  ..** Subsequent 
fa40: 61 72 67 75 6d 65 6e 74 73 20 76 61 72 79 20 64  arguments vary d
fa50: 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20  epending on the 
fa60: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65  configuration ve
fa70: 72 62 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 73  rb..**.** ^Calls
fa80: 20 74 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63   to sqlite3_db_c
fa90: 6f 6e 66 69 67 28 29 20 72 65 74 75 72 6e 20 53  onfig() return S
faa0: 51 4c 49 54 45 5f 4f 4b 20 69 66 20 61 6e 64 20  QLITE_OK if and 
fab0: 6f 6e 6c 79 20 69 66 0a 2a 2a 20 74 68 65 20 63  only if.** the c
fac0: 61 6c 6c 20 69 73 20 63 6f 6e 73 69 64 65 72 65  all is considere
fad0: 64 20 73 75 63 63 65 73 73 66 75 6c 2e 0a 2a 2f  d successful..*/
fae0: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 62 5f  .int sqlite3_db_
faf0: 63 6f 6e 66 69 67 28 73 71 6c 69 74 65 33 2a 2c  config(sqlite3*,
fb00: 20 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a   int op, ...);..
fb10: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
fb20: 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f  Memory Allocatio
fb30: 6e 20 52 6f 75 74 69 6e 65 73 0a 2a 2a 0a 2a 2a  n Routines.**.**
fb40: 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   An instance of 
fb50: 74 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69  this object defi
fb60: 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63  nes the interfac
fb70: 65 20 62 65 74 77 65 65 6e 20 53 51 4c 69 74 65  e between SQLite
fb80: 0a 2a 2a 20 61 6e 64 20 6c 6f 77 2d 6c 65 76 65  .** and low-leve
fb90: 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  l memory allocat
fba0: 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a  ion routines..**
fbb0: 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20  .** This object 
fbc0: 69 73 20 75 73 65 64 20 69 6e 20 6f 6e 6c 79 20  is used in only 
fbd0: 6f 6e 65 20 70 6c 61 63 65 20 69 6e 20 74 68 65  one place in the
fbe0: 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
fbf0: 65 2e 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20  e..** A pointer 
fc00: 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  to an instance o
fc10: 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73  f this object is
fc20: 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f   the argument to
fc30: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
fc40: 66 69 67 28 29 5d 20 77 68 65 6e 20 74 68 65 20  fig()] when the 
fc50: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
fc60: 74 69 6f 6e 20 69 73 0a 2a 2a 20 5b 53 51 4c 49  tion is.** [SQLI
fc70: 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
fc80: 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  ] or [SQLITE_CON
fc90: 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 2e 20  FIG_GETMALLOC]. 
fca0: 20 0a 2a 2a 20 42 79 20 63 72 65 61 74 69 6e 67   .** By creating
fcb0: 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   an instance of 
fcc0: 74 68 69 73 20 6f 62 6a 65 63 74 0a 2a 2a 20 61  this object.** a
fcd0: 6e 64 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f  nd passing it to
fce0: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
fcf0: 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ]([SQLITE_CONFIG
fd00: 5f 4d 41 4c 4c 4f 43 5d 29 0a 2a 2a 20 64 75 72  _MALLOC]).** dur
fd10: 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ing configuratio
fd20: 6e 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  n, an applicatio
fd30: 6e 20 63 61 6e 20 73 70 65 63 69 66 79 20 61 6e  n can specify an
fd40: 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20   alternative.** 
fd50: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
fd60: 6e 20 73 75 62 73 79 73 74 65 6d 20 66 6f 72 20  n subsystem for 
fd70: 53 51 4c 69 74 65 20 74 6f 20 75 73 65 20 66 6f  SQLite to use fo
fd80: 72 20 61 6c 6c 20 6f 66 20 69 74 73 0a 2a 2a 20  r all of its.** 
fd90: 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 6e  dynamic memory n
fda0: 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65  eeds..**.** Note
fdb0: 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 6f 6d   that SQLite com
fdc0: 65 73 20 77 69 74 68 20 73 65 76 65 72 61 6c 20  es with several 
fdd0: 5b 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79  [built-in memory
fde0: 20 61 6c 6c 6f 63 61 74 6f 72 73 5d 0a 2a 2a 20   allocators].** 
fdf0: 74 68 61 74 20 61 72 65 20 70 65 72 66 65 63 74  that are perfect
fe00: 6c 79 20 61 64 65 71 75 61 74 65 20 66 6f 72 20  ly adequate for 
fe10: 74 68 65 20 6f 76 65 72 77 68 65 6c 6d 69 6e 67  the overwhelming
fe20: 20 6d 61 6a 6f 72 69 74 79 20 6f 66 20 61 70 70   majority of app
fe30: 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64  lications.** and
fe40: 20 74 68 61 74 20 74 68 69 73 20 6f 62 6a 65 63   that this objec
fe50: 74 20 69 73 20 6f 6e 6c 79 20 75 73 65 66 75 6c  t is only useful
fe60: 20 74 6f 20 61 20 74 69 6e 79 20 6d 69 6e 6f 72   to a tiny minor
fe70: 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69  ity of applicati
fe80: 6f 6e 73 0a 2a 2a 20 77 69 74 68 20 73 70 65 63  ons.** with spec
fe90: 69 61 6c 69 7a 65 64 20 6d 65 6d 6f 72 79 20 61  ialized memory a
fea0: 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 69 72  llocation requir
feb0: 65 6d 65 6e 74 73 2e 20 20 54 68 69 73 20 6f 62  ements.  This ob
fec0: 6a 65 63 74 20 69 73 0a 2a 2a 20 61 6c 73 6f 20  ject is.** also 
fed0: 75 73 65 64 20 64 75 72 69 6e 67 20 74 65 73 74  used during test
fee0: 69 6e 67 20 6f 66 20 53 51 4c 69 74 65 20 69 6e  ing of SQLite in
fef0: 20 6f 72 64 65 72 20 74 6f 20 73 70 65 63 69 66   order to specif
ff00: 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65  y an alternative
ff10: 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  .** memory alloc
ff20: 61 74 6f 72 20 74 68 61 74 20 73 69 6d 75 6c 61  ator that simula
ff30: 74 65 73 20 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f  tes memory out-o
ff40: 66 2d 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 74 69  f-memory conditi
ff50: 6f 6e 73 20 69 6e 0a 2a 2a 20 6f 72 64 65 72 20  ons in.** order 
ff60: 74 6f 20 76 65 72 69 66 79 20 74 68 61 74 20 53  to verify that S
ff70: 51 4c 69 74 65 20 72 65 63 6f 76 65 72 73 20 67  QLite recovers g
ff80: 72 61 63 65 66 75 6c 6c 79 20 66 72 6f 6d 20 73  racefully from s
ff90: 75 63 68 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e  uch.** condition
ffa0: 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 61  s..**.** The xMa
ffb0: 6c 6c 6f 63 2c 20 78 52 65 61 6c 6c 6f 63 2c 20  lloc, xRealloc, 
ffc0: 61 6e 64 20 78 46 72 65 65 20 6d 65 74 68 6f 64  and xFree method
ffd0: 73 20 6d 75 73 74 20 77 6f 72 6b 20 6c 69 6b 65  s must work like
ffe0: 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29   the.** malloc()
fff0: 2c 20 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20  , realloc() and 
10000 66 72 65 65 28 29 20 66 75 6e 63 74 69 6f 6e 73  free() functions
10010 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61   from the standa
10020 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a  rd C library..**
10030 20 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74   ^SQLite guarant
10040 65 65 73 20 74 68 61 74 20 74 68 65 20 73 65 63  ees that the sec
10050 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a  ond argument to.
10060 2a 2a 20 78 52 65 61 6c 6c 6f 63 20 69 73 20 61  ** xRealloc is a
10070 6c 77 61 79 73 20 61 20 76 61 6c 75 65 20 72 65  lways a value re
10080 74 75 72 6e 65 64 20 62 79 20 61 20 70 72 69 6f  turned by a prio
10090 72 20 63 61 6c 6c 20 74 6f 20 78 52 6f 75 6e 64  r call to xRound
100a0 75 70 2e 0a 2a 2a 0a 2a 2a 20 78 53 69 7a 65 20  up..**.** xSize 
100b0 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68  should return th
100c0 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65  e allocated size
100d0 20 6f 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c   of a memory all
100e0 6f 63 61 74 69 6f 6e 0a 2a 2a 20 70 72 65 76 69  ocation.** previ
100f0 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 66  ously obtained f
10100 72 6f 6d 20 78 4d 61 6c 6c 6f 63 20 6f 72 20 78  rom xMalloc or x
10110 52 65 61 6c 6c 6f 63 2e 20 20 54 68 65 20 61 6c  Realloc.  The al
10120 6c 6f 63 61 74 65 64 20 73 69 7a 65 0a 2a 2a 20  located size.** 
10130 69 73 20 61 6c 77 61 79 73 20 61 74 20 6c 65 61  is always at lea
10140 73 74 20 61 73 20 62 69 67 20 61 73 20 74 68 65  st as big as the
10150 20 72 65 71 75 65 73 74 65 64 20 73 69 7a 65 20   requested size 
10160 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72 67 65  but may be large
10170 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 6f  r..**.** The xRo
10180 75 6e 64 75 70 20 6d 65 74 68 6f 64 20 72 65 74  undup method ret
10190 75 72 6e 73 20 77 68 61 74 20 77 6f 75 6c 64 20  urns what would 
101a0 62 65 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64  be the allocated
101b0 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 61 20 6d 65   size of.** a me
101c0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
101d0 67 69 76 65 6e 20 61 20 70 61 72 74 69 63 75 6c  given a particul
101e0 61 72 20 72 65 71 75 65 73 74 65 64 20 73 69 7a  ar requested siz
101f0 65 2e 20 20 4d 6f 73 74 20 6d 65 6d 6f 72 79 0a  e.  Most memory.
10200 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f  ** allocators ro
10210 75 6e 64 20 75 70 20 6d 65 6d 6f 72 79 20 61 6c  und up memory al
10220 6c 6f 63 61 74 69 6f 6e 73 20 61 74 20 6c 65 61  locations at lea
10230 73 74 20 74 6f 20 74 68 65 20 6e 65 78 74 20 6d  st to the next m
10240 75 6c 74 69 70 6c 65 0a 2a 2a 20 6f 66 20 38 2e  ultiple.** of 8.
10250 20 20 53 6f 6d 65 20 61 6c 6c 6f 63 61 74 6f 72    Some allocator
10260 73 20 72 6f 75 6e 64 20 75 70 20 74 6f 20 61 20  s round up to a 
10270 6c 61 72 67 65 72 20 6d 75 6c 74 69 70 6c 65 20  larger multiple 
10280 6f 72 20 74 6f 20 61 20 70 6f 77 65 72 20 6f 66  or to a power of
10290 20 32 2e 0a 2a 2a 20 45 76 65 72 79 20 6d 65 6d   2..** Every mem
102a0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ory allocation r
102b0 65 71 75 65 73 74 20 63 6f 6d 69 6e 67 20 69 6e  equest coming in
102c0 20 74 68 72 6f 75 67 68 20 5b 73 71 6c 69 74 65   through [sqlite
102d0 33 5f 6d 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6f  3_malloc()].** o
102e0 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  r [sqlite3_reall
102f0 6f 63 28 29 5d 20 66 69 72 73 74 20 63 61 6c 6c  oc()] first call
10300 73 20 78 52 6f 75 6e 64 75 70 2e 20 20 49 66 20  s xRoundup.  If 
10310 78 52 6f 75 6e 64 75 70 20 72 65 74 75 72 6e 73  xRoundup returns
10320 20 30 2c 20 0a 2a 2a 20 74 68 61 74 20 63 61 75   0, .** that cau
10330 73 65 73 20 74 68 65 20 63 6f 72 72 65 73 70 6f  ses the correspo
10340 6e 64 69 6e 67 20 6d 65 6d 6f 72 79 20 61 6c 6c  nding memory all
10350 6f 63 61 74 69 6f 6e 20 74 6f 20 66 61 69 6c 2e  ocation to fail.
10360 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 49 6e 69 74  .**.** The xInit
10370 20 6d 65 74 68 6f 64 20 69 6e 69 74 69 61 6c 69   method initiali
10380 7a 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61  zes the memory a
10390 6c 6c 6f 63 61 74 6f 72 2e 20 20 28 46 6f 72 20  llocator.  (For 
103a0 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d  example,.** it m
103b0 69 67 68 74 20 61 6c 6c 6f 63 61 74 65 20 61 6e  ight allocate an
103c0 79 20 72 65 71 75 69 72 65 20 6d 75 74 65 78 65  y require mutexe
103d0 73 20 6f 72 20 69 6e 69 74 69 61 6c 69 7a 65 20  s or initialize 
103e0 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 0a 2a 2a  internal data.**
103f0 20 73 74 72 75 63 74 75 72 65 73 2e 20 20 54 68   structures.  Th
10400 65 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68  e xShutdown meth
10410 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64 20 28 69  od is invoked (i
10420 6e 64 69 72 65 63 74 6c 79 29 20 62 79 0a 2a 2a  ndirectly) by.**
10430 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f   [sqlite3_shutdo
10440 77 6e 28 29 5d 20 61 6e 64 20 73 68 6f 75 6c 64  wn()] and should
10450 20 64 65 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20   deallocate any 
10460 72 65 73 6f 75 72 63 65 73 20 61 63 71 75 69 72  resources acquir
10470 65 64 0a 2a 2a 20 62 79 20 78 49 6e 69 74 2e 20  ed.** by xInit. 
10480 20 54 68 65 20 70 41 70 70 44 61 74 61 20 70 6f   The pAppData po
10490 69 6e 74 65 72 20 69 73 20 75 73 65 64 20 61 73  inter is used as
104a0 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65   the only parame
104b0 74 65 72 20 74 6f 0a 2a 2a 20 78 49 6e 69 74 20  ter to.** xInit 
104c0 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 2e 0a 2a  and xShutdown..*
104d0 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 68 6f 6c 64  *.** SQLite hold
104e0 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55  s the [SQLITE_MU
104f0 54 45 58 5f 53 54 41 54 49 43 5f 4d 41 53 54 45  TEX_STATIC_MASTE
10500 52 5d 20 6d 75 74 65 78 20 77 68 65 6e 20 69 74  R] mutex when it
10510 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 74 68 65 20   invokes.** the 
10520 78 49 6e 69 74 20 6d 65 74 68 6f 64 2c 20 73 6f  xInit method, so
10530 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f   the xInit metho
10540 64 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 74 68  d need not be th
10550 72 65 61 64 73 61 66 65 2e 20 20 54 68 65 0a 2a  readsafe.  The.*
10560 2a 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68  * xShutdown meth
10570 6f 64 20 69 73 20 6f 6e 6c 79 20 63 61 6c 6c 65  od is only calle
10580 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
10590 73 68 75 74 64 6f 77 6e 28 29 5d 20 73 6f 20 69  shutdown()] so i
105a0 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 6e 65  t does.** not ne
105b0 65 64 20 74 6f 20 62 65 20 74 68 72 65 61 64 73  ed to be threads
105c0 61 66 65 20 65 69 74 68 65 72 2e 20 20 46 6f 72  afe either.  For
105d0 20 61 6c 6c 20 6f 74 68 65 72 20 6d 65 74 68 6f   all other metho
105e0 64 73 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 68 6f  ds, SQLite.** ho
105f0 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  lds the [SQLITE_
10600 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d  MUTEX_STATIC_MEM
10610 5d 20 6d 75 74 65 78 20 61 73 20 6c 6f 6e 67 20  ] mutex as long 
10620 61 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  as the.** [SQLIT
10630 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54  E_CONFIG_MEMSTAT
10640 55 53 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  US] configuratio
10650 6e 20 6f 70 74 69 6f 6e 20 69 73 20 74 75 72 6e  n option is turn
10660 65 64 20 6f 6e 20 28 77 68 69 63 68 0a 2a 2a 20  ed on (which.** 
10670 69 74 20 69 73 20 62 79 20 64 65 66 61 75 6c 74  it is by default
10680 29 20 61 6e 64 20 73 6f 20 74 68 65 20 6d 65 74  ) and so the met
10690 68 6f 64 73 20 61 72 65 20 61 75 74 6f 6d 61 74  hods are automat
106a0 69 63 61 6c 6c 79 20 73 65 72 69 61 6c 69 7a 65  ically serialize
106b0 64 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 69  d..** However, i
106c0 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  f [SQLITE_CONFIG
106d0 5f 4d 45 4d 53 54 41 54 55 53 5d 20 69 73 20 64  _MEMSTATUS] is d
106e0 69 73 61 62 6c 65 64 2c 20 74 68 65 6e 20 74 68  isabled, then th
106f0 65 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 74 68 6f  e other.** metho
10700 64 73 20 6d 75 73 74 20 62 65 20 74 68 72 65 61  ds must be threa
10710 64 73 61 66 65 20 6f 72 20 65 6c 73 65 20 6d 61  dsafe or else ma
10720 6b 65 20 74 68 65 69 72 20 6f 77 6e 20 61 72 72  ke their own arr
10730 61 6e 67 65 6d 65 6e 74 73 20 66 6f 72 0a 2a 2a  angements for.**
10740 20 73 65 72 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a   serialization..
10750 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c  **.** SQLite wil
10760 6c 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 78  l never invoke x
10770 49 6e 69 74 28 29 20 6d 6f 72 65 20 74 68 61 6e  Init() more than
10780 20 6f 6e 63 65 20 77 69 74 68 6f 75 74 20 61 6e   once without an
10790 20 69 6e 74 65 72 76 65 6e 69 6e 67 0a 2a 2a 20   intervening.** 
107a0 63 61 6c 6c 20 74 6f 20 78 53 68 75 74 64 6f 77  call to xShutdow
107b0 6e 28 29 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  n()..*/.typedef 
107c0 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d  struct sqlite3_m
107d0 65 6d 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74  em_methods sqlit
107e0 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 3b 0a  e3_mem_methods;.
107f0 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d  struct sqlite3_m
10800 65 6d 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 76  em_methods {.  v
10810 6f 69 64 20 2a 28 2a 78 4d 61 6c 6c 6f 63 29 28  oid *(*xMalloc)(
10820 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20 2f 2a  int);         /*
10830 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   Memory allocati
10840 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20  on function */. 
10850 20 76 6f 69 64 20 28 2a 78 46 72 65 65 29 28 76   void (*xFree)(v
10860 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20  oid*);          
10870 2f 2a 20 46 72 65 65 20 61 20 70 72 69 6f 72 20  /* Free a prior 
10880 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20  allocation */.  
10890 76 6f 69 64 20 2a 28 2a 78 52 65 61 6c 6c 6f 63  void *(*xRealloc
108a0 29 28 76 6f 69 64 2a 2c 69 6e 74 29 3b 20 20 2f  )(void*,int);  /
108b0 2a 20 52 65 73 69 7a 65 20 61 6e 20 61 6c 6c 6f  * Resize an allo
108c0 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20  cation */.  int 
108d0 28 2a 78 53 69 7a 65 29 28 76 6f 69 64 2a 29 3b  (*xSize)(void*);
108e0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52 65             /* Re
108f0 74 75 72 6e 20 74 68 65 20 73 69 7a 65 20 6f 66  turn the size of
10900 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a   an allocation *
10910 2f 0a 20 20 69 6e 74 20 28 2a 78 52 6f 75 6e 64  /.  int (*xRound
10920 75 70 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20  up)(int);       
10930 20 20 20 2f 2a 20 52 6f 75 6e 64 20 75 70 20 72     /* Round up r
10940 65 71 75 65 73 74 20 73 69 7a 65 20 74 6f 20 61  equest size to a
10950 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 2a  llocation size *
10960 2f 0a 20 20 69 6e 74 20 28 2a 78 49 6e 69 74 29  /.  int (*xInit)
10970 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20  (void*);        
10980 20 20 20 2f 2a 20 49 6e 69 74 69 61 6c 69 7a 65     /* Initialize
10990 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   the memory allo
109a0 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20  cator */.  void 
109b0 28 2a 78 53 68 75 74 64 6f 77 6e 29 28 76 6f 69  (*xShutdown)(voi
109c0 64 2a 29 3b 20 20 20 20 20 20 2f 2a 20 44 65 69  d*);      /* Dei
109d0 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65  nitialize the me
109e0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a  mory allocator *
109f0 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61  /.  void *pAppDa
10a00 74 61 3b 20 20 20 20 20 20 20 20 20 20 20 20 20  ta;             
10a10 20 20 20 2f 2a 20 41 72 67 75 6d 65 6e 74 20 74     /* Argument t
10a20 6f 20 78 49 6e 69 74 28 29 20 61 6e 64 20 78 53  o xInit() and xS
10a30 68 75 74 64 6f 77 6e 28 29 20 2a 2f 0a 7d 3b 0a  hutdown() */.};.
10a40 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
10a50 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f   Configuration O
10a60 70 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52  ptions.** KEYWOR
10a70 44 53 3a 20 7b 63 6f 6e 66 69 67 75 72 61 74 69  DS: {configurati
10a80 6f 6e 20 6f 70 74 69 6f 6e 7d 0a 2a 2a 0a 2a 2a  on option}.**.**
10a90 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73   These constants
10aa0 20 61 72 65 20 74 68 65 20 61 76 61 69 6c 61 62   are the availab
10ab0 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69  le integer confi
10ac0 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73  guration options
10ad0 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20   that.** can be 
10ae0 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66 69  passed as the fi
10af0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
10b00 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  the [sqlite3_con
10b10 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65  fig()] interface
10b20 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66  ..**.** New conf
10b30 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
10b40 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69  s may be added i
10b50 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  n future release
10b60 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20  s of SQLite..** 
10b70 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75  Existing configu
10b80 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d  ration options m
10b90 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69  ight be disconti
10ba0 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69  nued.  Applicati
10bb0 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68  ons.** should ch
10bc0 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63  eck the return c
10bd0 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ode from [sqlite
10be0 33 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d  3_config()] to m
10bf0 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a  ake sure that.**
10c00 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64   the call worked
10c10 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  .  The [sqlite3_
10c20 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66  config()] interf
10c30 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ace will return 
10c40 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65  a.** non-zero [e
10c50 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20  rror code] if a 
10c60 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20  discontinued or 
10c70 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66  unsupported conf
10c80 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
10c90 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a  .** is invoked..
10ca0 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b  **.** <dl>.** [[
10cb0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49  SQLITE_CONFIG_SI
10cc0 4e 47 4c 45 54 48 52 45 41 44 5d 5d 20 3c 64 74  NGLETHREAD]] <dt
10cd0 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  >SQLITE_CONFIG_S
10ce0 49 4e 47 4c 45 54 48 52 45 41 44 3c 2f 64 74 3e  INGLETHREAD</dt>
10cf0 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72  .** <dd>There ar
10d00 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74  e no arguments t
10d10 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20  o this option.  
10d20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74  ^This option set
10d30 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64  s the.** [thread
10d40 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 69 6e  ing mode] to Sin
10d50 67 6c 65 2d 74 68 72 65 61 64 2e 20 20 49 6e 20  gle-thread.  In 
10d60 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20  other words, it 
10d70 64 69 73 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20  disables.** all 
10d80 6d 75 74 65 78 69 6e 67 20 61 6e 64 20 70 75 74  mutexing and put
10d90 73 20 53 51 4c 69 74 65 20 69 6e 74 6f 20 61 20  s SQLite into a 
10da0 6d 6f 64 65 20 77 68 65 72 65 20 69 74 20 63 61  mode where it ca
10db0 6e 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 0a 2a  n only be used.*
10dc0 2a 20 62 79 20 61 20 73 69 6e 67 6c 65 20 74 68  * by a single th
10dd0 72 65 61 64 2e 20 20 20 5e 49 66 20 53 51 4c 69  read.   ^If SQLi
10de0 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
10df0 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49  ith.** the [SQLI
10e00 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20  TE_THREADSAFE | 
10e10 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
10e20 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  E=0] compile-tim
10e30 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a  e option then.**
10e40 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69   it is not possi
10e50 62 6c 65 20 74 6f 20 63 68 61 6e 67 65 20 74 68  ble to change th
10e60 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  e [threading mod
10e70 65 5d 20 66 72 6f 6d 20 69 74 73 20 64 65 66 61  e] from its defa
10e80 75 6c 74 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20  ult.** value of 
10e90 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 61 6e  Single-thread an
10ea0 64 20 73 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d so [sqlite3_co
10eb0 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74  nfig()] will ret
10ec0 75 72 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  urn .** [SQLITE_
10ed0 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64  ERROR] if called
10ee0 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45   with the SQLITE
10ef0 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48  _CONFIG_SINGLETH
10f00 52 45 41 44 0a 2a 2a 20 63 6f 6e 66 69 67 75 72  READ.** configur
10f10 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64  ation option.</d
10f20 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
10f30 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48  E_CONFIG_MULTITH
10f40 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  READ]] <dt>SQLIT
10f50 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48  E_CONFIG_MULTITH
10f60 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  READ</dt>.** <dd
10f70 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72  >There are no ar
10f80 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20  guments to this 
10f90 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f  option.  ^This o
10fa0 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a  ption sets the.*
10fb0 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  * [threading mod
10fc0 65 5d 20 74 6f 20 4d 75 6c 74 69 2d 74 68 72 65  e] to Multi-thre
10fd0 61 64 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f  ad.  In other wo
10fe0 72 64 73 2c 20 69 74 20 64 69 73 61 62 6c 65 73  rds, it disables
10ff0 0a 2a 2a 20 6d 75 74 65 78 69 6e 67 20 6f 6e 20  .** mutexing on 
11000 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
11010 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61  tion] and [prepa
11020 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f  red statement] o
11030 62 6a 65 63 74 73 2e 0a 2a 2a 20 54 68 65 20 61  bjects..** The a
11040 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 72 65  pplication is re
11050 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 73 65  sponsible for se
11060 72 69 61 6c 69 7a 69 6e 67 20 61 63 63 65 73 73  rializing access
11070 20 74 6f 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65   to.** [database
11080 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e   connections] an
11090 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  d [prepared stat
110a0 65 6d 65 6e 74 73 5d 2e 20 20 42 75 74 20 6f 74  ements].  But ot
110b0 68 65 72 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61  her mutexes.** a
110c0 72 65 20 65 6e 61 62 6c 65 64 20 73 6f 20 74 68  re enabled so th
110d0 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62  at SQLite will b
110e0 65 20 73 61 66 65 20 74 6f 20 75 73 65 20 69 6e  e safe to use in
110f0 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65   a multi-threade
11100 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e 6d 65 6e 74  d.** environment
11110 20 61 73 20 6c 6f 6e 67 20 61 73 20 6e 6f 20 74   as long as no t
11120 77 6f 20 74 68 72 65 61 64 73 20 61 74 74 65 6d  wo threads attem
11130 70 74 20 74 6f 20 75 73 65 20 74 68 65 20 73 61  pt to use the sa
11140 6d 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  me.** [database 
11150 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 74 20 74  connection] at t
11160 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 20 20 5e  he same time.  ^
11170 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
11180 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68  piled with.** th
11190 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
111a0 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48  SAFE | SQLITE_TH
111b0 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70  READSAFE=0] comp
111c0 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
111d0 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f  then.** it is no
111e0 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 73 65  t possible to se
111f0 74 20 74 68 65 20 4d 75 6c 74 69 2d 74 68 72 65  t the Multi-thre
11200 61 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ad [threading mo
11210 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  de] and.** [sqli
11220 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69  te3_config()] wi
11230 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ll return [SQLIT
11240 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c  E_ERROR] if call
11250 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53  ed with the.** S
11260 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c  QLITE_CONFIG_MUL
11270 54 49 54 48 52 45 41 44 20 63 6f 6e 66 69 67 75  TITHREAD configu
11280 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f  ration option.</
11290 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
112a0 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c  TE_CONFIG_SERIAL
112b0 49 5a 45 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  IZED]] <dt>SQLIT
112c0 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49  E_CONFIG_SERIALI
112d0 5a 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  ZED</dt>.** <dd>
112e0 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67  There are no arg
112f0 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f  uments to this o
11300 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70  ption.  ^This op
11310 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a  tion sets the.**
11320 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
11330 5d 20 74 6f 20 53 65 72 69 61 6c 69 7a 65 64 2e  ] to Serialized.
11340 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
11350 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 65 6e 61   this option ena
11360 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65  bles.** all mute
11370 78 65 73 20 69 6e 63 6c 75 64 69 6e 67 20 74 68  xes including th
11380 65 20 72 65 63 75 72 73 69 76 65 0a 2a 2a 20 6d  e recursive.** m
11390 75 74 65 78 65 73 20 6f 6e 20 5b 64 61 74 61 62  utexes on [datab
113a0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
113b0 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  and [prepared st
113c0 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73  atement] objects
113d0 2e 0a 2a 2a 20 49 6e 20 74 68 69 73 20 6d 6f 64  ..** In this mod
113e0 65 20 28 77 68 69 63 68 20 69 73 20 74 68 65 20  e (which is the 
113f0 64 65 66 61 75 6c 74 20 77 68 65 6e 20 53 51 4c  default when SQL
11400 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
11410 77 69 74 68 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  with.** [SQLITE_
11420 54 48 52 45 41 44 53 41 46 45 3d 31 5d 29 20 74  THREADSAFE=1]) t
11430 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72  he SQLite librar
11440 79 20 77 69 6c 6c 20 69 74 73 65 6c 66 20 73 65  y will itself se
11450 72 69 61 6c 69 7a 65 20 61 63 63 65 73 73 0a 2a  rialize access.*
11460 2a 20 74 6f 20 5b 64 61 74 61 62 61 73 65 20 63  * to [database c
11470 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20  onnections] and 
11480 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
11490 65 6e 74 73 5d 20 73 6f 20 74 68 61 74 20 74 68  ents] so that th
114a0 65 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e  e.** application
114b0 20 69 73 20 66 72 65 65 20 74 6f 20 75 73 65 20   is free to use 
114c0 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61  the same [databa
114d0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f  se connection] o
114e0 72 20 74 68 65 0a 2a 2a 20 73 61 6d 65 20 5b 70  r the.** same [p
114f0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
11500 74 5d 20 69 6e 20 64 69 66 66 65 72 65 6e 74 20  t] in different 
11510 74 68 72 65 61 64 73 20 61 74 20 74 68 65 20 73  threads at the s
11520 61 6d 65 20 74 69 6d 65 2e 0a 2a 2a 20 5e 49 66  ame time..** ^If
11530 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
11540 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20  led with.** the 
11550 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
11560 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45  FE | SQLITE_THRE
11570 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c  ADSAFE=0] compil
11580 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68  e-time option th
11590 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20  en.** it is not 
115a0 70 6f 73 73 69 62 6c 65 20 74 6f 20 73 65 74 20  possible to set 
115b0 74 68 65 20 53 65 72 69 61 6c 69 7a 65 64 20 5b  the Serialized [
115c0 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
115d0 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
115e0 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72  config()] will r
115f0 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52  eturn [SQLITE_ER
11600 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77  ROR] if called w
11610 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54  ith the.** SQLIT
11620 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49  E_CONFIG_SERIALI
11630 5a 45 44 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ZED configuratio
11640 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a  n option.</dd>.*
11650 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
11660 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c 64  NFIG_MALLOC]] <d
11670 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
11680 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c  MALLOC</dt>.** <
11690 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f  dd> ^(This optio
116a0 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
116b0 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20   argument which 
116c0 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
116d0 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f  an.** instance o
116e0 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
116f0 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75  em_methods] stru
11700 63 74 75 72 65 2e 20 20 54 68 65 20 61 72 67 75  cture.  The argu
11710 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73 0a 2a  ment specifies.*
11720 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f  * alternative lo
11730 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61  w-level memory a
11740 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e  llocation routin
11750 65 73 20 74 6f 20 62 65 20 75 73 65 64 20 69 6e  es to be used in
11760 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 74 68 65   place of.** the
11770 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
11780 6f 6e 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c  on routines buil
11790 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e  t into SQLite.)^
117a0 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 0a 2a   ^SQLite makes.*
117b0 2a 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74  * its own privat
117c0 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 63 6f  e copy of the co
117d0 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71  ntent of the [sq
117e0 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
117f0 73 5d 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20  s] structure.** 
11800 62 65 66 6f 72 65 20 74 68 65 20 5b 73 71 6c 69  before the [sqli
11810 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61  te3_config()] ca
11820 6c 6c 20 72 65 74 75 72 6e 73 2e 3c 2f 64 64 3e  ll returns.</dd>
11830 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
11840 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43  CONFIG_GETMALLOC
11850 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
11860 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 3c 2f  NFIG_GETMALLOC</
11870 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68  dt>.** <dd> ^(Th
11880 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
11890 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
118a0 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69  t which is a poi
118b0 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e  nter to an.** in
118c0 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73  stance of the [s
118d0 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
118e0 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20  ds] structure.  
118f0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  The [sqlite3_mem
11900 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72  _methods].** str
11910 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64  ucture is filled
11920 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e   with the curren
11930 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 65 6d 6f  tly defined memo
11940 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f  ry allocation ro
11950 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69  utines.)^.** Thi
11960 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20  s option can be 
11970 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64  used to overload
11980 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 65 6d   the default mem
11990 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a  ory allocation.*
119a0 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20  * routines with 
119b0 61 20 77 72 61 70 70 65 72 20 74 68 61 74 20 73  a wrapper that s
119c0 69 6d 75 6c 61 74 69 6f 6e 73 20 6d 65 6d 6f 72  imulations memor
119d0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69  y allocation fai
119e0 6c 75 72 65 20 6f 72 0a 2a 2a 20 74 72 61 63 6b  lure or.** track
119f0 73 20 6d 65 6d 6f 72 79 20 75 73 61 67 65 2c 20  s memory usage, 
11a00 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 3c 2f 64  for example. </d
11a10 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
11a20 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54  E_CONFIG_MEMSTAT
11a30 55 53 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  US]] <dt>SQLITE_
11a40 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53  CONFIG_MEMSTATUS
11a50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
11a60 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
11a70 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
11a80 20 6f 66 20 74 79 70 65 20 69 6e 74 2c 20 69 6e   of type int, in
11a90 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20 0a  terpreted as a .
11aa0 2a 2a 20 62 6f 6f 6c 65 61 6e 2c 20 77 68 69 63  ** boolean, whic
11ab0 68 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73  h enables or dis
11ac0 61 62 6c 65 73 20 74 68 65 20 63 6f 6c 6c 65 63  ables the collec
11ad0 74 69 6f 6e 20 6f 66 20 6d 65 6d 6f 72 79 20 61  tion of memory a
11ae0 6c 6c 6f 63 61 74 69 6f 6e 20 0a 2a 2a 20 73 74  llocation .** st
11af0 61 74 69 73 74 69 63 73 2e 20 5e 28 57 68 65 6e  atistics. ^(When
11b00 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
11b10 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 61 72  on statistics ar
11b20 65 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65 20  e disabled, the 
11b30 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51  .** following SQ
11b40 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20  Lite interfaces 
11b50 62 65 63 6f 6d 65 20 6e 6f 6e 2d 6f 70 65 72 61  become non-opera
11b60 74 69 6f 6e 61 6c 3a 0a 2a 2a 20 20 20 3c 75 6c  tional:.**   <ul
11b70 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c  >.**   <li> [sql
11b80 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64  ite3_memory_used
11b90 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73  ()].**   <li> [s
11ba0 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69  qlite3_memory_hi
11bb0 67 68 77 61 74 65 72 28 29 5d 0a 2a 2a 20 20 20  ghwater()].**   
11bc0 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 6f  <li> [sqlite3_so
11bd0 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28  ft_heap_limit64(
11be0 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71  )].**   <li> [sq
11bf0 6c 69 74 65 33 5f 73 74 61 74 75 73 28 29 5d 0a  lite3_status()].
11c00 2a 2a 20 20 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20  **   </ul>)^.** 
11c10 5e 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69  ^Memory allocati
11c20 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 61 72  on statistics ar
11c30 65 20 65 6e 61 62 6c 65 64 20 62 79 20 64 65 66  e enabled by def
11c40 61 75 6c 74 20 75 6e 6c 65 73 73 20 53 51 4c 69  ault unless SQLi
11c50 74 65 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65  te is.** compile
11c60 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 44  d with [SQLITE_D
11c70 45 46 41 55 4c 54 5f 4d 45 4d 53 54 41 54 55 53  EFAULT_MEMSTATUS
11c80 5d 3d 30 20 69 6e 20 77 68 69 63 68 20 63 61 73  ]=0 in which cas
11c90 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f  e memory.** allo
11ca0 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63  cation statistic
11cb0 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 62  s are disabled b
11cc0 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 3c 2f  y default..** </
11cd0 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
11ce0 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43  TE_CONFIG_SCRATC
11cf0 48 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  H]] <dt>SQLITE_C
11d00 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 3c 2f 64  ONFIG_SCRATCH</d
11d10 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73  t>.** <dd> ^This
11d20 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65   option specifie
11d30 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72  s a static memor
11d40 79 20 62 75 66 66 65 72 20 74 68 61 74 20 53 51  y buffer that SQ
11d50 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72  Lite can use for
11d60 0a 2a 2a 20 73 63 72 61 74 63 68 20 6d 65 6d 6f  .** scratch memo
11d70 72 79 2e 20 20 54 68 65 72 65 20 61 72 65 20 74  ry.  There are t
11d80 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 3a 20  hree arguments: 
11d90 20 41 20 70 6f 69 6e 74 65 72 20 61 6e 20 38 2d   A pointer an 8-
11da0 62 79 74 65 0a 2a 2a 20 61 6c 69 67 6e 65 64 20  byte.** aligned 
11db0 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 66 72  memory buffer fr
11dc0 6f 6d 20 77 68 69 63 68 20 74 68 65 20 73 63 72  om which the scr
11dd0 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73  atch allocations
11de0 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 64 72 61 77   will be.** draw
11df0 6e 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65  n, the size of e
11e00 61 63 68 20 73 63 72 61 74 63 68 20 61 6c 6c 6f  ach scratch allo
11e10 63 61 74 69 6f 6e 20 28 73 7a 29 2c 0a 2a 2a 20  cation (sz),.** 
11e20 61 6e 64 20 74 68 65 20 6d 61 78 69 6d 75 6d 20  and the maximum 
11e30 6e 75 6d 62 65 72 20 6f 66 20 73 63 72 61 74 63  number of scratc
11e40 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 28 4e  h allocations (N
11e50 29 2e 20 20 54 68 65 20 73 7a 0a 2a 2a 20 61 72  ).  The sz.** ar
11e60 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 61  gument must be a
11e70 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 31 36 2e   multiple of 16.
11e80 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72  .** The first ar
11e90 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 61  gument must be a
11ea0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 38   pointer to an 8
11eb0 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20 62 75  -byte aligned bu
11ec0 66 66 65 72 0a 2a 2a 20 6f 66 20 61 74 20 6c 65  ffer.** of at le
11ed0 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f  ast sz*N bytes o
11ee0 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51  f memory..** ^SQ
11ef0 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 6e 6f  Lite will use no
11f00 20 6d 6f 72 65 20 74 68 61 6e 20 74 77 6f 20 73   more than two s
11f10 63 72 61 74 63 68 20 62 75 66 66 65 72 73 20 70  cratch buffers p
11f20 65 72 20 74 68 72 65 61 64 2e 20 20 53 6f 0a 2a  er thread.  So.*
11f30 2a 20 4e 20 73 68 6f 75 6c 64 20 62 65 20 73 65  * N should be se
11f40 74 20 74 6f 20 74 77 69 63 65 20 74 68 65 20 65  t to twice the e
11f50 78 70 65 63 74 65 64 20 6d 61 78 69 6d 75 6d 20  xpected maximum 
11f60 6e 75 6d 62 65 72 20 6f 66 20 74 68 72 65 61 64  number of thread
11f70 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69  s..** ^SQLite wi
11f80 6c 6c 20 6e 65 76 65 72 20 72 65 71 75 69 72 65  ll never require
11f90 20 61 20 73 63 72 61 74 63 68 20 62 75 66 66 65   a scratch buffe
11fa0 72 20 74 68 61 74 20 69 73 20 6d 6f 72 65 20 74  r that is more t
11fb0 68 61 6e 20 36 0a 2a 2a 20 74 69 6d 65 73 20 74  han 6.** times t
11fc0 68 65 20 64 61 74 61 62 61 73 65 20 70 61 67 65  he database page
11fd0 20 73 69 7a 65 2e 20 5e 49 66 20 53 51 4c 69 74   size. ^If SQLit
11fe0 65 20 6e 65 65 64 73 20 6e 65 65 64 73 20 61 64  e needs needs ad
11ff0 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 73 63 72 61  ditional.** scra
12000 74 63 68 20 6d 65 6d 6f 72 79 20 62 65 79 6f 6e  tch memory beyon
12010 64 20 77 68 61 74 20 69 73 20 70 72 6f 76 69 64  d what is provid
12020 65 64 20 62 79 20 74 68 69 73 20 63 6f 6e 66 69  ed by this confi
12030 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2c  guration option,
12040 20 74 68 65 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74   then .** [sqlit
12050 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 77 69 6c  e3_malloc()] wil
12060 6c 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74  l be used to obt
12070 61 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 6e  ain the memory n
12080 65 65 64 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  eeded.</dd>.**.*
12090 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
120a0 47 5f 50 41 47 45 43 41 43 48 45 5d 5d 20 3c 64  G_PAGECACHE]] <d
120b0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
120c0 50 41 47 45 43 41 43 48 45 3c 2f 64 74 3e 0a 2a  PAGECACHE</dt>.*
120d0 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74  * <dd> ^This opt
120e0 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20  ion specifies a 
120f0 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75  static memory bu
12100 66 66 65 72 20 74 68 61 74 20 53 51 4c 69 74 65  ffer that SQLite
12110 20 63 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20   can use for.** 
12120 74 68 65 20 64 61 74 61 62 61 73 65 20 70 61 67  the database pag
12130 65 20 63 61 63 68 65 20 77 69 74 68 20 74 68 65  e cache with the
12140 20 64 65 66 61 75 6c 74 20 70 61 67 65 20 63 61   default page ca
12150 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  che implementati
12160 6f 6e 2e 20 20 0a 2a 2a 20 54 68 69 73 20 63 6f  on.  .** This co
12170 6e 66 69 67 75 72 61 74 69 6f 6e 20 73 68 6f 75  nfiguration shou
12180 6c 64 20 6e 6f 74 20 62 65 20 75 73 65 64 20 69  ld not be used i
12190 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  f an application
121a0 2d 64 65 66 69 6e 65 20 70 61 67 65 0a 2a 2a 20  -define page.** 
121b0 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  cache implementa
121c0 74 69 6f 6e 20 69 73 20 6c 6f 61 64 65 64 20 75  tion is loaded u
121d0 73 69 6e 67 20 74 68 65 20 53 51 4c 49 54 45 5f  sing the SQLITE_
121e0 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 20 6f  CONFIG_PCACHE2 o
121f0 70 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65 72 65 20  ption..** There 
12200 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65  are three argume
12210 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69  nts to this opti
12220 6f 6e 3a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f  on: A pointer to
12230 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 0a   8-byte aligned.
12240 2a 2a 20 6d 65 6d 6f 72 79 2c 20 74 68 65 20 73  ** memory, the s
12250 69 7a 65 20 6f 66 20 65 61 63 68 20 70 61 67 65  ize of each page
12260 20 62 75 66 66 65 72 20 28 73 7a 29 2c 20 61 6e   buffer (sz), an
12270 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  d the number of 
12280 70 61 67 65 73 20 28 4e 29 2e 0a 2a 2a 20 54 68  pages (N)..** Th
12290 65 20 73 7a 20 61 72 67 75 6d 65 6e 74 20 73 68  e sz argument sh
122a0 6f 75 6c 64 20 62 65 20 74 68 65 20 73 69 7a 65  ould be the size
122b0 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74 20   of the largest 
122c0 64 61 74 61 62 61 73 65 20 70 61 67 65 0a 2a 2a  database page.**
122d0 20 28 61 20 70 6f 77 65 72 20 6f 66 20 74 77 6f   (a power of two
122e0 20 62 65 74 77 65 65 6e 20 35 31 32 20 61 6e 64   between 512 and
122f0 20 33 32 37 36 38 29 20 70 6c 75 73 20 61 20 6c   32768) plus a l
12300 69 74 74 6c 65 20 65 78 74 72 61 20 66 6f 72 20  ittle extra for 
12310 65 61 63 68 0a 2a 2a 20 70 61 67 65 20 68 65 61  each.** page hea
12320 64 65 72 2e 20 20 5e 54 68 65 20 70 61 67 65 20  der.  ^The page 
12330 68 65 61 64 65 72 20 73 69 7a 65 20 69 73 20 32  header size is 2
12340 30 20 74 6f 20 34 30 20 62 79 74 65 73 20 64 65  0 to 40 bytes de
12350 70 65 6e 64 69 6e 67 20 6f 6e 0a 2a 2a 20 74 68  pending on.** th
12360 65 20 68 6f 73 74 20 61 72 63 68 69 74 65 63 74  e host architect
12370 75 72 65 2e 20 20 5e 49 74 20 69 73 20 68 61 72  ure.  ^It is har
12380 6d 6c 65 73 73 2c 20 61 70 61 72 74 20 66 72 6f  mless, apart fro
12390 6d 20 74 68 65 20 77 61 73 74 65 64 20 6d 65 6d  m the wasted mem
123a0 6f 72 79 2c 0a 2a 2a 20 74 6f 20 6d 61 6b 65 20  ory,.** to make 
123b0 73 7a 20 61 20 6c 69 74 74 6c 65 20 74 6f 6f 20  sz a little too 
123c0 6c 61 72 67 65 2e 20 20 54 68 65 20 66 69 72 73  large.  The firs
123d0 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73 68  t.** argument sh
123e0 6f 75 6c 64 20 70 6f 69 6e 74 20 74 6f 20 61 6e  ould point to an
123f0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 66 20 61   allocation of a
12400 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74  t least sz*N byt
12410 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a  es of memory..**
12420 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73   ^SQLite will us
12430 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f  e the memory pro
12440 76 69 64 65 64 20 62 79 20 74 68 65 20 66 69 72  vided by the fir
12450 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  st argument to s
12460 61 74 69 73 66 79 20 69 74 73 0a 2a 2a 20 6d 65  atisfy its.** me
12470 6d 6f 72 79 20 6e 65 65 64 73 20 66 6f 72 20 74  mory needs for t
12480 68 65 20 66 69 72 73 74 20 4e 20 70 61 67 65 73  he first N pages
12490 20 74 68 61 74 20 69 74 20 61 64 64 73 20 74 6f   that it adds to
124a0 20 63 61 63 68 65 2e 20 20 5e 49 66 20 61 64 64   cache.  ^If add
124b0 69 74 69 6f 6e 61 6c 0a 2a 2a 20 70 61 67 65 20  itional.** page 
124c0 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 69 73 20  cache memory is 
124d0 6e 65 65 64 65 64 20 62 65 79 6f 6e 64 20 77 68  needed beyond wh
124e0 61 74 20 69 73 20 70 72 6f 76 69 64 65 64 20 62  at is provided b
124f0 79 20 74 68 69 73 20 6f 70 74 69 6f 6e 2c 20 74  y this option, t
12500 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 67 6f  hen.** SQLite go
12510 65 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d  es to [sqlite3_m
12520 61 6c 6c 6f 63 28 29 5d 20 66 6f 72 20 74 68 65  alloc()] for the
12530 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 74 6f 72   additional stor
12540 61 67 65 20 73 70 61 63 65 2e 0a 2a 2a 20 54 68  age space..** Th
12550 65 20 70 6f 69 6e 74 65 72 20 69 6e 20 74 68 65  e pointer in the
12560 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
12570 6d 75 73 74 0a 2a 2a 20 62 65 20 61 6c 69 67 6e  must.** be align
12580 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20  ed to an 8-byte 
12590 62 6f 75 6e 64 61 72 79 20 6f 72 20 73 75 62 73  boundary or subs
125a0 65 71 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20  equent behavior 
125b0 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c  of SQLite.** wil
125c0 6c 20 62 65 20 75 6e 64 65 66 69 6e 65 64 2e 3c  l be undefined.<
125d0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
125e0 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 5d  ITE_CONFIG_HEAP]
125f0 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
12600 46 49 47 5f 48 45 41 50 3c 2f 64 74 3e 0a 2a 2a  FIG_HEAP</dt>.**
12610 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69   <dd> ^This opti
12620 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 73  on specifies a s
12630 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66  tatic memory buf
12640 66 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 20  fer that SQLite 
12650 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 66 6f 72 20  will use.** for 
12660 61 6c 6c 20 6f 66 20 69 74 73 20 64 79 6e 61 6d  all of its dynam
12670 69 63 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ic memory alloca
12680 74 69 6f 6e 20 6e 65 65 64 73 20 62 65 79 6f 6e  tion needs beyon
12690 64 20 74 68 6f 73 65 20 70 72 6f 76 69 64 65 64  d those provided
126a0 0a 2a 2a 20 66 6f 72 20 62 79 20 5b 53 51 4c 49  .** for by [SQLI
126b0 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43  TE_CONFIG_SCRATC
126c0 48 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 43  H] and [SQLITE_C
126d0 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d  ONFIG_PAGECACHE]
126e0 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74  ..** There are t
126f0 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 3a 20  hree arguments: 
12700 41 6e 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65  An 8-byte aligne
12710 64 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  d pointer to the
12720 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74 68 65 20   memory,.** the 
12730 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
12740 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 62 75  in the memory bu
12750 66 66 65 72 2c 20 61 6e 64 20 74 68 65 20 6d 69  ffer, and the mi
12760 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e  nimum allocation
12770 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49 66 20 74 68   size..** ^If th
12780 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20  e first pointer 
12790 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e  (the memory poin
127a0 74 65 72 29 20 69 73 20 4e 55 4c 4c 2c 20 74 68  ter) is NULL, th
127b0 65 6e 20 53 51 4c 69 74 65 20 72 65 76 65 72 74  en SQLite revert
127c0 73 0a 2a 2a 20 74 6f 20 75 73 69 6e 67 20 69 74  s.** to using it
127d0 73 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79  s default memory
127e0 20 61 6c 6c 6f 63 61 74 6f 72 20 28 74 68 65 20   allocator (the 
127f0 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20  system malloc() 
12800 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 29 2c  implementation),
12810 0a 2a 2a 20 75 6e 64 6f 69 6e 67 20 61 6e 79 20  .** undoing any 
12820 70 72 69 6f 72 20 69 6e 76 6f 63 61 74 69 6f 6e  prior invocation
12830 20 6f 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46   of [SQLITE_CONF
12840 49 47 5f 4d 41 4c 4c 4f 43 5d 2e 20 20 5e 49 66  IG_MALLOC].  ^If
12850 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 70   the.** memory p
12860 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55  ointer is not NU
12870 4c 4c 20 61 6e 64 20 65 69 74 68 65 72 20 5b 53  LL and either [S
12880 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d  QLITE_ENABLE_MEM
12890 53 59 53 33 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c  SYS3] or.** [SQL
128a0 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59  ITE_ENABLE_MEMSY
128b0 53 35 5d 20 61 72 65 20 64 65 66 69 6e 65 64 2c  S5] are defined,
128c0 20 74 68 65 6e 20 74 68 65 20 61 6c 74 65 72 6e   then the altern
128d0 61 74 69 76 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20  ative memory.** 
128e0 61 6c 6c 6f 63 61 74 6f 72 20 69 73 20 65 6e 67  allocator is eng
128f0 61 67 65 64 20 74 6f 20 68 61 6e 64 6c 65 20 61  aged to handle a
12900 6c 6c 20 6f 66 20 53 51 4c 69 74 65 73 20 6d 65  ll of SQLites me
12910 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
12920 6e 65 65 64 73 2e 0a 2a 2a 20 54 68 65 20 66 69  needs..** The fi
12930 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65  rst pointer (the
12940 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29   memory pointer)
12950 20 6d 75 73 74 20 62 65 20 61 6c 69 67 6e 65 64   must be aligned
12960 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a   to an 8-byte.**
12970 20 62 6f 75 6e 64 61 72 79 20 6f 72 20 73 75 62   boundary or sub
12980 73 65 71 75 65 6e 74 20 62 65 68 61 76 69 6f 72  sequent behavior
12990 20 6f 66 20 53 51 4c 69 74 65 20 77 69 6c 6c 20   of SQLite will 
129a0 62 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  be undefined..**
129b0 20 54 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c   The minimum all
129c0 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 69 73 20  ocation size is 
129d0 63 61 70 70 65 64 20 61 74 20 32 2a 2a 31 32 2e  capped at 2**12.
129e0 20 52 65 61 73 6f 6e 61 62 6c 65 20 76 61 6c 75   Reasonable valu
129f0 65 73 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6d 69  es.** for the mi
12a00 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e  nimum allocation
12a10 20 73 69 7a 65 20 61 72 65 20 32 2a 2a 35 20 74   size are 2**5 t
12a20 68 72 6f 75 67 68 20 32 2a 2a 38 2e 3c 2f 64 64  hrough 2**8.</dd
12a30 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
12a40 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 5d 20  _CONFIG_MUTEX]] 
12a50 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
12a60 47 5f 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20  G_MUTEX</dt>.** 
12a70 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69  <dd> ^(This opti
12a80 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
12a90 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
12aa0 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
12ab0 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20   an.** instance 
12ac0 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
12ad0 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73  mutex_methods] s
12ae0 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 20 61  tructure.  The a
12af0 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65  rgument specifie
12b00 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 65  s.** alternative
12b10 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 75 74 65 78   low-level mutex
12b20 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20   routines to be 
12b30 75 73 65 64 20 69 6e 20 70 6c 61 63 65 0a 2a 2a  used in place.**
12b40 20 74 68 65 20 6d 75 74 65 78 20 72 6f 75 74 69   the mutex routi
12b50 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53  nes built into S
12b60 51 4c 69 74 65 2e 29 5e 20 20 5e 53 51 4c 69 74  QLite.)^  ^SQLit
12b70 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f  e makes a copy o
12b80 66 20 74 68 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74  f the.** content
12b90 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
12ba0 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20  _mutex_methods] 
12bb0 73 74 72 75 63 74 75 72 65 20 62 65 66 6f 72 65  structure before
12bc0 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20   the call to.** 
12bd0 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
12be0 29 5d 20 72 65 74 75 72 6e 73 2e 20 5e 49 66 20  )] returns. ^If 
12bf0 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
12c00 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b  ed with.** the [
12c10 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
12c20 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41  E | SQLITE_THREA
12c30 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65  DSAFE=0] compile
12c40 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65  -time option the
12c50 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 20  n.** the entire 
12c60 6d 75 74 65 78 69 6e 67 20 73 75 62 73 79 73 74  mutexing subsyst
12c70 65 6d 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72  em is omitted fr
12c80 6f 6d 20 74 68 65 20 62 75 69 6c 64 20 61 6e 64  om the build and
12c90 20 68 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a   hence calls to.
12ca0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
12cb0 69 67 28 29 5d 20 77 69 74 68 20 74 68 65 20 53  ig()] with the S
12cc0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54  QLITE_CONFIG_MUT
12cd0 45 58 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  EX configuration
12ce0 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20   option will.** 
12cf0 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45  return [SQLITE_E
12d00 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  RROR].</dd>.**.*
12d10 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
12d20 47 5f 47 45 54 4d 55 54 45 58 5d 5d 20 3c 64 74  G_GETMUTEX]] <dt
12d30 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  >SQLITE_CONFIG_G
12d40 45 54 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20  ETMUTEX</dt>.** 
12d50 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69  <dd> ^(This opti
12d60 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
12d70 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
12d80 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
12d90 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20   an.** instance 
12da0 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
12db0 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73  mutex_methods] s
12dc0 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 0a 2a  tructure.  The.*
12dd0 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  * [sqlite3_mutex
12de0 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72  _methods].** str
12df0 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64  ucture is filled
12e00 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e   with the curren
12e10 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 75 74 65  tly defined mute
12e20 78 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a  x routines.)^.**
12e30 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e   This option can
12e40 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72   be used to over
12e50 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c 74  load the default
12e60 20 6d 75 74 65 78 20 61 6c 6c 6f 63 61 74 69 6f   mutex allocatio
12e70 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69  n.** routines wi
12e80 74 68 20 61 20 77 72 61 70 70 65 72 20 75 73 65  th a wrapper use
12e90 64 20 74 6f 20 74 72 61 63 6b 20 6d 75 74 65 78  d to track mutex
12ea0 20 75 73 61 67 65 20 66 6f 72 20 70 65 72 66 6f   usage for perfo
12eb0 72 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f 66 69 6c  rmance.** profil
12ec0 69 6e 67 20 6f 72 20 74 65 73 74 69 6e 67 2c 20  ing or testing, 
12ed0 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 20 20 5e  for example.   ^
12ee0 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
12ef0 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68  piled with.** th
12f00 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
12f10 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48  SAFE | SQLITE_TH
12f20 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70  READSAFE=0] comp
12f30 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
12f40 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69  then.** the enti
12f50 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62 73  re mutexing subs
12f60 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65 64  ystem is omitted
12f70 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64 20   from the build 
12f80 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73 20  and hence calls 
12f90 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  to.** [sqlite3_c
12fa0 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74 68  onfig()] with th
12fb0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
12fc0 47 45 54 4d 55 54 45 58 20 63 6f 6e 66 69 67 75  GETMUTEX configu
12fd0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69  ration option wi
12fe0 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51  ll.** return [SQ
12ff0 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64  LITE_ERROR].</dd
13000 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
13010 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  _CONFIG_LOOKASID
13020 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  E]] <dt>SQLITE_C
13030 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c  ONFIG_LOOKASIDE<
13040 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54  /dt>.** <dd> ^(T
13050 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
13060 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 20 74   two arguments t
13070 68 61 74 20 64 65 74 65 72 6d 69 6e 65 20 74 68  hat determine th
13080 65 20 64 65 66 61 75 6c 74 0a 2a 2a 20 6d 65 6d  e default.** mem
13090 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66  ory allocation f
130a0 6f 72 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65  or the lookaside
130b0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
130c0 72 20 6f 6e 20 65 61 63 68 0a 2a 2a 20 5b 64 61  r on each.** [da
130d0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
130e0 6e 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20 61  n].  The first a
130f0 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a  rgument is the.*
13100 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c  * size of each l
13110 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20  ookaside buffer 
13120 73 6c 6f 74 20 61 6e 64 20 74 68 65 20 73 65 63  slot and the sec
13130 6f 6e 64 20 69 73 20 74 68 65 20 6e 75 6d 62 65  ond is the numbe
13140 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c  r of.** slots al
13150 6c 6f 63 61 74 65 64 20 74 6f 20 65 61 63 68 20  located to each 
13160 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
13170 69 6f 6e 2e 29 5e 20 20 5e 28 54 68 69 73 20 6f  ion.)^  ^(This o
13180 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a  ption sets the.*
13190 2a 20 3c 69 3e 64 65 66 61 75 6c 74 3c 2f 69 3e  * <i>default</i>
131a0 20 6c 6f 6f 6b 61 73 69 64 65 20 73 69 7a 65 2e   lookaside size.
131b0 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 44 42 43   The [SQLITE_DBC
131c0 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d  ONFIG_LOOKASIDE]
131d0 0a 2a 2a 20 76 65 72 62 20 74 6f 20 5b 73 71 6c  .** verb to [sql
131e0 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
131f0 5d 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  ] can be used to
13200 20 63 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b   change the look
13210 61 73 69 64 65 0a 2a 2a 20 63 6f 6e 66 69 67 75  aside.** configu
13220 72 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69  ration on indivi
13230 64 75 61 6c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  dual connections
13240 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  .)^ </dd>.**.** 
13250 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
13260 50 43 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53 51  PCACHE2]] <dt>SQ
13270 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
13280 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  HE2</dt>.** <dd>
13290 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74   ^(This option t
132a0 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
132b0 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20  gument which is 
132c0 61 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20  a pointer to.** 
132d0 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63  an [sqlite3_pcac
132e0 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a  he_methods2] obj
132f0 65 63 74 2e 20 20 54 68 69 73 20 6f 62 6a 65 63  ect.  This objec
13300 74 20 73 70 65 63 69 66 69 65 73 20 74 68 65 20  t specifies the 
13310 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 74 6f 20  interface.** to 
13320 61 20 63 75 73 74 6f 6d 20 70 61 67 65 20 63 61  a custom page ca
13330 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  che implementati
13340 6f 6e 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d  on.)^  ^SQLite m
13350 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74  akes a copy of t
13360 68 65 0a 2a 2a 20 6f 62 6a 65 63 74 20 61 6e 64  he.** object and
13370 20 75 73 65 73 20 69 74 20 66 6f 72 20 70 61 67   uses it for pag
13380 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 61  e cache memory a
13390 6c 6c 6f 63 61 74 69 6f 6e 73 2e 3c 2f 64 64 3e  llocations.</dd>
133a0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
133b0 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45  CONFIG_GETPCACHE
133c0 32 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  2]] <dt>SQLITE_C
133d0 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32  ONFIG_GETPCACHE2
133e0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28  </dt>.** <dd> ^(
133f0 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
13400 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
13410 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70  ent which is a p
13420 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20  ointer to an.** 
13430 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f  [sqlite3_pcache_
13440 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74  methods2] object
13450 2e 20 20 53 51 4c 69 74 65 20 63 6f 70 69 65 73  .  SQLite copies
13460 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 0a   of the current.
13470 2a 2a 20 70 61 67 65 20 63 61 63 68 65 20 69 6d  ** page cache im
13480 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 74  plementation int
13490 6f 20 74 68 61 74 20 6f 62 6a 65 63 74 2e 29 5e  o that object.)^
134a0 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53   </dd>.**.** [[S
134b0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47  QLITE_CONFIG_LOG
134c0 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
134d0 4e 46 49 47 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a 2a  NFIG_LOG</dt>.**
134e0 20 3c 64 64 3e 20 54 68 65 20 53 51 4c 49 54 45   <dd> The SQLITE
134f0 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69  _CONFIG_LOG opti
13500 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 63 6f  on is used to co
13510 6e 66 69 67 75 72 65 20 74 68 65 20 53 51 4c 69  nfigure the SQLi
13520 74 65 0a 2a 2a 20 67 6c 6f 62 61 6c 20 5b 65 72  te.** global [er
13530 72 6f 72 20 6c 6f 67 5d 2e 0a 2a 2a 20 28 5e 54  ror log]..** (^T
13540 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
13550 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 74 61 6b 65  _LOG option take
13560 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 3a  s two arguments:
13570 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 0a   a pointer to a.
13580 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68  ** function with
13590 20 61 20 63 61 6c 6c 20 73 69 67 6e 61 74 75 72   a call signatur
135a0 65 20 6f 66 20 76 6f 69 64 28 2a 29 28 76 6f 69  e of void(*)(voi
135b0 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61  d*,int,const cha
135c0 72 2a 29 2c 20 0a 2a 2a 20 61 6e 64 20 61 20 70  r*), .** and a p
135d0 6f 69 6e 74 65 72 20 74 6f 20 76 6f 69 64 2e 20  ointer to void. 
135e0 5e 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  ^If the function
135f0 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20   pointer is not 
13600 4e 55 4c 4c 2c 20 69 74 20 69 73 0a 2a 2a 20 69  NULL, it is.** i
13610 6e 76 6f 6b 65 64 20 62 79 20 5b 73 71 6c 69 74  nvoked by [sqlit
13620 65 33 5f 6c 6f 67 28 29 5d 20 74 6f 20 70 72 6f  e3_log()] to pro
13630 63 65 73 73 20 65 61 63 68 20 6c 6f 67 67 69 6e  cess each loggin
13640 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 68  g event.  ^If th
13650 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 6f  e.** function po
13660 69 6e 74 65 72 20 69 73 20 4e 55 4c 4c 2c 20 74  inter is NULL, t
13670 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28  he [sqlite3_log(
13680 29 5d 20 69 6e 74 65 72 66 61 63 65 20 62 65 63  )] interface bec
13690 6f 6d 65 73 20 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a  omes a no-op..**
136a0 20 5e 54 68 65 20 76 6f 69 64 20 70 6f 69 6e 74   ^The void point
136b0 65 72 20 74 68 61 74 20 69 73 20 74 68 65 20 73  er that is the s
136c0 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  econd argument t
136d0 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  o SQLITE_CONFIG_
136e0 4c 4f 47 20 69 73 0a 2a 2a 20 70 61 73 73 65 64  LOG is.** passed
136f0 20 74 68 72 6f 75 67 68 20 61 73 20 74 68 65 20   through as the 
13700 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
13710 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  to the applicati
13720 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65  on-defined logge
13730 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 68  r.** function wh
13740 65 6e 65 76 65 72 20 74 68 61 74 20 66 75 6e 63  enever that func
13750 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2e  tion is invoked.
13760 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61    ^The second pa
13770 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68  rameter to.** th
13780 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f  e logger functio
13790 6e 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74  n is a copy of t
137a0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
137b0 65 72 20 74 6f 20 74 68 65 20 63 6f 72 72 65 73  er to the corres
137c0 70 6f 6e 64 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  ponding.** [sqli
137d0 74 65 33 5f 6c 6f 67 28 29 5d 20 63 61 6c 6c 20  te3_log()] call 
137e0 61 6e 64 20 69 73 20 69 6e 74 65 6e 64 65 64 20  and is intended 
137f0 74 6f 20 62 65 20 61 20 5b 72 65 73 75 6c 74 20  to be a [result 
13800 63 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b  code] or an.** [
13810 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
13820 63 6f 64 65 5d 2e 20 20 5e 54 68 65 20 74 68 69  code].  ^The thi
13830 72 64 20 70 61 72 61 6d 65 74 65 72 20 70 61 73  rd parameter pas
13840 73 65 64 20 74 6f 20 74 68 65 20 6c 6f 67 67 65  sed to the logge
13850 72 20 69 73 0a 2a 2a 20 6c 6f 67 20 6d 65 73 73  r is.** log mess
13860 61 67 65 20 61 66 74 65 72 20 66 6f 72 6d 61 74  age after format
13870 74 69 6e 67 20 76 69 61 20 5b 73 71 6c 69 74 65  ting via [sqlite
13880 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 2e 0a 2a  3_snprintf()]..*
13890 2a 20 54 68 65 20 53 51 4c 69 74 65 20 6c 6f 67  * The SQLite log
138a0 67 69 6e 67 20 69 6e 74 65 72 66 61 63 65 20 69  ging interface i
138b0 73 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74 3b  s not reentrant;
138c0 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63   the logger func
138d0 74 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69 65 64  tion.** supplied
138e0 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74   by the applicat
138f0 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 69 6e 76  ion must not inv
13900 6f 6b 65 20 61 6e 79 20 53 51 4c 69 74 65 20 69  oke any SQLite i
13910 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 49 6e 20  nterface..** In 
13920 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64  a multi-threaded
13930 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20 74 68   application, th
13940 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
13950 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20  fined logger.** 
13960 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 62 65  function must be
13970 20 74 68 72 65 61 64 73 61 66 65 2e 20 3c 2f 64   threadsafe. </d
13980 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
13990 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 5d 20 3c  E_CONFIG_URI]] <
139a0 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
139b0 5f 55 52 49 0a 2a 2a 20 3c 64 64 3e 20 54 68 69  _URI.** <dd> Thi
139c0 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  s option takes a
139d0 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
139e0 20 6f 66 20 74 79 70 65 20 69 6e 74 2e 20 49 66   of type int. If
139f0 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 0a   non-zero, then.
13a00 2a 2a 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20  ** URI handling 
13a10 69 73 20 67 6c 6f 62 61 6c 6c 79 20 65 6e 61 62  is globally enab
13a20 6c 65 64 2e 20 49 66 20 74 68 65 20 70 61 72 61  led. If the para
13a30 6d 65 74 65 72 20 69 73 20 7a 65 72 6f 2c 20 74  meter is zero, t
13a40 68 65 6e 20 55 52 49 20 68 61 6e 64 6c 69 6e 67  hen URI handling
13a50 0a 2a 2a 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20  .** is globally 
13a60 64 69 73 61 62 6c 65 64 2e 20 49 66 20 55 52 49  disabled. If URI
13a70 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f   handling is glo
13a80 62 61 6c 6c 79 20 65 6e 61 62 6c 65 64 2c 20 61  bally enabled, a
13a90 6c 6c 20 66 69 6c 65 6e 61 6d 65 73 0a 2a 2a 20  ll filenames.** 
13aa0 70 61 73 73 65 64 20 74 6f 20 5b 73 71 6c 69 74  passed to [sqlit
13ab0 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c  e3_open()], [sql
13ac0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c  ite3_open_v2()],
13ad0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
13ae0 28 29 5d 20 6f 72 0a 2a 2a 20 73 70 65 63 69 66  ()] or.** specif
13af0 69 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 5b  ied as part of [
13b00 41 54 54 41 43 48 5d 20 63 6f 6d 6d 61 6e 64 73  ATTACH] commands
13b10 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64   are interpreted
13b20 20 61 73 20 55 52 49 73 2c 20 72 65 67 61 72 64   as URIs, regard
13b30 6c 65 73 73 0a 2a 2a 20 6f 66 20 77 68 65 74 68  less.** of wheth
13b40 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 5b 53  er or not the [S
13b50 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20  QLITE_OPEN_URI] 
13b60 66 6c 61 67 20 69 73 20 73 65 74 20 77 68 65 6e  flag is set when
13b70 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   the database.**
13b80 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f   connection is o
13b90 70 65 6e 65 64 2e 20 49 66 20 69 74 20 69 73 20  pened. If it is 
13ba0 67 6c 6f 62 61 6c 6c 79 20 64 69 73 61 62 6c 65  globally disable
13bb0 64 2c 20 66 69 6c 65 6e 61 6d 65 73 20 61 72 65  d, filenames are
13bc0 0a 2a 2a 20 6f 6e 6c 79 20 69 6e 74 65 72 70 72  .** only interpr
13bd0 65 74 65 64 20 61 73 20 55 52 49 73 20 69 66 20  eted as URIs if 
13be0 74 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  the SQLITE_OPEN_
13bf0 55 52 49 20 66 6c 61 67 20 69 73 20 73 65 74 20  URI flag is set 
13c00 77 68 65 6e 20 74 68 65 0a 2a 2a 20 64 61 74 61  when the.** data
13c10 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
13c20 69 73 20 6f 70 65 6e 65 64 2e 20 42 79 20 64 65  is opened. By de
13c30 66 61 75 6c 74 2c 20 55 52 49 20 68 61 6e 64 6c  fault, URI handl
13c40 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a  ing is globally.
13c50 2a 2a 20 64 69 73 61 62 6c 65 64 2e 20 54 68 65  ** disabled. The
13c60 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 6d   default value m
13c70 61 79 20 62 65 20 63 68 61 6e 67 65 64 20 62 79  ay be changed by
13c80 20 63 6f 6d 70 69 6c 69 6e 67 20 77 69 74 68 20   compiling with 
13c90 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55  the.** [SQLITE_U
13ca0 53 45 5f 55 52 49 5d 20 73 79 6d 62 6f 6c 20 64  SE_URI] symbol d
13cb0 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b  efined..**.** [[
13cc0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f  SQLITE_CONFIG_CO
13cd0 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41  VERING_INDEX_SCA
13ce0 4e 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  N]] <dt>SQLITE_C
13cf0 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49  ONFIG_COVERING_I
13d00 4e 44 45 58 5f 53 43 41 4e 0a 2a 2a 20 3c 64 64  NDEX_SCAN.** <dd
13d10 3e 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61  > This option ta
13d20 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 69 6e 74  kes a single int
13d30 65 67 65 72 20 61 72 67 75 6d 65 6e 74 20 77 68  eger argument wh
13d40 69 63 68 20 69 73 20 69 6e 74 65 72 70 72 65 74  ich is interpret
13d50 65 64 20 61 73 0a 2a 2a 20 61 20 62 6f 6f 6c 65  ed as.** a boole
13d60 61 6e 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 65  an in order to e
13d70 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65  nable or disable
13d80 20 74 68 65 20 75 73 65 20 6f 66 20 63 6f 76 65   the use of cove
13d90 72 69 6e 67 20 69 6e 64 69 63 65 73 20 66 6f 72  ring indices for
13da0 0a 2a 2a 20 66 75 6c 6c 20 74 61 62 6c 65 20 73  .** full table s
13db0 63 61 6e 73 20 69 6e 20 74 68 65 20 71 75 65 72  cans in the quer
13dc0 79 20 6f 70 74 69 6d 69 7a 65 72 2e 20 20 54 68  y optimizer.  Th
13dd0 65 20 64 65 66 61 75 6c 74 20 73 65 74 74 69 6e  e default settin
13de0 67 20 69 73 20 64 65 74 65 72 6d 69 6e 65 64 0a  g is determined.
13df0 2a 2a 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54  ** by the [SQLIT
13e00 45 5f 41 4c 4c 4f 57 5f 43 4f 56 45 52 49 4e 47  E_ALLOW_COVERING
13e10 5f 49 4e 44 45 58 5f 53 43 41 4e 5d 20 63 6f 6d  _INDEX_SCAN] com
13e20 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
13e30 2c 20 6f 72 20 69 73 20 22 6f 6e 22 0a 2a 2a 20  , or is "on".** 
13e40 69 66 20 74 68 61 74 20 63 6f 6d 70 69 6c 65 2d  if that compile-
13e50 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 6f  time option is o
13e60 6d 69 74 74 65 64 2e 0a 2a 2a 20 54 68 65 20 61  mitted..** The a
13e70 62 69 6c 69 74 79 20 74 6f 20 64 69 73 61 62 6c  bility to disabl
13e80 65 20 74 68 65 20 75 73 65 20 6f 66 20 63 6f 76  e the use of cov
13e90 65 72 69 6e 67 20 69 6e 64 69 63 65 73 20 66 6f  ering indices fo
13ea0 72 20 66 75 6c 6c 20 74 61 62 6c 65 20 73 63 61  r full table sca
13eb0 6e 73 0a 2a 2a 20 69 73 20 62 65 63 61 75 73 65  ns.** is because
13ec0 20 73 6f 6d 65 20 69 6e 63 6f 72 72 65 63 74 6c   some incorrectl
13ed0 79 20 63 6f 64 65 64 20 6c 65 67 61 63 79 20 61  y coded legacy a
13ee0 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 69 67 68  pplications migh
13ef0 74 20 6d 61 6c 66 75 6e 63 74 69 6f 6e 0a 2a 2a  t malfunction.**
13f00 20 6d 61 6c 66 75 6e 63 74 69 6f 6e 20 77 68 65   malfunction whe
13f10 6e 20 74 68 65 20 6f 70 74 69 6d 69 7a 61 74 69  n the optimizati
13f20 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 20 20  on is enabled.  
13f30 50 72 6f 76 69 64 69 6e 67 20 74 68 65 20 61 62  Providing the ab
13f40 69 6c 69 74 79 20 74 6f 0a 2a 2a 20 64 69 73 61  ility to.** disa
13f50 62 6c 65 20 74 68 65 20 6f 70 74 69 6d 69 7a 61  ble the optimiza
13f60 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 74 68 65 20  tion allows the 
13f70 6f 6c 64 65 72 2c 20 62 75 67 67 79 20 61 70 70  older, buggy app
13f80 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 74 6f  lication code to
13f90 20 77 6f 72 6b 0a 2a 2a 20 77 69 74 68 6f 75 74   work.** without
13fa0 20 63 68 61 6e 67 65 20 65 76 65 6e 20 77 69 74   change even wit
13fb0 68 20 6e 65 77 65 72 20 76 65 72 73 69 6f 6e 73  h newer versions
13fc0 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a   of SQLite..**.*
13fd0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
13fe0 47 5f 50 43 41 43 48 45 5d 5d 20 5b 5b 53 51 4c  G_PCACHE]] [[SQL
13ff0 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43  ITE_CONFIG_GETPC
14000 41 43 48 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51  ACHE]].** <dt>SQ
14010 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
14020 48 45 20 61 6e 64 20 53 51 4c 49 54 45 5f 43 4f  HE and SQLITE_CO
14030 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 0a 2a  NFIG_GETPCACHE.*
14040 2a 20 3c 64 64 3e 20 54 68 65 73 65 20 6f 70 74  * <dd> These opt
14050 69 6f 6e 73 20 61 72 65 20 6f 62 73 6f 6c 65 74  ions are obsolet
14060 65 20 61 6e 64 20 73 68 6f 75 6c 64 20 6e 6f 74  e and should not
14070 20 62 65 20 75 73 65 64 20 62 79 20 6e 65 77 20   be used by new 
14080 63 6f 64 65 2e 0a 2a 2a 20 54 68 65 79 20 61 72  code..** They ar
14090 65 20 72 65 74 61 69 6e 65 64 20 66 6f 72 20 62  e retained for b
140a0 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69  ackwards compati
140b0 62 69 6c 69 74 79 20 62 75 74 20 61 72 65 20 6e  bility but are n
140c0 6f 77 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 20 3c 2f  ow no-ops..** </
140d0 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
140e0 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47  TE_CONFIG_SQLLOG
140f0 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  ]].** <dt>SQLITE
14100 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 0a 2a  _CONFIG_SQLLOG.*
14110 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f  * <dd>This optio
14120 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61  n is only availa
14130 62 6c 65 20 69 66 20 73 71 6c 69 74 65 20 69 73  ble if sqlite is
14140 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74   compiled with t
14150 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e  he.** [SQLITE_EN
14160 41 42 4c 45 5f 53 51 4c 4c 4f 47 5d 20 70 72 65  ABLE_SQLLOG] pre
14170 2d 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f  -processor macro
14180 20 64 65 66 69 6e 65 64 2e 20 54 68 65 20 66 69   defined. The fi
14190 72 73 74 20 61 72 67 75 6d 65 6e 74 20 73 68 6f  rst argument sho
141a0 75 6c 64 0a 2a 2a 20 62 65 20 61 20 70 6f 69 6e  uld.** be a poin
141b0 74 65 72 20 74 6f 20 61 20 66 75 6e 63 74 69 6f  ter to a functio
141c0 6e 20 6f 66 20 74 79 70 65 20 76 6f 69 64 28 2a  n of type void(*
141d0 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a  )(void*,sqlite3*
141e0 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e  ,const char*, in
141f0 74 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e  t)..** The secon
14200 64 20 73 68 6f 75 6c 64 20 62 65 20 6f 66 20 74  d should be of t
14210 79 70 65 20 28 76 6f 69 64 2a 29 2e 20 54 68 65  ype (void*). The
14220 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
14230 6f 6b 65 64 20 62 79 20 74 68 65 20 6c 69 62 72  oked by the libr
14240 61 72 79 0a 2a 2a 20 69 6e 20 74 68 72 65 65 20  ary.** in three 
14250 73 65 70 61 72 61 74 65 20 63 69 72 63 75 6d 73  separate circums
14260 74 61 6e 63 65 73 2c 20 69 64 65 6e 74 69 66 69  tances, identifi
14270 65 64 20 62 79 20 74 68 65 20 76 61 6c 75 65 20  ed by the value 
14280 70 61 73 73 65 64 20 61 73 20 74 68 65 0a 2a 2a  passed as the.**
14290 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
142a0 72 2e 20 49 66 20 74 68 65 20 66 6f 75 72 74 68  r. If the fourth
142b0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 30 2c   parameter is 0,
142c0 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   then the databa
142d0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
142e0 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73   passed as the s
142f0 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 68  econd argument h
14300 61 73 20 6a 75 73 74 20 62 65 65 6e 20 6f 70 65  as just been ope
14310 6e 65 64 2e 20 54 68 65 20 74 68 69 72 64 20 61  ned. The third a
14320 72 67 75 6d 65 6e 74 0a 2a 2a 20 70 6f 69 6e 74  rgument.** point
14330 73 20 74 6f 20 61 20 62 75 66 66 65 72 20 63 6f  s to a buffer co
14340 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 6e 61 6d  ntaining the nam
14350 65 20 6f 66 20 74 68 65 20 6d 61 69 6e 20 64 61  e of the main da
14360 74 61 62 61 73 65 20 66 69 6c 65 2e 20 49 66 20  tabase file. If 
14370 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20 70 61  the.** fourth pa
14380 72 61 6d 65 74 65 72 20 69 73 20 31 2c 20 74 68  rameter is 1, th
14390 65 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  en the SQL state
143a0 6d 65 6e 74 20 74 68 61 74 20 74 68 65 20 74 68  ment that the th
143b0 69 72 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  ird parameter.**
143c0 20 70 6f 69 6e 74 73 20 74 6f 20 68 61 73 20 6a   points to has j
143d0 75 73 74 20 62 65 65 6e 20 65 78 65 63 75 74 65  ust been execute
143e0 64 2e 20 4f 72 2c 20 69 66 20 74 68 65 20 66 6f  d. Or, if the fo
143f0 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  urth parameter i
14400 73 20 32 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65  s 2, then.** the
14410 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 65 69 6e   connection bein
14420 67 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  g passed as the 
14430 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
14440 20 69 73 20 62 65 69 6e 67 20 63 6c 6f 73 65 64   is being closed
14450 2e 20 54 68 65 0a 2a 2a 20 74 68 69 72 64 20 70  . The.** third p
14460 61 72 61 6d 65 74 65 72 20 69 73 20 70 61 73 73  arameter is pass
14470 65 64 20 4e 55 4c 4c 20 49 6e 20 74 68 69 73 20  ed NULL In this 
14480 63 61 73 65 2e 20 20 41 6e 20 65 78 61 6d 70 6c  case.  An exampl
14490 65 20 6f 66 20 75 73 69 6e 67 20 74 68 69 73 0a  e of using this.
144a0 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ** configuration
144b0 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 73   option can be s
144c0 65 65 6e 20 69 6e 20 74 68 65 20 22 74 65 73 74  een in the "test
144d0 5f 73 71 6c 6c 6f 67 2e 63 22 20 73 6f 75 72 63  _sqllog.c" sourc
144e0 65 20 66 69 6c 65 20 69 6e 0a 2a 2a 20 74 68 65  e file in.** the
144f0 20 63 61 6e 6f 6e 69 63 61 6c 20 53 51 4c 69 74   canonical SQLit
14500 65 20 73 6f 75 72 63 65 20 74 72 65 65 2e 3c 2f  e source tree.</
14510 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
14520 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53  TE_CONFIG_MMAP_S
14530 49 5a 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c  IZE]].** <dt>SQL
14540 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f  ITE_CONFIG_MMAP_
14550 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e 53 51 4c 49  SIZE.** <dd>SQLI
14560 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53  TE_CONFIG_MMAP_S
14570 49 5a 45 20 74 61 6b 65 73 20 74 77 6f 20 36 34  IZE takes two 64
14580 2d 62 69 74 20 69 6e 74 65 67 65 72 20 28 73 71  -bit integer (sq
14590 6c 69 74 65 33 5f 69 6e 74 36 34 29 20 76 61 6c  lite3_int64) val
145a0 75 65 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20  ues.** that are 
145b0 74 68 65 20 64 65 66 61 75 6c 74 20 6d 6d 61 70  the default mmap
145c0 20 73 69 7a 65 20 6c 69 6d 69 74 20 28 74 68 65   size limit (the
145d0 20 64 65 66 61 75 6c 74 20 73 65 74 74 69 6e 67   default setting
145e0 20 66 6f 72 0a 2a 2a 20 5b 50 52 41 47 4d 41 20   for.** [PRAGMA 
145f0 6d 6d 61 70 5f 73 69 7a 65 5d 29 20 61 6e 64 20  mmap_size]) and 
14600 74 68 65 20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f  the maximum allo
14610 77 65 64 20 6d 6d 61 70 20 73 69 7a 65 20 6c 69  wed mmap size li
14620 6d 69 74 2e 0a 2a 2a 20 54 68 65 20 64 65 66 61  mit..** The defa
14630 75 6c 74 20 73 65 74 74 69 6e 67 20 63 61 6e 20  ult setting can 
14640 62 65 20 6f 76 65 72 72 69 64 64 65 6e 20 62 79  be overridden by
14650 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20 63   each database c
14660 6f 6e 6e 65 63 74 69 6f 6e 20 75 73 69 6e 67 0a  onnection using.
14670 2a 2a 20 65 69 74 68 65 72 20 74 68 65 20 5b 50  ** either the [P
14680 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d  RAGMA mmap_size]
14690 20 63 6f 6d 6d 61 6e 64 2c 20 6f 72 20 62 79 20   command, or by 
146a0 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 53 51  using the.** [SQ
146b0 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f  LITE_FCNTL_MMAP_
146c0 53 49 5a 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72  SIZE] file contr
146d0 6f 6c 2e 20 20 54 68 65 20 6d 61 78 69 6d 75 6d  ol.  The maximum
146e0 20 61 6c 6c 6f 77 65 64 20 6d 6d 61 70 20 73 69   allowed mmap si
146f0 7a 65 0a 2a 2a 20 63 61 6e 6e 6f 74 20 62 65 20  ze.** cannot be 
14700 63 68 61 6e 67 65 64 20 61 74 20 72 75 6e 2d 74  changed at run-t
14710 69 6d 65 2e 20 20 4e 6f 72 20 6d 61 79 20 74 68  ime.  Nor may th
14720 65 20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f 77 65  e maximum allowe
14730 64 20 6d 6d 61 70 20 73 69 7a 65 0a 2a 2a 20 65  d mmap size.** e
14740 78 63 65 65 64 20 74 68 65 20 63 6f 6d 70 69 6c  xceed the compil
14750 65 2d 74 69 6d 65 20 6d 61 78 69 6d 75 6d 20 6d  e-time maximum m
14760 6d 61 70 20 73 69 7a 65 20 73 65 74 20 62 79 20  map size set by 
14770 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d  the.** [SQLITE_M
14780 41 58 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 63 6f  AX_MMAP_SIZE] co
14790 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
147a0 6e 2e 20 20 0a 2a 2a 20 49 66 20 65 69 74 68 65  n.  .** If eithe
147b0 72 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  r argument to th
147c0 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 6e 65 67  is option is neg
147d0 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 61 74  ative, then that
147e0 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20   argument is.** 
147f0 63 68 61 6e 67 65 64 20 74 6f 20 69 74 73 20 63  changed to its c
14800 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 64 65 66 61  ompile-time defa
14810 75 6c 74 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f  ult..** </dl>.*/
14820 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
14830 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52  CONFIG_SINGLETHR
14840 45 41 44 20 20 31 20 20 2f 2a 20 6e 69 6c 20 2a  EAD  1  /* nil *
14850 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
14860 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
14870 45 41 44 20 20 20 32 20 20 2f 2a 20 6e 69 6c 20  EAD   2  /* nil 
14880 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
14890 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49  E_CONFIG_SERIALI
148a0 5a 45 44 20 20 20 20 33 20 20 2f 2a 20 6e 69 6c  ZED    3  /* nil
148b0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
148c0 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
148d0 20 20 20 20 20 20 20 20 34 20 20 2f 2a 20 73 71          4  /* sq
148e0 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
148f0 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  s* */.#define SQ
14900 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
14910 41 4c 4c 4f 43 20 20 20 20 20 35 20 20 2f 2a 20  ALLOC     5  /* 
14920 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
14930 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ods* */.#define 
14940 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43  SQLITE_CONFIG_SC
14950 52 41 54 43 48 20 20 20 20 20 20 20 36 20 20 2f  RATCH       6  /
14960 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c  * void*, int sz,
14970 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e   int N */.#defin
14980 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
14990 50 41 47 45 43 41 43 48 45 20 20 20 20 20 37 20  PAGECACHE     7 
149a0 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73   /* void*, int s
149b0 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66  z, int N */.#def
149c0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
149d0 47 5f 48 45 41 50 20 20 20 20 20 20 20 20 20 20  G_HEAP          
149e0 38 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74  8  /* void*, int
149f0 20 6e 42 79 74 65 2c 20 69 6e 74 20 6d 69 6e 20   nByte, int min 
14a00 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
14a10 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54  E_CONFIG_MEMSTAT
14a20 55 53 20 20 20 20 20 39 20 20 2f 2a 20 62 6f 6f  US     9  /* boo
14a30 6c 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20  lean */.#define 
14a40 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
14a50 54 45 58 20 20 20 20 20 20 20 20 31 30 20 20 2f  TEX        10  /
14a60 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  * sqlite3_mutex_
14a70 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66  methods* */.#def
14a80 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
14a90 47 5f 47 45 54 4d 55 54 45 58 20 20 20 20 20 31  G_GETMUTEX     1
14aa0 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75  1  /* sqlite3_mu
14ab0 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a  tex_methods* */.
14ac0 2f 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 53 51  /* previously SQ
14ad0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 48 55 4e  LITE_CONFIG_CHUN
14ae0 4b 41 4c 4c 4f 43 20 31 32 20 77 68 69 63 68 20  KALLOC 12 which 
14af0 69 73 20 6e 6f 77 20 75 6e 75 73 65 64 2e 20 2a  is now unused. *
14b00 2f 20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  / .#define SQLIT
14b10 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  E_CONFIG_LOOKASI
14b20 44 45 20 20 20 20 31 33 20 20 2f 2a 20 69 6e 74  DE    13  /* int
14b30 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20   int */.#define 
14b40 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
14b50 41 43 48 45 20 20 20 20 20 20 20 31 34 20 20 2f  ACHE       14  /
14b60 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 69  * no-op */.#defi
14b70 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
14b80 5f 47 45 54 50 43 41 43 48 45 20 20 20 20 31 35  _GETPCACHE    15
14b90 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64    /* no-op */.#d
14ba0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
14bb0 46 49 47 5f 4c 4f 47 20 20 20 20 20 20 20 20 20  FIG_LOG         
14bc0 20 31 36 20 20 2f 2a 20 78 46 75 6e 63 2c 20 76   16  /* xFunc, v
14bd0 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  oid* */.#define 
14be0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52  SQLITE_CONFIG_UR
14bf0 49 20 20 20 20 20 20 20 20 20 20 31 37 20 20 2f  I          17  /
14c00 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65  * int */.#define
14c10 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
14c20 43 41 43 48 45 32 20 20 20 20 20 20 31 38 20 20  CACHE2      18  
14c30 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68  /* sqlite3_pcach
14c40 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23  e_methods2* */.#
14c50 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
14c60 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 20  NFIG_GETPCACHE2 
14c70 20 20 31 39 20 20 2f 2a 20 73 71 6c 69 74 65 33    19  /* sqlite3
14c80 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32  _pcache_methods2
14c90 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
14ca0 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52  ITE_CONFIG_COVER
14cb0 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 20 32  ING_INDEX_SCAN 2
14cc0 30 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65  0  /* int */.#de
14cd0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
14ce0 49 47 5f 53 51 4c 4c 4f 47 20 20 20 20 20 20 20  IG_SQLLOG       
14cf0 32 31 20 20 2f 2a 20 78 53 71 6c 6c 6f 67 2c 20  21  /* xSqllog, 
14d00 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  void* */.#define
14d10 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
14d20 4d 41 50 5f 53 49 5a 45 20 20 20 20 32 32 20 20  MAP_SIZE    22  
14d30 2f 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  /* sqlite3_int64
14d40 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
14d50 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
14d60 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e  EF: Database Con
14d70 6e 65 63 74 69 6f 6e 20 43 6f 6e 66 69 67 75 72  nection Configur
14d80 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a  ation Options.**
14d90 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61  .** These consta
14da0 6e 74 73 20 61 72 65 20 74 68 65 20 61 76 61 69  nts are the avai
14db0 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f  lable integer co
14dc0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
14dd0 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20  ons that.** can 
14de0 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  be passed as the
14df0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
14e00 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
14e10 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e  _db_config()] in
14e20 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e  terface..**.** N
14e30 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ew configuration
14e40 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20   options may be 
14e50 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
14e60 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69  releases of SQLi
14e70 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20  te..** Existing 
14e80 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
14e90 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64  tions might be d
14ea0 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70  iscontinued.  Ap
14eb0 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68  plications.** sh
14ec0 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72  ould check the r
14ed0 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20  eturn code from 
14ee0 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66  [sqlite3_db_conf
14ef0 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75  ig()] to make su
14f00 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63  re that.** the c
14f10 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 5e 54 68  all worked.  ^Th
14f20 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  e [sqlite3_db_co
14f30 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63  nfig()] interfac
14f40 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a  e will return a.
14f50 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72  ** non-zero [err
14f60 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69  or code] if a di
14f70 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e  scontinued or un
14f80 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67  supported config
14f90 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a  uration option.*
14fa0 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a  * is invoked..**
14fb0 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e  .** <dl>.** <dt>
14fc0 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
14fd0 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a  LOOKASIDE</dt>.*
14fe0 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74  * <dd> ^This opt
14ff0 69 6f 6e 20 74 61 6b 65 73 20 74 68 72 65 65 20  ion takes three 
15000 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d  additional argum
15010 65 6e 74 73 20 74 68 61 74 20 64 65 74 65 72 6d  ents that determ
15020 69 6e 65 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f  ine the .** [loo
15030 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c  kaside memory al
15040 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e 66 69 67 75  locator] configu
15050 72 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 5b  ration for the [
15060 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
15070 69 6f 6e 5d 2e 0a 2a 2a 20 5e 54 68 65 20 66 69  ion]..** ^The fi
15080 72 73 74 20 61 72 67 75 6d 65 6e 74 20 28 74 68  rst argument (th
15090 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
150a0 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62  r to [sqlite3_db
150b0 5f 63 6f 6e 66 69 67 28 29 5d 20 69 73 20 61 0a  _config()] is a.
150c0 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20  ** pointer to a 
150d0 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 6f  memory buffer to
150e0 20 75 73 65 20 66 6f 72 20 6c 6f 6f 6b 61 73 69   use for lookasi
150f0 64 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 54  de memory..** ^T
15100 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
15110 74 20 61 66 74 65 72 20 74 68 65 20 53 51 4c 49  t after the SQLI
15120 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  TE_DBCONFIG_LOOK
15130 41 53 49 44 45 20 76 65 72 62 0a 2a 2a 20 6d 61  ASIDE verb.** ma
15140 79 20 62 65 20 4e 55 4c 4c 20 69 6e 20 77 68 69  y be NULL in whi
15150 63 68 20 63 61 73 65 20 53 51 4c 69 74 65 20 77  ch case SQLite w
15160 69 6c 6c 20 61 6c 6c 6f 63 61 74 65 20 74 68 65  ill allocate the
15170 0a 2a 2a 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75  .** lookaside bu
15180 66 66 65 72 20 69 74 73 65 6c 66 20 75 73 69 6e  ffer itself usin
15190 67 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  g [sqlite3_mallo
151a0 63 28 29 5d 2e 20 5e 54 68 65 20 73 65 63 6f 6e  c()]. ^The secon
151b0 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  d argument is th
151c0 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63  e.** size of eac
151d0 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66  h lookaside buff
151e0 65 72 20 73 6c 6f 74 2e 20 20 5e 54 68 65 20 74  er slot.  ^The t
151f0 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73  hird argument is
15200 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a   the number of.*
15210 2a 20 73 6c 6f 74 73 2e 20 20 54 68 65 20 73 69  * slots.  The si
15220 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66 65 72  ze of the buffer
15230 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72   in the first ar
15240 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 67  gument must be g
15250 72 65 61 74 65 72 20 74 68 61 6e 0a 2a 2a 20 6f  reater than.** o
15260 72 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20 70  r equal to the p
15270 72 6f 64 75 63 74 20 6f 66 20 74 68 65 20 73 65  roduct of the se
15280 63 6f 6e 64 20 61 6e 64 20 74 68 69 72 64 20 61  cond and third a
15290 72 67 75 6d 65 6e 74 73 2e 20 20 54 68 65 20 62  rguments.  The b
152a0 75 66 66 65 72 0a 2a 2a 20 6d 75 73 74 20 62 65  uffer.** must be
152b0 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38   aligned to an 8
152c0 2d 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2e 20  -byte boundary. 
152d0 20 5e 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20   ^If the second 
152e0 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 53  argument to.** S
152f0 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c  QLITE_DBCONFIG_L
15300 4f 4f 4b 41 53 49 44 45 20 69 73 20 6e 6f 74 20  OOKASIDE is not 
15310 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2c  a multiple of 8,
15320 20 69 74 20 69 73 20 69 6e 74 65 72 6e 61 6c 6c   it is internall
15330 79 0a 2a 2a 20 72 6f 75 6e 64 65 64 20 64 6f 77  y.** rounded dow
15340 6e 20 74 6f 20 74 68 65 20 6e 65 78 74 20 73 6d  n to the next sm
15350 61 6c 6c 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f  aller multiple o
15360 66 20 38 2e 20 20 5e 28 54 68 65 20 6c 6f 6f 6b  f 8.  ^(The look
15370 61 73 69 64 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20  aside memory.** 
15380 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f  configuration fo
15390 72 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e  r a database con
153a0 6e 65 63 74 69 6f 6e 20 63 61 6e 20 6f 6e 6c 79  nection can only
153b0 20 62 65 20 63 68 61 6e 67 65 64 20 77 68 65 6e   be changed when
153c0 20 74 68 61 74 0a 2a 2a 20 63 6f 6e 6e 65 63 74   that.** connect
153d0 69 6f 6e 20 69 73 20 6e 6f 74 20 63 75 72 72 65  ion is not curre
153e0 6e 74 6c 79 20 75 73 69 6e 67 20 6c 6f 6f 6b 61  ntly using looka
153f0 73 69 64 65 20 6d 65 6d 6f 72 79 2c 20 6f 72 20  side memory, or 
15400 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 0a 2a  in other words.*
15410 2a 20 77 68 65 6e 20 74 68 65 20 22 63 75 72 72  * when the "curr
15420 65 6e 74 20 76 61 6c 75 65 22 20 72 65 74 75 72  ent value" retur
15430 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74  ned by.** [sqlit
15440 65 33 5f 64 62 5f 73 74 61 74 75 73 5d 28 44 2c  e3_db_status](D,
15450 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c  [SQLITE_CONFIG_L
15460 4f 4f 4b 41 53 49 44 45 5d 2c 2e 2e 2e 29 20 69  OOKASIDE],...) i
15470 73 20 7a 65 72 6f 2e 0a 2a 2a 20 41 6e 79 20 61  s zero..** Any a
15480 74 74 65 6d 70 74 20 74 6f 20 63 68 61 6e 67 65  ttempt to change
15490 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d   the lookaside m
154a0 65 6d 6f 72 79 20 63 6f 6e 66 69 67 75 72 61 74  emory configurat
154b0 69 6f 6e 20 77 68 65 6e 20 6c 6f 6f 6b 61 73 69  ion when lookasi
154c0 64 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 69 73 20  de.** memory is 
154d0 69 6e 20 75 73 65 20 6c 65 61 76 65 73 20 74 68  in use leaves th
154e0 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  e configuration 
154f0 75 6e 63 68 61 6e 67 65 64 20 61 6e 64 20 72 65  unchanged and re
15500 74 75 72 6e 73 20 0a 2a 2a 20 5b 53 51 4c 49 54  turns .** [SQLIT
15510 45 5f 42 55 53 59 5d 2e 29 5e 3c 2f 64 64 3e 0a  E_BUSY].)^</dd>.
15520 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
15530 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45  _DBCONFIG_ENABLE
15540 5f 46 4b 45 59 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  _FKEY</dt>.** <d
15550 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  d> ^This option 
15560 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c  is used to enabl
15570 65 20 6f 72 20 64 69 73 61 62 6c 65 20 74 68 65  e or disable the
15580 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 66 0a   enforcement of.
15590 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20  ** [foreign key 
155a0 63 6f 6e 73 74 72 61 69 6e 74 73 5d 2e 20 20 54  constraints].  T
155b0 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74  here should be t
155c0 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72  wo additional ar
155d0 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20  guments..** The 
155e0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69  first argument i
155f0 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69  s an integer whi
15600 63 68 20 69 73 20 30 20 74 6f 20 64 69 73 61 62  ch is 0 to disab
15610 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e  le FK enforcemen
15620 74 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74  t,.** positive t
15630 6f 20 65 6e 61 62 6c 65 20 46 4b 20 65 6e 66 6f  o enable FK enfo
15640 72 63 65 6d 65 6e 74 20 6f 72 20 6e 65 67 61 74  rcement or negat
15650 69 76 65 20 74 6f 20 6c 65 61 76 65 20 46 4b 20  ive to leave FK 
15660 65 6e 66 6f 72 63 65 6d 65 6e 74 0a 2a 2a 20 75  enforcement.** u
15670 6e 63 68 61 6e 67 65 64 2e 20 20 54 68 65 20 73  nchanged.  The s
15680 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
15690 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
156a0 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20  an integer into 
156b0 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74  which.** is writ
156c0 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e  ten 0 or 1 to in
156d0 64 69 63 61 74 65 20 77 68 65 74 68 65 72 20 46  dicate whether F
156e0 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 69 73  K enforcement is
156f0 20 6f 66 66 20 6f 72 20 6f 6e 0a 2a 2a 20 66 6f   off or on.** fo
15700 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c  llowing this cal
15710 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70  l.  The second p
15720 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20  arameter may be 
15730 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  a NULL pointer, 
15740 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65  in.** which case
15750 20 74 68 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d   the FK enforcem
15760 65 6e 74 20 73 65 74 74 69 6e 67 20 69 73 20 6e  ent setting is n
15770 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b  ot reported back
15780 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  . </dd>.**.** <d
15790 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  t>SQLITE_DBCONFI
157a0 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 45 52  G_ENABLE_TRIGGER
157b0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
157c0 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73  his option is us
157d0 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20  ed to enable or 
157e0 64 69 73 61 62 6c 65 20 5b 43 52 45 41 54 45 20  disable [CREATE 
157f0 54 52 49 47 47 45 52 20 7c 20 74 72 69 67 67 65  TRIGGER | trigge
15800 72 73 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 73 68  rs]..** There sh
15810 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69  ould be two addi
15820 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73  tional arguments
15830 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61  ..** The first a
15840 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e  rgument is an in
15850 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20 30  teger which is 0
15860 20 74 6f 20 64 69 73 61 62 6c 65 20 74 72 69 67   to disable trig
15870 67 65 72 73 2c 0a 2a 2a 20 70 6f 73 69 74 69 76  gers,.** positiv
15880 65 20 74 6f 20 65 6e 61 62 6c 65 20 74 72 69 67  e to enable trig
15890 67 65 72 73 20 6f 72 20 6e 65 67 61 74 69 76 65  gers or negative
158a0 20 74 6f 20 6c 65 61 76 65 20 74 68 65 20 73 65   to leave the se
158b0 74 74 69 6e 67 20 75 6e 63 68 61 6e 67 65 64 2e  tting unchanged.
158c0 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70  .** The second p
158d0 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f  arameter is a po
158e0 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65  inter to an inte
158f0 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a  ger into which.*
15900 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f  * is written 0 o
15910 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20  r 1 to indicate 
15920 77 68 65 74 68 65 72 20 74 72 69 67 67 65 72 73  whether triggers
15930 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 6f 72   are disabled or
15940 20 65 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c   enabled.** foll
15950 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e  owing this call.
15960 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72    The second par
15970 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61 20  ameter may be a 
15980 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e  NULL pointer, in
15990 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20 74  .** which case t
159a0 68 65 20 74 72 69 67 67 65 72 20 73 65 74 74 69  he trigger setti
159b0 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74  ng is not report
159c0 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a  ed back. </dd>.*
159d0 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64  *.** </dl>.*/.#d
159e0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43  efine SQLITE_DBC
159f0 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20  ONFIG_LOOKASIDE 
15a00 20 20 20 20 20 20 31 30 30 31 20 20 2f 2a 20 76        1001  /* v
15a10 6f 69 64 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a  oid* int int */.
15a20 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
15a30 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46  BCONFIG_ENABLE_F
15a40 4b 45 59 20 20 20 20 20 31 30 30 32 20 20 2f 2a  KEY     1002  /*
15a50 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65   int int* */.#de
15a60 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f  fine SQLITE_DBCO
15a70 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47  NFIG_ENABLE_TRIG
15a80 47 45 52 20 20 31 30 30 33 20 20 2f 2a 20 69 6e  GER  1003  /* in
15a90 74 20 69 6e 74 2a 20 2a 2f 0a 0a 0a 2f 2a 0a 2a  t int* */.../*.*
15aa0 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62  * CAPI3REF: Enab
15ab0 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45 78  le Or Disable Ex
15ac0 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f  tended Result Co
15ad0 64 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  des.**.** ^The s
15ae0 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f  qlite3_extended_
15af0 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 20 72  result_codes() r
15b00 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f  outine enables o
15b10 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 0a 2a  r disables the.*
15b20 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75  * [extended resu
15b30 6c 74 20 63 6f 64 65 73 5d 20 66 65 61 74 75 72  lt codes] featur
15b40 65 20 6f 66 20 53 51 4c 69 74 65 2e 20 5e 54 68  e of SQLite. ^Th
15b50 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c  e extended resul
15b60 74 0a 2a 2a 20 63 6f 64 65 73 20 61 72 65 20 64  t.** codes are d
15b70 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75  isabled by defau
15b80 6c 74 20 66 6f 72 20 68 69 73 74 6f 72 69 63 61  lt for historica
15b90 6c 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e  l compatibility.
15ba0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
15bb0 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f  extended_result_
15bc0 63 6f 64 65 73 28 73 71 6c 69 74 65 33 2a 2c 20  codes(sqlite3*, 
15bd0 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a  int onoff);../*.
15be0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 61 73  ** CAPI3REF: Las
15bf0 74 20 49 6e 73 65 72 74 20 52 6f 77 69 64 0a 2a  t Insert Rowid.*
15c00 2a 0a 2a 2a 20 5e 45 61 63 68 20 65 6e 74 72 79  *.** ^Each entry
15c10 20 69 6e 20 61 6e 20 53 51 4c 69 74 65 20 74 61   in an SQLite ta
15c20 62 6c 65 20 68 61 73 20 61 20 75 6e 69 71 75 65  ble has a unique
15c30 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 0a 2a   64-bit signed.*
15c40 2a 20 69 6e 74 65 67 65 72 20 6b 65 79 20 63 61  * integer key ca
15c50 6c 6c 65 64 20 74 68 65 20 5b 52 4f 57 49 44 20  lled the [ROWID 
15c60 7c 20 22 72 6f 77 69 64 22 5d 2e 20 5e 54 68 65  | "rowid"]. ^The
15c70 20 72 6f 77 69 64 20 69 73 20 61 6c 77 61 79 73   rowid is always
15c80 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 61 73   available.** as
15c90 20 61 6e 20 75 6e 64 65 63 6c 61 72 65 64 20 63   an undeclared c
15ca0 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f 57 49  olumn named ROWI
15cb0 44 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f 57 49  D, OID, or _ROWI
15cc0 44 5f 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68  D_ as long as th
15cd0 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 61 72 65  ose.** names are
15ce0 20 6e 6f 74 20 61 6c 73 6f 20 75 73 65 64 20 62   not also used b
15cf0 79 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63  y explicitly dec
15d00 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 73 2e 20 5e  lared columns. ^
15d10 49 66 0a 2a 2a 20 74 68 65 20 74 61 62 6c 65 20  If.** the table 
15d20 68 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20  has a column of 
15d30 74 79 70 65 20 5b 49 4e 54 45 47 45 52 20 50 52  type [INTEGER PR
15d40 49 4d 41 52 59 20 4b 45 59 5d 20 74 68 65 6e 20  IMARY KEY] then 
15d50 74 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69  that column.** i
15d60 73 20 61 6e 6f 74 68 65 72 20 61 6c 69 61 73 20  s another alias 
15d70 66 6f 72 20 74 68 65 20 72 6f 77 69 64 2e 0a 2a  for the rowid..*
15d80 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69  *.** ^This routi
15d90 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 5b  ne returns the [
15da0 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 6d 6f  rowid] of the mo
15db0 73 74 20 72 65 63 65 6e 74 0a 2a 2a 20 73 75 63  st recent.** suc
15dc0 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d  cessful [INSERT]
15dd0 20 69 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61   into the databa
15de0 73 65 20 66 72 6f 6d 20 74 68 65 20 5b 64 61 74  se from the [dat
15df0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
15e00 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 73  ].** in the firs
15e10 74 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e 41 73  t argument.  ^As
15e20 20 6f 66 20 53 51 4c 69 74 65 20 76 65 72 73 69   of SQLite versi
15e30 6f 6e 20 33 2e 37 2e 37 2c 20 74 68 69 73 20 72  on 3.7.7, this r
15e40 6f 75 74 69 6e 65 73 0a 2a 2a 20 72 65 63 6f 72  outines.** recor
15e50 64 73 20 74 68 65 20 6c 61 73 74 20 69 6e 73 65  ds the last inse
15e60 72 74 20 72 6f 77 69 64 20 6f 66 20 62 6f 74 68  rt rowid of both
15e70 20 6f 72 64 69 6e 61 72 79 20 74 61 62 6c 65 73   ordinary tables
15e80 20 61 6e 64 20 5b 76 69 72 74 75 61 6c 20 74 61   and [virtual ta
15e90 62 6c 65 73 5d 2e 0a 2a 2a 20 5e 49 66 20 6e 6f  bles]..** ^If no
15ea0 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53   successful [INS
15eb0 45 52 54 5d 73 0a 2a 2a 20 68 61 76 65 20 65 76  ERT]s.** have ev
15ec0 65 72 20 6f 63 63 75 72 72 65 64 20 6f 6e 20 74  er occurred on t
15ed0 68 61 74 20 64 61 74 61 62 61 73 65 20 63 6f 6e  hat database con
15ee0 6e 65 63 74 69 6f 6e 2c 20 7a 65 72 6f 20 69 73  nection, zero is
15ef0 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
15f00 20 5e 28 49 66 20 61 6e 20 5b 49 4e 53 45 52 54   ^(If an [INSERT
15f10 5d 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20  ] occurs within 
15f20 61 20 74 72 69 67 67 65 72 20 6f 72 20 77 69 74  a trigger or wit
15f30 68 69 6e 20 61 20 5b 76 69 72 74 75 61 6c 20 74  hin a [virtual t
15f40 61 62 6c 65 5d 0a 2a 2a 20 6d 65 74 68 6f 64 2c  able].** method,
15f50 20 74 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69   then this routi
15f60 6e 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 74  ne will return t
15f70 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68  he [rowid] of th
15f80 65 20 69 6e 73 65 72 74 65 64 0a 2a 2a 20 72 6f  e inserted.** ro
15f90 77 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65  w as long as the
15fa0 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 72 74   trigger or virt
15fb0 75 61 6c 20 74 61 62 6c 65 20 6d 65 74 68 6f 64  ual table method
15fc0 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20   is running..** 
15fd0 42 75 74 20 6f 6e 63 65 20 74 68 65 20 74 72 69  But once the tri
15fe0 67 67 65 72 20 6f 72 20 76 69 72 74 75 61 6c 20  gger or virtual 
15ff0 74 61 62 6c 65 20 6d 65 74 68 6f 64 20 65 6e 64  table method end
16000 73 2c 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  s, the value ret
16010 75 72 6e 65 64 20 0a 2a 2a 20 62 79 20 74 68 69  urned .** by thi
16020 73 20 72 6f 75 74 69 6e 65 20 72 65 76 65 72 74  s routine revert
16030 73 20 74 6f 20 77 68 61 74 20 69 74 20 77 61 73  s to what it was
16040 20 62 65 66 6f 72 65 20 74 68 65 20 74 72 69 67   before the trig
16050 67 65 72 20 6f 72 20 76 69 72 74 75 61 6c 0a 2a  ger or virtual.*
16060 2a 20 74 61 62 6c 65 20 6d 65 74 68 6f 64 20 62  * table method b
16070 65 67 61 6e 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 41  egan.)^.**.** ^A
16080 6e 20 5b 49 4e 53 45 52 54 5d 20 74 68 61 74 20  n [INSERT] that 
16090 66 61 69 6c 73 20 64 75 65 20 74 6f 20 61 20 63  fails due to a c
160a0 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74  onstraint violat
160b0 69 6f 6e 20 69 73 20 6e 6f 74 20 61 0a 2a 2a 20  ion is not a.** 
160c0 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45  successful [INSE
160d0 52 54 5d 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74  RT] and does not
160e0 20 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75   change the valu
160f0 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  e returned by th
16100 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 2e 20 20  is.** routine.  
16110 5e 54 68 75 73 20 49 4e 53 45 52 54 20 4f 52 20  ^Thus INSERT OR 
16120 46 41 49 4c 2c 20 49 4e 53 45 52 54 20 4f 52 20  FAIL, INSERT OR 
16130 49 47 4e 4f 52 45 2c 20 49 4e 53 45 52 54 20 4f  IGNORE, INSERT O
16140 52 20 52 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 61  R ROLLBACK,.** a
16150 6e 64 20 49 4e 53 45 52 54 20 4f 52 20 41 42 4f  nd INSERT OR ABO
16160 52 54 20 6d 61 6b 65 20 6e 6f 20 63 68 61 6e 67  RT make no chang
16170 65 73 20 74 6f 20 74 68 65 20 72 65 74 75 72 6e  es to the return
16180 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 0a 2a   value of this.*
16190 2a 20 72 6f 75 74 69 6e 65 20 77 68 65 6e 20 74  * routine when t
161a0 68 65 69 72 20 69 6e 73 65 72 74 69 6f 6e 20 66  heir insertion f
161b0 61 69 6c 73 2e 20 20 5e 28 57 68 65 6e 20 49 4e  ails.  ^(When IN
161c0 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45 0a  SERT OR REPLACE.
161d0 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 73 20 61 20  ** encounters a 
161e0 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61  constraint viola
161f0 74 69 6f 6e 2c 20 69 74 20 64 6f 65 73 20 6e 6f  tion, it does no
16200 74 20 66 61 69 6c 2e 20 20 54 68 65 0a 2a 2a 20  t fail.  The.** 
16210 49 4e 53 45 52 54 20 63 6f 6e 74 69 6e 75 65 73  INSERT continues
16220 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61   to completion a
16230 66 74 65 72 20 64 65 6c 65 74 69 6e 67 20 72 6f  fter deleting ro
16240 77 73 20 74 68 61 74 20 63 61 75 73 65 64 0a 2a  ws that caused.*
16250 2a 20 74 68 65 20 63 6f 6e 73 74 72 61 69 6e 74  * the constraint
16260 20 70 72 6f 62 6c 65 6d 20 73 6f 20 49 4e 53 45   problem so INSE
16270 52 54 20 4f 52 20 52 45 50 4c 41 43 45 20 77 69  RT OR REPLACE wi
16280 6c 6c 20 61 6c 77 61 79 73 20 63 68 61 6e 67 65  ll always change
16290 0a 2a 2a 20 74 68 65 20 72 65 74 75 72 6e 20 76  .** the return v
162a0 61 6c 75 65 20 6f 66 20 74 68 69 73 20 69 6e 74  alue of this int
162b0 65 72 66 61 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20  erface.)^.**.** 
162c0 5e 46 6f 72 20 74 68 65 20 70 75 72 70 6f 73 65  ^For the purpose
162d0 73 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e  s of this routin
162e0 65 2c 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 69  e, an [INSERT] i
162f0 73 20 63 6f 6e 73 69 64 65 72 65 64 20 74 6f 0a  s considered to.
16300 2a 2a 20 62 65 20 73 75 63 63 65 73 73 66 75 6c  ** be successful
16310 20 65 76 65 6e 20 69 66 20 69 74 20 69 73 20 73   even if it is s
16320 75 62 73 65 71 75 65 6e 74 6c 79 20 72 6f 6c 6c  ubsequently roll
16330 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54  ed back..**.** T
16340 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  his function is 
16350 61 63 63 65 73 73 69 62 6c 65 20 74 6f 20 53 51  accessible to SQ
16360 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 76 69 61  L statements via
16370 20 74 68 65 0a 2a 2a 20 5b 6c 61 73 74 5f 69 6e   the.** [last_in
16380 73 65 72 74 5f 72 6f 77 69 64 28 29 20 53 51 4c  sert_rowid() SQL
16390 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a   function]..**.*
163a0 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20  * If a separate 
163b0 74 68 72 65 61 64 20 70 65 72 66 6f 72 6d 73 20  thread performs 
163c0 61 20 6e 65 77 20 5b 49 4e 53 45 52 54 5d 20 6f  a new [INSERT] o
163d0 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 64 61  n the same.** da
163e0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
163f0 6e 20 77 68 69 6c 65 20 74 68 65 20 5b 73 71 6c  n while the [sql
16400 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74  ite3_last_insert
16410 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a 20 66 75 6e  _rowid()].** fun
16420 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67  ction is running
16430 20 61 6e 64 20 74 68 75 73 20 63 68 61 6e 67 65   and thus change
16440 73 20 74 68 65 20 6c 61 73 74 20 69 6e 73 65 72  s the last inser
16450 74 20 5b 72 6f 77 69 64 5d 2c 0a 2a 2a 20 74 68  t [rowid],.** th
16460 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  en the value ret
16470 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65  urned by [sqlite
16480 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f  3_last_insert_ro
16490 77 69 64 28 29 5d 20 69 73 0a 2a 2a 20 75 6e 70  wid()] is.** unp
164a0 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6d  redictable and m
164b0 69 67 68 74 20 6e 6f 74 20 65 71 75 61 6c 20 65  ight not equal e
164c0 69 74 68 65 72 20 74 68 65 20 6f 6c 64 20 6f 72  ither the old or
164d0 20 74 68 65 20 6e 65 77 0a 2a 2a 20 6c 61 73 74   the new.** last
164e0 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2e   insert [rowid].
164f0 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36  .*/.sqlite3_int6
16500 34 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69  4 sqlite3_last_i
16510 6e 73 65 72 74 5f 72 6f 77 69 64 28 73 71 6c 69  nsert_rowid(sqli
16520 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  te3*);../*.** CA
16530 50 49 33 52 45 46 3a 20 43 6f 75 6e 74 20 54 68  PI3REF: Count Th
16540 65 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73  e Number Of Rows
16550 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a 2a 2a 20   Modified.**.** 
16560 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72  ^This function r
16570 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
16580 72 20 6f 66 20 64 61 74 61 62 61 73 65 20 72 6f  r of database ro
16590 77 73 20 74 68 61 74 20 77 65 72 65 20 63 68 61  ws that were cha
165a0 6e 67 65 64 0a 2a 2a 20 6f 72 20 69 6e 73 65 72  nged.** or inser
165b0 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64 20 62  ted or deleted b
165c0 79 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  y the most recen
165d0 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 53 51  tly completed SQ
165e0 4c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 6f  L statement.** o
165f0 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  n the [database 
16600 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63  connection] spec
16610 69 66 69 65 64 20 62 79 20 74 68 65 20 66 69 72  ified by the fir
16620 73 74 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  st parameter..**
16630 20 5e 28 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20   ^(Only changes 
16640 74 68 61 74 20 61 72 65 20 64 69 72 65 63 74 6c  that are directl
16650 79 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74  y specified by t
16660 68 65 20 5b 49 4e 53 45 52 54 5d 2c 20 5b 55 50  he [INSERT], [UP
16670 44 41 54 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 44 45  DATE],.** or [DE
16680 4c 45 54 45 5d 20 73 74 61 74 65 6d 65 6e 74 20  LETE] statement 
16690 61 72 65 20 63 6f 75 6e 74 65 64 2e 20 20 41 75  are counted.  Au
166a0 78 69 6c 69 61 72 79 20 63 68 61 6e 67 65 73 20  xiliary changes 
166b0 63 61 75 73 65 64 20 62 79 0a 2a 2a 20 74 72 69  caused by.** tri
166c0 67 67 65 72 73 20 6f 72 20 5b 66 6f 72 65 69 67  ggers or [foreig
166d0 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d 20 61  n key actions] a
166e0 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 29  re not counted.)
166f0 5e 20 55 73 65 20 74 68 65 0a 2a 2a 20 5b 73 71  ^ Use the.** [sq
16700 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e  lite3_total_chan
16710 67 65 73 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20  ges()] function 
16720 74 6f 20 66 69 6e 64 20 74 68 65 20 74 6f 74 61  to find the tota
16730 6c 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 6e  l number of chan
16740 67 65 73 0a 2a 2a 20 69 6e 63 6c 75 64 69 6e 67  ges.** including
16750 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 64 20   changes caused 
16760 62 79 20 74 72 69 67 67 65 72 73 20 61 6e 64 20  by triggers and 
16770 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69  foreign key acti
16780 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 43 68 61 6e  ons..**.** ^Chan
16790 67 65 73 20 74 6f 20 61 20 76 69 65 77 20 74 68  ges to a view th
167a0 61 74 20 61 72 65 20 73 69 6d 75 6c 61 74 65 64  at are simulated
167b0 20 62 79 20 61 6e 20 5b 49 4e 53 54 45 41 44 20   by an [INSTEAD 
167c0 4f 46 20 74 72 69 67 67 65 72 5d 0a 2a 2a 20 61  OF trigger].** a
167d0 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 20  re not counted. 
167e0 20 4f 6e 6c 79 20 72 65 61 6c 20 74 61 62 6c 65   Only real table
167f0 20 63 68 61 6e 67 65 73 20 61 72 65 20 63 6f 75   changes are cou
16800 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 20  nted..**.** ^(A 
16810 22 72 6f 77 20 63 68 61 6e 67 65 22 20 69 73 20  "row change" is 
16820 61 20 63 68 61 6e 67 65 20 74 6f 20 61 20 73 69  a change to a si
16830 6e 67 6c 65 20 72 6f 77 20 6f 66 20 61 20 73 69  ngle row of a si
16840 6e 67 6c 65 20 74 61 62 6c 65 0a 2a 2a 20 63 61  ngle table.** ca
16850 75 73 65 64 20 62 79 20 61 6e 20 49 4e 53 45 52  used by an INSER
16860 54 2c 20 44 45 4c 45 54 45 2c 20 6f 72 20 55 50  T, DELETE, or UP
16870 44 41 54 45 20 73 74 61 74 65 6d 65 6e 74 2e 20  DATE statement. 
16880 20 52 6f 77 73 20 74 68 61 74 0a 2a 2a 20 61 72   Rows that.** ar
16890 65 20 63 68 61 6e 67 65 64 20 61 73 20 73 69 64  e changed as sid
168a0 65 20 65 66 66 65 63 74 73 20 6f 66 20 5b 52 45  e effects of [RE
168b0 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61 69 6e  PLACE] constrain
168c0 74 20 72 65 73 6f 6c 75 74 69 6f 6e 2c 0a 2a 2a  t resolution,.**
168d0 20 72 6f 6c 6c 62 61 63 6b 2c 20 41 42 4f 52 54   rollback, ABORT
168e0 20 70 72 6f 63 65 73 73 69 6e 67 2c 20 5b 44 52   processing, [DR
168f0 4f 50 20 54 41 42 4c 45 5d 2c 20 6f 72 20 62 79  OP TABLE], or by
16900 20 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 6d 65   any other.** me
16910 63 68 61 6e 69 73 6d 73 20 64 6f 20 6e 6f 74 20  chanisms do not 
16920 63 6f 75 6e 74 20 61 73 20 64 69 72 65 63 74 20  count as direct 
16930 72 6f 77 20 63 68 61 6e 67 65 73 2e 29 5e 0a 2a  row changes.)^.*
16940 2a 0a 2a 2a 20 41 20 22 74 72 69 67 67 65 72 20  *.** A "trigger 
16950 63 6f 6e 74 65 78 74 22 20 69 73 20 61 20 73 63  context" is a sc
16960 6f 70 65 20 6f 66 20 65 78 65 63 75 74 69 6f 6e  ope of execution
16970 20 74 68 61 74 20 62 65 67 69 6e 73 20 61 6e 64   that begins and
16980 0a 2a 2a 20 65 6e 64 73 20 77 69 74 68 20 74 68  .** ends with th
16990 65 20 73 63 72 69 70 74 20 6f 66 20 61 20 5b 43  e script of a [C
169a0 52 45 41 54 45 20 54 52 49 47 47 45 52 20 7c 20  REATE TRIGGER | 
169b0 74 72 69 67 67 65 72 5d 2e 20 0a 2a 2a 20 4d 6f  trigger]. .** Mo
169c0 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  st SQL statement
169d0 73 20 61 72 65 0a 2a 2a 20 65 76 61 6c 75 61 74  s are.** evaluat
169e0 65 64 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e  ed outside of an
169f0 79 20 74 72 69 67 67 65 72 2e 20 20 54 68 69 73  y trigger.  This
16a00 20 69 73 20 74 68 65 20 22 74 6f 70 20 6c 65 76   is the "top lev
16a10 65 6c 22 0a 2a 2a 20 74 72 69 67 67 65 72 20 63  el".** trigger c
16a20 6f 6e 74 65 78 74 2e 20 20 49 66 20 61 20 74 72  ontext.  If a tr
16a30 69 67 67 65 72 20 66 69 72 65 73 20 66 72 6f 6d  igger fires from
16a40 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2c 20   the top level, 
16a50 61 0a 2a 2a 20 6e 65 77 20 74 72 69 67 67 65 72  a.** new trigger
16a60 20 63 6f 6e 74 65 78 74 20 69 73 20 65 6e 74 65   context is ente
16a70 72 65 64 20 66 6f 72 20 74 68 65 20 64 75 72 61  red for the dura
16a80 74 69 6f 6e 20 6f 66 20 74 68 61 74 20 6f 6e 65  tion of that one
16a90 0a 2a 2a 20 74 72 69 67 67 65 72 2e 20 20 53 75  .** trigger.  Su
16aa0 62 74 72 69 67 67 65 72 73 20 63 72 65 61 74 65  btriggers create
16ab0 20 73 75 62 63 6f 6e 74 65 78 74 73 20 66 6f 72   subcontexts for
16ac0 20 74 68 65 69 72 20 64 75 72 61 74 69 6f 6e 2e   their duration.
16ad0 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20  .**.** ^Calling 
16ae0 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
16af0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   or [sqlite3_ste
16b00 70 28 29 5d 20 72 65 63 75 72 73 69 76 65 6c 79  p()] recursively
16b10 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 63 72 65   does.** not cre
16b20 61 74 65 20 61 20 6e 65 77 20 74 72 69 67 67 65  ate a new trigge
16b30 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a  r context..**.**
16b40 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20   ^This function 
16b50 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
16b60 65 72 20 6f 66 20 64 69 72 65 63 74 20 72 6f 77  er of direct row
16b70 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 0a   changes in the.
16b80 2a 2a 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 49  ** most recent I
16b90 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f  NSERT, UPDATE, o
16ba0 72 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65  r DELETE stateme
16bb0 6e 74 20 77 69 74 68 69 6e 20 74 68 65 20 73 61  nt within the sa
16bc0 6d 65 0a 2a 2a 20 74 72 69 67 67 65 72 20 63 6f  me.** trigger co
16bd0 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ntext..**.** ^Th
16be0 75 73 2c 20 77 68 65 6e 20 63 61 6c 6c 65 64 20  us, when called 
16bf0 66 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65 76  from the top lev
16c00 65 6c 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f  el, this functio
16c10 6e 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a  n returns the.**
16c20 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 6e 67   number of chang
16c30 65 73 20 69 6e 20 74 68 65 20 6d 6f 73 74 20 72  es in the most r
16c40 65 63 65 6e 74 20 49 4e 53 45 52 54 2c 20 55 50  ecent INSERT, UP
16c50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a  DATE, or DELETE.
16c60 2a 2a 20 74 68 61 74 20 61 6c 73 6f 20 6f 63 63  ** that also occ
16c70 75 72 72 65 64 20 61 74 20 74 68 65 20 74 6f 70  urred at the top
16c80 20 6c 65 76 65 6c 2e 20 20 5e 28 57 69 74 68 69   level.  ^(Withi
16c90 6e 20 74 68 65 20 62 6f 64 79 20 6f 66 20 61 20  n the body of a 
16ca0 74 72 69 67 67 65 72 2c 0a 2a 2a 20 74 68 65 20  trigger,.** the 
16cb0 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
16cc0 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20  ) interface can 
16cd0 62 65 20 63 61 6c 6c 65 64 20 74 6f 20 66 69 6e  be called to fin
16ce0 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a  d the number of.
16cf0 2a 2a 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68  ** changes in th
16d00 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20  e most recently 
16d10 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53 45 52 54  completed INSERT
16d20 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c  , UPDATE, or DEL
16d30 45 54 45 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  ETE.** statement
16d40 20 77 69 74 68 69 6e 20 74 68 65 20 62 6f 64 79   within the body
16d50 20 6f 66 20 74 68 65 20 73 61 6d 65 20 74 72 69   of the same tri
16d60 67 67 65 72 2e 0a 2a 2a 20 48 6f 77 65 76 65 72  gger..** However
16d70 2c 20 74 68 65 20 6e 75 6d 62 65 72 20 72 65 74  , the number ret
16d80 75 72 6e 65 64 20 64 6f 65 73 20 6e 6f 74 20 69  urned does not i
16d90 6e 63 6c 75 64 65 20 63 68 61 6e 67 65 73 0a 2a  nclude changes.*
16da0 2a 20 63 61 75 73 65 64 20 62 79 20 73 75 62 74  * caused by subt
16db0 72 69 67 67 65 72 73 20 73 69 6e 63 65 20 74 68  riggers since th
16dc0 6f 73 65 20 68 61 76 65 20 74 68 65 69 72 20 6f  ose have their o
16dd0 77 6e 20 63 6f 6e 74 65 78 74 2e 29 5e 0a 2a 2a  wn context.)^.**
16de0 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65  .** See also the
16df0 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f   [sqlite3_total_
16e00 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72  changes()] inter
16e10 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f  face, the.** [co
16e20 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67  unt_changes prag
16e30 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b 63 68  ma], and the [ch
16e40 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63  anges() SQL func
16e50 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  tion]..**.** If 
16e60 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61  a separate threa
16e70 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20  d makes changes 
16e80 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  on the same data
16e90 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
16ea0 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65  ** while [sqlite
16eb0 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73 20  3_changes()] is 
16ec0 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65  running then the
16ed0 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a   value returned.
16ee0 2a 2a 20 69 73 20 75 6e 70 72 65 64 69 63 74 61  ** is unpredicta
16ef0 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e  ble and not mean
16f00 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73  ingful..*/.int s
16f10 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 73  qlite3_changes(s
16f20 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
16f30 20 43 41 50 49 33 52 45 46 3a 20 54 6f 74 61 6c   CAPI3REF: Total
16f40 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20   Number Of Rows 
16f50 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a 2a 2a 20 5e  Modified.**.** ^
16f60 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65  This function re
16f70 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
16f80 20 6f 66 20 72 6f 77 20 63 68 61 6e 67 65 73 20   of row changes 
16f90 63 61 75 73 65 64 20 62 79 20 5b 49 4e 53 45 52  caused by [INSER
16fa0 54 5d 2c 0a 2a 2a 20 5b 55 50 44 41 54 45 5d 20  T],.** [UPDATE] 
16fb0 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73 74 61 74  or [DELETE] stat
16fc0 65 6d 65 6e 74 73 20 73 69 6e 63 65 20 74 68 65  ements since the
16fd0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
16fe0 63 74 69 6f 6e 5d 20 77 61 73 20 6f 70 65 6e 65  ction] was opene
16ff0 64 2e 0a 2a 2a 20 5e 28 54 68 65 20 63 6f 75 6e  d..** ^(The coun
17000 74 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  t returned by sq
17010 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e  lite3_total_chan
17020 67 65 73 28 29 20 69 6e 63 6c 75 64 65 73 20 61  ges() includes a
17030 6c 6c 20 63 68 61 6e 67 65 73 0a 2a 2a 20 66 72  ll changes.** fr
17040 6f 6d 20 61 6c 6c 20 5b 43 52 45 41 54 45 20 54  om all [CREATE T
17050 52 49 47 47 45 52 20 7c 20 74 72 69 67 67 65 72  RIGGER | trigger
17060 5d 20 63 6f 6e 74 65 78 74 73 20 61 6e 64 20 63  ] contexts and c
17070 68 61 6e 67 65 73 20 6d 61 64 65 20 62 79 0a 2a  hanges made by.*
17080 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61  * [foreign key a
17090 63 74 69 6f 6e 73 5d 2e 20 48 6f 77 65 76 65 72  ctions]. However
170a0 2c 0a 2a 2a 20 74 68 65 20 63 6f 75 6e 74 20 64  ,.** the count d
170b0 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20  oes not include 
170c0 63 68 61 6e 67 65 73 20 75 73 65 64 20 74 6f 20  changes used to 
170d0 69 6d 70 6c 65 6d 65 6e 74 20 5b 52 45 50 4c 41  implement [REPLA
170e0 43 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74 73 2c  CE] constraints,
170f0 0a 2a 2a 20 64 6f 20 72 6f 6c 6c 62 61 63 6b 73  .** do rollbacks
17100 20 6f 72 20 41 42 4f 52 54 20 70 72 6f 63 65 73   or ABORT proces
17110 73 69 6e 67 2c 20 6f 72 20 5b 44 52 4f 50 20 54  sing, or [DROP T
17120 41 42 4c 45 5d 20 70 72 6f 63 65 73 73 69 6e 67  ABLE] processing
17130 2e 20 20 54 68 65 0a 2a 2a 20 63 6f 75 6e 74 20  .  The.** count 
17140 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65  does not include
17150 20 72 6f 77 73 20 6f 66 20 76 69 65 77 73 20 74   rows of views t
17160 68 61 74 20 66 69 72 65 20 61 6e 20 5b 49 4e 53  hat fire an [INS
17170 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 72 5d  TEAD OF trigger]
17180 2c 0a 2a 2a 20 74 68 6f 75 67 68 20 69 66 20 74  ,.** though if t
17190 68 65 20 49 4e 53 54 45 41 44 20 4f 46 20 74 72  he INSTEAD OF tr
171a0 69 67 67 65 72 20 6d 61 6b 65 73 20 63 68 61 6e  igger makes chan
171b0 67 65 73 20 6f 66 20 69 74 73 20 6f 77 6e 2c 20  ges of its own, 
171c0 74 68 6f 73 65 20 63 68 61 6e 67 65 73 20 0a 2a  those changes .*
171d0 2a 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 29 5e  * are counted.)^
171e0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
171f0 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29  _total_changes()
17200 20 66 75 6e 63 74 69 6f 6e 20 63 6f 75 6e 74 73   function counts
17210 20 74 68 65 20 63 68 61 6e 67 65 73 20 61 73 20   the changes as 
17220 73 6f 6f 6e 20 61 73 0a 2a 2a 20 74 68 65 20 73  soon as.** the s
17230 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 6d 61  tatement that ma
17240 6b 65 73 20 74 68 65 6d 20 69 73 20 63 6f 6d 70  kes them is comp
17250 6c 65 74 65 64 20 28 77 68 65 6e 20 74 68 65 20  leted (when the 
17260 73 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65  statement handle
17270 0a 2a 2a 20 69 73 20 70 61 73 73 65 64 20 74 6f  .** is passed to
17280 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
17290 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66  )] or [sqlite3_f
172a0 69 6e 61 6c 69 7a 65 28 29 5d 29 2e 0a 2a 2a 0a  inalize()])..**.
172b0 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20  ** See also the 
172c0 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73  [sqlite3_changes
172d0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2c 20 74  ()] interface, t
172e0 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61  he.** [count_cha
172f0 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e  nges pragma], an
17300 64 20 74 68 65 20 5b 74 6f 74 61 6c 5f 63 68 61  d the [total_cha
17310 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74  nges() SQL funct
17320 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61  ion]..**.** If a
17330 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64   separate thread
17340 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f   makes changes o
17350 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62  n the same datab
17360 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase connection.*
17370 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33  * while [sqlite3
17380 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29  _total_changes()
17390 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65  ] is running the
173a0 6e 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72  n the value.** r
173b0 65 74 75 72 6e 65 64 20 69 73 20 75 6e 70 72 65  eturned is unpre
173c0 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74  dictable and not
173d0 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a   meaningful..*/.
173e0 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 6f 74 61  int sqlite3_tota
173f0 6c 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65  l_changes(sqlite
17400 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  3*);../*.** CAPI
17410 33 52 45 46 3a 20 49 6e 74 65 72 72 75 70 74 20  3REF: Interrupt 
17420 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e 67 20 51  A Long-Running Q
17430 75 65 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  uery.**.** ^This
17440 20 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73   function causes
17450 20 61 6e 79 20 70 65 6e 64 69 6e 67 20 64 61 74   any pending dat
17460 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 20  abase operation 
17470 74 6f 20 61 62 6f 72 74 20 61 6e 64 0a 2a 2a 20  to abort and.** 
17480 72 65 74 75 72 6e 20 61 74 20 69 74 73 20 65 61  return at its ea
17490 72 6c 69 65 73 74 20 6f 70 70 6f 72 74 75 6e 69  rliest opportuni
174a0 74 79 2e 20 54 68 69 73 20 72 6f 75 74 69 6e 65  ty. This routine
174b0 20 69 73 20 74 79 70 69 63 61 6c 6c 79 0a 2a 2a   is typically.**
174c0 20 63 61 6c 6c 65 64 20 69 6e 20 72 65 73 70 6f   called in respo
174d0 6e 73 65 20 74 6f 20 61 20 75 73 65 72 20 61 63  nse to a user ac
174e0 74 69 6f 6e 20 73 75 63 68 20 61 73 20 70 72 65  tion such as pre
174f0 73 73 69 6e 67 20 22 43 61 6e 63 65 6c 22 0a 2a  ssing "Cancel".*
17500 2a 20 6f 72 20 43 74 72 6c 2d 43 20 77 68 65 72  * or Ctrl-C wher
17510 65 20 74 68 65 20 75 73 65 72 20 77 61 6e 74 73  e the user wants
17520 20 61 20 6c 6f 6e 67 20 71 75 65 72 79 20 6f 70   a long query op
17530 65 72 61 74 69 6f 6e 20 74 6f 20 68 61 6c 74 0a  eration to halt.
17540 2a 2a 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a  ** immediately..
17550 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 73 61 66  **.** ^It is saf
17560 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72  e to call this r
17570 6f 75 74 69 6e 65 20 66 72 6f 6d 20 61 20 74 68  outine from a th
17580 72 65 61 64 20 64 69 66 66 65 72 65 6e 74 20 66  read different f
17590 72 6f 6d 20 74 68 65 0a 2a 2a 20 74 68 72 65 61  rom the.** threa
175a0 64 20 74 68 61 74 20 69 73 20 63 75 72 72 65 6e  d that is curren
175b0 74 6c 79 20 72 75 6e 6e 69 6e 67 20 74 68 65 20  tly running the 
175c0 64 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 69  database operati
175d0 6f 6e 2e 20 20 42 75 74 20 69 74 0a 2a 2a 20 69  on.  But it.** i
175e0 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 63 61  s not safe to ca
175f0 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  ll this routine 
17600 77 69 74 68 20 61 20 5b 64 61 74 61 62 61 73 65  with a [database
17610 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61   connection] tha
17620 74 0a 2a 2a 20 69 73 20 63 6c 6f 73 65 64 20 6f  t.** is closed o
17630 72 20 6d 69 67 68 74 20 63 6c 6f 73 65 20 62 65  r might close be
17640 66 6f 72 65 20 73 71 6c 69 74 65 33 5f 69 6e 74  fore sqlite3_int
17650 65 72 72 75 70 74 28 29 20 72 65 74 75 72 6e 73  errupt() returns
17660 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 53  ..**.** ^If an S
17670 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20  QL operation is 
17680 76 65 72 79 20 6e 65 61 72 6c 79 20 66 69 6e 69  very nearly fini
17690 73 68 65 64 20 61 74 20 74 68 65 20 74 69 6d 65  shed at the time
176a0 20 77 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33   when.** sqlite3
176b0 5f 69 6e 74 65 72 72 75 70 74 28 29 20 69 73 20  _interrupt() is 
176c0 63 61 6c 6c 65 64 2c 20 74 68 65 6e 20 69 74 20  called, then it 
176d0 6d 69 67 68 74 20 6e 6f 74 20 68 61 76 65 20 61  might not have a
176e0 6e 20 6f 70 70 6f 72 74 75 6e 69 74 79 0a 2a 2a  n opportunity.**
176f0 20 74 6f 20 62 65 20 69 6e 74 65 72 72 75 70 74   to be interrupt
17700 65 64 20 61 6e 64 20 6d 69 67 68 74 20 63 6f 6e  ed and might con
17710 74 69 6e 75 65 20 74 6f 20 63 6f 6d 70 6c 65 74  tinue to complet
17720 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 53  ion..**.** ^An S
17730 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 74 68 61  QL operation tha
17740 74 20 69 73 20 69 6e 74 65 72 72 75 70 74 65 64  t is interrupted
17750 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51   will return [SQ
17760 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2e  LITE_INTERRUPT].
17770 0a 2a 2a 20 5e 49 66 20 74 68 65 20 69 6e 74 65  .** ^If the inte
17780 72 72 75 70 74 65 64 20 53 51 4c 20 6f 70 65 72  rrupted SQL oper
17790 61 74 69 6f 6e 20 69 73 20 61 6e 20 49 4e 53 45  ation is an INSE
177a0 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44  RT, UPDATE, or D
177b0 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 69 73  ELETE.** that is
177c0 20 69 6e 73 69 64 65 20 61 6e 20 65 78 70 6c 69   inside an expli
177d0 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c  cit transaction,
177e0 20 74 68 65 6e 20 74 68 65 20 65 6e 74 69 72 65   then the entire
177f0 20 74 72 61 6e 73 61 63 74 69 6f 6e 0a 2a 2a 20   transaction.** 
17800 77 69 6c 6c 20 62 65 20 72 6f 6c 6c 65 64 20 62  will be rolled b
17810 61 63 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ack automaticall
17820 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  y..**.** ^The sq
17830 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
17840 44 29 20 63 61 6c 6c 20 69 73 20 69 6e 20 65 66  D) call is in ef
17850 66 65 63 74 20 75 6e 74 69 6c 20 61 6c 6c 20 63  fect until all c
17860 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67  urrently running
17870 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  .** SQL statemen
17880 74 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20  ts on [database 
17890 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 63 6f  connection] D co
178a0 6d 70 6c 65 74 65 2e 20 20 5e 41 6e 79 20 6e 65  mplete.  ^Any ne
178b0 77 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  w SQL statements
178c0 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61  .** that are sta
178d0 72 74 65 64 20 61 66 74 65 72 20 74 68 65 20 73  rted after the s
178e0 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
178f0 28 29 20 63 61 6c 6c 20 61 6e 64 20 62 65 66 6f  () call and befo
17900 72 65 20 74 68 65 20 0a 2a 2a 20 72 75 6e 6e 69  re the .** runni
17910 6e 67 20 73 74 61 74 65 6d 65 6e 74 73 20 72 65  ng statements re
17920 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65 20 69  aches zero are i
17930 6e 74 65 72 72 75 70 74 65 64 20 61 73 20 69 66  nterrupted as if
17940 20 74 68 65 79 20 68 61 64 20 62 65 65 6e 0a 2a   they had been.*
17950 2a 20 72 75 6e 6e 69 6e 67 20 70 72 69 6f 72 20  * running prior 
17960 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69  to the sqlite3_i
17970 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 2e  nterrupt() call.
17980 20 20 5e 4e 65 77 20 53 51 4c 20 73 74 61 74 65    ^New SQL state
17990 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72  ments.** that ar
179a0 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20  e started after 
179b0 74 68 65 20 72 75 6e 6e 69 6e 67 20 73 74 61 74  the running stat
179c0 65 6d 65 6e 74 20 63 6f 75 6e 74 20 72 65 61 63  ement count reac
179d0 68 65 73 20 7a 65 72 6f 20 61 72 65 0a 2a 2a 20  hes zero are.** 
179e0 6e 6f 74 20 65 66 66 65 63 74 65 64 20 62 79 20  not effected by 
179f0 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  the sqlite3_inte
17a00 72 72 75 70 74 28 29 2e 0a 2a 2a 20 5e 41 20 63  rrupt()..** ^A c
17a10 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69  all to sqlite3_i
17a20 6e 74 65 72 72 75 70 74 28 44 29 20 74 68 61 74  nterrupt(D) that
17a30 20 6f 63 63 75 72 73 20 77 68 65 6e 20 74 68 65   occurs when the
17a40 72 65 20 61 72 65 20 6e 6f 20 72 75 6e 6e 69 6e  re are no runnin
17a50 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65  g.** SQL stateme
17a60 6e 74 73 20 69 73 20 61 20 6e 6f 2d 6f 70 20 61  nts is a no-op a
17a70 6e 64 20 68 61 73 20 6e 6f 20 65 66 66 65 63 74  nd has no effect
17a80 20 6f 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   on SQL statemen
17a90 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73  ts.** that are s
17aa0 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65  tarted after the
17ab0 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
17ac0 70 74 28 29 20 63 61 6c 6c 20 72 65 74 75 72 6e  pt() call return
17ad0 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  s..**.** If the 
17ae0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
17af0 69 6f 6e 20 63 6c 6f 73 65 73 20 77 68 69 6c 65  ion closes while
17b00 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72   [sqlite3_interr
17b10 75 70 74 28 29 5d 0a 2a 2a 20 69 73 20 72 75 6e  upt()].** is run
17b20 6e 69 6e 67 20 74 68 65 6e 20 62 61 64 20 74 68  ning then bad th
17b30 69 6e 67 73 20 77 69 6c 6c 20 6c 69 6b 65 6c 79  ings will likely
17b40 20 68 61 70 70 65 6e 2e 0a 2a 2f 0a 76 6f 69 64   happen..*/.void
17b50 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
17b60 70 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  pt(sqlite3*);../
17b70 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
17b80 65 74 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 53  etermine If An S
17b90 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 49 73 20  QL Statement Is 
17ba0 43 6f 6d 70 6c 65 74 65 0a 2a 2a 0a 2a 2a 20 54  Complete.**.** T
17bb0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
17bc0 65 20 75 73 65 66 75 6c 20 64 75 72 69 6e 67 20  e useful during 
17bd0 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69 6e 70  command-line inp
17be0 75 74 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20  ut to determine 
17bf0 69 66 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e  if the.** curren
17c00 74 6c 79 20 65 6e 74 65 72 65 64 20 74 65 78 74  tly entered text
17c10 20 73 65 65 6d 73 20 74 6f 20 66 6f 72 6d 20 61   seems to form a
17c20 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74   complete SQL st
17c30 61 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a 20 69 66  atement or.** if
17c40 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 70 75   additional inpu
17c50 74 20 69 73 20 6e 65 65 64 65 64 20 62 65 66 6f  t is needed befo
17c60 72 65 20 73 65 6e 64 69 6e 67 20 74 68 65 20 74  re sending the t
17c70 65 78 74 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c 69  ext into.** SQLi
17c80 74 65 20 66 6f 72 20 70 61 72 73 69 6e 67 2e 20  te for parsing. 
17c90 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73   ^These routines
17ca0 20 72 65 74 75 72 6e 20 31 20 69 66 20 74 68 65   return 1 if the
17cb0 20 69 6e 70 75 74 20 73 74 72 69 6e 67 0a 2a 2a   input string.**
17cc0 20 61 70 70 65 61 72 73 20 74 6f 20 62 65 20 61   appears to be a
17cd0 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74   complete SQL st
17ce0 61 74 65 6d 65 6e 74 2e 20 20 5e 41 20 73 74 61  atement.  ^A sta
17cf0 74 65 6d 65 6e 74 20 69 73 20 6a 75 64 67 65 64  tement is judged
17d00 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 6c 65   to be.** comple
17d10 74 65 20 69 66 20 69 74 20 65 6e 64 73 20 77 69  te if it ends wi
17d20 74 68 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 20 74  th a semicolon t
17d30 6f 6b 65 6e 20 61 6e 64 20 69 73 20 6e 6f 74 20  oken and is not 
17d40 61 20 70 72 65 66 69 78 20 6f 66 20 61 0a 2a 2a  a prefix of a.**
17d50 20 77 65 6c 6c 2d 66 6f 72 6d 65 64 20 43 52 45   well-formed CRE
17d60 41 54 45 20 54 52 49 47 47 45 52 20 73 74 61 74  ATE TRIGGER stat
17d70 65 6d 65 6e 74 2e 20 20 5e 53 65 6d 69 63 6f 6c  ement.  ^Semicol
17d80 6f 6e 73 20 74 68 61 74 20 61 72 65 20 65 6d 62  ons that are emb
17d90 65 64 64 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20  edded within.** 
17da0 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 73 20  string literals 
17db0 6f 72 20 71 75 6f 74 65 64 20 69 64 65 6e 74 69  or quoted identi
17dc0 66 69 65 72 20 6e 61 6d 65 73 20 6f 72 20 63 6f  fier names or co
17dd0 6d 6d 65 6e 74 73 20 61 72 65 20 6e 6f 74 0a 2a  mments are not.*
17de0 2a 20 69 6e 64 65 70 65 6e 64 65 6e 74 20 74 6f  * independent to
17df0 6b 65 6e 73 20 28 74 68 65 79 20 61 72 65 20 70  kens (they are p
17e00 61 72 74 20 6f 66 20 74 68 65 20 74 6f 6b 65 6e  art of the token
17e10 20 69 6e 20 77 68 69 63 68 20 74 68 65 79 20 61   in which they a
17e20 72 65 0a 2a 2a 20 65 6d 62 65 64 64 65 64 29 20  re.** embedded) 
17e30 61 6e 64 20 74 68 75 73 20 64 6f 20 6e 6f 74 20  and thus do not 
17e40 63 6f 75 6e 74 20 61 73 20 61 20 73 74 61 74 65  count as a state
17e50 6d 65 6e 74 20 74 65 72 6d 69 6e 61 74 6f 72 2e  ment terminator.
17e60 20 20 5e 57 68 69 74 65 73 70 61 63 65 0a 2a 2a    ^Whitespace.**
17e70 20 61 6e 64 20 63 6f 6d 6d 65 6e 74 73 20 74 68   and comments th
17e80 61 74 20 66 6f 6c 6c 6f 77 20 74 68 65 20 66 69  at follow the fi
17e90 6e 61 6c 20 73 65 6d 69 63 6f 6c 6f 6e 20 61 72  nal semicolon ar
17ea0 65 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a  e ignored..**.**
17eb0 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73   ^These routines
17ec0 20 72 65 74 75 72 6e 20 30 20 69 66 20 74 68 65   return 0 if the
17ed0 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 69 6e   statement is in
17ee0 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 49 66 20 61  complete.  ^If a
17ef0 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  .** memory alloc
17f00 61 74 69 6f 6e 20 66 61 69 6c 73 2c 20 74 68 65  ation fails, the
17f10 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 69  n SQLITE_NOMEM i
17f20 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
17f30 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65  * ^These routine
17f40 73 20 64 6f 20 6e 6f 74 20 70 61 72 73 65 20 74  s do not parse t
17f50 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
17f60 73 20 74 68 75 73 0a 2a 2a 20 77 69 6c 6c 20 6e  s thus.** will n
17f70 6f 74 20 64 65 74 65 63 74 20 73 79 6e 74 61 63  ot detect syntac
17f80 74 69 63 61 6c 6c 79 20 69 6e 63 6f 72 72 65 63  tically incorrec
17f90 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49  t SQL..**.** ^(I
17fa0 66 20 53 51 4c 69 74 65 20 68 61 73 20 6e 6f 74  f SQLite has not
17fb0 20 62 65 65 6e 20 69 6e 69 74 69 61 6c 69 7a 65   been initialize
17fc0 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
17fd0 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 70  _initialize()] p
17fe0 72 69 6f 72 20 0a 2a 2a 20 74 6f 20 69 6e 76 6f  rior .** to invo
17ff0 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 63 6f 6d  king sqlite3_com
18000 70 6c 65 74 65 31 36 28 29 20 74 68 65 6e 20 73  plete16() then s
18010 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
18020 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a  e() is invoked.*
18030 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  * automatically 
18040 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  by sqlite3_compl
18050 65 74 65 31 36 28 29 2e 20 20 49 66 20 74 68 61  ete16().  If tha
18060 74 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  t initialization
18070 20 66 61 69 6c 73 2c 0a 2a 2a 20 74 68 65 6e 20   fails,.** then 
18080 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
18090 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f   from sqlite3_co
180a0 6d 70 6c 65 74 65 31 36 28 29 20 77 69 6c 6c 20  mplete16() will 
180b0 62 65 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a 20 72  be non-zero.** r
180c0 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65  egardless of whe
180d0 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20  ther or not the 
180e0 69 6e 70 75 74 20 53 51 4c 20 69 73 20 63 6f 6d  input SQL is com
180f0 70 6c 65 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54  plete.)^.**.** T
18100 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c  he input to [sql
18110 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 29 5d  ite3_complete()]
18120 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d   must be a zero-
18130 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54  terminated.** UT
18140 46 2d 38 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a  F-8 string..**.*
18150 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b  * The input to [
18160 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
18170 31 36 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20  16()] must be a 
18180 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a  zero-terminated.
18190 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67  ** UTF-16 string
181a0 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20   in native byte 
181b0 6f 72 64 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71  order..*/.int sq
181c0 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 63  lite3_complete(c
181d0 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 29 3b  onst char *sql);
181e0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d  .int sqlite3_com
181f0 70 6c 65 74 65 31 36 28 63 6f 6e 73 74 20 76 6f  plete16(const vo
18200 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a  id *sql);../*.**
18210 20 43 41 50 49 33 52 45 46 3a 20 52 65 67 69 73   CAPI3REF: Regis
18220 74 65 72 20 41 20 43 61 6c 6c 62 61 63 6b 20 54  ter A Callback T
18230 6f 20 48 61 6e 64 6c 65 20 53 51 4c 49 54 45 5f  o Handle SQLITE_
18240 42 55 53 59 20 45 72 72 6f 72 73 0a 2a 2a 0a 2a  BUSY Errors.**.*
18250 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20  * ^This routine 
18260 73 65 74 73 20 61 20 63 61 6c 6c 62 61 63 6b 20  sets a callback 
18270 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 6d 69  function that mi
18280 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77  ght be invoked w
18290 68 65 6e 65 76 65 72 0a 2a 2a 20 61 6e 20 61 74  henever.** an at
182a0 74 65 6d 70 74 20 69 73 20 6d 61 64 65 20 74 6f  tempt is made to
182b0 20 6f 70 65 6e 20 61 20 64 61 74 61 62 61 73 65   open a database
182c0 20 74 61 62 6c 65 20 74 68 61 74 20 61 6e 6f 74   table that anot
182d0 68 65 72 20 74 68 72 65 61 64 0a 2a 2a 20 6f 72  her thread.** or
182e0 20 70 72 6f 63 65 73 73 20 68 61 73 20 6c 6f 63   process has loc
182f0 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ked..**.** ^If t
18300 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b  he busy callback
18310 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b   is NULL, then [
18320 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20  SQLITE_BUSY] or 
18330 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c  [SQLITE_IOERR_BL
18340 4f 43 4b 45 44 5d 0a 2a 2a 20 69 73 20 72 65 74  OCKED].** is ret
18350 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c  urned immediatel
18360 79 20 75 70 6f 6e 20 65 6e 63 6f 75 6e 74 65 72  y upon encounter
18370 69 6e 67 20 74 68 65 20 6c 6f 63 6b 2e 20 20 5e  ing the lock.  ^
18380 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c  If the busy call
18390 62 61 63 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e  back.** is not N
183a0 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20 63 61  ULL, then the ca
183b0 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 62 65 20  llback might be 
183c0 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74 77 6f  invoked with two
183d0 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a   arguments..**.*
183e0 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67  * ^The first arg
183f0 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 62 75 73  ument to the bus
18400 79 20 68 61 6e 64 6c 65 72 20 69 73 20 61 20 63  y handler is a c
18410 6f 70 79 20 6f 66 20 74 68 65 20 76 6f 69 64 2a  opy of the void*
18420 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68 0a 2a   pointer which.*
18430 2a 20 69 73 20 74 68 65 20 74 68 69 72 64 20 61  * is the third a
18440 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
18450 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28  e3_busy_handler(
18460 29 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  ).  ^The second 
18470 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74  argument to.** t
18480 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  he busy handler 
18490 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20  callback is the 
184a0 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d 65 73 20  number of times 
184b0 74 68 61 74 20 74 68 65 20 62 75 73 79 20 68 61  that the busy ha
184c0 6e 64 6c 65 72 20 68 61 73 0a 2a 2a 20 62 65 65  ndler has.** bee
184d0 6e 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 74 68  n invoked for th
184e0 69 73 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74  is locking event
184f0 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 62 75  .  ^If the.** bu
18500 73 79 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  sy callback retu
18510 72 6e 73 20 30 2c 20 74 68 65 6e 20 6e 6f 20 61  rns 0, then no a
18520 64 64 69 74 69 6f 6e 61 6c 20 61 74 74 65 6d 70  dditional attemp
18530 74 73 20 61 72 65 20 6d 61 64 65 20 74 6f 0a 2a  ts are made to.*
18540 2a 20 61 63 63 65 73 73 20 74 68 65 20 64 61 74  * access the dat
18550 61 62 61 73 65 20 61 6e 64 20 5b 53 51 4c 49 54  abase and [SQLIT
18560 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49  E_BUSY] or [SQLI
18570 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44  TE_IOERR_BLOCKED
18580 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  ] is returned..*
18590 2a 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61  * ^If the callba
185a0 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a  ck returns non-z
185b0 65 72 6f 2c 20 74 68 65 6e 20 61 6e 6f 74 68 65  ero, then anothe
185c0 72 20 61 74 74 65 6d 70 74 0a 2a 2a 20 69 73 20  r attempt.** is 
185d0 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20 74 68 65  made to open the
185e0 20 64 61 74 61 62 61 73 65 20 66 6f 72 20 72 65   database for re
185f0 61 64 69 6e 67 20 61 6e 64 20 74 68 65 20 63 79  ading and the cy
18600 63 6c 65 20 72 65 70 65 61 74 73 2e 0a 2a 2a 0a  cle repeats..**.
18610 2a 2a 20 54 68 65 20 70 72 65 73 65 6e 63 65 20  ** The presence 
18620 6f 66 20 61 20 62 75 73 79 20 68 61 6e 64 6c 65  of a busy handle
18630 72 20 64 6f 65 73 20 6e 6f 74 20 67 75 61 72 61  r does not guara
18640 6e 74 65 65 20 74 68 61 74 20 69 74 20 77 69 6c  ntee that it wil
18650 6c 20 62 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20  l be invoked.** 
18660 77 68 65 6e 20 74 68 65 72 65 20 69 73 20 6c 6f  when there is lo
18670 63 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e 20 5e  ck contention. ^
18680 49 66 20 53 51 4c 69 74 65 20 64 65 74 65 72 6d  If SQLite determ
18690 69 6e 65 73 20 74 68 61 74 20 69 6e 76 6f 6b 69  ines that invoki
186a0 6e 67 20 74 68 65 20 62 75 73 79 0a 2a 2a 20 68  ng the busy.** h
186b0 61 6e 64 6c 65 72 20 63 6f 75 6c 64 20 72 65 73  andler could res
186c0 75 6c 74 20 69 6e 20 61 20 64 65 61 64 6c 6f 63  ult in a deadloc
186d0 6b 2c 20 69 74 20 77 69 6c 6c 20 67 6f 20 61 68  k, it will go ah
186e0 65 61 64 20 61 6e 64 20 72 65 74 75 72 6e 20 5b  ead and return [
186f0 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20  SQLITE_BUSY].** 
18700 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  or [SQLITE_IOERR
18710 5f 42 4c 4f 43 4b 45 44 5d 20 69 6e 73 74 65 61  _BLOCKED] instea
18720 64 20 6f 66 20 69 6e 76 6f 6b 69 6e 67 20 74 68  d of invoking th
18730 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a  e busy handler..
18740 2a 2a 20 43 6f 6e 73 69 64 65 72 20 61 20 73 63  ** Consider a sc
18750 65 6e 61 72 69 6f 20 77 68 65 72 65 20 6f 6e 65  enario where one
18760 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64   process is hold
18770 69 6e 67 20 61 20 72 65 61 64 20 6c 6f 63 6b 20  ing a read lock 
18780 74 68 61 74 0a 2a 2a 20 69 74 20 69 73 20 74 72  that.** it is tr
18790 79 69 6e 67 20 74 6f 20 70 72 6f 6d 6f 74 65 20  ying to promote 
187a0 74 6f 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f  to a reserved lo
187b0 63 6b 20 61 6e 64 0a 2a 2a 20 61 20 73 65 63 6f  ck and.** a seco
187c0 6e 64 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f  nd process is ho
187d0 6c 64 69 6e 67 20 61 20 72 65 73 65 72 76 65 64  lding a reserved
187e0 20 6c 6f 63 6b 20 74 68 61 74 20 69 74 20 69 73   lock that it is
187f0 20 74 72 79 69 6e 67 0a 2a 2a 20 74 6f 20 70 72   trying.** to pr
18800 6f 6d 6f 74 65 20 74 6f 20 61 6e 20 65 78 63 6c  omote to an excl
18810 75 73 69 76 65 20 6c 6f 63 6b 2e 20 20 54 68 65  usive lock.  The
18820 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 20 63   first process c
18830 61 6e 6e 6f 74 20 70 72 6f 63 65 65 64 0a 2a 2a  annot proceed.**
18840 20 62 65 63 61 75 73 65 20 69 74 20 69 73 20 62   because it is b
18850 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20 73 65  locked by the se
18860 63 6f 6e 64 20 61 6e 64 20 74 68 65 20 73 65 63  cond and the sec
18870 6f 6e 64 20 70 72 6f 63 65 73 73 20 63 61 6e 6e  ond process cann
18880 6f 74 0a 2a 2a 20 70 72 6f 63 65 65 64 20 62 65  ot.** proceed be
18890 63 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63  cause it is bloc
188a0 6b 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74  ked by the first
188b0 2e 20 20 49 66 20 62 6f 74 68 20 70 72 6f 63 65  .  If both proce
188c0 73 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74  sses.** invoke t
188d0 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73  he busy handlers
188e0 2c 20 6e 65 69 74 68 65 72 20 77 69 6c 6c 20 6d  , neither will m
188f0 61 6b 65 20 61 6e 79 20 70 72 6f 67 72 65 73 73  ake any progress
18900 2e 20 20 54 68 65 72 65 66 6f 72 65 2c 0a 2a 2a  .  Therefore,.**
18910 20 53 51 4c 69 74 65 20 72 65 74 75 72 6e 73 20   SQLite returns 
18920 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 66 6f  [SQLITE_BUSY] fo
18930 72 20 74 68 65 20 66 69 72 73 74 20 70 72 6f 63  r the first proc
18940 65 73 73 2c 20 68 6f 70 69 6e 67 20 74 68 61 74  ess, hoping that
18950 20 74 68 69 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e   this.** will in
18960 64 75 63 65 20 74 68 65 20 66 69 72 73 74 20 70  duce the first p
18970 72 6f 63 65 73 73 20 74 6f 20 72 65 6c 65 61 73  rocess to releas
18980 65 20 69 74 73 20 72 65 61 64 20 6c 6f 63 6b 20  e its read lock 
18990 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65  and allow.** the
189a0 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20   second process 
189b0 74 6f 20 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a  to proceed..**.*
189c0 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 62  * ^The default b
189d0 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  usy callback is 
189e0 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  NULL..**.** ^The
189f0 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 65   [SQLITE_BUSY] e
18a00 72 72 6f 72 20 69 73 20 63 6f 6e 76 65 72 74 65  rror is converte
18a10 64 20 74 6f 20 5b 53 51 4c 49 54 45 5f 49 4f 45  d to [SQLITE_IOE
18a20 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 77  RR_BLOCKED].** w
18a30 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 69 6e  hen SQLite is in
18a40 20 74 68 65 20 6d 69 64 64 6c 65 20 6f 66 20 61   the middle of a
18a50 20 6c 61 72 67 65 20 74 72 61 6e 73 61 63 74 69   large transacti
18a60 6f 6e 20 77 68 65 72 65 20 61 6c 6c 20 74 68 65  on where all the
18a70 0a 2a 2a 20 63 68 61 6e 67 65 73 20 77 69 6c 6c  .** changes will
18a80 20 6e 6f 74 20 66 69 74 20 69 6e 74 6f 20 74 68   not fit into th
18a90 65 20 69 6e 2d 6d 65 6d 6f 72 79 20 63 61 63 68  e in-memory cach
18aa0 65 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 0a  e.  SQLite will.
18ab0 2a 2a 20 61 6c 72 65 61 64 79 20 68 6f 6c 64 20  ** already hold 
18ac0 61 20 52 45 53 45 52 56 45 44 20 6c 6f 63 6b 20  a RESERVED lock 
18ad0 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  on the database 
18ae0 66 69 6c 65 2c 20 62 75 74 20 69 74 20 6e 65 65  file, but it nee
18af0 64 73 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65  ds.** to promote
18b00 20 74 68 69 73 20 6c 6f 63 6b 20 74 6f 20 45 58   this lock to EX
18b10 43 4c 55 53 49 56 45 20 73 6f 20 74 68 61 74 20  CLUSIVE so that 
18b20 69 74 20 63 61 6e 20 73 70 69 6c 6c 20 63 61 63  it can spill cac
18b30 68 65 0a 2a 2a 20 70 61 67 65 73 20 69 6e 74 6f  he.** pages into
18b40 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
18b50 6c 65 20 77 69 74 68 6f 75 74 20 68 61 72 6d 20  le without harm 
18b60 74 6f 20 63 6f 6e 63 75 72 72 65 6e 74 0a 2a 2a  to concurrent.**
18b70 20 72 65 61 64 65 72 73 2e 20 20 5e 49 66 20 69   readers.  ^If i
18b80 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 70  t is unable to p
18b90 72 6f 6d 6f 74 65 20 74 68 65 20 6c 6f 63 6b 2c  romote the lock,
18ba0 20 74 68 65 6e 20 74 68 65 20 69 6e 2d 6d 65 6d   then the in-mem
18bb0 6f 72 79 0a 2a 2a 20 63 61 63 68 65 20 77 69 6c  ory.** cache wil
18bc0 6c 20 62 65 20 6c 65 66 74 20 69 6e 20 61 6e 20  l be left in an 
18bd0 69 6e 63 6f 6e 73 69 73 74 65 6e 74 20 73 74 61  inconsistent sta
18be0 74 65 20 61 6e 64 20 73 6f 20 74 68 65 20 65 72  te and so the er
18bf0 72 6f 72 0a 2a 2a 20 63 6f 64 65 20 69 73 20 70  ror.** code is p
18c00 72 6f 6d 6f 74 65 64 20 66 72 6f 6d 20 74 68 65  romoted from the
18c10 20 72 65 6c 61 74 69 76 65 6c 79 20 62 65 6e 69   relatively beni
18c20 67 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  gn [SQLITE_BUSY]
18c30 20 74 6f 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20   to.** the more 
18c40 73 65 76 65 72 65 20 5b 53 51 4c 49 54 45 5f 49  severe [SQLITE_I
18c50 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e 20 20  OERR_BLOCKED].  
18c60 5e 54 68 69 73 20 65 72 72 6f 72 20 63 6f 64 65  ^This error code
18c70 20 70 72 6f 6d 6f 74 69 6f 6e 0a 2a 2a 20 66 6f   promotion.** fo
18c80 72 63 65 73 20 61 6e 20 61 75 74 6f 6d 61 74 69  rces an automati
18c90 63 20 72 6f 6c 6c 62 61 63 6b 20 6f 66 20 74 68  c rollback of th
18ca0 65 20 63 68 61 6e 67 65 73 2e 20 20 53 65 65 20  e changes.  See 
18cb0 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66 3d 22  the.** <a href="
18cc0 2f 63 76 73 74 72 61 63 2f 77 69 6b 69 3f 70 3d  /cvstrac/wiki?p=
18cd0 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77  CorruptionFollow
18ce0 69 6e 67 42 75 73 79 45 72 72 6f 72 22 3e 0a 2a  ingBusyError">.*
18cf0 2a 20 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c  * CorruptionFoll
18d00 6f 77 69 6e 67 42 75 73 79 45 72 72 6f 72 3c 2f  owingBusyError</
18d10 61 3e 20 77 69 6b 69 20 70 61 67 65 20 66 6f 72  a> wiki page for
18d20 20 61 20 64 69 73 63 75 73 73 69 6f 6e 20 6f 66   a discussion of
18d30 20 77 68 79 0a 2a 2a 20 74 68 69 73 20 69 73 20   why.** this is 
18d40 69 6d 70 6f 72 74 61 6e 74 2e 0a 2a 2a 0a 2a 2a  important..**.**
18d50 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c   ^(There can onl
18d60 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75  y be a single bu
18d70 73 79 20 68 61 6e 64 6c 65 72 20 64 65 66 69 6e  sy handler defin
18d80 65 64 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 5b  ed for each.** [
18d90 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
18da0 69 6f 6e 5d 2e 20 20 53 65 74 74 69 6e 67 20 61  ion].  Setting a
18db0 20 6e 65 77 20 62 75 73 79 20 68 61 6e 64 6c 65   new busy handle
18dc0 72 20 63 6c 65 61 72 73 20 61 6e 79 0a 2a 2a 20  r clears any.** 
18dd0 70 72 65 76 69 6f 75 73 6c 79 20 73 65 74 20 68  previously set h
18de0 61 6e 64 6c 65 72 2e 29 5e 20 20 5e 4e 6f 74 65  andler.)^  ^Note
18df0 20 74 68 61 74 20 63 61 6c 6c 69 6e 67 20 5b 73   that calling [s
18e00 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65  qlite3_busy_time
18e10 6f 75 74 28 29 5d 0a 2a 2a 20 77 69 6c 6c 20 61  out()].** will a
18e20 6c 73 6f 20 73 65 74 20 6f 72 20 63 6c 65 61 72  lso set or clear
18e30 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
18e40 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 62 75 73  r..**.** The bus
18e50 79 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c  y callback shoul
18e60 64 20 6e 6f 74 20 74 61 6b 65 20 61 6e 79 20 61  d not take any a
18e70 63 74 69 6f 6e 73 20 77 68 69 63 68 20 6d 6f 64  ctions which mod
18e80 69 66 79 20 74 68 65 0a 2a 2a 20 64 61 74 61 62  ify the.** datab
18e90 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  ase connection t
18ea0 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20  hat invoked the 
18eb0 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 20 20 41  busy handler.  A
18ec0 6e 79 20 73 75 63 68 20 61 63 74 69 6f 6e 73 0a  ny such actions.
18ed0 2a 2a 20 72 65 73 75 6c 74 20 69 6e 20 75 6e 64  ** result in und
18ee0 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e  efined behavior.
18ef0 0a 2a 2a 20 0a 2a 2a 20 41 20 62 75 73 79 20 68  .** .** A busy h
18f00 61 6e 64 6c 65 72 20 6d 75 73 74 20 6e 6f 74 20  andler must not 
18f10 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62 61  close the databa
18f20 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
18f30 20 6f 72 20 5b 70 72 65 70 61 72 65 64 20 73 74   or [prepared st
18f40 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 6e  atement] that in
18f50 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20 68  voked the busy h
18f60 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73  andler..*/.int s
18f70 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64  qlite3_busy_hand
18f80 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e  ler(sqlite3*, in
18f90 74 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 29 2c  t(*)(void*,int),
18fa0 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20   void*);../*.** 
18fb0 43 41 50 49 33 52 45 46 3a 20 53 65 74 20 41 20  CAPI3REF: Set A 
18fc0 42 75 73 79 20 54 69 6d 65 6f 75 74 0a 2a 2a 0a  Busy Timeout.**.
18fd0 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65  ** ^This routine
18fe0 20 73 65 74 73 20 61 20 5b 73 71 6c 69 74 65 33   sets a [sqlite3
18ff0 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 20 7c 20  _busy_handler | 
19000 62 75 73 79 20 68 61 6e 64 6c 65 72 5d 20 74 68  busy handler] th
19010 61 74 20 73 6c 65 65 70 73 0a 2a 2a 20 66 6f 72  at sleeps.** for
19020 20 61 20 73 70 65 63 69 66 69 65 64 20 61 6d 6f   a specified amo
19030 75 6e 74 20 6f 66 20 74 69 6d 65 20 77 68 65 6e  unt of time when
19040 20 61 20 74 61 62 6c 65 20 69 73 20 6c 6f 63 6b   a table is lock
19050 65 64 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c 65  ed.  ^The handle
19060 72 0a 2a 2a 20 77 69 6c 6c 20 73 6c 65 65 70 20  r.** will sleep 
19070 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 75  multiple times u
19080 6e 74 69 6c 20 61 74 20 6c 65 61 73 74 20 22 6d  ntil at least "m
19090 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20  s" milliseconds 
190a0 6f 66 20 73 6c 65 65 70 69 6e 67 0a 2a 2a 20 68  of sleeping.** h
190b0 61 76 65 20 61 63 63 75 6d 75 6c 61 74 65 64 2e  ave accumulated.
190c0 20 20 5e 41 66 74 65 72 20 61 74 20 6c 65 61 73    ^After at leas
190d0 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f  t "ms" milliseco
190e0 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 2c  nds of sleeping,
190f0 0a 2a 2a 20 74 68 65 20 68 61 6e 64 6c 65 72 20  .** the handler 
19100 72 65 74 75 72 6e 73 20 30 20 77 68 69 63 68 20  returns 0 which 
19110 63 61 75 73 65 73 20 5b 73 71 6c 69 74 65 33 5f  causes [sqlite3_
19120 73 74 65 70 28 29 5d 20 74 6f 20 72 65 74 75 72  step()] to retur
19130 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53  n.** [SQLITE_BUS
19140 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f  Y] or [SQLITE_IO
19150 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e 0a 2a 2a  ERR_BLOCKED]..**
19160 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 74 68 69  .** ^Calling thi
19170 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61  s routine with a
19180 6e 20 61 72 67 75 6d 65 6e 74 20 6c 65 73 73 20  n argument less 
19190 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f  than or equal to
191a0 20 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f   zero.** turns o
191b0 66 66 20 61 6c 6c 20 62 75 73 79 20 68 61 6e 64  ff all busy hand
191c0 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  lers..**.** ^(Th
191d0 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20  ere can only be 
191e0 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61  a single busy ha
191f0 6e 64 6c 65 72 20 66 6f 72 20 61 20 70 61 72 74  ndler for a part
19200 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62  icular.** [datab
19210 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
19220 61 6e 79 20 61 6e 79 20 67 69 76 65 6e 20 6d 6f  any any given mo
19230 6d 65 6e 74 2e 20 20 49 66 20 61 6e 6f 74 68 65  ment.  If anothe
19240 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72 0a 2a  r busy handler.*
19250 2a 20 77 61 73 20 64 65 66 69 6e 65 64 20 20 28  * was defined  (
19260 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62  using [sqlite3_b
19270 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d 29 20  usy_handler()]) 
19280 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67  prior to calling
19290 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65  .** this routine
192a0 2c 20 74 68 61 74 20 6f 74 68 65 72 20 62 75 73  , that other bus
192b0 79 20 68 61 6e 64 6c 65 72 20 69 73 20 63 6c 65  y handler is cle
192c0 61 72 65 64 2e 29 5e 0a 2a 2f 0a 69 6e 74 20 73  ared.)^.*/.int s
192d0 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65  qlite3_busy_time
192e0 6f 75 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e  out(sqlite3*, in
192f0 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  t ms);../*.** CA
19300 50 49 33 52 45 46 3a 20 43 6f 6e 76 65 6e 69 65  PI3REF: Convenie
19310 6e 63 65 20 52 6f 75 74 69 6e 65 73 20 46 6f 72  nce Routines For
19320 20 52 75 6e 6e 69 6e 67 20 51 75 65 72 69 65 73   Running Queries
19330 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 61  .**.** This is a
19340 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63   legacy interfac
19350 65 20 74 68 61 74 20 69 73 20 70 72 65 73 65 72  e that is preser
19360 76 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64  ved for backward
19370 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e  s compatibility.
19380 0a 2a 2a 20 55 73 65 20 6f 66 20 74 68 69 73 20  .** Use of this 
19390 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74  interface is not
193a0 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2a   recommended..**
193b0 0a 2a 2a 20 44 65 66 69 6e 69 74 69 6f 6e 3a 20  .** Definition: 
193c0 41 20 3c 62 3e 72 65 73 75 6c 74 20 74 61 62 6c  A <b>result tabl
193d0 65 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f 72 79 20  e</b> is memory 
193e0 64 61 74 61 20 73 74 72 75 63 74 75 72 65 20 63  data structure c
193f0 72 65 61 74 65 64 20 62 79 20 74 68 65 0a 2a 2a  reated by the.**
19400 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61   [sqlite3_get_ta
19410 62 6c 65 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ble()] interface
19420 2e 20 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c  .  A result tabl
19430 65 20 72 65 63 6f 72 64 73 20 74 68 65 0a 2a 2a  e records the.**
19440 20 63 6f 6d 70 6c 65 74 65 20 71 75 65 72 79 20   complete query 
19450 72 65 73 75 6c 74 73 20 66 72 6f 6d 20 6f 6e 65  results from one
19460 20 6f 72 20 6d 6f 72 65 20 71 75 65 72 69 65 73   or more queries
19470 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c  ..**.** The tabl
19480 65 20 63 6f 6e 63 65 70 74 75 61 6c 6c 79 20 68  e conceptually h
19490 61 73 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 72  as a number of r
194a0 6f 77 73 20 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e  ows and columns.
194b0 20 20 42 75 74 0a 2a 2a 20 74 68 65 73 65 20 6e    But.** these n
194c0 75 6d 62 65 72 73 20 61 72 65 20 6e 6f 74 20 70  umbers are not p
194d0 61 72 74 20 6f 66 20 74 68 65 20 72 65 73 75 6c  art of the resul
194e0 74 20 74 61 62 6c 65 20 69 74 73 65 6c 66 2e 20  t table itself. 
194f0 20 54 68 65 73 65 0a 2a 2a 20 6e 75 6d 62 65 72   These.** number
19500 73 20 61 72 65 20 6f 62 74 61 69 6e 65 64 20 73  s are obtained s
19510 65 70 61 72 61 74 65 6c 79 2e 20 20 4c 65 74 20  eparately.  Let 
19520 4e 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20  N be the number 
19530 6f 66 20 72 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d  of rows.** and M
19540 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   be the number o
19550 66 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a  f columns..**.**
19560 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   A result table 
19570 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70  is an array of p
19580 6f 69 6e 74 65 72 73 20 74 6f 20 7a 65 72 6f 2d  ointers to zero-
19590 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38  terminated UTF-8
195a0 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65   strings..** The
195b0 72 65 20 61 72 65 20 28 4e 2b 31 29 2a 4d 20 65  re are (N+1)*M e
195c0 6c 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 61  lements in the a
195d0 72 72 61 79 2e 20 20 54 68 65 20 66 69 72 73 74  rray.  The first
195e0 20 4d 20 70 6f 69 6e 74 65 72 73 20 70 6f 69 6e   M pointers poin
195f0 74 0a 2a 2a 20 74 6f 20 7a 65 72 6f 2d 74 65 72  t.** to zero-ter
19600 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20  minated strings 
19610 74 68 61 74 20 20 63 6f 6e 74 61 69 6e 20 74 68  that  contain th
19620 65 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 20 63  e names of the c
19630 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20 72  olumns..** The r
19640 65 6d 61 69 6e 69 6e 67 20 65 6e 74 72 69 65 73  emaining entries
19650 20 61 6c 6c 20 70 6f 69 6e 74 20 74 6f 20 71 75   all point to qu
19660 65 72 79 20 72 65 73 75 6c 74 73 2e 20 20 4e 55  ery results.  NU
19670 4c 4c 20 76 61 6c 75 65 73 20 72 65 73 75 6c 74  LL values result
19680 0a 2a 2a 20 69 6e 20 4e 55 4c 4c 20 70 6f 69 6e  .** in NULL poin
19690 74 65 72 73 2e 20 20 41 6c 6c 20 6f 74 68 65 72  ters.  All other
196a0 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e 20 74   values are in t
196b0 68 65 69 72 20 55 54 46 2d 38 20 7a 65 72 6f 2d  heir UTF-8 zero-
196c0 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74  terminated.** st
196d0 72 69 6e 67 20 72 65 70 72 65 73 65 6e 74 61 74  ring representat
196e0 69 6f 6e 20 61 73 20 72 65 74 75 72 6e 65 64 20  ion as returned 
196f0 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  by [sqlite3_colu
19700 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a  mn_text()]..**.*
19710 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65  * A result table
19720 20 6d 69 67 68 74 20 63 6f 6e 73 69 73 74 20 6f   might consist o
19730 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6d 65  f one or more me
19740 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73  mory allocations
19750 2e 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73  ..** It is not s
19760 61 66 65 20 74 6f 20 70 61 73 73 20 61 20 72 65  afe to pass a re
19770 73 75 6c 74 20 74 61 62 6c 65 20 64 69 72 65 63  sult table direc
19780 74 6c 79 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  tly to [sqlite3_
19790 66 72 65 65 28 29 5d 2e 0a 2a 2a 20 41 20 72 65  free()]..** A re
197a0 73 75 6c 74 20 74 61 62 6c 65 20 73 68 6f 75 6c  sult table shoul
197b0 64 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64  d be deallocated
197c0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
197d0 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a  free_table()]..*
197e0 2a 0a 2a 2a 20 5e 28 41 73 20 61 6e 20 65 78 61  *.** ^(As an exa
197f0 6d 70 6c 65 20 6f 66 20 74 68 65 20 72 65 73 75  mple of the resu
19800 6c 74 20 74 61 62 6c 65 20 66 6f 72 6d 61 74 2c  lt table format,
19810 20 73 75 70 70 6f 73 65 20 61 20 71 75 65 72 79   suppose a query
19820 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 61 73   result.** is as
19830 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20   follows:.**.** 
19840 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
19850 3e 0a 2a 2a 20 20 20 20 20 20 20 20 4e 61 6d 65  >.**        Name
19860 20 20 20 20 20 20 20 20 7c 20 41 67 65 0a 2a 2a          | Age.**
19870 20 20 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d          --------
19880 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a  ---------------.
19890 2a 2a 20 20 20 20 20 20 20 20 41 6c 69 63 65 20  **        Alice 
198a0 20 20 20 20 20 20 7c 20 34 33 0a 2a 2a 20 20 20        | 43.**   
198b0 20 20 20 20 20 42 6f 62 20 20 20 20 20 20 20 20       Bob        
198c0 20 7c 20 32 38 0a 2a 2a 20 20 20 20 20 20 20 20   | 28.**        
198d0 43 69 6e 64 79 20 20 20 20 20 20 20 7c 20 32 31  Cindy       | 21
198e0 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
198f0 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68  kquote>.**.** Th
19900 65 72 65 20 61 72 65 20 74 77 6f 20 63 6f 6c 75  ere are two colu
19910 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e 64 20 74 68  mn (M==2) and th
19920 72 65 65 20 72 6f 77 73 20 28 4e 3d 3d 33 29 2e  ree rows (N==3).
19930 20 20 54 68 75 73 20 74 68 65 0a 2a 2a 20 72 65    Thus the.** re
19940 73 75 6c 74 20 74 61 62 6c 65 20 68 61 73 20 38  sult table has 8
19950 20 65 6e 74 72 69 65 73 2e 20 20 53 75 70 70 6f   entries.  Suppo
19960 73 65 20 74 68 65 20 72 65 73 75 6c 74 20 74 61  se the result ta
19970 62 6c 65 20 69 73 20 73 74 6f 72 65 64 0a 2a 2a  ble is stored.**
19980 20 69 6e 20 61 6e 20 61 72 72 61 79 20 6e 61 6d   in an array nam
19990 65 73 20 61 7a 52 65 73 75 6c 74 2e 20 20 54 68  es azResult.  Th
199a0 65 6e 20 61 7a 52 65 73 75 6c 74 20 68 6f 6c 64  en azResult hold
199b0 73 20 74 68 69 73 20 63 6f 6e 74 65 6e 74 3a 0a  s this content:.
199c0 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
199d0 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20  e><pre>.**      
199e0 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 30    azResult&#91;0
199f0 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20  ] = "Name";.**  
19a00 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
19a10 39 31 3b 31 5d 20 3d 20 22 41 67 65 22 3b 0a 2a  91;1] = "Age";.*
19a20 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
19a30 74 26 23 39 31 3b 32 5d 20 3d 20 22 41 6c 69 63  t&#91;2] = "Alic
19a40 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  e";.**        az
19a50 52 65 73 75 6c 74 26 23 39 31 3b 33 5d 20 3d 20  Result&#91;3] = 
19a60 22 34 33 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  "43";.**        
19a70 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 34 5d 20  azResult&#91;4] 
19a80 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20 20 20 20 20  = "Bob";.**     
19a90 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
19aa0 35 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a 20 20 20  5] = "28";.**   
19ab0 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
19ac0 31 3b 36 5d 20 3d 20 22 43 69 6e 64 79 22 3b 0a  1;6] = "Cindy";.
19ad0 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
19ae0 6c 74 26 23 39 31 3b 37 5d 20 3d 20 22 32 31 22  lt&#91;7] = "21"
19af0 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
19b00 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a  ckquote>)^.**.**
19b10 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65   ^The sqlite3_ge
19b20 74 5f 74 61 62 6c 65 28 29 20 66 75 6e 63 74 69  t_table() functi
19b30 6f 6e 20 65 76 61 6c 75 61 74 65 73 20 6f 6e 65  on evaluates one
19b40 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d 69   or more.** semi
19b50 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65 64 20  colon-separated 
19b60 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69  SQL statements i
19b70 6e 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69  n the zero-termi
19b80 6e 61 74 65 64 20 55 54 46 2d 38 0a 2a 2a 20 73  nated UTF-8.** s
19b90 74 72 69 6e 67 20 6f 66 20 69 74 73 20 32 6e 64  tring of its 2nd
19ba0 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72   parameter and r
19bb0 65 74 75 72 6e 73 20 61 20 72 65 73 75 6c 74 20  eturns a result 
19bc0 74 61 62 6c 65 20 74 6f 20 74 68 65 0a 2a 2a 20  table to the.** 
19bd0 70 6f 69 6e 74 65 72 20 67 69 76 65 6e 20 69 6e  pointer given in
19be0 20 69 74 73 20 33 72 64 20 70 61 72 61 6d 65 74   its 3rd paramet
19bf0 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20  er..**.** After 
19c00 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
19c10 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74  has finished wit
19c20 68 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f  h the result fro
19c30 6d 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61  m sqlite3_get_ta
19c40 62 6c 65 28 29 2c 0a 2a 2a 20 69 74 20 6d 75 73  ble(),.** it mus
19c50 74 20 70 61 73 73 20 74 68 65 20 72 65 73 75 6c  t pass the resul
19c60 74 20 74 61 62 6c 65 20 70 6f 69 6e 74 65 72 20  t table pointer 
19c70 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f  to sqlite3_free_
19c80 74 61 62 6c 65 28 29 20 69 6e 20 6f 72 64 65 72  table() in order
19c90 20 74 6f 0a 2a 2a 20 72 65 6c 65 61 73 65 20 74   to.** release t
19ca0 68 65 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 77  he memory that w
19cb0 61 73 20 6d 61 6c 6c 6f 63 65 64 2e 20 20 42 65  as malloced.  Be
19cc0 63 61 75 73 65 20 6f 66 20 74 68 65 20 77 61 79  cause of the way
19cd0 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
19ce0 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68 61 70 70 65  _malloc()] happe
19cf0 6e 73 20 77 69 74 68 69 6e 20 73 71 6c 69 74 65  ns within sqlite
19d00 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 20 74  3_get_table(), t
19d10 68 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75  he calling.** fu
19d20 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20  nction must not 
19d30 74 72 79 20 74 6f 20 63 61 6c 6c 20 5b 73 71 6c  try to call [sql
19d40 69 74 65 33 5f 66 72 65 65 28 29 5d 20 64 69 72  ite3_free()] dir
19d50 65 63 74 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a 20  ectly.  Only.** 
19d60 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61  [sqlite3_free_ta
19d70 62 6c 65 28 29 5d 20 69 73 20 61 62 6c 65 20 74  ble()] is able t
19d80 6f 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65  o release the me
19d90 6d 6f 72 79 20 70 72 6f 70 65 72 6c 79 20 61 6e  mory properly an
19da0 64 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20  d safely..**.** 
19db0 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  The sqlite3_get_
19dc0 74 61 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63  table() interfac
19dd0 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64  e is implemented
19de0 20 61 73 20 61 20 77 72 61 70 70 65 72 20 61 72   as a wrapper ar
19df0 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ound.** [sqlite3
19e00 5f 65 78 65 63 28 29 5d 2e 20 20 54 68 65 20 73  _exec()].  The s
19e10 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
19e20 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20  () routine does 
19e30 6e 6f 74 20 68 61 76 65 20 61 63 63 65 73 73 0a  not have access.
19e40 2a 2a 20 74 6f 20 61 6e 79 20 69 6e 74 65 72 6e  ** to any intern
19e50 61 6c 20 64 61 74 61 20 73 74 72 75 63 74 75 72  al data structur
19e60 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 49  es of SQLite.  I
19e70 74 20 75 73 65 73 20 6f 6e 6c 79 20 74 68 65 20  t uses only the 
19e80 70 75 62 6c 69 63 0a 2a 2a 20 69 6e 74 65 72 66  public.** interf
19e90 61 63 65 20 64 65 66 69 6e 65 64 20 68 65 72 65  ace defined here
19ea0 2e 20 20 41 73 20 61 20 63 6f 6e 73 65 71 75 65  .  As a conseque
19eb0 6e 63 65 2c 20 65 72 72 6f 72 73 20 74 68 61 74  nce, errors that
19ec0 20 6f 63 63 75 72 20 69 6e 20 74 68 65 0a 2a 2a   occur in the.**
19ed0 20 77 72 61 70 70 65 72 20 6c 61 79 65 72 20 6f   wrapper layer o
19ee0 75 74 73 69 64 65 20 6f 66 20 74 68 65 20 69 6e  utside of the in
19ef0 74 65 72 6e 61 6c 20 5b 73 71 6c 69 74 65 33 5f  ternal [sqlite3_
19f00 65 78 65 63 28 29 5d 20 63 61 6c 6c 20 61 72 65  exec()] call are
19f10 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c 65 63 74 65   not.** reflecte
19f20 64 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20  d in subsequent 
19f30 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
19f40 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 6f 72 0a  3_errcode()] or.
19f50 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  ** [sqlite3_errm
19f60 73 67 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71  sg()]..*/.int sq
19f70 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
19f80 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
19f90 20 20 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f           /* An o
19fa0 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f 0a  pen database */.
19fb0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53    const char *zS
19fc0 71 6c 2c 20 20 20 20 20 2f 2a 20 53 51 4c 20 74  ql,     /* SQL t
19fd0 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a  o be evaluated *
19fe0 2f 0a 20 20 63 68 61 72 20 2a 2a 2a 70 61 7a 52  /.  char ***pazR
19ff0 65 73 75 6c 74 2c 20 20 20 20 2f 2a 20 52 65 73  esult,    /* Res
1a000 75 6c 74 73 20 6f 66 20 74 68 65 20 71 75 65 72  ults of the quer
1a010 79 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 52 6f  y */.  int *pnRo
1a020 77 2c 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  w,           /* 
1a030 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74  Number of result
1a040 20 72 6f 77 73 20 77 72 69 74 74 65 6e 20 68 65   rows written he
1a050 72 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 43  re */.  int *pnC
1a060 6f 6c 75 6d 6e 2c 20 20 20 20 20 20 20 20 2f 2a  olumn,        /*
1a070 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c   Number of resul
1a080 74 20 63 6f 6c 75 6d 6e 73 20 77 72 69 74 74 65  t columns writte
1a090 6e 20 68 65 72 65 20 2a 2f 0a 20 20 63 68 61 72  n here */.  char
1a0a0 20 2a 2a 70 7a 45 72 72 6d 73 67 20 20 20 20 20   **pzErrmsg     
1a0b0 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77    /* Error msg w
1a0c0 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29  ritten here */.)
1a0d0 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66  ;.void sqlite3_f
1a0e0 72 65 65 5f 74 61 62 6c 65 28 63 68 61 72 20 2a  ree_table(char *
1a0f0 2a 72 65 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a  *result);../*.**
1a100 20 43 41 50 49 33 52 45 46 3a 20 46 6f 72 6d 61   CAPI3REF: Forma
1a110 74 74 65 64 20 53 74 72 69 6e 67 20 50 72 69 6e  tted String Prin
1a120 74 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a  ting Functions.*
1a130 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
1a140 6e 65 73 20 61 72 65 20 77 6f 72 6b 2d 61 6c 69  nes are work-ali
1a150 6b 65 73 20 6f 66 20 74 68 65 20 22 70 72 69 6e  kes of the "prin
1a160 74 66 28 29 22 20 66 61 6d 69 6c 79 20 6f 66 20  tf()" family of 
1a170 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f  functions.** fro
1a180 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43  m the standard C
1a190 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20   library..**.** 
1a1a0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 70 72  ^The sqlite3_mpr
1a1b0 69 6e 74 66 28 29 20 61 6e 64 20 73 71 6c 69 74  intf() and sqlit
1a1c0 65 33 5f 76 6d 70 72 69 6e 74 66 28 29 20 72 6f  e3_vmprintf() ro
1a1d0 75 74 69 6e 65 73 20 77 72 69 74 65 20 74 68 65  utines write the
1a1e0 69 72 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e  ir.** results in
1a1f0 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e  to memory obtain
1a200 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
1a210 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54  _malloc()]..** T
1a220 68 65 20 73 74 72 69 6e 67 73 20 72 65 74 75 72  he strings retur
1a230 6e 65 64 20 62 79 20 74 68 65 73 65 20 74 77 6f  ned by these two
1a240 20 72 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c 64   routines should
1a250 20 62 65 0a 2a 2a 20 72 65 6c 65 61 73 65 64 20   be.** released 
1a260 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  by [sqlite3_free
1a270 28 29 5d 2e 20 20 5e 42 6f 74 68 20 72 6f 75 74  ()].  ^Both rout
1a280 69 6e 65 73 20 72 65 74 75 72 6e 20 61 0a 2a 2a  ines return a.**
1a290 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66   NULL pointer if
1a2a0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
1a2b0 28 29 5d 20 69 73 20 75 6e 61 62 6c 65 20 74 6f  ()] is unable to
1a2c0 20 61 6c 6c 6f 63 61 74 65 20 65 6e 6f 75 67 68   allocate enough
1a2d0 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f  .** memory to ho
1a2e0 6c 64 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67  ld the resulting
1a2f0 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e   string..**.** ^
1a300 28 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6e 70  (The sqlite3_snp
1a310 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 20  rintf() routine 
1a320 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 20 22 73  is similar to "s
1a330 6e 70 72 69 6e 74 66 28 29 22 20 66 72 6f 6d 0a  nprintf()" from.
1a340 2a 2a 20 74 68 65 20 73 74 61 6e 64 61 72 64 20  ** the standard 
1a350 43 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20  C library.  The 
1a360 72 65 73 75 6c 74 20 69 73 20 77 72 69 74 74 65  result is writte
1a370 6e 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 62 75  n into the.** bu
1a380 66 66 65 72 20 73 75 70 70 6c 69 65 64 20 61 73  ffer supplied as
1a390 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
1a3a0 6d 65 74 65 72 20 77 68 6f 73 65 20 73 69 7a 65  meter whose size
1a3b0 20 69 73 20 67 69 76 65 6e 20 62 79 0a 2a 2a 20   is given by.** 
1a3c0 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
1a3d0 74 65 72 2e 20 4e 6f 74 65 20 74 68 61 74 20 74  ter. Note that t
1a3e0 68 65 20 6f 72 64 65 72 20 6f 66 20 74 68 65 0a  he order of the.
1a3f0 2a 2a 20 66 69 72 73 74 20 74 77 6f 20 70 61 72  ** first two par
1a400 61 6d 65 74 65 72 73 20 69 73 20 72 65 76 65 72  ameters is rever
1a410 73 65 64 20 66 72 6f 6d 20 73 6e 70 72 69 6e 74  sed from snprint
1a420 66 28 29 2e 29 5e 20 20 54 68 69 73 20 69 73 20  f().)^  This is 
1a430 61 6e 0a 2a 2a 20 68 69 73 74 6f 72 69 63 61 6c  an.** historical
1a440 20 61 63 63 69 64 65 6e 74 20 74 68 61 74 20 63   accident that c
1a450 61 6e 6e 6f 74 20 62 65 20 66 69 78 65 64 20 77  annot be fixed w
1a460 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 0a  ithout breaking.
1a470 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d  ** backwards com
1a480 70 61 74 69 62 69 6c 69 74 79 2e 20 20 5e 28 4e  patibility.  ^(N
1a490 6f 74 65 20 61 6c 73 6f 20 74 68 61 74 20 73 71  ote also that sq
1a4a0 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
1a4b0 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 20 70 6f  .** returns a po
1a4c0 69 6e 74 65 72 20 74 6f 20 69 74 73 20 62 75 66  inter to its buf
1a4d0 66 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 74  fer instead of t
1a4e0 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20  he number of.** 
1a4f0 63 68 61 72 61 63 74 65 72 73 20 61 63 74 75 61  characters actua
1a500 6c 6c 79 20 77 72 69 74 74 65 6e 20 69 6e 74 6f  lly written into
1a510 20 74 68 65 20 62 75 66 66 65 72 2e 29 5e 20 20   the buffer.)^  
1a520 57 65 20 61 64 6d 69 74 20 74 68 61 74 0a 2a 2a  We admit that.**
1a530 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
1a540 68 61 72 61 63 74 65 72 73 20 77 72 69 74 74 65  haracters writte
1a550 6e 20 77 6f 75 6c 64 20 62 65 20 61 20 6d 6f 72  n would be a mor
1a560 65 20 75 73 65 66 75 6c 20 72 65 74 75 72 6e 0a  e useful return.
1a570 2a 2a 20 76 61 6c 75 65 20 62 75 74 20 77 65 20  ** value but we 
1a580 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65 20 74 68  cannot change th
1a590 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
1a5a0 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72   of sqlite3_snpr
1a5b0 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77 20 77 69  intf().** now wi
1a5c0 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 20 63  thout breaking c
1a5d0 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a  ompatibility..**
1a5e0 0a 2a 2a 20 5e 41 73 20 6c 6f 6e 67 20 61 73 20  .** ^As long as 
1a5f0 74 68 65 20 62 75 66 66 65 72 20 73 69 7a 65 20  the buffer size 
1a600 69 73 20 67 72 65 61 74 65 72 20 74 68 61 6e 20  is greater than 
1a610 7a 65 72 6f 2c 20 73 71 6c 69 74 65 33 5f 73 6e  zero, sqlite3_sn
1a620 70 72 69 6e 74 66 28 29 0a 2a 2a 20 67 75 61 72  printf().** guar
1a630 61 6e 74 65 65 73 20 74 68 61 74 20 74 68 65 20  antees that the 
1a640 62 75 66 66 65 72 20 69 73 20 61 6c 77 61 79 73  buffer is always
1a650 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
1a660 2e 20 20 5e 54 68 65 20 66 69 72 73 74 0a 2a 2a  .  ^The first.**
1a670 20 70 61 72 61 6d 65 74 65 72 20 22 6e 22 20 69   parameter "n" i
1a680 73 20 74 68 65 20 74 6f 74 61 6c 20 73 69 7a 65  s the total size
1a690 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 2c 20   of the buffer, 
1a6a0 69 6e 63 6c 75 64 69 6e 67 20 73 70 61 63 65 20  including space 
1a6b0 66 6f 72 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 20  for.** the zero 
1a6c0 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 53 6f 20  terminator.  So 
1a6d0 74 68 65 20 6c 6f 6e 67 65 73 74 20 73 74 72 69  the longest stri
1a6e0 6e 67 20 74 68 61 74 20 63 61 6e 20 62 65 20 63  ng that can be c
1a6f0 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a 20 77 72 69  ompletely.** wri
1a700 74 74 65 6e 20 77 69 6c 6c 20 62 65 20 6e 2d 31  tten will be n-1
1a710 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a   characters..**.
1a720 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
1a730 76 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74  vsnprintf() rout
1a740 69 6e 65 20 69 73 20 61 20 76 61 72 61 72 67 73  ine is a varargs
1a750 20 76 65 72 73 69 6f 6e 20 6f 66 20 73 71 6c 69   version of sqli
1a760 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 2e 0a  te3_snprintf()..
1a770 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
1a780 69 6e 65 73 20 61 6c 6c 20 69 6d 70 6c 65 6d 65  ines all impleme
1a790 6e 74 20 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e  nt some addition
1a7a0 61 6c 20 66 6f 72 6d 61 74 74 69 6e 67 0a 2a 2a  al formatting.**
1a7b0 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 20 61 72   options that ar
1a7c0 65 20 75 73 65 66 75 6c 20 66 6f 72 20 63 6f 6e  e useful for con
1a7d0 73 74 72 75 63 74 69 6e 67 20 53 51 4c 20 73 74  structing SQL st
1a7e0 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 41 6c 6c  atements..** All
1a7f0 20 6f 66 20 74 68 65 20 75 73 75 61 6c 20 70 72   of the usual pr
1a800 69 6e 74 66 28 29 20 66 6f 72 6d 61 74 74 69 6e  intf() formattin
1a810 67 20 6f 70 74 69 6f 6e 73 20 61 70 70 6c 79 2e  g options apply.
1a820 20 20 49 6e 20 61 64 64 69 74 69 6f 6e 2c 20 74    In addition, t
1a830 68 65 72 65 0a 2a 2a 20 69 73 20 61 72 65 20 22  here.** is are "
1a840 25 71 22 2c 20 22 25 51 22 2c 20 61 6e 64 20 22  %q", "%Q", and "
1a850 25 7a 22 20 6f 70 74 69 6f 6e 73 2e 0a 2a 2a 0a  %z" options..**.
1a860 2a 2a 20 5e 28 54 68 65 20 25 71 20 6f 70 74 69  ** ^(The %q opti
1a870 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 73  on works like %s
1a880 20 69 6e 20 74 68 61 74 20 69 74 20 73 75 62 73   in that it subs
1a890 74 69 74 75 74 65 73 20 61 20 6e 75 6c 2d 74 65  titutes a nul-te
1a8a0 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69  rminated.** stri
1a8b0 6e 67 20 66 72 6f 6d 20 74 68 65 20 61 72 67 75  ng from the argu
1a8c0 6d 65 6e 74 20 6c 69 73 74 2e 20 20 42 75 74 20  ment list.  But 
1a8d0 25 71 20 61 6c 73 6f 20 64 6f 75 62 6c 65 73 20  %q also doubles 
1a8e0 65 76 65 72 79 20 27 5c 27 27 20 63 68 61 72 61  every '\'' chara
1a8f0 63 74 65 72 2e 0a 2a 2a 20 25 71 20 69 73 20 64  cter..** %q is d
1a900 65 73 69 67 6e 65 64 20 66 6f 72 20 75 73 65 20  esigned for use 
1a910 69 6e 73 69 64 65 20 61 20 73 74 72 69 6e 67 20  inside a string 
1a920 6c 69 74 65 72 61 6c 2e 29 5e 20 20 42 79 20 64  literal.)^  By d
1a930 6f 75 62 6c 69 6e 67 20 65 61 63 68 20 27 5c 27  oubling each '\'
1a940 27 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 20 69  '.** character i
1a950 74 20 65 73 63 61 70 65 73 20 74 68 61 74 20 63  t escapes that c
1a960 68 61 72 61 63 74 65 72 20 61 6e 64 20 61 6c 6c  haracter and all
1a970 6f 77 73 20 69 74 20 74 6f 20 62 65 20 69 6e 73  ows it to be ins
1a980 65 72 74 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68  erted into.** th
1a990 65 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  e string..**.** 
1a9a0 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 73 73  For example, ass
1a9b0 75 6d 65 20 74 68 65 20 73 74 72 69 6e 67 20 76  ume the string v
1a9c0 61 72 69 61 62 6c 65 20 7a 54 65 78 74 20 63 6f  ariable zText co
1a9d0 6e 74 61 69 6e 73 20 74 65 78 74 20 61 73 20 66  ntains text as f
1a9e0 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ollows:.**.** <b
1a9f0 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
1aa00 2a 2a 20 20 63 68 61 72 20 2a 7a 54 65 78 74 20  **  char *zText 
1aa10 3d 20 22 49 74 27 73 20 61 20 68 61 70 70 79 20  = "It's a happy 
1aa20 64 61 79 21 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e  day!";.** </pre>
1aa30 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
1aa40 0a 2a 2a 20 4f 6e 65 20 63 61 6e 20 75 73 65 20  .** One can use 
1aa50 74 68 69 73 20 74 65 78 74 20 69 6e 20 61 6e 20  this text in an 
1aa60 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 73  SQL statement as
1aa70 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20   follows:.**.** 
1aa80 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
1aa90 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c  >.**  char *zSQL
1aaa0 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e   = sqlite3_mprin
1aab0 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20  tf("INSERT INTO 
1aac0 74 61 62 6c 65 20 56 41 4c 55 45 53 28 27 25 71  table VALUES('%q
1aad0 27 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20  ')", zText);.** 
1aae0 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62   sqlite3_exec(db
1aaf0 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29  , zSQL, 0, 0, 0)
1ab00 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72  ;.**  sqlite3_fr
1ab10 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70  ee(zSQL);.** </p
1ab20 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
1ab30 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74  .**.** Because t
1ab40 68 65 20 25 71 20 66 6f 72 6d 61 74 20 73 74 72  he %q format str
1ab50 69 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68 65  ing is used, the
1ab60 20 27 5c 27 27 20 63 68 61 72 61 63 74 65 72 20   '\'' character 
1ab70 69 6e 20 7a 54 65 78 74 0a 2a 2a 20 69 73 20 65  in zText.** is e
1ab80 73 63 61 70 65 64 20 61 6e 64 20 74 68 65 20 53  scaped and the S
1ab90 51 4c 20 67 65 6e 65 72 61 74 65 64 20 69 73 20  QL generated is 
1aba0 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a  as follows:.**.*
1abb0 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
1abc0 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49  re>.**  INSERT I
1abd0 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45  NTO table1 VALUE
1abe0 53 28 27 49 74 27 27 73 20 61 20 68 61 70 70 79  S('It''s a happy
1abf0 20 64 61 79 21 27 29 0a 2a 2a 20 3c 2f 70 72 65   day!').** </pre
1ac00 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
1ac10 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 63 6f 72  *.** This is cor
1ac20 72 65 63 74 2e 20 20 48 61 64 20 77 65 20 75 73  rect.  Had we us
1ac30 65 64 20 25 73 20 69 6e 73 74 65 61 64 20 6f 66  ed %s instead of
1ac40 20 25 71 2c 20 74 68 65 20 67 65 6e 65 72 61 74   %q, the generat
1ac50 65 64 20 53 51 4c 0a 2a 2a 20 77 6f 75 6c 64 20  ed SQL.** would 
1ac60 68 61 76 65 20 6c 6f 6f 6b 65 64 20 6c 69 6b 65  have looked like
1ac70 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c   this:.**.** <bl
1ac80 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
1ac90 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74  *  INSERT INTO t
1aca0 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74  able1 VALUES('It
1acb0 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21 27  's a happy day!'
1acc0 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  );.** </pre></bl
1acd0 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
1ace0 54 68 69 73 20 73 65 63 6f 6e 64 20 65 78 61 6d  This second exam
1acf0 70 6c 65 20 69 73 20 61 6e 20 53 51 4c 20 73 79  ple is an SQL sy
1ad00 6e 74 61 78 20 65 72 72 6f 72 2e 20 20 41 73 20  ntax error.  As 
1ad10 61 20 67 65 6e 65 72 61 6c 20 72 75 6c 65 20 79  a general rule y
1ad20 6f 75 20 73 68 6f 75 6c 64 0a 2a 2a 20 61 6c 77  ou should.** alw
1ad30 61 79 73 20 75 73 65 20 25 71 20 69 6e 73 74 65  ays use %q inste
1ad40 61 64 20 6f 66 20 25 73 20 77 68 65 6e 20 69 6e  ad of %s when in
1ad50 73 65 72 74 69 6e 67 20 74 65 78 74 20 69 6e 74  serting text int
1ad60 6f 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72  o a string liter
1ad70 61 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  al..**.** ^(The 
1ad80 25 51 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20  %Q option works 
1ad90 6c 69 6b 65 20 25 71 20 65 78 63 65 70 74 20 69  like %q except i
1ada0 74 20 61 6c 73 6f 20 61 64 64 73 20 73 69 6e 67  t also adds sing
1adb0 6c 65 20 71 75 6f 74 65 73 20 61 72 6f 75 6e 64  le quotes around
1adc0 0a 2a 2a 20 74 68 65 20 6f 75 74 73 69 64 65 20  .** the outside 
1add0 6f 66 20 74 68 65 20 74 6f 74 61 6c 20 73 74 72  of the total str
1ade0 69 6e 67 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c  ing.  Additional
1adf0 6c 79 2c 20 69 66 20 74 68 65 20 70 61 72 61 6d  ly, if the param
1ae00 65 74 65 72 20 69 6e 20 74 68 65 0a 2a 2a 20 61  eter in the.** a
1ae10 72 67 75 6d 65 6e 74 20 6c 69 73 74 20 69 73 20  rgument list is 
1ae20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  a NULL pointer, 
1ae30 25 51 20 73 75 62 73 74 69 74 75 74 65 73 20 74  %Q substitutes t
1ae40 68 65 20 74 65 78 74 20 22 4e 55 4c 4c 22 20 28  he text "NULL" (
1ae50 77 69 74 68 6f 75 74 0a 2a 2a 20 73 69 6e 67 6c  without.** singl
1ae60 65 20 71 75 6f 74 65 73 29 2e 29 5e 20 20 53 6f  e quotes).)^  So
1ae70 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 6f  , for example, o
1ae80 6e 65 20 63 6f 75 6c 64 20 73 61 79 3a 0a 2a 2a  ne could say:.**
1ae90 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
1aea0 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a  <pre>.**  char *
1aeb0 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d  zSQL = sqlite3_m
1aec0 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49  printf("INSERT I
1aed0 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53  NTO table VALUES
1aee0 28 25 51 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a  (%Q)", zText);.*
1aef0 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  *  sqlite3_exec(
1af00 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20  db, zSQL, 0, 0, 
1af10 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f  0);.**  sqlite3_
1af20 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c  free(zSQL);.** <
1af30 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
1af40 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64  e>.**.** The cod
1af50 65 20 61 62 6f 76 65 20 77 69 6c 6c 20 72 65 6e  e above will ren
1af60 64 65 72 20 61 20 63 6f 72 72 65 63 74 20 53 51  der a correct SQ
1af70 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 74  L statement in t
1af80 68 65 20 7a 53 51 4c 0a 2a 2a 20 76 61 72 69 61  he zSQL.** varia
1af90 62 6c 65 20 65 76 65 6e 20 69 66 20 74 68 65 20  ble even if the 
1afa0 7a 54 65 78 74 20 76 61 72 69 61 62 6c 65 20 69  zText variable i
1afb0 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
1afc0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 22 25  ..**.** ^(The "%
1afd0 7a 22 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70  z" formatting op
1afe0 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20  tion works like 
1aff0 22 25 73 22 20 62 75 74 20 77 69 74 68 20 74 68  "%s" but with th
1b000 65 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 20 74 68  e.** addition th
1b010 61 74 20 61 66 74 65 72 20 74 68 65 20 73 74 72  at after the str
1b020 69 6e 67 20 68 61 73 20 62 65 65 6e 20 72 65 61  ing has been rea
1b030 64 20 61 6e 64 20 63 6f 70 69 65 64 20 69 6e 74  d and copied int
1b040 6f 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 2c  o.** the result,
1b050 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
1b060 5d 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 74  ] is called on t
1b070 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 2e  he input string.
1b080 29 5e 0a 2a 2f 0a 63 68 61 72 20 2a 73 71 6c 69  )^.*/.char *sqli
1b090 74 65 33 5f 6d 70 72 69 6e 74 66 28 63 6f 6e 73  te3_mprintf(cons
1b0a0 74 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 63 68  t char*,...);.ch
1b0b0 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 6d 70 72  ar *sqlite3_vmpr
1b0c0 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a  intf(const char*
1b0d0 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 63 68 61 72  , va_list);.char
1b0e0 20 2a 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e   *sqlite3_snprin
1b0f0 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e  tf(int,char*,con
1b100 73 74 20 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a  st char*, ...);.
1b110 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 73  char *sqlite3_vs
1b120 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72  nprintf(int,char
1b130 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76  *,const char*, v
1b140 61 5f 6c 69 73 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  a_list);../*.** 
1b150 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79  CAPI3REF: Memory
1b160 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 53 75 62 73   Allocation Subs
1b170 79 73 74 65 6d 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ystem.**.** The 
1b180 53 51 4c 69 74 65 20 63 6f 72 65 20 75 73 65 73  SQLite core uses
1b190 20 74 68 65 73 65 20 74 68 72 65 65 20 72 6f 75   these three rou
1b1a0 74 69 6e 65 73 20 66 6f 72 20 61 6c 6c 20 6f 66  tines for all of
1b1b0 20 69 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65   its own.** inte
1b1c0 72 6e 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  rnal memory allo
1b1d0 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 20 22 43  cation needs. "C
1b1e0 6f 72 65 22 20 69 6e 20 74 68 65 20 70 72 65 76  ore" in the prev
1b1f0 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 0a 2a 2a  ious sentence.**
1b200 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64   does not includ
1b210 65 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74  e operating-syst
1b220 65 6d 20 73 70 65 63 69 66 69 63 20 56 46 53 20  em specific VFS 
1b230 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20  implementation. 
1b240 20 54 68 65 0a 2a 2a 20 57 69 6e 64 6f 77 73 20   The.** Windows 
1b250 56 46 53 20 75 73 65 73 20 6e 61 74 69 76 65 20  VFS uses native 
1b260 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65  malloc() and fre
1b270 65 28 29 20 66 6f 72 20 73 6f 6d 65 20 6f 70 65  e() for some ope
1b280 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e  rations..**.** ^
1b290 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  The sqlite3_mall
1b2a0 6f 63 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74  oc() routine ret
1b2b0 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
1b2c0 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20  o a block.** of 
1b2d0 6d 65 6d 6f 72 79 20 61 74 20 6c 65 61 73 74 20  memory at least 
1b2e0 4e 20 62 79 74 65 73 20 69 6e 20 6c 65 6e 67 74  N bytes in lengt
1b2f0 68 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68  h, where N is th
1b300 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20  e parameter..** 
1b310 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ^If sqlite3_mall
1b320 6f 63 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74  oc() is unable t
1b330 6f 20 6f 62 74 61 69 6e 20 73 75 66 66 69 63 69  o obtain suffici
1b340 65 6e 74 20 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f  ent free.** memo
1b350 72 79 2c 20 69 74 20 72 65 74 75 72 6e 73 20 61  ry, it returns a
1b360 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20   NULL pointer.  
1b370 5e 49 66 20 74 68 65 20 70 61 72 61 6d 65 74 65  ^If the paramete
1b380 72 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  r N to.** sqlite
1b390 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65  3_malloc() is ze
1b3a0 72 6f 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74  ro or negative t
1b3b0 68 65 6e 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  hen sqlite3_mall
1b3c0 6f 63 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20  oc() returns.** 
1b3d0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
1b3e0 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73  **.** ^Calling s
1b3f0 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 77 69  qlite3_free() wi
1b400 74 68 20 61 20 70 6f 69 6e 74 65 72 20 70 72 65  th a pointer pre
1b410 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64  viously returned
1b420 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 6d  .** by sqlite3_m
1b430 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74  alloc() or sqlit
1b440 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 6c  e3_realloc() rel
1b450 65 61 73 65 73 20 74 68 61 74 20 6d 65 6d 6f 72  eases that memor
1b460 79 20 73 6f 0a 2a 2a 20 74 68 61 74 20 69 74 20  y so.** that it 
1b470 6d 69 67 68 74 20 62 65 20 72 65 75 73 65 64 2e  might be reused.
1b480 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66    ^The sqlite3_f
1b490 72 65 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73  ree() routine is
1b4a0 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69 66 20 69  .** a no-op if i
1b4b0 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20  s called with a 
1b4c0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 50  NULL pointer.  P
1b4d0 61 73 73 69 6e 67 20 61 20 4e 55 4c 4c 20 70 6f  assing a NULL po
1b4e0 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 73 71 6c 69  inter.** to sqli
1b4f0 74 65 33 5f 66 72 65 65 28 29 20 69 73 20 68 61  te3_free() is ha
1b500 72 6d 6c 65 73 73 2e 20 20 41 66 74 65 72 20 62  rmless.  After b
1b510 65 69 6e 67 20 66 72 65 65 64 2c 20 6d 65 6d 6f  eing freed, memo
1b520 72 79 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 65 69  ry.** should nei
1b530 74 68 65 72 20 62 65 20 72 65 61 64 20 6e 6f 72  ther be read nor
1b540 20 77 72 69 74 74 65 6e 2e 20 20 45 76 65 6e 20   written.  Even 
1b550 72 65 61 64 69 6e 67 20 70 72 65 76 69 6f 75 73  reading previous
1b560 6c 79 20 66 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f  ly freed.** memo
1b570 72 79 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20  ry might result 
1b580 69 6e 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f  in a segmentatio
1b590 6e 20 66 61 75 6c 74 20 6f 72 20 6f 74 68 65 72  n fault or other
1b5a0 20 73 65 76 65 72 65 20 65 72 72 6f 72 2e 0a 2a   severe error..*
1b5b0 2a 20 4d 65 6d 6f 72 79 20 63 6f 72 72 75 70 74  * Memory corrupt
1b5c0 69 6f 6e 2c 20 61 20 73 65 67 6d 65 6e 74 61 74  ion, a segmentat
1b5d0 69 6f 6e 20 66 61 75 6c 74 2c 20 6f 72 20 6f 74  ion fault, or ot
1b5e0 68 65 72 20 73 65 76 65 72 65 20 65 72 72 6f 72  her severe error
1b5f0 0a 2a 2a 20 6d 69 67 68 74 20 72 65 73 75 6c 74  .** might result
1b600 20 69 66 20 73 71 6c 69 74 65 33 5f 66 72 65 65   if sqlite3_free
1b610 28 29 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74  () is called wit
1b620 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69  h a non-NULL poi
1b630 6e 74 65 72 20 74 68 61 74 0a 2a 2a 20 77 61 73  nter that.** was
1b640 20 6e 6f 74 20 6f 62 74 61 69 6e 65 64 20 66 72   not obtained fr
1b650 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  om sqlite3_mallo
1b660 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  c() or sqlite3_r
1b670 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a 20  ealloc()..**.** 
1b680 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65  ^(The sqlite3_re
1b690 61 6c 6c 6f 63 28 29 20 69 6e 74 65 72 66 61 63  alloc() interfac
1b6a0 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65  e attempts to re
1b6b0 73 69 7a 65 20 61 0a 2a 2a 20 70 72 69 6f 72 20  size a.** prior 
1b6c0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
1b6d0 6e 20 74 6f 20 62 65 20 61 74 20 6c 65 61 73 74  n to be at least
1b6e0 20 4e 20 62 79 74 65 73 2c 20 77 68 65 72 65 20   N bytes, where 
1b6f0 4e 20 69 73 20 74 68 65 0a 2a 2a 20 73 65 63 6f  N is the.** seco
1b700 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54  nd parameter.  T
1b710 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
1b720 74 69 6f 6e 20 74 6f 20 62 65 20 72 65 73 69 7a  tion to be resiz
1b730 65 64 20 69 73 20 74 68 65 20 66 69 72 73 74 0a  ed is the first.
1b740 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 29 5e 20  ** parameter.)^ 
1b750 5e 20 49 66 20 74 68 65 20 66 69 72 73 74 20 70  ^ If the first p
1b760 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
1b770 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a  te3_realloc().**
1b780 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
1b790 65 72 20 74 68 65 6e 20 69 74 73 20 62 65 68 61  er then its beha
1b7a0 76 69 6f 72 20 69 73 20 69 64 65 6e 74 69 63 61  vior is identica
1b7b0 6c 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20  l to calling.** 
1b7c0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e  sqlite3_malloc(N
1b7d0 29 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65  ) where N is the
1b7e0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
1b7f0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61  r to sqlite3_rea
1b800 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 5e 49 66 20 74  lloc()..** ^If t
1b810 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
1b820 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72  ter to sqlite3_r
1b830 65 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f  ealloc() is zero
1b840 20 6f 72 0a 2a 2a 20 6e 65 67 61 74 69 76 65 20   or.** negative 
1b850 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
1b860 72 20 69 73 20 65 78 61 63 74 6c 79 20 74 68 65  r is exactly the
1b870 20 73 61 6d 65 20 61 73 20 63 61 6c 6c 69 6e 67   same as calling
1b880 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 72 65 65  .** sqlite3_free
1b890 28 50 29 20 77 68 65 72 65 20 50 20 69 73 20 74  (P) where P is t
1b8a0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
1b8b0 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65  er to sqlite3_re
1b8c0 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 5e 73 71 6c  alloc()..** ^sql
1b8d0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72  ite3_realloc() r
1b8e0 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
1b8f0 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c   to a memory all
1b900 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74  ocation.** of at
1b910 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20 69   least N bytes i
1b920 6e 20 73 69 7a 65 20 6f 72 20 4e 55 4c 4c 20 69  n size or NULL i
1b930 66 20 73 75 66 66 69 63 69 65 6e 74 20 6d 65 6d  f sufficient mem
1b940 6f 72 79 20 69 73 20 75 6e 61 76 61 69 6c 61 62  ory is unavailab
1b950 6c 65 2e 0a 2a 2a 20 5e 49 66 20 4d 20 69 73 20  le..** ^If M is 
1b960 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
1b970 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e  prior allocation
1b980 2c 20 74 68 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20  , then min(N,M) 
1b990 62 79 74 65 73 0a 2a 2a 20 6f 66 20 74 68 65 20  bytes.** of the 
1b9a0 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e  prior allocation
1b9b0 20 61 72 65 20 63 6f 70 69 65 64 20 69 6e 74 6f   are copied into
1b9c0 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f   the beginning o
1b9d0 66 20 62 75 66 66 65 72 20 72 65 74 75 72 6e 65  f buffer returne
1b9e0 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f  d.** by sqlite3_
1b9f0 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20 74 68  realloc() and th
1ba00 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69  e prior allocati
1ba10 6f 6e 20 69 73 20 66 72 65 65 64 2e 0a 2a 2a 20  on is freed..** 
1ba20 5e 49 66 20 73 71 6c 69 74 65 33 5f 72 65 61 6c  ^If sqlite3_real
1ba30 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 20 4e 55  loc() returns NU
1ba40 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20 70 72 69  LL, then the pri
1ba50 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a  or allocation.**
1ba60 20 69 73 20 6e 6f 74 20 66 72 65 65 64 2e 0a 2a   is not freed..*
1ba70 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79  *.** ^The memory
1ba80 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
1ba90 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 61 6e  ite3_malloc() an
1baa0 64 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  d sqlite3_reallo
1bab0 63 28 29 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73  c().** is always
1bac0 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 74 20 6c   aligned to at l
1bad0 65 61 73 74 20 61 6e 20 38 20 62 79 74 65 20 62  east an 8 byte b
1bae0 6f 75 6e 64 61 72 79 2c 20 6f 72 20 74 6f 20 61  oundary, or to a
1baf0 0a 2a 2a 20 34 20 62 79 74 65 20 62 6f 75 6e 64  .** 4 byte bound
1bb00 61 72 79 20 69 66 20 74 68 65 20 5b 53 51 4c 49  ary if the [SQLI
1bb10 54 45 5f 34 5f 42 59 54 45 5f 41 4c 49 47 4e 45  TE_4_BYTE_ALIGNE
1bb20 44 5f 4d 41 4c 4c 4f 43 5d 20 63 6f 6d 70 69 6c  D_MALLOC] compil
1bb30 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e  e-time.** option
1bb40 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20   is used..**.** 
1bb50 49 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  In SQLite versio
1bb60 6e 20 33 2e 35 2e 30 20 61 6e 64 20 33 2e 35 2e  n 3.5.0 and 3.5.
1bb70 31 2c 20 69 74 20 77 61 73 20 70 6f 73 73 69 62  1, it was possib
1bb80 6c 65 20 74 6f 20 64 65 66 69 6e 65 0a 2a 2a 20  le to define.** 
1bb90 74 68 65 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  the SQLITE_OMIT_
1bba0 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54 49 4f  MEMORY_ALLOCATIO
1bbb0 4e 20 77 68 69 63 68 20 77 6f 75 6c 64 20 63 61  N which would ca
1bbc0 75 73 65 20 74 68 65 20 62 75 69 6c 74 2d 69 6e  use the built-in
1bbd0 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
1bbe0 6f 6e 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  on of these rout
1bbf0 69 6e 65 73 20 74 6f 20 62 65 20 6f 6d 69 74 74  ines to be omitt
1bc00 65 64 2e 20 20 54 68 61 74 20 63 61 70 61 62 69  ed.  That capabi
1bc10 6c 69 74 79 0a 2a 2a 20 69 73 20 6e 6f 20 6c 6f  lity.** is no lo
1bc20 6e 67 65 72 20 70 72 6f 76 69 64 65 64 2e 20 20  nger provided.  
1bc30 4f 6e 6c 79 20 62 75 69 6c 74 2d 69 6e 20 6d 65  Only built-in me
1bc40 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 20  mory allocators 
1bc50 63 61 6e 20 62 65 20 75 73 65 64 2e 0a 2a 2a 0a  can be used..**.
1bc60 2a 2a 20 50 72 69 6f 72 20 74 6f 20 53 51 4c 69  ** Prior to SQLi
1bc70 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e 31  te version 3.7.1
1bc80 30 2c 20 74 68 65 20 57 69 6e 64 6f 77 73 20 4f  0, the Windows O
1bc90 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65  S interface laye
1bca0 72 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 68 65 20  r called.** the 
1bcb0 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20  system malloc() 
1bcc0 61 6e 64 20 66 72 65 65 28 29 20 64 69 72 65 63  and free() direc
1bcd0 74 6c 79 20 77 68 65 6e 20 63 6f 6e 76 65 72 74  tly when convert
1bce0 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 73  ing.** filenames
1bcf0 20 62 65 74 77 65 65 6e 20 74 68 65 20 55 54 46   between the UTF
1bd00 2d 38 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64  -8 encoding used
1bd10 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e   by SQLite.** an
1bd20 64 20 77 68 61 74 65 76 65 72 20 66 69 6c 65 6e  d whatever filen
1bd30 61 6d 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20  ame encoding is 
1bd40 75 73 65 64 20 62 79 20 74 68 65 20 70 61 72 74  used by the part
1bd50 69 63 75 6c 61 72 20 57 69 6e 64 6f 77 73 0a 2a  icular Windows.*
1bd60 2a 20 69 6e 73 74 61 6c 6c 61 74 69 6f 6e 2e 20  * installation. 
1bd70 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   Memory allocati
1bd80 6f 6e 20 65 72 72 6f 72 73 20 77 65 72 65 20 64  on errors were d
1bd90 65 74 65 63 74 65 64 2c 20 62 75 74 0a 2a 2a 20  etected, but.** 
1bda0 74 68 65 79 20 77 65 72 65 20 72 65 70 6f 72 74  they were report
1bdb0 65 64 20 62 61 63 6b 20 61 73 20 5b 53 51 4c 49  ed back as [SQLI
1bdc0 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a  TE_CANTOPEN] or.
1bdd0 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  ** [SQLITE_IOERR
1bde0 5d 20 72 61 74 68 65 72 20 74 68 61 6e 20 5b 53  ] rather than [S
1bdf0 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a  QLITE_NOMEM]..**
1be00 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65 72 20  .** The pointer 
1be10 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 5b 73 71  arguments to [sq
1be20 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 61 6e  lite3_free()] an
1be30 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  d [sqlite3_reall
1be40 6f 63 28 29 5d 0a 2a 2a 20 6d 75 73 74 20 62 65  oc()].** must be
1be50 20 65 69 74 68 65 72 20 4e 55 4c 4c 20 6f 72 20   either NULL or 
1be60 65 6c 73 65 20 70 6f 69 6e 74 65 72 73 20 6f 62  else pointers ob
1be70 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 20 70 72  tained from a pr
1be80 69 6f 72 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f  ior.** invocatio
1be90 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61  n of [sqlite3_ma
1bea0 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69  lloc()] or [sqli
1beb0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 74  te3_realloc()] t
1bec0 68 61 74 20 68 61 76 65 0a 2a 2a 20 6e 6f 74 20  hat have.** not 
1bed0 79 65 74 20 62 65 65 6e 20 72 65 6c 65 61 73 65  yet been release
1bee0 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70  d..**.** The app
1bef0 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f  lication must no
1bf00 74 20 72 65 61 64 20 6f 72 20 77 72 69 74 65 20  t read or write 
1bf10 61 6e 79 20 70 61 72 74 20 6f 66 0a 2a 2a 20 61  any part of.** a
1bf20 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79   block of memory
1bf30 20 61 66 74 65 72 20 69 74 20 68 61 73 20 62 65   after it has be
1bf40 65 6e 20 72 65 6c 65 61 73 65 64 20 75 73 69 6e  en released usin
1bf50 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72  g.** [sqlite3_fr
1bf60 65 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  ee()] or [sqlite
1bf70 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f  3_realloc()]..*/
1bf80 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 6d  .void *sqlite3_m
1bf90 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76 6f 69 64  alloc(int);.void
1bfa0 20 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   *sqlite3_reallo
1bfb0 63 28 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76  c(void*, int);.v
1bfc0 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65  oid sqlite3_free
1bfd0 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  (void*);../*.** 
1bfe0 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79  CAPI3REF: Memory
1bff0 20 41 6c 6c 6f 63 61 74 6f 72 20 53 74 61 74 69   Allocator Stati
1c000 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  stics.**.** SQLi
1c010 74 65 20 70 72 6f 76 69 64 65 73 20 74 68 65 73  te provides thes
1c020 65 20 74 77 6f 20 69 6e 74 65 72 66 61 63 65 73  e two interfaces
1c030 20 66 6f 72 20 72 65 70 6f 72 74 69 6e 67 20 6f   for reporting o
1c040 6e 20 74 68 65 20 73 74 61 74 75 73 0a 2a 2a 20  n the status.** 
1c050 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
1c060 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c 69  malloc()], [sqli
1c070 74 65 33 5f 66 72 65 65 28 29 5d 2c 20 61 6e 64  te3_free()], and
1c080 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   [sqlite3_reallo
1c090 63 28 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65 73  c()].** routines
1c0a0 2c 20 77 68 69 63 68 20 66 6f 72 6d 20 74 68 65  , which form the
1c0b0 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79   built-in memory
1c0c0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73   allocation subs
1c0d0 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ystem..**.** ^Th
1c0e0 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  e [sqlite3_memor
1c0f0 79 5f 75 73 65 64 28 29 5d 20 72 6f 75 74 69 6e  y_used()] routin
1c100 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  e returns the nu
1c110 6d 62 65 72 20 6f 66 20 62 79 74 65 73 0a 2a 2a  mber of bytes.**
1c120 20 6f 66 20 6d 65 6d 6f 72 79 20 63 75 72 72 65   of memory curre
1c130 6e 74 6c 79 20 6f 75 74 73 74 61 6e 64 69 6e 67  ntly outstanding
1c140 20 28 6d 61 6c 6c 6f 63 65 64 20 62 75 74 20 6e   (malloced but n
1c150 6f 74 20 66 72 65 65 64 29 2e 0a 2a 2a 20 5e 54  ot freed)..** ^T
1c160 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  he [sqlite3_memo
1c170 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20  ry_highwater()] 
1c180 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
1c190 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 76  the maximum.** v
1c1a0 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74 65 33  alue of [sqlite3
1c1b0 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20  _memory_used()] 
1c1c0 73 69 6e 63 65 20 74 68 65 20 68 69 67 68 2d 77  since the high-w
1c1d0 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 77 61 73  ater mark.** was
1c1e0 20 6c 61 73 74 20 72 65 73 65 74 2e 20 20 5e 54   last reset.  ^T
1c1f0 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e  he values return
1c200 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d  ed by [sqlite3_m
1c210 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 61 6e  emory_used()] an
1c220 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65  d.** [sqlite3_me
1c230 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29  mory_highwater()
1c240 5d 20 69 6e 63 6c 75 64 65 20 61 6e 79 20 6f 76  ] include any ov
1c250 65 72 68 65 61 64 0a 2a 2a 20 61 64 64 65 64 20  erhead.** added 
1c260 62 79 20 53 51 4c 69 74 65 20 69 6e 20 69 74 73  by SQLite in its
1c270 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
1c280 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  of [sqlite3_mall
1c290 6f 63 28 29 5d 2c 0a 2a 2a 20 62 75 74 20 6e 6f  oc()],.** but no
1c2a0 74 20 6f 76 65 72 68 65 61 64 20 61 64 64 65 64  t overhead added
1c2b0 20 62 79 20 74 68 65 20 61 6e 79 20 75 6e 64 65   by the any unde
1c2c0 72 6c 79 69 6e 67 20 73 79 73 74 65 6d 20 6c 69  rlying system li
1c2d0 62 72 61 72 79 0a 2a 2a 20 72 6f 75 74 69 6e 65  brary.** routine
1c2e0 73 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f  s that [sqlite3_
1c2f0 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61 79 20 63 61  malloc()] may ca
1c300 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d  ll..**.** ^The m
1c310 65 6d 6f 72 79 20 68 69 67 68 2d 77 61 74 65 72  emory high-water
1c320 20 6d 61 72 6b 20 69 73 20 72 65 73 65 74 20 74   mark is reset t
1c330 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20 76 61  o the current va
1c340 6c 75 65 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69 74  lue of.** [sqlit
1c350 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29  e3_memory_used()
1c360 5d 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66  ] if and only if
1c370 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 74   the parameter t
1c380 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65  o.** [sqlite3_me
1c390 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29  mory_highwater()
1c3a0 5d 20 69 73 20 74 72 75 65 2e 20 20 5e 54 68 65  ] is true.  ^The
1c3b0 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a   value returned.
1c3c0 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d  ** by [sqlite3_m
1c3d0 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
1c3e0 31 29 5d 20 69 73 20 74 68 65 20 68 69 67 68 2d  1)] is the high-
1c3f0 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 70 72  water mark.** pr
1c400 69 6f 72 20 74 6f 20 74 68 65 20 72 65 73 65 74  ior to the reset
1c410 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74  ..*/.sqlite3_int
1c420 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  64 sqlite3_memor
1c430 79 5f 75 73 65 64 28 76 6f 69 64 29 3b 0a 73 71  y_used(void);.sq
1c440 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69  lite3_int64 sqli
1c450 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
1c460 61 74 65 72 28 69 6e 74 20 72 65 73 65 74 46 6c  ater(int resetFl
1c470 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ag);../*.** CAPI
1c480 33 52 45 46 3a 20 50 73 65 75 64 6f 2d 52 61 6e  3REF: Pseudo-Ran
1c490 64 6f 6d 20 4e 75 6d 62 65 72 20 47 65 6e 65 72  dom Number Gener
1c4a0 61 74 6f 72 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  ator.**.** SQLit
1c4b0 65 20 63 6f 6e 74 61 69 6e 73 20 61 20 68 69 67  e contains a hig
1c4c0 68 2d 71 75 61 6c 69 74 79 20 70 73 65 75 64 6f  h-quality pseudo
1c4d0 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62 65 72 20 67  -random number g
1c4e0 65 6e 65 72 61 74 6f 72 20 28 50 52 4e 47 29 20  enerator (PRNG) 
1c4f0 75 73 65 64 20 74 6f 0a 2a 2a 20 73 65 6c 65 63  used to.** selec
1c500 74 20 72 61 6e 64 6f 6d 20 5b 52 4f 57 49 44 20  t random [ROWID 
1c510 7c 20 52 4f 57 49 44 73 5d 20 77 68 65 6e 20 69  | ROWIDs] when i
1c520 6e 73 65 72 74 69 6e 67 20 6e 65 77 20 72 65 63  nserting new rec
1c530 6f 72 64 73 20 69 6e 74 6f 20 61 20 74 61 62 6c  ords into a tabl
1c540 65 20 74 68 61 74 0a 2a 2a 20 61 6c 72 65 61 64  e that.** alread
1c550 79 20 75 73 65 73 20 74 68 65 20 6c 61 72 67 65  y uses the large
1c560 73 74 20 70 6f 73 73 69 62 6c 65 20 5b 52 4f 57  st possible [ROW
1c570 49 44 5d 2e 20 20 54 68 65 20 50 52 4e 47 20 69  ID].  The PRNG i
1c580 73 20 61 6c 73 6f 20 75 73 65 64 20 66 6f 72 0a  s also used for.
1c590 2a 2a 20 74 68 65 20 62 75 69 6c 64 2d 69 6e 20  ** the build-in 
1c5a0 72 61 6e 64 6f 6d 28 29 20 61 6e 64 20 72 61 6e  random() and ran
1c5b0 64 6f 6d 62 6c 6f 62 28 29 20 53 51 4c 20 66 75  domblob() SQL fu
1c5c0 6e 63 74 69 6f 6e 73 2e 20 20 54 68 69 73 20 69  nctions.  This i
1c5d0 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 0a  nterface allows.
1c5e0 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  ** applications 
1c5f0 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 73 61  to access the sa
1c600 6d 65 20 50 52 4e 47 20 66 6f 72 20 6f 74 68 65  me PRNG for othe
1c610 72 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a  r purposes..**.*
1c620 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 74 68 69  * ^A call to thi
1c630 73 20 72 6f 75 74 69 6e 65 20 73 74 6f 72 65 73  s routine stores
1c640 20 4e 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64   N bytes of rand
1c650 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 62 75 66 66  omness into buff
1c660 65 72 20 50 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  er P..**.** ^The
1c670 20 66 69 72 73 74 20 74 69 6d 65 20 74 68 69 73   first time this
1c680 20 72 6f 75 74 69 6e 65 20 69 73 20 69 6e 76 6f   routine is invo
1c690 6b 65 64 20 28 65 69 74 68 65 72 20 69 6e 74 65  ked (either inte
1c6a0 72 6e 61 6c 6c 79 20 6f 72 20 62 79 0a 2a 2a 20  rnally or by.** 
1c6b0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 29  the application)
1c6c0 20 74 68 65 20 50 52 4e 47 20 69 73 20 73 65 65   the PRNG is see
1c6d0 64 65 64 20 75 73 69 6e 67 20 72 61 6e 64 6f 6d  ded using random
1c6e0 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 0a 2a 2a  ness obtained.**
1c6f0 20 66 72 6f 6d 20 74 68 65 20 78 52 61 6e 64 6f   from the xRando
1c700 6d 6e 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 20  mness method of 
1c710 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c  the default [sql
1c720 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
1c730 2e 0a 2a 2a 20 5e 4f 6e 20 61 6c 6c 20 73 75 62  ..** ^On all sub
1c740 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69  sequent invocati
1c750 6f 6e 73 2c 20 74 68 65 20 70 73 65 75 64 6f 2d  ons, the pseudo-
1c760 72 61 6e 64 6f 6d 6e 65 73 73 20 69 73 20 67 65  randomness is ge
1c770 6e 65 72 61 74 65 64 0a 2a 2a 20 69 6e 74 65 72  nerated.** inter
1c780 6e 61 6c 6c 79 20 61 6e 64 20 77 69 74 68 6f 75  nally and withou
1c790 74 20 72 65 63 6f 75 72 73 65 20 74 6f 20 74 68  t recourse to th
1c7a0 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  e [sqlite3_vfs] 
1c7b0 78 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d  xRandomness.** m
1c7c0 65 74 68 6f 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73  ethod..*/.void s
1c7d0 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 73  qlite3_randomnes
1c7e0 73 28 69 6e 74 20 4e 2c 20 76 6f 69 64 20 2a 50  s(int N, void *P
1c7f0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1c800 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65  EF: Compile-Time
1c810 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 43   Authorization C
1c820 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e  allbacks.**.** ^
1c830 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 67  This routine reg
1c840 69 73 74 65 72 73 20 61 6e 20 61 75 74 68 6f 72  isters an author
1c850 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 77 69  izer callback wi
1c860 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a  th a particular.
1c870 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
1c880 6e 65 63 74 69 6f 6e 5d 2c 20 73 75 70 70 6c 69  nection], suppli
1c890 65 64 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  ed in the first 
1c8a0 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68  argument..** ^Th
1c8b0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
1c8c0 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
1c8d0 20 61 73 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   as SQL statemen
1c8e0 74 73 20 61 72 65 20 62 65 69 6e 67 20 63 6f 6d  ts are being com
1c8f0 70 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c  piled.** by [sql
1c900 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
1c910 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 20  or its variants 
1c920 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1c930 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  _v2()],.** [sqli
1c940 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
1c950 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72   and [sqlite3_pr
1c960 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 20 20  epare16_v2()].  
1c970 5e 41 74 20 76 61 72 69 6f 75 73 0a 2a 2a 20 70  ^At various.** p
1c980 6f 69 6e 74 73 20 64 75 72 69 6e 67 20 74 68 65  oints during the
1c990 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 70 72 6f   compilation pro
1c9a0 63 65 73 73 2c 20 61 73 20 6c 6f 67 69 63 20 69  cess, as logic i
1c9b0 73 20 62 65 69 6e 67 20 63 72 65 61 74 65 64 0a  s being created.
1c9c0 2a 2a 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61  ** to perform va
1c9d0 72 69 6f 75 73 20 61 63 74 69 6f 6e 73 2c 20 74  rious actions, t
1c9e0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
1c9f0 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
1ca00 64 20 74 6f 0a 2a 2a 20 73 65 65 20 69 66 20 74  d to.** see if t
1ca10 68 6f 73 65 20 61 63 74 69 6f 6e 73 20 61 72 65  hose actions are
1ca20 20 61 6c 6c 6f 77 65 64 2e 20 20 5e 54 68 65 20   allowed.  ^The 
1ca30 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
1ca40 61 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65  ack should.** re
1ca50 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  turn [SQLITE_OK]
1ca60 20 74 6f 20 61 6c 6c 6f 77 20 74 68 65 20 61 63   to allow the ac
1ca70 74 69 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f 49 47  tion, [SQLITE_IG
1ca80 4e 4f 52 45 5d 20 74 6f 20 64 69 73 61 6c 6c 6f  NORE] to disallo
1ca90 77 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69  w the.** specifi
1caa0 63 20 61 63 74 69 6f 6e 20 62 75 74 20 61 6c 6c  c action but all
1cab0 6f 77 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  ow the SQL state
1cac0 6d 65 6e 74 20 74 6f 20 63 6f 6e 74 69 6e 75 65  ment to continue
1cad0 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c   to be.** compil
1cae0 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44  ed, or [SQLITE_D
1caf0 45 4e 59 5d 20 74 6f 20 63 61 75 73 65 20 74 68  ENY] to cause th
1cb00 65 20 65 6e 74 69 72 65 20 53 51 4c 20 73 74 61  e entire SQL sta
1cb10 74 65 6d 65 6e 74 20 74 6f 20 62 65 0a 2a 2a 20  tement to be.** 
1cb20 72 65 6a 65 63 74 65 64 20 77 69 74 68 20 61 6e  rejected with an
1cb30 20 65 72 72 6f 72 2e 20 20 5e 49 66 20 74 68 65   error.  ^If the
1cb40 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
1cb50 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20  back returns.** 
1cb60 61 6e 79 20 76 61 6c 75 65 20 6f 74 68 65 72 20  any value other 
1cb70 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 49 47 4e  than [SQLITE_IGN
1cb80 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b  ORE], [SQLITE_OK
1cb90 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45  ], or [SQLITE_DE
1cba0 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  NY].** then the 
1cbb0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1cbc0 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61  _v2()] or equiva
1cbd0 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74  lent call that t
1cbe0 72 69 67 67 65 72 65 64 0a 2a 2a 20 74 68 65 20  riggered.** the 
1cbf0 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20  authorizer will 
1cc00 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72  fail with an err
1cc10 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a  or message..**.*
1cc20 2a 20 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62  * When the callb
1cc30 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ack returns [SQL
1cc40 49 54 45 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d 65  ITE_OK], that me
1cc50 61 6e 73 20 74 68 65 20 6f 70 65 72 61 74 69 6f  ans the operatio
1cc60 6e 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20 69  n.** requested i
1cc70 73 20 6f 6b 2e 20 20 5e 57 68 65 6e 20 74 68 65  s ok.  ^When the
1cc80 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
1cc90 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c  s [SQLITE_DENY],
1cca0 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
1ccb0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
1ccc0 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c  r equivalent cal
1ccd0 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64  l that triggered
1cce0 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a   the.** authoriz
1ccf0 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74  er will fail wit
1cd00 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61  h an error messa
1cd10 67 65 20 65 78 70 6c 61 69 6e 69 6e 67 20 74 68  ge explaining th
1cd20 61 74 0a 2a 2a 20 61 63 63 65 73 73 20 69 73 20  at.** access is 
1cd30 64 65 6e 69 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 5e  denied. .**.** ^
1cd40 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
1cd50 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f  ter to the autho
1cd60 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
1cd70 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
1cd80 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74  third.** paramet
1cd90 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  er to the sqlite
1cda0 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
1cdb0 28 29 20 69 6e 74 65 72 66 61 63 65 2e 20 5e 54  () interface. ^T
1cdc0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
1cdd0 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61  ter.** to the ca
1cde0 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74  llback is an int
1cdf0 65 67 65 72 20 5b 53 51 4c 49 54 45 5f 43 4f 50  eger [SQLITE_COP
1ce00 59 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d  Y | action code]
1ce10 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73 0a   that specifies.
1ce20 2a 2a 20 74 68 65 20 70 61 72 74 69 63 75 6c 61  ** the particula
1ce30 72 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61  r action to be a
1ce40 75 74 68 6f 72 69 7a 65 64 2e 20 5e 54 68 65 20  uthorized. ^The 
1ce50 74 68 69 72 64 20 74 68 72 6f 75 67 68 20 73 69  third through si
1ce60 78 74 68 20 70 61 72 61 6d 65 74 65 72 73 0a 2a  xth parameters.*
1ce70 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63  * to the callbac
1ce80 6b 20 61 72 65 20 7a 65 72 6f 2d 74 65 72 6d 69  k are zero-termi
1ce90 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20 74 68  nated strings th
1cea0 61 74 20 63 6f 6e 74 61 69 6e 20 61 64 64 69 74  at contain addit
1ceb0 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74 61 69 6c 73  ional.** details
1cec0 20 61 62 6f 75 74 20 74 68 65 20 61 63 74 69 6f   about the actio
1ced0 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a  n to be authoriz
1cee0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  ed..**.** ^If th
1cef0 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73  e action code is
1cf00 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d 0a 2a   [SQLITE_READ].*
1cf10 2a 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61  * and the callba
1cf20 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  ck returns [SQLI
1cf30 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20  TE_IGNORE] then 
1cf40 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
1cf50 20 73 74 61 74 65 6d 65 6e 74 5d 20 73 74 61 74   statement] stat
1cf60 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73 74 72 75  ement is constru
1cf70 63 74 65 64 20 74 6f 20 73 75 62 73 74 69 74 75  cted to substitu
1cf80 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76 61 6c  te.** a NULL val
1cf90 75 65 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 74  ue in place of t
1cfa0 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20  he table column 
1cfb0 74 68 61 74 20 77 6f 75 6c 64 20 68 61 76 65 0a  that would have.
1cfc0 2a 2a 20 62 65 65 6e 20 72 65 61 64 20 69 66 20  ** been read if 
1cfd0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20  [SQLITE_OK] had 
1cfe0 62 65 65 6e 20 72 65 74 75 72 6e 65 64 2e 20 20  been returned.  
1cff0 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f  The [SQLITE_IGNO
1d000 52 45 5d 0a 2a 2a 20 72 65 74 75 72 6e 20 63 61  RE].** return ca
1d010 6e 20 62 65 20 75 73 65 64 20 74 6f 20 64 65 6e  n be used to den
1d020 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 75  y an untrusted u
1d030 73 65 72 20 61 63 63 65 73 73 20 74 6f 20 69 6e  ser access to in
1d040 64 69 76 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75  dividual.** colu
1d050 6d 6e 73 20 6f 66 20 61 20 74 61 62 6c 65 2e 0a  mns of a table..
1d060 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f  ** ^If the actio
1d070 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54  n code is [SQLIT
1d080 45 5f 44 45 4c 45 54 45 5d 20 61 6e 64 20 74 68  E_DELETE] and th
1d090 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  e callback retur
1d0a0 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 47  ns.** [SQLITE_IG
1d0b0 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 20 5b  NORE] then the [
1d0c0 44 45 4c 45 54 45 5d 20 6f 70 65 72 61 74 69 6f  DELETE] operatio
1d0d0 6e 20 70 72 6f 63 65 65 64 73 20 62 75 74 20 74  n proceeds but t
1d0e0 68 65 0a 2a 2a 20 5b 74 72 75 6e 63 61 74 65 20  he.** [truncate 
1d0f0 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 20 69 73  optimization] is
1d100 20 64 69 73 61 62 6c 65 64 20 61 6e 64 20 61 6c   disabled and al
1d110 6c 20 72 6f 77 73 20 61 72 65 20 64 65 6c 65 74  l rows are delet
1d120 65 64 20 69 6e 64 69 76 69 64 75 61 6c 6c 79 2e  ed individually.
1d130 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68 6f 72  .**.** An author
1d140 69 7a 65 72 20 69 73 20 75 73 65 64 20 77 68 65  izer is used whe
1d150 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  n [sqlite3_prepa
1d160 72 65 20 7c 20 70 72 65 70 61 72 69 6e 67 5d 0a  re | preparing].
1d170 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ** SQL statement
1d180 73 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72 75 73  s from an untrus
1d190 74 65 64 20 73 6f 75 72 63 65 2c 20 74 6f 20 65  ted source, to e
1d1a0 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20 53  nsure that the S
1d1b0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  QL statements.**
1d1c0 20 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f 20 61   do not try to a
1d1d0 63 63 65 73 73 20 64 61 74 61 20 74 68 65 79 20  ccess data they 
1d1e0 61 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65 64 20  are not allowed 
1d1f0 74 6f 20 73 65 65 2c 20 6f 72 20 74 68 61 74 20  to see, or that 
1d200 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 74  they do not.** t
1d210 72 79 20 74 6f 20 65 78 65 63 75 74 65 20 6d 61  ry to execute ma
1d220 6c 69 63 69 6f 75 73 20 73 74 61 74 65 6d 65 6e  licious statemen
1d230 74 73 20 74 68 61 74 20 64 61 6d 61 67 65 20 74  ts that damage t
1d240 68 65 20 64 61 74 61 62 61 73 65 2e 20 20 46 6f  he database.  Fo
1d250 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 61 6e  r.** example, an
1d260 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79   application may
1d270 20 61 6c 6c 6f 77 20 61 20 75 73 65 72 20 74 6f   allow a user to
1d280 20 65 6e 74 65 72 20 61 72 62 69 74 72 61 72 79   enter arbitrary
1d290 0a 2a 2a 20 53 51 4c 20 71 75 65 72 69 65 73 20  .** SQL queries 
1d2a0 66 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e 20 62  for evaluation b
1d2b0 79 20 61 20 64 61 74 61 62 61 73 65 2e 20 20 42  y a database.  B
1d2c0 75 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ut the applicati
1d2d0 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77  on does.** not w
1d2e0 61 6e 74 20 74 68 65 20 75 73 65 72 20 74 6f 20  ant the user to 
1d2f0 62 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b 65 20  be able to make 
1d300 61 72 62 69 74 72 61 72 79 20 63 68 61 6e 67 65  arbitrary change
1d310 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61  s to the.** data
1d320 62 61 73 65 2e 20 20 41 6e 20 61 75 74 68 6f 72  base.  An author
1d330 69 7a 65 72 20 63 6f 75 6c 64 20 74 68 65 6e 20  izer could then 
1d340 62 65 20 70 75 74 20 69 6e 20 70 6c 61 63 65 20  be put in place 
1d350 77 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75 73 65  while the.** use
1d360 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 20 69 73  r-entered SQL is
1d370 20 62 65 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   being [sqlite3_
1d380 70 72 65 70 61 72 65 20 7c 20 70 72 65 70 61 72  prepare | prepar
1d390 65 64 5d 20 74 68 61 74 0a 2a 2a 20 64 69 73 61  ed] that.** disa
1d3a0 6c 6c 6f 77 73 20 65 76 65 72 79 74 68 69 6e 67  llows everything
1d3b0 20 65 78 63 65 70 74 20 5b 53 45 4c 45 43 54 5d   except [SELECT]
1d3c0 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a   statements..**.
1d3d0 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20  ** Applications 
1d3e0 74 68 61 74 20 6e 65 65 64 20 74 6f 20 70 72 6f  that need to pro
1d3f0 63 65 73 73 20 53 51 4c 20 66 72 6f 6d 20 75 6e  cess SQL from un
1d400 74 72 75 73 74 65 64 20 73 6f 75 72 63 65 73 0a  trusted sources.
1d410 2a 2a 20 6d 69 67 68 74 20 61 6c 73 6f 20 63 6f  ** might also co
1d420 6e 73 69 64 65 72 20 6c 6f 77 65 72 69 6e 67 20  nsider lowering 
1d430 72 65 73 6f 75 72 63 65 20 6c 69 6d 69 74 73 20  resource limits 
1d440 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c  using [sqlite3_l
1d450 69 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c  imit()].** and l
1d460 69 6d 69 74 69 6e 67 20 64 61 74 61 62 61 73 65  imiting database
1d470 20 73 69 7a 65 20 75 73 69 6e 67 20 74 68 65 20   size using the 
1d480 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d  [max_page_count]
1d490 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20   [PRAGMA].** in 
1d4a0 61 64 64 69 74 69 6f 6e 20 74 6f 20 75 73 69 6e  addition to usin
1d4b0 67 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 2e  g an authorizer.
1d4c0 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 61 20  .**.** ^(Only a 
1d4d0 73 69 6e 67 6c 65 20 61 75 74 68 6f 72 69 7a 65  single authorize
1d4e0 72 20 63 61 6e 20 62 65 20 69 6e 20 70 6c 61 63  r can be in plac
1d4f0 65 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20  e on a database 
1d500 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 74  connection.** at
1d510 20 61 20 74 69 6d 65 2e 20 20 45 61 63 68 20 63   a time.  Each c
1d520 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  all to sqlite3_s
1d530 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 6f 76  et_authorizer ov
1d540 65 72 72 69 64 65 73 20 74 68 65 0a 2a 2a 20 70  errides the.** p
1d550 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e 29 5e 20  revious call.)^ 
1d560 20 5e 44 69 73 61 62 6c 65 20 74 68 65 20 61 75   ^Disable the au
1d570 74 68 6f 72 69 7a 65 72 20 62 79 20 69 6e 73 74  thorizer by inst
1d580 61 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c 20 63 61  alling a NULL ca
1d590 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 61  llback..** The a
1d5a0 75 74 68 6f 72 69 7a 65 72 20 69 73 20 64 69 73  uthorizer is dis
1d5b0 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74  abled by default
1d5c0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68  ..**.** The auth
1d5d0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
1d5e0 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74  must not do anyt
1d5f0 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d  hing that will m
1d600 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74  odify.** the dat
1d610 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1d620 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68   that invoked th
1d630 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
1d640 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74  lback..** Note t
1d650 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  hat [sqlite3_pre
1d660 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b  pare_v2()] and [
1d670 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
1d680 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69  both modify thei
1d690 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  r.** database co
1d6a0 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68  nnections for th
1d6b0 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f  e meaning of "mo
1d6c0 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 61  dify" in this pa
1d6d0 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e  ragraph..**.** ^
1d6e0 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72  When [sqlite3_pr
1d6f0 65 70 61 72 65 5f 76 32 28 29 5d 20 69 73 20 75  epare_v2()] is u
1d700 73 65 64 20 74 6f 20 70 72 65 70 61 72 65 20 61  sed to prepare a
1d710 20 73 74 61 74 65 6d 65 6e 74 2c 20 74 68 65 0a   statement, the.
1d720 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 6d 69 67  ** statement mig
1d730 68 74 20 62 65 20 72 65 2d 70 72 65 70 61 72 65  ht be re-prepare
1d740 64 20 64 75 72 69 6e 67 20 5b 73 71 6c 69 74 65  d during [sqlite
1d750 33 5f 73 74 65 70 28 29 5d 20 64 75 65 20 74 6f  3_step()] due to
1d760 20 61 20 0a 2a 2a 20 73 63 68 65 6d 61 20 63 68   a .** schema ch
1d770 61 6e 67 65 2e 20 20 48 65 6e 63 65 2c 20 74 68  ange.  Hence, th
1d780 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68  e application sh
1d790 6f 75 6c 64 20 65 6e 73 75 72 65 20 74 68 61 74  ould ensure that
1d7a0 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 63 74 20   the.** correct 
1d7b0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
1d7c0 61 63 6b 20 72 65 6d 61 69 6e 73 20 69 6e 20 70  ack remains in p
1d7d0 6c 61 63 65 20 64 75 72 69 6e 67 20 74 68 65 20  lace during the 
1d7e0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
1d7f0 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68  ..**.** ^Note th
1d800 61 74 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  at the authorize
1d810 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  r callback is in
1d820 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72 69 6e  voked only durin
1d830 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  g.** [sqlite3_pr
1d840 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20  epare()] or its 
1d850 76 61 72 69 61 6e 74 73 2e 20 20 41 75 74 68 6f  variants.  Autho
1d860 72 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f 74 0a  rization is not.
1d870 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 64 75 72  ** performed dur
1d880 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 65 76  ing statement ev
1d890 61 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73 71 6c  aluation in [sql
1d8a0 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 75 6e  ite3_step()], un
1d8b0 6c 65 73 73 0a 2a 2a 20 61 73 20 73 74 61 74 65  less.** as state
1d8c0 64 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75  d in the previou
1d8d0 73 20 70 61 72 61 67 72 61 70 68 2c 20 73 71 6c  s paragraph, sql
1d8e0 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e 76 6f  ite3_step() invo
1d8f0 6b 65 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70  kes.** sqlite3_p
1d900 72 65 70 61 72 65 5f 76 32 28 29 20 74 6f 20 72  repare_v2() to r
1d910 65 70 72 65 70 61 72 65 20 61 20 73 74 61 74 65  eprepare a state
1d920 6d 65 6e 74 20 61 66 74 65 72 20 61 20 73 63 68  ment after a sch
1d930 65 6d 61 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a 69  ema change..*/.i
1d940 6e 74 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  nt sqlite3_set_a
1d950 75 74 68 6f 72 69 7a 65 72 28 0a 20 20 73 71 6c  uthorizer(.  sql
1d960 69 74 65 33 2a 2c 0a 20 20 69 6e 74 20 28 2a 78  ite3*,.  int (*x
1d970 41 75 74 68 29 28 76 6f 69 64 2a 2c 69 6e 74 2c  Auth)(void*,int,
1d980 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73  const char*,cons
1d990 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68  t char*,const ch
1d9a0 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29  ar*,const char*)
1d9b0 2c 0a 20 20 76 6f 69 64 20 2a 70 55 73 65 72 44  ,.  void *pUserD
1d9c0 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ata.);../*.** CA
1d9d0 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a  PI3REF: Authoriz
1d9e0 65 72 20 52 65 74 75 72 6e 20 43 6f 64 65 73 0a  er Return Codes.
1d9f0 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74  **.** The [sqlit
1da00 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
1da10 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63  r | authorizer c
1da20 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
1da30 5d 20 6d 75 73 74 0a 2a 2a 20 72 65 74 75 72 6e  ] must.** return
1da40 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f   either [SQLITE_
1da50 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68  OK] or one of th
1da60 65 73 65 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74  ese two constant
1da70 73 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 6f  s in order.** to
1da80 20 73 69 67 6e 61 6c 20 53 51 4c 69 74 65 20 77   signal SQLite w
1da90 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68  hether or not th
1daa0 65 20 61 63 74 69 6f 6e 20 69 73 20 70 65 72 6d  e action is perm
1dab0 69 74 74 65 64 2e 20 20 53 65 65 20 74 68 65 0a  itted.  See the.
1dac0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  ** [sqlite3_set_
1dad0 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74  authorizer | aut
1dae0 68 6f 72 69 7a 65 72 20 64 6f 63 75 6d 65 6e 74  horizer document
1daf0 61 74 69 6f 6e 5d 20 66 6f 72 20 61 64 64 69 74  ation] for addit
1db00 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61  ional.** informa
1db10 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65  tion..**.** Note
1db20 20 74 68 61 74 20 53 51 4c 49 54 45 5f 49 47 4e   that SQLITE_IGN
1db30 4f 52 45 20 69 73 20 61 6c 73 6f 20 75 73 65 64  ORE is also used
1db40 20 61 73 20 61 20 5b 53 51 4c 49 54 45 5f 52 4f   as a [SQLITE_RO
1db50 4c 4c 42 41 43 4b 20 7c 20 72 65 74 75 72 6e 20  LLBACK | return 
1db60 63 6f 64 65 5d 0a 2a 2a 20 66 72 6f 6d 20 74 68  code].** from th
1db70 65 20 5b 73 71 6c 69 74 65 33 5f 76 74 61 62 5f  e [sqlite3_vtab_
1db80 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28 29 5d 20 69  on_conflict()] i
1db90 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 23 64 65  nterface..*/.#de
1dba0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4e 59  fine SQLITE_DENY
1dbb0 20 20 20 31 20 20 20 2f 2a 20 41 62 6f 72 74 20     1   /* Abort 
1dbc0 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
1dbd0 74 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20  t with an error 
1dbe0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1dbf0 45 5f 49 47 4e 4f 52 45 20 32 20 20 20 2f 2a 20  E_IGNORE 2   /* 
1dc00 44 6f 6e 27 74 20 61 6c 6c 6f 77 20 61 63 63 65  Don't allow acce
1dc10 73 73 2c 20 62 75 74 20 64 6f 6e 27 74 20 67 65  ss, but don't ge
1dc20 6e 65 72 61 74 65 20 61 6e 20 65 72 72 6f 72 20  nerate an error 
1dc30 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
1dc40 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 41  EF: Authorizer A
1dc50 63 74 69 6f 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a  ction Codes.**.*
1dc60 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  * The [sqlite3_s
1dc70 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d  et_authorizer()]
1dc80 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73   interface regis
1dc90 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 20  ters a callback 
1dca0 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68 61 74  function.** that
1dcb0 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 20 61   is invoked to a
1dcc0 75 74 68 6f 72 69 7a 65 20 63 65 72 74 61 69 6e  uthorize certain
1dcd0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61   SQL statement a
1dce0 63 74 69 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a 20  ctions.  The.** 
1dcf0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
1dd00 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
1dd10 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 63   is an integer c
1dd20 6f 64 65 20 74 68 61 74 20 73 70 65 63 69 66 69  ode that specifi
1dd30 65 73 0a 2a 2a 20 77 68 61 74 20 61 63 74 69 6f  es.** what actio
1dd40 6e 20 69 73 20 62 65 69 6e 67 20 61 75 74 68 6f  n is being autho
1dd50 72 69 7a 65 64 2e 20 20 54 68 65 73 65 20 61 72  rized.  These ar
1dd60 65 20 74 68 65 20 69 6e 74 65 67 65 72 20 61 63  e the integer ac
1dd70 74 69 6f 6e 20 63 6f 64 65 73 20 74 68 61 74 0a  tion codes that.
1dd80 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  ** the authorize
1dd90 72 20 63 61 6c 6c 62 61 63 6b 20 6d 61 79 20 62  r callback may b
1dda0 65 20 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a 20  e passed..**.** 
1ddb0 54 68 65 73 65 20 61 63 74 69 6f 6e 20 63 6f 64  These action cod
1ddc0 65 20 76 61 6c 75 65 73 20 73 69 67 6e 69 66 79  e values signify
1ddd0 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 6f 70   what kind of op
1dde0 65 72 61 74 69 6f 6e 20 69 73 20 74 6f 20 62 65  eration is to be
1ddf0 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 64 2e 20  .** authorized. 
1de00 20 54 68 65 20 33 72 64 20 61 6e 64 20 34 74 68   The 3rd and 4th
1de10 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74   parameters to t
1de20 68 65 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e  he authorization
1de30 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  .** callback fun
1de40 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20 70 61  ction will be pa
1de50 72 61 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c 4c  rameters or NULL
1de60 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68   depending on wh
1de70 69 63 68 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20  ich of these.** 
1de80 63 6f 64 65 73 20 69 73 20 75 73 65 64 20 61 73  codes is used as
1de90 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
1dea0 6d 65 74 65 72 2e 20 20 5e 28 54 68 65 20 35 74  meter.  ^(The 5t
1deb0 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
1dec0 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72  he.** authorizer
1ded0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65   callback is the
1dee0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74   name of the dat
1def0 61 62 61 73 65 20 28 22 6d 61 69 6e 22 2c 20 22  abase ("main", "
1df00 74 65 6d 70 22 2c 0a 2a 2a 20 65 74 63 2e 29 20  temp",.** etc.) 
1df10 69 66 20 61 70 70 6c 69 63 61 62 6c 65 2e 29 5e  if applicable.)^
1df20 20 20 5e 54 68 65 20 36 74 68 20 70 61 72 61 6d    ^The 6th param
1df30 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68  eter to the auth
1df40 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 0a  orizer callback.
1df50 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  ** is the name o
1df60 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f 73 74  f the inner-most
1df70 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 65 77   trigger or view
1df80 20 74 68 61 74 20 69 73 20 72 65 73 70 6f 6e 73   that is respons
1df90 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20  ible for.** the 
1dfa0 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 6f  access attempt o
1dfb0 72 20 4e 55 4c 4c 20 69 66 20 74 68 69 73 20 61  r NULL if this a
1dfc0 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 69 73  ccess attempt is
1dfd0 20 64 69 72 65 63 74 6c 79 20 66 72 6f 6d 0a 2a   directly from.*
1dfe0 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51 4c 20  * top-level SQL 
1dff0 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a  code..*/./******
1e000 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1e010 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1e020 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a  ***** 3rd ******
1e030 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a  ****** 4th *****
1e040 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65 20  ******/.#define 
1e050 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 49 4e  SQLITE_CREATE_IN
1e060 44 45 58 20 20 20 20 20 20 20 20 20 20 31 20 20  DEX          1  
1e070 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20   /* Index Name  
1e080 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
1e090 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1e0a0 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 41 42  QLITE_CREATE_TAB
1e0b0 4c 45 20 20 20 20 20 20 20 20 20 20 32 20 20 20  LE          2   
1e0c0 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
1e0d0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1e0e0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1e0f0 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50  LITE_CREATE_TEMP
1e100 5f 49 4e 44 45 58 20 20 20 20 20 33 20 20 20 2f  _INDEX     3   /
1e110 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20  * Index Name    
1e120 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
1e130 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1e140 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f  ITE_CREATE_TEMP_
1e150 54 41 42 4c 45 20 20 20 20 20 34 20 20 20 2f 2a  TABLE     4   /*
1e160 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1e170 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1e180 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1e190 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54  TE_CREATE_TEMP_T
1e1a0 52 49 47 47 45 52 20 20 20 35 20 20 20 2f 2a 20  RIGGER   5   /* 
1e1b0 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20  Trigger Name    
1e1c0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1e1d0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1e1e0 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 56 49  E_CREATE_TEMP_VI
1e1f0 45 57 20 20 20 20 20 20 36 20 20 20 2f 2a 20 56  EW      6   /* V
1e200 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e  iew Name       N
1e210 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1e220 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1e230 5f 43 52 45 41 54 45 5f 54 52 49 47 47 45 52 20  _CREATE_TRIGGER 
1e240 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 54 72         7   /* Tr
1e250 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61  igger Name    Ta
1e260 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
1e270 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1e280 43 52 45 41 54 45 5f 56 49 45 57 20 20 20 20 20  CREATE_VIEW     
1e290 20 20 20 20 20 20 38 20 20 20 2f 2a 20 56 69 65        8   /* Vie
1e2a0 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c  w Name       NUL
1e2b0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
1e2c0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1e2d0 45 4c 45 54 45 20 20 20 20 20 20 20 20 20 20 20  ELETE           
1e2e0 20 20 20 20 20 39 20 20 20 2f 2a 20 54 61 62 6c       9   /* Tabl
1e2f0 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
1e300 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1e310 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
1e320 4f 50 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20  OP_INDEX        
1e330 20 20 20 31 30 20 20 20 2f 2a 20 49 6e 64 65 78     10   /* Index
1e340 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65   Name      Table
1e350 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
1e360 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
1e370 50 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20  P_TABLE         
1e380 20 20 31 31 20 20 20 2f 2a 20 54 61 62 6c 65 20    11   /* Table 
1e390 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
1e3a0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
1e3b0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
1e3c0 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20  _TEMP_INDEX     
1e3d0 20 31 32 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e   12   /* Index N
1e3e0 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e  ame      Table N
1e3f0 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
1e400 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
1e410 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 20  TEMP_TABLE      
1e420 31 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  13   /* Table Na
1e430 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
1e440 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
1e450 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
1e460 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 20 31  EMP_TRIGGER    1
1e470 34 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e  4   /* Trigger N
1e480 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  ame    Table Nam
1e490 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
1e4a0 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45  e SQLITE_DROP_TE
1e4b0 4d 50 5f 56 49 45 57 20 20 20 20 20 20 20 31 35  MP_VIEW       15
1e4c0 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20     /* View Name 
1e4d0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1e4e0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1e4f0 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 52 49   SQLITE_DROP_TRI
1e500 47 47 45 52 20 20 20 20 20 20 20 20 20 31 36 20  GGER         16 
1e510 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d    /* Trigger Nam
1e520 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20  e    Table Name 
1e530 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1e540 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 49 45 57  SQLITE_DROP_VIEW
1e550 20 20 20 20 20 20 20 20 20 20 20 20 31 37 20 20              17  
1e560 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20   /* View Name   
1e570 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
1e580 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1e590 51 4c 49 54 45 5f 49 4e 53 45 52 54 20 20 20 20  QLITE_INSERT    
1e5a0 20 20 20 20 20 20 20 20 20 20 20 31 38 20 20 20             18   
1e5b0 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
1e5c0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1e5d0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1e5e0 4c 49 54 45 5f 50 52 41 47 4d 41 20 20 20 20 20  LITE_PRAGMA     
1e5f0 20 20 20 20 20 20 20 20 20 20 31 39 20 20 20 2f            19   /
1e600 2a 20 50 72 61 67 6d 61 20 4e 61 6d 65 20 20 20  * Pragma Name   
1e610 20 20 31 73 74 20 61 72 67 20 6f 72 20 4e 55 4c    1st arg or NUL
1e620 4c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  L */.#define SQL
1e630 49 54 45 5f 52 45 41 44 20 20 20 20 20 20 20 20  ITE_READ        
1e640 20 20 20 20 20 20 20 20 20 32 30 20 20 20 2f 2a           20   /*
1e650 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1e660 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20   Column Name    
1e670 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1e680 54 45 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20  TE_SELECT       
1e690 20 20 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20          21   /* 
1e6a0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1e6b0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1e6c0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1e6d0 45 5f 54 52 41 4e 53 41 43 54 49 4f 4e 20 20 20  E_TRANSACTION   
1e6e0 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20 4f         22   /* O
1e6f0 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20 4e  peration       N
1e700 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1e710 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1e720 5f 55 50 44 41 54 45 20 20 20 20 20 20 20 20 20  _UPDATE         
1e730 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20 54 61        23   /* Ta
1e740 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f  ble Name      Co
1e750 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f  lumn Name     */
1e760 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1e770 41 54 54 41 43 48 20 20 20 20 20 20 20 20 20 20  ATTACH          
1e780 20 20 20 20 20 32 34 20 20 20 2f 2a 20 46 69 6c       24   /* Fil
1e790 65 6e 61 6d 65 20 20 20 20 20 20 20 20 4e 55 4c  ename        NUL
1e7a0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
1e7b0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1e7c0 45 54 41 43 48 20 20 20 20 20 20 20 20 20 20 20  ETACH           
1e7d0 20 20 20 20 32 35 20 20 20 2f 2a 20 44 61 74 61      25   /* Data
1e7e0 62 61 73 65 20 4e 61 6d 65 20 20 20 4e 55 4c 4c  base Name   NULL
1e7f0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1e800 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4c  define SQLITE_AL
1e810 54 45 52 5f 54 41 42 4c 45 20 20 20 20 20 20 20  TER_TABLE       
1e820 20 20 20 32 36 20 20 20 2f 2a 20 44 61 74 61 62     26   /* Datab
1e830 61 73 65 20 4e 61 6d 65 20 20 20 54 61 62 6c 65  ase Name   Table
1e840 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
1e850 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 49  efine SQLITE_REI
1e860 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 20 20  NDEX            
1e870 20 20 32 37 20 20 20 2f 2a 20 49 6e 64 65 78 20    27   /* Index 
1e880 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
1e890 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
1e8a0 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 41 4c  fine SQLITE_ANAL
1e8b0 59 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 20  YZE             
1e8c0 20 32 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   28   /* Table N
1e8d0 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
1e8e0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1e8f0 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
1e900 45 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 20  E_VTABLE        
1e910 32 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  29   /* Table Na
1e920 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e  me      Module N
1e930 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  ame     */.#defi
1e940 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56  ne SQLITE_DROP_V
1e950 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 33  TABLE          3
1e960 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  0   /* Table Nam
1e970 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61  e      Module Na
1e980 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  me     */.#defin
1e990 65 20 53 51 4c 49 54 45 5f 46 55 4e 43 54 49 4f  e SQLITE_FUNCTIO
1e9a0 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 33 31  N             31
1e9b0 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20     /* NULL      
1e9c0 20 20 20 20 20 20 46 75 6e 63 74 69 6f 6e 20 4e        Function N
1e9d0 61 6d 65 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65  ame   */.#define
1e9e0 20 53 51 4c 49 54 45 5f 53 41 56 45 50 4f 49 4e   SQLITE_SAVEPOIN
1e9f0 54 20 20 20 20 20 20 20 20 20 20 20 20 33 32 20  T            32 
1ea00 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20    /* Operation  
1ea10 20 20 20 20 20 53 61 76 65 70 6f 69 6e 74 20 4e       Savepoint N
1ea20 61 6d 65 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ame  */.#define 
1ea30 53 51 4c 49 54 45 5f 43 4f 50 59 20 20 20 20 20  SQLITE_COPY     
1ea40 20 20 20 20 20 20 20 20 20 20 20 20 20 30 20 20               0  
1ea50 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 73   /* No longer us
1ea60 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ed */../*.** CAP
1ea70 49 33 52 45 46 3a 20 54 72 61 63 69 6e 67 20 41  I3REF: Tracing A
1ea80 6e 64 20 50 72 6f 66 69 6c 69 6e 67 20 46 75 6e  nd Profiling Fun
1ea90 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65  ctions.**.** The
1eaa0 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 67 69  se routines regi
1eab0 73 74 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75  ster callback fu
1eac0 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 63 61 6e  nctions that can
1ead0 20 62 65 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20   be used for.** 
1eae0 74 72 61 63 69 6e 67 20 61 6e 64 20 70 72 6f 66  tracing and prof
1eaf0 69 6c 69 6e 67 20 74 68 65 20 65 78 65 63 75 74  iling the execut
1eb00 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61 74 65  ion of SQL state
1eb10 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ments..**.** ^Th
1eb20 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  e callback funct
1eb30 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62  ion registered b
1eb40 79 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28  y sqlite3_trace(
1eb50 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 74 0a  ) is invoked at.
1eb60 2a 2a 20 76 61 72 69 6f 75 73 20 74 69 6d 65 73  ** various times
1eb70 20 77 68 65 6e 20 61 6e 20 53 51 4c 20 73 74 61   when an SQL sta
1eb80 74 65 6d 65 6e 74 20 69 73 20 62 65 69 6e 67 20  tement is being 
1eb90 72 75 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  run by [sqlite3_
1eba0 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65  step()]..** ^The
1ebb0 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29   sqlite3_trace()
1ebc0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
1ebd0 6f 6b 65 64 20 77 69 74 68 20 61 20 55 54 46 2d  oked with a UTF-
1ebe0 38 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74  8 rendering of t
1ebf0 68 65 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d  he.** SQL statem
1ec00 65 6e 74 20 74 65 78 74 20 61 73 20 74 68 65 20  ent text as the 
1ec10 73 74 61 74 65 6d 65 6e 74 20 66 69 72 73 74 20  statement first 
1ec20 62 65 67 69 6e 73 20 65 78 65 63 75 74 69 6e 67  begins executing
1ec30 2e 0a 2a 2a 20 5e 28 41 64 64 69 74 69 6f 6e 61  ..** ^(Additiona
1ec40 6c 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28  l sqlite3_trace(
1ec50 29 20 63 61 6c 6c 62 61 63 6b 73 20 6d 69 67 68  ) callbacks migh
1ec60 74 20 6f 63 63 75 72 0a 2a 2a 20 61 73 20 65 61  t occur.** as ea
1ec70 63 68 20 74 72 69 67 67 65 72 65 64 20 73 75 62  ch triggered sub
1ec80 70 72 6f 67 72 61 6d 20 69 73 20 65 6e 74 65 72  program is enter
1ec90 65 64 2e 20 20 54 68 65 20 63 61 6c 6c 62 61 63  ed.  The callbac
1eca0 6b 73 20 66 6f 72 20 74 72 69 67 67 65 72 73 0a  ks for triggers.
1ecb0 2a 2a 20 63 6f 6e 74 61 69 6e 20 61 20 55 54 46  ** contain a UTF
1ecc0 2d 38 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 74  -8 SQL comment t
1ecd0 68 61 74 20 69 64 65 6e 74 69 66 69 65 73 20 74  hat identifies t
1ece0 68 65 20 74 72 69 67 67 65 72 2e 29 5e 0a 2a 2a  he trigger.)^.**
1ecf0 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
1ed00 54 52 41 43 45 5f 53 49 5a 45 5f 4c 49 4d 49 54  TRACE_SIZE_LIMIT
1ed10 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
1ed20 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65  ption can be use
1ed30 64 20 74 6f 20 6c 69 6d 69 74 0a 2a 2a 20 74 68  d to limit.** th
1ed40 65 20 6c 65 6e 67 74 68 20 6f 66 20 5b 62 6f 75  e length of [bou
1ed50 6e 64 20 70 61 72 61 6d 65 74 65 72 5d 20 65 78  nd parameter] ex
1ed60 70 61 6e 73 69 6f 6e 20 69 6e 20 74 68 65 20 6f  pansion in the o
1ed70 75 74 70 75 74 20 6f 66 20 73 71 6c 69 74 65 33  utput of sqlite3
1ed80 5f 74 72 61 63 65 28 29 2e 0a 2a 2a 0a 2a 2a 20  _trace()..**.** 
1ed90 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75  ^The callback fu
1eda0 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65  nction registere
1edb0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 70 72 6f  d by sqlite3_pro
1edc0 66 69 6c 65 28 29 20 69 73 20 69 6e 76 6f 6b 65  file() is invoke
1edd0 64 0a 2a 2a 20 61 73 20 65 61 63 68 20 53 51 4c  d.** as each SQL
1ede0 20 73 74 61 74 65 6d 65 6e 74 20 66 69 6e 69 73   statement finis
1edf0 68 65 73 2e 20 20 5e 54 68 65 20 70 72 6f 66 69  hes.  ^The profi
1ee00 6c 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74  le callback cont
1ee10 61 69 6e 73 0a 2a 2a 20 74 68 65 20 6f 72 69 67  ains.** the orig
1ee20 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 20 74  inal statement t
1ee30 65 78 74 20 61 6e 64 20 61 6e 20 65 73 74 69 6d  ext and an estim
1ee40 61 74 65 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63  ate of wall-cloc
1ee50 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77  k time.** of how
1ee60 20 6c 6f 6e 67 20 74 68 61 74 20 73 74 61 74 65   long that state
1ee70 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 72 75 6e  ment took to run
1ee80 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 20  .  ^The profile 
1ee90 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 69 6d 65  callback.** time
1eea0 20 69 73 20 69 6e 20 75 6e 69 74 73 20 6f 66 20   is in units of 
1eeb0 6e 61 6e 6f 73 65 63 6f 6e 64 73 2c 20 68 6f 77  nanoseconds, how
1eec0 65 76 65 72 20 74 68 65 20 63 75 72 72 65 6e 74  ever the current
1eed0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a   implementation.
1eee0 2a 2a 20 69 73 20 6f 6e 6c 79 20 63 61 70 61 62  ** is only capab
1eef0 6c 65 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e  le of millisecon
1ef00 64 20 72 65 73 6f 6c 75 74 69 6f 6e 20 73 6f 20  d resolution so 
1ef10 74 68 65 20 73 69 78 20 6c 65 61 73 74 20 73 69  the six least si
1ef20 67 6e 69 66 69 63 61 6e 74 0a 2a 2a 20 64 69 67  gnificant.** dig
1ef30 69 74 73 20 69 6e 20 74 68 65 20 74 69 6d 65 20  its in the time 
1ef40 61 72 65 20 6d 65 61 6e 69 6e 67 6c 65 73 73 2e  are meaningless.
1ef50 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e    Future version
1ef60 73 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 6d  s of SQLite.** m
1ef70 69 67 68 74 20 70 72 6f 76 69 64 65 20 67 72 65  ight provide gre
1ef80 61 74 65 72 20 72 65 73 6f 6c 75 74 69 6f 6e 20  ater resolution 
1ef90 6f 6e 20 74 68 65 20 70 72 6f 66 69 6c 65 72 20  on the profiler 
1efa0 63 61 6c 6c 62 61 63 6b 2e 20 20 54 68 65 0a 2a  callback.  The.*
1efb0 2a 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c  * sqlite3_profil
1efc0 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  e() function is 
1efd0 63 6f 6e 73 69 64 65 72 65 64 20 65 78 70 65 72  considered exper
1efe0 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73 0a 2a  imental and is.*
1eff0 2a 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61  * subject to cha
1f000 6e 67 65 20 69 6e 20 66 75 74 75 72 65 20 76 65  nge in future ve
1f010 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
1f020 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74  ..*/.void *sqlit
1f030 65 33 5f 74 72 61 63 65 28 73 71 6c 69 74 65 33  e3_trace(sqlite3
1f040 2a 2c 20 76 6f 69 64 28 2a 78 54 72 61 63 65 29  *, void(*xTrace)
1f050 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61  (void*,const cha
1f060 72 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 53 51 4c  r*), void*);.SQL
1f070 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c  ITE_EXPERIMENTAL
1f080 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 70   void *sqlite3_p
1f090 72 6f 66 69 6c 65 28 73 71 6c 69 74 65 33 2a 2c  rofile(sqlite3*,
1f0a0 0a 20 20 20 76 6f 69 64 28 2a 78 50 72 6f 66 69  .   void(*xProfi
1f0b0 6c 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20  le)(void*,const 
1f0c0 63 68 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69  char*,sqlite3_ui
1f0d0 6e 74 36 34 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a  nt64), void*);..
1f0e0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1f0f0 51 75 65 72 79 20 50 72 6f 67 72 65 73 73 20 43  Query Progress C
1f100 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e  allbacks.**.** ^
1f110 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 6f 67  The sqlite3_prog
1f120 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 44 2c 4e  ress_handler(D,N
1f130 2c 58 2c 50 29 20 69 6e 74 65 72 66 61 63 65 20  ,X,P) interface 
1f140 63 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c 62  causes the callb
1f150 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ack.** function 
1f160 58 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20  X to be invoked 
1f170 70 65 72 69 6f 64 69 63 61 6c 6c 79 20 64 75 72  periodically dur
1f180 69 6e 67 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e 67  ing long running
1f190 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71   calls to.** [sq
1f1a0 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 5b  lite3_exec()], [
1f1b0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
1f1c0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 67 65 74  and [sqlite3_get
1f1d0 5f 74 61 62 6c 65 28 29 5d 20 66 6f 72 0a 2a 2a  _table()] for.**
1f1e0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1f1f0 74 69 6f 6e 20 44 2e 20 20 41 6e 20 65 78 61 6d  tion D.  An exam
1f200 70 6c 65 20 75 73 65 20 66 6f 72 20 74 68 69 73  ple use for this
1f210 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73  .** interface is
1f220 20 74 6f 20 6b 65 65 70 20 61 20 47 55 49 20 75   to keep a GUI u
1f230 70 64 61 74 65 64 20 64 75 72 69 6e 67 20 61 20  pdated during a 
1f240 6c 61 72 67 65 20 71 75 65 72 79 2e 0a 2a 2a 0a  large query..**.
1f250 2a 2a 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65  ** ^The paramete
1f260 72 20 50 20 69 73 20 70 61 73 73 65 64 20 74 68  r P is passed th
1f270 72 6f 75 67 68 20 61 73 20 74 68 65 20 6f 6e 6c  rough as the onl
1f280 79 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  y parameter to t
1f290 68 65 20 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20  he .** callback 
1f2a0 66 75 6e 63 74 69 6f 6e 20 58 2e 20 20 5e 54 68  function X.  ^Th
1f2b0 65 20 70 61 72 61 6d 65 74 65 72 20 4e 20 69 73  e parameter N is
1f2c0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 0a   the number of .
1f2d0 2a 2a 20 5b 76 69 72 74 75 61 6c 20 6d 61 63 68  ** [virtual mach
1f2e0 69 6e 65 20 69 6e 73 74 72 75 63 74 69 6f 6e 73  ine instructions
1f2f0 5d 20 74 68 61 74 20 61 72 65 20 65 76 61 6c 75  ] that are evalu
1f300 61 74 65 64 20 62 65 74 77 65 65 6e 20 73 75 63  ated between suc
1f310 63 65 73 73 69 76 65 0a 2a 2a 20 69 6e 76 6f 63  cessive.** invoc
1f320 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 63 61  ations of the ca
1f330 6c 6c 62 61 63 6b 20 58 2e 0a 2a 2a 0a 2a 2a 20  llback X..**.** 
1f340 5e 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 70  ^Only a single p
1f350 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20  rogress handler 
1f360 6d 61 79 20 62 65 20 64 65 66 69 6e 65 64 20 61  may be defined a
1f370 74 20 6f 6e 65 20 74 69 6d 65 20 70 65 72 0a 2a  t one time per.*
1f380 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
1f390 65 63 74 69 6f 6e 5d 3b 20 73 65 74 74 69 6e 67  ection]; setting
1f3a0 20 61 20 6e 65 77 20 70 72 6f 67 72 65 73 73 20   a new progress 
1f3b0 68 61 6e 64 6c 65 72 20 63 61 6e 63 65 6c 73 20  handler cancels 
1f3c0 74 68 65 0a 2a 2a 20 6f 6c 64 20 6f 6e 65 2e 20  the.** old one. 
1f3d0 20 5e 53 65 74 74 69 6e 67 20 70 61 72 61 6d 65   ^Setting parame
1f3e0 74 65 72 20 58 20 74 6f 20 4e 55 4c 4c 20 64 69  ter X to NULL di
1f3f0 73 61 62 6c 65 73 20 74 68 65 20 70 72 6f 67 72  sables the progr
1f400 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20  ess handler..** 
1f410 5e 54 68 65 20 70 72 6f 67 72 65 73 73 20 68 61  ^The progress ha
1f420 6e 64 6c 65 72 20 69 73 20 61 6c 73 6f 20 64 69  ndler is also di
1f430 73 61 62 6c 65 64 20 62 79 20 73 65 74 74 69 6e  sabled by settin
1f440 67 20 4e 20 74 6f 20 61 20 76 61 6c 75 65 20 6c  g N to a value l
1f450 65 73 73 0a 2a 2a 20 74 68 61 6e 20 31 2e 0a 2a  ess.** than 1..*
1f460 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 70 72 6f  *.** ^If the pro
1f470 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 72  gress callback r
1f480 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c  eturns non-zero,
1f490 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 69   the operation i
1f4a0 73 0a 2a 2a 20 69 6e 74 65 72 72 75 70 74 65 64  s.** interrupted
1f4b0 2e 20 20 54 68 69 73 20 66 65 61 74 75 72 65 20  .  This feature 
1f4c0 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 69  can be used to i
1f4d0 6d 70 6c 65 6d 65 6e 74 20 61 0a 2a 2a 20 22 43  mplement a.** "C
1f4e0 61 6e 63 65 6c 22 20 62 75 74 74 6f 6e 20 6f 6e  ancel" button on
1f4f0 20 61 20 47 55 49 20 70 72 6f 67 72 65 73 73 20   a GUI progress 
1f500 64 69 61 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a  dialog box..**.*
1f510 2a 20 54 68 65 20 70 72 6f 67 72 65 73 73 20 68  * The progress h
1f520 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20  andler callback 
1f530 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74  must not do anyt
1f540 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d  hing that will m
1f550 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74  odify.** the dat
1f560 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1f570 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68   that invoked th
1f580 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c  e progress handl
1f590 65 72 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  er..** Note that
1f5a0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1f5b0 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c  e_v2()] and [sql
1f5c0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74  ite3_step()] bot
1f5d0 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a  h modify their.*
1f5e0 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
1f5f0 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d  ctions for the m
1f600 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66  eaning of "modif
1f610 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 67  y" in this parag
1f620 72 61 70 68 2e 0a 2a 2a 0a 2a 2f 0a 76 6f 69 64  raph..**.*/.void
1f630 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73   sqlite3_progres
1f640 73 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65  s_handler(sqlite
1f650 33 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28  3*, int, int(*)(
1f660 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a  void*), void*);.
1f670 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1f680 20 4f 70 65 6e 69 6e 67 20 41 20 4e 65 77 20 44   Opening A New D
1f690 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69  atabase Connecti
1f6a0 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  on.**.** ^These 
1f6b0 72 6f 75 74 69 6e 65 73 20 6f 70 65 6e 20 61 6e  routines open an
1f6c0 20 53 51 4c 69 74 65 20 64 61 74 61 62 61 73 65   SQLite database
1f6d0 20 66 69 6c 65 20 61 73 20 73 70 65 63 69 66 69   file as specifi
1f6e0 65 64 20 62 79 20 74 68 65 20 0a 2a 2a 20 66 69  ed by the .** fi
1f6f0 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 2e  lename argument.
1f700 20 5e 54 68 65 20 66 69 6c 65 6e 61 6d 65 20 61   ^The filename a
1f710 72 67 75 6d 65 6e 74 20 69 73 20 69 6e 74 65 72  rgument is inter
1f720 70 72 65 74 65 64 20 61 73 20 55 54 46 2d 38 20  preted as UTF-8 
1f730 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  for.** sqlite3_o
1f740 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65  pen() and sqlite
1f750 33 5f 6f 70 65 6e 5f 76 32 28 29 20 61 6e 64 20  3_open_v2() and 
1f760 61 73 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65  as UTF-16 in the
1f770 20 6e 61 74 69 76 65 20 62 79 74 65 0a 2a 2a 20   native byte.** 
1f780 6f 72 64 65 72 20 66 6f 72 20 73 71 6c 69 74 65  order for sqlite
1f790 33 5f 6f 70 65 6e 31 36 28 29 2e 20 5e 28 41 20  3_open16(). ^(A 
1f7a0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
1f7b0 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 69 73 20  tion] handle is 
1f7c0 75 73 75 61 6c 6c 79 0a 2a 2a 20 72 65 74 75 72  usually.** retur
1f7d0 6e 65 64 20 69 6e 20 2a 70 70 44 62 2c 20 65 76  ned in *ppDb, ev
1f7e0 65 6e 20 69 66 20 61 6e 20 65 72 72 6f 72 20 6f  en if an error o
1f7f0 63 63 75 72 73 2e 20 20 54 68 65 20 6f 6e 6c 79  ccurs.  The only
1f800 20 65 78 63 65 70 74 69 6f 6e 20 69 73 20 74 68   exception is th
1f810 61 74 0a 2a 2a 20 69 66 20 53 51 4c 69 74 65 20  at.** if SQLite 
1f820 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c  is unable to all
1f830 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20  ocate memory to 
1f840 68 6f 6c 64 20 74 68 65 20 5b 73 71 6c 69 74 65  hold the [sqlite
1f850 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a 20 61 20  3] object,.** a 
1f860 4e 55 4c 4c 20 77 69 6c 6c 20 62 65 20 77 72 69  NULL will be wri
1f870 74 74 65 6e 20 69 6e 74 6f 20 2a 70 70 44 62 20  tten into *ppDb 
1f880 69 6e 73 74 65 61 64 20 6f 66 20 61 20 70 6f 69  instead of a poi
1f890 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c  nter to the [sql
1f8a0 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2e  ite3].** object.
1f8b0 29 5e 20 5e 28 49 66 20 74 68 65 20 64 61 74 61  )^ ^(If the data
1f8c0 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 28  base is opened (
1f8d0 61 6e 64 2f 6f 72 20 63 72 65 61 74 65 64 29 20  and/or created) 
1f8e0 73 75 63 63 65 73 73 66 75 6c 6c 79 2c 20 74 68  successfully, th
1f8f0 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b  en.** [SQLITE_OK
1f900 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20  ] is returned.  
1f910 4f 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72  Otherwise an [er
1f920 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74  ror code] is ret
1f930 75 72 6e 65 64 2e 29 5e 20 5e 54 68 65 0a 2a 2a  urned.)^ ^The.**
1f940 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
1f950 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
1f960 65 72 72 6d 73 67 31 36 28 29 5d 20 72 6f 75 74  errmsg16()] rout
1f970 69 6e 65 73 20 63 61 6e 20 62 65 20 75 73 65 64  ines can be used
1f980 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20 61 6e   to obtain.** an
1f990 20 45 6e 67 6c 69 73 68 20 6c 61 6e 67 75 61 67   English languag
1f9a0 65 20 64 65 73 63 72 69 70 74 69 6f 6e 20 6f 66  e description of
1f9b0 20 74 68 65 20 65 72 72 6f 72 20 66 6f 6c 6c 6f   the error follo
1f9c0 77 69 6e 67 20 61 20 66 61 69 6c 75 72 65 20 6f  wing a failure o
1f9d0 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 20  f any.** of the 
1f9e0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 72  sqlite3_open() r
1f9f0 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e  outines..**.** ^
1fa00 54 68 65 20 64 65 66 61 75 6c 74 20 65 6e 63 6f  The default enco
1fa10 64 69 6e 67 20 66 6f 72 20 74 68 65 20 64 61 74  ding for the dat
1fa20 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20 55 54  abase will be UT
1fa30 46 2d 38 20 69 66 0a 2a 2a 20 73 71 6c 69 74 65  F-8 if.** sqlite
1fa40 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69  3_open() or sqli
1fa50 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73  te3_open_v2() is
1fa60 20 63 61 6c 6c 65 64 20 61 6e 64 0a 2a 2a 20 55   called and.** U
1fa70 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74  TF-16 in the nat
1fa80 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 69  ive byte order i
1fa90 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36  f sqlite3_open16
1faa0 28 29 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a  () is used..**.*
1fab0 2a 20 57 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  * Whether or not
1fac0 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73   an error occurs
1fad0 20 77 68 65 6e 20 69 74 20 69 73 20 6f 70 65 6e   when it is open
1fae0 65 64 2c 20 72 65 73 6f 75 72 63 65 73 0a 2a 2a  ed, resources.**
1faf0 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
1fb00 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
1fb10 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c  onnection] handl
1fb20 65 20 73 68 6f 75 6c 64 20 62 65 20 72 65 6c 65  e should be rele
1fb30 61 73 65 64 20 62 79 0a 2a 2a 20 70 61 73 73 69  ased by.** passi
1fb40 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65  ng it to [sqlite
1fb50 33 5f 63 6c 6f 73 65 28 29 5d 20 77 68 65 6e 20  3_close()] when 
1fb60 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20  it is no longer 
1fb70 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20  required..**.** 
1fb80 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  The sqlite3_open
1fb90 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 20  _v2() interface 
1fba0 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74  works like sqlit
1fbb0 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65 78 63  e3_open().** exc
1fbc0 65 70 74 20 74 68 61 74 20 69 74 20 61 63 63 65  ept that it acce
1fbd0 70 74 73 20 74 77 6f 20 61 64 64 69 74 69 6f 6e  pts two addition
1fbe0 61 6c 20 70 61 72 61 6d 65 74 65 72 73 20 66 6f  al parameters fo
1fbf0 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 63 6f 6e  r additional con
1fc00 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74 68 65  trol.** over the
1fc10 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f   new database co
1fc20 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 28 54 68 65  nnection.  ^(The
1fc30 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72   flags parameter
1fc40 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f   to.** sqlite3_o
1fc50 70 65 6e 5f 76 32 28 29 20 63 61 6e 20 74 61 6b  pen_v2() can tak
1fc60 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68 65 20  e one of.** the 
1fc70 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65 65 20  following three 
1fc80 76 61 6c 75 65 73 2c 20 6f 70 74 69 6f 6e 61 6c  values, optional
1fc90 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69 74 68  ly combined with
1fca0 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45   the .** [SQLITE
1fcb0 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c 20  _OPEN_NOMUTEX], 
1fcc0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c  [SQLITE_OPEN_FUL
1fcd0 4c 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45  LMUTEX], [SQLITE
1fce0 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48  _OPEN_SHAREDCACH
1fcf0 45 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  E],.** [SQLITE_O
1fd00 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45  PEN_PRIVATECACHE
1fd10 5d 2c 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54  ], and/or [SQLIT
1fd20 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67  E_OPEN_URI] flag
1fd30 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a  s:)^.**.** <dl>.
1fd40 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45  ** ^(<dt>[SQLITE
1fd50 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c  _OPEN_READONLY]<
1fd60 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
1fd70 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
1fd80 65 64 20 69 6e 20 72 65 61 64 2d 6f 6e 6c 79 20  ed in read-only 
1fd90 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 64 61  mode.  If the da
1fda0 74 61 62 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a  tabase does not.
1fdb0 2a 2a 20 61 6c 72 65 61 64 79 20 65 78 69 73 74  ** already exist
1fdc0 2c 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65  , an error is re
1fdd0 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a  turned.</dd>)^.*
1fde0 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49  *.** ^(<dt>[SQLI
1fdf0 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
1fe00 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  E]</dt>.** <dd>T
1fe10 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
1fe20 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e  pened for readin
1fe30 67 20 61 6e 64 20 77 72 69 74 69 6e 67 20 69 66  g and writing if
1fe40 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20 72 65   possible, or re
1fe50 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69 66  ading.** only if
1fe60 20 74 68 65 20 66 69 6c 65 20 69 73 20 77 72 69   the file is wri
1fe70 74 65 20 70 72 6f 74 65 63 74 65 64 20 62 79 20  te protected by 
1fe80 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79  the operating sy
1fe90 73 74 65 6d 2e 20 20 49 6e 20 65 69 74 68 65 72  stem.  In either
1fea0 0a 2a 2a 20 63 61 73 65 20 74 68 65 20 64 61 74  .** case the dat
1feb0 61 62 61 73 65 20 6d 75 73 74 20 61 6c 72 65 61  abase must alrea
1fec0 64 79 20 65 78 69 73 74 2c 20 6f 74 68 65 72 77  dy exist, otherw
1fed0 69 73 65 20 61 6e 20 65 72 72 6f 72 20 69 73 20  ise an error is 
1fee0 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e  returned.</dd>)^
1fef0 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51  .**.** ^(<dt>[SQ
1ff00 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
1ff10 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f  ITE] | [SQLITE_O
1ff20 50 45 4e 5f 43 52 45 41 54 45 5d 3c 2f 64 74 3e  PEN_CREATE]</dt>
1ff30 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61  .** <dd>The data
1ff40 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66  base is opened f
1ff50 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77  or reading and w
1ff60 72 69 74 69 6e 67 2c 20 61 6e 64 20 69 73 20 63  riting, and is c
1ff70 72 65 61 74 65 64 20 69 66 0a 2a 2a 20 69 74 20  reated if.** it 
1ff80 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65 61 64 79  does not already
1ff90 20 65 78 69 73 74 2e 20 54 68 69 73 20 69 73 20   exist. This is 
1ffa0 74 68 65 20 62 65 68 61 76 69 6f 72 20 74 68 61  the behavior tha
1ffb0 74 20 69 73 20 61 6c 77 61 79 73 20 75 73 65 64  t is always used
1ffc0 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   for.** sqlite3_
1ffd0 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74  open() and sqlit
1ffe0 65 33 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f 64 64  e3_open16().</dd
1fff0 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a  >)^.** </dl>.**.
20000 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20 70 61  ** If the 3rd pa
20010 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
20020 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20  e3_open_v2() is 
20030 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a  not one of the.*
20040 2a 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73  * combinations s
20050 68 6f 77 6e 20 61 62 6f 76 65 20 6f 70 74 69 6f  hown above optio
20060 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77  nally combined w
20070 69 74 68 20 6f 74 68 65 72 0a 2a 2a 20 5b 53 51  ith other.** [SQ
20080 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e  LITE_OPEN_READON
20090 4c 59 20 7c 20 53 51 4c 49 54 45 5f 4f 50 45 4e  LY | SQLITE_OPEN
200a0 5f 2a 20 62 69 74 73 5d 0a 2a 2a 20 74 68 65 6e  _* bits].** then
200b0 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73   the behavior is
200c0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
200d0 2a 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54  * ^If the [SQLIT
200e0 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20  E_OPEN_NOMUTEX] 
200f0 66 6c 61 67 20 69 73 20 73 65 74 2c 20 74 68 65  flag is set, the
20100 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  n the database c
20110 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 70 65  onnection.** ope
20120 6e 73 20 69 6e 20 74 68 65 20 6d 75 6c 74 69 2d  ns in the multi-
20130 74 68 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e  thread [threadin
20140 67 20 6d 6f 64 65 5d 20 61 73 20 6c 6f 6e 67 20  g mode] as long 
20150 61 73 20 74 68 65 20 73 69 6e 67 6c 65 2d 74 68  as the single-th
20160 72 65 61 64 0a 2a 2a 20 6d 6f 64 65 20 68 61 73  read.** mode has
20170 20 6e 6f 74 20 62 65 65 6e 20 73 65 74 20 61 74   not been set at
20180 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72   compile-time or
20190 20 73 74 61 72 74 2d 74 69 6d 65 2e 20 20 5e 49   start-time.  ^I
201a0 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  f the.** [SQLITE
201b0 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d  _OPEN_FULLMUTEX]
201c0 20 66 6c 61 67 20 69 73 20 73 65 74 20 74 68 65   flag is set the
201d0 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  n the database c
201e0 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 73 0a  onnection opens.
201f0 2a 2a 20 69 6e 20 74 68 65 20 73 65 72 69 61 6c  ** in the serial
20200 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20  ized [threading 
20210 6d 6f 64 65 5d 20 75 6e 6c 65 73 73 20 73 69 6e  mode] unless sin
20220 67 6c 65 2d 74 68 72 65 61 64 20 77 61 73 0a 2a  gle-thread was.*
20230 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 6c  * previously sel
20240 65 63 74 65 64 20 61 74 20 63 6f 6d 70 69 6c 65  ected at compile
20250 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74  -time or start-t
20260 69 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  ime..** ^The [SQ
20270 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44  LITE_OPEN_SHARED
20280 43 41 43 48 45 5d 20 66 6c 61 67 20 63 61 75 73  CACHE] flag caus
20290 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  es the database 
202a0 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 62 65  connection to be
202b0 0a 2a 2a 20 65 6c 69 67 69 62 6c 65 20 74 6f 20  .** eligible to 
202c0 75 73 65 20 5b 73 68 61 72 65 64 20 63 61 63 68  use [shared cach
202d0 65 20 6d 6f 64 65 5d 2c 20 72 65 67 61 72 64 6c  e mode], regardl
202e0 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f  ess of whether o
202f0 72 20 6e 6f 74 20 73 68 61 72 65 64 0a 2a 2a 20  r not shared.** 
20300 63 61 63 68 65 20 69 73 20 65 6e 61 62 6c 65 64  cache is enabled
20310 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
20320 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61  enable_shared_ca
20330 63 68 65 28 29 5d 2e 20 20 5e 54 68 65 0a 2a 2a  che()].  ^The.**
20340 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52   [SQLITE_OPEN_PR
20350 49 56 41 54 45 43 41 43 48 45 5d 20 66 6c 61 67  IVATECACHE] flag
20360 20 63 61 75 73 65 73 20 74 68 65 20 64 61 74 61   causes the data
20370 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
20380 74 6f 20 6e 6f 74 0a 2a 2a 20 70 61 72 74 69 63  to not.** partic
20390 69 70 61 74 65 20 69 6e 20 5b 73 68 61 72 65 64  ipate in [shared
203a0 20 63 61 63 68 65 20 6d 6f 64 65 5d 20 65 76 65   cache mode] eve
203b0 6e 20 69 66 20 69 74 20 69 73 20 65 6e 61 62 6c  n if it is enabl
203c0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  ed..**.** ^The f
203d0 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
203e0 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  to sqlite3_open_
203f0 76 32 28 29 20 69 73 20 74 68 65 20 6e 61 6d 65  v2() is the name
20400 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69   of the.** [sqli
20410 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20  te3_vfs] object 
20420 74 68 61 74 20 64 65 66 69 6e 65 73 20 74 68 65  that defines the
20430 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
20440 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74  m interface that
20450 0a 2a 2a 20 74 68 65 20 6e 65 77 20 64 61 74 61  .** the new data
20460 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
20470 73 68 6f 75 6c 64 20 75 73 65 2e 20 20 5e 49 66  should use.  ^If
20480 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
20490 6d 65 74 65 72 20 69 73 0a 2a 2a 20 61 20 4e 55  meter is.** a NU
204a0 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20  LL pointer then 
204b0 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c  the default [sql
204c0 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
204d0 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20   is used..**.** 
204e0 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  ^If the filename
204f0 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20   is ":memory:", 
20500 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20  then a private, 
20510 74 65 6d 70 6f 72 61 72 79 20 69 6e 2d 6d 65 6d  temporary in-mem
20520 6f 72 79 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  ory database.** 
20530 69 73 20 63 72 65 61 74 65 64 20 66 6f 72 20 74  is created for t
20540 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20  he connection.  
20550 5e 54 68 69 73 20 69 6e 2d 6d 65 6d 6f 72 79 20  ^This in-memory 
20560 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 76 61  database will va
20570 6e 69 73 68 20 77 68 65 6e 0a 2a 2a 20 74 68 65  nish when.** the
20580 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
20590 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 20  tion is closed. 
205a0 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   Future versions
205b0 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74   of SQLite might
205c0 0a 2a 2a 20 6d 61 6b 65 20 75 73 65 20 6f 66 20  .** make use of 
205d0 61 64 64 69 74 69 6f 6e 61 6c 20 73 70 65 63 69  additional speci
205e0 61 6c 20 66 69 6c 65 6e 61 6d 65 73 20 74 68 61  al filenames tha
205f0 74 20 62 65 67 69 6e 20 77 69 74 68 20 74 68 65  t begin with the
20600 20 22 3a 22 20 63 68 61 72 61 63 74 65 72 2e 0a   ":" character..
20610 2a 2a 20 49 74 20 69 73 20 72 65 63 6f 6d 6d 65  ** It is recomme
20620 6e 64 65 64 20 74 68 61 74 20 77 68 65 6e 20 61  nded that when a
20630 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61   database filena
20640 6d 65 20 61 63 74 75 61 6c 6c 79 20 64 6f 65 73  me actually does
20650 20 62 65 67 69 6e 20 77 69 74 68 0a 2a 2a 20 61   begin with.** a
20660 20 22 3a 22 20 63 68 61 72 61 63 74 65 72 20 79   ":" character y
20670 6f 75 20 73 68 6f 75 6c 64 20 70 72 65 66 69 78  ou should prefix
20680 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 77 69   the filename wi
20690 74 68 20 61 20 70 61 74 68 6e 61 6d 65 20 73 75  th a pathname su
206a0 63 68 20 61 73 0a 2a 2a 20 22 2e 2f 22 20 74 6f  ch as.** "./" to
206b0 20 61 76 6f 69 64 20 61 6d 62 69 67 75 69 74 79   avoid ambiguity
206c0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
206d0 66 69 6c 65 6e 61 6d 65 20 69 73 20 61 6e 20 65  filename is an e
206e0 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 74 68 65  mpty string, the
206f0 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d  n a private, tem
20700 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73  porary.** on-dis
20710 6b 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20  k database will 
20720 62 65 20 63 72 65 61 74 65 64 2e 20 20 5e 54 68  be created.  ^Th
20730 69 73 20 70 72 69 76 61 74 65 20 64 61 74 61 62  is private datab
20740 61 73 65 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 61  ase will be.** a
20750 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c  utomatically del
20760 65 74 65 64 20 61 73 20 73 6f 6f 6e 20 61 73 20  eted as soon as 
20770 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
20780 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65  nection is close
20790 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66  d..**.** [[URI f
207a0 69 6c 65 6e 61 6d 65 73 20 69 6e 20 73 71 6c 69  ilenames in sqli
207b0 74 65 33 5f 6f 70 65 6e 28 29 5d 5d 20 3c 68 33  te3_open()]] <h3
207c0 3e 55 52 49 20 46 69 6c 65 6e 61 6d 65 73 3c 2f  >URI Filenames</
207d0 68 33 3e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 5b 55  h3>.**.** ^If [U
207e0 52 49 20 66 69 6c 65 6e 61 6d 65 5d 20 69 6e 74  RI filename] int
207f0 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20 65  erpretation is e
20800 6e 61 62 6c 65 64 2c 20 61 6e 64 20 74 68 65 20  nabled, and the 
20810 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e  filename argumen
20820 74 0a 2a 2a 20 62 65 67 69 6e 73 20 77 69 74 68  t.** begins with
20830 20 22 66 69 6c 65 3a 22 2c 20 74 68 65 6e 20 74   "file:", then t
20840 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 69  he filename is i
20850 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20  nterpreted as a 
20860 55 52 49 2e 20 5e 55 52 49 0a 2a 2a 20 66 69 6c  URI. ^URI.** fil
20870 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 65 74 61  ename interpreta
20880 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 20  tion is enabled 
20890 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  if the [SQLITE_O
208a0 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69 73  PEN_URI] flag is
208b0 0a 2a 2a 20 73 65 74 20 69 6e 20 74 68 65 20 66  .** set in the f
208c0 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74  ourth argument t
208d0 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  o sqlite3_open_v
208e0 32 28 29 2c 20 6f 72 20 69 66 20 69 74 20 68 61  2(), or if it ha
208f0 73 0a 2a 2a 20 62 65 65 6e 20 65 6e 61 62 6c 65  s.** been enable
20900 64 20 67 6c 6f 62 61 6c 6c 79 20 75 73 69 6e 67  d globally using
20910 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e   the [SQLITE_CON
20920 46 49 47 5f 55 52 49 5d 20 6f 70 74 69 6f 6e 20  FIG_URI] option 
20930 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  with the.** [sql
20940 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 6d  ite3_config()] m
20950 65 74 68 6f 64 20 6f 72 20 62 79 20 74 68 65 20  ethod or by the 
20960 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d  [SQLITE_USE_URI]
20970 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
20980 74 69 6f 6e 2e 0a 2a 2a 20 41 73 20 6f 66 20 53  tion..** As of S
20990 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e  QLite version 3.
209a0 37 2e 37 2c 20 55 52 49 20 66 69 6c 65 6e 61 6d  7.7, URI filenam
209b0 65 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e  e interpretation
209c0 20 69 73 20 74 75 72 6e 65 64 20 6f 66 66 0a 2a   is turned off.*
209d0 2a 20 62 79 20 64 65 66 61 75 6c 74 2c 20 62 75  * by default, bu
209e0 74 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  t future release
209f0 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68  s of SQLite migh
20a00 74 20 65 6e 61 62 6c 65 20 55 52 49 20 66 69 6c  t enable URI fil
20a10 65 6e 61 6d 65 0a 2a 2a 20 69 6e 74 65 72 70 72  ename.** interpr
20a20 65 74 61 74 69 6f 6e 20 62 79 20 64 65 66 61 75  etation by defau
20a30 6c 74 2e 20 20 53 65 65 20 22 5b 55 52 49 20 66  lt.  See "[URI f
20a40 69 6c 65 6e 61 6d 65 73 5d 22 20 66 6f 72 20 61  ilenames]" for a
20a50 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66  dditional.** inf
20a60 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  ormation..**.** 
20a70 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 61 72  URI filenames ar
20a80 65 20 70 61 72 73 65 64 20 61 63 63 6f 72 64 69  e parsed accordi
20a90 6e 67 20 74 6f 20 52 46 43 20 33 39 38 36 2e 20  ng to RFC 3986. 
20aa0 5e 49 66 20 74 68 65 20 55 52 49 20 63 6f 6e 74  ^If the URI cont
20ab0 61 69 6e 73 20 61 6e 0a 2a 2a 20 61 75 74 68 6f  ains an.** autho
20ac0 72 69 74 79 2c 20 74 68 65 6e 20 69 74 20 6d 75  rity, then it mu
20ad0 73 74 20 62 65 20 65 69 74 68 65 72 20 61 6e 20  st be either an 
20ae0 65 6d 70 74 79 20 73 74 72 69 6e 67 20 6f 72 20  empty string or 
20af0 74 68 65 20 73 74 72 69 6e 67 20 0a 2a 2a 20 22  the string .** "
20b00 6c 6f 63 61 6c 68 6f 73 74 22 2e 20 5e 49 66 20  localhost". ^If 
20b10 74 68 65 20 61 75 74 68 6f 72 69 74 79 20 69 73  the authority is
20b20 20 6e 6f 74 20 61 6e 20 65 6d 70 74 79 20 73 74   not an empty st
20b30 72 69 6e 67 20 6f 72 20 22 6c 6f 63 61 6c 68 6f  ring or "localho
20b40 73 74 22 2c 20 61 6e 20 0a 2a 2a 20 65 72 72 6f  st", an .** erro
20b50 72 20 69 73 20 72 65 74 75 72 6e 65 64 20 74 6f  r is returned to
20b60 20 74 68 65 20 63 61 6c 6c 65 72 2e 20 5e 54 68   the caller. ^Th
20b70 65 20 66 72 61 67 6d 65 6e 74 20 63 6f 6d 70 6f  e fragment compo
20b80 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 2c 20 69  nent of a URI, i
20b90 66 20 0a 2a 2a 20 70 72 65 73 65 6e 74 2c 20 69  f .** present, i
20ba0 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a  s ignored..**.**
20bb0 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20 74 68   ^SQLite uses th
20bc0 65 20 70 61 74 68 20 63 6f 6d 70 6f 6e 65 6e 74  e path component
20bd0 20 6f 66 20 74 68 65 20 55 52 49 20 61 73 20 74   of the URI as t
20be0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64  he name of the d
20bf0 69 73 6b 20 66 69 6c 65 0a 2a 2a 20 77 68 69 63  isk file.** whic
20c00 68 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 64  h contains the d
20c10 61 74 61 62 61 73 65 2e 20 5e 49 66 20 74 68 65  atabase. ^If the
20c20 20 70 61 74 68 20 62 65 67 69 6e 73 20 77 69 74   path begins wit
20c30 68 20 61 20 27 2f 27 20 63 68 61 72 61 63 74 65  h a '/' characte
20c40 72 2c 20 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69  r, .** then it i
20c50 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  s interpreted as
20c60 20 61 6e 20 61 62 73 6f 6c 75 74 65 20 70 61 74   an absolute pat
20c70 68 2e 20 5e 49 66 20 74 68 65 20 70 61 74 68 20  h. ^If the path 
20c80 64 6f 65 73 20 6e 6f 74 20 62 65 67 69 6e 20 0a  does not begin .
20c90 2a 2a 20 77 69 74 68 20 61 20 27 2f 27 20 28 6d  ** with a '/' (m
20ca0 65 61 6e 69 6e 67 20 74 68 61 74 20 74 68 65 20  eaning that the 
20cb0 61 75 74 68 6f 72 69 74 79 20 73 65 63 74 69 6f  authority sectio
20cc0 6e 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f  n is omitted fro
20cd0 6d 20 74 68 65 20 55 52 49 29 0a 2a 2a 20 74 68  m the URI).** th
20ce0 65 6e 20 74 68 65 20 70 61 74 68 20 69 73 20 69  en the path is i
20cf0 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20  nterpreted as a 
20d00 72 65 6c 61 74 69 76 65 20 70 61 74 68 2e 20 0a  relative path. .
20d10 2a 2a 20 5e 4f 6e 20 77 69 6e 64 6f 77 73 2c 20  ** ^On windows, 
20d20 74 68 65 20 66 69 72 73 74 20 63 6f 6d 70 6f 6e  the first compon
20d30 65 6e 74 20 6f 66 20 61 6e 20 61 62 73 6f 6c 75  ent of an absolu
20d40 74 65 20 70 61 74 68 20 0a 2a 2a 20 69 73 20 61  te path .** is a
20d50 20 64 72 69 76 65 20 73 70 65 63 69 66 69 63 61   drive specifica
20d60 74 69 6f 6e 20 28 65 2e 67 2e 20 22 43 3a 22 29  tion (e.g. "C:")
20d70 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 63 6f 72 65 20 55  ..**.** [[core U
20d80 52 49 20 71 75 65 72 79 20 70 61 72 61 6d 65 74  RI query paramet
20d90 65 72 73 5d 5d 0a 2a 2a 20 54 68 65 20 71 75 65  ers]].** The que
20da0 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20  ry component of 
20db0 61 20 55 52 49 20 6d 61 79 20 63 6f 6e 74 61 69  a URI may contai
20dc0 6e 20 70 61 72 61 6d 65 74 65 72 73 20 74 68 61  n parameters tha
20dd0 74 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65  t are interprete
20de0 64 0a 2a 2a 20 65 69 74 68 65 72 20 62 79 20 53  d.** either by S
20df0 51 4c 69 74 65 20 69 74 73 65 6c 66 2c 20 6f 72  QLite itself, or
20e00 20 62 79 20 61 20 5b 56 46 53 20 7c 20 63 75 73   by a [VFS | cus
20e10 74 6f 6d 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e  tom VFS implemen
20e20 74 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 53 51 4c 69  tation]..** SQLi
20e30 74 65 20 69 6e 74 65 72 70 72 65 74 73 20 74 68  te interprets th
20e40 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65  e following thre
20e50 65 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  e query paramete
20e60 72 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  rs:.**.** <ul>.*
20e70 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 76 66 73 3c  *   <li> <b>vfs<
20e80 2f 62 3e 3a 20 5e 54 68 65 20 22 76 66 73 22 20  /b>: ^The "vfs" 
20e90 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65  parameter may be
20ea0 20 75 73 65 64 20 74 6f 20 73 70 65 63 69 66 79   used to specify
20eb0 20 74 68 65 20 6e 61 6d 65 20 6f 66 0a 2a 2a 20   the name of.** 
20ec0 20 20 20 20 61 20 56 46 53 20 6f 62 6a 65 63 74      a VFS object
20ed0 20 74 68 61 74 20 70 72 6f 76 69 64 65 73 20 74   that provides t
20ee0 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  he operating sys
20ef0 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68  tem interface th
20f00 61 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 20 20 20  at should.**    
20f10 20 62 65 20 75 73 65 64 20 74 6f 20 61 63 63 65   be used to acce
20f20 73 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ss the database 
20f30 66 69 6c 65 20 6f 6e 20 64 69 73 6b 2e 20 5e 49  file on disk. ^I
20f40 66 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 69 73  f this option is
20f50 20 73 65 74 20 74 6f 0a 2a 2a 20 20 20 20 20 61   set to.**     a
20f60 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20 74  n empty string t
20f70 68 65 20 64 65 66 61 75 6c 74 20 56 46 53 20 6f  he default VFS o
20f80 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e 20 5e  bject is used. ^
20f90 53 70 65 63 69 66 79 69 6e 67 20 61 6e 20 75 6e  Specifying an un
20fa0 6b 6e 6f 77 6e 0a 2a 2a 20 20 20 20 20 56 46 53  known.**     VFS
20fb0 20 69 73 20 61 6e 20 65 72 72 6f 72 2e 20 5e 49   is an error. ^I
20fc0 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  f sqlite3_open_v
20fd0 32 28 29 20 69 73 20 75 73 65 64 20 61 6e 64 20  2() is used and 
20fe0 74 68 65 20 76 66 73 20 6f 70 74 69 6f 6e 20 69  the vfs option i
20ff0 73 0a 2a 2a 20 20 20 20 20 70 72 65 73 65 6e 74  s.**     present
21000 2c 20 74 68 65 6e 20 74 68 65 20 56 46 53 20 73  , then the VFS s
21010 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20  pecified by the 
21020 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 70 72 65  option takes pre
21030 63 65 64 65 6e 63 65 20 6f 76 65 72 0a 2a 2a 20  cedence over.** 
21040 20 20 20 20 74 68 65 20 76 61 6c 75 65 20 70 61      the value pa
21050 73 73 65 64 20 61 73 20 74 68 65 20 66 6f 75 72  ssed as the four
21060 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
21070 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
21080 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20  )..**.**   <li> 
21090 3c 62 3e 6d 6f 64 65 3c 2f 62 3e 3a 20 5e 28 54  <b>mode</b>: ^(T
210a0 68 65 20 6d 6f 64 65 20 70 61 72 61 6d 65 74 65  he mode paramete
210b0 72 20 6d 61 79 20 62 65 20 73 65 74 20 74 6f 20  r may be set to 
210c0 65 69 74 68 65 72 20 22 72 6f 22 2c 20 22 72 77  either "ro", "rw
210d0 22 2c 0a 2a 2a 20 20 20 20 20 22 72 77 63 22 2c  ",.**     "rwc",
210e0 20 6f 72 20 22 6d 65 6d 6f 72 79 22 2e 20 41 74   or "memory". At
210f0 74 65 6d 70 74 69 6e 67 20 74 6f 20 73 65 74 20  tempting to set 
21100 69 74 20 74 6f 20 61 6e 79 20 6f 74 68 65 72 20  it to any other 
21110 76 61 6c 75 65 20 69 73 0a 2a 2a 20 20 20 20 20  value is.**     
21120 61 6e 20 65 72 72 6f 72 29 5e 2e 20 0a 2a 2a 20  an error)^. .** 
21130 20 20 20 20 5e 49 66 20 22 72 6f 22 20 69 73 20      ^If "ro" is 
21140 73 70 65 63 69 66 69 65 64 2c 20 74 68 65 6e 20  specified, then 
21150 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  the database is 
21160 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 2d  opened for read-
21170 6f 6e 6c 79 20 0a 2a 2a 20 20 20 20 20 61 63 63  only .**     acc
21180 65 73 73 2c 20 6a 75 73 74 20 61 73 20 69 66 20  ess, just as if 
21190 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  the [SQLITE_OPEN
211a0 5f 52 45 41 44 4f 4e 4c 59 5d 20 66 6c 61 67 20  _READONLY] flag 
211b0 68 61 64 20 62 65 65 6e 20 73 65 74 20 69 6e 20  had been set in 
211c0 74 68 65 20 0a 2a 2a 20 20 20 20 20 74 68 69 72  the .**     thir
211d0 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  d argument to sq
211e0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e  lite3_open_v2().
211f0 20 5e 49 66 20 74 68 65 20 6d 6f 64 65 20 6f 70   ^If the mode op
21200 74 69 6f 6e 20 69 73 20 73 65 74 20 74 6f 20 0a  tion is set to .
21210 2a 2a 20 20 20 20 20 22 72 77 22 2c 20 74 68 65  **     "rw", the
21220 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  n the database i
21230 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61  s opened for rea
21240 64 2d 77 72 69 74 65 20 28 62 75 74 20 6e 6f 74  d-write (but not
21250 20 63 72 65 61 74 65 29 20 0a 2a 2a 20 20 20 20   create) .**    
21260 20 61 63 63 65 73 73 2c 20 61 73 20 69 66 20 53   access, as if S
21270 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
21280 52 49 54 45 20 28 62 75 74 20 6e 6f 74 20 53 51  RITE (but not SQ
21290 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
212a0 29 20 68 61 64 20 0a 2a 2a 20 20 20 20 20 62 65  ) had .**     be
212b0 65 6e 20 73 65 74 2e 20 5e 56 61 6c 75 65 20 22  en set. ^Value "
212c0 72 77 63 22 20 69 73 20 65 71 75 69 76 61 6c 65  rwc" is equivale
212d0 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20 62 6f  nt to setting bo
212e0 74 68 20 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54  th .**     SQLIT
212f0 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
21300 20 61 6e 64 20 53 51 4c 49 54 45 5f 4f 50 45 4e   and SQLITE_OPEN
21310 5f 43 52 45 41 54 45 2e 20 20 5e 49 66 20 74 68  _CREATE.  ^If th
21320 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 69 73  e mode option is
21330 0a 2a 2a 20 20 20 20 20 73 65 74 20 74 6f 20 22  .**     set to "
21340 6d 65 6d 6f 72 79 22 20 74 68 65 6e 20 61 20 70  memory" then a p
21350 75 72 65 20 5b 69 6e 2d 6d 65 6d 6f 72 79 20 64  ure [in-memory d
21360 61 74 61 62 61 73 65 5d 20 74 68 61 74 20 6e 65  atabase] that ne
21370 76 65 72 20 72 65 61 64 73 0a 2a 2a 20 20 20 20  ver reads.**    
21380 20 6f 72 20 77 72 69 74 65 73 20 66 72 6f 6d 20   or writes from 
21390 64 69 73 6b 20 69 73 20 75 73 65 64 2e 20 5e 49  disk is used. ^I
213a0 74 20 69 73 20 61 6e 20 65 72 72 6f 72 20 74 6f  t is an error to
213b0 20 73 70 65 63 69 66 79 20 61 20 76 61 6c 75 65   specify a value
213c0 20 66 6f 72 0a 2a 2a 20 20 20 20 20 74 68 65 20   for.**     the 
213d0 6d 6f 64 65 20 70 61 72 61 6d 65 74 65 72 20 74  mode parameter t
213e0 68 61 74 20 69 73 20 6c 65 73 73 20 72 65 73 74  hat is less rest
213f0 72 69 63 74 69 76 65 20 74 68 61 6e 20 74 68 61  rictive than tha
21400 74 20 73 70 65 63 69 66 69 65 64 20 62 79 0a 2a  t specified by.*
21410 2a 20 20 20 20 20 74 68 65 20 66 6c 61 67 73 20  *     the flags 
21420 70 61 73 73 65 64 20 69 6e 20 74 68 65 20 74 68  passed in the th
21430 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
21440 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
21450 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e  ()..**.**   <li>
21460 20 3c 62 3e 63 61 63 68 65 3c 2f 62 3e 3a 20 5e   <b>cache</b>: ^
21470 54 68 65 20 63 61 63 68 65 20 70 61 72 61 6d 65  The cache parame
21480 74 65 72 20 6d 61 79 20 62 65 20 73 65 74 20 74  ter may be set t
21490 6f 20 65 69 74 68 65 72 20 22 73 68 61 72 65 64  o either "shared
214a0 22 20 6f 72 0a 2a 2a 20 20 20 20 20 22 70 72 69  " or.**     "pri
214b0 76 61 74 65 22 2e 20 5e 53 65 74 74 69 6e 67 20  vate". ^Setting 
214c0 69 74 20 74 6f 20 22 73 68 61 72 65 64 22 20 69  it to "shared" i
214d0 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20  s equivalent to 
214e0 73 65 74 74 69 6e 67 20 74 68 65 0a 2a 2a 20 20  setting the.**  
214f0 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53     SQLITE_OPEN_S
21500 48 41 52 45 44 43 41 43 48 45 20 62 69 74 20 69  HAREDCACHE bit i
21510 6e 20 74 68 65 20 66 6c 61 67 73 20 61 72 67 75  n the flags argu
21520 6d 65 6e 74 20 70 61 73 73 65 64 20 74 6f 0a 2a  ment passed to.*
21530 2a 20 20 20 20 20 73 71 6c 69 74 65 33 5f 6f 70  *     sqlite3_op
21540 65 6e 5f 76 32 28 29 2e 20 5e 53 65 74 74 69 6e  en_v2(). ^Settin
21550 67 20 74 68 65 20 63 61 63 68 65 20 70 61 72 61  g the cache para
21560 6d 65 74 65 72 20 74 6f 20 22 70 72 69 76 61 74  meter to "privat
21570 65 22 20 69 73 20 0a 2a 2a 20 20 20 20 20 65 71  e" is .**     eq
21580 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74  uivalent to sett
21590 69 6e 67 20 74 68 65 20 53 51 4c 49 54 45 5f 4f  ing the SQLITE_O
215a0 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45  PEN_PRIVATECACHE
215b0 20 62 69 74 2e 0a 2a 2a 20 20 20 20 20 5e 49 66   bit..**     ^If
215c0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
215d0 28 29 20 69 73 20 75 73 65 64 20 61 6e 64 20 74  () is used and t
215e0 68 65 20 22 63 61 63 68 65 22 20 70 61 72 61 6d  he "cache" param
215f0 65 74 65 72 20 69 73 20 70 72 65 73 65 6e 74 20  eter is present 
21600 69 6e 0a 2a 2a 20 20 20 20 20 61 20 55 52 49 20  in.**     a URI 
21610 66 69 6c 65 6e 61 6d 65 2c 20 69 74 73 20 76 61  filename, its va
21620 6c 75 65 20 6f 76 65 72 72 69 64 65 73 20 61 6e  lue overrides an
21630 79 20 62 65 68 61 76 69 6f 72 20 72 65 71 75 65  y behavior reque
21640 73 74 65 64 20 62 79 20 73 65 74 74 69 6e 67 0a  sted by setting.
21650 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50  **     SQLITE_OP
21660 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 20  EN_PRIVATECACHE 
21670 6f 72 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53  or SQLITE_OPEN_S
21680 48 41 52 45 44 43 41 43 48 45 20 66 6c 61 67 2e  HAREDCACHE flag.
21690 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
216a0 5e 53 70 65 63 69 66 79 69 6e 67 20 61 6e 20 75  ^Specifying an u
216b0 6e 6b 6e 6f 77 6e 20 70 61 72 61 6d 65 74 65 72  nknown parameter
216c0 20 69 6e 20 74 68 65 20 71 75 65 72 79 20 63 6f   in the query co
216d0 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49  mponent of a URI
216e0 20 69 73 20 6e 6f 74 20 61 6e 0a 2a 2a 20 65 72   is not an.** er
216f0 72 6f 72 2e 20 20 46 75 74 75 72 65 20 76 65 72  ror.  Future ver
21700 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20  sions of SQLite 
21710 6d 69 67 68 74 20 75 6e 64 65 72 73 74 61 6e 64  might understand
21720 20 61 64 64 69 74 69 6f 6e 61 6c 20 71 75 65 72   additional quer
21730 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e  y.** parameters.
21740 20 20 53 65 65 20 22 5b 71 75 65 72 79 20 70 61    See "[query pa
21750 72 61 6d 65 74 65 72 73 20 77 69 74 68 20 73 70  rameters with sp
21760 65 63 69 61 6c 20 6d 65 61 6e 69 6e 67 20 74 6f  ecial meaning to
21770 20 53 51 4c 69 74 65 5d 22 20 66 6f 72 0a 2a 2a   SQLite]" for.**
21780 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f   additional info
21790 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b  rmation..**.** [
217a0 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 65 78  [URI filename ex
217b0 61 6d 70 6c 65 73 5d 5d 20 3c 68 33 3e 55 52 49  amples]] <h3>URI
217c0 20 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c   filename exampl
217d0 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 3c 74  es</h3>.**.** <t
217e0 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 20  able border="1" 
217f0 61 6c 69 67 6e 3d 63 65 6e 74 65 72 20 63 65 6c  align=center cel
21800 6c 70 61 64 64 69 6e 67 3d 35 3e 0a 2a 2a 20 3c  lpadding=5>.** <
21810 74 72 3e 3c 74 68 3e 20 55 52 49 20 66 69 6c 65  tr><th> URI file
21820 6e 61 6d 65 73 20 3c 74 68 3e 20 52 65 73 75 6c  names <th> Resul
21830 74 73 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66  ts.** <tr><td> f
21840 69 6c 65 3a 64 61 74 61 2e 64 62 20 3c 74 64 3e  ile:data.db <td>
21850 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70   .**          Op
21860 65 6e 20 74 68 65 20 66 69 6c 65 20 22 64 61 74  en the file "dat
21870 61 2e 64 62 22 20 69 6e 20 74 68 65 20 63 75 72  a.db" in the cur
21880 72 65 6e 74 20 64 69 72 65 63 74 6f 72 79 2e 0a  rent directory..
21890 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65  ** <tr><td> file
218a0 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61  :/home/fred/data
218b0 2e 64 62 3c 62 72 3e 0a 2a 2a 20 20 20 20 20 20  .db<br>.**      
218c0 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 68 6f 6d 65      file:///home
218d0 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 62  /fred/data.db <b
218e0 72 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  r> .**          
218f0 66 69 6c 65 3a 2f 2f 6c 6f 63 61 6c 68 6f 73 74  file://localhost
21900 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e  /home/fred/data.
21910 64 62 20 3c 62 72 3e 20 3c 74 64 3e 20 0a 2a 2a  db <br> <td> .**
21920 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 74            Open t
21930 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
21940 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74   "/home/fred/dat
21950 61 2e 64 62 22 2e 0a 2a 2a 20 3c 74 72 3e 3c 74  a.db"..** <tr><t
21960 64 3e 20 66 69 6c 65 3a 2f 2f 64 61 72 6b 73 74  d> file://darkst
21970 61 72 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74  ar/home/fred/dat
21980 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20  a.db <td> .**   
21990 20 20 20 20 20 20 20 41 6e 20 65 72 72 6f 72 2e         An error.
219a0 20 22 64 61 72 6b 73 74 61 72 22 20 69 73 20 6e   "darkstar" is n
219b0 6f 74 20 61 20 72 65 63 6f 67 6e 69 7a 65 64 20  ot a recognized 
219c0 61 75 74 68 6f 72 69 74 79 2e 0a 2a 2a 20 3c 74  authority..** <t
219d0 72 3e 3c 74 64 20 73 74 79 6c 65 3d 22 77 68 69  r><td style="whi
219e0 74 65 2d 73 70 61 63 65 3a 6e 6f 77 72 61 70 22  te-space:nowrap"
219f0 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66  > .**          f
21a00 69 6c 65 3a 2f 2f 2f 43 3a 2f 44 6f 63 75 6d 65  ile:///C:/Docume
21a10 6e 74 73 25 32 30 61 6e 64 25 32 30 53 65 74 74  nts%20and%20Sett
21a20 69 6e 67 73 2f 66 72 65 64 2f 44 65 73 6b 74 6f  ings/fred/Deskto
21a30 70 2f 64 61 74 61 2e 64 62 0a 2a 2a 20 20 20 20  p/data.db.**    
21a40 20 3c 74 64 3e 20 57 69 6e 64 6f 77 73 20 6f 6e   <td> Windows on
21a50 6c 79 3a 20 4f 70 65 6e 20 74 68 65 20 66 69 6c  ly: Open the fil
21a60 65 20 22 64 61 74 61 2e 64 62 22 20 6f 6e 20 66  e "data.db" on f
21a70 72 65 64 27 73 20 64 65 73 6b 74 6f 70 20 6f 6e  red's desktop on
21a80 20 64 72 69 76 65 0a 2a 2a 20 20 20 20 20 20 20   drive.**       
21a90 20 20 20 43 3a 2e 20 4e 6f 74 65 20 74 68 61 74     C:. Note that
21aa0 20 74 68 65 20 25 32 30 20 65 73 63 61 70 69 6e   the %20 escapin
21ab0 67 20 69 6e 20 74 68 69 73 20 65 78 61 6d 70 6c  g in this exampl
21ac0 65 20 69 73 20 6e 6f 74 20 73 74 72 69 63 74 6c  e is not strictl
21ad0 79 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e  y .**          n
21ae0 65 63 65 73 73 61 72 79 20 2d 20 73 70 61 63 65  ecessary - space
21af0 20 63 68 61 72 61 63 74 65 72 73 20 63 61 6e 20   characters can 
21b00 62 65 20 75 73 65 64 20 6c 69 74 65 72 61 6c 6c  be used literall
21b10 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e  y.**          in
21b20 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 2e 0a   URI filenames..
21b30 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65  ** <tr><td> file
21b40 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 6f  :data.db?mode=ro
21b50 26 63 61 63 68 65 3d 70 72 69 76 61 74 65 20 3c  &cache=private <
21b60 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  td> .**         
21b70 20 4f 70 65 6e 20 66 69 6c 65 20 22 64 61 74 61   Open file "data
21b80 2e 64 62 22 20 69 6e 20 74 68 65 20 63 75 72 72  .db" in the curr
21b90 65 6e 74 20 64 69 72 65 63 74 6f 72 79 20 66 6f  ent directory fo
21ba0 72 20 72 65 61 64 2d 6f 6e 6c 79 20 61 63 63 65  r read-only acce
21bb0 73 73 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ss..**          
21bc0 52 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68  Regardless of wh
21bd0 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61  ether or not sha
21be0 72 65 64 2d 63 61 63 68 65 20 6d 6f 64 65 20 69  red-cache mode i
21bf0 73 20 65 6e 61 62 6c 65 64 20 62 79 0a 2a 2a 20  s enabled by.** 
21c00 20 20 20 20 20 20 20 20 20 64 65 66 61 75 6c 74           default
21c10 2c 20 75 73 65 20 61 20 70 72 69 76 61 74 65 20  , use a private 
21c20 63 61 63 68 65 2e 0a 2a 2a 20 3c 74 72 3e 3c 74  cache..** <tr><t
21c30 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72  d> file:/home/fr
21c40 65 64 2f 64 61 74 61 2e 64 62 3f 76 66 73 3d 75  ed/data.db?vfs=u
21c50 6e 69 78 2d 6e 6f 6c 6f 63 6b 20 3c 74 64 3e 0a  nix-nolock <td>.
21c60 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e  **          Open
21c70 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65   file "/home/fre
21c80 64 2f 64 61 74 61 2e 64 62 22 2e 20 55 73 65 20  d/data.db". Use 
21c90 74 68 65 20 73 70 65 63 69 61 6c 20 56 46 53 20  the special VFS 
21ca0 22 75 6e 69 78 2d 6e 6f 6c 6f 63 6b 22 2e 0a 2a  "unix-nolock"..*
21cb0 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a  * <tr><td> file:
21cc0 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 65 61  data.db?mode=rea
21cd0 64 6f 6e 6c 79 20 3c 74 64 3e 20 0a 2a 2a 20 20  donly <td> .**  
21ce0 20 20 20 20 20 20 20 20 41 6e 20 65 72 72 6f 72          An error
21cf0 2e 20 22 72 65 61 64 6f 6e 6c 79 22 20 69 73 20  . "readonly" is 
21d00 6e 6f 74 20 61 20 76 61 6c 69 64 20 6f 70 74 69  not a valid opti
21d10 6f 6e 20 66 6f 72 20 74 68 65 20 22 6d 6f 64 65  on for the "mode
21d20 22 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20  " parameter..** 
21d30 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 0a 2a 2a 20 5e  </table>.**.** ^
21d40 55 52 49 20 68 65 78 61 64 65 63 69 6d 61 6c 20  URI hexadecimal 
21d50 65 73 63 61 70 65 20 73 65 71 75 65 6e 63 65 73  escape sequences
21d60 20 28 25 48 48 29 20 61 72 65 20 73 75 70 70 6f   (%HH) are suppo
21d70 72 74 65 64 20 77 69 74 68 69 6e 20 74 68 65 20  rted within the 
21d80 70 61 74 68 20 61 6e 64 0a 2a 2a 20 71 75 65 72  path and.** quer
21d90 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20  y components of 
21da0 61 20 55 52 49 2e 20 41 20 68 65 78 61 64 65 63  a URI. A hexadec
21db0 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71 75  imal escape sequ
21dc0 65 6e 63 65 20 63 6f 6e 73 69 73 74 73 20 6f 66  ence consists of
21dd0 20 61 0a 2a 2a 20 70 65 72 63 65 6e 74 20 73 69   a.** percent si
21de0 67 6e 20 2d 20 22 25 22 20 2d 20 66 6f 6c 6c 6f  gn - "%" - follo
21df0 77 65 64 20 62 79 20 65 78 61 63 74 6c 79 20 74  wed by exactly t
21e00 77 6f 20 68 65 78 61 64 65 63 69 6d 61 6c 20 64  wo hexadecimal d
21e10 69 67 69 74 73 20 0a 2a 2a 20 73 70 65 63 69 66  igits .** specif
21e20 79 69 6e 67 20 61 6e 20 6f 63 74 65 74 20 76 61  ying an octet va
21e30 6c 75 65 2e 20 5e 42 65 66 6f 72 65 20 74 68 65  lue. ^Before the
21e40 20 70 61 74 68 20 6f 72 20 71 75 65 72 79 20 63   path or query c
21e50 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 61 0a 2a  omponents of a.*
21e60 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 61  * URI filename a
21e70 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 2c 20  re interpreted, 
21e80 74 68 65 79 20 61 72 65 20 65 6e 63 6f 64 65 64  they are encoded
21e90 20 75 73 69 6e 67 20 55 54 46 2d 38 20 61 6e 64   using UTF-8 and
21ea0 20 61 6c 6c 20 0a 2a 2a 20 68 65 78 61 64 65 63   all .** hexadec
21eb0 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71 75  imal escape sequ
21ec0 65 6e 63 65 73 20 72 65 70 6c 61 63 65 64 20 62  ences replaced b
21ed0 79 20 61 20 73 69 6e 67 6c 65 20 62 79 74 65 20  y a single byte 
21ee0 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 0a 2a  containing the.*
21ef0 2a 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  * corresponding 
21f00 6f 63 74 65 74 2e 20 49 66 20 74 68 69 73 20 70  octet. If this p
21f10 72 6f 63 65 73 73 20 67 65 6e 65 72 61 74 65 73  rocess generates
21f20 20 61 6e 20 69 6e 76 61 6c 69 64 20 55 54 46 2d   an invalid UTF-
21f30 38 20 65 6e 63 6f 64 69 6e 67 2c 0a 2a 2a 20 74  8 encoding,.** t
21f40 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75  he results are u
21f50 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
21f60 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f  <b>Note to Windo
21f70 77 73 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54  ws users:</b>  T
21f80 68 65 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64  he encoding used
21f90 20 66 6f 72 20 74 68 65 20 66 69 6c 65 6e 61 6d   for the filenam
21fa0 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66  e argument.** of
21fb0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
21fc0 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  and sqlite3_open
21fd0 5f 76 32 28 29 20 6d 75 73 74 20 62 65 20 55 54  _v2() must be UT
21fe0 46 2d 38 2c 20 6e 6f 74 20 77 68 61 74 65 76 65  F-8, not whateve
21ff0 72 0a 2a 2a 20 63 6f 64 65 70 61 67 65 20 69 73  r.** codepage is
22000 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e   currently defin
22010 65 64 2e 20 20 46 69 6c 65 6e 61 6d 65 73 20 63  ed.  Filenames c
22020 6f 6e 74 61 69 6e 69 6e 67 20 69 6e 74 65 72 6e  ontaining intern
22030 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72 61  ational.** chara
22040 63 74 65 72 73 20 6d 75 73 74 20 62 65 20 63 6f  cters must be co
22050 6e 76 65 72 74 65 64 20 74 6f 20 55 54 46 2d 38  nverted to UTF-8
22060 20 70 72 69 6f 72 20 74 6f 20 70 61 73 73 69 6e   prior to passin
22070 67 20 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20 73  g them into.** s
22080 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72  qlite3_open() or
22090 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
220a0 28 29 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74  ()..**.** <b>Not
220b0 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 52 75 6e  e to Windows Run
220c0 74 69 6d 65 20 75 73 65 72 73 3a 3c 2f 62 3e 20  time users:</b> 
220d0 20 54 68 65 20 74 65 6d 70 6f 72 61 72 79 20 64   The temporary d
220e0 69 72 65 63 74 6f 72 79 20 6d 75 73 74 20 62 65  irectory must be
220f0 20 73 65 74 0a 2a 2a 20 70 72 69 6f 72 20 74 6f   set.** prior to
22100 20 63 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33   calling sqlite3
22110 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74  _open() or sqlit
22120 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 20 4f  e3_open_v2().  O
22130 74 68 65 72 77 69 73 65 2c 20 76 61 72 69 6f 75  therwise, variou
22140 73 0a 2a 2a 20 66 65 61 74 75 72 65 73 20 74 68  s.** features th
22150 61 74 20 72 65 71 75 69 72 65 20 74 68 65 20 75  at require the u
22160 73 65 20 6f 66 20 74 65 6d 70 6f 72 61 72 79 20  se of temporary 
22170 66 69 6c 65 73 20 6d 61 79 20 66 61 69 6c 2e 0a  files may fail..
22180 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
22190 5b 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64 69  [sqlite3_temp_di
221a0 72 65 63 74 6f 72 79 5d 0a 2a 2f 0a 69 6e 74 20  rectory].*/.int 
221b0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 0a 20 20  sqlite3_open(.  
221c0 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65  const char *file
221d0 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62  name,   /* Datab
221e0 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54  ase filename (UT
221f0 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65  F-8) */.  sqlite
22200 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20  3 **ppDb        
22210 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65    /* OUT: SQLite
22220 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b   db handle */.);
22230 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65  .int sqlite3_ope
22240 6e 31 36 28 0a 20 20 63 6f 6e 73 74 20 76 6f 69  n16(.  const voi
22250 64 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f  d *filename,   /
22260 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e  * Database filen
22270 61 6d 65 20 28 55 54 46 2d 31 36 29 20 2a 2f 0a  ame (UTF-16) */.
22280 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62    sqlite3 **ppDb
22290 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54            /* OUT
222a0 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64  : SQLite db hand
222b0 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c  le */.);.int sql
222c0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 0a 20 20  ite3_open_v2(.  
222d0 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65  const char *file
222e0 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62  name,   /* Datab
222f0 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54  ase filename (UT
22300 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65  F-8) */.  sqlite
22310 33 20 2a 2a 70 70 44 62 2c 20 20 20 20 20 20 20  3 **ppDb,       
22320 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65    /* OUT: SQLite
22330 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20   db handle */.  
22340 69 6e 74 20 66 6c 61 67 73 2c 20 20 20 20 20 20  int flags,      
22350 20 20 20 20 20 20 20 20 2f 2a 20 46 6c 61 67 73          /* Flags
22360 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
22370 20 2a 7a 56 66 73 20 20 20 20 20 20 20 20 2f 2a   *zVfs        /*
22380 20 4e 61 6d 65 20 6f 66 20 56 46 53 20 6d 6f 64   Name of VFS mod
22390 75 6c 65 20 74 6f 20 75 73 65 20 2a 2f 0a 29 3b  ule to use */.);
223a0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
223b0 3a 20 4f 62 74 61 69 6e 20 56 61 6c 75 65 73 20  : Obtain Values 
223c0 46 6f 72 20 55 52 49 20 50 61 72 61 6d 65 74 65  For URI Paramete
223d0 72 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61  rs.**.** These a
223e0 72 65 20 75 74 69 6c 69 74 79 20 72 6f 75 74 69  re utility routi
223f0 6e 65 73 2c 20 75 73 65 66 75 6c 20 74 6f 20 56  nes, useful to V
22400 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  FS implementatio
22410 6e 73 2c 20 74 68 61 74 20 63 68 65 63 6b 0a 2a  ns, that check.*
22420 2a 20 74 6f 20 73 65 65 20 69 66 20 61 20 64 61  * to see if a da
22430 74 61 62 61 73 65 20 66 69 6c 65 20 77 61 73 20  tabase file was 
22440 61 20 55 52 49 20 74 68 61 74 20 63 6f 6e 74 61  a URI that conta
22450 69 6e 65 64 20 61 20 73 70 65 63 69 66 69 63 20  ined a specific 
22460 71 75 65 72 79 20 0a 2a 2a 20 70 61 72 61 6d 65  query .** parame
22470 74 65 72 2c 20 61 6e 64 20 69 66 20 73 6f 20 6f  ter, and if so o
22480 62 74 61 69 6e 73 20 74 68 65 20 76 61 6c 75 65  btains the value
22490 20 6f 66 20 74 68 61 74 20 71 75 65 72 79 20 70   of that query p
224a0 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  arameter..**.** 
224b0 49 66 20 46 20 69 73 20 74 68 65 20 64 61 74 61  If F is the data
224c0 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 70 6f  base filename po
224d0 69 6e 74 65 72 20 70 61 73 73 65 64 20 69 6e 74  inter passed int
224e0 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 20 6d 65  o the xOpen() me
224f0 74 68 6f 64 20 6f 66 20 0a 2a 2a 20 61 20 56 46  thod of .** a VF
22500 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  S implementation
22510 20 77 68 65 6e 20 74 68 65 20 66 6c 61 67 73 20   when the flags 
22520 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70  parameter to xOp
22530 65 6e 28 29 20 68 61 73 20 6f 6e 65 20 6f 72 20  en() has one or 
22540 0a 2a 2a 20 6d 6f 72 65 20 6f 66 20 74 68 65 20  .** more of the 
22550 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49  [SQLITE_OPEN_URI
22560 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45  ] or [SQLITE_OPE
22570 4e 5f 4d 41 49 4e 5f 44 42 5d 20 62 69 74 73 20  N_MAIN_DB] bits 
22580 73 65 74 20 61 6e 64 0a 2a 2a 20 50 20 69 73 20  set and.** P is 
22590 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
225a0 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 2c  query parameter,
225b0 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33   then.** sqlite3
225c0 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 46  _uri_parameter(F
225d0 2c 50 29 20 72 65 74 75 72 6e 73 20 74 68 65 20  ,P) returns the 
225e0 76 61 6c 75 65 20 6f 66 20 74 68 65 20 50 0a 2a  value of the P.*
225f0 2a 20 70 61 72 61 6d 65 74 65 72 20 69 66 20 69  * parameter if i
22600 74 20 65 78 69 73 74 73 20 6f 72 20 61 20 4e 55  t exists or a NU
22610 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 50 20  LL pointer if P 
22620 64 6f 65 73 20 6e 6f 74 20 61 70 70 65 61 72 20  does not appear 
22630 61 73 20 61 20 0a 2a 2a 20 71 75 65 72 79 20 70  as a .** query p
22640 61 72 61 6d 65 74 65 72 20 6f 6e 20 46 2e 20 20  arameter on F.  
22650 49 66 20 50 20 69 73 20 61 20 71 75 65 72 79 20  If P is a query 
22660 70 61 72 61 6d 65 74 65 72 20 6f 66 20 46 0a 2a  parameter of F.*
22670 2a 20 68 61 73 20 6e 6f 20 65 78 70 6c 69 63 69  * has no explici
22680 74 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 73 71  t value, then sq
22690 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65  lite3_uri_parame
226a0 74 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73  ter(F,P) returns
226b0 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  .** a pointer to
226c0 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67   an empty string
226d0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
226e0 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28  te3_uri_boolean(
226f0 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 20 61  F,P,B) routine a
22700 73 73 75 6d 65 73 20 74 68 61 74 20 50 20 69 73  ssumes that P is
22710 20 61 20 62 6f 6f 6c 65 61 6e 0a 2a 2a 20 70 61   a boolean.** pa
22720 72 61 6d 65 74 65 72 20 61 6e 64 20 72 65 74 75  rameter and retu
22730 72 6e 73 20 74 72 75 65 20 28 31 29 20 6f 72 20  rns true (1) or 
22740 66 61 6c 73 65 20 28 30 29 20 61 63 63 6f 72 64  false (0) accord
22750 69 6e 67 20 74 6f 20 74 68 65 20 76 61 6c 75 65  ing to the value
22760 0a 2a 2a 20 6f 66 20 50 2e 20 20 54 68 65 20 73  .** of P.  The s
22770 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65  qlite3_uri_boole
22780 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e  an(F,P,B) routin
22790 65 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 28  e returns true (
227a0 31 29 20 69 66 20 74 68 65 0a 2a 2a 20 76 61 6c  1) if the.** val
227b0 75 65 20 6f 66 20 71 75 65 72 79 20 70 61 72 61  ue of query para
227c0 6d 65 74 65 72 20 50 20 69 73 20 6f 6e 65 20 6f  meter P is one o
227d0 66 20 22 79 65 73 22 2c 20 22 74 72 75 65 22 2c  f "yes", "true",
227e0 20 6f 72 20 22 6f 6e 22 20 69 6e 20 61 6e 79 0a   or "on" in any.
227f0 2a 2a 20 63 61 73 65 20 6f 72 20 69 66 20 74 68  ** case or if th
22800 65 20 76 61 6c 75 65 20 62 65 67 69 6e 73 20 77  e value begins w
22810 69 74 68 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 6e  ith a non-zero n
22820 75 6d 62 65 72 2e 20 20 54 68 65 20 0a 2a 2a 20  umber.  The .** 
22830 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c  sqlite3_uri_bool
22840 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69  ean(F,P,B) routi
22850 6e 65 73 20 72 65 74 75 72 6e 73 20 66 61 6c 73  nes returns fals
22860 65 20 28 30 29 20 69 66 20 74 68 65 20 76 61 6c  e (0) if the val
22870 75 65 20 6f 66 0a 2a 2a 20 71 75 65 72 79 20 70  ue of.** query p
22880 61 72 61 6d 65 74 65 72 20 50 20 69 73 20 6f 6e  arameter P is on
22890 65 20 6f 66 20 22 6e 6f 22 2c 20 22 66 61 6c 73  e of "no", "fals
228a0 65 22 2c 20 6f 72 20 22 6f 66 66 22 20 69 6e 20  e", or "off" in 
228b0 61 6e 79 20 63 61 73 65 20 6f 72 0a 2a 2a 20 69  any case or.** i
228c0 66 20 74 68 65 20 76 61 6c 75 65 20 62 65 67 69  f the value begi
228d0 6e 73 20 77 69 74 68 20 61 20 6e 75 6d 65 72 69  ns with a numeri
228e0 63 20 7a 65 72 6f 2e 20 20 49 66 20 50 20 69 73  c zero.  If P is
228f0 20 6e 6f 74 20 61 20 71 75 65 72 79 0a 2a 2a 20   not a query.** 
22900 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 46 20 6f  parameter on F o
22910 72 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 6f  r if the value o
22920 66 20 50 20 69 73 20 64 6f 65 73 20 6e 6f 74 20  f P is does not 
22930 6d 61 74 63 68 20 61 6e 79 20 6f 66 20 74 68 65  match any of the
22940 0a 2a 2a 20 61 62 6f 76 65 2c 20 74 68 65 6e 20  .** above, then 
22950 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c  sqlite3_uri_bool
22960 65 61 6e 28 46 2c 50 2c 42 29 20 72 65 74 75 72  ean(F,P,B) retur
22970 6e 73 20 28 42 21 3d 30 29 2e 0a 2a 2a 0a 2a 2a  ns (B!=0)..**.**
22980 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69   The sqlite3_uri
22990 5f 69 6e 74 36 34 28 46 2c 50 2c 44 29 20 72 6f  _int64(F,P,D) ro
229a0 75 74 69 6e 65 20 63 6f 6e 76 65 72 74 73 20 74  utine converts t
229b0 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69 6e  he value of P in
229c0 74 6f 20 61 0a 2a 2a 20 36 34 2d 62 69 74 20 73  to a.** 64-bit s
229d0 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 61 6e  igned integer an
229e0 64 20 72 65 74 75 72 6e 73 20 74 68 61 74 20 69  d returns that i
229f0 6e 74 65 67 65 72 2c 20 6f 72 20 44 20 69 66 20  nteger, or D if 
22a00 50 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 65 78  P does not.** ex
22a10 69 73 74 2e 20 20 49 66 20 74 68 65 20 76 61 6c  ist.  If the val
22a20 75 65 20 6f 66 20 50 20 69 73 20 73 6f 6d 65 74  ue of P is somet
22a30 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20  hing other than 
22a40 61 6e 20 69 6e 74 65 67 65 72 2c 20 74 68 65 6e  an integer, then
22a50 0a 2a 2a 20 7a 65 72 6f 20 69 73 20 72 65 74 75  .** zero is retu
22a60 72 6e 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 49 66 20  rned..** .** If 
22a70 46 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  F is a NULL poin
22a80 74 65 72 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  ter, then sqlite
22a90 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28  3_uri_parameter(
22aa0 46 2c 50 29 20 72 65 74 75 72 6e 73 20 4e 55 4c  F,P) returns NUL
22ab0 4c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33  L and.** sqlite3
22ac0 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50  _uri_boolean(F,P
22ad0 2c 42 29 20 72 65 74 75 72 6e 73 20 42 2e 20 20  ,B) returns B.  
22ae0 49 66 20 46 20 69 73 20 6e 6f 74 20 61 20 4e 55  If F is not a NU
22af0 4c 4c 20 70 6f 69 6e 74 65 72 20 61 6e 64 0a 2a  LL pointer and.*
22b00 2a 20 69 73 20 6e 6f 74 20 61 20 64 61 74 61 62  * is not a datab
22b10 61 73 65 20 66 69 6c 65 20 70 61 74 68 6e 61 6d  ase file pathnam
22b20 65 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 53  e pointer that S
22b30 51 4c 69 74 65 20 70 61 73 73 65 64 20 69 6e 74  QLite passed int
22b40 6f 20 74 68 65 20 78 4f 70 65 6e 0a 2a 2a 20 56  o the xOpen.** V
22b50 46 53 20 6d 65 74 68 6f 64 2c 20 74 68 65 6e 20  FS method, then 
22b60 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20  the behavior of 
22b70 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20  this routine is 
22b80 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72  undefined and pr
22b90 6f 62 61 62 6c 79 0a 2a 2a 20 75 6e 64 65 73 69  obably.** undesi
22ba0 72 61 62 6c 65 2e 0a 2a 2f 0a 63 6f 6e 73 74 20  rable..*/.const 
22bb0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 75 72  char *sqlite3_ur
22bc0 69 5f 70 61 72 61 6d 65 74 65 72 28 63 6f 6e 73  i_parameter(cons
22bd0 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d  t char *zFilenam
22be0 65 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  e, const char *z
22bf0 50 61 72 61 6d 29 3b 0a 69 6e 74 20 73 71 6c 69  Param);.int sqli
22c00 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28  te3_uri_boolean(
22c10 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c  const char *zFil
22c20 65 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  e, const char *z
22c30 50 61 72 61 6d 2c 20 69 6e 74 20 62 44 65 66 61  Param, int bDefa
22c40 75 6c 74 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e  ult);.sqlite3_in
22c50 74 36 34 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  t64 sqlite3_uri_
22c60 69 6e 74 36 34 28 63 6f 6e 73 74 20 63 68 61 72  int64(const char
22c70 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  *, const char*, 
22c80 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a  sqlite3_int64);.
22c90 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
22ca0 3a 20 45 72 72 6f 72 20 43 6f 64 65 73 20 41 6e  : Error Codes An
22cb0 64 20 4d 65 73 73 61 67 65 73 0a 2a 2a 0a 2a 2a  d Messages.**.**
22cc0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72   ^The sqlite3_er
22cd0 72 63 6f 64 65 28 29 20 69 6e 74 65 72 66 61 63  rcode() interfac
22ce0 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  e returns the nu
22cf0 6d 65 72 69 63 20 5b 72 65 73 75 6c 74 20 63 6f  meric [result co
22d00 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e  de] or.** [exten
22d10 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d  ded result code]
22d20 20 66 6f 72 20 74 68 65 20 6d 6f 73 74 20 72 65   for the most re
22d30 63 65 6e 74 20 66 61 69 6c 65 64 20 73 71 6c 69  cent failed sqli
22d40 74 65 33 5f 2a 20 41 50 49 20 63 61 6c 6c 0a 2a  te3_* API call.*
22d50 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  * associated wit
22d60 68 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f  h a [database co
22d70 6e 6e 65 63 74 69 6f 6e 5d 2e 20 49 66 20 61 20  nnection]. If a 
22d80 70 72 69 6f 72 20 41 50 49 20 63 61 6c 6c 20 66  prior API call f
22d90 61 69 6c 65 64 0a 2a 2a 20 62 75 74 20 74 68 65  ailed.** but the
22da0 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 41 50 49   most recent API
22db0 20 63 61 6c 6c 20 73 75 63 63 65 65 64 65 64 2c   call succeeded,
22dc0 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
22dd0 65 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65  e from.** sqlite
22de0 33 5f 65 72 72 63 6f 64 65 28 29 20 69 73 20 75  3_errcode() is u
22df0 6e 64 65 66 69 6e 65 64 2e 20 20 5e 54 68 65 20  ndefined.  ^The 
22e00 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64  sqlite3_extended
22e10 5f 65 72 72 63 6f 64 65 28 29 0a 2a 2a 20 69 6e  _errcode().** in
22e20 74 65 72 66 61 63 65 20 69 73 20 74 68 65 20 73  terface is the s
22e30 61 6d 65 20 65 78 63 65 70 74 20 74 68 61 74 20  ame except that 
22e40 69 74 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e  it always return
22e50 73 20 74 68 65 20 0a 2a 2a 20 5b 65 78 74 65 6e  s the .** [exten
22e60 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d  ded result code]
22e70 20 65 76 65 6e 20 77 68 65 6e 20 65 78 74 65 6e   even when exten
22e80 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
22e90 20 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c 65 64   are.** disabled
22ea0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
22eb0 69 74 65 33 5f 65 72 72 6d 73 67 28 29 20 61 6e  ite3_errmsg() an
22ec0 64 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67  d sqlite3_errmsg
22ed0 31 36 28 29 20 72 65 74 75 72 6e 20 45 6e 67 6c  16() return Engl
22ee0 69 73 68 2d 6c 61 6e 67 75 61 67 65 0a 2a 2a 20  ish-language.** 
22ef0 74 65 78 74 20 74 68 61 74 20 64 65 73 63 72 69  text that descri
22f00 62 65 73 20 74 68 65 20 65 72 72 6f 72 2c 20 61  bes the error, a
22f10 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f  s either UTF-8 o
22f20 72 20 55 54 46 2d 31 36 20 72 65 73 70 65 63 74  r UTF-16 respect
22f30 69 76 65 6c 79 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f  ively..** ^(Memo
22f40 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65  ry to hold the e
22f50 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72  rror message str
22f60 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69  ing is managed i
22f70 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68  nternally..** Th
22f80 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f  e application do
22f90 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 77  es not need to w
22fa0 6f 72 72 79 20 61 62 6f 75 74 20 66 72 65 65 69  orry about freei
22fb0 6e 67 20 74 68 65 20 72 65 73 75 6c 74 2e 0a 2a  ng the result..*
22fc0 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20 65  * However, the e
22fd0 72 72 6f 72 20 73 74 72 69 6e 67 20 6d 69 67 68  rror string migh
22fe0 74 20 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e  t be overwritten
22ff0 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 65 64 20   or deallocated 
23000 62 79 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74  by.** subsequent
23010 20 63 61 6c 6c 73 20 74 6f 20 6f 74 68 65 72 20   calls to other 
23020 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
23030 20 66 75 6e 63 74 69 6f 6e 73 2e 29 5e 0a 2a 2a   functions.)^.**
23040 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
23050 5f 65 72 72 73 74 72 28 29 20 69 6e 74 65 72 66  _errstr() interf
23060 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ace returns the 
23070 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65  English-language
23080 20 74 65 78 74 0a 2a 2a 20 74 68 61 74 20 64 65   text.** that de
23090 73 63 72 69 62 65 73 20 74 68 65 20 5b 72 65 73  scribes the [res
230a0 75 6c 74 20 63 6f 64 65 5d 2c 20 61 73 20 55 54  ult code], as UT
230b0 46 2d 38 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79  F-8..** ^(Memory
230c0 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 72   to hold the err
230d0 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e  or message strin
230e0 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69 6e 74  g is managed int
230f0 65 72 6e 61 6c 6c 79 0a 2a 2a 20 61 6e 64 20 6d  ernally.** and m
23100 75 73 74 20 6e 6f 74 20 62 65 20 66 72 65 65 64  ust not be freed
23110 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74   by the applicat
23120 69 6f 6e 29 5e 2e 0a 2a 2a 0a 2a 2a 20 57 68 65  ion)^..**.** Whe
23130 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64  n the serialized
23140 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
23150 5d 20 69 73 20 69 6e 20 75 73 65 2c 20 69 74 20  ] is in use, it 
23160 6d 69 67 68 74 20 62 65 20 74 68 65 0a 2a 2a 20  might be the.** 
23170 63 61 73 65 20 74 68 61 74 20 61 20 73 65 63 6f  case that a seco
23180 6e 64 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20  nd error occurs 
23190 6f 6e 20 61 20 73 65 70 61 72 61 74 65 20 74 68  on a separate th
231a0 72 65 61 64 20 69 6e 20 62 65 74 77 65 65 6e 0a  read in between.
231b0 2a 2a 20 74 68 65 20 74 69 6d 65 20 6f 66 20 74  ** the time of t
231c0 68 65 20 66 69 72 73 74 20 65 72 72 6f 72 20 61  he first error a
231d0 6e 64 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 74  nd the call to t
231e0 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 2e  hese interfaces.
231f0 0a 2a 2a 20 57 68 65 6e 20 74 68 61 74 20 68 61  .** When that ha
23200 70 70 65 6e 73 2c 20 74 68 65 20 73 65 63 6f 6e  ppens, the secon
23210 64 20 65 72 72 6f 72 20 77 69 6c 6c 20 62 65 20  d error will be 
23220 72 65 70 6f 72 74 65 64 20 73 69 6e 63 65 20 74  reported since t
23230 68 65 73 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63  hese.** interfac
23240 65 73 20 61 6c 77 61 79 73 20 72 65 70 6f 72 74  es always report
23250 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
23260 20 72 65 73 75 6c 74 2e 20 20 54 6f 20 61 76 6f   result.  To avo
23270 69 64 0a 2a 2a 20 74 68 69 73 2c 20 65 61 63 68  id.** this, each
23280 20 74 68 72 65 61 64 20 63 61 6e 20 6f 62 74 61   thread can obta
23290 69 6e 20 65 78 63 6c 75 73 69 76 65 20 75 73 65  in exclusive use
232a0 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73   of the [databas
232b0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a  e connection] D.
232c0 2a 2a 20 62 79 20 69 6e 76 6f 6b 69 6e 67 20 5b  ** by invoking [
232d0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e  sqlite3_mutex_en
232e0 74 65 72 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62  ter]([sqlite3_db
232f0 5f 6d 75 74 65 78 5d 28 44 29 29 20 62 65 66 6f  _mutex](D)) befo
23300 72 65 20 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20  re beginning.** 
23310 74 6f 20 75 73 65 20 44 20 61 6e 64 20 69 6e 76  to use D and inv
23320 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d  oking [sqlite3_m
23330 75 74 65 78 5f 6c 65 61 76 65 5d 28 5b 73 71 6c  utex_leave]([sql
23340 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44  ite3_db_mutex](D
23350 29 29 20 61 66 74 65 72 0a 2a 2a 20 61 6c 6c 20  )) after.** all 
23360 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 69 6e 74  calls to the int
23370 65 72 66 61 63 65 73 20 6c 69 73 74 65 64 20 68  erfaces listed h
23380 65 72 65 20 61 72 65 20 63 6f 6d 70 6c 65 74 65  ere are complete
23390 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 69  d..**.** If an i
233a0 6e 74 65 72 66 61 63 65 20 66 61 69 6c 73 20 77  nterface fails w
233b0 69 74 68 20 53 51 4c 49 54 45 5f 4d 49 53 55 53  ith SQLITE_MISUS
233c0 45 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68  E, that means th
233d0 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 77  e interface.** w
233e0 61 73 20 69 6e 76 6f 6b 65 64 20 69 6e 63 6f 72  as invoked incor
233f0 72 65 63 74 6c 79 20 62 79 20 74 68 65 20 61 70  rectly by the ap
23400 70 6c 69 63 61 74 69 6f 6e 2e 20 20 49 6e 20 74  plication.  In t
23410 68 61 74 20 63 61 73 65 2c 20 74 68 65 0a 2a 2a  hat case, the.**
23420 20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 20   error code and 
23430 6d 65 73 73 61 67 65 20 6d 61 79 20 6f 72 20 6d  message may or m
23440 61 79 20 6e 6f 74 20 62 65 20 73 65 74 2e 0a 2a  ay not be set..*
23450 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 72  /.int sqlite3_er
23460 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64  rcode(sqlite3 *d
23470 62 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  b);.int sqlite3_
23480 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65  extended_errcode
23490 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 63  (sqlite3 *db);.c
234a0 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
234b0 65 33 5f 65 72 72 6d 73 67 28 73 71 6c 69 74 65  e3_errmsg(sqlite
234c0 33 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  3*);.const void 
234d0 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31  *sqlite3_errmsg1
234e0 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e  6(sqlite3*);.con
234f0 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
23500 5f 65 72 72 73 74 72 28 69 6e 74 29 3b 0a 0a 2f  _errstr(int);../
23510 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
23520 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a  QL Statement Obj
23530 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ect.** KEYWORDS:
23540 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   {prepared state
23550 6d 65 6e 74 7d 20 7b 70 72 65 70 61 72 65 64 20  ment} {prepared 
23560 73 74 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a  statements}.**.*
23570 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  * An instance of
23580 20 74 68 69 73 20 6f 62 6a 65 63 74 20 72 65 70   this object rep
23590 72 65 73 65 6e 74 73 20 61 20 73 69 6e 67 6c 65  resents a single
235a0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 0a   SQL statement..
235b0 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69  ** This object i
235c0 73 20 76 61 72 69 6f 75 73 6c 79 20 6b 6e 6f 77  s variously know
235d0 6e 20 61 73 20 61 20 22 70 72 65 70 61 72 65 64  n as a "prepared
235e0 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 61   statement" or a
235f0 0a 2a 2a 20 22 63 6f 6d 70 69 6c 65 64 20 53 51  .** "compiled SQ
23600 4c 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20  L statement" or 
23610 73 69 6d 70 6c 79 20 61 73 20 61 20 22 73 74 61  simply as a "sta
23620 74 65 6d 65 6e 74 22 2e 0a 2a 2a 0a 2a 2a 20 54  tement"..**.** T
23630 68 65 20 6c 69 66 65 20 6f 66 20 61 20 73 74 61  he life of a sta
23640 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 67 6f  tement object go
23650 65 73 20 73 6f 6d 65 74 68 69 6e 67 20 6c 69 6b  es something lik
23660 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f  e this:.**.** <o
23670 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74  l>.** <li> Creat
23680 65 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69  e the object usi
23690 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ng [sqlite3_prep
236a0 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 61 20 72  are_v2()] or a r
236b0 65 6c 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 66  elated.**      f
236c0 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e  unction..** <li>
236d0 20 42 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20   Bind values to 
236e0 5b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73  [host parameters
236f0 5d 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69  ] using the sqli
23700 74 65 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20  te3_bind_*().** 
23710 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 73 2e       interfaces.
23720 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65  .** <li> Run the
23730 20 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20   SQL by calling 
23740 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
23750 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d   one or more tim
23760 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65  es..** <li> Rese
23770 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  t the statement 
23780 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72  using [sqlite3_r
23790 65 73 65 74 28 29 5d 20 74 68 65 6e 20 67 6f 20  eset()] then go 
237a0 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 74 6f 20  back.**      to 
237b0 73 74 65 70 20 32 2e 20 20 44 6f 20 74 68 69 73  step 2.  Do this
237c0 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 74 69   zero or more ti
237d0 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73  mes..** <li> Des
237e0 74 72 6f 79 20 74 68 65 20 6f 62 6a 65 63 74 20  troy the object 
237f0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66  using [sqlite3_f
23800 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c  inalize()]..** <
23810 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 66 65 72  /ol>.**.** Refer
23820 20 74 6f 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f   to documentatio
23830 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20  n on individual 
23840 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 66 6f  methods above fo
23850 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  r additional.** 
23860 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a  information..*/.
23870 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
23880 71 6c 69 74 65 33 5f 73 74 6d 74 20 73 71 6c 69  qlite3_stmt sqli
23890 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a  te3_stmt;../*.**
238a0 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 74   CAPI3REF: Run-t
238b0 69 6d 65 20 4c 69 6d 69 74 73 0a 2a 2a 0a 2a 2a  ime Limits.**.**
238c0 20 5e 28 54 68 69 73 20 69 6e 74 65 72 66 61 63   ^(This interfac
238d0 65 20 61 6c 6c 6f 77 73 20 74 68 65 20 73 69 7a  e allows the siz
238e0 65 20 6f 66 20 76 61 72 69 6f 75 73 20 63 6f 6e  e of various con
238f0 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 6c 69  structs to be li
23900 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f  mited.** on a co
23910 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63 6f 6e 6e  nnection by conn
23920 65 63 74 69 6f 6e 20 62 61 73 69 73 2e 20 20 54  ection basis.  T
23930 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
23940 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b 64 61  er is the.** [da
23950 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
23960 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69 74 20 69  n] whose limit i
23970 73 20 74 6f 20 62 65 20 73 65 74 20 6f 72 20 71  s to be set or q
23980 75 65 72 69 65 64 2e 20 20 54 68 65 0a 2a 2a 20  ueried.  The.** 
23990 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
239a0 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b   is one of the [
239b0 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73  limit categories
239c0 5d 20 74 68 61 74 20 64 65 66 69 6e 65 20 61 0a  ] that define a.
239d0 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63 6f 6e 73  ** class of cons
239e0 74 72 75 63 74 73 20 74 6f 20 62 65 20 73 69 7a  tructs to be siz
239f0 65 20 6c 69 6d 69 74 65 64 2e 20 20 54 68 65 20  e limited.  The 
23a00 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
23a10 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77 20 6c 69  is the.** new li
23a20 6d 69 74 20 66 6f 72 20 74 68 61 74 20 63 6f 6e  mit for that con
23a30 73 74 72 75 63 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20  struct.)^.**.** 
23a40 5e 49 66 20 74 68 65 20 6e 65 77 20 6c 69 6d 69  ^If the new limi
23a50 74 20 69 73 20 61 20 6e 65 67 61 74 69 76 65 20  t is a negative 
23a60 6e 75 6d 62 65 72 2c 20 74 68 65 20 6c 69 6d 69  number, the limi
23a70 74 20 69 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a  t is unchanged..
23a80 2a 2a 20 5e 28 46 6f 72 20 65 61 63 68 20 6c 69  ** ^(For each li
23a90 6d 69 74 20 63 61 74 65 67 6f 72 79 20 53 51 4c  mit category SQL
23aa0 49 54 45 5f 4c 49 4d 49 54 5f 3c 69 3e 4e 41 4d  ITE_LIMIT_<i>NAM
23ab0 45 3c 2f 69 3e 20 74 68 65 72 65 20 69 73 20 61  E</i> there is a
23ac0 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 68   .** [limits | h
23ad0 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 5d  ard upper bound]
23ae0 0a 2a 2a 20 73 65 74 20 61 74 20 63 6f 6d 70 69  .** set at compi
23af0 6c 65 2d 74 69 6d 65 20 62 79 20 61 20 43 20 70  le-time by a C p
23b00 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  reprocessor macr
23b10 6f 20 63 61 6c 6c 65 64 0a 2a 2a 20 5b 6c 69 6d  o called.** [lim
23b20 69 74 73 20 7c 20 53 51 4c 49 54 45 5f 4d 41 58  its | SQLITE_MAX
23b30 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e 0a 2a  _<i>NAME</i>]..*
23b40 2a 20 28 54 68 65 20 22 5f 4c 49 4d 49 54 5f 22  * (The "_LIMIT_"
23b50 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 69 73 20   in the name is 
23b60 63 68 61 6e 67 65 64 20 74 6f 20 22 5f 4d 41 58  changed to "_MAX
23b70 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41 74 74 65 6d  _".))^.** ^Attem
23b80 70 74 73 20 74 6f 20 69 6e 63 72 65 61 73 65 20  pts to increase 
23b90 61 20 6c 69 6d 69 74 20 61 62 6f 76 65 20 69 74  a limit above it
23ba0 73 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75  s hard upper bou
23bb0 6e 64 20 61 72 65 0a 2a 2a 20 73 69 6c 65 6e 74  nd are.** silent
23bc0 6c 79 20 74 72 75 6e 63 61 74 65 64 20 74 6f 20  ly truncated to 
23bd0 74 68 65 20 68 61 72 64 20 75 70 70 65 72 20 62  the hard upper b
23be0 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67  ound..**.** ^Reg
23bf0 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68  ardless of wheth
23c00 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 6c 69  er or not the li
23c10 6d 69 74 20 77 61 73 20 63 68 61 6e 67 65 64 2c  mit was changed,
23c20 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65   the .** [sqlite
23c30 33 5f 6c 69 6d 69 74 28 29 5d 20 69 6e 74 65 72  3_limit()] inter
23c40 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
23c50 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20   prior value of 
23c60 74 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 48  the limit..** ^H
23c70 65 6e 63 65 2c 20 74 6f 20 66 69 6e 64 20 74 68  ence, to find th
23c80 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20  e current value 
23c90 6f 66 20 61 20 6c 69 6d 69 74 20 77 69 74 68 6f  of a limit witho
23ca0 75 74 20 63 68 61 6e 67 69 6e 67 20 69 74 2c 0a  ut changing it,.
23cb0 2a 2a 20 73 69 6d 70 6c 79 20 69 6e 76 6f 6b 65  ** simply invoke
23cc0 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   this interface 
23cd0 77 69 74 68 20 74 68 65 20 74 68 69 72 64 20 70  with the third p
23ce0 61 72 61 6d 65 74 65 72 20 73 65 74 20 74 6f 20  arameter set to 
23cf0 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d 74 69  -1..**.** Run-ti
23d00 6d 65 20 6c 69 6d 69 74 73 20 61 72 65 20 69 6e  me limits are in
23d10 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69  tended for use i
23d20 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74  n applications t
23d30 68 61 74 20 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f  hat manage.** bo
23d40 74 68 20 74 68 65 69 72 20 6f 77 6e 20 69 6e 74  th their own int
23d50 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 20 61  ernal database a
23d60 6e 64 20 61 6c 73 6f 20 64 61 74 61 62 61 73 65  nd also database
23d70 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e 74 72  s that are contr
23d80 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 75 6e 74 72  olled.** by untr
23d90 75 73 74 65 64 20 65 78 74 65 72 6e 61 6c 20 73  usted external s
23da0 6f 75 72 63 65 73 2e 20 20 41 6e 20 65 78 61 6d  ources.  An exam
23db0 70 6c 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  ple application 
23dc0 6d 69 67 68 74 20 62 65 20 61 0a 2a 2a 20 77 65  might be a.** we
23dd0 62 20 62 72 6f 77 73 65 72 20 74 68 61 74 20 68  b browser that h
23de0 61 73 20 69 74 73 20 6f 77 6e 20 64 61 74 61 62  as its own datab
23df0 61 73 65 73 20 66 6f 72 20 73 74 6f 72 69 6e 67  ases for storing
23e00 20 68 69 73 74 6f 72 79 20 61 6e 64 0a 2a 2a 20   history and.** 
23e10 73 65 70 61 72 61 74 65 20 64 61 74 61 62 61 73  separate databas
23e20 65 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79  es controlled by
23e30 20 4a 61 76 61 53 63 72 69 70 74 20 61 70 70 6c   JavaScript appl
23e40 69 63 61 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61  ications downloa
23e50 64 65 64 0a 2a 2a 20 6f 66 66 20 74 68 65 20 49  ded.** off the I
23e60 6e 74 65 72 6e 65 74 2e 20 20 54 68 65 20 69 6e  nternet.  The in
23e70 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 73  ternal databases
23e80 20 63 61 6e 20 62 65 20 67 69 76 65 6e 20 74 68   can be given th
23e90 65 0a 2a 2a 20 6c 61 72 67 65 2c 20 64 65 66 61  e.** large, defa
23ea0 75 6c 74 20 6c 69 6d 69 74 73 2e 20 20 44 61 74  ult limits.  Dat
23eb0 61 62 61 73 65 73 20 6d 61 6e 61 67 65 64 20 62  abases managed b
23ec0 79 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63  y external sourc
23ed0 65 73 20 63 61 6e 0a 2a 2a 20 62 65 20 67 69 76  es can.** be giv
23ee0 65 6e 20 6d 75 63 68 20 73 6d 61 6c 6c 65 72 20  en much smaller 
23ef0 6c 69 6d 69 74 73 20 64 65 73 69 67 6e 65 64 20  limits designed 
23f00 74 6f 20 70 72 65 76 65 6e 74 20 61 20 64 65 6e  to prevent a den
23f10 69 61 6c 20 6f 66 20 73 65 72 76 69 63 65 0a 2a  ial of service.*
23f20 2a 20 61 74 74 61 63 6b 2e 20 20 44 65 76 65 6c  * attack.  Devel
23f30 6f 70 65 72 73 20 6d 69 67 68 74 20 61 6c 73 6f  opers might also
23f40 20 77 61 6e 74 20 74 6f 20 75 73 65 20 74 68 65   want to use the
23f50 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
23f60 74 68 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a 20 69  thorizer()].** i
23f70 6e 74 65 72 66 61 63 65 20 74 6f 20 66 75 72 74  nterface to furt
23f80 68 65 72 20 63 6f 6e 74 72 6f 6c 20 75 6e 74 72  her control untr
23f90 75 73 74 65 64 20 53 51 4c 2e 20 20 54 68 65 20  usted SQL.  The 
23fa0 73 69 7a 65 20 6f 66 20 74 68 65 20 64 61 74 61  size of the data
23fb0 62 61 73 65 0a 2a 2a 20 63 72 65 61 74 65 64 20  base.** created 
23fc0 62 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20  by an untrusted 
23fd0 73 63 72 69 70 74 20 63 61 6e 20 62 65 20 63 6f  script can be co
23fe0 6e 74 61 69 6e 65 64 20 75 73 69 6e 67 20 74 68  ntained using th
23ff0 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67 65 5f 63  e.** [max_page_c
24000 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a  ount] [PRAGMA]..
24010 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d 74 69  **.** New run-ti
24020 6d 65 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72  me limit categor
24030 69 65 73 20 6d 61 79 20 62 65 20 61 64 64 65 64  ies may be added
24040 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
24050 73 65 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ses..*/.int sqli
24060 74 65 33 5f 6c 69 6d 69 74 28 73 71 6c 69 74 65  te3_limit(sqlite
24070 33 2a 2c 20 69 6e 74 20 69 64 2c 20 69 6e 74 20  3*, int id, int 
24080 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20  newVal);../*.** 
24090 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69  CAPI3REF: Run-Ti
240a0 6d 65 20 4c 69 6d 69 74 20 43 61 74 65 67 6f 72  me Limit Categor
240b0 69 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ies.** KEYWORDS:
240c0 20 7b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79   {limit category
240d0 7d 20 7b 2a 6c 69 6d 69 74 20 63 61 74 65 67 6f  } {*limit catego
240e0 72 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ries}.**.** Thes
240f0 65 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69  e constants defi
24100 6e 65 20 76 61 72 69 6f 75 73 20 70 65 72 66 6f  ne various perfo
24110 72 6d 61 6e 63 65 20 6c 69 6d 69 74 73 0a 2a 2a  rmance limits.**
24120 20 74 68 61 74 20 63 61 6e 20 62 65 20 6c 6f 77   that can be low
24130 65 72 65 64 20 61 74 20 72 75 6e 2d 74 69 6d 65  ered at run-time
24140 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
24150 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54 68 65  limit()]..** The
24160 20 73 79 6e 6f 70 73 69 73 20 6f 66 20 74 68 65   synopsis of the
24170 20 6d 65 61 6e 69 6e 67 73 20 6f 66 20 74 68 65   meanings of the
24180 20 76 61 72 69 6f 75 73 20 6c 69 6d 69 74 73 20   various limits 
24190 69 73 20 73 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a  is shown below..
241a0 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 69 6e  ** Additional in
241b0 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 61 76 61  formation is ava
241c0 69 6c 61 62 6c 65 20 61 74 20 5b 6c 69 6d 69 74  ilable at [limit
241d0 73 20 7c 20 4c 69 6d 69 74 73 20 69 6e 20 53 51  s | Limits in SQ
241e0 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c  Lite]..**.** <dl
241f0 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  >.** [[SQLITE_LI
24200 4d 49 54 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c  MIT_LENGTH]] ^(<
24210 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
24220 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c  LENGTH</dt>.** <
24230 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 73  dd>The maximum s
24240 69 7a 65 20 6f 66 20 61 6e 79 20 73 74 72 69 6e  ize of any strin
24250 67 20 6f 72 20 42 4c 4f 42 20 6f 72 20 74 61 62  g or BLOB or tab
24260 6c 65 20 72 6f 77 2c 20 69 6e 20 62 79 74 65 73  le row, in bytes
24270 2e 3c 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  .<dd>)^.**.** [[
24280 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c  SQLITE_LIMIT_SQL
24290 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e  _LENGTH]] ^(<dt>
242a0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c  SQLITE_LIMIT_SQL
242b0 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20  _LENGTH</dt>.** 
242c0 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
242d0 6c 65 6e 67 74 68 20 6f 66 20 61 6e 20 53 51 4c  length of an SQL
242e0 20 73 74 61 74 65 6d 65 6e 74 2c 20 69 6e 20 62   statement, in b
242f0 79 74 65 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  ytes.</dd>)^.**.
24300 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
24310 54 5f 43 4f 4c 55 4d 4e 5d 5d 20 5e 28 3c 64 74  T_COLUMN]] ^(<dt
24320 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f  >SQLITE_LIMIT_CO
24330 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  LUMN</dt>.** <dd
24340 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  >The maximum num
24350 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
24360 6e 20 61 20 74 61 62 6c 65 20 64 65 66 69 6e 69  n a table defini
24370 74 69 6f 6e 20 6f 72 20 69 6e 20 74 68 65 0a 2a  tion or in the.*
24380 2a 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20  * result set of 
24390 61 20 5b 53 45 4c 45 43 54 5d 20 6f 72 20 74 68  a [SELECT] or th
243a0 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
243b0 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61   of columns in a
243c0 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f 72 20 69 6e  n index.** or in
243d0 20 61 6e 20 4f 52 44 45 52 20 42 59 20 6f 72 20   an ORDER BY or 
243e0 47 52 4f 55 50 20 42 59 20 63 6c 61 75 73 65 2e  GROUP BY clause.
243f0 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  </dd>)^.**.** [[
24400 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50  SQLITE_LIMIT_EXP
24410 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e  R_DEPTH]] ^(<dt>
24420 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50  SQLITE_LIMIT_EXP
24430 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20  R_DEPTH</dt>.** 
24440 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
24450 64 65 70 74 68 20 6f 66 20 74 68 65 20 70 61 72  depth of the par
24460 73 65 20 74 72 65 65 20 6f 6e 20 61 6e 79 20 65  se tree on any e
24470 78 70 72 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e 29  xpression.</dd>)
24480 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
24490 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f  _LIMIT_COMPOUND_
244a0 53 45 4c 45 43 54 5d 5d 20 5e 28 3c 64 74 3e 53  SELECT]] ^(<dt>S
244b0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50  QLITE_LIMIT_COMP
244c0 4f 55 4e 44 5f 53 45 4c 45 43 54 3c 2f 64 74 3e  OUND_SELECT</dt>
244d0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
244e0 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 65  mum number of te
244f0 72 6d 73 20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e  rms in a compoun
24500 64 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65  d SELECT stateme
24510 6e 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  nt.</dd>)^.**.**
24520 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
24530 56 44 42 45 5f 4f 50 5d 5d 20 5e 28 3c 64 74 3e  VDBE_OP]] ^(<dt>
24540 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42  SQLITE_LIMIT_VDB
24550 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  E_OP</dt>.** <dd
24560 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  >The maximum num
24570 62 65 72 20 6f 66 20 69 6e 73 74 72 75 63 74 69  ber of instructi
24580 6f 6e 73 20 69 6e 20 61 20 76 69 72 74 75 61 6c  ons in a virtual
24590 20 6d 61 63 68 69 6e 65 20 70 72 6f 67 72 61 6d   machine program
245a0 0a 2a 2a 20 75 73 65 64 20 74 6f 20 69 6d 70 6c  .** used to impl
245b0 65 6d 65 6e 74 20 61 6e 20 53 51 4c 20 73 74 61  ement an SQL sta
245c0 74 65 6d 65 6e 74 2e 20 20 54 68 69 73 20 6c 69  tement.  This li
245d0 6d 69 74 20 69 73 20 6e 6f 74 20 63 75 72 72 65  mit is not curre
245e0 6e 74 6c 79 0a 2a 2a 20 65 6e 66 6f 72 63 65 64  ntly.** enforced
245f0 2c 20 74 68 6f 75 67 68 20 74 68 61 74 20 6d 69  , though that mi
24600 67 68 74 20 62 65 20 61 64 64 65 64 20 69 6e 20  ght be added in 
24610 73 6f 6d 65 20 66 75 74 75 72 65 20 72 65 6c 65  some future rele
24620 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65  ase of.** SQLite
24630 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  .</dd>)^.**.** [
24640 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55  [SQLITE_LIMIT_FU
24650 4e 43 54 49 4f 4e 5f 41 52 47 5d 5d 20 5e 28 3c  NCTION_ARG]] ^(<
24660 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
24670 46 55 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f 64 74  FUNCTION_ARG</dt
24680 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
24690 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61  imum number of a
246a0 72 67 75 6d 65 6e 74 73 20 6f 6e 20 61 20 66 75  rguments on a fu
246b0 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a  nction.</dd>)^.*
246c0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
246d0 4d 49 54 5f 41 54 54 41 43 48 45 44 5d 5d 20 5e  MIT_ATTACHED]] ^
246e0 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
246f0 54 5f 41 54 54 41 43 48 45 44 3c 2f 64 74 3e 0a  T_ATTACHED</dt>.
24700 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
24710 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 5b 41 54  um number of [AT
24720 54 41 43 48 20 7c 20 61 74 74 61 63 68 65 64 20  TACH | attached 
24730 64 61 74 61 62 61 73 65 73 5d 2e 29 5e 3c 2f 64  databases].)^</d
24740 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
24750 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54  E_LIMIT_LIKE_PAT
24760 54 45 52 4e 5f 4c 45 4e 47 54 48 5d 5d 0a 2a 2a  TERN_LENGTH]].**
24770 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
24780 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e  MIT_LIKE_PATTERN
24790 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20  _LENGTH</dt>.** 
247a0 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
247b0 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 70 61  length of the pa
247c0 74 74 65 72 6e 20 61 72 67 75 6d 65 6e 74 20 74  ttern argument t
247d0 6f 20 74 68 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a  o the [LIKE] or.
247e0 2a 2a 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74  ** [GLOB] operat
247f0 6f 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  ors.</dd>)^.**.*
24800 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
24810 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52  _VARIABLE_NUMBER
24820 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49  ]].** ^(<dt>SQLI
24830 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c  TE_LIMIT_VARIABL
24840 45 5f 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a  E_NUMBER</dt>.**
24850 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
24860 20 69 6e 64 65 78 20 6e 75 6d 62 65 72 20 6f 66   index number of
24870 20 61 6e 79 20 5b 70 61 72 61 6d 65 74 65 72 5d   any [parameter]
24880 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65   in an SQL state
24890 6d 65 6e 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  ment.)^.**.** [[
248a0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49  SQLITE_LIMIT_TRI
248b0 47 47 45 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c  GGER_DEPTH]] ^(<
248c0 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
248d0 54 52 49 47 47 45 52 5f 44 45 50 54 48 3c 2f 64  TRIGGER_DEPTH</d
248e0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
248f0 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 72  ximum depth of r
24900 65 63 75 72 73 69 6f 6e 20 66 6f 72 20 74 72 69  ecursion for tri
24910 67 67 65 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  ggers.</dd>)^.**
24920 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e   </dl>.*/.#defin
24930 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  e SQLITE_LIMIT_L
24940 45 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 20  ENGTH           
24950 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 69           0.#defi
24960 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
24970 53 51 4c 5f 4c 45 4e 47 54 48 20 20 20 20 20 20  SQL_LENGTH      
24980 20 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66            1.#def
24990 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
249a0 5f 43 4f 4c 55 4d 4e 20 20 20 20 20 20 20 20 20  _COLUMN         
249b0 20 20 20 20 20 20 20 20 20 20 20 32 0a 23 64 65             2.#de
249c0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
249d0 54 5f 45 58 50 52 5f 44 45 50 54 48 20 20 20 20  T_EXPR_DEPTH    
249e0 20 20 20 20 20 20 20 20 20 20 20 20 33 0a 23 64              3.#d
249f0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
24a00 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45  IT_COMPOUND_SELE
24a10 43 54 20 20 20 20 20 20 20 20 20 20 20 34 0a 23  CT           4.#
24a20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
24a30 4d 49 54 5f 56 44 42 45 5f 4f 50 20 20 20 20 20  MIT_VDBE_OP     
24a40 20 20 20 20 20 20 20 20 20 20 20 20 20 20 35 0a                5.
24a50 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
24a60 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52  IMIT_FUNCTION_AR
24a70 47 20 20 20 20 20 20 20 20 20 20 20 20 20 20 36  G              6
24a80 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
24a90 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 20 20  LIMIT_ATTACHED  
24aa0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
24ab0 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  7.#define SQLITE
24ac0 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54  _LIMIT_LIKE_PATT
24ad0 45 52 4e 5f 4c 45 4e 47 54 48 20 20 20 20 20 20  ERN_LENGTH      
24ae0 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   8.#define SQLIT
24af0 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45  E_LIMIT_VARIABLE
24b00 5f 4e 55 4d 42 45 52 20 20 20 20 20 20 20 20 20  _NUMBER         
24b10 20 20 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    9.#define SQLI
24b20 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52  TE_LIMIT_TRIGGER
24b30 5f 44 45 50 54 48 20 20 20 20 20 20 20 20 20 20  _DEPTH          
24b40 20 20 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49    10../*.** CAPI
24b50 33 52 45 46 3a 20 43 6f 6d 70 69 6c 69 6e 67 20  3REF: Compiling 
24b60 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74  An SQL Statement
24b70 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53  .** KEYWORDS: {S
24b80 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d  QL statement com
24b90 70 69 6c 65 72 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20  piler}.**.** To 
24ba0 65 78 65 63 75 74 65 20 61 6e 20 53 51 4c 20 71  execute an SQL q
24bb0 75 65 72 79 2c 20 69 74 20 6d 75 73 74 20 66 69  uery, it must fi
24bc0 72 73 74 20 62 65 20 63 6f 6d 70 69 6c 65 64 20  rst be compiled 
24bd0 69 6e 74 6f 20 61 20 62 79 74 65 2d 63 6f 64 65  into a byte-code
24be0 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 69 6e  .** program usin
24bf0 67 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 72  g one of these r
24c00 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54  outines..**.** T
24c10 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
24c20 74 2c 20 22 64 62 22 2c 20 69 73 20 61 20 5b 64  t, "db", is a [d
24c30 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
24c40 6f 6e 5d 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  on] obtained fro
24c50 6d 20 61 0a 2a 2a 20 70 72 69 6f 72 20 73 75 63  m a.** prior suc
24c60 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20  cessful call to 
24c70 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
24c80 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  , [sqlite3_open_
24c90 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c  v2()] or.** [sql
24ca0 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 20  ite3_open16()]. 
24cb0 20 54 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   The database co
24cc0 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f  nnection must no
24cd0 74 20 68 61 76 65 20 62 65 65 6e 20 63 6c 6f 73  t have been clos
24ce0 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65  ed..**.** The se
24cf0 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2c 20 22  cond argument, "
24d00 7a 53 71 6c 22 2c 20 69 73 20 74 68 65 20 73 74  zSql", is the st
24d10 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f  atement to be co
24d20 6d 70 69 6c 65 64 2c 20 65 6e 63 6f 64 65 64 0a  mpiled, encoded.
24d30 2a 2a 20 61 73 20 65 69 74 68 65 72 20 55 54 46  ** as either UTF
24d40 2d 38 20 6f 72 20 55 54 46 2d 31 36 2e 20 20 54  -8 or UTF-16.  T
24d50 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  he sqlite3_prepa
24d60 72 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  re() and sqlite3
24d70 5f 70 72 65 70 61 72 65 5f 76 32 28 29 0a 2a 2a  _prepare_v2().**
24d80 20 69 6e 74 65 72 66 61 63 65 73 20 75 73 65 20   interfaces use 
24d90 55 54 46 2d 38 2c 20 61 6e 64 20 73 71 6c 69 74  UTF-8, and sqlit
24da0 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 20 61  e3_prepare16() a
24db0 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nd sqlite3_prepa
24dc0 72 65 31 36 5f 76 32 28 29 0a 2a 2a 20 75 73 65  re16_v2().** use
24dd0 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e   UTF-16..**.** ^
24de0 49 66 20 74 68 65 20 6e 42 79 74 65 20 61 72 67  If the nByte arg
24df0 75 6d 65 6e 74 20 69 73 20 6c 65 73 73 20 74 68  ument is less th
24e00 61 6e 20 7a 65 72 6f 2c 20 74 68 65 6e 20 7a 53  an zero, then zS
24e10 71 6c 20 69 73 20 72 65 61 64 20 75 70 20 74 6f  ql is read up to
24e20 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 7a 65   the.** first ze
24e30 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 5e  ro terminator. ^
24e40 49 66 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d  If nByte is non-
24e50 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 69  negative, then i
24e60 74 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d  t is the maximum
24e70 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 20 62  .** number of  b
24e80 79 74 65 73 20 72 65 61 64 20 66 72 6f 6d 20 7a  ytes read from z
24e90 53 71 6c 2e 20 20 5e 57 68 65 6e 20 6e 42 79 74  Sql.  ^When nByt
24ea0 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  e is non-negativ
24eb0 65 2c 20 74 68 65 0a 2a 2a 20 7a 53 71 6c 20 73  e, the.** zSql s
24ec0 74 72 69 6e 67 20 65 6e 64 73 20 61 74 20 65 69  tring ends at ei
24ed0 74 68 65 72 20 74 68 65 20 66 69 72 73 74 20 27  ther the first '
24ee0 5c 30 30 30 27 20 6f 72 20 27 5c 75 30 30 30 30  \000' or '\u0000
24ef0 27 20 63 68 61 72 61 63 74 65 72 20 6f 72 0a 2a  ' character or.*
24f00 2a 20 74 68 65 20 6e 42 79 74 65 2d 74 68 20 62  * the nByte-th b
24f10 79 74 65 2c 20 77 68 69 63 68 65 76 65 72 20 63  yte, whichever c
24f20 6f 6d 65 73 20 66 69 72 73 74 2e 20 49 66 20 74  omes first. If t
24f30 68 65 20 63 61 6c 6c 65 72 20 6b 6e 6f 77 73 0a  he caller knows.
24f40 2a 2a 20 74 68 61 74 20 74 68 65 20 73 75 70 70  ** that the supp
24f50 6c 69 65 64 20 73 74 72 69 6e 67 20 69 73 20 6e  lied string is n
24f60 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 2c 20 74  ul-terminated, t
24f70 68 65 6e 20 74 68 65 72 65 20 69 73 20 61 20 73  hen there is a s
24f80 6d 61 6c 6c 0a 2a 2a 20 70 65 72 66 6f 72 6d 61  mall.** performa
24f90 6e 63 65 20 61 64 76 61 6e 74 61 67 65 20 74 6f  nce advantage to
24fa0 20 62 65 20 67 61 69 6e 65 64 20 62 79 20 70 61   be gained by pa
24fb0 73 73 69 6e 67 20 61 6e 20 6e 42 79 74 65 20 70  ssing an nByte p
24fc0 61 72 61 6d 65 74 65 72 20 74 68 61 74 0a 2a 2a  arameter that.**
24fd0 20 69 73 20 65 71 75 61 6c 20 74 6f 20 74 68 65   is equal to the
24fe0 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
24ff0 20 69 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74   in the input st
25000 72 69 6e 67 20 3c 69 3e 69 6e 63 6c 75 64 69 6e  ring <i>includin
25010 67 3c 2f 69 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c  g</i>.** the nul
25020 2d 74 65 72 6d 69 6e 61 74 6f 72 20 62 79 74 65  -terminator byte
25030 73 20 61 73 20 74 68 69 73 20 73 61 76 65 73 20  s as this saves 
25040 53 51 4c 69 74 65 20 66 72 6f 6d 20 68 61 76 69  SQLite from havi
25050 6e 67 20 74 6f 0a 2a 2a 20 6d 61 6b 65 20 61 20  ng to.** make a 
25060 63 6f 70 79 20 6f 66 20 74 68 65 20 69 6e 70 75  copy of the inpu
25070 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  t string..**.** 
25080 5e 49 66 20 70 7a 54 61 69 6c 20 69 73 20 6e 6f  ^If pzTail is no
25090 74 20 4e 55 4c 4c 20 74 68 65 6e 20 2a 70 7a 54  t NULL then *pzT
250a0 61 69 6c 20 69 73 20 6d 61 64 65 20 74 6f 20 70  ail is made to p
250b0 6f 69 6e 74 20 74 6f 20 74 68 65 20 66 69 72 73  oint to the firs
250c0 74 20 62 79 74 65 0a 2a 2a 20 70 61 73 74 20 74  t byte.** past t
250d0 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20 66 69  he end of the fi
250e0 72 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  rst SQL statemen
250f0 74 20 69 6e 20 7a 53 71 6c 2e 20 20 54 68 65 73  t in zSql.  Thes
25100 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 6c 79 0a  e routines only.
25110 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 68 65 20 66  ** compile the f
25120 69 72 73 74 20 73 74 61 74 65 6d 65 6e 74 20 69  irst statement i
25130 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a 54 61  n zSql, so *pzTa
25140 69 6c 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74  il is left point
25150 69 6e 67 20 74 6f 0a 2a 2a 20 77 68 61 74 20 72  ing to.** what r
25160 65 6d 61 69 6e 73 20 75 6e 63 6f 6d 70 69 6c 65  emains uncompile
25170 64 2e 0a 2a 2a 0a 2a 2a 20 5e 2a 70 70 53 74 6d  d..**.** ^*ppStm
25180 74 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69  t is left pointi
25190 6e 67 20 74 6f 20 61 20 63 6f 6d 70 69 6c 65 64  ng to a compiled
251a0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
251b0 6d 65 6e 74 5d 20 74 68 61 74 20 63 61 6e 20 62  ment] that can b
251c0 65 0a 2a 2a 20 65 78 65 63 75 74 65 64 20 75 73  e.** executed us
251d0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  ing [sqlite3_ste
251e0 70 28 29 5d 2e 20 20 5e 49 66 20 74 68 65 72 65  p()].  ^If there
251f0 20 69 73 20 61 6e 20 65 72 72 6f 72 2c 20 2a 70   is an error, *p
25200 70 53 74 6d 74 20 69 73 20 73 65 74 0a 2a 2a 20  pStmt is set.** 
25210 74 6f 20 4e 55 4c 4c 2e 20 20 5e 49 66 20 74 68  to NULL.  ^If th
25220 65 20 69 6e 70 75 74 20 74 65 78 74 20 63 6f 6e  e input text con
25230 74 61 69 6e 73 20 6e 6f 20 53 51 4c 20 28 69 66  tains no SQL (if
25240 20 74 68 65 20 69 6e 70 75 74 20 69 73 20 61 6e   the input is an
25250 20 65 6d 70 74 79 0a 2a 2a 20 73 74 72 69 6e 67   empty.** string
25260 20 6f 72 20 61 20 63 6f 6d 6d 65 6e 74 29 20 74   or a comment) t
25270 68 65 6e 20 2a 70 70 53 74 6d 74 20 69 73 20 73  hen *ppStmt is s
25280 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 54  et to NULL..** T
25290 68 65 20 63 61 6c 6c 69 6e 67 20 70 72 6f 63 65  he calling proce
252a0 64 75 72 65 20 69 73 20 72 65 73 70 6f 6e 73 69  dure is responsi
252b0 62 6c 65 20 66 6f 72 20 64 65 6c 65 74 69 6e 67  ble for deleting
252c0 20 74 68 65 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a   the compiled.**
252d0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 75   SQL statement u
252e0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69  sing [sqlite3_fi
252f0 6e 61 6c 69 7a 65 28 29 5d 20 61 66 74 65 72 20  nalize()] after 
25300 69 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  it has finished 
25310 77 69 74 68 20 69 74 2e 0a 2a 2a 20 70 70 53 74  with it..** ppSt
25320 6d 74 20 6d 61 79 20 6e 6f 74 20 62 65 20 4e 55  mt may not be NU
25330 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73 75  LL..**.** ^On su
25340 63 63 65 73 73 2c 20 74 68 65 20 73 71 6c 69 74  ccess, the sqlit
25350 65 33 5f 70 72 65 70 61 72 65 28 29 20 66 61 6d  e3_prepare() fam
25360 69 6c 79 20 6f 66 20 72 6f 75 74 69 6e 65 73 20  ily of routines 
25370 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f  return [SQLITE_O
25380 4b 5d 3b 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65  K];.** otherwise
25390 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d   an [error code]
253a0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
253b0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
253c0 70 72 65 70 61 72 65 5f 76 32 28 29 20 61 6e 64  prepare_v2() and
253d0 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
253e0 31 36 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63  16_v2() interfac
253f0 65 73 20 61 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d  es are.** recomm
25400 65 6e 64 65 64 20 66 6f 72 20 61 6c 6c 20 6e 65  ended for all ne
25410 77 20 70 72 6f 67 72 61 6d 73 2e 20 54 68 65 20  w programs. The 
25420 74 77 6f 20 6f 6c 64 65 72 20 69 6e 74 65 72 66  two older interf
25430 61 63 65 73 20 61 72 65 20 72 65 74 61 69 6e 65  aces are retaine
25440 64 0a 2a 2a 20 66 6f 72 20 62 61 63 6b 77 61 72  d.** for backwar
25450 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ds compatibility
25460 2c 20 62 75 74 20 74 68 65 69 72 20 75 73 65 20  , but their use 
25470 69 73 20 64 69 73 63 6f 75 72 61 67 65 64 2e 0a  is discouraged..
25480 2a 2a 20 5e 49 6e 20 74 68 65 20 22 76 32 22 20  ** ^In the "v2" 
25490 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65 20  interfaces, the 
254a0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
254b0 6e 74 0a 2a 2a 20 74 68 61 74 20 69 73 20 72 65  nt.** that is re
254c0 74 75 72 6e 65 64 20 28 74 68 65 20 5b 73 71 6c  turned (the [sql
254d0 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63  ite3_stmt] objec
254e0 74 29 20 63 6f 6e 74 61 69 6e 73 20 61 20 63 6f  t) contains a co
254f0 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 72 69  py of the.** ori
25500 67 69 6e 61 6c 20 53 51 4c 20 74 65 78 74 2e 20  ginal SQL text. 
25510 54 68 69 73 20 63 61 75 73 65 73 20 74 68 65 20  This causes the 
25520 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
25530 20 69 6e 74 65 72 66 61 63 65 20 74 6f 0a 2a 2a   interface to.**
25540 20 62 65 68 61 76 65 20 64 69 66 66 65 72 65 6e   behave differen
25550 74 6c 79 20 69 6e 20 74 68 72 65 65 20 77 61 79  tly in three way
25560 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a  s:.**.** <ol>.**
25570 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65   <li>.** ^If the
25580 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61   database schema
25590 20 63 68 61 6e 67 65 73 2c 20 69 6e 73 74 65 61   changes, instea
255a0 64 20 6f 66 20 72 65 74 75 72 6e 69 6e 67 20 5b  d of returning [
255b0 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 61  SQLITE_SCHEMA] a
255c0 73 20 69 74 0a 2a 2a 20 61 6c 77 61 79 73 20 75  s it.** always u
255d0 73 65 64 20 74 6f 20 64 6f 2c 20 5b 73 71 6c 69  sed to do, [sqli
255e0 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c  te3_step()] will
255f0 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72   automatically r
25600 65 63 6f 6d 70 69 6c 65 20 74 68 65 20 53 51 4c  ecompile the SQL
25610 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 6e  .** statement an
25620 64 20 74 72 79 20 74 6f 20 72 75 6e 20 69 74 20  d try to run it 
25630 61 67 61 69 6e 2e 20 41 73 20 6d 61 6e 79 20 61  again. As many a
25640 73 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 53 43  s [SQLITE_MAX_SC
25650 48 45 4d 41 5f 52 45 54 52 59 5d 0a 2a 2a 20 72  HEMA_RETRY].** r
25660 65 74 72 69 65 73 20 77 69 6c 6c 20 6f 63 63 75  etries will occu
25670 72 20 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33  r before sqlite3
25680 5f 73 74 65 70 28 29 20 67 69 76 65 73 20 75 70  _step() gives up
25690 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 6e 20   and returns an 
256a0 65 72 72 6f 72 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a  error..** </li>.
256b0 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 57  **.** <li>.** ^W
256c0 68 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f 63 63  hen an error occ
256d0 75 72 73 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74  urs, [sqlite3_st
256e0 65 70 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72  ep()] will retur
256f0 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 64 65 74  n one of the det
25700 61 69 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f 72 20  ailed.** [error 
25710 63 6f 64 65 73 5d 20 6f 72 20 5b 65 78 74 65 6e  codes] or [exten
25720 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 73 5d  ded error codes]
25730 2e 20 20 5e 54 68 65 20 6c 65 67 61 63 79 20 62  .  ^The legacy b
25740 65 68 61 76 69 6f 72 20 77 61 73 20 74 68 61 74  ehavior was that
25750 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  .** [sqlite3_ste
25760 70 28 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 20  p()] would only 
25770 72 65 74 75 72 6e 20 61 20 67 65 6e 65 72 69 63  return a generic
25780 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
25790 72 65 73 75 6c 74 20 63 6f 64 65 0a 2a 2a 20 61  result code.** a
257a0 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  nd the applicati
257b0 6f 6e 20 77 6f 75 6c 64 20 68 61 76 65 20 74 6f  on would have to
257c0 20 6d 61 6b 65 20 61 20 73 65 63 6f 6e 64 20 63   make a second c
257d0 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
257e0 72 65 73 65 74 28 29 5d 0a 2a 2a 20 69 6e 20 6f  reset()].** in o
257f0 72 64 65 72 20 74 6f 20 66 69 6e 64 20 74 68 65  rder to find the
25800 20 75 6e 64 65 72 6c 79 69 6e 67 20 63 61 75 73   underlying caus
25810 65 20 6f 66 20 74 68 65 20 70 72 6f 62 6c 65 6d  e of the problem
25820 2e 20 57 69 74 68 20 74 68 65 20 22 76 32 22 20  . With the "v2" 
25830 70 72 65 70 61 72 65 0a 2a 2a 20 69 6e 74 65 72  prepare.** inter
25840 66 61 63 65 73 2c 20 74 68 65 20 75 6e 64 65 72  faces, the under
25850 6c 79 69 6e 67 20 72 65 61 73 6f 6e 20 66 6f 72  lying reason for
25860 20 74 68 65 20 65 72 72 6f 72 20 69 73 20 72 65   the error is re
25870 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65  turned immediate
25880 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a  ly..** </li>.**.
25890 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74  ** <li>.** ^If t
258a0 68 65 20 73 70 65 63 69 66 69 63 20 76 61 6c 75  he specific valu
258b0 65 20 62 6f 75 6e 64 20 74 6f 20 5b 70 61 72 61  e bound to [para
258c0 6d 65 74 65 72 20 7c 20 68 6f 73 74 20 70 61 72  meter | host par
258d0 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 65 20 0a  ameter] in the .
258e0 2a 2a 20 57 48 45 52 45 20 63 6c 61 75 73 65 20  ** WHERE clause 
258f0 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e 63 65 20  might influence 
25900 74 68 65 20 63 68 6f 69 63 65 20 6f 66 20 71 75  the choice of qu
25910 65 72 79 20 70 6c 61 6e 20 66 6f 72 20 61 20 73  ery plan for a s
25920 74 61 74 65 6d 65 6e 74 2c 0a 2a 2a 20 74 68 65  tatement,.** the
25930 6e 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  n the statement 
25940 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69  will be automati
25950 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 64  cally recompiled
25960 2c 20 61 73 20 69 66 20 74 68 65 72 65 20 68 61  , as if there ha
25970 64 20 62 65 65 6e 20 0a 2a 2a 20 61 20 73 63 68  d been .** a sch
25980 65 6d 61 20 63 68 61 6e 67 65 2c 20 6f 6e 20 74  ema change, on t
25990 68 65 20 66 69 72 73 74 20 20 5b 73 71 6c 69 74  he first  [sqlit
259a0 65 33 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c 20  e3_step()] call 
259b0 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 20 63 68  following any ch
259c0 61 6e 67 65 0a 2a 2a 20 74 6f 20 74 68 65 20 5b  ange.** to the [
259d0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
259e0 74 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 66  t | bindings] of
259f0 20 74 68 61 74 20 5b 70 61 72 61 6d 65 74 65 72   that [parameter
25a00 5d 2e 20 0a 2a 2a 20 5e 54 68 65 20 73 70 65 63  ]. .** ^The spec
25a10 69 66 69 63 20 76 61 6c 75 65 20 6f 66 20 57 48  ific value of WH
25a20 45 52 45 2d 63 6c 61 75 73 65 20 5b 70 61 72 61  ERE-clause [para
25a30 6d 65 74 65 72 5d 20 6d 69 67 68 74 20 69 6e 66  meter] might inf
25a40 6c 75 65 6e 63 65 20 74 68 65 20 0a 2a 2a 20 63  luence the .** c
25a50 68 6f 69 63 65 20 6f 66 20 71 75 65 72 79 20 70  hoice of query p
25a60 6c 61 6e 20 69 66 20 74 68 65 20 70 61 72 61 6d  lan if the param
25a70 65 74 65 72 20 69 73 20 74 68 65 20 6c 65 66 74  eter is the left
25a80 2d 68 61 6e 64 20 73 69 64 65 20 6f 66 20 61 20  -hand side of a 
25a90 5b 4c 49 4b 45 5d 0a 2a 2a 20 6f 72 20 5b 47 4c  [LIKE].** or [GL
25aa0 4f 42 5d 20 6f 70 65 72 61 74 6f 72 20 6f 72 20  OB] operator or 
25ab0 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  if the parameter
25ac0 20 69 73 20 63 6f 6d 70 61 72 65 64 20 74 6f 20   is compared to 
25ad0 61 6e 20 69 6e 64 65 78 65 64 20 63 6f 6c 75 6d  an indexed colum
25ae0 6e 0a 2a 2a 20 61 6e 64 20 74 68 65 20 5b 53 51  n.** and the [SQ
25af0 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53 54 41 54  LITE_ENABLE_STAT
25b00 33 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  3] compile-time 
25b10 6f 70 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65  option is enable
25b20 64 2e 0a 2a 2a 20 74 68 65 20 0a 2a 2a 20 3c 2f  d..** the .** </
25b30 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a  li>.** </ol>.*/.
25b40 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70  int sqlite3_prep
25b50 61 72 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  are(.  sqlite3 *
25b60 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f  db,            /
25b70 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c  * Database handl
25b80 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
25b90 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f  r *zSql,       /
25ba0 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  * SQL statement,
25bb0 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a   UTF-8 encoded *
25bc0 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20  /.  int nByte,  
25bd0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d              /* M
25be0 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
25bf0 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20   zSql in bytes. 
25c00 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d  */.  sqlite3_stm
25c10 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20  t **ppStmt,  /* 
25c20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68  OUT: Statement h
25c30 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
25c40 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20   char **pzTail  
25c50 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74     /* OUT: Point
25c60 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72  er to unused por
25c70 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a  tion of zSql */.
25c80 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70  );.int sqlite3_p
25c90 72 65 70 61 72 65 5f 76 32 28 0a 20 20 73 71 6c  repare_v2(.  sql
25ca0 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
25cb0 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
25cc0 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
25cd0 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20  st char *zSql,  
25ce0 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74       /* SQL stat
25cf0 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63  ement, UTF-8 enc
25d00 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42  oded */.  int nB
25d10 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20  yte,            
25d20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e    /* Maximum len
25d30 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62  gth of zSql in b
25d40 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74  ytes. */.  sqlit
25d50 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74  e3_stmt **ppStmt
25d60 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65  ,  /* OUT: State
25d70 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  ment handle */. 
25d80 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a   const char **pz
25d90 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a  Tail     /* OUT:
25da0 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73   Pointer to unus
25db0 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53  ed portion of zS
25dc0 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c  ql */.);.int sql
25dd0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 0a  ite3_prepare16(.
25de0 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
25df0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
25e00 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a  abase handle */.
25e10 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53    const void *zS
25e20 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c  ql,       /* SQL
25e30 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d   statement, UTF-
25e40 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20  16 encoded */.  
25e50 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20  int nByte,      
25e60 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d          /* Maxim
25e70 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71  um length of zSq
25e80 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20  l in bytes. */. 
25e90 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a   sqlite3_stmt **
25ea0 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a  ppStmt,  /* OUT:
25eb0 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c   Statement handl
25ec0 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  e */.  const voi
25ed0 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f  d **pzTail     /
25ee0 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74  * OUT: Pointer t
25ef0 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e  o unused portion
25f00 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69   of zSql */.);.i
25f10 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nt sqlite3_prepa
25f20 72 65 31 36 5f 76 32 28 0a 20 20 73 71 6c 69 74  re16_v2(.  sqlit
25f30 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
25f40 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68     /* Database h
25f50 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
25f60 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20   void *zSql,    
25f70 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d     /* SQL statem
25f80 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f  ent, UTF-16 enco
25f90 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79  ded */.  int nBy
25fa0 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  te,             
25fb0 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67   /* Maximum leng
25fc0 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79  th of zSql in by
25fd0 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65  tes. */.  sqlite
25fe0 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c  3_stmt **ppStmt,
25ff0 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d    /* OUT: Statem
26000 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ent handle */.  
26010 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54  const void **pzT
26020 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20  ail     /* OUT: 
26030 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65  Pointer to unuse
26040 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71  d portion of zSq
26050 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  l */.);../*.** C
26060 41 50 49 33 52 45 46 3a 20 52 65 74 72 69 65 76  API3REF: Retriev
26070 69 6e 67 20 53 74 61 74 65 6d 65 6e 74 20 53 51  ing Statement SQ
26080 4c 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e  L.**.** ^This in
26090 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75  terface can be u
260a0 73 65 64 20 74 6f 20 72 65 74 72 69 65 76 65 20  sed to retrieve 
260b0 61 20 73 61 76 65 64 20 63 6f 70 79 20 6f 66 20  a saved copy of 
260c0 74 68 65 20 6f 72 69 67 69 6e 61 6c 0a 2a 2a 20  the original.** 
260d0 53 51 4c 20 74 65 78 74 20 75 73 65 64 20 74 6f  SQL text used to
260e0 20 63 72 65 61 74 65 20 61 20 5b 70 72 65 70 61   create a [prepa
260f0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69  red statement] i
26100 66 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74  f that statement
26110 20 77 61 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64   was.** compiled
26120 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73   using either [s
26130 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
26140 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  2()] or [sqlite3
26150 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
26160 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20  ..*/.const char 
26170 2a 73 71 6c 69 74 65 33 5f 73 71 6c 28 73 71 6c  *sqlite3_sql(sql
26180 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
26190 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
261a0 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66  EF: Determine If
261b0 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e   An SQL Statemen
261c0 74 20 57 72 69 74 65 73 20 54 68 65 20 44 61 74  t Writes The Dat
261d0 61 62 61 73 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  abase.**.** ^The
261e0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65   sqlite3_stmt_re
261f0 61 64 6f 6e 6c 79 28 58 29 20 69 6e 74 65 72 66  adonly(X) interf
26200 61 63 65 20 72 65 74 75 72 6e 73 20 74 72 75 65  ace returns true
26210 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 0a 2a   (non-zero) if.*
26220 2a 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68  * and only if th
26230 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
26240 65 6d 65 6e 74 5d 20 58 20 6d 61 6b 65 73 20 6e  ement] X makes n
26250 6f 20 64 69 72 65 63 74 20 63 68 61 6e 67 65 73  o direct changes
26260 20 74 6f 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65   to.** the conte
26270 6e 74 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  nt of the databa
26280 73 65 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 4e  se file..**.** N
26290 6f 74 65 20 74 68 61 74 20 5b 61 70 70 6c 69 63  ote that [applic
262a0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
262b0 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 6f 72 0a  L functions] or.
262c0 2a 2a 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c  ** [virtual tabl
262d0 65 73 5d 20 6d 69 67 68 74 20 63 68 61 6e 67 65  es] might change
262e0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 6e   the database in
262f0 64 69 72 65 63 74 6c 79 20 61 73 20 61 20 73 69  directly as a si
26300 64 65 20 65 66 66 65 63 74 2e 20 20 0a 2a 2a 20  de effect.  .** 
26310 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69  ^(For example, i
26320 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  f an application
26330 20 64 65 66 69 6e 65 73 20 61 20 66 75 6e 63 74   defines a funct
26340 69 6f 6e 20 22 65 76 61 6c 28 29 22 20 74 68 61  ion "eval()" tha
26350 74 20 0a 2a 2a 20 63 61 6c 6c 73 20 5b 73 71 6c  t .** calls [sql
26360 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 74 68  ite3_exec()], th
26370 65 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  en the following
26380 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 77   SQL statement w
26390 6f 75 6c 64 0a 2a 2a 20 63 68 61 6e 67 65 20 74  ould.** change t
263a0 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
263b0 20 74 68 72 6f 75 67 68 20 73 69 64 65 2d 65 66   through side-ef
263c0 66 65 63 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  fects:.**.** <bl
263d0 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
263e0 2a 20 20 20 20 53 45 4c 45 43 54 20 65 76 61 6c  *    SELECT eval
263f0 28 27 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 31  ('DELETE FROM t1
26400 27 29 20 46 52 4f 4d 20 74 32 3b 0a 2a 2a 20 3c  ') FROM t2;.** <
26410 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
26420 65 3e 0a 2a 2a 0a 2a 2a 20 42 75 74 20 62 65 63  e>.**.** But bec
26430 61 75 73 65 20 74 68 65 20 5b 53 45 4c 45 43 54  ause the [SELECT
26440 5d 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73  ] statement does
26450 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20   not change the 
26460 64 61 74 61 62 61 73 65 20 66 69 6c 65 0a 2a 2a  database file.**
26470 20 64 69 72 65 63 74 6c 79 2c 20 73 71 6c 69 74   directly, sqlit
26480 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79  e3_stmt_readonly
26490 28 29 20 77 6f 75 6c 64 20 73 74 69 6c 6c 20 72  () would still r
264a0 65 74 75 72 6e 20 74 72 75 65 2e 29 5e 0a 2a 2a  eturn true.)^.**
264b0 0a 2a 2a 20 5e 54 72 61 6e 73 61 63 74 69 6f 6e  .** ^Transaction
264c0 20 63 6f 6e 74 72 6f 6c 20 73 74 61 74 65 6d 65   control stateme
264d0 6e 74 73 20 73 75 63 68 20 61 73 20 5b 42 45 47  nts such as [BEG
264e0 49 4e 5d 2c 20 5b 43 4f 4d 4d 49 54 5d 2c 20 5b  IN], [COMMIT], [
264f0 52 4f 4c 4c 42 41 43 4b 5d 2c 0a 2a 2a 20 5b 53  ROLLBACK],.** [S
26500 41 56 45 50 4f 49 4e 54 5d 2c 20 61 6e 64 20 5b  AVEPOINT], and [
26510 52 45 4c 45 41 53 45 5d 20 63 61 75 73 65 20 73  RELEASE] cause s
26520 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64  qlite3_stmt_read
26530 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74 75 72 6e  only() to return
26540 20 74 72 75 65 2c 0a 2a 2a 20 73 69 6e 63 65 20   true,.** since 
26550 74 68 65 20 73 74 61 74 65 6d 65 6e 74 73 20 74  the statements t
26560 68 65 6d 73 65 6c 76 65 73 20 64 6f 20 6e 6f 74  hemselves do not
26570 20 61 63 74 75 61 6c 6c 79 20 6d 6f 64 69 66 79   actually modify
26580 20 74 68 65 20 64 61 74 61 62 61 73 65 20 62 75   the database bu
26590 74 0a 2a 2a 20 72 61 74 68 65 72 20 74 68 65 79  t.** rather they
265a0 20 63 6f 6e 74 72 6f 6c 20 74 68 65 20 74 69 6d   control the tim
265b0 69 6e 67 20 6f 66 20 77 68 65 6e 20 6f 74 68 65  ing of when othe
265c0 72 20 73 74 61 74 65 6d 65 6e 74 73 20 6d 6f 64  r statements mod
265d0 69 66 79 20 74 68 65 20 0a 2a 2a 20 64 61 74 61  ify the .** data
265e0 62 61 73 65 2e 20 20 5e 54 68 65 20 5b 41 54 54  base.  ^The [ATT
265f0 41 43 48 5d 20 61 6e 64 20 5b 44 45 54 41 43 48  ACH] and [DETACH
26600 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 61 6c 73  ] statements als
26610 6f 20 63 61 75 73 65 0a 2a 2a 20 73 71 6c 69 74  o cause.** sqlit
26620 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79  e3_stmt_readonly
26630 28 29 20 74 6f 20 72 65 74 75 72 6e 20 74 72 75  () to return tru
26640 65 20 73 69 6e 63 65 2c 20 77 68 69 6c 65 20 74  e since, while t
26650 68 6f 73 65 20 73 74 61 74 65 6d 65 6e 74 73 0a  hose statements.
26660 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 63 6f  ** change the co
26670 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 66 20 61  nfiguration of a
26680 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
26690 74 69 6f 6e 2c 20 74 68 65 79 20 64 6f 20 6e 6f  tion, they do no
266a0 74 20 6d 61 6b 65 20 0a 2a 2a 20 63 68 61 6e 67  t make .** chang
266b0 65 73 20 74 6f 20 74 68 65 20 63 6f 6e 74 65 6e  es to the conten
266c0 74 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  t of the databas
266d0 65 20 66 69 6c 65 73 20 6f 6e 20 64 69 73 6b 2e  e files on disk.
266e0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
266f0 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 73 71  stmt_readonly(sq
26700 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
26710 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
26720 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49  REF: Determine I
26730 66 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61  f A Prepared Sta
26740 74 65 6d 65 6e 74 20 48 61 73 20 42 65 65 6e 20  tement Has Been 
26750 52 65 73 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  Reset.**.** ^The
26760 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75   sqlite3_stmt_bu
26770 73 79 28 53 29 20 69 6e 74 65 72 66 61 63 65 20  sy(S) interface 
26780 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 6e 6f  returns true (no
26790 6e 2d 7a 65 72 6f 29 20 69 66 20 74 68 65 0a 2a  n-zero) if the.*
267a0 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
267b0 65 6d 65 6e 74 5d 20 53 20 68 61 73 20 62 65 65  ement] S has bee
267c0 6e 20 73 74 65 70 70 65 64 20 61 74 20 6c 65 61  n stepped at lea
267d0 73 74 20 6f 6e 63 65 20 75 73 69 6e 67 20 0a 2a  st once using .*
267e0 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  * [sqlite3_step(
267f0 53 29 5d 20 62 75 74 20 68 61 73 20 6e 6f 74 20  S)] but has not 
26800 72 75 6e 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f  run to completio
26810 6e 20 61 6e 64 2f 6f 72 20 68 61 73 20 6e 6f 74  n and/or has not
26820 20 0a 2a 2a 20 62 65 65 6e 20 72 65 73 65 74 20   .** been reset 
26830 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72  using [sqlite3_r
26840 65 73 65 74 28 53 29 5d 2e 20 20 5e 54 68 65 20  eset(S)].  ^The 
26850 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73  sqlite3_stmt_bus
26860 79 28 53 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  y(S).** interfac
26870 65 20 72 65 74 75 72 6e 73 20 66 61 6c 73 65 20  e returns false 
26880 69 66 20 53 20 69 73 20 61 20 4e 55 4c 4c 20 70  if S is a NULL p
26890 6f 69 6e 74 65 72 2e 20 20 49 66 20 53 20 69 73  ointer.  If S is
268a0 20 6e 6f 74 20 61 20 0a 2a 2a 20 4e 55 4c 4c 20   not a .** NULL 
268b0 70 6f 69 6e 74 65 72 20 61 6e 64 20 69 73 20 6e  pointer and is n
268c0 6f 74 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ot a pointer to 
268d0 61 20 76 61 6c 69 64 20 5b 70 72 65 70 61 72 65  a valid [prepare
268e0 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20  d statement].** 
268f0 6f 62 6a 65 63 74 2c 20 74 68 65 6e 20 74 68 65  object, then the
26900 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64   behavior is und
26910 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61  efined and proba
26920 62 6c 79 20 75 6e 64 65 73 69 72 61 62 6c 65 2e  bly undesirable.
26930 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65  .**.** This inte
26940 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65  rface can be use
26950 64 20 69 6e 20 63 6f 6d 62 69 6e 61 74 69 6f 6e  d in combination
26960 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73   [sqlite3_next_s
26970 74 6d 74 28 29 5d 0a 2a 2a 20 74 6f 20 6c 6f 63  tmt()].** to loc
26980 61 74 65 20 61 6c 6c 20 70 72 65 70 61 72 65 64  ate all prepared
26990 20 73 74 61 74 65 6d 65 6e 74 73 20 61 73 73 6f   statements asso
269a0 63 69 61 74 65 64 20 77 69 74 68 20 61 20 64 61  ciated with a da
269b0 74 61 62 61 73 65 20 0a 2a 2a 20 63 6f 6e 6e 65  tabase .** conne
269c0 63 74 69 6f 6e 20 74 68 61 74 20 61 72 65 20 69  ction that are i
269d0 6e 20 6e 65 65 64 20 6f 66 20 62 65 69 6e 67 20  n need of being 
269e0 72 65 73 65 74 2e 20 20 54 68 69 73 20 63 61 6e  reset.  This can
269f0 20 62 65 20 75 73 65 64 2c 0a 2a 2a 20 66 6f 72   be used,.** for
26a00 20 65 78 61 6d 70 6c 65 2c 20 69 6e 20 64 69 61   example, in dia
26a10 67 6e 6f 73 74 69 63 20 72 6f 75 74 69 6e 65 73  gnostic routines
26a20 20 74 6f 20 73 65 61 72 63 68 20 66 6f 72 20 70   to search for p
26a30 72 65 70 61 72 65 64 20 0a 2a 2a 20 73 74 61 74  repared .** stat
26a40 65 6d 65 6e 74 73 20 74 68 61 74 20 61 72 65 20  ements that are 
26a50 68 6f 6c 64 69 6e 67 20 61 20 74 72 61 6e 73 61  holding a transa
26a60 63 74 69 6f 6e 20 6f 70 65 6e 2e 0a 2a 2f 0a 69  ction open..*/.i
26a70 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  nt sqlite3_stmt_
26a80 62 75 73 79 28 73 71 6c 69 74 65 33 5f 73 74 6d  busy(sqlite3_stm
26a90 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
26aa0 33 52 45 46 3a 20 44 79 6e 61 6d 69 63 61 6c 6c  3REF: Dynamicall
26ab0 79 20 54 79 70 65 64 20 56 61 6c 75 65 20 4f 62  y Typed Value Ob
26ac0 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ject.** KEYWORDS
26ad0 3a 20 7b 70 72 6f 74 65 63 74 65 64 20 73 71 6c  : {protected sql
26ae0 69 74 65 33 5f 76 61 6c 75 65 7d 20 7b 75 6e 70  ite3_value} {unp
26af0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
26b00 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51  _value}.**.** SQ
26b10 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 73 71  Lite uses the sq
26b20 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
26b30 63 74 20 74 6f 20 72 65 70 72 65 73 65 6e 74 20  ct to represent 
26b40 61 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68  all values.** th
26b50 61 74 20 63 61 6e 20 62 65 20 73 74 6f 72 65 64  at can be stored
26b60 20 69 6e 20 61 20 64 61 74 61 62 61 73 65 20 74   in a database t
26b70 61 62 6c 65 2e 20 53 51 4c 69 74 65 20 75 73 65  able. SQLite use
26b80 73 20 64 79 6e 61 6d 69 63 20 74 79 70 69 6e 67  s dynamic typing
26b90 0a 2a 2a 20 66 6f 72 20 74 68 65 20 76 61 6c 75  .** for the valu
26ba0 65 73 20 69 74 20 73 74 6f 72 65 73 2e 20 20 5e  es it stores.  ^
26bb0 56 61 6c 75 65 73 20 73 74 6f 72 65 64 20 69 6e  Values stored in
26bc0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
26bd0 62 6a 65 63 74 73 0a 2a 2a 20 63 61 6e 20 62 65  bjects.** can be
26be0 20 69 6e 74 65 67 65 72 73 2c 20 66 6c 6f 61 74   integers, float
26bf0 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 73  ing point values
26c00 2c 20 73 74 72 69 6e 67 73 2c 20 42 4c 4f 42 73  , strings, BLOBs
26c10 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  , or NULL..**.**
26c20 20 41 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75   An sqlite3_valu
26c30 65 20 6f 62 6a 65 63 74 20 6d 61 79 20 62 65 20  e object may be 
26c40 65 69 74 68 65 72 20 22 70 72 6f 74 65 63 74 65  either "protecte
26c50 64 22 20 6f 72 20 22 75 6e 70 72 6f 74 65 63 74  d" or "unprotect
26c60 65 64 22 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74  ed"..** Some int
26c70 65 72 66 61 63 65 73 20 72 65 71 75 69 72 65 20  erfaces require 
26c80 61 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  a protected sqli
26c90 74 65 33 5f 76 61 6c 75 65 2e 20 20 4f 74 68 65  te3_value.  Othe
26ca0 72 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  r interfaces.** 
26cb0 77 69 6c 6c 20 61 63 63 65 70 74 20 65 69 74 68  will accept eith
26cc0 65 72 20 61 20 70 72 6f 74 65 63 74 65 64 20 6f  er a protected o
26cd0 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64  r an unprotected
26ce0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a   sqlite3_value..
26cf0 2a 2a 20 45 76 65 72 79 20 69 6e 74 65 72 66 61  ** Every interfa
26d00 63 65 20 74 68 61 74 20 61 63 63 65 70 74 73 20  ce that accepts 
26d10 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 61 72  sqlite3_value ar
26d20 67 75 6d 65 6e 74 73 20 73 70 65 63 69 66 69 65  guments specifie
26d30 73 0a 2a 2a 20 77 68 65 74 68 65 72 20 6f 72 20  s.** whether or 
26d40 6e 6f 74 20 69 74 20 72 65 71 75 69 72 65 73 20  not it requires 
26d50 61 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  a protected sqli
26d60 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a  te3_value..**.**
26d70 20 54 68 65 20 74 65 72 6d 73 20 22 70 72 6f 74   The terms "prot
26d80 65 63 74 65 64 22 20 61 6e 64 20 22 75 6e 70 72  ected" and "unpr
26d90 6f 74 65 63 74 65 64 22 20 72 65 66 65 72 20 74  otected" refer t
26da0 6f 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  o whether or not
26db0 0a 2a 2a 20 61 20 6d 75 74 65 78 20 69 73 20 68  .** a mutex is h
26dc0 65 6c 64 2e 20 20 41 6e 20 69 6e 74 65 72 6e 61  eld.  An interna
26dd0 6c 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20  l mutex is held 
26de0 66 6f 72 20 61 20 70 72 6f 74 65 63 74 65 64 0a  for a protected.
26df0 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ** sqlite3_value
26e00 20 6f 62 6a 65 63 74 20 62 75 74 20 6e 6f 20 6d   object but no m
26e10 75 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72  utex is held for
26e20 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 0a   an unprotected.
26e30 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ** sqlite3_value
26e40 20 6f 62 6a 65 63 74 2e 20 20 49 66 20 53 51 4c   object.  If SQL
26e50 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
26e60 74 6f 20 62 65 20 73 69 6e 67 6c 65 2d 74 68 72  to be single-thr
26e70 65 61 64 65 64 0a 2a 2a 20 28 77 69 74 68 20 5b  eaded.** (with [
26e80 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
26e90 45 3d 30 5d 20 61 6e 64 20 77 69 74 68 20 5b 73  E=0] and with [s
26ea0 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66  qlite3_threadsaf
26eb0 65 28 29 5d 20 72 65 74 75 72 6e 69 6e 67 20 30  e()] returning 0
26ec0 29 0a 2a 2a 20 6f 72 20 69 66 20 53 51 4c 69 74  ).** or if SQLit
26ed0 65 20 69 73 20 72 75 6e 20 69 6e 20 6f 6e 65 20  e is run in one 
26ee0 6f 66 20 72 65 64 75 63 65 64 20 6d 75 74 65 78  of reduced mutex
26ef0 20 6d 6f 64 65 73 20 0a 2a 2a 20 5b 53 51 4c 49   modes .** [SQLI
26f00 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
26f10 54 48 52 45 41 44 5d 20 6f 72 20 5b 53 51 4c 49  THREAD] or [SQLI
26f20 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54  TE_CONFIG_MULTIT
26f30 48 52 45 41 44 5d 0a 2a 2a 20 74 68 65 6e 20 74  HREAD].** then t
26f40 68 65 72 65 20 69 73 20 6e 6f 20 64 69 73 74 69  here is no disti
26f50 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 70  nction between p
26f60 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70  rotected and unp
26f70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69  rotected.** sqli
26f80 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
26f90 73 20 61 6e 64 20 74 68 65 79 20 63 61 6e 20 62  s and they can b
26fa0 65 20 75 73 65 64 20 69 6e 74 65 72 63 68 61 6e  e used interchan
26fb0 67 65 61 62 6c 79 2e 20 20 48 6f 77 65 76 65 72  geably.  However
26fc0 2c 0a 2a 2a 20 66 6f 72 20 6d 61 78 69 6d 75 6d  ,.** for maximum
26fd0 20 63 6f 64 65 20 70 6f 72 74 61 62 69 6c 69 74   code portabilit
26fe0 79 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e  y it is recommen
26ff0 64 65 64 20 74 68 61 74 20 61 70 70 6c 69 63 61  ded that applica
27000 74 69 6f 6e 73 0a 2a 2a 20 73 74 69 6c 6c 20 6d  tions.** still m
27010 61 6b 65 20 74 68 65 20 64 69 73 74 69 6e 63 74  ake the distinct
27020 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74  ion between prot
27030 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74  ected and unprot
27040 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33  ected.** sqlite3
27050 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 65  _value objects e
27060 76 65 6e 20 77 68 65 6e 20 6e 6f 74 20 73 74 72  ven when not str
27070 69 63 74 6c 79 20 72 65 71 75 69 72 65 64 2e 0a  ictly required..
27080 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
27090 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
270a0 20 74 68 61 74 20 61 72 65 20 70 61 73 73 65 64   that are passed
270b0 20 61 73 20 70 61 72 61 6d 65 74 65 72 73 20 69   as parameters i
270c0 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65  nto the.** imple
270d0 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 61 70  mentation of [ap
270e0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
270f0 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d  d SQL functions]
27100 20 61 72 65 20 70 72 6f 74 65 63 74 65 64 2e 0a   are protected..
27110 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
27120 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 72 65 74  value object ret
27130 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c  urned by.** [sql
27140 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75  ite3_column_valu
27150 65 28 29 5d 20 69 73 20 75 6e 70 72 6f 74 65 63  e()] is unprotec
27160 74 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74 65 63  ted..** Unprotec
27170 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
27180 65 20 6f 62 6a 65 63 74 73 20 6d 61 79 20 6f 6e  e objects may on
27190 6c 79 20 62 65 20 75 73 65 64 20 77 69 74 68 0a  ly be used with.
271a0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  ** [sqlite3_resu
271b0 6c 74 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20  lt_value()] and 
271c0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61  [sqlite3_bind_va
271d0 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b  lue()]..** The [
271e0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c  sqlite3_value_bl
271f0 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 76 61 6c  ob | sqlite3_val
27200 75 65 5f 74 79 70 65 28 29 5d 20 66 61 6d 69 6c  ue_type()] famil
27210 79 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63  y of.** interfac
27220 65 73 20 72 65 71 75 69 72 65 20 70 72 6f 74 65  es require prote
27230 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
27240 75 65 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74  ue objects..*/.t
27250 79 70 65 64 65 66 20 73 74 72 75 63 74 20 4d 65  ypedef struct Me
27260 6d 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 3b  m sqlite3_value;
27270 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
27280 3a 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 43  : SQL Function C
27290 6f 6e 74 65 78 74 20 4f 62 6a 65 63 74 0a 2a 2a  ontext Object.**
272a0 0a 2a 2a 20 54 68 65 20 63 6f 6e 74 65 78 74 20  .** The context 
272b0 69 6e 20 77 68 69 63 68 20 61 6e 20 53 51 4c 20  in which an SQL 
272c0 66 75 6e 63 74 69 6f 6e 20 65 78 65 63 75 74 65  function execute
272d0 73 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 61  s is stored in a
272e0 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e  n.** sqlite3_con
272f0 74 65 78 74 20 6f 62 6a 65 63 74 2e 20 20 5e 41  text object.  ^A
27300 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 73   pointer to an s
27310 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f  qlite3_context o
27320 62 6a 65 63 74 0a 2a 2a 20 69 73 20 61 6c 77 61  bject.** is alwa
27330 79 73 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  ys first paramet
27340 65 72 20 74 6f 20 5b 61 70 70 6c 69 63 61 74 69  er to [applicati
27350 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
27360 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68  unctions]..** Th
27370 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
27380 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
27390 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  on implementatio
273a0 6e 20 77 69 6c 6c 20 70 61 73 73 20 74 68 69 73  n will pass this
273b0 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 68 72 6f  .** pointer thro
273c0 75 67 68 20 69 6e 74 6f 20 63 61 6c 6c 73 20 74  ugh into calls t
273d0 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  o [sqlite3_resul
273e0 74 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f  t_int | sqlite3_
273f0 72 65 73 75 6c 74 28 29 5d 2c 0a 2a 2a 20 5b 73  result()],.** [s
27400 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
27410 5f 63 6f 6e 74 65 78 74 28 29 5d 2c 20 5b 73 71  _context()], [sq
27420 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28  lite3_user_data(
27430 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
27440 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c  context_db_handl
27450 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 67  e()], [sqlite3_g
27460 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2c 0a 2a  et_auxdata()],.*
27470 2a 20 61 6e 64 2f 6f 72 20 5b 73 71 6c 69 74 65  * and/or [sqlite
27480 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 5d  3_set_auxdata()]
27490 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
274a0 75 63 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74  uct sqlite3_cont
274b0 65 78 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ext sqlite3_cont
274c0 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ext;../*.** CAPI
274d0 33 52 45 46 3a 20 42 69 6e 64 69 6e 67 20 56 61  3REF: Binding Va
274e0 6c 75 65 73 20 54 6f 20 50 72 65 70 61 72 65 64  lues To Prepared
274f0 20 53 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 4b   Statements.** K
27500 45 59 57 4f 52 44 53 3a 20 7b 68 6f 73 74 20 70  EYWORDS: {host p
27510 61 72 61 6d 65 74 65 72 7d 20 7b 68 6f 73 74 20  arameter} {host 
27520 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 68 6f 73  parameters} {hos
27530 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65  t parameter name
27540 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  }.** KEYWORDS: {
27550 53 51 4c 20 70 61 72 61 6d 65 74 65 72 7d 20 7b  SQL parameter} {
27560 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 7d 20  SQL parameters} 
27570 7b 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69  {parameter bindi
27580 6e 67 7d 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74  ng}.**.** ^(In t
27590 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
275a0 20 74 65 78 74 20 69 6e 70 75 74 20 74 6f 20 5b   text input to [
275b0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
275c0 76 32 28 29 5d 20 61 6e 64 20 69 74 73 20 76 61  v2()] and its va
275d0 72 69 61 6e 74 73 2c 0a 2a 2a 20 6c 69 74 65 72  riants,.** liter
275e0 61 6c 73 20 6d 61 79 20 62 65 20 72 65 70 6c 61  als may be repla
275f0 63 65 64 20 62 79 20 61 20 5b 70 61 72 61 6d 65  ced by a [parame
27600 74 65 72 5d 20 74 68 61 74 20 6d 61 74 63 68 65  ter] that matche
27610 73 20 6f 6e 65 20 6f 66 20 66 6f 6c 6c 6f 77 69  s one of followi
27620 6e 67 0a 2a 2a 20 74 65 6d 70 6c 61 74 65 73 3a  ng.** templates:
27630 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
27640 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20  li>  ?.** <li>  
27650 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56  ?NNN.** <li>  :V
27660 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 40 56 56 56  VV.** <li>  @VVV
27670 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56 56 56 0a 2a  .** <li>  $VVV.*
27680 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e  * </ul>.**.** In
27690 20 74 68 65 20 74 65 6d 70 6c 61 74 65 73 20 61   the templates a
276a0 62 6f 76 65 2c 20 4e 4e 4e 20 72 65 70 72 65 73  bove, NNN repres
276b0 65 6e 74 73 20 61 6e 20 69 6e 74 65 67 65 72 20  ents an integer 
276c0 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20 61 6e 64 20  literal,.** and 
276d0 56 56 56 20 72 65 70 72 65 73 65 6e 74 73 20 61  VVV represents a
276e0 6e 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 69  n alphanumeric i
276f0 64 65 6e 74 69 66 69 65 72 2e 29 5e 20 20 5e 54  dentifier.)^  ^T
27700 68 65 20 76 61 6c 75 65 73 20 6f 66 20 74 68 65  he values of the
27710 73 65 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73  se.** parameters
27720 20 28 61 6c 73 6f 20 63 61 6c 6c 65 64 20 22 68   (also called "h
27730 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61  ost parameter na
27740 6d 65 73 22 20 6f 72 20 22 53 51 4c 20 70 61 72  mes" or "SQL par
27750 61 6d 65 74 65 72 73 22 29 0a 2a 2a 20 63 61 6e  ameters").** can
27760 20 62 65 20 73 65 74 20 75 73 69 6e 67 20 74 68   be set using th
27770 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
27780 28 29 20 72 6f 75 74 69 6e 65 73 20 64 65 66 69  () routines defi
27790 6e 65 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20  ned here..**.** 
277a0 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d  ^The first argum
277b0 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ent to the sqlit
277c0 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74  e3_bind_*() rout
277d0 69 6e 65 73 20 69 73 20 61 6c 77 61 79 73 0a 2a  ines is always.*
277e0 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  * a pointer to t
277f0 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74  he [sqlite3_stmt
27800 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65  ] object returne
27810 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74  d from.** [sqlit
27820 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
27830 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73   or its variants
27840 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63  ..**.** ^The sec
27850 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ond argument is 
27860 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65  the index of the
27870 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 74   SQL parameter t
27880 6f 20 62 65 20 73 65 74 2e 0a 2a 2a 20 5e 54 68  o be set..** ^Th
27890 65 20 6c 65 66 74 6d 6f 73 74 20 53 51 4c 20 70  e leftmost SQL p
278a0 61 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20  arameter has an 
278b0 69 6e 64 65 78 20 6f 66 20 31 2e 20 20 5e 57 68  index of 1.  ^Wh
278c0 65 6e 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65  en the same name
278d0 64 0a 2a 2a 20 53 51 4c 20 70 61 72 61 6d 65 74  d.** SQL paramet
278e0 65 72 20 69 73 20 75 73 65 64 20 6d 6f 72 65 20  er is used more 
278f0 74 68 61 6e 20 6f 6e 63 65 2c 20 73 65 63 6f 6e  than once, secon
27900 64 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74  d and subsequent
27910 0a 2a 2a 20 6f 63 63 75 72 72 65 6e 63 65 73 20  .** occurrences 
27920 68 61 76 65 20 74 68 65 20 73 61 6d 65 20 69 6e  have the same in
27930 64 65 78 20 61 73 20 74 68 65 20 66 69 72 73 74  dex as the first
27940 20 6f 63 63 75 72 72 65 6e 63 65 2e 0a 2a 2a 20   occurrence..** 
27950 5e 54 68 65 20 69 6e 64 65 78 20 66 6f 72 20 6e  ^The index for n
27960 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72 73 20  amed parameters 
27970 63 61 6e 20 62 65 20 6c 6f 6f 6b 65 64 20 75 70  can be looked up
27980 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73   using the.** [s
27990 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
279a0 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 20 41  meter_index()] A
279b0 50 49 20 69 66 20 64 65 73 69 72 65 64 2e 20 20  PI if desired.  
279c0 5e 54 68 65 20 69 6e 64 65 78 0a 2a 2a 20 66 6f  ^The index.** fo
279d0 72 20 22 3f 4e 4e 4e 22 20 70 61 72 61 6d 65 74  r "?NNN" paramet
279e0 65 72 73 20 69 73 20 74 68 65 20 76 61 6c 75 65  ers is the value
279f0 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 5e 54 68 65   of NNN..** ^The
27a00 20 4e 4e 4e 20 76 61 6c 75 65 20 6d 75 73 74 20   NNN value must 
27a10 62 65 20 62 65 74 77 65 65 6e 20 31 20 61 6e 64  be between 1 and
27a20 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 69   the [sqlite3_li
27a30 6d 69 74 28 29 5d 0a 2a 2a 20 70 61 72 61 6d 65  mit()].** parame
27a40 74 65 72 20 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ter [SQLITE_LIMI
27a50 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45  T_VARIABLE_NUMBE
27a60 52 5d 20 28 64 65 66 61 75 6c 74 20 76 61 6c 75  R] (default valu
27a70 65 3a 20 39 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e  e: 999)..**.** ^
27a80 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  The third argume
27a90 6e 74 20 69 73 20 74 68 65 20 76 61 6c 75 65 20  nt is the value 
27aa0 74 6f 20 62 69 6e 64 20 74 6f 20 74 68 65 20 70  to bind to the p
27ab0 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 66  arameter..** ^If
27ac0 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   the third param
27ad0 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
27ae0 62 69 6e 64 5f 74 65 78 74 28 29 20 6f 72 20 73  bind_text() or s
27af0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
27b00 31 36 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74  16().** or sqlit
27b10 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 20 69  e3_bind_blob() i
27b20 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
27b30 20 74 68 65 6e 20 74 68 65 20 66 6f 75 72 74 68   then the fourth
27b40 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 73   parameter.** is
27b50 20 69 67 6e 6f 72 65 64 20 61 6e 64 20 74 68 65   ignored and the
27b60 20 65 6e 64 20 72 65 73 75 6c 74 20 69 73 20 74   end result is t
27b70 68 65 20 73 61 6d 65 20 61 73 20 73 71 6c 69 74  he same as sqlit
27b80 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 29 2e 0a  e3_bind_null()..
27b90 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 6f 73 65  **.** ^(In those
27ba0 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 68   routines that h
27bb0 61 76 65 20 61 20 66 6f 75 72 74 68 20 61 72 67  ave a fourth arg
27bc0 75 6d 65 6e 74 2c 20 69 74 73 20 76 61 6c 75 65  ument, its value
27bd0 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65   is the.** numbe
27be0 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
27bf0 65 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 6f  e parameter.  To
27c00 20 62 65 20 63 6c 65 61 72 3a 20 74 68 65 20 76   be clear: the v
27c10 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e  alue is the.** n
27c20 75 6d 62 65 72 20 6f 66 20 3c 75 3e 62 79 74 65  umber of <u>byte
27c30 73 3c 2f 75 3e 20 69 6e 20 74 68 65 20 76 61 6c  s</u> in the val
27c40 75 65 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62  ue, not the numb
27c50 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73  er of characters
27c60 2e 29 5e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66  .)^.** ^If the f
27c70 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
27c80 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  to sqlite3_bind_
27c90 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65  text() or sqlite
27ca0 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 0a  3_bind_text16().
27cb0 2a 2a 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20  ** is negative, 
27cc0 74 68 65 6e 20 74 68 65 20 6c 65 6e 67 74 68 20  then the length 
27cd0 6f 66 20 74 68 65 20 73 74 72 69 6e 67 20 69 73  of the string is
27ce0 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  .** the number o
27cf0 66 20 62 79 74 65 73 20 75 70 20 74 6f 20 74 68  f bytes up to th
27d00 65 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72  e first zero ter
27d10 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 20 49 66 20 74  minator..** If t
27d20 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
27d30 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62  ter to sqlite3_b
27d40 69 6e 64 5f 62 6c 6f 62 28 29 20 69 73 20 6e 65  ind_blob() is ne
27d50 67 61 74 69 76 65 2c 20 74 68 65 6e 0a 2a 2a 20  gative, then.** 
27d60 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20  the behavior is 
27d70 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66  undefined..** If
27d80 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20   a non-negative 
27d90 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
27da0 20 69 73 20 70 72 6f 76 69 64 65 64 20 74 6f 20   is provided to 
27db0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
27dc0 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65  t().** or sqlite
27dd0 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20  3_bind_text16() 
27de0 74 68 65 6e 20 74 68 61 74 20 70 61 72 61 6d 65  then that parame
27df0 74 65 72 20 6d 75 73 74 20 62 65 20 74 68 65 20  ter must be the 
27e00 62 79 74 65 20 6f 66 66 73 65 74 0a 2a 2a 20 77  byte offset.** w
27e10 68 65 72 65 20 74 68 65 20 4e 55 4c 20 74 65 72  here the NUL ter
27e20 6d 69 6e 61 74 6f 72 20 77 6f 75 6c 64 20 6f 63  minator would oc
27e30 63 75 72 20 61 73 73 75 6d 69 6e 67 20 74 68 65  cur assuming the
27e40 20 73 74 72 69 6e 67 20 77 65 72 65 20 4e 55 4c   string were NUL
27e50 0a 2a 2a 20 74 65 72 6d 69 6e 61 74 65 64 2e 20  .** terminated. 
27e60 20 49 66 20 61 6e 79 20 4e 55 4c 20 63 68 61 72   If any NUL char
27e70 61 63 74 65 72 73 20 6f 63 63 75 72 20 61 74 20  acters occur at 
27e80 62 79 74 65 20 6f 66 66 73 65 74 73 20 6c 65 73  byte offsets les
27e90 73 20 74 68 61 6e 20 0a 2a 2a 20 74 68 65 20 76  s than .** the v
27ea0 61 6c 75 65 20 6f 66 20 74 68 65 20 66 6f 75 72  alue of the four
27eb0 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 68 65  th parameter the
27ec0 6e 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20  n the resulting 
27ed0 73 74 72 69 6e 67 20 76 61 6c 75 65 20 77 69 6c  string value wil
27ee0 6c 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 65 6d 62  l.** contain emb
27ef0 65 64 64 65 64 20 4e 55 4c 73 2e 20 20 54 68 65  edded NULs.  The
27f00 20 72 65 73 75 6c 74 20 6f 66 20 65 78 70 72 65   result of expre
27f10 73 73 69 6f 6e 73 20 69 6e 76 6f 6c 76 69 6e 67  ssions involving
27f20 20 73 74 72 69 6e 67 73 0a 2a 2a 20 77 69 74 68   strings.** with
27f30 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 20 69   embedded NULs i
27f40 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  s undefined..**.
27f50 2a 2a 20 5e 54 68 65 20 66 69 66 74 68 20 61 72  ** ^The fifth ar
27f60 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
27f70 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 2c 20 73  3_bind_blob(), s
27f80 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
27f90 28 29 2c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74  (), and.** sqlit
27fa0 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29  e3_bind_text16()
27fb0 20 69 73 20 61 20 64 65 73 74 72 75 63 74 6f 72   is a destructor
27fc0 20 75 73 65 64 20 74 6f 20 64 69 73 70 6f 73 65   used to dispose
27fd0 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 0a   of the BLOB or.
27fe0 2a 2a 20 73 74 72 69 6e 67 20 61 66 74 65 72 20  ** string after 
27ff0 53 51 4c 69 74 65 20 68 61 73 20 66 69 6e 69 73  SQLite has finis
28000 68 65 64 20 77 69 74 68 20 69 74 2e 20 20 5e 54  hed with it.  ^T
28010 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 73  he destructor is
28020 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 6f 20 64 69   called.** to di
28030 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f  spose of the BLO
28040 42 20 6f 72 20 73 74 72 69 6e 67 20 65 76 65 6e  B or string even
28050 20 69 66 20 74 68 65 20 63 61 6c 6c 20 74 6f 20   if the call to 
28060 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
28070 62 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  b(),.** sqlite3_
28080 62 69 6e 64 5f 74 65 78 74 28 29 2c 20 6f 72 20  bind_text(), or 
28090 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
280a0 74 31 36 28 29 20 66 61 69 6c 73 2e 20 20 0a 2a  t16() fails.  .*
280b0 2a 20 5e 49 66 20 74 68 65 20 66 69 66 74 68 20  * ^If the fifth 
280c0 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 74  argument is.** t
280d0 68 65 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65  he special value
280e0 20 5b 53 51 4c 49 54 45 5f 53 54 41 54 49 43 5d   [SQLITE_STATIC]
280f0 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 61 73  , then SQLite as
28100 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a  sumes that the.*
28110 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73  * information is
28120 20 69 6e 20 73 74 61 74 69 63 2c 20 75 6e 6d 61   in static, unma
28130 6e 61 67 65 64 20 73 70 61 63 65 20 61 6e 64 20  naged space and 
28140 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f  does not need to
28150 20 62 65 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49   be freed..** ^I
28160 66 20 74 68 65 20 66 69 66 74 68 20 61 72 67 75  f the fifth argu
28170 6d 65 6e 74 20 68 61 73 20 74 68 65 20 76 61 6c  ment has the val
28180 75 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53  ue [SQLITE_TRANS
28190 49 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53  IENT], then.** S
281a0 51 4c 69 74 65 20 6d 61 6b 65 73 20 69 74 73 20  QLite makes its 
281b0 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79  own private copy
281c0 20 6f 66 20 74 68 65 20 64 61 74 61 20 69 6d 6d   of the data imm
281d0 65 64 69 61 74 65 6c 79 2c 20 62 65 66 6f 72 65  ediately, before
281e0 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f  .** the sqlite3_
281f0 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65  bind_*() routine
28200 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20   returns..**.** 
28210 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e  ^The sqlite3_bin
28220 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 72 6f 75  d_zeroblob() rou
28230 74 69 6e 65 20 62 69 6e 64 73 20 61 20 42 4c 4f  tine binds a BLO
28240 42 20 6f 66 20 6c 65 6e 67 74 68 20 4e 20 74 68  B of length N th
28250 61 74 0a 2a 2a 20 69 73 20 66 69 6c 6c 65 64 20  at.** is filled 
28260 77 69 74 68 20 7a 65 72 6f 65 73 2e 20 20 5e 41  with zeroes.  ^A
28270 20 7a 65 72 6f 62 6c 6f 62 20 75 73 65 73 20 61   zeroblob uses a
28280 20 66 69 78 65 64 20 61 6d 6f 75 6e 74 20 6f 66   fixed amount of
28290 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73 74   memory.** (just
282a0 20 61 6e 20 69 6e 74 65 67 65 72 20 74 6f 20 68   an integer to h
282b0 6f 6c 64 20 69 74 73 20 73 69 7a 65 29 20 77 68  old its size) wh
282c0 69 6c 65 20 69 74 20 69 73 20 62 65 69 6e 67 20  ile it is being 
282d0 70 72 6f 63 65 73 73 65 64 2e 0a 2a 2a 20 5a 65  processed..** Ze
282e0 72 6f 62 6c 6f 62 73 20 61 72 65 20 69 6e 74 65  roblobs are inte
282f0 6e 64 65 64 20 74 6f 20 73 65 72 76 65 20 61 73  nded to serve as
28300 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f   placeholders fo
28310 72 20 42 4c 4f 42 73 20 77 68 6f 73 65 0a 2a 2a  r BLOBs whose.**
28320 20 63 6f 6e 74 65 6e 74 20 69 73 20 6c 61 74 65   content is late
28330 72 20 77 72 69 74 74 65 6e 20 75 73 69 6e 67 0a  r written using.
28340 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  ** [sqlite3_blob
28350 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 65 6d 65 6e  _open | incremen
28360 74 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f  tal BLOB I/O] ro
28370 75 74 69 6e 65 73 2e 0a 2a 2a 20 5e 41 20 6e 65  utines..** ^A ne
28380 67 61 74 69 76 65 20 76 61 6c 75 65 20 66 6f 72  gative value for
28390 20 74 68 65 20 7a 65 72 6f 62 6c 6f 62 20 72 65   the zeroblob re
283a0 73 75 6c 74 73 20 69 6e 20 61 20 7a 65 72 6f 2d  sults in a zero-
283b0 6c 65 6e 67 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a  length BLOB..**.
283c0 2a 2a 20 5e 49 66 20 61 6e 79 20 6f 66 20 74 68  ** ^If any of th
283d0 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
283e0 28 29 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  () routines are 
283f0 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55  called with a NU
28400 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 66 6f  LL pointer.** fo
28410 72 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  r the [prepared 
28420 73 74 61 74 65 6d 65 6e 74 5d 20 6f 72 20 77 69  statement] or wi
28430 74 68 20 61 20 70 72 65 70 61 72 65 64 20 73 74  th a prepared st
28440 61 74 65 6d 65 6e 74 20 66 6f 72 20 77 68 69 63  atement for whic
28450 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74  h.** [sqlite3_st
28460 65 70 28 29 5d 20 68 61 73 20 62 65 65 6e 20 63  ep()] has been c
28470 61 6c 6c 65 64 20 6d 6f 72 65 20 72 65 63 65 6e  alled more recen
28480 74 6c 79 20 74 68 61 6e 20 5b 73 71 6c 69 74 65  tly than [sqlite
28490 33 5f 72 65 73 65 74 28 29 5d 2c 0a 2a 2a 20 74  3_reset()],.** t
284a0 68 65 6e 20 74 68 65 20 63 61 6c 6c 20 77 69 6c  hen the call wil
284b0 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  l return [SQLITE
284c0 5f 4d 49 53 55 53 45 5d 2e 20 20 49 66 20 61 6e  _MISUSE].  If an
284d0 79 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 28  y sqlite3_bind_(
284e0 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 69 73 20  ).** routine is 
284f0 70 61 73 73 65 64 20 61 20 5b 70 72 65 70 61 72  passed a [prepar
28500 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68  ed statement] th
28510 61 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61  at has been fina
28520 6c 69 7a 65 64 2c 20 74 68 65 0a 2a 2a 20 72 65  lized, the.** re
28530 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65  sult is undefine
28540 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 68  d and probably h
28550 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 42  armful..**.** ^B
28560 69 6e 64 69 6e 67 73 20 61 72 65 20 6e 6f 74 20  indings are not 
28570 63 6c 65 61 72 65 64 20 62 79 20 74 68 65 20 5b  cleared by the [
28580 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
28590 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20 5e 55 6e   routine..** ^Un
285a0 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72 73  bound parameters
285b0 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64   are interpreted
285c0 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   as NULL..**.** 
285d0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e  ^The sqlite3_bin
285e0 64 5f 2a 20 72 6f 75 74 69 6e 65 73 20 72 65 74  d_* routines ret
285f0 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  urn [SQLITE_OK] 
28600 6f 6e 20 73 75 63 63 65 73 73 20 6f 72 20 61 6e  on success or an
28610 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  .** [error code]
28620 20 69 66 20 61 6e 79 74 68 69 6e 67 20 67 6f 65   if anything goe
28630 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20 5e 5b 53 51  s wrong..** ^[SQ
28640 4c 49 54 45 5f 52 41 4e 47 45 5d 20 69 73 20 72  LITE_RANGE] is r
28650 65 74 75 72 6e 65 64 20 69 66 20 74 68 65 20 70  eturned if the p
28660 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 6e 64 65  arameter.** inde
28670 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67  x is out of rang
28680 65 2e 20 20 5e 5b 53 51 4c 49 54 45 5f 4e 4f 4d  e.  ^[SQLITE_NOM
28690 45 4d 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20  EM] is returned 
286a0 69 66 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c  if malloc() fail
286b0 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  s..**.** See als
286c0 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  o: [sqlite3_bind
286d0 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74  _parameter_count
286e0 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
286f0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
28700 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71  name()], and [sq
28710 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
28720 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a  eter_index()]..*
28730 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  /.int sqlite3_bi
28740 6e 64 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f  nd_blob(sqlite3_
28750 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73  stmt*, int, cons
28760 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c 20  t void*, int n, 
28770 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
28780 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
28790 64 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33  d_double(sqlite3
287a0 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f 75  _stmt*, int, dou
287b0 62 6c 65 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  ble);.int sqlite
287c0 33 5f 62 69 6e 64 5f 69 6e 74 28 73 71 6c 69 74  3_bind_int(sqlit
287d0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69  e3_stmt*, int, i
287e0 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  nt);.int sqlite3
287f0 5f 62 69 6e 64 5f 69 6e 74 36 34 28 73 71 6c 69  _bind_int64(sqli
28800 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
28810 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a  sqlite3_int64);.
28820 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
28830 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 73 74  _null(sqlite3_st
28840 6d 74 2a 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73  mt*, int);.int s
28850 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
28860 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
28870 69 6e 74 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a  int, const char*
28880 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29  , int n, void(*)
28890 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71  (void*));.int sq
288a0 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31  lite3_bind_text1
288b0 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
288c0 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64   int, const void
288d0 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28  *, int, void(*)(
288e0 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c  void*));.int sql
288f0 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28  ite3_bind_value(
28900 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
28910 6e 74 2c 20 63 6f 6e 73 74 20 73 71 6c 69 74 65  nt, const sqlite
28920 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73  3_value*);.int s
28930 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f  qlite3_bind_zero
28940 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d  blob(sqlite3_stm
28950 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 20 6e 29 3b  t*, int, int n);
28960 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
28970 3a 20 4e 75 6d 62 65 72 20 4f 66 20 53 51 4c 20  : Number Of SQL 
28980 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a  Parameters.**.**
28990 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63   ^This routine c
289a0 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 66 69  an be used to fi
289b0 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  nd the number of
289c0 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73   [SQL parameters
289d0 5d 0a 2a 2a 20 69 6e 20 61 20 5b 70 72 65 70 61  ].** in a [prepa
289e0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20  red statement]. 
289f0 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20   SQL parameters 
28a00 61 72 65 20 74 6f 6b 65 6e 73 20 6f 66 20 74 68  are tokens of th
28a10 65 0a 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c 20 22  e.** form "?", "
28a20 3f 4e 4e 4e 22 2c 20 22 3a 41 41 41 22 2c 20 22  ?NNN", ":AAA", "
28a30 24 41 41 41 22 2c 20 6f 72 20 22 40 41 41 41 22  $AAA", or "@AAA"
28a40 20 74 68 61 74 20 73 65 72 76 65 20 61 73 0a 2a   that serve as.*
28a50 2a 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66  * placeholders f
28a60 6f 72 20 76 61 6c 75 65 73 20 74 68 61 74 20 61  or values that a
28a70 72 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  re [sqlite3_bind
28a80 5f 62 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a  _blob | bound].*
28a90 2a 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74  * to the paramet
28aa0 65 72 73 20 61 74 20 61 20 6c 61 74 65 72 20 74  ers at a later t
28ab0 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69  ime..**.** ^(Thi
28ac0 73 20 72 6f 75 74 69 6e 65 20 61 63 74 75 61 6c  s routine actual
28ad0 6c 79 20 72 65 74 75 72 6e 73 20 74 68 65 20 69  ly returns the i
28ae0 6e 64 65 78 20 6f 66 20 74 68 65 20 6c 61 72 67  ndex of the larg
28af0 65 73 74 20 28 72 69 67 68 74 6d 6f 73 74 29 0a  est (rightmost).
28b00 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 20 46 6f  ** parameter. Fo
28b10 72 20 61 6c 6c 20 66 6f 72 6d 73 20 65 78 63 65  r all forms exce
28b20 70 74 20 3f 4e 4e 4e 2c 20 74 68 69 73 20 77 69  pt ?NNN, this wi
28b30 6c 6c 20 63 6f 72 72 65 73 70 6f 6e 64 20 74 6f  ll correspond to
28b40 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f   the.** number o
28b50 66 20 75 6e 69 71 75 65 20 70 61 72 61 6d 65 74  f unique paramet
28b60 65 72 73 2e 20 20 49 66 20 70 61 72 61 6d 65 74  ers.  If paramet
28b70 65 72 73 20 6f 66 20 74 68 65 20 3f 4e 4e 4e 20  ers of the ?NNN 
28b80 66 6f 72 6d 20 61 72 65 20 75 73 65 64 2c 0a 2a  form are used,.*
28b90 2a 20 74 68 65 72 65 20 6d 61 79 20 62 65 20 67  * there may be g
28ba0 61 70 73 20 69 6e 20 74 68 65 20 6c 69 73 74 2e  aps in the list.
28bb0 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  )^.**.** See als
28bc0 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  o: [sqlite3_bind
28bd0 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69  _blob|sqlite3_bi
28be0 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  nd()],.** [sqlit
28bf0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
28c00 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a  r_name()], and.*
28c10 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
28c20 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28  parameter_index(
28c30 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  )]..*/.int sqlit
28c40 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
28c50 72 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f  r_count(sqlite3_
28c60 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  stmt*);../*.** C
28c70 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66  API3REF: Name Of
28c80 20 41 20 48 6f 73 74 20 50 61 72 61 6d 65 74 65   A Host Paramete
28c90 72 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  r.**.** ^The sql
28ca0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
28cb0 74 65 72 5f 6e 61 6d 65 28 50 2c 4e 29 20 69 6e  ter_name(P,N) in
28cc0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a  terface returns.
28cd0 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  ** the name of t
28ce0 68 65 20 4e 2d 74 68 20 5b 53 51 4c 20 70 61 72  he N-th [SQL par
28cf0 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 65 20 5b  ameter] in the [
28d00 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
28d10 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 28 53 51 4c 20  nt] P..** ^(SQL 
28d20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68  parameters of th
28d30 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20 6f 72  e form "?NNN" or
28d40 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41   ":AAA" or "@AAA
28d50 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 68  " or "$AAA".** h
28d60 61 76 65 20 61 20 6e 61 6d 65 20 77 68 69 63 68  ave a name which
28d70 20 69 73 20 74 68 65 20 73 74 72 69 6e 67 20 22   is the string "
28d80 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20  ?NNN" or ":AAA" 
28d90 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22 24 41  or "@AAA" or "$A
28da0 41 41 22 0a 2a 2a 20 72 65 73 70 65 63 74 69 76  AA".** respectiv
28db0 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68 65 72  ely..** In other
28dc0 20 77 6f 72 64 73 2c 20 74 68 65 20 69 6e 69 74   words, the init
28dd0 69 61 6c 20 22 3a 22 20 6f 72 20 22 24 22 20 6f  ial ":" or "$" o
28de0 72 20 22 40 22 20 6f 72 20 22 3f 22 0a 2a 2a 20  r "@" or "?".** 
28df0 69 73 20 69 6e 63 6c 75 64 65 64 20 61 73 20 70  is included as p
28e00 61 72 74 20 6f 66 20 74 68 65 20 6e 61 6d 65 2e  art of the name.
28e10 29 5e 0a 2a 2a 20 5e 50 61 72 61 6d 65 74 65 72  )^.** ^Parameter
28e20 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f  s of the form "?
28e30 22 20 77 69 74 68 6f 75 74 20 61 20 66 6f 6c 6c  " without a foll
28e40 6f 77 69 6e 67 20 69 6e 74 65 67 65 72 20 68 61  owing integer ha
28e50 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a 20 61 6e  ve no name.** an
28e60 64 20 61 72 65 20 72 65 66 65 72 72 65 64 20 74  d are referred t
28e70 6f 20 61 73 20 22 6e 61 6d 65 6c 65 73 73 22 20  o as "nameless" 
28e80 6f 72 20 22 61 6e 6f 6e 79 6d 6f 75 73 20 70 61  or "anonymous pa
28e90 72 61 6d 65 74 65 72 73 22 2e 0a 2a 2a 0a 2a 2a  rameters"..**.**
28ea0 20 5e 54 68 65 20 66 69 72 73 74 20 68 6f 73 74   ^The first host
28eb0 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 61   parameter has a
28ec0 6e 20 69 6e 64 65 78 20 6f 66 20 31 2c 20 6e 6f  n index of 1, no
28ed0 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  t 0..**.** ^If t
28ee0 68 65 20 76 61 6c 75 65 20 4e 20 69 73 20 6f 75  he value N is ou
28ef0 74 20 6f 66 20 72 61 6e 67 65 20 6f 72 20 69 66  t of range or if
28f00 20 74 68 65 20 4e 2d 74 68 20 70 61 72 61 6d 65   the N-th parame
28f10 74 65 72 20 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65  ter is.** namele
28f20 73 73 2c 20 74 68 65 6e 20 4e 55 4c 4c 20 69 73  ss, then NULL is
28f30 20 72 65 74 75 72 6e 65 64 2e 20 20 5e 54 68 65   returned.  ^The
28f40 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67   returned string
28f50 20 69 73 0a 2a 2a 20 61 6c 77 61 79 73 20 69 6e   is.** always in
28f60 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20   UTF-8 encoding 
28f70 65 76 65 6e 20 69 66 20 74 68 65 20 6e 61 6d 65  even if the name
28f80 64 20 70 61 72 61 6d 65 74 65 72 20 77 61 73 0a  d parameter was.
28f90 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c 79 20 73 70  ** originally sp
28fa0 65 63 69 66 69 65 64 20 61 73 20 55 54 46 2d 31  ecified as UTF-1
28fb0 36 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72  6 in [sqlite3_pr
28fc0 65 70 61 72 65 31 36 28 29 5d 20 6f 72 0a 2a 2a  epare16()] or.**
28fd0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
28fe0 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a  e16_v2()]..**.**
28ff0 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
29000 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71  te3_bind_blob|sq
29010 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a  lite3_bind()],.*
29020 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
29030 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28  parameter_count(
29040 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  )], and.** [sqli
29050 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
29060 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a  er_index()]..*/.
29070 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
29080 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
29090 65 72 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f  er_name(sqlite3_
290a0 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a  stmt*, int);../*
290b0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e  .** CAPI3REF: In
290c0 64 65 78 20 4f 66 20 41 20 50 61 72 61 6d 65 74  dex Of A Paramet
290d0 65 72 20 57 69 74 68 20 41 20 47 69 76 65 6e 20  er With A Given 
290e0 4e 61 6d 65 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75  Name.**.** ^Retu
290f0 72 6e 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20  rn the index of 
29100 61 6e 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  an SQL parameter
29110 20 67 69 76 65 6e 20 69 74 73 20 6e 61 6d 65 2e   given its name.
29120 20 20 5e 54 68 65 0a 2a 2a 20 69 6e 64 65 78 20    ^The.** index 
29130 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 69  value returned i
29140 73 20 73 75 69 74 61 62 6c 65 20 66 6f 72 20 75  s suitable for u
29150 73 65 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  se as the second
29160 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f  .** parameter to
29170 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
29180 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64  lob|sqlite3_bind
29190 28 29 5d 2e 20 20 5e 41 20 7a 65 72 6f 0a 2a 2a  ()].  ^A zero.**
291a0 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20   is returned if 
291b0 6e 6f 20 6d 61 74 63 68 69 6e 67 20 70 61 72 61  no matching para
291c0 6d 65 74 65 72 20 69 73 20 66 6f 75 6e 64 2e 20  meter is found. 
291d0 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72 0a   ^The parameter.
291e0 2a 2a 20 6e 61 6d 65 20 6d 75 73 74 20 62 65 20  ** name must be 
291f0 67 69 76 65 6e 20 69 6e 20 55 54 46 2d 38 20 65  given in UTF-8 e
29200 76 65 6e 20 69 66 20 74 68 65 20 6f 72 69 67 69  ven if the origi
29210 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a  nal statement.**
29220 20 77 61 73 20 70 72 65 70 61 72 65 64 20 66 72   was prepared fr
29230 6f 6d 20 55 54 46 2d 31 36 20 74 65 78 74 20 75  om UTF-16 text u
29240 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72  sing [sqlite3_pr
29250 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a  epare16_v2()]..*
29260 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
29270 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
29280 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29  b|sqlite3_bind()
29290 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  ],.** [sqlite3_b
292a0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f  ind_parameter_co
292b0 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b  unt()], and.** [
292c0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
292d0 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e  ameter_index()].
292e0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
292f0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69  bind_parameter_i
29300 6e 64 65 78 28 73 71 6c 69 74 65 33 5f 73 74 6d  ndex(sqlite3_stm
29310 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  t*, const char *
29320 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  zName);../*.** C
29330 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 41  API3REF: Reset A
29340 6c 6c 20 42 69 6e 64 69 6e 67 73 20 4f 6e 20 41  ll Bindings On A
29350 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d   Prepared Statem
29360 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 74 72  ent.**.** ^Contr
29370 61 72 79 20 74 6f 20 74 68 65 20 69 6e 74 75 69  ary to the intui
29380 74 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b 73  tion of many, [s
29390 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
293a0 64 6f 65 73 20 6e 6f 74 20 72 65 73 65 74 0a 2a  does not reset.*
293b0 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62  * the [sqlite3_b
293c0 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 69 6e 64 69  ind_blob | bindi
293d0 6e 67 73 5d 20 6f 6e 20 61 20 5b 70 72 65 70 61  ngs] on a [prepa
293e0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a  red statement]..
293f0 2a 2a 20 5e 55 73 65 20 74 68 69 73 20 72 6f 75  ** ^Use this rou
29400 74 69 6e 65 20 74 6f 20 72 65 73 65 74 20 61 6c  tine to reset al
29410 6c 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72  l host parameter
29420 73 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e  s to NULL..*/.in
29430 74 20 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f  t sqlite3_clear_
29440 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33  bindings(sqlite3
29450 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  _stmt*);../*.** 
29460 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72  CAPI3REF: Number
29470 20 4f 66 20 43 6f 6c 75 6d 6e 73 20 49 6e 20 41   Of Columns In A
29480 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a   Result Set.**.*
29490 2a 20 5e 52 65 74 75 72 6e 20 74 68 65 20 6e 75  * ^Return the nu
294a0 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
294b0 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  in the result se
294c0 74 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  t returned by th
294d0 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  e.** [prepared s
294e0 74 61 74 65 6d 65 6e 74 5d 2e 20 5e 54 68 69 73  tatement]. ^This
294f0 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
29500 20 30 20 69 66 20 70 53 74 6d 74 20 69 73 20 61   0 if pStmt is a
29510 6e 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65  n SQL.** stateme
29520 6e 74 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74  nt that does not
29530 20 72 65 74 75 72 6e 20 64 61 74 61 20 28 66 6f   return data (fo
29540 72 20 65 78 61 6d 70 6c 65 20 61 6e 20 5b 55 50  r example an [UP
29550 44 41 54 45 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65  DATE])..**.** Se
29560 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
29570 5f 64 61 74 61 5f 63 6f 75 6e 74 28 29 5d 0a 2a  _data_count()].*
29580 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  /.int sqlite3_co
29590 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c 69 74  lumn_count(sqlit
295a0 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
295b0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
295c0 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20 49  : Column Names I
295d0 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a  n A Result Set.*
295e0 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74  *.** ^These rout
295f0 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20  ines return the 
29600 6e 61 6d 65 20 61 73 73 69 67 6e 65 64 20 74 6f  name assigned to
29610 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 63 6f   a particular co
29620 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 72  lumn.** in the r
29630 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b  esult set of a [
29640 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e  SELECT] statemen
29650 74 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33  t.  ^The sqlite3
29660 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a  _column_name().*
29670 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  * interface retu
29680 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
29690 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
296a0 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a  ed UTF-8 string.
296b0 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  ** and sqlite3_c
296c0 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 72  olumn_name16() r
296d0 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
296e0 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69   to a zero-termi
296f0 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20  nated.** UTF-16 
29700 73 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 66 69  string.  ^The fi
29710 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73  rst parameter is
29720 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
29730 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61  tatement].** tha
29740 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65  t implements the
29750 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d   [SELECT] statem
29760 65 6e 74 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64  ent. ^The second
29770 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
29780 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62  e.** column numb
29790 65 72 2e 20 20 5e 54 68 65 20 6c 65 66 74 6d 6f  er.  ^The leftmo
297a0 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d  st column is num
297b0 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ber 0..**.** ^Th
297c0 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e  e returned strin
297d0 67 20 70 6f 69 6e 74 65 72 20 69 73 20 76 61 6c  g pointer is val
297e0 69 64 20 75 6e 74 69 6c 20 65 69 74 68 65 72 20  id until either 
297f0 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
29800 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20 64  atement].** is d
29810 65 73 74 72 6f 79 65 64 20 62 79 20 5b 73 71 6c  estroyed by [sql
29820 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
29830 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 74   or until the st
29840 61 74 65 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d  atement is autom
29850 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72  atically.** repr
29860 65 70 61 72 65 64 20 62 79 20 74 68 65 20 66 69  epared by the fi
29870 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  rst call to [sql
29880 69 74 65 33 5f 73 74 65 70 28 29 5d 20 66 6f 72  ite3_step()] for
29890 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 75   a particular ru
298a0 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68  n.** or until th
298b0 65 20 6e 65 78 74 20 63 61 6c 6c 20 74 6f 0a 2a  e next call to.*
298c0 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  * sqlite3_column
298d0 5f 6e 61 6d 65 28 29 20 6f 72 20 73 71 6c 69 74  _name() or sqlit
298e0 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36  e3_column_name16
298f0 28 29 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 63  () on the same c
29900 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  olumn..**.** ^If
29910 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
29920 29 20 66 61 69 6c 73 20 64 75 72 69 6e 67 20 74  ) fails during t
29930 68 65 20 70 72 6f 63 65 73 73 69 6e 67 20 6f 66  he processing of
29940 20 65 69 74 68 65 72 20 72 6f 75 74 69 6e 65 0a   either routine.
29950 2a 2a 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20  ** (for example 
29960 64 75 72 69 6e 67 20 61 20 63 6f 6e 76 65 72 73  during a convers
29970 69 6f 6e 20 66 72 6f 6d 20 55 54 46 2d 38 20 74  ion from UTF-8 t
29980 6f 20 55 54 46 2d 31 36 29 20 74 68 65 6e 20 61  o UTF-16) then a
29990 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  .** NULL pointer
299a0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
299b0 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66  .** ^The name of
299c0 20 61 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e   a result column
299d0 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66   is the value of
299e0 20 74 68 65 20 22 41 53 22 20 63 6c 61 75 73 65   the "AS" clause
299f0 20 66 6f 72 0a 2a 2a 20 74 68 61 74 20 63 6f 6c   for.** that col
29a00 75 6d 6e 2c 20 69 66 20 74 68 65 72 65 20 69 73  umn, if there is
29a10 20 61 6e 20 41 53 20 63 6c 61 75 73 65 2e 20 20   an AS clause.  
29a20 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20 41  If there is no A
29a30 53 20 63 6c 61 75 73 65 0a 2a 2a 20 74 68 65 6e  S clause.** then
29a40 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
29a50 20 63 6f 6c 75 6d 6e 20 69 73 20 75 6e 73 70 65   column is unspe
29a60 63 69 66 69 65 64 20 61 6e 64 20 6d 61 79 20 63  cified and may c
29a70 68 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e  hange from.** on
29a80 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c  e release of SQL
29a90 69 74 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e  ite to the next.
29aa0 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  .*/.const char *
29ab0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
29ac0 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
29ad0 2a 2c 20 69 6e 74 20 4e 29 3b 0a 63 6f 6e 73 74  *, int N);.const
29ae0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
29af0 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 73 71 6c  olumn_name16(sql
29b00 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
29b10 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  N);../*.** CAPI3
29b20 52 45 46 3a 20 53 6f 75 72 63 65 20 4f 66 20 44  REF: Source Of D
29b30 61 74 61 20 49 6e 20 41 20 51 75 65 72 79 20 52  ata In A Query R
29b40 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  esult.**.** ^The
29b50 73 65 20 72 6f 75 74 69 6e 65 73 20 70 72 6f 76  se routines prov
29b60 69 64 65 20 61 20 6d 65 61 6e 73 20 74 6f 20 64  ide a means to d
29b70 65 74 65 72 6d 69 6e 65 20 74 68 65 20 64 61 74  etermine the dat
29b80 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e  abase, table, an
29b90 64 0a 2a 2a 20 74 61 62 6c 65 20 63 6f 6c 75 6d  d.** table colum
29ba0 6e 20 74 68 61 74 20 69 73 20 74 68 65 20 6f 72  n that is the or
29bb0 69 67 69 6e 20 6f 66 20 61 20 70 61 72 74 69 63  igin of a partic
29bc0 75 6c 61 72 20 72 65 73 75 6c 74 20 63 6f 6c 75  ular result colu
29bd0 6d 6e 20 69 6e 0a 2a 2a 20 5b 53 45 4c 45 43 54  mn in.** [SELECT
29be0 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20  ] statement..** 
29bf0 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65  ^The name of the
29c00 20 64 61 74 61 62 61 73 65 20 6f 72 20 74 61 62   database or tab
29c10 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 20 63 61 6e  le or column can
29c20 20 62 65 20 72 65 74 75 72 6e 65 64 20 61 73 0a   be returned as.
29c30 2a 2a 20 65 69 74 68 65 72 20 61 20 55 54 46 2d  ** either a UTF-
29c40 38 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72 69  8 or UTF-16 stri
29c50 6e 67 2e 20 20 5e 54 68 65 20 5f 64 61 74 61 62  ng.  ^The _datab
29c60 61 73 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65  ase_ routines re
29c70 74 75 72 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61  turn.** the data
29c80 62 61 73 65 20 6e 61 6d 65 2c 20 74 68 65 20 5f  base name, the _
29c90 74 61 62 6c 65 5f 20 72 6f 75 74 69 6e 65 73 20  table_ routines 
29ca0 72 65 74 75 72 6e 20 74 68 65 20 74 61 62 6c 65  return the table
29cb0 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74 68   name, and.** th
29cc0 65 20 6f 72 69 67 69 6e 5f 20 72 6f 75 74 69 6e  e origin_ routin
29cd0 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 63 6f  es return the co
29ce0 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 54  lumn name..** ^T
29cf0 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69  he returned stri
29d00 6e 67 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69  ng is valid unti
29d10 6c 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  l the [prepared 
29d20 73 74 61 74 65 6d 65 6e 74 5d 20 69 73 20 64 65  statement] is de
29d30 73 74 72 6f 79 65 64 0a 2a 2a 20 75 73 69 6e 67  stroyed.** using
29d40 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
29d50 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74  ze()] or until t
29d60 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
29d70 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a  automatically.**
29d80 20 72 65 70 72 65 70 61 72 65 64 20 62 79 20 74   reprepared by t
29d90 68 65 20 66 69 72 73 74 20 63 61 6c 6c 20 74 6f  he first call to
29da0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
29db0 5d 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c  ] for a particul
29dc0 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74  ar run.** or unt
29dd0 69 6c 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f  il the same info
29de0 72 6d 61 74 69 6f 6e 20 69 73 20 72 65 71 75 65  rmation is reque
29df0 73 74 65 64 0a 2a 2a 20 61 67 61 69 6e 20 69 6e  sted.** again in
29e00 20 61 20 64 69 66 66 65 72 65 6e 74 20 65 6e 63   a different enc
29e10 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  oding..**.** ^Th
29e20 65 20 6e 61 6d 65 73 20 72 65 74 75 72 6e 65 64  e names returned
29e30 20 61 72 65 20 74 68 65 20 6f 72 69 67 69 6e 61   are the origina
29e40 6c 20 75 6e 2d 61 6c 69 61 73 65 64 20 6e 61 6d  l un-aliased nam
29e50 65 73 20 6f 66 20 74 68 65 0a 2a 2a 20 64 61 74  es of the.** dat
29e60 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e  abase, table, an
29e70 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20  d column..**.** 
29e80 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d  ^The first argum
29e90 65 6e 74 20 74 6f 20 74 68 65 73 65 20 69 6e 74  ent to these int
29ea0 65 72 66 61 63 65 73 20 69 73 20 61 20 5b 70 72  erfaces is a [pr
29eb0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
29ec0 5d 2e 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e  ]..** ^These fun
29ed0 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 69 6e  ctions return in
29ee0 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20  formation about 
29ef0 74 68 65 20 4e 74 68 20 72 65 73 75 6c 74 20 63  the Nth result c
29f00 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62  olumn returned b
29f10 79 0a 2a 2a 20 74 68 65 20 73 74 61 74 65 6d 65  y.** the stateme
29f20 6e 74 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74  nt, where N is t
29f30 68 65 20 73 65 63 6f 6e 64 20 66 75 6e 63 74 69  he second functi
29f40 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20  on argument..** 
29f50 5e 54 68 65 20 6c 65 66 74 2d 6d 6f 73 74 20 63  ^The left-most c
29f60 6f 6c 75 6d 6e 20 69 73 20 63 6f 6c 75 6d 6e 20  olumn is column 
29f70 30 20 66 6f 72 20 74 68 65 73 65 20 72 6f 75 74  0 for these rout
29f80 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ines..**.** ^If 
29f90 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72  the Nth column r
29fa0 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 20 73  eturned by the s
29fb0 74 61 74 65 6d 65 6e 74 20 69 73 20 61 6e 20 65  tatement is an e
29fc0 78 70 72 65 73 73 69 6f 6e 20 6f 72 0a 2a 2a 20  xpression or.** 
29fd0 73 75 62 71 75 65 72 79 20 61 6e 64 20 69 73 20  subquery and is 
29fe0 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e 20 76 61 6c  not a column val
29ff0 75 65 2c 20 74 68 65 6e 20 61 6c 6c 20 6f 66 20  ue, then all of 
2a000 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  these functions 
2a010 72 65 74 75 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20  return.** NULL. 
2a020 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 20   ^These routine 
2a030 6d 69 67 68 74 20 61 6c 73 6f 20 72 65 74 75 72  might also retur
2a040 6e 20 4e 55 4c 4c 20 69 66 20 61 20 6d 65 6d 6f  n NULL if a memo
2a050 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72  ry allocation er
2a060 72 6f 72 0a 2a 2a 20 6f 63 63 75 72 73 2e 20 20  ror.** occurs.  
2a070 5e 4f 74 68 65 72 77 69 73 65 2c 20 74 68 65 79  ^Otherwise, they
2a080 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65   return the name
2a090 20 6f 66 20 74 68 65 20 61 74 74 61 63 68 65 64   of the attached
2a0a0 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65   database, table
2a0b0 2c 0a 2a 2a 20 6f 72 20 63 6f 6c 75 6d 6e 20 74  ,.** or column t
2a0c0 68 61 74 20 71 75 65 72 79 20 72 65 73 75 6c 74  hat query result
2a0d0 20 63 6f 6c 75 6d 6e 20 77 61 73 20 65 78 74 72   column was extr
2a0e0 61 63 74 65 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a  acted from..**.*
2a0f0 2a 20 5e 41 73 20 77 69 74 68 20 61 6c 6c 20 6f  * ^As with all o
2a100 74 68 65 72 20 53 51 4c 69 74 65 20 41 50 49 73  ther SQLite APIs
2a110 2c 20 74 68 6f 73 65 20 77 68 6f 73 65 20 6e 61  , those whose na
2a120 6d 65 73 20 65 6e 64 20 77 69 74 68 20 22 31 36  mes end with "16
2a130 22 20 72 65 74 75 72 6e 0a 2a 2a 20 55 54 46 2d  " return.** UTF-
2a140 31 36 20 65 6e 63 6f 64 65 64 20 73 74 72 69 6e  16 encoded strin
2a150 67 73 20 61 6e 64 20 74 68 65 20 6f 74 68 65 72  gs and the other
2a160 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72   functions retur
2a170 6e 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 5e  n UTF-8..**.** ^
2a180 54 68 65 73 65 20 41 50 49 73 20 61 72 65 20 6f  These APIs are o
2a190 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66  nly available if
2a1a0 20 74 68 65 20 6c 69 62 72 61 72 79 20 77 61 73   the library was
2a1b0 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74   compiled with t
2a1c0 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e  he.** [SQLITE_EN
2a1d0 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41  ABLE_COLUMN_META
2a1e0 44 41 54 41 5d 20 43 2d 70 72 65 70 72 6f 63 65  DATA] C-preproce
2a1f0 73 73 6f 72 20 73 79 6d 62 6f 6c 2e 0a 2a 2a 0a  ssor symbol..**.
2a200 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72  ** If two or mor
2a210 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f  e threads call o
2a220 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68  ne or more of th
2a230 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 67 61  ese routines aga
2a240 69 6e 73 74 20 74 68 65 20 73 61 6d 65 0a 2a 2a  inst the same.**
2a250 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
2a260 65 6e 74 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 61  ent and column a
2a270 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20  t the same time 
2a280 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73  then the results
2a290 20 61 72 65 0a 2a 2a 20 75 6e 64 65 66 69 6e 65   are.** undefine
2a2a0 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20  d..**.** If two 
2a2b0 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20  or more threads 
2a2c0 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  call one or more
2a2d0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
2a2e0 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d  umn_database_nam
2a2f0 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74 61 64  e | column metad
2a300 61 74 61 20 69 6e 74 65 72 66 61 63 65 73 5d 0a  ata interfaces].
2a310 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20  ** for the same 
2a320 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2a330 65 6e 74 5d 20 61 6e 64 20 72 65 73 75 6c 74 20  ent] and result 
2a340 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 74 20 74 68 65  column.** at the
2a350 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20   same time then 
2a360 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20  the results are 
2a370 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 63 6f  undefined..*/.co
2a380 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
2a390 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73  3_column_databas
2a3a0 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73  e_name(sqlite3_s
2a3b0 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74  tmt*,int);.const
2a3c0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
2a3d0 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e  olumn_database_n
2a3e0 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ame16(sqlite3_st
2a3f0 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20  mt*,int);.const 
2a400 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
2a410 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28  lumn_table_name(
2a420 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
2a430 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  t);.const void *
2a440 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2a450 61 62 6c 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69  able_name16(sqli
2a460 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
2a470 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
2a480 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69  te3_column_origi
2a490 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73  n_name(sqlite3_s
2a4a0 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74  tmt*,int);.const
2a4b0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
2a4c0 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d  olumn_origin_nam
2a4d0 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  e16(sqlite3_stmt
2a4e0 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  *,int);../*.** C
2a4f0 41 50 49 33 52 45 46 3a 20 44 65 63 6c 61 72 65  API3REF: Declare
2a500 64 20 44 61 74 61 74 79 70 65 20 4f 66 20 41 20  d Datatype Of A 
2a510 51 75 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a 0a  Query Result.**.
2a520 2a 2a 20 5e 28 54 68 65 20 66 69 72 73 74 20 70  ** ^(The first p
2a530 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 5b 70  arameter is a [p
2a540 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2a550 74 5d 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20 73  t]..** If this s
2a560 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 53  tatement is a [S
2a570 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74  ELECT] statement
2a580 20 61 6e 64 20 74 68 65 20 4e 74 68 20 63 6f 6c   and the Nth col
2a590 75 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65  umn of the.** re
2a5a0 74 75 72 6e 65 64 20 72 65 73 75 6c 74 20 73 65  turned result se
2a5b0 74 20 6f 66 20 74 68 61 74 20 5b 53 45 4c 45 43  t of that [SELEC
2a5c0 54 5d 20 69 73 20 61 20 74 61 62 6c 65 20 63 6f  T] is a table co
2a5d0 6c 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20  lumn (not an.** 
2a5e0 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75  expression or su
2a5f0 62 71 75 65 72 79 29 20 74 68 65 6e 20 74 68 65  bquery) then the
2a600 20 64 65 63 6c 61 72 65 64 20 74 79 70 65 20 6f   declared type o
2a610 66 20 74 68 65 20 74 61 62 6c 65 0a 2a 2a 20 63  f the table.** c
2a620 6f 6c 75 6d 6e 20 69 73 20 72 65 74 75 72 6e 65  olumn is returne
2a630 64 2e 29 5e 20 20 5e 49 66 20 74 68 65 20 4e 74  d.)^  ^If the Nt
2a640 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20  h column of the 
2a650 72 65 73 75 6c 74 20 73 65 74 20 69 73 20 61 6e  result set is an
2a660 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f  .** expression o
2a670 72 20 73 75 62 71 75 65 72 79 2c 20 74 68 65 6e  r subquery, then
2a680 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
2a690 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20  is returned..** 
2a6a0 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74  ^The returned st
2a6b0 72 69 6e 67 20 69 73 20 61 6c 77 61 79 73 20 55  ring is always U
2a6c0 54 46 2d 38 20 65 6e 63 6f 64 65 64 2e 0a 2a 2a  TF-8 encoded..**
2a6d0 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c  .** ^(For exampl
2a6e0 65 2c 20 67 69 76 65 6e 20 74 68 65 20 64 61 74  e, given the dat
2a6f0 61 62 61 73 65 20 73 63 68 65 6d 61 3a 0a 2a 2a  abase schema:.**
2a700 0a 2a 2a 20 43 52 45 41 54 45 20 54 41 42 4c 45  .** CREATE TABLE
2a710 20 74 31 28 63 31 20 56 41 52 49 41 4e 54 29 3b   t1(c1 VARIANT);
2a720 0a 2a 2a 0a 2a 2a 20 61 6e 64 20 74 68 65 20 66  .**.** and the f
2a730 6f 6c 6c 6f 77 69 6e 67 20 73 74 61 74 65 6d 65  ollowing stateme
2a740 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65  nt to be compile
2a750 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54 20  d:.**.** SELECT 
2a760 63 31 20 2b 20 31 2c 20 63 31 20 46 52 4f 4d 20  c1 + 1, c1 FROM 
2a770 74 31 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 73 20 72  t1;.**.** this r
2a780 6f 75 74 69 6e 65 20 77 6f 75 6c 64 20 72 65 74  outine would ret
2a790 75 72 6e 20 74 68 65 20 73 74 72 69 6e 67 20 22  urn the string "
2a7a0 56 41 52 49 41 4e 54 22 20 66 6f 72 20 74 68 65  VARIANT" for the
2a7b0 20 73 65 63 6f 6e 64 20 72 65 73 75 6c 74 0a 2a   second result.*
2a7c0 2a 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c  * column (i==1),
2a7d0 20 61 6e 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e   and a NULL poin
2a7e0 74 65 72 20 66 6f 72 20 74 68 65 20 66 69 72 73  ter for the firs
2a7f0 74 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  t result column 
2a800 28 69 3d 3d 30 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20  (i==0).)^.**.** 
2a810 5e 53 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e  ^SQLite uses dyn
2a820 61 6d 69 63 20 72 75 6e 2d 74 69 6d 65 20 74 79  amic run-time ty
2a830 70 69 6e 67 2e 20 20 5e 53 6f 20 6a 75 73 74 20  ping.  ^So just 
2a840 62 65 63 61 75 73 65 20 61 20 63 6f 6c 75 6d 6e  because a column
2a850 0a 2a 2a 20 69 73 20 64 65 63 6c 61 72 65 64 20  .** is declared 
2a860 74 6f 20 63 6f 6e 74 61 69 6e 20 61 20 70 61 72  to contain a par
2a870 74 69 63 75 6c 61 72 20 74 79 70 65 20 64 6f 65  ticular type doe
2a880 73 20 6e 6f 74 20 6d 65 61 6e 20 74 68 61 74 20  s not mean that 
2a890 74 68 65 0a 2a 2a 20 64 61 74 61 20 73 74 6f 72  the.** data stor
2a8a0 65 64 20 69 6e 20 74 68 61 74 20 63 6f 6c 75 6d  ed in that colum
2a8b0 6e 20 69 73 20 6f 66 20 74 68 65 20 64 65 63 6c  n is of the decl
2a8c0 61 72 65 64 20 74 79 70 65 2e 20 20 53 51 4c 69  ared type.  SQLi
2a8d0 74 65 20 69 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c  te is.** strongl
2a8e0 79 20 74 79 70 65 64 2c 20 62 75 74 20 74 68 65  y typed, but the
2a8f0 20 74 79 70 69 6e 67 20 69 73 20 64 79 6e 61 6d   typing is dynam
2a900 69 63 20 6e 6f 74 20 73 74 61 74 69 63 2e 20 20  ic not static.  
2a910 5e 54 79 70 65 0a 2a 2a 20 69 73 20 61 73 73 6f  ^Type.** is asso
2a920 63 69 61 74 65 64 20 77 69 74 68 20 69 6e 64 69  ciated with indi
2a930 76 69 64 75 61 6c 20 76 61 6c 75 65 73 2c 20 6e  vidual values, n
2a940 6f 74 20 77 69 74 68 20 74 68 65 20 63 6f 6e 74  ot with the cont
2a950 61 69 6e 65 72 73 0a 2a 2a 20 75 73 65 64 20 74  ainers.** used t
2a960 6f 20 68 6f 6c 64 20 74 68 6f 73 65 20 76 61 6c  o hold those val
2a970 75 65 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68  ues..*/.const ch
2a980 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ar *sqlite3_colu
2a990 6d 6e 5f 64 65 63 6c 74 79 70 65 28 73 71 6c 69  mn_decltype(sqli
2a9a0 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
2a9b0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
2a9c0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74  te3_column_declt
2a9d0 79 70 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ype16(sqlite3_st
2a9e0 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  mt*,int);../*.**
2a9f0 20 43 41 50 49 33 52 45 46 3a 20 45 76 61 6c 75   CAPI3REF: Evalu
2aa00 61 74 65 20 41 6e 20 53 51 4c 20 53 74 61 74 65  ate An SQL State
2aa10 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72  ment.**.** After
2aa20 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
2aa30 74 65 6d 65 6e 74 5d 20 68 61 73 20 62 65 65 6e  tement] has been
2aa40 20 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 20   prepared using 
2aa50 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74  either.** [sqlit
2aa60 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
2aa70 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   or [sqlite3_pre
2aa80 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20  pare16_v2()] or 
2aa90 6f 6e 65 20 6f 66 20 74 68 65 20 6c 65 67 61 63  one of the legac
2aaa0 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  y.** interfaces 
2aab0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2aac0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
2aad0 70 72 65 70 61 72 65 31 36 28 29 5d 2c 20 74 68  prepare16()], th
2aae0 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d  is function.** m
2aaf0 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 6f 6e  ust be called on
2ab00 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 20  e or more times 
2ab10 74 6f 20 65 76 61 6c 75 61 74 65 20 74 68 65 20  to evaluate the 
2ab20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a  statement..**.**
2ab30 20 54 68 65 20 64 65 74 61 69 6c 73 20 6f 66 20   The details of 
2ab40 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20  the behavior of 
2ab50 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70  the sqlite3_step
2ab60 28 29 20 69 6e 74 65 72 66 61 63 65 20 64 65 70  () interface dep
2ab70 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65  end.** on whethe
2ab80 72 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  r the statement 
2ab90 77 61 73 20 70 72 65 70 61 72 65 64 20 75 73 69  was prepared usi
2aba0 6e 67 20 74 68 65 20 6e 65 77 65 72 20 22 76 32  ng the newer "v2
2abb0 22 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 5b  " interface.** [
2abc0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
2abd0 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  v2()] and [sqlit
2abe0 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
2abf0 29 5d 20 6f 72 20 74 68 65 20 6f 6c 64 65 72 20  )] or the older 
2ac00 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66  legacy.** interf
2ac10 61 63 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  ace [sqlite3_pre
2ac20 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  pare()] and [sql
2ac30 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
2ac40 5d 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20 74  ].  The use of t
2ac50 68 65 0a 2a 2a 20 6e 65 77 20 22 76 32 22 20 69  he.** new "v2" i
2ac60 6e 74 65 72 66 61 63 65 20 69 73 20 72 65 63 6f  nterface is reco
2ac70 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6e 65 77 20  mmended for new 
2ac80 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 62 75 74  applications but
2ac90 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69   the legacy.** i
2aca0 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 63 6f  nterface will co
2acb0 6e 74 69 6e 75 65 20 74 6f 20 62 65 20 73 75 70  ntinue to be sup
2acc0 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  ported..**.** ^I
2acd0 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74  n the legacy int
2ace0 65 72 66 61 63 65 2c 20 74 68 65 20 72 65 74 75  erface, the retu
2acf0 72 6e 20 76 61 6c 75 65 20 77 69 6c 6c 20 62 65  rn value will be
2ad00 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f   either [SQLITE_
2ad10 42 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54  BUSY],.** [SQLIT
2ad20 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45  E_DONE], [SQLITE
2ad30 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49 54 45 5f 45  _ROW], [SQLITE_E
2ad40 52 52 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c 49 54  RROR], or [SQLIT
2ad50 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20 5e 57  E_MISUSE]..** ^W
2ad60 69 74 68 20 74 68 65 20 22 76 32 22 20 69 6e 74  ith the "v2" int
2ad70 65 72 66 61 63 65 2c 20 61 6e 79 20 6f 66 20 74  erface, any of t
2ad80 68 65 20 6f 74 68 65 72 20 5b 72 65 73 75 6c 74  he other [result
2ad90 20 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65   codes] or.** [e
2ada0 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
2adb0 6f 64 65 73 5d 20 6d 69 67 68 74 20 62 65 20 72  odes] might be r
2adc0 65 74 75 72 6e 65 64 20 61 73 20 77 65 6c 6c 2e  eturned as well.
2add0 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f  .**.** ^[SQLITE_
2ade0 42 55 53 59 5d 20 6d 65 61 6e 73 20 74 68 61 74  BUSY] means that
2adf0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 65 6e   the database en
2ae00 67 69 6e 65 20 77 61 73 20 75 6e 61 62 6c 65 20  gine was unable 
2ae10 74 6f 20 61 63 71 75 69 72 65 20 74 68 65 0a 2a  to acquire the.*
2ae20 2a 20 64 61 74 61 62 61 73 65 20 6c 6f 63 6b 73  * database locks
2ae30 20 69 74 20 6e 65 65 64 73 20 74 6f 20 64 6f 20   it needs to do 
2ae40 69 74 73 20 6a 6f 62 2e 20 20 5e 49 66 20 74 68  its job.  ^If th
2ae50 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61  e statement is a
2ae60 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20   [COMMIT].** or 
2ae70 6f 63 63 75 72 73 20 6f 75 74 73 69 64 65 20 6f  occurs outside o
2ae80 66 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72  f an explicit tr
2ae90 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20  ansaction, then 
2aea0 79 6f 75 20 63 61 6e 20 72 65 74 72 79 20 74 68  you can retry th
2aeb0 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e 20  e.** statement. 
2aec0 20 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e   If the statemen
2aed0 74 20 69 73 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d  t is not a [COMM
2aee0 49 54 5d 20 61 6e 64 20 6f 63 63 75 72 73 20 77  IT] and occurs w
2aef0 69 74 68 69 6e 20 61 6e 0a 2a 2a 20 65 78 70 6c  ithin an.** expl
2af00 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e  icit transaction
2af10 20 74 68 65 6e 20 79 6f 75 20 73 68 6f 75 6c 64   then you should
2af20 20 72 6f 6c 6c 62 61 63 6b 20 74 68 65 20 74 72   rollback the tr
2af30 61 6e 73 61 63 74 69 6f 6e 20 62 65 66 6f 72 65  ansaction before
2af40 0a 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a  .** continuing..
2af50 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 44  **.** ^[SQLITE_D
2af60 4f 4e 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20  ONE] means that 
2af70 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61  the statement ha
2af80 73 20 66 69 6e 69 73 68 65 64 20 65 78 65 63 75  s finished execu
2af90 74 69 6e 67 0a 2a 2a 20 73 75 63 63 65 73 73 66  ting.** successf
2afa0 75 6c 6c 79 2e 20 20 73 71 6c 69 74 65 33 5f 73  ully.  sqlite3_s
2afb0 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74  tep() should not
2afc0 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e   be called again
2afd0 20 6f 6e 20 74 68 69 73 20 76 69 72 74 75 61 6c   on this virtual
2afe0 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 77 69 74 68  .** machine with
2aff0 6f 75 74 20 66 69 72 73 74 20 63 61 6c 6c 69 6e  out first callin
2b000 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  g [sqlite3_reset
2b010 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65  ()] to reset the
2b020 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68   virtual.** mach
2b030 69 6e 65 20 62 61 63 6b 20 74 6f 20 69 74 73 20  ine back to its 
2b040 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2e 0a 2a  initial state..*
2b050 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 53 51 4c  *.** ^If the SQL
2b060 20 73 74 61 74 65 6d 65 6e 74 20 62 65 69 6e 67   statement being
2b070 20 65 78 65 63 75 74 65 64 20 72 65 74 75 72 6e   executed return
2b080 73 20 61 6e 79 20 64 61 74 61 2c 20 74 68 65 6e  s any data, then
2b090 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a   [SQLITE_ROW].**
2b0a0 20 69 73 20 72 65 74 75 72 6e 65 64 20 65 61 63   is returned eac
2b0b0 68 20 74 69 6d 65 20 61 20 6e 65 77 20 72 6f 77  h time a new row
2b0c0 20 6f 66 20 64 61 74 61 20 69 73 20 72 65 61 64   of data is read
2b0d0 79 20 66 6f 72 20 70 72 6f 63 65 73 73 69 6e 67  y for processing
2b0e0 20 62 79 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 65   by the.** calle
2b0f0 72 2e 20 54 68 65 20 76 61 6c 75 65 73 20 6d 61  r. The values ma
2b100 79 20 62 65 20 61 63 63 65 73 73 65 64 20 75 73  y be accessed us
2b110 69 6e 67 20 74 68 65 20 5b 63 6f 6c 75 6d 6e 20  ing the [column 
2b120 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73  access functions
2b130 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74  ]..** sqlite3_st
2b140 65 70 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61  ep() is called a
2b150 67 61 69 6e 20 74 6f 20 72 65 74 72 69 65 76 65  gain to retrieve
2b160 20 74 68 65 20 6e 65 78 74 20 72 6f 77 20 6f 66   the next row of
2b170 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53   data..**.** ^[S
2b180 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6d 65 61  QLITE_ERROR] mea
2b190 6e 73 20 74 68 61 74 20 61 20 72 75 6e 2d 74 69  ns that a run-ti
2b1a0 6d 65 20 65 72 72 6f 72 20 28 73 75 63 68 20 61  me error (such a
2b1b0 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a  s a constraint.*
2b1c0 2a 20 76 69 6f 6c 61 74 69 6f 6e 29 20 68 61 73  * violation) has
2b1d0 20 6f 63 63 75 72 72 65 64 2e 20 20 73 71 6c 69   occurred.  sqli
2b1e0 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c  te3_step() shoul
2b1f0 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20  d not be called 
2b200 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20  again on.** the 
2b210 56 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f 72 6d 61  VM. More informa
2b220 74 69 6f 6e 20 6d 61 79 20 62 65 20 66 6f 75 6e  tion may be foun
2b230 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71  d by calling [sq
2b240 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e  lite3_errmsg()].
2b250 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 20 6c 65  .** ^With the le
2b260 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20  gacy interface, 
2b270 61 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20  a more specific 
2b280 65 72 72 6f 72 20 63 6f 64 65 20 28 66 6f 72 20  error code (for 
2b290 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c  example,.** [SQL
2b2a0 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2c 20  ITE_INTERRUPT], 
2b2b0 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2c  [SQLITE_SCHEMA],
2b2c0 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54   [SQLITE_CORRUPT
2b2d0 5d 2c 20 61 6e 64 20 73 6f 20 66 6f 72 74 68 29  ], and so forth)
2b2e0 0a 2a 2a 20 63 61 6e 20 62 65 20 6f 62 74 61 69  .** can be obtai
2b2f0 6e 65 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b  ned by calling [
2b300 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
2b310 20 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70   on the.** [prep
2b320 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
2b330 20 20 5e 49 6e 20 74 68 65 20 22 76 32 22 20 69    ^In the "v2" i
2b340 6e 74 65 72 66 61 63 65 2c 0a 2a 2a 20 74 68 65  nterface,.** the
2b350 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 65   more specific e
2b360 72 72 6f 72 20 63 6f 64 65 20 69 73 20 72 65 74  rror code is ret
2b370 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79 20 62  urned directly b
2b380 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  y sqlite3_step()
2b390 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ..**.** [SQLITE_
2b3a0 4d 49 53 55 53 45 5d 20 6d 65 61 6e 73 20 74 68  MISUSE] means th
2b3b0 61 74 20 74 68 65 20 74 68 69 73 20 72 6f 75 74  at the this rout
2b3c0 69 6e 65 20 77 61 73 20 63 61 6c 6c 65 64 20 69  ine was called i
2b3d0 6e 61 70 70 72 6f 70 72 69 61 74 65 6c 79 2e 0a  nappropriately..
2b3e0 2a 2a 20 50 65 72 68 61 70 73 20 69 74 20 77 61  ** Perhaps it wa
2b3f0 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 70  s called on a [p
2b400 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2b410 74 5d 20 74 68 61 74 20 68 61 73 0a 2a 2a 20 61  t] that has.** a
2b420 6c 72 65 61 64 79 20 62 65 65 6e 20 5b 73 71 6c  lready been [sql
2b430 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20  ite3_finalize | 
2b440 66 69 6e 61 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e  finalized] or on
2b450 20 6f 6e 65 20 74 68 61 74 20 68 61 64 0a 2a 2a   one that had.**
2b460 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75   previously retu
2b470 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 45 52 52  rned [SQLITE_ERR
2b480 4f 52 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44  OR] or [SQLITE_D
2b490 4f 4e 45 5d 2e 20 20 4f 72 20 69 74 20 63 6f 75  ONE].  Or it cou
2b4a0 6c 64 0a 2a 2a 20 62 65 20 74 68 65 20 63 61 73  ld.** be the cas
2b4b0 65 20 74 68 61 74 20 74 68 65 20 73 61 6d 65 20  e that the same 
2b4c0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2b4d0 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 75 73 65  ion is being use
2b4e0 64 20 62 79 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d  d by two or.** m
2b4f0 6f 72 65 20 74 68 72 65 61 64 73 20 61 74 20 74  ore threads at t
2b500 68 65 20 73 61 6d 65 20 6d 6f 6d 65 6e 74 20 69  he same moment i
2b510 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f  n time..**.** Fo
2b520 72 20 61 6c 6c 20 76 65 72 73 69 6f 6e 73 20 6f  r all versions o
2b530 66 20 53 51 4c 69 74 65 20 75 70 20 74 6f 20 61  f SQLite up to a
2b540 6e 64 20 69 6e 63 6c 75 64 69 6e 67 20 33 2e 36  nd including 3.6
2b550 2e 32 33 2e 31 2c 20 61 20 63 61 6c 6c 20 74 6f  .23.1, a call to
2b560 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  .** [sqlite3_res
2b570 65 74 28 29 5d 20 77 61 73 20 72 65 71 75 69 72  et()] was requir
2b580 65 64 20 61 66 74 65 72 20 73 71 6c 69 74 65 33  ed after sqlite3
2b590 5f 73 74 65 70 28 29 20 72 65 74 75 72 6e 65 64  _step() returned
2b5a0 20 61 6e 79 74 68 69 6e 67 0a 2a 2a 20 6f 74 68   anything.** oth
2b5b0 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
2b5c0 52 4f 57 5d 20 62 65 66 6f 72 65 20 61 6e 79 20  ROW] before any 
2b5d0 73 75 62 73 65 71 75 65 6e 74 20 69 6e 76 6f 63  subsequent invoc
2b5e0 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 73 71 6c 69  ation of.** sqli
2b5f0 74 65 33 5f 73 74 65 70 28 29 2e 20 20 46 61 69  te3_step().  Fai
2b600 6c 75 72 65 20 74 6f 20 72 65 73 65 74 20 74 68  lure to reset th
2b610 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  e prepared state
2b620 6d 65 6e 74 20 75 73 69 6e 67 20 0a 2a 2a 20 5b  ment using .** [
2b630 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
2b640 20 77 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e   would result in
2b650 20 61 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55   an [SQLITE_MISU
2b660 53 45 5d 20 72 65 74 75 72 6e 20 66 72 6f 6d 0a  SE] return from.
2b670 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  ** sqlite3_step(
2b680 29 2e 20 20 42 75 74 20 61 66 74 65 72 20 76 65  ).  But after ve
2b690 72 73 69 6f 6e 20 33 2e 36 2e 32 33 2e 31 2c 20  rsion 3.6.23.1, 
2b6a0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 62  sqlite3_step() b
2b6b0 65 67 61 6e 0a 2a 2a 20 63 61 6c 6c 69 6e 67 20  egan.** calling 
2b6c0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
2b6d0 5d 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  ] automatically 
2b6e0 69 6e 20 74 68 69 73 20 63 69 72 63 75 6d 73 74  in this circumst
2b6f0 61 6e 63 65 20 72 61 74 68 65 72 0a 2a 2a 20 74  ance rather.** t
2b700 68 61 6e 20 72 65 74 75 72 6e 69 6e 67 20 5b 53  han returning [S
2b710 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20  QLITE_MISUSE].  
2b720 54 68 69 73 20 69 73 20 6e 6f 74 20 63 6f 6e 73  This is not cons
2b730 69 64 65 72 65 64 20 61 20 63 6f 6d 70 61 74 69  idered a compati
2b740 62 69 6c 69 74 79 0a 2a 2a 20 62 72 65 61 6b 20  bility.** break 
2b750 62 65 63 61 75 73 65 20 61 6e 79 20 61 70 70 6c  because any appl
2b760 69 63 61 74 69 6f 6e 20 74 68 61 74 20 65 76 65  ication that eve
2b770 72 20 72 65 63 65 69 76 65 73 20 61 6e 20 53 51  r receives an SQ
2b780 4c 49 54 45 5f 4d 49 53 55 53 45 20 65 72 72 6f  LITE_MISUSE erro
2b790 72 0a 2a 2a 20 69 73 20 62 72 6f 6b 65 6e 20 62  r.** is broken b
2b7a0 79 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54  y definition.  T
2b7b0 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  he [SQLITE_OMIT_
2b7c0 41 55 54 4f 52 45 53 45 54 5d 20 63 6f 6d 70 69  AUTORESET] compi
2b7d0 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 0a 2a  le-time option.*
2b7e0 2a 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  * can be used to
2b7f0 20 72 65 73 74 6f 72 65 20 74 68 65 20 6c 65 67   restore the leg
2b800 61 63 79 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a  acy behavior..**
2b810 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20 49 6e 74  .** <b>Goofy Int
2b820 65 72 66 61 63 65 20 41 6c 65 72 74 3a 3c 2f 62  erface Alert:</b
2b830 3e 20 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20  > In the legacy 
2b840 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 73  interface, the s
2b850 71 6c 69 74 65 33 5f 73 74 65 70 28 29 0a 2a 2a  qlite3_step().**
2b860 20 41 50 49 20 61 6c 77 61 79 73 20 72 65 74 75   API always retu
2b870 72 6e 73 20 61 20 67 65 6e 65 72 69 63 20 65 72  rns a generic er
2b880 72 6f 72 20 63 6f 64 65 2c 20 5b 53 51 4c 49 54  ror code, [SQLIT
2b890 45 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77  E_ERROR], follow
2b8a0 69 6e 67 20 61 6e 79 0a 2a 2a 20 65 72 72 6f 72  ing any.** error
2b8b0 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
2b8c0 49 54 45 5f 42 55 53 59 5d 20 61 6e 64 20 5b 53  ITE_BUSY] and [S
2b8d0 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20  QLITE_MISUSE].  
2b8e0 59 6f 75 20 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a  You must call.**
2b8f0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2b900 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66  )] or [sqlite3_f
2b910 69 6e 61 6c 69 7a 65 28 29 5d 20 69 6e 20 6f 72  inalize()] in or
2b920 64 65 72 20 74 6f 20 66 69 6e 64 20 6f 6e 65 20  der to find one 
2b930 6f 66 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66  of the.** specif
2b940 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d  ic [error codes]
2b950 20 74 68 61 74 20 62 65 74 74 65 72 20 64 65 73   that better des
2b960 63 72 69 62 65 73 20 74 68 65 20 65 72 72 6f 72  cribes the error
2b970 2e 0a 2a 2a 20 57 65 20 61 64 6d 69 74 20 74 68  ..** We admit th
2b980 61 74 20 74 68 69 73 20 69 73 20 61 20 67 6f 6f  at this is a goo
2b990 66 79 20 64 65 73 69 67 6e 2e 20 20 54 68 65 20  fy design.  The 
2b9a0 70 72 6f 62 6c 65 6d 20 68 61 73 20 62 65 65 6e  problem has been
2b9b0 20 66 69 78 65 64 0a 2a 2a 20 77 69 74 68 20 74   fixed.** with t
2b9c0 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  he "v2" interfac
2b9d0 65 2e 20 20 49 66 20 79 6f 75 20 70 72 65 70 61  e.  If you prepa
2b9e0 72 65 20 61 6c 6c 20 6f 66 20 79 6f 75 72 20 53  re all of your S
2b9f0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  QL statements.**
2ba00 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73   using either [s
2ba10 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2ba20 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  2()] or [sqlite3
2ba30 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
2ba40 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 74   instead.** of t
2ba50 68 65 20 6c 65 67 61 63 79 20 5b 73 71 6c 69 74  he legacy [sqlit
2ba60 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e  e3_prepare()] an
2ba70 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  d [sqlite3_prepa
2ba80 72 65 31 36 28 29 5d 20 69 6e 74 65 72 66 61 63  re16()] interfac
2ba90 65 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  es,.** then the 
2baa0 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 5b 65  more specific [e
2bab0 72 72 6f 72 20 63 6f 64 65 73 5d 20 61 72 65 20  rror codes] are 
2bac0 72 65 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c  returned directl
2bad0 79 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f  y.** by sqlite3_
2bae0 73 74 65 70 28 29 2e 20 20 54 68 65 20 75 73 65  step().  The use
2baf0 20 6f 66 20 74 68 65 20 22 76 32 22 20 69 6e 74   of the "v2" int
2bb00 65 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d  erface is recomm
2bb10 65 6e 64 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ended..*/.int sq
2bb20 6c 69 74 65 33 5f 73 74 65 70 28 73 71 6c 69 74  lite3_step(sqlit
2bb30 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a  e3_stmt*);../*.*
2bb40 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62  * CAPI3REF: Numb
2bb50 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
2bb60 20 61 20 72 65 73 75 6c 74 20 73 65 74 0a 2a 2a   a result set.**
2bb70 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2bb80 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 69  _data_count(P) i
2bb90 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
2bba0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
2bbb0 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 0a 2a 2a  olumns in the.**
2bbc0 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20   current row of 
2bbd0 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f  the result set o
2bbe0 66 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  f [prepared stat
2bbf0 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 49 66  ement] P..** ^If
2bc00 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
2bc10 65 6e 74 20 50 20 64 6f 65 73 20 6e 6f 74 20 68  ent P does not h
2bc20 61 76 65 20 72 65 73 75 6c 74 73 20 72 65 61 64  ave results read
2bc30 79 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 28  y to return.** (
2bc40 76 69 61 20 63 61 6c 6c 73 20 74 6f 20 74 68 65  via calls to the
2bc50 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
2bc60 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f 63  _int | sqlite3_c
2bc70 6f 6c 75 6d 6e 5f 2a 28 29 5d 20 6f 66 0a 2a 2a  olumn_*()] of.**
2bc80 20 69 6e 74 65 72 66 61 63 65 73 29 20 74 68 65   interfaces) the
2bc90 6e 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63  n sqlite3_data_c
2bca0 6f 75 6e 74 28 50 29 20 72 65 74 75 72 6e 73 20  ount(P) returns 
2bcb0 30 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  0..** ^The sqlit
2bcc0 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29  e3_data_count(P)
2bcd0 20 72 6f 75 74 69 6e 65 20 61 6c 73 6f 20 72 65   routine also re
2bce0 74 75 72 6e 73 20 30 20 69 66 20 50 20 69 73 20  turns 0 if P is 
2bcf0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
2bd00 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2bd10 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f  data_count(P) ro
2bd20 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30 20  utine returns 0 
2bd30 69 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 20  if the previous 
2bd40 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  call to.** [sqli
2bd50 74 65 33 5f 73 74 65 70 5d 28 50 29 20 72 65 74  te3_step](P) ret
2bd60 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 44 4f  urned [SQLITE_DO
2bd70 4e 45 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 74  NE].  ^The sqlit
2bd80 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29  e3_data_count(P)
2bd90 0a 2a 2a 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  .** will return 
2bda0 6e 6f 6e 2d 7a 65 72 6f 20 69 66 20 70 72 65 76  non-zero if prev
2bdb0 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 5b 73 71  ious call to [sq
2bdc0 6c 69 74 65 33 5f 73 74 65 70 5d 28 50 29 20 72  lite3_step](P) r
2bdd0 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 53 51 4c 49  eturned.** [SQLI
2bde0 54 45 5f 52 4f 57 5d 2c 20 65 78 63 65 70 74 20  TE_ROW], except 
2bdf0 69 6e 20 74 68 65 20 63 61 73 65 20 6f 66 20 74  in the case of t
2be00 68 65 20 5b 50 52 41 47 4d 41 20 69 6e 63 72 65  he [PRAGMA incre
2be10 6d 65 6e 74 61 6c 5f 76 61 63 75 75 6d 5d 0a 2a  mental_vacuum].*
2be20 2a 20 77 68 65 72 65 20 69 74 20 61 6c 77 61 79  * where it alway
2be30 73 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 73  s returns zero s
2be40 69 6e 63 65 20 65 61 63 68 20 73 74 65 70 20 6f  ince each step o
2be50 66 20 74 68 61 74 20 6d 75 6c 74 69 2d 73 74 65  f that multi-ste
2be60 70 0a 2a 2a 20 70 72 61 67 6d 61 20 72 65 74 75  p.** pragma retu
2be70 72 6e 73 20 30 20 63 6f 6c 75 6d 6e 73 20 6f 66  rns 0 columns of
2be80 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 53 65 65   data..**.** See
2be90 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
2bea0 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 0a  column_count()].
2beb0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 64  */.int sqlite3_d
2bec0 61 74 61 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65  ata_count(sqlite
2bed0 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
2bee0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2bef0 20 46 75 6e 64 61 6d 65 6e 74 61 6c 20 44 61 74   Fundamental Dat
2bf00 61 74 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52  atypes.** KEYWOR
2bf10 44 53 3a 20 53 51 4c 49 54 45 5f 54 45 58 54 0a  DS: SQLITE_TEXT.
2bf20 2a 2a 0a 2a 2a 20 5e 28 45 76 65 72 79 20 76 61  **.** ^(Every va
2bf30 6c 75 65 20 69 6e 20 53 51 4c 69 74 65 20 68 61  lue in SQLite ha
2bf40 73 20 6f 6e 65 20 6f 66 20 66 69 76 65 20 66 75  s one of five fu
2bf50 6e 64 61 6d 65 6e 74 61 6c 20 64 61 74 61 74 79  ndamental dataty
2bf60 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  pes:.**.** <ul>.
2bf70 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 73  ** <li> 64-bit s
2bf80 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a  igned integer.**
2bf90 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 49 45 45   <li> 64-bit IEE
2bfa0 45 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  E floating point
2bfb0 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20   number.** <li> 
2bfc0 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42  string.** <li> B
2bfd0 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c  LOB.** <li> NULL
2bfe0 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a  .** </ul>)^.**.*
2bff0 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74  * These constant
2c000 73 20 61 72 65 20 63 6f 64 65 73 20 66 6f 72 20  s are codes for 
2c010 65 61 63 68 20 6f 66 20 74 68 6f 73 65 20 74 79  each of those ty
2c020 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20  pes..**.** Note 
2c030 74 68 61 74 20 74 68 65 20 53 51 4c 49 54 45 5f  that the SQLITE_
2c040 54 45 58 54 20 63 6f 6e 73 74 61 6e 74 20 77 61  TEXT constant wa
2c050 73 20 61 6c 73 6f 20 75 73 65 64 20 69 6e 20 53  s also used in S
2c060 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32 0a  QLite version 2.
2c070 2a 2a 20 66 6f 72 20 61 20 63 6f 6d 70 6c 65 74  ** for a complet
2c080 65 6c 79 20 64 69 66 66 65 72 65 6e 74 20 6d 65  ely different me
2c090 61 6e 69 6e 67 2e 20 20 53 6f 66 74 77 61 72 65  aning.  Software
2c0a0 20 74 68 61 74 20 6c 69 6e 6b 73 20 61 67 61 69   that links agai
2c0b0 6e 73 74 20 62 6f 74 68 0a 2a 2a 20 53 51 4c 69  nst both.** SQLi
2c0c0 74 65 20 76 65 72 73 69 6f 6e 20 32 20 61 6e 64  te version 2 and
2c0d0 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
2c0e0 33 20 73 68 6f 75 6c 64 20 75 73 65 20 53 51 4c  3 should use SQL
2c0f0 49 54 45 33 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a  ITE3_TEXT, not.*
2c100 2a 20 53 51 4c 49 54 45 5f 54 45 58 54 2e 0a 2a  * SQLITE_TEXT..*
2c110 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
2c120 5f 49 4e 54 45 47 45 52 20 20 31 0a 23 64 65 66  _INTEGER  1.#def
2c130 69 6e 65 20 53 51 4c 49 54 45 5f 46 4c 4f 41 54  ine SQLITE_FLOAT
2c140 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51      2.#define SQ
2c150 4c 49 54 45 5f 42 4c 4f 42 20 20 20 20 20 34 0a  LITE_BLOB     4.
2c160 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e  #define SQLITE_N
2c170 55 4c 4c 20 20 20 20 20 35 0a 23 69 66 64 65 66  ULL     5.#ifdef
2c180 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 20 75   SQLITE_TEXT.# u
2c190 6e 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54  ndef SQLITE_TEXT
2c1a0 0a 23 65 6c 73 65 0a 23 20 64 65 66 69 6e 65 20  .#else.# define 
2c1b0 53 51 4c 49 54 45 5f 54 45 58 54 20 20 20 20 20  SQLITE_TEXT     
2c1c0 33 0a 23 65 6e 64 69 66 0a 23 64 65 66 69 6e 65  3.#endif.#define
2c1d0 20 53 51 4c 49 54 45 33 5f 54 45 58 54 20 20 20   SQLITE3_TEXT   
2c1e0 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33    3../*.** CAPI3
2c1f0 52 45 46 3a 20 52 65 73 75 6c 74 20 56 61 6c 75  REF: Result Valu
2c200 65 73 20 46 72 6f 6d 20 41 20 51 75 65 72 79 0a  es From A Query.
2c210 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f  ** KEYWORDS: {co
2c220 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63  lumn access func
2c230 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  tions}.**.** The
2c240 73 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 6d  se routines form
2c250 20 74 68 65 20 22 72 65 73 75 6c 74 20 73 65 74   the "result set
2c260 22 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a  " interface..**.
2c270 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
2c280 65 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d  es return inform
2c290 61 74 69 6f 6e 20 61 62 6f 75 74 20 61 20 73 69  ation about a si
2c2a0 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66 20 74  ngle column of t
2c2b0 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65  he current.** re
2c2c0 73 75 6c 74 20 72 6f 77 20 6f 66 20 61 20 71 75  sult row of a qu
2c2d0 65 72 79 2e 20 20 5e 49 6e 20 65 76 65 72 79 20  ery.  ^In every 
2c2e0 63 61 73 65 20 74 68 65 20 66 69 72 73 74 20 61  case the first a
2c2f0 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69  rgument is a poi
2c300 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b  nter.** to the [
2c310 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2c320 6e 74 5d 20 74 68 61 74 20 69 73 20 62 65 69 6e  nt] that is bein
2c330 67 20 65 76 61 6c 75 61 74 65 64 20 28 74 68 65  g evaluated (the
2c340 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d   [sqlite3_stmt*]
2c350 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 72 65 74  .** that was ret
2c360 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  urned from [sqli
2c370 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
2c380 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74 73 20  ] or one of its 
2c390 76 61 72 69 61 6e 74 73 29 0a 2a 2a 20 61 6e 64  variants).** and
2c3a0 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
2c3b0 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65  ment is the inde
2c3c0 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20  x of the column 
2c3d0 66 6f 72 20 77 68 69 63 68 20 69 6e 66 6f 72 6d  for which inform
2c3e0 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20  ation.** should 
2c3f0 62 65 20 72 65 74 75 72 6e 65 64 2e 20 5e 54 68  be returned. ^Th
2c400 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d  e leftmost colum
2c410 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  n of the result 
2c420 73 65 74 20 68 61 73 20 74 68 65 20 69 6e 64 65  set has the inde
2c430 78 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 6e 75 6d  x 0..** ^The num
2c440 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
2c450 6e 20 74 68 65 20 72 65 73 75 6c 74 20 63 61 6e  n the result can
2c460 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64 20 75   be determined u
2c470 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  sing.** [sqlite3
2c480 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d  _column_count()]
2c490 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53  ..**.** If the S
2c4a0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65  QL statement doe
2c4b0 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20  s not currently 
2c4c0 70 6f 69 6e 74 20 74 6f 20 61 20 76 61 6c 69 64  point to a valid
2c4d0 20 72 6f 77 2c 20 6f 72 20 69 66 20 74 68 65 0a   row, or if the.
2c4e0 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e 64 65 78 20  ** column index 
2c4f0 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c  is out of range,
2c500 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 75   the result is u
2c510 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65  ndefined..** The
2c520 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 61 79 20  se routines may 
2c530 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 77  only be called w
2c540 68 65 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63  hen the most rec
2c550 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b  ent call to.** [
2c560 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
2c570 68 61 73 20 72 65 74 75 72 6e 65 64 20 5b 53 51  has returned [SQ
2c580 4c 49 54 45 5f 52 4f 57 5d 20 61 6e 64 20 6e 65  LITE_ROW] and ne
2c590 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  ither.** [sqlite
2c5a0 33 5f 72 65 73 65 74 28 29 5d 20 6e 6f 72 20 5b  3_reset()] nor [
2c5b0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2c5c0 28 29 5d 20 68 61 76 65 20 62 65 65 6e 20 63 61  ()] have been ca
2c5d0 6c 6c 65 64 20 73 75 62 73 65 71 75 65 6e 74 6c  lled subsequentl
2c5e0 79 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 6f 66 20  y..** If any of 
2c5f0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  these routines a
2c600 72 65 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20  re called after 
2c610 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
2c620 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
2c630 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20  _finalize()] or 
2c640 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 73  after [sqlite3_s
2c650 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 75 72  tep()] has retur
2c660 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e 67  ned.** something
2c670 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
2c680 49 54 45 5f 52 4f 57 5d 2c 20 74 68 65 20 72 65  ITE_ROW], the re
2c690 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69  sults are undefi
2c6a0 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c 69  ned..** If [sqli
2c6b0 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b  te3_step()] or [
2c6c0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
2c6d0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e   or [sqlite3_fin
2c6e0 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61 72 65 20  alize()].** are 
2c6f0 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 20 64 69  called from a di
2c700 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 20 77  fferent thread w
2c710 68 69 6c 65 20 61 6e 79 20 6f 66 20 74 68 65 73  hile any of thes
2c720 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72  e routines.** ar
2c730 65 20 70 65 6e 64 69 6e 67 2c 20 74 68 65 6e 20  e pending, then 
2c740 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20  the results are 
2c750 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
2c760 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f   ^The sqlite3_co
2c770 6c 75 6d 6e 5f 74 79 70 65 28 29 20 72 6f 75 74  lumn_type() rout
2c780 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 0a  ine returns the.
2c790 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47  ** [SQLITE_INTEG
2c7a0 45 52 20 7c 20 64 61 74 61 74 79 70 65 20 63 6f  ER | datatype co
2c7b0 64 65 5d 20 66 6f 72 20 74 68 65 20 69 6e 69 74  de] for the init
2c7c0 69 61 6c 20 64 61 74 61 20 74 79 70 65 0a 2a 2a  ial data type.**
2c7d0 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 63   of the result c
2c7e0 6f 6c 75 6d 6e 2e 20 20 5e 54 68 65 20 72 65 74  olumn.  ^The ret
2c7f0 75 72 6e 65 64 20 76 61 6c 75 65 20 69 73 20 6f  urned value is o
2c800 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e  ne of [SQLITE_IN
2c810 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49  TEGER],.** [SQLI
2c820 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49  TE_FLOAT], [SQLI
2c830 54 45 5f 54 45 58 54 5d 2c 20 5b 53 51 4c 49 54  TE_TEXT], [SQLIT
2c840 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c  E_BLOB], or [SQL
2c850 49 54 45 5f 4e 55 4c 4c 5d 2e 20 20 54 68 65 20  ITE_NULL].  The 
2c860 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65  value.** returne
2c870 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
2c880 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 6f 6e  umn_type() is on
2c890 6c 79 20 6d 65 61 6e 69 6e 67 66 75 6c 20 69 66  ly meaningful if
2c8a0 20 6e 6f 20 74 79 70 65 0a 2a 2a 20 63 6f 6e 76   no type.** conv
2c8b0 65 72 73 69 6f 6e 73 20 68 61 76 65 20 6f 63 63  ersions have occ
2c8c0 75 72 72 65 64 20 61 73 20 64 65 73 63 72 69 62  urred as describ
2c8d0 65 64 20 62 65 6c 6f 77 2e 20 20 41 66 74 65 72  ed below.  After
2c8e0 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69   a type conversi
2c8f0 6f 6e 2c 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65  on,.** the value
2c900 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
2c910 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
2c920 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  () is undefined.
2c930 20 20 46 75 74 75 72 65 0a 2a 2a 20 76 65 72 73    Future.** vers
2c940 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d  ions of SQLite m
2c950 61 79 20 63 68 61 6e 67 65 20 74 68 65 20 62 65  ay change the be
2c960 68 61 76 69 6f 72 20 6f 66 20 73 71 6c 69 74 65  havior of sqlite
2c970 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a  3_column_type().
2c980 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 74  ** following a t
2c990 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a  ype conversion..
2c9a0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  **.** ^If the re
2c9b0 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f  sult is a BLOB o
2c9c0 72 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 74  r UTF-8 string t
2c9d0 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f  hen the sqlite3_
2c9e0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a  column_bytes().*
2c9f0 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  * routine return
2ca00 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
2ca10 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c  bytes in that BL
2ca20 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a  OB or string..**
2ca30 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20   ^If the result 
2ca40 69 73 20 61 20 55 54 46 2d 31 36 20 73 74 72 69  is a UTF-16 stri
2ca50 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ng, then sqlite3
2ca60 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20  _column_bytes() 
2ca70 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20  converts.** the 
2ca80 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 38 20  string to UTF-8 
2ca90 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73  and then returns
2caa0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
2cab0 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ytes..** ^If the
2cac0 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d   result is a num
2cad0 65 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20  eric value then 
2cae0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2caf0 79 74 65 73 28 29 20 75 73 65 73 0a 2a 2a 20 5b  ytes() uses.** [
2cb00 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
2cb10 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74  ()] to convert t
2cb20 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55  hat value to a U
2cb30 54 46 2d 38 20 73 74 72 69 6e 67 20 61 6e 64 20  TF-8 string and 
2cb40 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e  returns.** the n
2cb50 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
2cb60 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a  n that string..*
2cb70 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
2cb80 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73   is NULL, then s
2cb90 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2cba0 74 65 73 28 29 20 72 65 74 75 72 6e 73 20 7a 65  tes() returns ze
2cbb0 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  ro..**.** ^If th
2cbc0 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c  e result is a BL
2cbd0 4f 42 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72  OB or UTF-16 str
2cbe0 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c  ing then the sql
2cbf0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2cc00 73 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65  s16().** routine
2cc10 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
2cc20 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
2cc30 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72  that BLOB or str
2cc40 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ing..** ^If the 
2cc50 72 65 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d  result is a UTF-
2cc60 38 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73  8 string, then s
2cc70 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2cc80 74 65 73 31 36 28 29 20 63 6f 6e 76 65 72 74 73  tes16() converts
2cc90 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74  .** the string t
2cca0 6f 20 55 54 46 2d 31 36 20 61 6e 64 20 74 68 65  o UTF-16 and the
2ccb0 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  n returns the nu
2ccc0 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a  mber of bytes..*
2ccd0 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
2cce0 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61   is a numeric va
2ccf0 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33  lue then sqlite3
2cd00 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
2cd10 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74  ) uses.** [sqlit
2cd20 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74  e3_snprintf()] t
2cd30 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76  o convert that v
2cd40 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 31 36  alue to a UTF-16
2cd50 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75   string and retu
2cd60 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65  rns.** the numbe
2cd70 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
2cd80 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49  at string..** ^I
2cd90 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
2cda0 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74  NULL, then sqlit
2cdb0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
2cdc0 36 28 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f  6() returns zero
2cdd0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 76 61 6c  ..**.** ^The val
2cde0 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ues returned by 
2cdf0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
2ce00 62 79 74 65 73 28 29 5d 20 61 6e 64 20 0a 2a 2a  bytes()] and .**
2ce10 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
2ce20 5f 62 79 74 65 73 31 36 28 29 5d 20 64 6f 20 6e  _bytes16()] do n
2ce30 6f 74 20 69 6e 63 6c 75 64 65 20 74 68 65 20 7a  ot include the z
2ce40 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 73 20  ero terminators 
2ce50 61 74 20 74 68 65 20 65 6e 64 0a 2a 2a 20 6f 66  at the end.** of
2ce60 20 74 68 65 20 73 74 72 69 6e 67 2e 20 20 5e 46   the string.  ^F
2ce70 6f 72 20 63 6c 61 72 69 74 79 3a 20 74 68 65 20  or clarity: the 
2ce80 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20  values returned 
2ce90 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  by.** [sqlite3_c
2cea0 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61  olumn_bytes()] a
2ceb0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  nd [sqlite3_colu
2cec0 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d 20 61 72  mn_bytes16()] ar
2ced0 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a  e the number of.
2cee0 2a 2a 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  ** bytes in the 
2cef0 73 74 72 69 6e 67 2c 20 6e 6f 74 20 74 68 65 20  string, not the 
2cf00 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63  number of charac
2cf10 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 53 74 72  ters..**.** ^Str
2cf20 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79  ings returned by
2cf30 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2cf40 74 65 78 74 28 29 20 61 6e 64 20 73 71 6c 69 74  text() and sqlit
2cf50 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
2cf60 28 29 2c 0a 2a 2a 20 65 76 65 6e 20 65 6d 70 74  (),.** even empt
2cf70 79 20 73 74 72 69 6e 67 73 2c 20 61 72 65 20 61  y strings, are a
2cf80 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69  lways zero-termi
2cf90 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 72 65 74  nated.  ^The ret
2cfa0 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 66 72 6f  urn.** value fro
2cfb0 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  m sqlite3_column
2cfc0 5f 62 6c 6f 62 28 29 20 66 6f 72 20 61 20 7a 65  _blob() for a ze
2cfd0 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 20 69  ro-length BLOB i
2cfe0 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
2cff0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6f 62 6a  ..**.** ^The obj
2d000 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 20  ect returned by 
2d010 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
2d020 76 61 6c 75 65 28 29 5d 20 69 73 20 61 6e 0a 2a  value()] is an.*
2d030 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  * [unprotected s
2d040 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
2d050 6a 65 63 74 2e 20 20 41 6e 20 75 6e 70 72 6f 74  ject.  An unprot
2d060 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
2d070 6c 75 65 20 6f 62 6a 65 63 74 0a 2a 2a 20 6d 61  lue object.** ma
2d080 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77  y only be used w
2d090 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  ith [sqlite3_bin
2d0a0 64 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b  d_value()] and [
2d0b0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
2d0c0 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49 66 20 74  alue()]..** If t
2d0d0 68 65 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20  he [unprotected 
2d0e0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
2d0f0 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62  bject returned b
2d100 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  y.** [sqlite3_co
2d110 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73  lumn_value()] is
2d120 20 75 73 65 64 20 69 6e 20 61 6e 79 20 6f 74 68   used in any oth
2d130 65 72 20 77 61 79 2c 20 69 6e 63 6c 75 64 69 6e  er way, includin
2d140 67 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f  g calls.** to ro
2d150 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c  utines like [sql
2d160 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 29  ite3_value_int()
2d170 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ], [sqlite3_valu
2d180 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72  e_text()],.** or
2d190 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
2d1a0 62 79 74 65 73 28 29 5d 2c 20 74 68 65 6e 20 74  bytes()], then t
2d1b0 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75  he behavior is u
2d1c0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
2d1d0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
2d1e0 74 74 65 6d 70 74 20 74 6f 20 63 6f 6e 76 65 72  ttempt to conver
2d1f0 74 20 74 68 65 20 76 61 6c 75 65 20 77 68 65 72  t the value wher
2d200 65 20 61 70 70 72 6f 70 72 69 61 74 65 2e 20 20  e appropriate.  
2d210 5e 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c  ^For.** example,
2d220 20 69 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c   if the internal
2d230 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20   representation 
2d240 69 73 20 46 4c 4f 41 54 20 61 6e 64 20 61 20 74  is FLOAT and a t
2d250 65 78 74 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73  ext result.** is
2d260 20 72 65 71 75 65 73 74 65 64 2c 20 5b 73 71 6c   requested, [sql
2d270 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d  ite3_snprintf()]
2d280 20 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61   is used interna
2d290 6c 6c 79 20 74 6f 20 70 65 72 66 6f 72 6d 20 74  lly to perform t
2d2a0 68 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e  he.** conversion
2d2b0 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20   automatically. 
2d2c0 20 5e 28 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67   ^(The following
2d2d0 20 74 61 62 6c 65 20 64 65 74 61 69 6c 73 20 74   table details t
2d2e0 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a  he conversions.*
2d2f0 2a 20 74 68 61 74 20 61 72 65 20 61 70 70 6c 69  * that are appli
2d300 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ed:.**.** <block
2d310 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65  quote>.** <table
2d320 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20   border="1">.** 
2d330 3c 74 72 3e 3c 74 68 3e 20 49 6e 74 65 72 6e 61  <tr><th> Interna
2d340 6c 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 52  l<br>Type <th> R
2d350 65 71 75 65 73 74 65 64 3c 62 72 3e 54 79 70 65  equested<br>Type
2d360 20 3c 74 68 3e 20 20 43 6f 6e 76 65 72 73 69 6f   <th>  Conversio
2d370 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  n.**.** <tr><td>
2d380 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 49    NULL    <td> I
2d390 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 52 65  NTEGER   <td> Re
2d3a0 73 75 6c 74 20 69 73 20 30 0a 2a 2a 20 3c 74 72  sult is 0.** <tr
2d3b0 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c  ><td>  NULL    <
2d3c0 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74  td>  FLOAT    <t
2d3d0 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30 2e 30  d> Result is 0.0
2d3e0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55  .** <tr><td>  NU
2d3f0 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58  LL    <td>   TEX
2d400 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74  T    <td> Result
2d410 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72   is NULL pointer
2d420 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55  .** <tr><td>  NU
2d430 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f  LL    <td>   BLO
2d440 42 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74  B    <td> Result
2d450 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72   is NULL pointer
2d460 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54  .** <tr><td> INT
2d470 45 47 45 52 20 20 3c 74 64 3e 20 20 46 4c 4f 41  EGER  <td>  FLOA
2d480 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72  T    <td> Conver
2d490 74 20 66 72 6f 6d 20 69 6e 74 65 67 65 72 20 74  t from integer t
2d4a0 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c  o float.** <tr><
2d4b0 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64  td> INTEGER  <td
2d4c0 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  >   TEXT    <td>
2d4d0 20 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67   ASCII rendering
2d4e0 20 6f 66 20 74 68 65 20 69 6e 74 65 67 65 72 0a   of the integer.
2d4f0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45  ** <tr><td> INTE
2d500 47 45 52 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42  GER  <td>   BLOB
2d510 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20 61 73      <td> Same as
2d520 20 49 4e 54 45 47 45 52 2d 3e 54 45 58 54 0a 2a   INTEGER->TEXT.*
2d530 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41  * <tr><td>  FLOA
2d540 54 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52  T   <td> INTEGER
2d550 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20     <td> Convert 
2d560 66 72 6f 6d 20 66 6c 6f 61 74 20 74 6f 20 69 6e  from float to in
2d570 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64  teger.** <tr><td
2d580 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20  >  FLOAT   <td> 
2d590 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41    TEXT    <td> A
2d5a0 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f  SCII rendering o
2d5b0 66 20 74 68 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c  f the float.** <
2d5c0 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20  tr><td>  FLOAT  
2d5d0 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20   <td>   BLOB    
2d5e0 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 46 4c 4f  <td> Same as FLO
2d5f0 41 54 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e  AT->TEXT.** <tr>
2d600 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74  <td>  TEXT    <t
2d610 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64  d> INTEGER   <td
2d620 3e 20 55 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20  > Use atoi().** 
2d630 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20  <tr><td>  TEXT  
2d640 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20    <td>  FLOAT   
2d650 20 3c 74 64 3e 20 55 73 65 20 61 74 6f 66 28 29   <td> Use atof()
2d660 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45  .** <tr><td>  TE
2d670 58 54 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f  XT    <td>   BLO
2d680 42 20 20 20 20 3c 74 64 3e 20 4e 6f 20 63 68 61  B    <td> No cha
2d690 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  nge.** <tr><td> 
2d6a0 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 49 4e   BLOB    <td> IN
2d6b0 54 45 47 45 52 20 20 20 3c 74 64 3e 20 43 6f 6e  TEGER   <td> Con
2d6c0 76 65 72 74 20 74 6f 20 54 45 58 54 20 74 68 65  vert to TEXT the
2d6d0 6e 20 75 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20  n use atoi().** 
2d6e0 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20  <tr><td>  BLOB  
2d6f0 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20    <td>  FLOAT   
2d700 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f   <td> Convert to
2d710 20 54 45 58 54 20 74 68 65 6e 20 75 73 65 20 61   TEXT then use a
2d720 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64  tof().** <tr><td
2d730 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20  >  BLOB    <td> 
2d740 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41    TEXT    <td> A
2d750 64 64 20 61 20 7a 65 72 6f 20 74 65 72 6d 69 6e  dd a zero termin
2d760 61 74 6f 72 20 69 66 20 6e 65 65 64 65 64 0a 2a  ator if needed.*
2d770 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f  * </table>.** </
2d780 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a  blockquote>)^.**
2d790 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 20 61 62  .** The table ab
2d7a0 6f 76 65 20 6d 61 6b 65 73 20 72 65 66 65 72 65  ove makes refere
2d7b0 6e 63 65 20 74 6f 20 73 74 61 6e 64 61 72 64 20  nce to standard 
2d7c0 43 20 6c 69 62 72 61 72 79 20 66 75 6e 63 74 69  C library functi
2d7d0 6f 6e 73 20 61 74 6f 69 28 29 0a 2a 2a 20 61 6e  ons atoi().** an
2d7e0 64 20 61 74 6f 66 28 29 2e 20 20 53 51 4c 69 74  d atof().  SQLit
2d7f0 65 20 64 6f 65 73 20 6e 6f 74 20 72 65 61 6c 6c  e does not reall
2d800 79 20 75 73 65 20 74 68 65 73 65 20 66 75 6e 63  y use these func
2d810 74 69 6f 6e 73 2e 20 20 49 74 20 68 61 73 20 69  tions.  It has i
2d820 74 73 0a 2a 2a 20 6f 77 6e 20 65 71 75 69 76 61  ts.** own equiva
2d830 6c 65 6e 74 20 69 6e 74 65 72 6e 61 6c 20 72 6f  lent internal ro
2d840 75 74 69 6e 65 73 2e 20 20 54 68 65 20 61 74 6f  utines.  The ato
2d850 69 28 29 20 61 6e 64 20 61 74 6f 66 28 29 20 6e  i() and atof() n
2d860 61 6d 65 73 20 61 72 65 0a 2a 2a 20 75 73 65 64  ames are.** used
2d870 20 69 6e 20 74 68 65 20 74 61 62 6c 65 20 66 6f   in the table fo
2d880 72 20 62 72 65 76 69 74 79 20 61 6e 64 20 62 65  r brevity and be
2d890 63 61 75 73 65 20 74 68 65 79 20 61 72 65 20 66  cause they are f
2d8a0 61 6d 69 6c 69 61 72 20 74 6f 20 6d 6f 73 74 0a  amiliar to most.
2d8b0 2a 2a 20 43 20 70 72 6f 67 72 61 6d 6d 65 72 73  ** C programmers
2d8c0 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ..**.** Note tha
2d8d0 74 20 77 68 65 6e 20 74 79 70 65 20 63 6f 6e 76  t when type conv
2d8e0 65 72 73 69 6f 6e 73 20 6f 63 63 75 72 2c 20 70  ersions occur, p
2d8f0 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64  ointers returned
2d900 20 62 79 20 70 72 69 6f 72 0a 2a 2a 20 63 61 6c   by prior.** cal
2d910 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ls to sqlite3_co
2d920 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73 71 6c  lumn_blob(), sql
2d930 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2d940 28 29 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71  (), and/or.** sq
2d950 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
2d960 74 31 36 28 29 20 6d 61 79 20 62 65 20 69 6e 76  t16() may be inv
2d970 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 20 54 79 70  alidated..** Typ
2d980 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 61 6e  e conversions an
2d990 64 20 70 6f 69 6e 74 65 72 20 69 6e 76 61 6c 69  d pointer invali
2d9a0 64 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 6f 63  dations might oc
2d9b0 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20 66 6f  cur.** in the fo
2d9c0 6c 6c 6f 77 69 6e 67 20 63 61 73 65 73 3a 0a 2a  llowing cases:.*
2d9d0 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
2d9e0 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f  > The initial co
2d9f0 6e 74 65 6e 74 20 69 73 20 61 20 42 4c 4f 42 20  ntent is a BLOB 
2da00 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  and sqlite3_colu
2da10 6d 6e 5f 74 65 78 74 28 29 20 6f 72 0a 2a 2a 20  mn_text() or.** 
2da20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c       sqlite3_col
2da30 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20  umn_text16() is 
2da40 63 61 6c 6c 65 64 2e 20 20 41 20 7a 65 72 6f 2d  called.  A zero-
2da50 74 65 72 6d 69 6e 61 74 6f 72 20 6d 69 67 68 74  terminator might
2da60 0a 2a 2a 20 20 20 20 20 20 6e 65 65 64 20 74 6f  .**      need to
2da70 20 62 65 20 61 64 64 65 64 20 74 6f 20 74 68 65   be added to the
2da80 20 73 74 72 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a   string.</li>.**
2da90 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61   <li> The initia
2daa0 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46  l content is UTF
2dab0 2d 38 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69  -8 text and sqli
2dac0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2dad0 31 36 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20  16() or.**      
2dae0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2daf0 65 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65  ext16() is calle
2db00 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20  d.  The content 
2db10 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65  must be converte
2db20 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46  d.**      to UTF
2db30 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69  -16.</li>.** <li
2db40 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f  > The initial co
2db50 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 31 36 20  ntent is UTF-16 
2db60 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33  text and sqlite3
2db70 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20  _column_bytes() 
2db80 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74  or.**      sqlit
2db90 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
2dba0 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65   is called.  The
2dbb0 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65   content must be
2dbc0 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20   converted.**   
2dbd0 20 20 20 74 6f 20 55 54 46 2d 38 2e 3c 2f 6c 69     to UTF-8.</li
2dbe0 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  >.** </ul>.**.**
2dbf0 20 5e 43 6f 6e 76 65 72 73 69 6f 6e 73 20 62 65   ^Conversions be
2dc00 74 77 65 65 6e 20 55 54 46 2d 31 36 62 65 20 61  tween UTF-16be a
2dc10 6e 64 20 55 54 46 2d 31 36 6c 65 20 61 72 65 20  nd UTF-16le are 
2dc20 61 6c 77 61 79 73 20 64 6f 6e 65 20 69 6e 20 70  always done in p
2dc30 6c 61 63 65 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e  lace and do.** n
2dc40 6f 74 20 69 6e 76 61 6c 69 64 61 74 65 20 61 20  ot invalidate a 
2dc50 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 2c 20 74  prior pointer, t
2dc60 68 6f 75 67 68 20 6f 66 20 63 6f 75 72 73 65 20  hough of course 
2dc70 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74  the content of t
2dc80 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 74 68 61  he buffer.** tha
2dc90 74 20 74 68 65 20 70 72 69 6f 72 20 70 6f 69 6e  t the prior poin
2dca0 74 65 72 20 72 65 66 65 72 65 6e 63 65 73 20 77  ter references w
2dcb0 69 6c 6c 20 68 61 76 65 20 62 65 65 6e 20 6d 6f  ill have been mo
2dcc0 64 69 66 69 65 64 2e 20 20 4f 74 68 65 72 20 6b  dified.  Other k
2dcd0 69 6e 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65  inds.** of conve
2dce0 72 73 69 6f 6e 20 61 72 65 20 64 6f 6e 65 20 69  rsion are done i
2dcf0 6e 20 70 6c 61 63 65 20 77 68 65 6e 20 69 74 20  n place when it 
2dd00 69 73 20 70 6f 73 73 69 62 6c 65 2c 20 62 75 74  is possible, but
2dd10 20 73 6f 6d 65 74 69 6d 65 73 20 74 68 65 79 0a   sometimes they.
2dd20 2a 2a 20 61 72 65 20 6e 6f 74 20 70 6f 73 73 69  ** are not possi
2dd30 62 6c 65 20 61 6e 64 20 69 6e 20 74 68 6f 73 65  ble and in those
2dd40 20 63 61 73 65 73 20 70 72 69 6f 72 20 70 6f 69   cases prior poi
2dd50 6e 74 65 72 73 20 61 72 65 20 69 6e 76 61 6c 69  nters are invali
2dd60 64 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  dated..**.** The
2dd70 20 73 61 66 65 73 74 20 61 6e 64 20 65 61 73 69   safest and easi
2dd80 65 73 74 20 74 6f 20 72 65 6d 65 6d 62 65 72 20  est to remember 
2dd90 70 6f 6c 69 63 79 20 69 73 20 74 6f 20 69 6e 76  policy is to inv
2dda0 6f 6b 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e  oke these routin
2ddb0 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f 66 20  es.** in one of 
2ddc0 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 77 61  the following wa
2ddd0 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  ys:.**.** <ul>.*
2dde0 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63  *  <li>sqlite3_c
2ddf0 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 66 6f 6c  olumn_text() fol
2de00 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33  lowed by sqlite3
2de10 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c  _column_bytes()<
2de20 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c  /li>.**  <li>sql
2de30 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
2de40 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73  () followed by s
2de50 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2de60 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c  tes()</li>.**  <
2de70 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  li>sqlite3_colum
2de80 6e 5f 74 65 78 74 31 36 28 29 20 66 6f 6c 6c 6f  n_text16() follo
2de90 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  wed by sqlite3_c
2dea0 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 3c  olumn_bytes16()<
2deb0 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  /li>.** </ul>.**
2dec0 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  .** In other wor
2ded0 64 73 2c 20 79 6f 75 20 73 68 6f 75 6c 64 20 63  ds, you should c
2dee0 61 6c 6c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  all sqlite3_colu
2def0 6d 6e 5f 74 65 78 74 28 29 2c 0a 2a 2a 20 73 71  mn_text(),.** sq
2df00 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
2df10 62 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f  b(), or sqlite3_
2df20 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20  column_text16() 
2df30 66 69 72 73 74 20 74 6f 20 66 6f 72 63 65 20 74  first to force t
2df40 68 65 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 74  he result.** int
2df50 6f 20 74 68 65 20 64 65 73 69 72 65 64 20 66 6f  o the desired fo
2df60 72 6d 61 74 2c 20 74 68 65 6e 20 69 6e 76 6f 6b  rmat, then invok
2df70 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
2df80 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 73  _bytes() or.** s
2df90 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2dfa0 74 65 73 31 36 28 29 20 74 6f 20 66 69 6e 64 20  tes16() to find 
2dfb0 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
2dfc0 72 65 73 75 6c 74 2e 20 20 44 6f 20 6e 6f 74 20  result.  Do not 
2dfd0 6d 69 78 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20  mix calls.** to 
2dfe0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2dff0 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33  ext() or sqlite3
2e000 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 77  _column_blob() w
2e010 69 74 68 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20  ith calls to.** 
2e020 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2e030 79 74 65 73 31 36 28 29 2c 20 61 6e 64 20 64 6f  ytes16(), and do
2e040 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 20 74   not mix calls t
2e050 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  o sqlite3_column
2e060 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 77 69 74  _text16().** wit
2e070 68 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  h calls to sqlit
2e080 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
2e090 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 6f  )..**.** ^The po
2e0a0 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 20  inters returned 
2e0b0 61 72 65 20 76 61 6c 69 64 20 75 6e 74 69 6c 20  are valid until 
2e0c0 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f  a type conversio
2e0d0 6e 20 6f 63 63 75 72 73 20 61 73 0a 2a 2a 20 64  n occurs as.** d
2e0e0 65 73 63 72 69 62 65 64 20 61 62 6f 76 65 2c 20  escribed above, 
2e0f0 6f 72 20 75 6e 74 69 6c 20 5b 73 71 6c 69 74 65  or until [sqlite
2e100 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71  3_step()] or [sq
2e110 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
2e120 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  r.** [sqlite3_fi
2e130 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20 63 61 6c  nalize()] is cal
2e140 6c 65 64 2e 20 20 5e 54 68 65 20 6d 65 6d 6f 72  led.  ^The memor
2e150 79 20 73 70 61 63 65 20 75 73 65 64 20 74 6f 20  y space used to 
2e160 68 6f 6c 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20  hold strings.** 
2e170 61 6e 64 20 42 4c 4f 42 73 20 69 73 20 66 72 65  and BLOBs is fre
2e180 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ed automatically
2e190 2e 20 20 44 6f 20 3c 62 3e 6e 6f 74 3c 2f 62 3e  .  Do <b>not</b>
2e1a0 20 70 61 73 73 20 74 68 65 20 70 6f 69 6e 74 65   pass the pointe
2e1b0 72 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b  rs returned.** [
2e1c0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2e1d0 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  lob()], [sqlite3
2e1e0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c  _column_text()],
2e1f0 20 65 74 63 2e 20 69 6e 74 6f 0a 2a 2a 20 5b 73   etc. into.** [s
2e200 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a  qlite3_free()]..
2e210 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 20 6d 65 6d  **.** ^(If a mem
2e220 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65  ory allocation e
2e230 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69  rror occurs duri
2e240 6e 67 20 74 68 65 20 65 76 61 6c 75 61 74 69 6f  ng the evaluatio
2e250 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74  n of any.** of t
2e260 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2c 20 61  hese routines, a
2e270 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 69   default value i
2e280 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65  s returned.  The
2e290 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 0a 2a   default value.*
2e2a0 2a 20 69 73 20 65 69 74 68 65 72 20 74 68 65 20  * is either the 
2e2b0 69 6e 74 65 67 65 72 20 30 2c 20 74 68 65 20 66  integer 0, the f
2e2c0 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75  loating point nu
2e2d0 6d 62 65 72 20 30 2e 30 2c 20 6f 72 20 61 20 4e  mber 0.0, or a N
2e2e0 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e 20  ULL.** pointer. 
2e2f0 20 53 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   Subsequent call
2e300 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72  s to [sqlite3_er
2e310 72 63 6f 64 65 28 29 5d 20 77 69 6c 6c 20 72 65  rcode()] will re
2e320 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  turn.** [SQLITE_
2e330 4e 4f 4d 45 4d 5d 2e 29 5e 0a 2a 2f 0a 63 6f 6e  NOMEM].)^.*/.con
2e340 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
2e350 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c  _column_blob(sql
2e360 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
2e370 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74  iCol);.int sqlit
2e380 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
2e390 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2e3a0 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71  nt iCol);.int sq
2e3b0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2e3c0 65 73 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  es16(sqlite3_stm
2e3d0 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 64  t*, int iCol);.d
2e3e0 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f  ouble sqlite3_co
2e3f0 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28 73 71 6c 69  lumn_double(sqli
2e400 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
2e410 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  Col);.int sqlite
2e420 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c  3_column_int(sql
2e430 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
2e440 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 69  iCol);.sqlite3_i
2e450 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 63 6f 6c  nt64 sqlite3_col
2e460 75 6d 6e 5f 69 6e 74 36 34 28 73 71 6c 69 74 65  umn_int64(sqlite
2e470 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
2e480 6c 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e  l);.const unsign
2e490 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  ed char *sqlite3
2e4a0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 73 71 6c  _column_text(sql
2e4b0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
2e4c0 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  iCol);.const voi
2e4d0 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
2e4e0 6e 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33  n_text16(sqlite3
2e4f0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
2e500 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
2e510 6f 6c 75 6d 6e 5f 74 79 70 65 28 73 71 6c 69 74  olumn_type(sqlit
2e520 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
2e530 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 76 61 6c  ol);.sqlite3_val
2e540 75 65 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ue *sqlite3_colu
2e550 6d 6e 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33  mn_value(sqlite3
2e560 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
2e570 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2e580 45 46 3a 20 44 65 73 74 72 6f 79 20 41 20 50 72  EF: Destroy A Pr
2e590 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
2e5a0 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 5e 54   Object.**.** ^T
2e5b0 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  he sqlite3_final
2e5c0 69 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69  ize() function i
2e5d0 73 20 63 61 6c 6c 65 64 20 74 6f 20 64 65 6c 65  s called to dele
2e5e0 74 65 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  te a [prepared s
2e5f0 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 49  tatement]..** ^I
2e600 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  f the most recen
2e610 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20  t evaluation of 
2e620 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 65 6e  the statement en
2e630 63 6f 75 6e 74 65 72 65 64 20 6e 6f 20 65 72 72  countered no err
2e640 6f 72 73 0a 2a 2a 20 6f 72 20 69 66 20 74 68 65  ors.** or if the
2e650 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 65   statement is ne
2e660 76 65 72 20 62 65 65 6e 20 65 76 61 6c 75 61 74  ver been evaluat
2e670 65 64 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ed, then sqlite3
2e680 5f 66 69 6e 61 6c 69 7a 65 28 29 20 72 65 74 75  _finalize() retu
2e690 72 6e 73 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b  rns.** SQLITE_OK
2e6a0 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20  .  ^If the most 
2e6b0 72 65 63 65 6e 74 20 65 76 61 6c 75 61 74 69 6f  recent evaluatio
2e6c0 6e 20 6f 66 20 73 74 61 74 65 6d 65 6e 74 20 53  n of statement S
2e6d0 20 66 61 69 6c 65 64 2c 20 74 68 65 6e 0a 2a 2a   failed, then.**
2e6e0 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a   sqlite3_finaliz
2e6f0 65 28 53 29 20 72 65 74 75 72 6e 73 20 74 68 65  e(S) returns the
2e700 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72   appropriate [er
2e710 72 6f 72 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20  ror code] or.** 
2e720 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20  [extended error 
2e730 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  code]..**.** ^Th
2e740 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69  e sqlite3_finali
2e750 7a 65 28 53 29 20 72 6f 75 74 69 6e 65 20 63 61  ze(S) routine ca
2e760 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 74 20 61  n be called at a
2e770 6e 79 20 70 6f 69 6e 74 20 64 75 72 69 6e 67 0a  ny point during.
2e780 2a 2a 20 74 68 65 20 6c 69 66 65 20 63 79 63 6c  ** the life cycl
2e790 65 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73  e of [prepared s
2e7a0 74 61 74 65 6d 65 6e 74 5d 20 53 3a 0a 2a 2a 20  tatement] S:.** 
2e7b0 62 65 66 6f 72 65 20 73 74 61 74 65 6d 65 6e 74  before statement
2e7c0 20 53 20 69 73 20 65 76 65 72 20 65 76 61 6c 75   S is ever evalu
2e7d0 61 74 65 64 2c 20 61 66 74 65 72 0a 2a 2a 20 6f  ated, after.** o
2e7e0 6e 65 20 6f 72 20 6d 6f 72 65 20 63 61 6c 6c 73  ne or more calls
2e7f0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   to [sqlite3_res
2e800 65 74 28 29 5d 2c 20 6f 72 20 61 66 74 65 72 20  et()], or after 
2e810 61 6e 79 20 63 61 6c 6c 0a 2a 2a 20 74 6f 20 5b  any call.** to [
2e820 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
2e830 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68  regardless of wh
2e840 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65  ether or not the
2e850 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73 0a 2a   statement has.*
2e860 2a 20 63 6f 6d 70 6c 65 74 65 64 20 65 78 65 63  * completed exec
2e870 75 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e  ution..**.** ^In
2e880 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 66  voking sqlite3_f
2e890 69 6e 61 6c 69 7a 65 28 29 20 6f 6e 20 61 20 4e  inalize() on a N
2e8a0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 61  ULL pointer is a
2e8b0 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e   harmless no-op.
2e8c0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69  .**.** The appli
2e8d0 63 61 74 69 6f 6e 20 6d 75 73 74 20 66 69 6e 61  cation must fina
2e8e0 6c 69 7a 65 20 65 76 65 72 79 20 5b 70 72 65 70  lize every [prep
2e8f0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2e900 69 6e 20 6f 72 64 65 72 20 74 6f 20 61 76 6f 69  in order to avoi
2e910 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65 20 6c 65  d.** resource le
2e920 61 6b 73 2e 20 20 49 74 20 69 73 20 61 20 67 72  aks.  It is a gr
2e930 69 65 76 6f 75 73 20 65 72 72 6f 72 20 66 6f 72  ievous error for
2e940 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
2e950 20 74 6f 20 74 72 79 20 74 6f 20 75 73 65 0a 2a   to try to use.*
2e960 2a 20 61 20 70 72 65 70 61 72 65 64 20 73 74 61  * a prepared sta
2e970 74 65 6d 65 6e 74 20 61 66 74 65 72 20 69 74 20  tement after it 
2e980 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a  has been finaliz
2e990 65 64 2e 20 20 41 6e 79 20 75 73 65 20 6f 66 20  ed.  Any use of 
2e9a0 61 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74  a prepared.** st
2e9b0 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 69 74  atement after it
2e9c0 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69   has been finali
2e9d0 7a 65 64 20 63 61 6e 20 72 65 73 75 6c 74 20 69  zed can result i
2e9e0 6e 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 0a  n undefined and.
2e9f0 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c 65 20 62  ** undesirable b
2ea00 65 68 61 76 69 6f 72 20 73 75 63 68 20 61 73 20  ehavior such as 
2ea10 73 65 67 66 61 75 6c 74 73 20 61 6e 64 20 68 65  segfaults and he
2ea20 61 70 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a  ap corruption..*
2ea30 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 66 69  /.int sqlite3_fi
2ea40 6e 61 6c 69 7a 65 28 73 71 6c 69 74 65 33 5f 73  nalize(sqlite3_s
2ea50 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
2ea60 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
2ea70 73 65 74 20 41 20 50 72 65 70 61 72 65 64 20 53  set A Prepared S
2ea80 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a  tatement Object.
2ea90 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
2eaa0 33 5f 72 65 73 65 74 28 29 20 66 75 6e 63 74 69  3_reset() functi
2eab0 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20  on is called to 
2eac0 72 65 73 65 74 20 61 20 5b 70 72 65 70 61 72 65  reset a [prepare
2ead0 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20  d statement].** 
2eae0 6f 62 6a 65 63 74 20 62 61 63 6b 20 74 6f 20 69  object back to i
2eaf0 74 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65  ts initial state
2eb00 2c 20 72 65 61 64 79 20 74 6f 20 62 65 20 72 65  , ready to be re
2eb10 2d 65 78 65 63 75 74 65 64 2e 0a 2a 2a 20 5e 41  -executed..** ^A
2eb20 6e 79 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ny SQL statement
2eb30 20 76 61 72 69 61 62 6c 65 73 20 74 68 61 74 20   variables that 
2eb40 68 61 64 20 76 61 6c 75 65 73 20 62 6f 75 6e 64  had values bound
2eb50 20 74 6f 20 74 68 65 6d 20 75 73 69 6e 67 0a 2a   to them using.*
2eb60 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62  * the [sqlite3_b
2eb70 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74  ind_blob | sqlit
2eb80 65 33 5f 62 69 6e 64 5f 2a 28 29 20 41 50 49 5d  e3_bind_*() API]
2eb90 20 72 65 74 61 69 6e 20 74 68 65 69 72 20 76 61   retain their va
2eba0 6c 75 65 73 2e 0a 2a 2a 20 55 73 65 20 5b 73 71  lues..** Use [sq
2ebb0 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64  lite3_clear_bind
2ebc0 69 6e 67 73 28 29 5d 20 74 6f 20 72 65 73 65 74  ings()] to reset
2ebd0 20 74 68 65 20 62 69 6e 64 69 6e 67 73 2e 0a 2a   the bindings..*
2ebe0 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74  *.** ^The [sqlit
2ebf0 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74  e3_reset(S)] int
2ec00 65 72 66 61 63 65 20 72 65 73 65 74 73 20 74 68  erface resets th
2ec10 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
2ec20 65 6d 65 6e 74 5d 20 53 0a 2a 2a 20 62 61 63 6b  ement] S.** back
2ec30 20 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e   to the beginnin
2ec40 67 20 6f 66 20 69 74 73 20 70 72 6f 67 72 61 6d  g of its program
2ec50 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
2ec60 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c  most recent call
2ec70 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   to [sqlite3_ste
2ec80 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a  p(S)] for the.**
2ec90 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2eca0 6d 65 6e 74 5d 20 53 20 72 65 74 75 72 6e 65 64  ment] S returned
2ecb0 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72   [SQLITE_ROW] or
2ecc0 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a   [SQLITE_DONE],.
2ecd0 2a 2a 20 6f 72 20 69 66 20 5b 73 71 6c 69 74 65  ** or if [sqlite
2ece0 33 5f 73 74 65 70 28 53 29 5d 20 68 61 73 20 6e  3_step(S)] has n
2ecf0 65 76 65 72 20 62 65 66 6f 72 65 20 62 65 65 6e  ever before been
2ed00 20 63 61 6c 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a   called on S,.**
2ed10 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72   then [sqlite3_r
2ed20 65 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73  eset(S)] returns
2ed30 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a   [SQLITE_OK]..**
2ed40 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74  .** ^If the most
2ed50 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20   recent call to 
2ed60 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29  [sqlite3_step(S)
2ed70 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72  ] for the.** [pr
2ed80 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2ed90 5d 20 53 20 69 6e 64 69 63 61 74 65 64 20 61 6e  ] S indicated an
2eda0 20 65 72 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20   error, then.** 
2edb0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53  [sqlite3_reset(S
2edc0 29 5d 20 72 65 74 75 72 6e 73 20 61 6e 20 61 70  )] returns an ap
2edd0 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72  propriate [error
2ede0 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54   code]..**.** ^T
2edf0 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  he [sqlite3_rese
2ee00 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20  t(S)] interface 
2ee10 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20  does not change 
2ee20 74 68 65 20 76 61 6c 75 65 73 0a 2a 2a 20 6f 66  the values.** of
2ee30 20 61 6e 79 20 5b 73 71 6c 69 74 65 33 5f 62 69   any [sqlite3_bi
2ee40 6e 64 5f 62 6c 6f 62 7c 62 69 6e 64 69 6e 67 73  nd_blob|bindings
2ee50 5d 20 6f 6e 20 74 68 65 20 5b 70 72 65 70 61 72  ] on the [prepar
2ee60 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e  ed statement] S.
2ee70 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
2ee80 72 65 73 65 74 28 73 71 6c 69 74 65 33 5f 73 74  reset(sqlite3_st
2ee90 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
2eea0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 72 65  ** CAPI3REF: Cre
2eeb0 61 74 65 20 4f 72 20 52 65 64 65 66 69 6e 65 20  ate Or Redefine 
2eec0 53 51 4c 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a  SQL Functions.**
2eed0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 66 75 6e 63   KEYWORDS: {func
2eee0 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f  tion creation ro
2eef0 75 74 69 6e 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f  utines}.** KEYWO
2ef00 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f  RDS: {applicatio
2ef10 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
2ef20 6e 63 74 69 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f  nction}.** KEYWO
2ef30 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f  RDS: {applicatio
2ef40 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
2ef50 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 5e  nctions}.**.** ^
2ef60 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  These functions 
2ef70 28 63 6f 6c 6c 65 63 74 69 76 65 6c 79 20 6b 6e  (collectively kn
2ef80 6f 77 6e 20 61 73 20 22 66 75 6e 63 74 69 6f 6e  own as "function
2ef90 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e   creation routin
2efa0 65 73 22 29 0a 2a 2a 20 61 72 65 20 75 73 65 64  es").** are used
2efb0 20 74 6f 20 61 64 64 20 53 51 4c 20 66 75 6e 63   to add SQL func
2efc0 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61  tions or aggrega
2efd0 74 65 73 20 6f 72 20 74 6f 20 72 65 64 65 66 69  tes or to redefi
2efe0 6e 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a  ne the behavior.
2eff0 2a 2a 20 6f 66 20 65 78 69 73 74 69 6e 67 20 53  ** of existing S
2f000 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20  QL functions or 
2f010 61 67 67 72 65 67 61 74 65 73 2e 20 20 54 68 65  aggregates.  The
2f020 20 6f 6e 6c 79 20 64 69 66 66 65 72 65 6e 63 65   only difference
2f030 73 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65  s between.** the
2f040 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
2f050 74 68 65 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  the text encodin
2f060 67 20 65 78 70 65 63 74 65 64 20 66 6f 72 0a 2a  g expected for.*
2f070 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  * the second par
2f080 61 6d 65 74 65 72 20 28 74 68 65 20 6e 61 6d 65  ameter (the name
2f090 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e   of the function
2f0a0 20 62 65 69 6e 67 20 63 72 65 61 74 65 64 29 0a   being created).
2f0b0 2a 2a 20 61 6e 64 20 74 68 65 20 70 72 65 73 65  ** and the prese
2f0c0 6e 63 65 20 6f 72 20 61 62 73 65 6e 63 65 20 6f  nce or absence o
2f0d0 66 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 63  f a destructor c
2f0e0 61 6c 6c 62 61 63 6b 20 66 6f 72 0a 2a 2a 20 74  allback for.** t
2f0f0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
2f100 61 74 61 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ata pointer..**.
2f110 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 70 61  ** ^The first pa
2f120 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b  rameter is the [
2f130 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2f140 69 6f 6e 5d 20 74 6f 20 77 68 69 63 68 20 74 68  ion] to which th
2f150 65 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f  e SQL.** functio
2f160 6e 20 69 73 20 74 6f 20 62 65 20 61 64 64 65 64  n is to be added
2f170 2e 20 20 5e 49 66 20 61 6e 20 61 70 70 6c 69 63  .  ^If an applic
2f180 61 74 69 6f 6e 20 75 73 65 73 20 6d 6f 72 65 20  ation uses more 
2f190 74 68 61 6e 20 6f 6e 65 20 64 61 74 61 62 61 73  than one databas
2f1a0 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  e.** connection 
2f1b0 74 68 65 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  then application
2f1c0 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
2f1d0 63 74 69 6f 6e 73 20 6d 75 73 74 20 62 65 20 61  ctions must be a
2f1e0 64 64 65 64 0a 2a 2a 20 74 6f 20 65 61 63 68 20  dded.** to each 
2f1f0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2f200 69 6f 6e 20 73 65 70 61 72 61 74 65 6c 79 2e 0a  ion separately..
2f210 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e  **.** ^The secon
2f220 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  d parameter is t
2f230 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 53  he name of the S
2f240 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  QL function to b
2f250 65 20 63 72 65 61 74 65 64 20 6f 72 0a 2a 2a 20  e created or.** 
2f260 72 65 64 65 66 69 6e 65 64 2e 20 20 5e 54 68 65  redefined.  ^The
2f270 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 6e   length of the n
2f280 61 6d 65 20 69 73 20 6c 69 6d 69 74 65 64 20 74  ame is limited t
2f290 6f 20 32 35 35 20 62 79 74 65 73 20 69 6e 20 61  o 255 bytes in a
2f2a0 20 55 54 46 2d 38 0a 2a 2a 20 72 65 70 72 65 73   UTF-8.** repres
2f2b0 65 6e 74 61 74 69 6f 6e 2c 20 65 78 63 6c 75 73  entation, exclus
2f2c0 69 76 65 20 6f 66 20 74 68 65 20 7a 65 72 6f 2d  ive of the zero-
2f2d0 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 4e 6f  terminator.  ^No
2f2e0 74 65 20 74 68 61 74 20 74 68 65 20 6e 61 6d 65  te that the name
2f2f0 0a 2a 2a 20 6c 65 6e 67 74 68 20 6c 69 6d 69 74  .** length limit
2f300 20 69 73 20 69 6e 20 55 54 46 2d 38 20 62 79 74   is in UTF-8 byt
2f310 65 73 2c 20 6e 6f 74 20 63 68 61 72 61 63 74 65  es, not characte
2f320 72 73 20 6e 6f 72 20 55 54 46 2d 31 36 20 62 79  rs nor UTF-16 by
2f330 74 65 73 2e 20 20 0a 2a 2a 20 5e 41 6e 79 20 61  tes.  .** ^Any a
2f340 74 74 65 6d 70 74 20 74 6f 20 63 72 65 61 74 65  ttempt to create
2f350 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68   a function with
2f360 20 61 20 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a   a longer name.*
2f370 2a 20 77 69 6c 6c 20 72 65 73 75 6c 74 20 69 6e  * will result in
2f380 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
2f390 20 62 65 69 6e 67 20 72 65 74 75 72 6e 65 64 2e   being returned.
2f3a0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72  .**.** ^The thir
2f3b0 64 20 70 61 72 61 6d 65 74 65 72 20 28 6e 41 72  d parameter (nAr
2f3c0 67 29 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d  g).** is the num
2f3d0 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73  ber of arguments
2f3e0 20 74 68 61 74 20 74 68 65 20 53 51 4c 20 66 75   that the SQL fu
2f3f0 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67  nction or.** agg
2f400 72 65 67 61 74 65 20 74 61 6b 65 73 2e 20 5e 49  regate takes. ^I
2f410 66 20 74 68 69 73 20 70 61 72 61 6d 65 74 65 72  f this parameter
2f420 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 74 68 65   is -1, then the
2f430 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72   SQL function or
2f440 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 6d 61  .** aggregate ma
2f450 79 20 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62 65  y take any numbe
2f460 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 62  r of arguments b
2f470 65 74 77 65 65 6e 20 30 20 61 6e 64 20 74 68 65  etween 0 and the
2f480 20 6c 69 6d 69 74 0a 2a 2a 20 73 65 74 20 62 79   limit.** set by
2f490 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d   [sqlite3_limit]
2f4a0 28 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46  ([SQLITE_LIMIT_F
2f4b0 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 29 2e 20 20  UNCTION_ARG]).  
2f4c0 49 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20  If the third.** 
2f4d0 70 61 72 61 6d 65 74 65 72 20 69 73 20 6c 65 73  parameter is les
2f4e0 73 20 74 68 61 6e 20 2d 31 20 6f 72 20 67 72 65  s than -1 or gre
2f4f0 61 74 65 72 20 74 68 61 6e 20 31 32 37 20 74 68  ater than 127 th
2f500 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
2f510 69 73 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e  is.** undefined.
2f520 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72  .**.** ^The four
2f530 74 68 20 70 61 72 61 6d 65 74 65 72 2c 20 65 54  th parameter, eT
2f540 65 78 74 52 65 70 2c 20 73 70 65 63 69 66 69 65  extRep, specifie
2f550 73 20 77 68 61 74 0a 2a 2a 20 5b 53 51 4c 49 54  s what.** [SQLIT
2f560 45 5f 55 54 46 38 20 7c 20 74 65 78 74 20 65 6e  E_UTF8 | text en
2f570 63 6f 64 69 6e 67 5d 20 74 68 69 73 20 53 51 4c  coding] this SQL
2f580 20 66 75 6e 63 74 69 6f 6e 20 70 72 65 66 65 72   function prefer
2f590 73 20 66 6f 72 0a 2a 2a 20 69 74 73 20 70 61 72  s for.** its par
2f5a0 61 6d 65 74 65 72 73 2e 20 20 45 76 65 72 79 20  ameters.  Every 
2f5b0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70  SQL function imp
2f5c0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 75 73 74  lementation must
2f5d0 20 62 65 20 61 62 6c 65 20 74 6f 20 77 6f 72 6b   be able to work
2f5e0 0a 2a 2a 20 77 69 74 68 20 55 54 46 2d 38 2c 20  .** with UTF-8, 
2f5f0 55 54 46 2d 31 36 6c 65 2c 20 6f 72 20 55 54 46  UTF-16le, or UTF
2f600 2d 31 36 62 65 2e 20 20 42 75 74 20 73 6f 6d 65  -16be.  But some
2f610 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
2f620 20 6d 61 79 20 62 65 0a 2a 2a 20 6d 6f 72 65 20   may be.** more 
2f630 65 66 66 69 63 69 65 6e 74 20 77 69 74 68 20 6f  efficient with o
2f640 6e 65 20 65 6e 63 6f 64 69 6e 67 20 74 68 61 6e  ne encoding than
2f650 20 61 6e 6f 74 68 65 72 2e 20 20 5e 41 6e 20 61   another.  ^An a
2f660 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79 0a 2a  pplication may.*
2f670 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33  * invoke sqlite3
2f680 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
2f690 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 72  () or sqlite3_cr
2f6a0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
2f6b0 29 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 74 69  ) multiple.** ti
2f6c0 6d 65 73 20 77 69 74 68 20 74 68 65 20 73 61 6d  mes with the sam
2f6d0 65 20 66 75 6e 63 74 69 6f 6e 20 62 75 74 20 77  e function but w
2f6e0 69 74 68 20 64 69 66 66 65 72 65 6e 74 20 76 61  ith different va
2f6f0 6c 75 65 73 20 6f 66 20 65 54 65 78 74 52 65 70  lues of eTextRep
2f700 2e 0a 2a 2a 20 5e 57 68 65 6e 20 6d 75 6c 74 69  ..** ^When multi
2f710 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ple implementati
2f720 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20  ons of the same 
2f730 66 75 6e 63 74 69 6f 6e 20 61 72 65 20 61 76 61  function are ava
2f740 69 6c 61 62 6c 65 2c 20 53 51 4c 69 74 65 0a 2a  ilable, SQLite.*
2f750 2a 20 77 69 6c 6c 20 70 69 63 6b 20 74 68 65 20  * will pick the 
2f760 6f 6e 65 20 74 68 61 74 20 69 6e 76 6f 6c 76 65  one that involve
2f770 73 20 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75  s the least amou
2f780 6e 74 20 6f 66 20 64 61 74 61 20 63 6f 6e 76 65  nt of data conve
2f790 72 73 69 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65  rsion..** If the
2f7a0 72 65 20 69 73 20 6f 6e 6c 79 20 61 20 73 69 6e  re is only a sin
2f7b0 67 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  gle implementati
2f7c0 6f 6e 20 77 68 69 63 68 20 64 6f 65 73 20 6e 6f  on which does no
2f7d0 74 20 63 61 72 65 20 77 68 61 74 20 74 65 78 74  t care what text
2f7e0 0a 2a 2a 20 65 6e 63 6f 64 69 6e 67 20 69 73 20  .** encoding is 
2f7f0 75 73 65 64 2c 20 74 68 65 6e 20 74 68 65 20 66  used, then the f
2f800 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 73  ourth argument s
2f810 68 6f 75 6c 64 20 62 65 20 5b 53 51 4c 49 54 45  hould be [SQLITE
2f820 5f 41 4e 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  _ANY]..**.** ^(T
2f830 68 65 20 66 69 66 74 68 20 70 61 72 61 6d 65 74  he fifth paramet
2f840 65 72 20 69 73 20 61 6e 20 61 72 62 69 74 72 61  er is an arbitra
2f850 72 79 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65  ry pointer.  The
2f860 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
2f870 6f 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69  of the.** functi
2f880 6f 6e 20 63 61 6e 20 67 61 69 6e 20 61 63 63 65  on can gain acce
2f890 73 73 20 74 6f 20 74 68 69 73 20 70 6f 69 6e 74  ss to this point
2f8a0 65 72 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  er using [sqlite
2f8b0 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2e 29  3_user_data()].)
2f8c0 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 69 78  ^.**.** ^The six
2f8d0 74 68 2c 20 73 65 76 65 6e 74 68 20 61 6e 64 20  th, seventh and 
2f8e0 65 69 67 68 74 68 20 70 61 72 61 6d 65 74 65 72  eighth parameter
2f8f0 73 2c 20 78 46 75 6e 63 2c 20 78 53 74 65 70 20  s, xFunc, xStep 
2f900 61 6e 64 20 78 46 69 6e 61 6c 2c 20 61 72 65 0a  and xFinal, are.
2f910 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 43  ** pointers to C
2f920 2d 6c 61 6e 67 75 61 67 65 20 66 75 6e 63 74 69  -language functi
2f930 6f 6e 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65  ons that impleme
2f940 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  nt the SQL funct
2f950 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67  ion or.** aggreg
2f960 61 74 65 2e 20 5e 41 20 73 63 61 6c 61 72 20 53  ate. ^A scalar S
2f970 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75  QL function requ
2f980 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e  ires an implemen
2f990 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 46  tation of the xF
2f9a0 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20  unc.** callback 
2f9b0 6f 6e 6c 79 3b 20 4e 55 4c 4c 20 70 6f 69 6e 74  only; NULL point
2f9c0 65 72 73 20 6d 75 73 74 20 62 65 20 70 61 73 73  ers must be pass
2f9d0 65 64 20 61 73 20 74 68 65 20 78 53 74 65 70 20  ed as the xStep 
2f9e0 61 6e 64 20 78 46 69 6e 61 6c 0a 2a 2a 20 70 61  and xFinal.** pa
2f9f0 72 61 6d 65 74 65 72 73 2e 20 5e 41 6e 20 61 67  rameters. ^An ag
2fa00 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63  gregate SQL func
2fa10 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e  tion requires an
2fa20 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
2fa30 6f 66 20 78 53 74 65 70 0a 2a 2a 20 61 6e 64 20  of xStep.** and 
2fa40 78 46 69 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c 20  xFinal and NULL 
2fa50 70 6f 69 6e 74 65 72 20 6d 75 73 74 20 62 65 20  pointer must be 
2fa60 70 61 73 73 65 64 20 66 6f 72 20 78 46 75 6e 63  passed for xFunc
2fa70 2e 20 5e 54 6f 20 64 65 6c 65 74 65 20 61 6e 20  . ^To delete an 
2fa80 65 78 69 73 74 69 6e 67 0a 2a 2a 20 53 51 4c 20  existing.** SQL 
2fa90 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72  function or aggr
2faa0 65 67 61 74 65 2c 20 70 61 73 73 20 4e 55 4c 4c  egate, pass NULL
2fab0 20 70 6f 69 6e 74 65 72 73 20 66 6f 72 20 61 6c   pointers for al
2fac0 6c 20 74 68 72 65 65 20 66 75 6e 63 74 69 6f 6e  l three function
2fad0 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a  .** callbacks..*
2fae0 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 65 20 6e 69  *.** ^(If the ni
2faf0 6e 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  nth parameter to
2fb00 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
2fb10 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20 69 73  function_v2() is
2fb20 20 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 74 68   not NULL,.** th
2fb30 65 6e 20 69 74 20 69 73 20 64 65 73 74 72 75 63  en it is destruc
2fb40 74 6f 72 20 66 6f 72 20 74 68 65 20 61 70 70 6c  tor for the appl
2fb50 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69  ication data poi
2fb60 6e 74 65 72 2e 20 0a 2a 2a 20 54 68 65 20 64 65  nter. .** The de
2fb70 73 74 72 75 63 74 6f 72 20 69 73 20 69 6e 76 6f  structor is invo
2fb80 6b 65 64 20 77 68 65 6e 20 74 68 65 20 66 75 6e  ked when the fun
2fb90 63 74 69 6f 6e 20 69 73 20 64 65 6c 65 74 65 64  ction is deleted
2fba0 2c 20 65 69 74 68 65 72 20 62 79 20 62 65 69 6e  , either by bein
2fbb0 67 0a 2a 2a 20 6f 76 65 72 6c 6f 61 64 65 64 20  g.** overloaded 
2fbc0 6f 72 20 77 68 65 6e 20 74 68 65 20 64 61 74 61  or when the data
2fbd0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
2fbe0 63 6c 6f 73 65 73 2e 29 5e 0a 2a 2a 20 5e 54 68  closes.)^.** ^Th
2fbf0 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20  e destructor is 
2fc00 61 6c 73 6f 20 69 6e 76 6f 6b 65 64 20 69 66 20  also invoked if 
2fc10 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73  the call to.** s
2fc20 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
2fc30 6e 63 74 69 6f 6e 5f 76 32 28 29 20 66 61 69 6c  nction_v2() fail
2fc40 73 2e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20  s..** ^When the 
2fc50 64 65 73 74 72 75 63 74 6f 72 20 63 61 6c 6c 62  destructor callb
2fc60 61 63 6b 20 6f 66 20 74 68 65 20 74 65 6e 74 68  ack of the tenth
2fc70 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 69 6e   parameter is in
2fc80 76 6f 6b 65 64 2c 20 69 74 0a 2a 2a 20 69 73 20  voked, it.** is 
2fc90 70 61 73 73 65 64 20 61 20 73 69 6e 67 6c 65 20  passed a single 
2fca0 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
2fcb0 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
2fcc0 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61  application data
2fcd0 20 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 77 68 69   .** pointer whi
2fce0 63 68 20 77 61 73 20 74 68 65 20 66 69 66 74 68  ch was the fifth
2fcf0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
2fd00 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
2fd10 63 74 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a  ction_v2()..**.*
2fd20 2a 20 5e 49 74 20 69 73 20 70 65 72 6d 69 74 74  * ^It is permitt
2fd30 65 64 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d  ed to register m
2fd40 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e  ultiple implemen
2fd50 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73  tations of the s
2fd60 61 6d 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73  ame.** functions
2fd70 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 6e   with the same n
2fd80 61 6d 65 20 62 75 74 20 77 69 74 68 20 65 69 74  ame but with eit
2fd90 68 65 72 20 64 69 66 66 65 72 69 6e 67 20 6e 75  her differing nu
2fda0 6d 62 65 72 73 20 6f 66 0a 2a 2a 20 61 72 67 75  mbers of.** argu
2fdb0 6d 65 6e 74 73 20 6f 72 20 64 69 66 66 65 72 69  ments or differi
2fdc0 6e 67 20 70 72 65 66 65 72 72 65 64 20 74 65 78  ng preferred tex
2fdd0 74 20 65 6e 63 6f 64 69 6e 67 73 2e 20 20 5e 53  t encodings.  ^S
2fde0 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a  QLite will use.*
2fdf0 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  * the implementa
2fe00 74 69 6f 6e 20 74 68 61 74 20 6d 6f 73 74 20 63  tion that most c
2fe10 6c 6f 73 65 6c 79 20 6d 61 74 63 68 65 73 20 74  losely matches t
2fe20 68 65 20 77 61 79 20 69 6e 20 77 68 69 63 68 20  he way in which 
2fe30 74 68 65 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74  the.** SQL funct
2fe40 69 6f 6e 20 69 73 20 75 73 65 64 2e 20 20 5e 41  ion is used.  ^A
2fe50 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d   function implem
2fe60 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 20 61 20  entation with a 
2fe70 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 0a 2a 2a 20  non-negative.** 
2fe80 6e 41 72 67 20 70 61 72 61 6d 65 74 65 72 20 69  nArg parameter i
2fe90 73 20 61 20 62 65 74 74 65 72 20 6d 61 74 63 68  s a better match
2fea0 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e   than a function
2feb0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
2fec0 77 69 74 68 0a 2a 2a 20 61 20 6e 65 67 61 74 69  with.** a negati
2fed0 76 65 20 6e 41 72 67 2e 20 20 5e 41 20 66 75 6e  ve nArg.  ^A fun
2fee0 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20  ction where the 
2fef0 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65  preferred text e
2ff00 6e 63 6f 64 69 6e 67 0a 2a 2a 20 6d 61 74 63 68  ncoding.** match
2ff10 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  es the database 
2ff20 65 6e 63 6f 64 69 6e 67 20 69 73 20 61 20 62 65  encoding is a be
2ff30 74 74 65 72 0a 2a 2a 20 6d 61 74 63 68 20 74 68  tter.** match th
2ff40 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68  an a function wh
2ff50 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67  ere the encoding
2ff60 20 69 73 20 64 69 66 66 65 72 65 6e 74 2e 20 20   is different.  
2ff70 0a 2a 2a 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20  .** ^A function 
2ff80 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69  where the encodi
2ff90 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20 69 73  ng difference is
2ffa0 20 62 65 74 77 65 65 6e 20 55 54 46 31 36 6c 65   between UTF16le
2ffb0 20 61 6e 64 20 55 54 46 31 36 62 65 0a 2a 2a 20   and UTF16be.** 
2ffc0 69 73 20 61 20 63 6c 6f 73 65 72 20 6d 61 74 63  is a closer matc
2ffd0 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f  h than a functio
2ffe0 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f  n where the enco
2fff0 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20  ding difference 
30000 69 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 55 54  is.** between UT
30010 46 38 20 61 6e 64 20 55 54 46 31 36 2e 0a 2a 2a  F8 and UTF16..**
30020 0a 2a 2a 20 5e 42 75 69 6c 74 2d 69 6e 20 66 75  .** ^Built-in fu
30030 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 6f  nctions may be o
30040 76 65 72 6c 6f 61 64 65 64 20 62 79 20 6e 65 77  verloaded by new
30050 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
30060 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73 2e 0a  ined functions..
30070 2a 2a 0a 2a 2a 20 5e 41 6e 20 61 70 70 6c 69 63  **.** ^An applic
30080 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
30090 6e 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74  nction is permit
300a0 74 65 64 20 74 6f 20 63 61 6c 6c 20 6f 74 68 65  ted to call othe
300b0 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65  r.** SQLite inte
300c0 72 66 61 63 65 73 2e 20 20 48 6f 77 65 76 65 72  rfaces.  However
300d0 2c 20 73 75 63 68 20 63 61 6c 6c 73 20 6d 75 73  , such calls mus
300e0 74 20 6e 6f 74 0a 2a 2a 20 63 6c 6f 73 65 20 74  t not.** close t
300f0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
30100 65 63 74 69 6f 6e 20 6e 6f 72 20 66 69 6e 61 6c  ection nor final
30110 69 7a 65 20 6f 72 20 72 65 73 65 74 20 74 68 65  ize or reset the
30120 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61   prepared.** sta
30130 74 65 6d 65 6e 74 20 69 6e 20 77 68 69 63 68 20  tement in which 
30140 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  the function is 
30150 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 69 6e 74 20  running..*/.int 
30160 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
30170 75 6e 63 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74  unction(.  sqlit
30180 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20  e3 *db,.  const 
30190 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e  char *zFunctionN
301a0 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c  ame,.  int nArg,
301b0 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c  .  int eTextRep,
301c0 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20  .  void *pApp,. 
301d0 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73   void (*xFunc)(s
301e0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
301f0 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75  int,sqlite3_valu
30200 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78  e**),.  void (*x
30210 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f  Step)(sqlite3_co
30220 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74  ntext*,int,sqlit
30230 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76  e3_value**),.  v
30240 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71  oid (*xFinal)(sq
30250 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a  lite3_context*).
30260 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
30270 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
30280 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
30290 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a  .  const void *z
302a0 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20  FunctionName,.  
302b0 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20  int nArg,.  int 
302c0 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64  eTextRep,.  void
302d0 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28   *pApp,.  void (
302e0 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f  *xFunc)(sqlite3_
302f0 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c  context*,int,sql
30300 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20  ite3_value**),. 
30310 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73   void (*xStep)(s
30320 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
30330 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75  int,sqlite3_valu
30340 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78  e**),.  void (*x
30350 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63  Final)(sqlite3_c
30360 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 69 6e 74 20  ontext*).);.int 
30370 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
30380 75 6e 63 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71  unction_v2(.  sq
30390 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e  lite3 *db,.  con
303a0 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69  st char *zFuncti
303b0 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41  onName,.  int nA
303c0 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52  rg,.  int eTextR
303d0 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70  ep,.  void *pApp
303e0 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63  ,.  void (*xFunc
303f0 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
30400 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76  t*,int,sqlite3_v
30410 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20  alue**),.  void 
30420 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33  (*xStep)(sqlite3
30430 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71  _context*,int,sq
30440 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a  lite3_value**),.
30450 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29    void (*xFinal)
30460 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
30470 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65 73  *),.  void(*xDes
30480 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a  troy)(void*).);.
30490 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
304a0 20 54 65 78 74 20 45 6e 63 6f 64 69 6e 67 73 0a   Text Encodings.
304b0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
304c0 74 61 6e 74 20 64 65 66 69 6e 65 20 69 6e 74 65  tant define inte
304d0 67 65 72 20 63 6f 64 65 73 20 74 68 61 74 20 72  ger codes that r
304e0 65 70 72 65 73 65 6e 74 20 74 68 65 20 76 61 72  epresent the var
304f0 69 6f 75 73 0a 2a 2a 20 74 65 78 74 20 65 6e 63  ious.** text enc
30500 6f 64 69 6e 67 73 20 73 75 70 70 6f 72 74 65 64  odings supported
30510 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23   by SQLite..*/.#
30520 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54  define SQLITE_UT
30530 46 38 20 20 20 20 20 20 20 20 20 20 20 31 0a 23  F8           1.#
30540 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54  define SQLITE_UT
30550 46 31 36 4c 45 20 20 20 20 20 20 20 20 32 0a 23  F16LE        2.#
30560 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54  define SQLITE_UT
30570 46 31 36 42 45 20 20 20 20 20 20 20 20 33 0a 23  F16BE        3.#
30580 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54  define SQLITE_UT
30590 46 31 36 20 20 20 20 20 20 20 20 20 20 34 20 20  F16          4  
305a0 20 20 2f 2a 20 55 73 65 20 6e 61 74 69 76 65 20    /* Use native 
305b0 62 79 74 65 20 6f 72 64 65 72 20 2a 2f 0a 23 64  byte order */.#d
305c0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 59  efine SQLITE_ANY
305d0 20 20 20 20 20 20 20 20 20 20 20 20 35 20 20 20              5   
305e0 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61   /* sqlite3_crea
305f0 74 65 5f 66 75 6e 63 74 69 6f 6e 20 6f 6e 6c 79  te_function only
30600 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
30610 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44  TE_UTF16_ALIGNED
30620 20 20 38 20 20 20 20 2f 2a 20 73 71 6c 69 74 65    8    /* sqlite
30630 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
30640 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a  on only */../*.*
30650 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 70 72  * CAPI3REF: Depr
30660 65 63 61 74 65 64 20 46 75 6e 63 74 69 6f 6e 73  ecated Functions
30670 0a 2a 2a 20 44 45 50 52 45 43 41 54 45 44 0a 2a  .** DEPRECATED.*
30680 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74  *.** These funct
30690 69 6f 6e 73 20 61 72 65 20 5b 64 65 70 72 65 63  ions are [deprec
306a0 61 74 65 64 5d 2e 20 20 49 6e 20 6f 72 64 65 72  ated].  In order
306b0 20 74 6f 20 6d 61 69 6e 74 61 69 6e 0a 2a 2a 20   to maintain.** 
306c0 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74  backwards compat
306d0 69 62 69 6c 69 74 79 20 77 69 74 68 20 6f 6c 64  ibility with old
306e0 65 72 20 63 6f 64 65 2c 20 74 68 65 73 65 20 66  er code, these f
306f0 75 6e 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75  unctions continu
30700 65 20 0a 2a 2a 20 74 6f 20 62 65 20 73 75 70 70  e .** to be supp
30710 6f 72 74 65 64 2e 20 20 48 6f 77 65 76 65 72 2c  orted.  However,
30720 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e   new application
30730 73 20 73 68 6f 75 6c 64 20 61 76 6f 69 64 0a 2a  s should avoid.*
30740 2a 20 74 68 65 20 75 73 65 20 6f 66 20 74 68 65  * the use of the
30750 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54  se functions.  T
30760 6f 20 68 65 6c 70 20 65 6e 63 6f 75 72 61 67 65  o help encourage
30770 20 70 65 6f 70 6c 65 20 74 6f 20 61 76 6f 69 64   people to avoid
30780 0a 2a 2a 20 75 73 69 6e 67 20 74 68 65 73 65 20  .** using these 
30790 66 75 6e 63 74 69 6f 6e 73 2c 20 77 65 20 61 72  functions, we ar
307a0 65 20 6e 6f 74 20 67 6f 69 6e 67 20 74 6f 20 74  e not going to t
307b0 65 6c 6c 20 79 6f 75 20 77 68 61 74 20 74 68 65  ell you what the
307c0 79 20 64 6f 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66  y do..*/.#ifndef
307d0 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 44 45 50   SQLITE_OMIT_DEP
307e0 52 45 43 41 54 45 44 0a 53 51 4c 49 54 45 5f 44  RECATED.SQLITE_D
307f0 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71  EPRECATED int sq
30800 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
30810 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f  count(sqlite3_co
30820 6e 74 65 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f  ntext*);.SQLITE_
30830 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73  DEPRECATED int s
30840 71 6c 69 74 65 33 5f 65 78 70 69 72 65 64 28 73  qlite3_expired(s
30850 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53  qlite3_stmt*);.S
30860 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
30870 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 72 61   int sqlite3_tra
30880 6e 73 66 65 72 5f 62 69 6e 64 69 6e 67 73 28 73  nsfer_bindings(s
30890 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 73 71  qlite3_stmt*, sq
308a0 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51  lite3_stmt*);.SQ
308b0 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20  LITE_DEPRECATED 
308c0 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 6c 6f 62  int sqlite3_glob
308d0 61 6c 5f 72 65 63 6f 76 65 72 28 76 6f 69 64 29  al_recover(void)
308e0 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  ;.SQLITE_DEPRECA
308f0 54 45 44 20 76 6f 69 64 20 73 71 6c 69 74 65 33  TED void sqlite3
30900 5f 74 68 72 65 61 64 5f 63 6c 65 61 6e 75 70 28  _thread_cleanup(
30910 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 44 45  void);.SQLITE_DE
30920 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c  PRECATED int sql
30930 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72  ite3_memory_alar
30940 6d 28 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c  m(void(*)(void*,
30950 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c 69 6e  sqlite3_int64,in
30960 74 29 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20  t),.            
30970 20 20 20 20 20 20 20 20 20 20 76 6f 69 64 2a 2c            void*,
30980 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a  sqlite3_int64);.
30990 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41  #endif../*.** CA
309a0 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 69 6e  PI3REF: Obtainin
309b0 67 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 50  g SQL Function P
309c0 61 72 61 6d 65 74 65 72 20 56 61 6c 75 65 73 0a  arameter Values.
309d0 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d 6c 61 6e 67  **.** The C-lang
309e0 75 61 67 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  uage implementat
309f0 69 6f 6e 20 6f 66 20 53 51 4c 20 66 75 6e 63 74  ion of SQL funct
30a00 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61  ions and aggrega
30a10 74 65 73 20 75 73 65 73 0a 2a 2a 20 74 68 69 73  tes uses.** this
30a20 20 73 65 74 20 6f 66 20 69 6e 74 65 72 66 61 63   set of interfac
30a30 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 61 63  e routines to ac
30a40 63 65 73 73 20 74 68 65 20 70 61 72 61 6d 65 74  cess the paramet
30a50 65 72 20 76 61 6c 75 65 73 20 6f 6e 0a 2a 2a 20  er values on.** 
30a60 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20  the function or 
30a70 61 67 67 72 65 67 61 74 65 2e 0a 2a 2a 0a 2a 2a  aggregate..**.**
30a80 20 54 68 65 20 78 46 75 6e 63 20 28 66 6f 72 20   The xFunc (for 
30a90 73 63 61 6c 61 72 20 66 75 6e 63 74 69 6f 6e 73  scalar functions
30aa0 29 20 6f 72 20 78 53 74 65 70 20 28 66 6f 72 20  ) or xStep (for 
30ab0 61 67 67 72 65 67 61 74 65 73 29 20 70 61 72 61  aggregates) para
30ac0 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 5b 73 71  meters.** to [sq
30ad0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
30ae0 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71  ction()] and [sq
30af0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
30b00 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 64 65  ction16()].** de
30b10 66 69 6e 65 20 63 61 6c 6c 62 61 63 6b 73 20 74  fine callbacks t
30b20 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68  hat implement th
30b30 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  e SQL functions 
30b40 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e 0a  and aggregates..
30b50 2a 2a 20 54 68 65 20 33 72 64 20 70 61 72 61 6d  ** The 3rd param
30b60 65 74 65 72 20 74 6f 20 74 68 65 73 65 20 63 61  eter to these ca
30b70 6c 6c 62 61 63 6b 73 20 69 73 20 61 6e 20 61 72  llbacks is an ar
30b80 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20  ray of pointers 
30b90 74 6f 0a 2a 2a 20 5b 70 72 6f 74 65 63 74 65 64  to.** [protected
30ba0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
30bb0 6f 62 6a 65 63 74 73 2e 20 20 54 68 65 72 65 20  objects.  There 
30bc0 69 73 20 6f 6e 65 20 5b 73 71 6c 69 74 65 33 5f  is one [sqlite3_
30bd0 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 66 6f  value] object fo
30be0 72 0a 2a 2a 20 65 61 63 68 20 70 61 72 61 6d 65  r.** each parame
30bf0 74 65 72 20 74 6f 20 74 68 65 20 53 51 4c 20 66  ter to the SQL f
30c00 75 6e 63 74 69 6f 6e 2e 20 20 54 68 65 73 65 20  unction.  These 
30c10 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65  routines are use
30c20 64 20 74 6f 0a 2a 2a 20 65 78 74 72 61 63 74 20  d to.** extract 
30c30 76 61 6c 75 65 73 20 66 72 6f 6d 20 74 68 65 20  values from the 
30c40 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20  [sqlite3_value] 
30c50 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54  objects..**.** T
30c60 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f  hese routines wo
30c70 72 6b 20 6f 6e 6c 79 20 77 69 74 68 20 5b 70 72  rk only with [pr
30c80 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
30c90 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a  value] objects..
30ca0 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74  ** Any attempt t
30cb0 6f 20 75 73 65 20 74 68 65 73 65 20 72 6f 75 74  o use these rout
30cc0 69 6e 65 73 20 6f 6e 20 61 6e 20 5b 75 6e 70 72  ines on an [unpr
30cd0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
30ce0 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63 74  value].** object
30cf0 20 72 65 73 75 6c 74 73 20 69 6e 20 75 6e 64 65   results in unde
30d00 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a  fined behavior..
30d10 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75  **.** ^These rou
30d20 74 69 6e 65 73 20 77 6f 72 6b 20 6a 75 73 74 20  tines work just 
30d30 6c 69 6b 65 20 74 68 65 20 63 6f 72 72 65 73 70  like the corresp
30d40 6f 6e 64 69 6e 67 20 5b 63 6f 6c 75 6d 6e 20 61  onding [column a
30d50 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d  ccess functions]
30d60 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74 20  .** except that 
30d70 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
30d80 74 61 6b 65 20 61 20 73 69 6e 67 6c 65 20 5b 70  take a single [p
30d90 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
30da0 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 0a 2a  _value] object.*
30db0 2a 20 70 6f 69 6e 74 65 72 20 69 6e 73 74 65 61  * pointer instea
30dc0 64 20 6f 66 20 61 20 5b 73 71 6c 69 74 65 33 5f  d of a [sqlite3_
30dd0 73 74 6d 74 2a 5d 20 70 6f 69 6e 74 65 72 20 61  stmt*] pointer a
30de0 6e 64 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f  nd an integer co
30df0 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a  lumn number..**.
30e00 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
30e10 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 20 69  value_text16() i
30e20 6e 74 65 72 66 61 63 65 20 65 78 74 72 61 63 74  nterface extract
30e30 73 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e  s a UTF-16 strin
30e40 67 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 74 69  g.** in the nati
30e50 76 65 20 62 79 74 65 2d 6f 72 64 65 72 20 6f 66  ve byte-order of
30e60 20 74 68 65 20 68 6f 73 74 20 6d 61 63 68 69 6e   the host machin
30e70 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69  e.  ^The.** sqli
30e80 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
30e90 62 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  be() and sqlite3
30ea0 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28  _value_text16le(
30eb0 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  ) interfaces.** 
30ec0 65 78 74 72 61 63 74 20 55 54 46 2d 31 36 20 73  extract UTF-16 s
30ed0 74 72 69 6e 67 73 20 61 73 20 62 69 67 2d 65 6e  trings as big-en
30ee0 64 69 61 6e 20 61 6e 64 20 6c 69 74 74 6c 65 2d  dian and little-
30ef0 65 6e 64 69 61 6e 20 72 65 73 70 65 63 74 69 76  endian respectiv
30f00 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ely..**.** ^(The
30f10 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e   sqlite3_value_n
30f20 75 6d 65 72 69 63 5f 74 79 70 65 28 29 20 69 6e  umeric_type() in
30f30 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73  terface attempts
30f40 20 74 6f 20 61 70 70 6c 79 0a 2a 2a 20 6e 75 6d   to apply.** num
30f50 65 72 69 63 20 61 66 66 69 6e 69 74 79 20 74 6f  eric affinity to
30f60 20 74 68 65 20 76 61 6c 75 65 2e 20 20 54 68 69   the value.  Thi
30f70 73 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6e 20  s means that an 
30f80 61 74 74 65 6d 70 74 20 69 73 0a 2a 2a 20 6d 61  attempt is.** ma
30f90 64 65 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68  de to convert th
30fa0 65 20 76 61 6c 75 65 20 74 6f 20 61 6e 20 69 6e  e value to an in
30fb0 74 65 67 65 72 20 6f 72 20 66 6c 6f 61 74 69 6e  teger or floatin
30fc0 67 20 70 6f 69 6e 74 2e 20 20 49 66 0a 2a 2a 20  g point.  If.** 
30fd0 73 75 63 68 20 61 20 63 6f 6e 76 65 72 73 69 6f  such a conversio
30fe0 6e 20 69 73 20 70 6f 73 73 69 62 6c 65 20 77 69  n is possible wi
30ff0 74 68 6f 75 74 20 6c 6f 73 73 20 6f 66 20 69 6e  thout loss of in
31000 66 6f 72 6d 61 74 69 6f 6e 20 28 69 6e 20 6f 74  formation (in ot
31010 68 65 72 0a 2a 2a 20 77 6f 72 64 73 2c 20 69 66  her.** words, if
31020 20 74 68 65 20 76 61 6c 75 65 20 69 73 20 61 20   the value is a 
31030 73 74 72 69 6e 67 20 74 68 61 74 20 6c 6f 6f 6b  string that look
31040 73 20 6c 69 6b 65 20 61 20 6e 75 6d 62 65 72 29  s like a number)
31050 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 6f 6e  .** then the con
31060 76 65 72 73 69 6f 6e 20 69 73 20 70 65 72 66 6f  version is perfo
31070 72 6d 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65  rmed.  Otherwise
31080 20 6e 6f 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f   no conversion o
31090 63 63 75 72 73 2e 0a 2a 2a 20 54 68 65 20 5b 53  ccurs..** The [S
310a0 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20  QLITE_INTEGER | 
310b0 64 61 74 61 74 79 70 65 5d 20 61 66 74 65 72 20  datatype] after 
310c0 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 72 65  conversion is re
310d0 74 75 72 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20  turned.)^.**.** 
310e0 50 6c 65 61 73 65 20 70 61 79 20 70 61 72 74 69  Please pay parti
310f0 63 75 6c 61 72 20 61 74 74 65 6e 74 69 6f 6e 20  cular attention 
31100 74 6f 20 74 68 65 20 66 61 63 74 20 74 68 61 74  to the fact that
31110 20 74 68 65 20 70 6f 69 6e 74 65 72 20 72 65 74   the pointer ret
31120 75 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73  urned.** from [s
31130 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f  qlite3_value_blo
31140 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76  b()], [sqlite3_v
31150 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 20 6f 72  alue_text()], or
31160 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  .** [sqlite3_val
31170 75 65 5f 74 65 78 74 31 36 28 29 5d 20 63 61 6e  ue_text16()] can
31180 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64 20   be invalidated 
31190 62 79 20 61 20 73 75 62 73 65 71 75 65 6e 74 20  by a subsequent 
311a0 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  call to.** [sqli
311b0 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28  te3_value_bytes(
311c0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  )], [sqlite3_val
311d0 75 65 5f 62 79 74 65 73 31 36 28 29 5d 2c 20 5b  ue_bytes16()], [
311e0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
311f0 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71  xt()],.** or [sq
31200 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
31210 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  16()]..**.** The
31220 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74  se routines must
31230 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20   be called from 
31240 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20  the same thread 
31250 61 73 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75  as.** the SQL fu
31260 6e 63 74 69 6f 6e 20 74 68 61 74 20 73 75 70 70  nction that supp
31270 6c 69 65 64 20 74 68 65 20 5b 73 71 6c 69 74 65  lied the [sqlite
31280 33 5f 76 61 6c 75 65 2a 5d 20 70 61 72 61 6d 65  3_value*] parame
31290 74 65 72 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 76  ters..*/.const v
312a0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c  oid *sqlite3_val
312b0 75 65 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f  ue_blob(sqlite3_
312c0 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c  value*);.int sql
312d0 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73  ite3_value_bytes
312e0 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
312f0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61  ;.int sqlite3_va
31300 6c 75 65 5f 62 79 74 65 73 31 36 28 73 71 6c 69  lue_bytes16(sqli
31310 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 64 6f 75  te3_value*);.dou
31320 62 6c 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ble sqlite3_valu
31330 65 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33  e_double(sqlite3
31340 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71  _value*);.int sq
31350 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28  lite3_value_int(
31360 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
31370 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73  .sqlite3_int64 s
31380 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74  qlite3_value_int
31390 36 34 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  64(sqlite3_value
313a0 2a 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e  *);.const unsign
313b0 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  ed char *sqlite3
313c0 5f 76 61 6c 75 65 5f 74 65 78 74 28 73 71 6c 69  _value_text(sqli
313d0 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e  te3_value*);.con
313e0 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
313f0 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 73 71  _value_text16(sq
31400 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63  lite3_value*);.c
31410 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
31420 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c  e3_value_text16l
31430 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  e(sqlite3_value*
31440 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
31450 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
31460 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f 76 61  t16be(sqlite3_va
31470 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  lue*);.int sqlit
31480 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 73 71  e3_value_type(sq
31490 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69  lite3_value*);.i
314a0 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt sqlite3_value
314b0 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 73 71  _numeric_type(sq
314c0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a  lite3_value*);..
314d0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
314e0 4f 62 74 61 69 6e 20 41 67 67 72 65 67 61 74 65  Obtain Aggregate
314f0 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78   Function Contex
31500 74 0a 2a 2a 0a 2a 2a 20 49 6d 70 6c 65 6d 65 6e  t.**.** Implemen
31510 74 61 74 69 6f 6e 73 20 6f 66 20 61 67 67 72 65  tations of aggre
31520 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f  gate SQL functio
31530 6e 73 20 75 73 65 20 74 68 69 73 0a 2a 2a 20 72  ns use this.** r
31540 6f 75 74 69 6e 65 20 74 6f 20 61 6c 6c 6f 63 61  outine to alloca
31550 74 65 20 6d 65 6d 6f 72 79 20 66 6f 72 20 73 74  te memory for st
31560 6f 72 69 6e 67 20 74 68 65 69 72 20 73 74 61 74  oring their stat
31570 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  e..**.** ^The fi
31580 72 73 74 20 74 69 6d 65 20 74 68 65 20 73 71 6c  rst time the sql
31590 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
315a0 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f 75 74  ontext(C,N) rout
315b0 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 0a 2a  ine is called .*
315c0 2a 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c  * for a particul
315d0 61 72 20 61 67 67 72 65 67 61 74 65 20 66 75 6e  ar aggregate fun
315e0 63 74 69 6f 6e 2c 20 53 51 4c 69 74 65 0a 2a 2a  ction, SQLite.**
315f0 20 61 6c 6c 6f 63 61 74 65 73 20 4e 20 6f 66 20   allocates N of 
31600 6d 65 6d 6f 72 79 2c 20 7a 65 72 6f 65 73 20 6f  memory, zeroes o
31610 75 74 20 74 68 61 74 20 6d 65 6d 6f 72 79 2c 20  ut that memory, 
31620 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f  and returns a po
31630 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20  inter.** to the 
31640 6e 65 77 20 6d 65 6d 6f 72 79 2e 20 5e 4f 6e 20  new memory. ^On 
31650 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65  second and subse
31660 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 0a 2a  quent calls to.*
31670 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  * sqlite3_aggreg
31680 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 66 6f  ate_context() fo
31690 72 20 74 68 65 20 73 61 6d 65 20 61 67 67 72 65  r the same aggre
316a0 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e  gate function in
316b0 73 74 61 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 73  stance,.** the s
316c0 61 6d 65 20 62 75 66 66 65 72 20 69 73 20 72 65  ame buffer is re
316d0 74 75 72 6e 65 64 2e 20 20 53 71 6c 69 74 65 33  turned.  Sqlite3
316e0 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
316f0 78 74 28 29 20 69 73 20 6e 6f 72 6d 61 6c 6c 79  xt() is normally
31700 0a 2a 2a 20 63 61 6c 6c 65 64 20 6f 6e 63 65 20  .** called once 
31710 66 6f 72 20 65 61 63 68 20 69 6e 76 6f 63 61 74  for each invocat
31720 69 6f 6e 20 6f 66 20 74 68 65 20 78 53 74 65 70  ion of the xStep
31730 20 63 61 6c 6c 62 61 63 6b 20 61 6e 64 20 74 68   callback and th
31740 65 6e 20 6f 6e 65 0a 2a 2a 20 6c 61 73 74 20 74  en one.** last t
31750 69 6d 65 20 77 68 65 6e 20 74 68 65 20 78 46 69  ime when the xFi
31760 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  nal callback is 
31770 69 6e 76 6f 6b 65 64 2e 20 20 5e 28 57 68 65 6e  invoked.  ^(When
31780 20 6e 6f 20 72 6f 77 73 20 6d 61 74 63 68 0a 2a   no rows match.*
31790 2a 20 61 6e 20 61 67 67 72 65 67 61 74 65 20 71  * an aggregate q
317a0 75 65 72 79 2c 20 74 68 65 20 78 53 74 65 70 28  uery, the xStep(
317b0 29 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68  ) callback of th
317c0 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63  e aggregate func
317d0 74 69 6f 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e  tion.** implemen
317e0 74 61 74 69 6f 6e 20 69 73 20 6e 65 76 65 72 20  tation is never 
317f0 63 61 6c 6c 65 64 20 61 6e 64 20 78 46 69 6e 61  called and xFina
31800 6c 28 29 20 69 73 20 63 61 6c 6c 65 64 20 65 78  l() is called ex
31810 61 63 74 6c 79 20 6f 6e 63 65 2e 0a 2a 2a 20 49  actly once..** I
31820 6e 20 74 68 6f 73 65 20 63 61 73 65 73 2c 20 73  n those cases, s
31830 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
31840 5f 63 6f 6e 74 65 78 74 28 29 20 6d 69 67 68 74  _context() might
31850 20 62 65 20 63 61 6c 6c 65 64 20 66 6f 72 20 74   be called for t
31860 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 69 6d 65  he.** first time
31870 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 78 46 69   from within xFi
31880 6e 61 6c 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  nal().)^.**.** ^
31890 54 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72  The sqlite3_aggr
318a0 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c  egate_context(C,
318b0 4e 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  N) routine retur
318c0 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ns a NULL pointe
318d0 72 20 0a 2a 2a 20 77 68 65 6e 20 66 69 72 73 74  r .** when first
318e0 20 63 61 6c 6c 65 64 20 69 66 20 4e 20 69 73 20   called if N is 
318f0 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75  less than or equ
31900 61 6c 20 74 6f 20 7a 65 72 6f 20 6f 72 20 69 66  al to zero or if
31910 20 61 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c   a memory.** all
31920 6f 63 61 74 65 20 65 72 72 6f 72 20 6f 63 63 75  ocate error occu
31930 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  rs..**.** ^(The 
31940 61 6d 6f 75 6e 74 20 6f 66 20 73 70 61 63 65 20  amount of space 
31950 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c  allocated by sql
31960 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
31970 6f 6e 74 65 78 74 28 43 2c 4e 29 20 69 73 0a 2a  ontext(C,N) is.*
31980 2a 20 64 65 74 65 72 6d 69 6e 65 64 20 62 79 20  * determined by 
31990 74 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20  the N parameter 
319a0 6f 6e 20 66 69 72 73 74 20 73 75 63 63 65 73 73  on first success
319b0 66 75 6c 20 63 61 6c 6c 2e 20 20 43 68 61 6e 67  ful call.  Chang
319c0 69 6e 67 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65  ing the.** value
319d0 20 6f 66 20 4e 20 69 6e 20 73 75 62 73 65 71 75   of N in subsequ
319e0 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  ent call to sqli
319f0 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
31a00 6e 74 65 78 74 28 29 20 77 69 74 68 69 6e 0a 2a  ntext() within.*
31a10 2a 20 74 68 65 20 73 61 6d 65 20 61 67 67 72 65  * the same aggre
31a20 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e  gate function in
31a30 73 74 61 6e 63 65 20 77 69 6c 6c 20 6e 6f 74 20  stance will not 
31a40 72 65 73 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72  resize the memor
31a50 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 2e  y.** allocation.
31a60 29 5e 20 20 57 69 74 68 69 6e 20 74 68 65 20 78  )^  Within the x
31a70 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 2c 20  Final callback, 
31a80 69 74 20 69 73 20 63 75 73 74 6f 6d 61 72 79 20  it is customary 
31a90 74 6f 20 73 65 74 0a 2a 2a 20 4e 3d 30 20 69 6e  to set.** N=0 in
31aa0 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
31ab0 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
31ac0 65 78 74 28 43 2c 4e 29 20 73 6f 20 74 68 61 74  ext(C,N) so that
31ad0 20 6e 6f 20 0a 2a 2a 20 70 6f 69 6e 74 6c 65 73   no .** pointles
31ae0 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  s memory allocat
31af0 69 6f 6e 73 20 6f 63 63 75 72 2e 0a 2a 2a 0a 2a  ions occur..**.*
31b00 2a 20 5e 53 51 4c 69 74 65 20 61 75 74 6f 6d 61  * ^SQLite automa
31b10 74 69 63 61 6c 6c 79 20 66 72 65 65 73 20 74 68  tically frees th
31b20 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
31b30 65 64 20 62 79 20 0a 2a 2a 20 73 71 6c 69 74 65  ed by .** sqlite
31b40 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
31b50 65 78 74 28 29 20 77 68 65 6e 20 74 68 65 20 61  ext() when the a
31b60 67 67 72 65 67 61 74 65 20 71 75 65 72 79 20 63  ggregate query c
31b70 6f 6e 63 6c 75 64 65 73 2e 0a 2a 2a 0a 2a 2a 20  oncludes..**.** 
31b80 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
31b90 74 65 72 20 6d 75 73 74 20 62 65 20 61 20 63 6f  ter must be a co
31ba0 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71  py of the.** [sq
31bb0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 7c 20  lite3_context | 
31bc0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63 6f 6e  SQL function con
31bd0 74 65 78 74 5d 20 74 68 61 74 20 69 73 20 74 68  text] that is th
31be0 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
31bf0 72 0a 2a 2a 20 74 6f 20 74 68 65 20 78 53 74 65  r.** to the xSte
31c00 70 20 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c  p or xFinal call
31c10 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 74 68 61  back routine tha
31c20 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65  t implements the
31c30 20 61 67 67 72 65 67 61 74 65 0a 2a 2a 20 66 75   aggregate.** fu
31c40 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68  nction..**.** Th
31c50 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20  is routine must 
31c60 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74  be called from t
31c70 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69  he same thread i
31c80 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61  n which.** the a
31c90 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e  ggregate SQL fun
31ca0 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67  ction is running
31cb0 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74  ..*/.void *sqlit
31cc0 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
31cd0 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e  text(sqlite3_con
31ce0 74 65 78 74 2a 2c 20 69 6e 74 20 6e 42 79 74 65  text*, int nByte
31cf0 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  s);../*.** CAPI3
31d00 52 45 46 3a 20 55 73 65 72 20 44 61 74 61 20 46  REF: User Data F
31d10 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a  or Functions.**.
31d20 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
31d30 75 73 65 72 5f 64 61 74 61 28 29 20 69 6e 74 65  user_data() inte
31d40 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
31d50 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70  copy of.** the p
31d60 6f 69 6e 74 65 72 20 74 68 61 74 20 77 61 73 20  ointer that was 
31d70 74 68 65 20 70 55 73 65 72 44 61 74 61 20 70 61  the pUserData pa
31d80 72 61 6d 65 74 65 72 20 28 74 68 65 20 35 74 68  rameter (the 5th
31d90 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f   parameter).** o
31da0 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  f the [sqlite3_c
31db0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
31dc0 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65  ].** and [sqlite
31dd0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
31de0 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20  n16()] routines 
31df0 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a  that originally.
31e00 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20 74 68  ** registered th
31e10 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65  e application de
31e20 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a  fined function..
31e30 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  **.** This routi
31e40 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65  ne must be calle
31e50 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20  d from the same 
31e60 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a  thread in which.
31e70 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ** the applicati
31e80 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
31e90 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  ion is running..
31ea0 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  */.void *sqlite3
31eb0 5f 75 73 65 72 5f 64 61 74 61 28 73 71 6c 69 74  _user_data(sqlit
31ec0 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f  e3_context*);../
31ed0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
31ee0 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69  atabase Connecti
31ef0 6f 6e 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73  on For Functions
31f00 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
31f10 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68  te3_context_db_h
31f20 61 6e 64 6c 65 28 29 20 69 6e 74 65 72 66 61 63  andle() interfac
31f30 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79  e returns a copy
31f40 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74   of.** the point
31f50 65 72 20 74 6f 20 74 68 65 20 5b 64 61 74 61 62  er to the [datab
31f60 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
31f70 28 74 68 65 20 31 73 74 20 70 61 72 61 6d 65 74  (the 1st paramet
31f80 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73  er).** of the [s
31f90 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
31fa0 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64  nction()].** and
31fb0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
31fc0 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72  _function16()] r
31fd0 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69  outines that ori
31fe0 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73  ginally.** regis
31ff0 74 65 72 65 64 20 74 68 65 20 61 70 70 6c 69 63  tered the applic
32000 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75  ation defined fu
32010 6e 63 74 69 6f 6e 2e 0a 2a 2f 0a 73 71 6c 69 74  nction..*/.sqlit
32020 65 33 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6e 74  e3 *sqlite3_cont
32030 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71  ext_db_handle(sq
32040 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b  lite3_context*);
32050 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
32060 3a 20 46 75 6e 63 74 69 6f 6e 20 41 75 78 69 6c  : Function Auxil
32070 69 61 72 79 20 44 61 74 61 0a 2a 2a 0a 2a 2a 20  iary Data.**.** 
32080 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 77  The following tw
32090 6f 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20  o functions may 
320a0 62 65 20 75 73 65 64 20 62 79 20 73 63 61 6c 61  be used by scala
320b0 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  r SQL functions 
320c0 74 6f 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 20  to.** associate 
320d0 6d 65 74 61 64 61 74 61 20 77 69 74 68 20 61 72  metadata with ar
320e0 67 75 6d 65 6e 74 20 76 61 6c 75 65 73 2e 20 49  gument values. I
320f0 66 20 74 68 65 20 73 61 6d 65 20 76 61 6c 75 65  f the same value
32100 20 69 73 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a   is passed to.**
32110 20 6d 75 6c 74 69 70 6c 65 20 69 6e 76 6f 63 61   multiple invoca
32120 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d  tions of the sam
32130 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 64  e SQL function d
32140 75 72 69 6e 67 20 71 75 65 72 79 20 65 78 65 63  uring query exec
32150 75 74 69 6f 6e 2c 20 75 6e 64 65 72 0a 2a 2a 20  ution, under.** 
32160 73 6f 6d 65 20 63 69 72 63 75 6d 73 74 61 6e 63  some circumstanc
32170 65 73 20 74 68 65 20 61 73 73 6f 63 69 61 74 65  es the associate
32180 64 20 6d 65 74 61 64 61 74 61 20 6d 61 79 20 62  d metadata may b
32190 65 20 70 72 65 73 65 72 76 65 64 2e 20 54 68 69  e preserved. Thi
321a0 73 20 6d 61 79 0a 2a 2a 20 62 65 20 75 73 65 64  s may.** be used
321b0 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 74  , for example, t
321c0 6f 20 61 64 64 20 61 20 72 65 67 75 6c 61 72 2d  o add a regular-
321d0 65 78 70 72 65 73 73 69 6f 6e 20 6d 61 74 63 68  expression match
321e0 69 6e 67 20 73 63 61 6c 61 72 0a 2a 2a 20 66 75  ing scalar.** fu
321f0 6e 63 74 69 6f 6e 2e 20 54 68 65 20 63 6f 6d 70  nction. The comp
32200 69 6c 65 64 20 76 65 72 73 69 6f 6e 20 6f 66 20  iled version of 
32210 74 68 65 20 72 65 67 75 6c 61 72 20 65 78 70 72  the regular expr
32220 65 73 73 69 6f 6e 20 69 73 20 73 74 6f 72 65 64  ession is stored
32230 20 61 73 0a 2a 2a 20 6d 65 74 61 64 61 74 61 20   as.** metadata 
32240 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
32250 74 68 65 20 53 51 4c 20 76 61 6c 75 65 20 70 61  the SQL value pa
32260 73 73 65 64 20 61 73 20 74 68 65 20 72 65 67 75  ssed as the regu
32270 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 0a 2a  lar expression.*
32280 2a 20 70 61 74 74 65 72 6e 2e 20 20 54 68 65 20  * pattern.  The 
32290 63 6f 6d 70 69 6c 65 64 20 72 65 67 75 6c 61 72  compiled regular
322a0 20 65 78 70 72 65 73 73 69 6f 6e 20 63 61 6e 20   expression can 
322b0 62 65 20 72 65 75 73 65 64 20 6f 6e 20 6d 75 6c  be reused on mul
322c0 74 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f 63 61 74  tiple.** invocat
322d0 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65  ions of the same
322e0 20 66 75 6e 63 74 69 6f 6e 20 73 6f 20 74 68 61   function so tha
322f0 74 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 70  t the original p
32300 61 74 74 65 72 6e 20 73 74 72 69 6e 67 0a 2a 2a  attern string.**
32310 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74   does not need t
32320 6f 20 62 65 20 72 65 63 6f 6d 70 69 6c 65 64 20  o be recompiled 
32330 6f 6e 20 65 61 63 68 20 69 6e 76 6f 63 61 74 69  on each invocati
32340 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  on..**.** ^The s
32350 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61  qlite3_get_auxda
32360 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  ta() interface r
32370 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
32380 20 74 6f 20 74 68 65 20 6d 65 74 61 64 61 74 61   to the metadata
32390 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 62  .** associated b
323a0 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65  y the sqlite3_se
323b0 74 5f 61 75 78 64 61 74 61 28 29 20 66 75 6e 63  t_auxdata() func
323c0 74 69 6f 6e 20 77 69 74 68 20 74 68 65 20 4e 74  tion with the Nt
323d0 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 76 61  h argument.** va
323e0 6c 75 65 20 74 6f 20 74 68 65 20 61 70 70 6c 69  lue to the appli
323f0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
32400 75 6e 63 74 69 6f 6e 2e 20 5e 49 66 20 6e 6f 20  unction. ^If no 
32410 6d 65 74 61 64 61 74 61 20 68 61 73 20 62 65 65  metadata has bee
32420 6e 20 65 76 65 72 0a 2a 2a 20 62 65 65 6e 20 73  n ever.** been s
32430 65 74 20 66 6f 72 20 74 68 65 20 4e 74 68 20 61  et for the Nth a
32440 72 67 75 6d 65 6e 74 20 6f 66 20 74 68 65 20 66  rgument of the f
32450 75 6e 63 74 69 6f 6e 2c 20 6f 72 20 69 66 20 74  unction, or if t
32460 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
32470 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 61 72  .** function par
32480 61 6d 65 74 65 72 20 68 61 73 20 63 68 61 6e 67  ameter has chang
32490 65 64 20 73 69 6e 63 65 20 74 68 65 20 6d 65 74  ed since the met
324a0 61 2d 64 61 74 61 20 77 61 73 20 73 65 74 2c 0a  a-data was set,.
324b0 2a 2a 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  ** then sqlite3_
324c0 67 65 74 5f 61 75 78 64 61 74 61 28 29 20 72 65  get_auxdata() re
324d0 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69  turns a NULL poi
324e0 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  nter..**.** ^The
324f0 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78   sqlite3_set_aux
32500 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65  data() interface
32510 20 73 61 76 65 73 20 74 68 65 20 6d 65 74 61 64   saves the metad
32520 61 74 61 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74  ata.** pointed t
32530 6f 20 62 79 20 69 74 73 20 33 72 64 20 70 61 72  o by its 3rd par
32540 61 6d 65 74 65 72 20 61 73 20 74 68 65 20 6d 65  ameter as the me
32550 74 61 64 61 74 61 20 66 6f 72 20 74 68 65 20 4e  tadata for the N
32560 2d 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  -th.** argument 
32570 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  of the applicati
32580 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
32590 69 6f 6e 2e 20 20 53 75 62 73 65 71 75 65 6e 74  ion.  Subsequent
325a0 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  .** calls to sql
325b0 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61  ite3_get_auxdata
325c0 28 29 20 6d 69 67 68 74 20 72 65 74 75 72 6e 20  () might return 
325d0 74 68 69 73 20 64 61 74 61 2c 20 69 66 20 69 74  this data, if it
325e0 20 68 61 73 0a 2a 2a 20 6e 6f 74 20 62 65 65 6e   has.** not been
325f0 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a 20 5e   destroyed..** ^
32600 49 66 20 69 74 20 69 73 20 6e 6f 74 20 4e 55 4c  If it is not NUL
32610 4c 2c 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 69  L, SQLite will i
32620 6e 76 6f 6b 65 20 74 68 65 20 64 65 73 74 72 75  nvoke the destru
32630 63 74 6f 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  ctor.** function
32640 20 67 69 76 65 6e 20 62 79 20 74 68 65 20 34 74   given by the 4t
32650 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  h parameter to s
32660 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
32670 74 61 28 29 20 6f 6e 0a 2a 2a 20 74 68 65 20 6d  ta() on.** the m
32680 65 74 61 64 61 74 61 20 77 68 65 6e 20 74 68 65  etadata when the
32690 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 66   corresponding f
326a0 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 65  unction paramete
326b0 72 20 63 68 61 6e 67 65 73 0a 2a 2a 20 6f 72 20  r changes.** or 
326c0 77 68 65 6e 20 74 68 65 20 53 51 4c 20 73 74 61  when the SQL sta
326d0 74 65 6d 65 6e 74 20 63 6f 6d 70 6c 65 74 65 73  tement completes
326e0 2c 20 77 68 69 63 68 65 76 65 72 20 63 6f 6d 65  , whichever come
326f0 73 20 66 69 72 73 74 2e 0a 2a 2a 0a 2a 2a 20 53  s first..**.** S
32700 51 4c 69 74 65 20 69 73 20 66 72 65 65 20 74 6f  QLite is free to
32710 20 63 61 6c 6c 20 74 68 65 20 64 65 73 74 72 75   call the destru
32720 63 74 6f 72 20 61 6e 64 20 64 72 6f 70 20 6d 65  ctor and drop me
32730 74 61 64 61 74 61 20 6f 6e 20 61 6e 79 0a 2a 2a  tadata on any.**
32740 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 61 6e   parameter of an
32750 79 20 66 75 6e 63 74 69 6f 6e 20 61 74 20 61 6e  y function at an
32760 79 20 74 69 6d 65 2e 20 20 5e 54 68 65 20 6f 6e  y time.  ^The on
32770 6c 79 20 67 75 61 72 61 6e 74 65 65 20 69 73 20  ly guarantee is 
32780 74 68 61 74 0a 2a 2a 20 74 68 65 20 64 65 73 74  that.** the dest
32790 72 75 63 74 6f 72 20 77 69 6c 6c 20 62 65 20 63  ructor will be c
327a0 61 6c 6c 65 64 20 62 65 66 6f 72 65 20 74 68 65  alled before the
327b0 20 6d 65 74 61 64 61 74 61 20 69 73 20 64 72 6f   metadata is dro
327c0 70 70 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e  pped..**.** ^(In
327d0 20 70 72 61 63 74 69 63 65 2c 20 6d 65 74 61 64   practice, metad
327e0 61 74 61 20 69 73 20 70 72 65 73 65 72 76 65 64  ata is preserved
327f0 20 62 65 74 77 65 65 6e 20 66 75 6e 63 74 69 6f   between functio
32800 6e 20 63 61 6c 6c 73 20 66 6f 72 0a 2a 2a 20 65  n calls for.** e
32810 78 70 72 65 73 73 69 6f 6e 73 20 74 68 61 74 20  xpressions that 
32820 61 72 65 20 63 6f 6e 73 74 61 6e 74 20 61 74 20  are constant at 
32830 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 54 68  compile time. Th
32840 69 73 20 69 6e 63 6c 75 64 65 73 20 6c 69 74 65  is includes lite
32850 72 61 6c 0a 2a 2a 20 76 61 6c 75 65 73 20 61 6e  ral.** values an
32860 64 20 5b 70 61 72 61 6d 65 74 65 72 73 5d 2e 29  d [parameters].)
32870 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ^.**.** These ro
32880 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63  utines must be c
32890 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73  alled from the s
328a0 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68  ame thread in wh
328b0 69 63 68 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66  ich.** the SQL f
328c0 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69  unction is runni
328d0 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c  ng..*/.void *sql
328e0 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61  ite3_get_auxdata
328f0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
32900 2a 2c 20 69 6e 74 20 4e 29 3b 0a 76 6f 69 64 20  *, int N);.void 
32910 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
32920 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ata(sqlite3_cont
32930 65 78 74 2a 2c 20 69 6e 74 20 4e 2c 20 76 6f 69  ext*, int N, voi
32940 64 2a 2c 20 76 6f 69 64 20 28 2a 29 28 76 6f 69  d*, void (*)(voi
32950 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41  d*));.../*.** CA
32960 50 49 33 52 45 46 3a 20 43 6f 6e 73 74 61 6e 74  PI3REF: Constant
32970 73 20 44 65 66 69 6e 69 6e 67 20 53 70 65 63 69  s Defining Speci
32980 61 6c 20 44 65 73 74 72 75 63 74 6f 72 20 42 65  al Destructor Be
32990 68 61 76 69 6f 72 0a 2a 2a 0a 2a 2a 20 54 68 65  havior.**.** The
329a0 73 65 20 61 72 65 20 73 70 65 63 69 61 6c 20 76  se are special v
329b0 61 6c 75 65 73 20 66 6f 72 20 74 68 65 20 64 65  alues for the de
329c0 73 74 72 75 63 74 6f 72 20 74 68 61 74 20 69 73  structor that is
329d0 20 70 61 73 73 65 64 20 69 6e 20 61 73 20 74 68   passed in as th
329e0 65 0a 2a 2a 20 66 69 6e 61 6c 20 61 72 67 75 6d  e.** final argum
329f0 65 6e 74 20 74 6f 20 72 6f 75 74 69 6e 65 73 20  ent to routines 
32a00 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 72 65  like [sqlite3_re
32a10 73 75 6c 74 5f 62 6c 6f 62 28 29 5d 2e 20 20 5e  sult_blob()].  ^
32a20 49 66 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  If the destructo
32a30 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73  r.** argument is
32a40 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20   SQLITE_STATIC, 
32a50 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  it means that th
32a60 65 20 63 6f 6e 74 65 6e 74 20 70 6f 69 6e 74 65  e content pointe
32a70 72 20 69 73 20 63 6f 6e 73 74 61 6e 74 0a 2a 2a  r is constant.**
32a80 20 61 6e 64 20 77 69 6c 6c 20 6e 65 76 65 72 20   and will never 
32a90 63 68 61 6e 67 65 2e 20 20 49 74 20 64 6f 65 73  change.  It does
32aa0 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20   not need to be 
32ab0 64 65 73 74 72 6f 79 65 64 2e 20 20 5e 54 68 65  destroyed.  ^The
32ac0 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 52 41 4e 53  .** SQLITE_TRANS
32ad0 49 45 4e 54 20 76 61 6c 75 65 20 6d 65 61 6e 73  IENT value means
32ae0 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e   that the conten
32af0 74 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 63 68  t will likely ch
32b00 61 6e 67 65 20 69 6e 0a 2a 2a 20 74 68 65 20 6e  ange in.** the n
32b10 65 61 72 20 66 75 74 75 72 65 20 61 6e 64 20 74  ear future and t
32b20 68 61 74 20 53 51 4c 69 74 65 20 73 68 6f 75 6c  hat SQLite shoul
32b30 64 20 6d 61 6b 65 20 69 74 73 20 6f 77 6e 20 70  d make its own p
32b40 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 0a 2a  rivate copy of.*
32b50 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 62 65  * the content be
32b60 66 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 2e 0a  fore returning..
32b70 2a 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 64 65  **.** The typede
32b80 66 20 69 73 20 6e 65 63 65 73 73 61 72 79 20 74  f is necessary t
32b90 6f 20 77 6f 72 6b 20 61 72 6f 75 6e 64 20 70 72  o work around pr
32ba0 6f 62 6c 65 6d 73 20 69 6e 20 63 65 72 74 61 69  oblems in certai
32bb0 6e 0a 2a 2a 20 43 2b 2b 20 63 6f 6d 70 69 6c 65  n.** C++ compile
32bc0 72 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 76  rs..*/.typedef v
32bd0 6f 69 64 20 28 2a 73 71 6c 69 74 65 33 5f 64 65  oid (*sqlite3_de
32be0 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 28 76  structor_type)(v
32bf0 6f 69 64 2a 29 3b 0a 23 64 65 66 69 6e 65 20 53  oid*);.#define S
32c00 51 4c 49 54 45 5f 53 54 41 54 49 43 20 20 20 20  QLITE_STATIC    
32c10 20 20 28 28 73 71 6c 69 74 65 33 5f 64 65 73 74    ((sqlite3_dest
32c20 72 75 63 74 6f 72 5f 74 79 70 65 29 30 29 0a 23  ructor_type)0).#
32c30 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52  define SQLITE_TR
32c40 41 4e 53 49 45 4e 54 20 20 20 28 28 73 71 6c 69  ANSIENT   ((sqli
32c50 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74  te3_destructor_t
32c60 79 70 65 29 2d 31 29 0a 0a 2f 2a 0a 2a 2a 20 43  ype)-1)../*.** C
32c70 41 50 49 33 52 45 46 3a 20 53 65 74 74 69 6e 67  API3REF: Setting
32c80 20 54 68 65 20 52 65 73 75 6c 74 20 4f 66 20 41   The Result Of A
32c90 6e 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 0a 2a  n SQL Function.*
32ca0 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
32cb0 6e 65 73 20 61 72 65 20 75 73 65 64 20 62 79 20  nes are used by 
32cc0 74 68 65 20 78 46 75 6e 63 20 6f 72 20 78 46 69  the xFunc or xFi
32cd0 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 73 20 74 68  nal callbacks th
32ce0 61 74 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 20  at.** implement 
32cf0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e  SQL functions an
32d00 64 20 61 67 67 72 65 67 61 74 65 73 2e 20 20 53  d aggregates.  S
32d10 65 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  ee.** [sqlite3_c
32d20 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
32d30 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  ] and [sqlite3_c
32d40 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
32d50 28 29 5d 0a 2a 2a 20 66 6f 72 20 61 64 64 69 74  ()].** for addit
32d60 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f  ional informatio
32d70 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66  n..**.** These f
32d80 75 6e 63 74 69 6f 6e 73 20 77 6f 72 6b 20 76 65  unctions work ve
32d90 72 79 20 6d 75 63 68 20 6c 69 6b 65 20 74 68 65  ry much like the
32da0 20 5b 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64   [parameter bind
32db0 69 6e 67 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a  ing] family of.*
32dc0 2a 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 64  * functions used
32dd0 20 74 6f 20 62 69 6e 64 20 76 61 6c 75 65 73 20   to bind values 
32de0 74 6f 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65  to host paramete
32df0 72 73 20 69 6e 20 70 72 65 70 61 72 65 64 20 73  rs in prepared s
32e00 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 52 65  tatements..** Re
32e10 66 65 72 20 74 6f 20 74 68 65 20 5b 53 51 4c 20  fer to the [SQL 
32e20 70 61 72 61 6d 65 74 65 72 5d 20 64 6f 63 75 6d  parameter] docum
32e30 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 64 64  entation for add
32e40 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74  itional informat
32e50 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ion..**.** ^The 
32e60 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62  sqlite3_result_b
32e70 6c 6f 62 28 29 20 69 6e 74 65 72 66 61 63 65 20  lob() interface 
32e80 73 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 20  sets the result 
32e90 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69  from.** an appli
32ea0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
32eb0 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68  unction to be th
32ec0 65 20 42 4c 4f 42 20 77 68 6f 73 65 20 63 6f 6e  e BLOB whose con
32ed0 74 65 6e 74 20 69 73 20 70 6f 69 6e 74 65 64 0a  tent is pointed.
32ee0 2a 2a 20 74 6f 20 62 79 20 74 68 65 20 73 65 63  ** to by the sec
32ef0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 6e  ond parameter an
32f00 64 20 77 68 69 63 68 20 69 73 20 4e 20 62 79 74  d which is N byt
32f10 65 73 20 6c 6f 6e 67 20 77 68 65 72 65 20 4e 20  es long where N 
32f20 69 73 20 74 68 65 0a 2a 2a 20 74 68 69 72 64 20  is the.** third 
32f30 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a  parameter..**.**
32f40 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
32f50 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 29 20  sult_zeroblob() 
32f60 69 6e 74 65 72 66 61 63 65 73 20 73 65 74 20 74  interfaces set t
32f70 68 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20  he result of.** 
32f80 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
32f90 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
32fa0 20 74 6f 20 62 65 20 61 20 42 4c 4f 42 20 63 6f   to be a BLOB co
32fb0 6e 74 61 69 6e 69 6e 67 20 61 6c 6c 20 7a 65 72  ntaining all zer
32fc0 6f 0a 2a 2a 20 62 79 74 65 73 20 61 6e 64 20 4e  o.** bytes and N
32fd0 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 2c 20   bytes in size, 
32fe0 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 76  where N is the v
32ff0 61 6c 75 65 20 6f 66 20 74 68 65 20 32 6e 64 20  alue of the 2nd 
33000 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a  parameter..**.**
33010 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
33020 73 75 6c 74 5f 64 6f 75 62 6c 65 28 29 20 69 6e  sult_double() in
33030 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65  terface sets the
33040 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20   result from.** 
33050 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  an application-d
33060 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
33070 74 6f 20 62 65 20 61 20 66 6c 6f 61 74 69 6e 67  to be a floating
33080 20 70 6f 69 6e 74 20 76 61 6c 75 65 20 73 70 65   point value spe
33090 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 69 74 73  cified.** by its
330a0 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a   2nd argument..*
330b0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
330c0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
330d0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73   and sqlite3_res
330e0 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 66 75  ult_error16() fu
330f0 6e 63 74 69 6f 6e 73 0a 2a 2a 20 63 61 75 73 65  nctions.** cause
33100 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 65 64   the implemented
33110 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f   SQL function to
33120 20 74 68 72 6f 77 20 61 6e 20 65 78 63 65 70 74   throw an except
33130 69 6f 6e 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ion..** ^SQLite 
33140 75 73 65 73 20 74 68 65 20 73 74 72 69 6e 67 20  uses the string 
33150 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68  pointed to by th
33160 65 0a 2a 2a 20 32 6e 64 20 70 61 72 61 6d 65 74  e.** 2nd paramet
33170 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 72 65  er of sqlite3_re
33180 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72 20  sult_error() or 
33190 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
331a0 72 72 6f 72 31 36 28 29 0a 2a 2a 20 61 73 20 74  rror16().** as t
331b0 68 65 20 74 65 78 74 20 6f 66 20 61 6e 20 65 72  he text of an er
331c0 72 6f 72 20 6d 65 73 73 61 67 65 2e 20 20 5e 53  ror message.  ^S
331d0 51 4c 69 74 65 20 69 6e 74 65 72 70 72 65 74 73  QLite interprets
331e0 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65   the error.** me
331f0 73 73 61 67 65 20 73 74 72 69 6e 67 20 66 72 6f  ssage string fro
33200 6d 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  m sqlite3_result
33210 5f 65 72 72 6f 72 28 29 20 61 73 20 55 54 46 2d  _error() as UTF-
33220 38 2e 20 5e 53 51 4c 69 74 65 0a 2a 2a 20 69 6e  8. ^SQLite.** in
33230 74 65 72 70 72 65 74 73 20 74 68 65 20 73 74 72  terprets the str
33240 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  ing from sqlite3
33250 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
33260 29 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 6e  ) as UTF-16 in n
33270 61 74 69 76 65 0a 2a 2a 20 62 79 74 65 20 6f 72  ative.** byte or
33280 64 65 72 2e 20 20 5e 49 66 20 74 68 65 20 74 68  der.  ^If the th
33290 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
332a0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
332b0 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71  error().** or sq
332c0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
332d0 6f 72 31 36 28 29 20 69 73 20 6e 65 67 61 74 69  or16() is negati
332e0 76 65 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74  ve then SQLite t
332f0 61 6b 65 73 20 61 73 20 74 68 65 20 65 72 72 6f  akes as the erro
33300 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 61 6c 6c  r.** message all
33310 20 74 65 78 74 20 75 70 20 74 68 72 6f 75 67 68   text up through
33320 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20   the first zero 
33330 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 5e 49  character..** ^I
33340 66 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  f the third para
33350 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
33360 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20  _result_error() 
33370 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65  or.** sqlite3_re
33380 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 69  sult_error16() i
33390 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 74  s non-negative t
333a0 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73  hen SQLite takes
333b0 20 74 68 61 74 20 6d 61 6e 79 0a 2a 2a 20 62 79   that many.** by
333c0 74 65 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74  tes (not charact
333d0 65 72 73 29 20 66 72 6f 6d 20 74 68 65 20 32 6e  ers) from the 2n
333e0 64 20 70 61 72 61 6d 65 74 65 72 20 61 73 20 74  d parameter as t
333f0 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  he error message
33400 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
33410 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
33420 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73   and sqlite3_res
33430 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a  ult_error16().**
33440 20 72 6f 75 74 69 6e 65 73 20 6d 61 6b 65 20 61   routines make a
33450 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66   private copy of
33460 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61   the error messa
33470 67 65 20 74 65 78 74 20 62 65 66 6f 72 65 0a 2a  ge text before.*
33480 2a 20 74 68 65 79 20 72 65 74 75 72 6e 2e 20 20  * they return.  
33490 48 65 6e 63 65 2c 20 74 68 65 20 63 61 6c 6c 69  Hence, the calli
334a0 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20  ng function can 
334b0 64 65 61 6c 6c 6f 63 61 74 65 20 6f 72 0a 2a 2a  deallocate or.**
334c0 20 6d 6f 64 69 66 79 20 74 68 65 20 74 65 78 74   modify the text
334d0 20 61 66 74 65 72 20 74 68 65 79 20 72 65 74 75   after they retu
334e0 72 6e 20 77 69 74 68 6f 75 74 20 68 61 72 6d 2e  rn without harm.
334f0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
33500 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f  _result_error_co
33510 64 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 68  de() function ch
33520 61 6e 67 65 73 20 74 68 65 20 65 72 72 6f 72 20  anges the error 
33530 63 6f 64 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64  code.** returned
33540 20 62 79 20 53 51 4c 69 74 65 20 61 73 20 61 20   by SQLite as a 
33550 72 65 73 75 6c 74 20 6f 66 20 61 6e 20 65 72 72  result of an err
33560 6f 72 20 69 6e 20 61 20 66 75 6e 63 74 69 6f 6e  or in a function
33570 2e 20 20 5e 42 79 20 64 65 66 61 75 6c 74 2c 0a  .  ^By default,.
33580 2a 2a 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64  ** the error cod
33590 65 20 69 73 20 53 51 4c 49 54 45 5f 45 52 52 4f  e is SQLITE_ERRO
335a0 52 2e 20 20 5e 41 20 73 75 62 73 65 71 75 65 6e  R.  ^A subsequen
335b0 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  t call to sqlite
335c0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
335d0 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  .** or sqlite3_r
335e0 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20  esult_error16() 
335f0 72 65 73 65 74 73 20 74 68 65 20 65 72 72 6f 72  resets the error
33600 20 63 6f 64 65 20 74 6f 20 53 51 4c 49 54 45 5f   code to SQLITE_
33610 45 52 52 4f 52 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ERROR..**.** ^Th
33620 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
33630 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28 29 20  _error_toobig() 
33640 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73  interface causes
33650 20 53 51 4c 69 74 65 20 74 6f 20 74 68 72 6f 77   SQLite to throw
33660 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 69 6e 64   an.** error ind
33670 69 63 61 74 69 6e 67 20 74 68 61 74 20 61 20 73  icating that a s
33680 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 69 73  tring or BLOB is
33690 20 74 6f 6f 20 6c 6f 6e 67 20 74 6f 20 72 65 70   too long to rep
336a0 72 65 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54  resent..**.** ^T
336b0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
336c0 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 29 20  t_error_nomem() 
336d0 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73  interface causes
336e0 20 53 51 4c 69 74 65 20 74 6f 20 74 68 72 6f 77   SQLite to throw
336f0 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 69 6e 64   an.** error ind
33700 69 63 61 74 69 6e 67 20 74 68 61 74 20 61 20 6d  icating that a m
33710 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
33720 20 66 61 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e   failed..**.** ^
33730 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
33740 6c 74 5f 69 6e 74 28 29 20 69 6e 74 65 72 66 61  lt_int() interfa
33750 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75  ce sets the retu
33760 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74  rn value.** of t
33770 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
33780 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
33790 74 6f 20 62 65 20 74 68 65 20 33 32 2d 62 69 74  to be the 32-bit
337a0 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a   signed integer.
337b0 2a 2a 20 76 61 6c 75 65 20 67 69 76 65 6e 20 69  ** value given i
337c0 6e 20 74 68 65 20 32 6e 64 20 61 72 67 75 6d 65  n the 2nd argume
337d0 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  nt..** ^The sqli
337e0 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34  te3_result_int64
337f0 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74  () interface set
33800 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  s the return val
33810 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70  ue.** of the app
33820 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
33830 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
33840 74 68 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65  the 64-bit signe
33850 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c  d integer.** val
33860 75 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20  ue given in the 
33870 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  2nd argument..**
33880 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
33890 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 29 20 69  _result_null() i
338a0 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68  nterface sets th
338b0 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a  e return value.*
338c0 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61  * of the applica
338d0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
338e0 63 74 69 6f 6e 20 74 6f 20 62 65 20 4e 55 4c 4c  ction to be NULL
338f0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
33900 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
33910 28 29 2c 20 73 71 6c 69 74 65 33 5f 72 65 73 75  (), sqlite3_resu
33920 6c 74 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20  lt_text16(),.** 
33930 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
33940 65 78 74 31 36 6c 65 28 29 2c 20 61 6e 64 20 73  ext16le(), and s
33950 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
33960 78 74 31 36 62 65 28 29 20 69 6e 74 65 72 66 61  xt16be() interfa
33970 63 65 73 0a 2a 2a 20 73 65 74 20 74 68 65 20 72  ces.** set the r
33980 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74  eturn value of t
33990 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
339a0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
339b0 74 6f 20 62 65 0a 2a 2a 20 61 20 74 65 78 74 20  to be.** a text 
339c0 73 74 72 69 6e 67 20 77 68 69 63 68 20 69 73 20  string which is 
339d0 72 65 70 72 65 73 65 6e 74 65 64 20 61 73 20 55  represented as U
339e0 54 46 2d 38 2c 20 55 54 46 2d 31 36 20 6e 61 74  TF-8, UTF-16 nat
339f0 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2c 0a  ive byte order,.
33a00 2a 2a 20 55 54 46 2d 31 36 20 6c 69 74 74 6c 65  ** UTF-16 little
33a10 20 65 6e 64 69 61 6e 2c 20 6f 72 20 55 54 46 2d   endian, or UTF-
33a20 31 36 20 62 69 67 20 65 6e 64 69 61 6e 2c 20 72  16 big endian, r
33a30 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20  espectively..** 
33a40 5e 53 51 4c 69 74 65 20 74 61 6b 65 73 20 74 68  ^SQLite takes th
33a50 65 20 74 65 78 74 20 72 65 73 75 6c 74 20 66 72  e text result fr
33a60 6f 6d 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  om the applicati
33a70 6f 6e 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 32  on from.** the 2
33a80 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20  nd parameter of 
33a90 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  the sqlite3_resu
33aa0 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61  lt_text* interfa
33ab0 63 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ces..** ^If the 
33ac0 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  3rd parameter to
33ad0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   the sqlite3_res
33ae0 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66  ult_text* interf
33af0 61 63 65 73 0a 2a 2a 20 69 73 20 6e 65 67 61 74  aces.** is negat
33b00 69 76 65 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  ive, then SQLite
33b10 20 74 61 6b 65 73 20 72 65 73 75 6c 74 20 74 65   takes result te
33b20 78 74 20 66 72 6f 6d 20 74 68 65 20 32 6e 64 20  xt from the 2nd 
33b30 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 68 72  parameter.** thr
33b40 6f 75 67 68 20 74 68 65 20 66 69 72 73 74 20 7a  ough the first z
33b50 65 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a  ero character..*
33b60 2a 20 5e 49 66 20 74 68 65 20 33 72 64 20 70 61  * ^If the 3rd pa
33b70 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73  rameter to the s
33b80 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
33b90 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  xt* interfaces.*
33ba0 2a 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  * is non-negativ
33bb0 65 2c 20 74 68 65 6e 20 61 73 20 6d 61 6e 79 20  e, then as many 
33bc0 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72 61  bytes (not chara
33bd0 63 74 65 72 73 29 20 6f 66 20 74 68 65 20 74 65  cters) of the te
33be0 78 74 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f  xt.** pointed to
33bf0 20 62 79 20 74 68 65 20 32 6e 64 20 70 61 72 61   by the 2nd para
33c00 6d 65 74 65 72 20 61 72 65 20 74 61 6b 65 6e 20  meter are taken 
33c10 61 73 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  as the applicati
33c20 6f 6e 2d 64 65 66 69 6e 65 64 0a 2a 2a 20 66 75  on-defined.** fu
33c30 6e 63 74 69 6f 6e 20 72 65 73 75 6c 74 2e 20 20  nction result.  
33c40 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d  If the 3rd param
33c50 65 74 65 72 20 69 73 20 6e 6f 6e 2d 6e 65 67 61  eter is non-nega
33c60 74 69 76 65 2c 20 74 68 65 6e 20 69 74 0a 2a 2a  tive, then it.**
33c70 20 6d 75 73 74 20 62 65 20 74 68 65 20 62 79 74   must be the byt
33c80 65 20 6f 66 66 73 65 74 20 69 6e 74 6f 20 74 68  e offset into th
33c90 65 20 73 74 72 69 6e 67 20 77 68 65 72 65 20 74  e string where t
33ca0 68 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 6f  he NUL terminato
33cb0 72 20 77 6f 75 6c 64 0a 2a 2a 20 61 70 70 65 61  r would.** appea
33cc0 72 20 69 66 20 74 68 65 20 73 74 72 69 6e 67 20  r if the string 
33cd0 77 68 65 72 65 20 4e 55 4c 20 74 65 72 6d 69 6e  where NUL termin
33ce0 61 74 65 64 2e 20 20 49 66 20 61 6e 79 20 4e 55  ated.  If any NU
33cf0 4c 20 63 68 61 72 61 63 74 65 72 73 20 6f 63 63  L characters occ
33d00 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20 73 74 72  ur.** in the str
33d10 69 6e 67 20 61 74 20 61 20 62 79 74 65 20 6f 66  ing at a byte of
33d20 66 73 65 74 20 74 68 61 74 20 69 73 20 6c 65 73  fset that is les
33d30 73 20 74 68 61 6e 20 74 68 65 20 76 61 6c 75 65  s than the value
33d40 20 6f 66 20 74 68 65 20 33 72 64 0a 2a 2a 20 70   of the 3rd.** p
33d50 61 72 61 6d 65 74 65 72 2c 20 74 68 65 6e 20 74  arameter, then t
33d60 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72  he resulting str
33d70 69 6e 67 20 77 69 6c 6c 20 63 6f 6e 74 61 69 6e  ing will contain
33d80 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 20 61   embedded NULs a
33d90 6e 64 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74  nd the.** result
33da0 20 6f 66 20 65 78 70 72 65 73 73 69 6f 6e 73 20   of expressions 
33db0 6f 70 65 72 61 74 69 6e 67 20 6f 6e 20 73 74 72  operating on str
33dc0 69 6e 67 73 20 77 69 74 68 20 65 6d 62 65 64 64  ings with embedd
33dd0 65 64 20 4e 55 4c 73 20 69 73 20 75 6e 64 65 66  ed NULs is undef
33de0 69 6e 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ined..** ^If the
33df0 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   4th parameter t
33e00 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65  o the sqlite3_re
33e10 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72  sult_text* inter
33e20 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69  faces.** or sqli
33e30 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20  te3_result_blob 
33e40 69 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f  is a non-NULL po
33e50 69 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 4c 69  inter, then SQLi
33e60 74 65 20 63 61 6c 6c 73 20 74 68 61 74 0a 2a 2a  te calls that.**
33e70 20 66 75 6e 63 74 69 6f 6e 20 61 73 20 74 68 65   function as the
33e80 20 64 65 73 74 72 75 63 74 6f 72 20 6f 6e 20 74   destructor on t
33e90 68 65 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 20  he text or BLOB 
33ea0 72 65 73 75 6c 74 20 77 68 65 6e 20 69 74 20 68  result when it h
33eb0 61 73 0a 2a 2a 20 66 69 6e 69 73 68 65 64 20 75  as.** finished u
33ec0 73 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c 74  sing that result
33ed0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68  ..** ^If the 4th
33ee0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
33ef0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
33f00 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65  _text* interface
33f10 73 20 6f 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  s or to.** sqlit
33f20 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69  e3_result_blob i
33f30 73 20 74 68 65 20 73 70 65 63 69 61 6c 20 63 6f  s the special co
33f40 6e 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 53 54  nstant SQLITE_ST
33f50 41 54 49 43 2c 20 74 68 65 6e 20 53 51 4c 69 74  ATIC, then SQLit
33f60 65 0a 2a 2a 20 61 73 73 75 6d 65 73 20 74 68 61  e.** assumes tha
33f70 74 20 74 68 65 20 74 65 78 74 20 6f 72 20 42 4c  t the text or BL
33f80 4f 42 20 72 65 73 75 6c 74 20 69 73 20 69 6e 20  OB result is in 
33f90 63 6f 6e 73 74 61 6e 74 20 73 70 61 63 65 20 61  constant space a
33fa0 6e 64 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 63  nd does not.** c
33fb0 6f 70 79 20 74 68 65 20 63 6f 6e 74 65 6e 74 20  opy the content 
33fc0 6f 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  of the parameter
33fd0 20 6e 6f 72 20 63 61 6c 6c 20 61 20 64 65 73 74   nor call a dest
33fe0 72 75 63 74 6f 72 20 6f 6e 20 74 68 65 20 63 6f  ructor on the co
33ff0 6e 74 65 6e 74 0a 2a 2a 20 77 68 65 6e 20 69 74  ntent.** when it
34000 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 75 73   has finished us
34010 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c 74 2e  ing that result.
34020 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20  .** ^If the 4th 
34030 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
34040 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
34050 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73  text* interfaces
34060 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  .** or sqlite3_r
34070 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68  esult_blob is th
34080 65 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74 61  e special consta
34090 6e 74 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49  nt SQLITE_TRANSI
340a0 45 4e 54 0a 2a 2a 20 74 68 65 6e 20 53 51 4c 69  ENT.** then SQLi
340b0 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20  te makes a copy 
340c0 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 6e  of the result in
340d0 74 6f 20 73 70 61 63 65 20 6f 62 74 61 69 6e 65  to space obtaine
340e0 64 20 66 72 6f 6d 0a 2a 2a 20 66 72 6f 6d 20 5b  d from.** from [
340f0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
34100 5d 20 62 65 66 6f 72 65 20 69 74 20 72 65 74 75  ] before it retu
34110 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  rns..**.** ^The 
34120 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
34130 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63 65  alue() interface
34140 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c 74   sets the result
34150 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69   of.** the appli
34160 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
34170 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20  unction to be a 
34180 63 6f 70 79 20 74 68 65 0a 2a 2a 20 5b 75 6e 70  copy the.** [unp
34190 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
341a0 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 73  _value] object s
341b0 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20  pecified by the 
341c0 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20  2nd parameter.  
341d0 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ^The.** sqlite3_
341e0 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 69  result_value() i
341f0 6e 74 65 72 66 61 63 65 20 6d 61 6b 65 73 20 61  nterface makes a
34200 20 63 6f 70 79 20 6f 66 20 74 68 65 20 5b 73 71   copy of the [sq
34210 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20  lite3_value].** 
34220 73 6f 20 74 68 61 74 20 74 68 65 20 5b 73 71 6c  so that the [sql
34230 69 74 65 33 5f 76 61 6c 75 65 5d 20 73 70 65 63  ite3_value] spec
34240 69 66 69 65 64 20 69 6e 20 74 68 65 20 70 61 72  ified in the par
34250 61 6d 65 74 65 72 20 6d 61 79 20 63 68 61 6e 67  ameter may chang
34260 65 20 6f 72 0a 2a 2a 20 62 65 20 64 65 61 6c 6c  e or.** be deall
34270 6f 63 61 74 65 64 20 61 66 74 65 72 20 73 71 6c  ocated after sql
34280 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75  ite3_result_valu
34290 65 28 29 20 72 65 74 75 72 6e 73 20 77 69 74 68  e() returns with
342a0 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e 41 20  out harm..** ^A 
342b0 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  [protected sqlit
342c0 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
342d0 20 6d 61 79 20 61 6c 77 61 79 73 20 62 65 20 75   may always be u
342e0 73 65 64 20 77 68 65 72 65 20 61 6e 0a 2a 2a 20  sed where an.** 
342f0 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c  [unprotected sql
34300 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
34310 63 74 20 69 73 20 72 65 71 75 69 72 65 64 2c 20  ct is required, 
34320 73 6f 20 65 69 74 68 65 72 0a 2a 2a 20 6b 69 6e  so either.** kin
34330 64 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 76 61  d of [sqlite3_va
34340 6c 75 65 5d 20 6f 62 6a 65 63 74 20 63 61 6e 20  lue] object can 
34350 62 65 20 75 73 65 64 20 77 69 74 68 20 74 68 69  be used with thi
34360 73 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a  s interface..**.
34370 2a 2a 20 49 66 20 74 68 65 73 65 20 72 6f 75 74  ** If these rout
34380 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20  ines are called 
34390 66 72 6f 6d 20 77 69 74 68 69 6e 20 74 68 65 20  from within the 
343a0 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64  different thread
343b0 0a 2a 2a 20 74 68 61 6e 20 74 68 65 20 6f 6e 65  .** than the one
343c0 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20   containing the 
343d0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
343e0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 68 61  ned function tha
343f0 74 20 72 65 63 65 69 76 65 64 0a 2a 2a 20 74 68  t received.** th
34400 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  e [sqlite3_conte
34410 78 74 5d 20 70 6f 69 6e 74 65 72 2c 20 74 68 65  xt] pointer, the
34420 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64   results are und
34430 65 66 69 6e 65 64 2e 0a 2a 2f 0a 76 6f 69 64 20  efined..*/.void 
34440 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62  sqlite3_result_b
34450 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  lob(sqlite3_cont
34460 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64  ext*, const void
34470 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28  *, int, void(*)(
34480 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71  void*));.void sq
34490 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75  lite3_result_dou
344a0 62 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ble(sqlite3_cont
344b0 65 78 74 2a 2c 20 64 6f 75 62 6c 65 29 3b 0a 76  ext*, double);.v
344c0 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
344d0 6c 74 5f 65 72 72 6f 72 28 73 71 6c 69 74 65 33  lt_error(sqlite3
344e0 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74  _context*, const
344f0 20 63 68 61 72 2a 2c 20 69 6e 74 29 3b 0a 76 6f   char*, int);.vo
34500 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
34510 74 5f 65 72 72 6f 72 31 36 28 73 71 6c 69 74 65  t_error16(sqlite
34520 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
34530 74 20 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76  t void*, int);.v
34540 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
34550 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28  lt_error_toobig(
34560 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
34570 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
34580 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d  result_error_nom
34590 65 6d 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  em(sqlite3_conte
345a0 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  xt*);.void sqlit
345b0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f  e3_result_error_
345c0 63 6f 64 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e  code(sqlite3_con
345d0 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69  text*, int);.voi
345e0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
345f0 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e  _int(sqlite3_con
34600 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69  text*, int);.voi
34610 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
34620 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 63  _int64(sqlite3_c
34630 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 33  ontext*, sqlite3
34640 5f 69 6e 74 36 34 29 3b 0a 76 6f 69 64 20 73 71  _int64);.void sq
34650 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c  lite3_result_nul
34660 6c 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  l(sqlite3_contex
34670 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  t*);.void sqlite
34680 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 73 71  3_result_text(sq
34690 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
346a0 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74  const char*, int
346b0 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  , void(*)(void*)
346c0 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
346d0 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28 73 71  result_text16(sq
346e0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
346f0 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
34700 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  , void(*)(void*)
34710 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
34720 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28  result_text16le(
34730 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
34740 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
34750 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  nt,void(*)(void*
34760 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  ));.void sqlite3
34770 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65  _result_text16be
34780 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
34790 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  *, const void*, 
347a0 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64  int,void(*)(void
347b0 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  *));.void sqlite
347c0 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 73  3_result_value(s
347d0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
347e0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29   sqlite3_value*)
347f0 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
34800 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 73  esult_zeroblob(s
34810 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
34820 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20   int n);../*.** 
34830 43 41 50 49 33 52 45 46 3a 20 44 65 66 69 6e 65  CAPI3REF: Define
34840 20 4e 65 77 20 43 6f 6c 6c 61 74 69 6e 67 20 53   New Collating S
34850 65 71 75 65 6e 63 65 73 0a 2a 2a 0a 2a 2a 20 5e  equences.**.** ^
34860 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  These functions 
34870 61 64 64 2c 20 72 65 6d 6f 76 65 2c 20 6f 72 20  add, remove, or 
34880 6d 6f 64 69 66 79 20 61 20 5b 63 6f 6c 6c 61 74  modify a [collat
34890 69 6f 6e 5d 20 61 73 73 6f 63 69 61 74 65 64 0a  ion] associated.
348a0 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 64 61 74  ** with the [dat
348b0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
348c0 5d 20 73 70 65 63 69 66 69 65 64 20 61 73 20 74  ] specified as t
348d0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
348e0 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61  t..**.** ^The na
348f0 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61 74  me of the collat
34900 69 6f 6e 20 69 73 20 61 20 55 54 46 2d 38 20 73  ion is a UTF-8 s
34910 74 72 69 6e 67 0a 2a 2a 20 66 6f 72 20 73 71 6c  tring.** for sql
34920 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
34930 61 74 69 6f 6e 28 29 20 61 6e 64 20 73 71 6c 69  ation() and sqli
34940 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
34950 74 69 6f 6e 5f 76 32 28 29 0a 2a 2a 20 61 6e 64  tion_v2().** and
34960 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67   a UTF-16 string
34970 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20   in native byte 
34980 6f 72 64 65 72 20 66 6f 72 20 73 71 6c 69 74 65  order for sqlite
34990 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
349a0 6f 6e 31 36 28 29 2e 0a 2a 2a 20 5e 43 6f 6c 6c  on16()..** ^Coll
349b0 61 74 69 6f 6e 20 6e 61 6d 65 73 20 74 68 61 74  ation names that
349c0 20 63 6f 6d 70 61 72 65 20 65 71 75 61 6c 20 61   compare equal a
349d0 63 63 6f 72 64 69 6e 67 20 74 6f 20 5b 73 71 6c  ccording to [sql
349e0 69 74 65 33 5f 73 74 72 6e 69 63 6d 70 28 29 5d  ite3_strnicmp()]
349f0 20 61 72 65 0a 2a 2a 20 63 6f 6e 73 69 64 65 72   are.** consider
34a00 65 64 20 74 6f 20 62 65 20 74 68 65 20 73 61 6d  ed to be the sam
34a10 65 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28  e name..**.** ^(
34a20 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  The third argume
34a30 6e 74 20 28 65 54 65 78 74 52 65 70 29 20 6d 75  nt (eTextRep) mu
34a40 73 74 20 62 65 20 6f 6e 65 20 6f 66 20 74 68 65  st be one of the
34a50 20 63 6f 6e 73 74 61 6e 74 73 3a 0a 2a 2a 20 3c   constants:.** <
34a60 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  ul>.** <li> [SQL
34a70 49 54 45 5f 55 54 46 38 5d 2c 0a 2a 2a 20 3c 6c  ITE_UTF8],.** <l
34a80 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  i> [SQLITE_UTF16
34a90 4c 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  LE],.** <li> [SQ
34aa0 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 0a 2a  LITE_UTF16BE],.*
34ab0 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55  * <li> [SQLITE_U
34ac0 54 46 31 36 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69  TF16], or.** <li
34ad0 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5f  > [SQLITE_UTF16_
34ae0 41 4c 49 47 4e 45 44 5d 2e 0a 2a 2a 20 3c 2f 75  ALIGNED]..** </u
34af0 6c 3e 29 5e 0a 2a 2a 20 5e 54 68 65 20 65 54 65  l>)^.** ^The eTe
34b00 78 74 52 65 70 20 61 72 67 75 6d 65 6e 74 20 64  xtRep argument d
34b10 65 74 65 72 6d 69 6e 65 73 20 74 68 65 20 65 6e  etermines the en
34b20 63 6f 64 69 6e 67 20 6f 66 20 73 74 72 69 6e 67  coding of string
34b30 73 20 70 61 73 73 65 64 0a 2a 2a 20 74 6f 20 74  s passed.** to t
34b40 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e  he collating fun
34b50 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 2c 20  ction callback, 
34b60 78 43 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 54  xCallback..** ^T
34b70 68 65 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  he [SQLITE_UTF16
34b80 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 55 54  ] and [SQLITE_UT
34b90 46 31 36 5f 41 4c 49 47 4e 45 44 5d 20 76 61 6c  F16_ALIGNED] val
34ba0 75 65 73 20 66 6f 72 20 65 54 65 78 74 52 65 70  ues for eTextRep
34bb0 0a 2a 2a 20 66 6f 72 63 65 20 73 74 72 69 6e 67  .** force string
34bc0 73 20 74 6f 20 62 65 20 55 54 46 31 36 20 77 69  s to be UTF16 wi
34bd0 74 68 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  th native byte o
34be0 72 64 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53  rder..** ^The [S
34bf0 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47  QLITE_UTF16_ALIG
34c00 4e 45 44 5d 20 76 61 6c 75 65 20 66 6f 72 20 65  NED] value for e
34c10 54 65 78 74 52 65 70 20 66 6f 72 63 65 73 20 73  TextRep forces s
34c20 74 72 69 6e 67 73 20 74 6f 20 62 65 67 69 6e 0a  trings to begin.
34c30 2a 2a 20 6f 6e 20 61 6e 20 65 76 65 6e 20 62 79  ** on an even by
34c40 74 65 20 61 64 64 72 65 73 73 2e 0a 2a 2a 0a 2a  te address..**.*
34c50 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20 61 72  * ^The fourth ar
34c60 67 75 6d 65 6e 74 2c 20 70 41 72 67 2c 20 69 73  gument, pArg, is
34c70 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20   an application 
34c80 64 61 74 61 20 70 6f 69 6e 74 65 72 20 74 68 61  data pointer tha
34c90 74 20 69 73 20 70 61 73 73 65 64 0a 2a 2a 20 74  t is passed.** t
34ca0 68 72 6f 75 67 68 20 61 73 20 74 68 65 20 66 69  hrough as the fi
34cb0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
34cc0 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75  the collating fu
34cd0 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 2e  nction callback.
34ce0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 66 74  .**.** ^The fift
34cf0 68 20 61 72 67 75 6d 65 6e 74 2c 20 78 43 61 6c  h argument, xCal
34d00 6c 62 61 63 6b 2c 20 69 73 20 61 20 70 6f 69 6e  lback, is a poin
34d10 74 65 72 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61  ter to the colla
34d20 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a  ting function..*
34d30 2a 20 5e 4d 75 6c 74 69 70 6c 65 20 63 6f 6c 6c  * ^Multiple coll
34d40 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20  ating functions 
34d50 63 61 6e 20 62 65 20 72 65 67 69 73 74 65 72 65  can be registere
34d60 64 20 75 73 69 6e 67 20 74 68 65 20 73 61 6d 65  d using the same
34d70 20 6e 61 6d 65 20 62 75 74 0a 2a 2a 20 77 69 74   name but.** wit
34d80 68 20 64 69 66 66 65 72 65 6e 74 20 65 54 65 78  h different eTex
34d90 74 52 65 70 20 70 61 72 61 6d 65 74 65 72 73 20  tRep parameters 
34da0 61 6e 64 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  and SQLite will 
34db0 75 73 65 20 77 68 69 63 68 65 76 65 72 0a 2a 2a  use whichever.**
34dc0 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72   function requir
34dd0 65 73 20 74 68 65 20 6c 65 61 73 74 20 61 6d 6f  es the least amo
34de0 75 6e 74 20 6f 66 20 64 61 74 61 20 74 72 61 6e  unt of data tran
34df0 73 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 20 5e  sformation..** ^
34e00 49 66 20 74 68 65 20 78 43 61 6c 6c 62 61 63 6b  If the xCallback
34e10 20 61 72 67 75 6d 65 6e 74 20 69 73 20 4e 55 4c   argument is NUL
34e20 4c 20 74 68 65 6e 20 74 68 65 20 63 6f 6c 6c 61  L then the colla
34e30 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73  ting function is
34e40 0a 2a 2a 20 64 65 6c 65 74 65 64 2e 20 20 5e 57  .** deleted.  ^W
34e50 68 65 6e 20 61 6c 6c 20 63 6f 6c 6c 61 74 69 6e  hen all collatin
34e60 67 20 66 75 6e 63 74 69 6f 6e 73 20 68 61 76 69  g functions havi
34e70 6e 67 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65  ng the same name
34e80 20 61 72 65 20 64 65 6c 65 74 65 64 2c 0a 2a 2a   are deleted,.**
34e90 20 74 68 61 74 20 63 6f 6c 6c 61 74 69 6f 6e 20   that collation 
34ea0 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 75 73 61  is no longer usa
34eb0 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ble..**.** ^The 
34ec0 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
34ed0 6f 6e 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  on callback is i
34ee0 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 20 63 6f  nvoked with a co
34ef0 70 79 20 6f 66 20 74 68 65 20 70 41 72 67 20 0a  py of the pArg .
34f00 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  ** application d
34f10 61 74 61 20 70 6f 69 6e 74 65 72 20 61 6e 64 20  ata pointer and 
34f20 77 69 74 68 20 74 77 6f 20 73 74 72 69 6e 67 73  with two strings
34f30 20 69 6e 20 74 68 65 20 65 6e 63 6f 64 69 6e 67   in the encoding
34f40 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79   specified.** by
34f50 20 74 68 65 20 65 54 65 78 74 52 65 70 20 61 72   the eTextRep ar
34f60 67 75 6d 65 6e 74 2e 20 20 54 68 65 20 63 6f 6c  gument.  The col
34f70 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  lating function 
34f80 6d 75 73 74 20 72 65 74 75 72 6e 20 61 6e 0a 2a  must return an.*
34f90 2a 20 69 6e 74 65 67 65 72 20 74 68 61 74 20 69  * integer that i
34fa0 73 20 6e 65 67 61 74 69 76 65 2c 20 7a 65 72 6f  s negative, zero
34fb0 2c 20 6f 72 20 70 6f 73 69 74 69 76 65 0a 2a 2a  , or positive.**
34fc0 20 69 66 20 74 68 65 20 66 69 72 73 74 20 73 74   if the first st
34fd0 72 69 6e 67 20 69 73 20 6c 65 73 73 20 74 68 61  ring is less tha
34fe0 6e 2c 20 65 71 75 61 6c 20 74 6f 2c 20 6f 72 20  n, equal to, or 
34ff0 67 72 65 61 74 65 72 20 74 68 61 6e 20 74 68 65  greater than the
35000 20 73 65 63 6f 6e 64 2c 0a 2a 2a 20 72 65 73 70   second,.** resp
35010 65 63 74 69 76 65 6c 79 2e 20 20 41 20 63 6f 6c  ectively.  A col
35020 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  lating function 
35030 6d 75 73 74 20 61 6c 77 61 79 73 20 72 65 74 75  must always retu
35040 72 6e 20 74 68 65 20 73 61 6d 65 20 61 6e 73 77  rn the same answ
35050 65 72 0a 2a 2a 20 67 69 76 65 6e 20 74 68 65 20  er.** given the 
35060 73 61 6d 65 20 69 6e 70 75 74 73 2e 20 20 49 66  same inputs.  If
35070 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 63 6f 6c   two or more col
35080 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73  lating functions
35090 20 61 72 65 20 72 65 67 69 73 74 65 72 65 64 0a   are registered.
350a0 2a 2a 20 74 6f 20 74 68 65 20 73 61 6d 65 20 63  ** to the same c
350b0 6f 6c 6c 61 74 69 6f 6e 20 6e 61 6d 65 20 28 75  ollation name (u
350c0 73 69 6e 67 20 64 69 66 66 65 72 65 6e 74 20 65  sing different e
350d0 54 65 78 74 52 65 70 20 76 61 6c 75 65 73 29 20  TextRep values) 
350e0 74 68 65 6e 20 61 6c 6c 0a 2a 2a 20 6d 75 73 74  then all.** must
350f0 20 67 69 76 65 20 61 6e 20 65 71 75 69 76 61 6c   give an equival
35100 65 6e 74 20 61 6e 73 77 65 72 20 77 68 65 6e 20  ent answer when 
35110 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 65 71 75  invoked with equ
35120 69 76 61 6c 65 6e 74 20 73 74 72 69 6e 67 73 2e  ivalent strings.
35130 0a 2a 2a 20 54 68 65 20 63 6f 6c 6c 61 74 69 6e  .** The collatin
35140 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20  g function must 
35150 6f 62 65 79 20 74 68 65 20 66 6f 6c 6c 6f 77 69  obey the followi
35160 6e 67 20 70 72 6f 70 65 72 74 69 65 73 20 66 6f  ng properties fo
35170 72 20 61 6c 6c 0a 2a 2a 20 73 74 72 69 6e 67 73  r all.** strings
35180 20 41 2c 20 42 2c 20 61 6e 64 20 43 3a 0a 2a 2a   A, B, and C:.**
35190 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ol>.** <li>
351a0 20 49 66 20 41 3d 3d 42 20 74 68 65 6e 20 42 3d   If A==B then B=
351b0 3d 41 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41  =A..** <li> If A
351c0 3d 3d 42 20 61 6e 64 20 42 3d 3d 43 20 74 68 65  ==B and B==C the
351d0 6e 20 41 3d 3d 43 2e 0a 2a 2a 20 3c 6c 69 3e 20  n A==C..** <li> 
351e0 49 66 20 41 26 6c 74 3b 42 20 54 48 45 4e 20 42  If A&lt;B THEN B
351f0 26 67 74 3b 41 2e 0a 2a 2a 20 3c 6c 69 3e 20 49  &gt;A..** <li> I
35200 66 20 41 26 6c 74 3b 42 20 61 6e 64 20 42 26 6c  f A&lt;B and B&l
35210 74 3b 43 20 74 68 65 6e 20 41 26 6c 74 3b 43 2e  t;C then A&lt;C.
35220 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ol>.**.** 
35230 49 66 20 61 20 63 6f 6c 6c 61 74 69 6e 67 20 66  If a collating f
35240 75 6e 63 74 69 6f 6e 20 66 61 69 6c 73 20 61 6e  unction fails an
35250 79 20 6f 66 20 74 68 65 20 61 62 6f 76 65 20 63  y of the above c
35260 6f 6e 73 74 72 61 69 6e 74 73 20 61 6e 64 20 74  onstraints and t
35270 68 61 74 0a 2a 2a 20 63 6f 6c 6c 61 74 69 6e 67  hat.** collating
35280 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 20 72 65   function is  re
35290 67 69 73 74 65 72 65 64 20 61 6e 64 20 75 73 65  gistered and use
352a0 64 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  d, then the beha
352b0 76 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 0a 2a  vior of SQLite.*
352c0 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  * is undefined..
352d0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
352e0 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
352f0 69 6f 6e 5f 76 32 28 29 20 77 6f 72 6b 73 20 6c  ion_v2() works l
35300 69 6b 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61  ike sqlite3_crea
35310 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 0a 2a  te_collation().*
35320 2a 20 77 69 74 68 20 74 68 65 20 61 64 64 69 74  * with the addit
35330 69 6f 6e 20 74 68 61 74 20 74 68 65 20 78 44 65  ion that the xDe
35340 73 74 72 6f 79 20 63 61 6c 6c 62 61 63 6b 20 69  stroy callback i
35350 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 20 70 41 72  s invoked on pAr
35360 67 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20 63 6f  g when.** the co
35370 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
35380 20 69 73 20 64 65 6c 65 74 65 64 2e 0a 2a 2a 20   is deleted..** 
35390 5e 43 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74  ^Collating funct
353a0 69 6f 6e 73 20 61 72 65 20 64 65 6c 65 74 65 64  ions are deleted
353b0 20 77 68 65 6e 20 74 68 65 79 20 61 72 65 20 6f   when they are o
353c0 76 65 72 72 69 64 64 65 6e 20 62 79 20 6c 61 74  verridden by lat
353d0 65 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 74  er.** calls to t
353e0 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 63 72 65  he collation cre
353f0 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 73 20  ation functions 
35400 6f 72 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20 5b  or when the.** [
35410 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
35420 69 6f 6e 5d 20 69 73 20 63 6c 6f 73 65 64 20 75  ion] is closed u
35430 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6c  sing [sqlite3_cl
35440 6f 73 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ose()]..**.** ^T
35450 68 65 20 78 44 65 73 74 72 6f 79 20 63 61 6c 6c  he xDestroy call
35460 62 61 63 6b 20 69 73 20 3c 75 3e 6e 6f 74 3c 2f  back is <u>not</
35470 75 3e 20 63 61 6c 6c 65 64 20 69 66 20 74 68 65  u> called if the
35480 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72 65   .** sqlite3_cre
35490 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32  ate_collation_v2
354a0 28 29 20 66 75 6e 63 74 69 6f 6e 20 66 61 69 6c  () function fail
354b0 73 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  s.  Applications
354c0 20 74 68 61 74 20 69 6e 76 6f 6b 65 0a 2a 2a 20   that invoke.** 
354d0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
354e0 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 77 69  ollation_v2() wi
354f0 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 78 44  th a non-NULL xD
35500 65 73 74 72 6f 79 20 61 72 67 75 6d 65 6e 74 20  estroy argument 
35510 73 68 6f 75 6c 64 20 0a 2a 2a 20 63 68 65 63 6b  should .** check
35520 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65   the return code
35530 20 61 6e 64 20 64 69 73 70 6f 73 65 20 6f 66 20   and dispose of 
35540 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
35550 64 61 74 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  data pointer.** 
35560 74 68 65 6d 73 65 6c 76 65 73 20 72 61 74 68 65  themselves rathe
35570 72 20 74 68 61 6e 20 65 78 70 65 63 74 69 6e 67  r than expecting
35580 20 53 51 4c 69 74 65 20 74 6f 20 64 65 61 6c 20   SQLite to deal 
35590 77 69 74 68 20 69 74 20 66 6f 72 20 74 68 65 6d  with it for them
355a0 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 64 69 66  ..** This is dif
355b0 66 65 72 65 6e 74 20 66 72 6f 6d 20 65 76 65 72  ferent from ever
355c0 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69  y other SQLite i
355d0 6e 74 65 72 66 61 63 65 2e 20 20 54 68 65 20 69  nterface.  The i
355e0 6e 63 6f 6e 73 69 73 74 65 6e 63 79 20 0a 2a 2a  nconsistency .**
355f0 20 69 73 20 75 6e 66 6f 72 74 75 6e 61 74 65 20   is unfortunate 
35600 62 75 74 20 63 61 6e 6e 6f 74 20 62 65 20 63 68  but cannot be ch
35610 61 6e 67 65 64 20 77 69 74 68 6f 75 74 20 62 72  anged without br
35620 65 61 6b 69 6e 67 20 62 61 63 6b 77 61 72 64 73  eaking backwards
35630 20 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69   .** compatibili
35640 74 79 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  ty..**.** See al
35650 73 6f 3a 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f  so:  [sqlite3_co
35660 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29  llation_needed()
35670 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  ] and [sqlite3_c
35680 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31  ollation_needed1
35690 36 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  6()]..*/.int sql
356a0 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
356b0 61 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33  ation(.  sqlite3
356c0 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  *, .  const char
356d0 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20   *zName, .  int 
356e0 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69  eTextRep, .  voi
356f0 64 20 2a 70 41 72 67 2c 0a 20 20 69 6e 74 28 2a  d *pArg,.  int(*
35700 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c  xCompare)(void*,
35710 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  int,const void*,
35720 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29  int,const void*)
35730 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
35740 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
35750 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c  _v2(.  sqlite3*,
35760 20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a   .  const char *
35770 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54  zName, .  int eT
35780 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 20  extRep, .  void 
35790 2a 70 41 72 67 2c 0a 20 20 69 6e 74 28 2a 78 43  *pArg,.  int(*xC
357a0 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e  ompare)(void*,in
357b0 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e  t,const void*,in
357c0 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 2c 0a  t,const void*),.
357d0 20 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79    void(*xDestroy
357e0 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74 20  )(void*).);.int 
357f0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
35800 6f 6c 6c 61 74 69 6f 6e 31 36 28 0a 20 20 73 71  ollation16(.  sq
35810 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74  lite3*, .  const
35820 20 76 6f 69 64 20 2a 7a 4e 61 6d 65 2c 0a 20 20   void *zName,.  
35830 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20  int eTextRep, . 
35840 20 76 6f 69 64 20 2a 70 41 72 67 2c 0a 20 20 69   void *pArg,.  i
35850 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f  nt(*xCompare)(vo
35860 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f  id*,int,const vo
35870 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f  id*,int,const vo
35880 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  id*).);../*.** C
35890 41 50 49 33 52 45 46 3a 20 43 6f 6c 6c 61 74 69  API3REF: Collati
358a0 6f 6e 20 4e 65 65 64 65 64 20 43 61 6c 6c 62 61  on Needed Callba
358b0 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 6f 20 61 76  cks.**.** ^To av
358c0 6f 69 64 20 68 61 76 69 6e 67 20 74 6f 20 72 65  oid having to re
358d0 67 69 73 74 65 72 20 61 6c 6c 20 63 6f 6c 6c 61  gister all colla
358e0 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 62  tion sequences b
358f0 65 66 6f 72 65 20 61 20 64 61 74 61 62 61 73 65  efore a database
35900 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 64 2c  .** can be used,
35910 20 61 20 73 69 6e 67 6c 65 20 63 61 6c 6c 62 61   a single callba
35920 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20  ck function may 
35930 62 65 20 72 65 67 69 73 74 65 72 65 64 20 77 69  be registered wi
35940 74 68 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62  th the.** [datab
35950 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
35960 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68  to be invoked wh
35970 65 6e 65 76 65 72 20 61 6e 20 75 6e 64 65 66 69  enever an undefi
35980 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a  ned collation.**
35990 20 73 65 71 75 65 6e 63 65 20 69 73 20 72 65 71   sequence is req
359a0 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  uired..**.** ^If
359b0 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73   the function is
359c0 20 72 65 67 69 73 74 65 72 65 64 20 75 73 69 6e   registered usin
359d0 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  g the sqlite3_co
359e0 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29  llation_needed()
359f0 20 41 50 49 2c 0a 2a 2a 20 74 68 65 6e 20 69 74   API,.** then it
35a00 20 69 73 20 70 61 73 73 65 64 20 74 68 65 20 6e   is passed the n
35a10 61 6d 65 73 20 6f 66 20 75 6e 64 65 66 69 6e 65  ames of undefine
35a20 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75  d collation sequ
35a30 65 6e 63 65 73 20 61 73 20 73 74 72 69 6e 67 73  ences as strings
35a40 0a 2a 2a 20 65 6e 63 6f 64 65 64 20 69 6e 20 55  .** encoded in U
35a50 54 46 2d 38 2e 20 5e 49 66 20 73 71 6c 69 74 65  TF-8. ^If sqlite
35a60 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
35a70 65 64 31 36 28 29 20 69 73 20 75 73 65 64 2c 0a  ed16() is used,.
35a80 2a 2a 20 74 68 65 20 6e 61 6d 65 73 20 61 72 65  ** the names are
35a90 20 70 61 73 73 65 64 20 61 73 20 55 54 46 2d 31   passed as UTF-1
35aa0 36 20 69 6e 20 6d 61 63 68 69 6e 65 20 6e 61 74  6 in machine nat
35ab0 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a  ive byte order..
35ac0 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 65 69  ** ^A call to ei
35ad0 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 20 72 65  ther function re
35ae0 70 6c 61 63 65 73 20 74 68 65 20 65 78 69 73 74  places the exist
35af0 69 6e 67 20 63 6f 6c 6c 61 74 69 6f 6e 2d 6e 65  ing collation-ne
35b00 65 64 65 64 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a  eded callback..*
35b10 2a 0a 2a 2a 20 5e 28 57 68 65 6e 20 74 68 65 20  *.** ^(When the 
35b20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
35b30 6b 65 64 2c 20 74 68 65 20 66 69 72 73 74 20 61  ked, the first a
35b40 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20 69  rgument passed i
35b50 73 20 61 20 63 6f 70 79 0a 2a 2a 20 6f 66 20 74  s a copy.** of t
35b60 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
35b70 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  nt to sqlite3_co
35b80 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29  llation_needed()
35b90 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   or.** sqlite3_c
35ba0 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31  ollation_needed1
35bb0 36 28 29 2e 20 20 54 68 65 20 73 65 63 6f 6e 64  6().  The second
35bc0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
35bd0 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e   database.** con
35be0 6e 65 63 74 69 6f 6e 2e 20 20 54 68 65 20 74 68  nection.  The th
35bf0 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ird argument is 
35c00 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 55  one of [SQLITE_U
35c10 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54  TF8], [SQLITE_UT
35c20 46 31 36 42 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 53  F16BE],.** or [S
35c30 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c 20  QLITE_UTF16LE], 
35c40 69 6e 64 69 63 61 74 69 6e 67 20 74 68 65 20 6d  indicating the m
35c50 6f 73 74 20 64 65 73 69 72 61 62 6c 65 20 66 6f  ost desirable fo
35c60 72 6d 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61 74  rm of the collat
35c70 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20  ion.** sequence 
35c80 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65  function require
35c90 64 2e 20 20 54 68 65 20 66 6f 75 72 74 68 20 70  d.  The fourth p
35ca0 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20  arameter is the 
35cb0 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 72  name of the.** r
35cc0 65 71 75 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f  equired collatio
35cd0 6e 20 73 65 71 75 65 6e 63 65 2e 29 5e 0a 2a 2a  n sequence.)^.**
35ce0 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b  .** The callback
35cf0 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64   function should
35d00 20 72 65 67 69 73 74 65 72 20 74 68 65 20 64 65   register the de
35d10 73 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20  sired collation 
35d20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  using.** [sqlite
35d30 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
35d40 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  on()], [sqlite3_
35d50 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
35d60 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71  16()], or.** [sq
35d70 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
35d80 6c 61 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2f  lation_v2()]..*/
35d90 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c  .int sqlite3_col
35da0 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 0a 20  lation_needed(. 
35db0 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f   sqlite3*, .  vo
35dc0 69 64 2a 2c 20 0a 20 20 76 6f 69 64 28 2a 29 28  id*, .  void(*)(
35dd0 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69  void*,sqlite3*,i
35de0 6e 74 20 65 54 65 78 74 52 65 70 2c 63 6f 6e 73  nt eTextRep,cons
35df0 74 20 63 68 61 72 2a 29 0a 29 3b 0a 69 6e 74 20  t char*).);.int 
35e00 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
35e10 6e 5f 6e 65 65 64 65 64 31 36 28 0a 20 20 73 71  n_needed16(.  sq
35e20 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a  lite3*, .  void*
35e30 2c 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64  ,.  void(*)(void
35e40 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65  *,sqlite3*,int e
35e50 54 65 78 74 52 65 70 2c 63 6f 6e 73 74 20 76 6f  TextRep,const vo
35e60 69 64 2a 29 0a 29 3b 0a 0a 23 69 66 64 65 66 20  id*).);..#ifdef 
35e70 53 51 4c 49 54 45 5f 48 41 53 5f 43 4f 44 45 43  SQLITE_HAS_CODEC
35e80 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20 74  ./*.** Specify t
35e90 68 65 20 6b 65 79 20 66 6f 72 20 61 6e 20 65 6e  he key for an en
35ea0 63 72 79 70 74 65 64 20 64 61 74 61 62 61 73 65  crypted database
35eb0 2e 20 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  .  This routine 
35ec0 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 63 61 6c  should be.** cal
35ed0 6c 65 64 20 72 69 67 68 74 20 61 66 74 65 72 20  led right after 
35ee0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 2e 0a  sqlite3_open()..
35ef0 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 74  **.** The code t
35f00 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73  o implement this
35f10 20 41 50 49 20 69 73 20 6e 6f 74 20 61 76 61 69   API is not avai
35f20 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 70 75 62  lable in the pub
35f30 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f  lic release.** o
35f40 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74  f SQLite..*/.int
35f50 20 73 71 6c 69 74 65 33 5f 6b 65 79 28 0a 20 20   sqlite3_key(.  
35f60 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
35f70 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
35f80 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20 62 65  * Database to be
35f90 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f   rekeyed */.  co
35fa0 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20  nst void *pKey, 
35fb0 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20  int nKey     /* 
35fc0 54 68 65 20 6b 65 79 20 2a 2f 0a 29 3b 0a 69 6e  The key */.);.in
35fd0 74 20 73 71 6c 69 74 65 33 5f 6b 65 79 5f 76 32  t sqlite3_key_v2
35fe0 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
35ff0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
36000 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74     /* Database t
36010 6f 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a  o be rekeyed */.
36020 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44    const char *zD
36030 62 4e 61 6d 65 2c 20 20 20 20 20 20 20 20 20 20  bName,          
36040 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 65 20   /* Name of the 
36050 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f  database */.  co
36060 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20  nst void *pKey, 
36070 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20  int nKey     /* 
36080 54 68 65 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f  The key */.);../
36090 2a 0a 2a 2a 20 43 68 61 6e 67 65 20 74 68 65 20  *.** Change the 
360a0 6b 65 79 20 6f 6e 20 61 6e 20 6f 70 65 6e 20 64  key on an open d
360b0 61 74 61 62 61 73 65 2e 20 20 49 66 20 74 68 65  atabase.  If the
360c0 20 63 75 72 72 65 6e 74 20 64 61 74 61 62 61 73   current databas
360d0 65 20 69 73 20 6e 6f 74 0a 2a 2a 20 65 6e 63 72  e is not.** encr
360e0 79 70 74 65 64 2c 20 74 68 69 73 20 72 6f 75 74  ypted, this rout
360f0 69 6e 65 20 77 69 6c 6c 20 65 6e 63 72 79 70 74  ine will encrypt
36100 20 69 74 2e 20 20 49 66 20 70 4e 65 77 3d 3d 30   it.  If pNew==0
36110 20 6f 72 20 6e 4e 65 77 3d 3d 30 2c 20 74 68 65   or nNew==0, the
36120 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 69 73 20  .** database is 
36130 64 65 63 72 79 70 74 65 64 2e 0a 2a 2a 0a 2a 2a  decrypted..**.**
36140 20 54 68 65 20 63 6f 64 65 20 74 6f 20 69 6d 70   The code to imp
36150 6c 65 6d 65 6e 74 20 74 68 69 73 20 41 50 49 20  lement this API 
36160 69 73 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65  is not available
36170 20 69 6e 20 74 68 65 20 70 75 62 6c 69 63 20 72   in the public r
36180 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c  elease.** of SQL
36190 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ite..*/.int sqli
361a0 74 65 33 5f 72 65 6b 65 79 28 0a 20 20 73 71 6c  te3_rekey(.  sql
361b0 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
361c0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44              /* D
361d0 61 74 61 62 61 73 65 20 74 6f 20 62 65 20 72 65  atabase to be re
361e0 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74  keyed */.  const
361f0 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74   void *pKey, int
36200 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 68 65   nKey     /* The
36210 20 6e 65 77 20 6b 65 79 20 2a 2f 0a 29 3b 0a 69   new key */.);.i
36220 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 6b 65 79  nt sqlite3_rekey
36230 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  _v2(.  sqlite3 *
36240 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  db,             
36250 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
36260 65 20 74 6f 20 62 65 20 72 65 6b 65 79 65 64 20  e to be rekeyed 
36270 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
36280 2a 7a 44 62 4e 61 6d 65 2c 20 20 20 20 20 20 20  *zDbName,       
36290 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74      /* Name of t
362a0 68 65 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20  he database */. 
362b0 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65   const void *pKe
362c0 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20  y, int nKey     
362d0 2f 2a 20 54 68 65 20 6e 65 77 20 6b 65 79 20 2a  /* The new key *
362e0 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 53 70 65 63  /.);../*.** Spec
362f0 69 66 79 20 74 68 65 20 61 63 74 69 76 61 74 69  ify the activati
36300 6f 6e 20 6b 65 79 20 66 6f 72 20 61 20 53 45 45  on key for a SEE
36310 20 64 61 74 61 62 61 73 65 2e 20 20 55 6e 6c 65   database.  Unle
36320 73 73 20 0a 2a 2a 20 61 63 74 69 76 61 74 65 64  ss .** activated
36330 2c 20 6e 6f 6e 65 20 6f 66 20 74 68 65 20 53 45  , none of the SE
36340 45 20 72 6f 75 74 69 6e 65 73 20 77 69 6c 6c 20  E routines will 
36350 77 6f 72 6b 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71  work..*/.void sq
36360 6c 69 74 65 33 5f 61 63 74 69 76 61 74 65 5f 73  lite3_activate_s
36370 65 65 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  ee(.  const char
36380 20 2a 7a 50 61 73 73 50 68 72 61 73 65 20 20 20   *zPassPhrase   
36390 20 20 20 20 20 2f 2a 20 41 63 74 69 76 61 74 69       /* Activati
363a0 6f 6e 20 70 68 72 61 73 65 20 2a 2f 0a 29 3b 0a  on phrase */.);.
363b0 23 65 6e 64 69 66 0a 0a 23 69 66 64 65 66 20 53  #endif..#ifdef S
363c0 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 45 52  QLITE_ENABLE_CER
363d0 4f 44 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79  OD./*.** Specify
363e0 20 74 68 65 20 61 63 74 69 76 61 74 69 6f 6e 20   the activation 
363f0 6b 65 79 20 66 6f 72 20 61 20 43 45 52 4f 44 20  key for a CEROD 
36400 64 61 74 61 62 61 73 65 2e 20 20 55 6e 6c 65 73  database.  Unles
36410 73 20 0a 2a 2a 20 61 63 74 69 76 61 74 65 64 2c  s .** activated,
36420 20 6e 6f 6e 65 20 6f 66 20 74 68 65 20 43 45 52   none of the CER
36430 4f 44 20 72 6f 75 74 69 6e 65 73 20 77 69 6c 6c  OD routines will
36440 20 77 6f 72 6b 2e 0a 2a 2f 0a 76 6f 69 64 20 73   work..*/.void s
36450 71 6c 69 74 65 33 5f 61 63 74 69 76 61 74 65 5f  qlite3_activate_
36460 63 65 72 6f 64 28 0a 20 20 63 6f 6e 73 74 20 63  cerod(.  const c
36470 68 61 72 20 2a 7a 50 61 73 73 50 68 72 61 73 65  har *zPassPhrase
36480 20 20 20 20 20 20 20 20 2f 2a 20 41 63 74 69 76          /* Activ
36490 61 74 69 6f 6e 20 70 68 72 61 73 65 20 2a 2f 0a  ation phrase */.
364a0 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a  );.#endif../*.**
364b0 20 43 41 50 49 33 52 45 46 3a 20 53 75 73 70 65   CAPI3REF: Suspe
364c0 6e 64 20 45 78 65 63 75 74 69 6f 6e 20 46 6f 72  nd Execution For
364d0 20 41 20 53 68 6f 72 74 20 54 69 6d 65 0a 2a 2a   A Short Time.**
364e0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
364f0 73 6c 65 65 70 28 29 20 66 75 6e 63 74 69 6f 6e  sleep() function
36500 20 63 61 75 73 65 73 20 74 68 65 20 63 75 72 72   causes the curr
36510 65 6e 74 20 74 68 72 65 61 64 20 74 6f 20 73 75  ent thread to su
36520 73 70 65 6e 64 20 65 78 65 63 75 74 69 6f 6e 0a  spend execution.
36530 2a 2a 20 66 6f 72 20 61 74 20 6c 65 61 73 74 20  ** for at least 
36540 61 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c  a number of mill
36550 69 73 65 63 6f 6e 64 73 20 73 70 65 63 69 66 69  iseconds specifi
36560 65 64 20 69 6e 20 69 74 73 20 70 61 72 61 6d 65  ed in its parame
36570 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  ter..**.** If th
36580 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  e operating syst
36590 65 6d 20 64 6f 65 73 20 6e 6f 74 20 73 75 70 70  em does not supp
365a0 6f 72 74 20 73 6c 65 65 70 20 72 65 71 75 65 73  ort sleep reques
365b0 74 73 20 77 69 74 68 0a 2a 2a 20 6d 69 6c 6c 69  ts with.** milli
365c0 73 65 63 6f 6e 64 20 74 69 6d 65 20 72 65 73 6f  second time reso
365d0 6c 75 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65  lution, then the
365e0 20 74 69 6d 65 20 77 69 6c 6c 20 62 65 20 72 6f   time will be ro
365f0 75 6e 64 65 64 20 75 70 20 74 6f 0a 2a 2a 20 74  unded up to.** t
36600 68 65 20 6e 65 61 72 65 73 74 20 73 65 63 6f 6e  he nearest secon
36610 64 2e 20 54 68 65 20 6e 75 6d 62 65 72 20 6f 66  d. The number of
36620 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66   milliseconds of
36630 20 73 6c 65 65 70 20 61 63 74 75 61 6c 6c 79 0a   sleep actually.
36640 2a 2a 20 72 65 71 75 65 73 74 65 64 20 66 72 6f  ** requested fro
36650 6d 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20  m the operating 
36660 73 79 73 74 65 6d 20 69 73 20 72 65 74 75 72 6e  system is return
36670 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74  ed..**.** ^SQLit
36680 65 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 69  e implements thi
36690 73 20 69 6e 74 65 72 66 61 63 65 20 62 79 20 63  s interface by c
366a0 61 6c 6c 69 6e 67 20 74 68 65 20 78 53 6c 65 65  alling the xSlee
366b0 70 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f 66  p().** method of
366c0 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71   the default [sq
366d0 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
366e0 74 2e 20 20 49 66 20 74 68 65 20 78 53 6c 65 65  t.  If the xSlee
366f0 70 28 29 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66  p() method.** of
36700 20 74 68 65 20 64 65 66 61 75 6c 74 20 56 46 53   the default VFS
36710 20 69 73 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e   is not implemen
36720 74 65 64 20 63 6f 72 72 65 63 74 6c 79 2c 20 6f  ted correctly, o
36730 72 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74 65  r not implemente
36740 64 20 61 74 0a 2a 2a 20 61 6c 6c 2c 20 74 68 65  d at.** all, the
36750 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f  n the behavior o
36760 66 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28  f sqlite3_sleep(
36770 29 20 6d 61 79 20 64 65 76 69 61 74 65 20 66 72  ) may deviate fr
36780 6f 6d 20 74 68 65 20 64 65 73 63 72 69 70 74 69  om the descripti
36790 6f 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 70 72 65  on.** in the pre
367a0 76 69 6f 75 73 20 70 61 72 61 67 72 61 70 68 73  vious paragraphs
367b0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
367c0 5f 73 6c 65 65 70 28 69 6e 74 29 3b 0a 0a 2f 2a  _sleep(int);../*
367d0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 61  .** CAPI3REF: Na
367e0 6d 65 20 4f 66 20 54 68 65 20 46 6f 6c 64 65 72  me Of The Folder
367f0 20 48 6f 6c 64 69 6e 67 20 54 65 6d 70 6f 72 61   Holding Tempora
36800 72 79 20 46 69 6c 65 73 0a 2a 2a 0a 2a 2a 20 5e  ry Files.**.** ^
36810 28 49 66 20 74 68 69 73 20 67 6c 6f 62 61 6c 20  (If this global 
36820 76 61 72 69 61 62 6c 65 20 69 73 20 6d 61 64 65  variable is made
36830 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 61 20 73   to point to a s
36840 74 72 69 6e 67 20 77 68 69 63 68 20 69 73 0a 2a  tring which is.*
36850 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 61 20  * the name of a 
36860 66 6f 6c 64 65 72 20 28 61 2e 6b 2e 61 2e 20 64  folder (a.k.a. d
36870 69 72 65 63 74 6f 72 79 29 2c 20 74 68 65 6e 20  irectory), then 
36880 61 6c 6c 20 74 65 6d 70 6f 72 61 72 79 20 66 69  all temporary fi
36890 6c 65 73 0a 2a 2a 20 63 72 65 61 74 65 64 20 62  les.** created b
368a0 79 20 53 51 4c 69 74 65 20 77 68 65 6e 20 75 73  y SQLite when us
368b0 69 6e 67 20 61 20 62 75 69 6c 74 2d 69 6e 20 5b  ing a built-in [
368c0 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 56 46  sqlite3_vfs | VF
368d0 53 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 70 6c  S].** will be pl
368e0 61 63 65 64 20 69 6e 20 74 68 61 74 20 64 69 72  aced in that dir
368f0 65 63 74 6f 72 79 2e 29 5e 20 20 5e 49 66 20 74  ectory.)^  ^If t
36900 68 69 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20  his variable.** 
36910 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
36920 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 70  r, then SQLite p
36930 65 72 66 6f 72 6d 73 20 61 20 73 65 61 72 63 68  erforms a search
36940 20 66 6f 72 20 61 6e 20 61 70 70 72 6f 70 72 69   for an appropri
36950 61 74 65 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79  ate.** temporary
36960 20 66 69 6c 65 20 64 69 72 65 63 74 6f 72 79 2e   file directory.
36970 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74  .**.** It is not
36980 20 73 61 66 65 20 74 6f 20 72 65 61 64 20 6f 72   safe to read or
36990 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61 72   modify this var
369a0 69 61 62 6c 65 20 69 6e 20 6d 6f 72 65 20 74 68  iable in more th
369b0 61 6e 20 6f 6e 65 0a 2a 2a 20 74 68 72 65 61 64  an one.** thread
369c0 20 61 74 20 61 20 74 69 6d 65 2e 20 20 49 74 20   at a time.  It 
369d0 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 72  is not safe to r
369e0 65 61 64 20 6f 72 20 6d 6f 64 69 66 79 20 74 68  ead or modify th
369f0 69 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 69  is variable.** i
36a00 66 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f  f a [database co
36a10 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 65 69  nnection] is bei
36a20 6e 67 20 75 73 65 64 20 61 74 20 74 68 65 20 73  ng used at the s
36a30 61 6d 65 20 74 69 6d 65 20 69 6e 20 61 20 73 65  ame time in a se
36a40 70 61 72 61 74 65 0a 2a 2a 20 74 68 72 65 61 64  parate.** thread
36a50 2e 0a 2a 2a 20 49 74 20 69 73 20 69 6e 74 65 6e  ..** It is inten
36a60 64 65 64 20 74 68 61 74 20 74 68 69 73 20 76 61  ded that this va
36a70 72 69 61 62 6c 65 20 62 65 20 73 65 74 20 6f 6e  riable be set on
36a80 63 65 0a 2a 2a 20 61 73 20 70 61 72 74 20 6f 66  ce.** as part of
36a90 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61 6c   process initial
36aa0 69 7a 61 74 69 6f 6e 20 61 6e 64 20 62 65 66 6f  ization and befo
36ab0 72 65 20 61 6e 79 20 53 51 4c 69 74 65 20 69 6e  re any SQLite in
36ac0 74 65 72 66 61 63 65 0a 2a 2a 20 72 6f 75 74 69  terface.** routi
36ad0 6e 65 73 20 68 61 76 65 20 62 65 65 6e 20 63 61  nes have been ca
36ae0 6c 6c 65 64 20 61 6e 64 20 74 68 61 74 20 74 68  lled and that th
36af0 69 73 20 76 61 72 69 61 62 6c 65 20 72 65 6d 61  is variable rema
36b00 69 6e 20 75 6e 63 68 61 6e 67 65 64 0a 2a 2a 20  in unchanged.** 
36b10 74 68 65 72 65 61 66 74 65 72 2e 0a 2a 2a 0a 2a  thereafter..**.*
36b20 2a 20 5e 54 68 65 20 5b 74 65 6d 70 5f 73 74 6f  * ^The [temp_sto
36b30 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61  re_directory pra
36b40 67 6d 61 5d 20 6d 61 79 20 6d 6f 64 69 66 79 20  gma] may modify 
36b50 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 61 6e  this variable an
36b60 64 20 63 61 75 73 65 0a 2a 2a 20 69 74 20 74 6f  d cause.** it to
36b70 20 70 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72 79   point to memory
36b80 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b   obtained from [
36b90 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 2e  sqlite3_malloc].
36ba0 20 20 5e 46 75 72 74 68 65 72 6d 6f 72 65 2c 0a    ^Furthermore,.
36bb0 2a 2a 20 74 68 65 20 5b 74 65 6d 70 5f 73 74 6f  ** the [temp_sto
36bc0 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61  re_directory pra
36bd0 67 6d 61 5d 20 61 6c 77 61 79 73 20 61 73 73 75  gma] always assu
36be0 6d 65 73 20 74 68 61 74 20 61 6e 79 20 73 74 72  mes that any str
36bf0 69 6e 67 0a 2a 2a 20 74 68 61 74 20 74 68 69 73  ing.** that this
36c00 20 76 61 72 69 61 62 6c 65 20 70 6f 69 6e 74 73   variable points
36c10 20 74 6f 20 69 73 20 68 65 6c 64 20 69 6e 20 6d   to is held in m
36c20 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66  emory obtained f
36c30 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  rom .** [sqlite3
36c40 5f 6d 61 6c 6c 6f 63 5d 20 61 6e 64 20 74 68 65  _malloc] and the
36c50 20 70 72 61 67 6d 61 20 6d 61 79 20 61 74 74 65   pragma may atte
36c60 6d 70 74 20 74 6f 20 66 72 65 65 20 74 68 61 74  mpt to free that
36c70 20 6d 65 6d 6f 72 79 0a 2a 2a 20 75 73 69 6e 67   memory.** using
36c80 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5d 2e   [sqlite3_free].
36c90 0a 2a 2a 20 48 65 6e 63 65 2c 20 69 66 20 74 68  .** Hence, if th
36ca0 69 73 20 76 61 72 69 61 62 6c 65 20 69 73 20 6d  is variable is m
36cb0 6f 64 69 66 69 65 64 20 64 69 72 65 63 74 6c 79  odified directly
36cc0 2c 20 65 69 74 68 65 72 20 69 74 20 73 68 6f 75  , either it shou
36cd0 6c 64 20 62 65 0a 2a 2a 20 6d 61 64 65 20 4e 55  ld be.** made NU
36ce0 4c 4c 20 6f 72 20 6d 61 64 65 20 74 6f 20 70 6f  LL or made to po
36cf0 69 6e 74 20 74 6f 20 6d 65 6d 6f 72 79 20 6f 62  int to memory ob
36d00 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  tained from [sql
36d10 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 0a 2a 2a 20  ite3_malloc].** 
36d20 6f 72 20 65 6c 73 65 20 74 68 65 20 75 73 65 20  or else the use 
36d30 6f 66 20 74 68 65 20 5b 74 65 6d 70 5f 73 74 6f  of the [temp_sto
36d40 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61  re_directory pra
36d50 67 6d 61 5d 20 73 68 6f 75 6c 64 20 62 65 20 61  gma] should be a
36d60 76 6f 69 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62  voided..**.** <b
36d70 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73  >Note to Windows
36d80 20 52 75 6e 74 69 6d 65 20 75 73 65 72 73 3a 3c   Runtime users:<
36d90 2f 62 3e 20 20 54 68 65 20 74 65 6d 70 6f 72 61  /b>  The tempora
36da0 72 79 20 64 69 72 65 63 74 6f 72 79 20 6d 75 73  ry directory mus
36db0 74 20 62 65 20 73 65 74 0a 2a 2a 20 70 72 69 6f  t be set.** prio
36dc0 72 20 74 6f 20 63 61 6c 6c 69 6e 67 20 5b 73 71  r to calling [sq
36dd0 6c 69 74 65 33 5f 6f 70 65 6e 5d 20 6f 72 20 5b  lite3_open] or [
36de0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 5d  sqlite3_open_v2]
36df0 2e 20 20 4f 74 68 65 72 77 69 73 65 2c 20 76 61  .  Otherwise, va
36e00 72 69 6f 75 73 0a 2a 2a 20 66 65 61 74 75 72 65  rious.** feature
36e10 73 20 74 68 61 74 20 72 65 71 75 69 72 65 20 74  s that require t
36e20 68 65 20 75 73 65 20 6f 66 20 74 65 6d 70 6f 72  he use of tempor
36e30 61 72 79 20 66 69 6c 65 73 20 6d 61 79 20 66 61  ary files may fa
36e40 69 6c 2e 20 20 48 65 72 65 20 69 73 20 61 6e 0a  il.  Here is an.
36e50 2a 2a 20 65 78 61 6d 70 6c 65 20 6f 66 20 68 6f  ** example of ho
36e60 77 20 74 6f 20 64 6f 20 74 68 69 73 20 75 73 69  w to do this usi
36e70 6e 67 20 43 2b 2b 20 77 69 74 68 20 74 68 65 20  ng C++ with the 
36e80 57 69 6e 64 6f 77 73 20 52 75 6e 74 69 6d 65 3a  Windows Runtime:
36e90 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
36ea0 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 4c 50 43 57  te><pre>.** LPCW
36eb0 53 54 52 20 7a 50 61 74 68 20 3d 20 57 69 6e 64  STR zPath = Wind
36ec0 6f 77 73 3a 3a 53 74 6f 72 61 67 65 3a 3a 41 70  ows::Storage::Ap
36ed0 70 6c 69 63 61 74 69 6f 6e 44 61 74 61 3a 3a 43  plicationData::C
36ee0 75 72 72 65 6e 74 2d 3e 0a 2a 2a 20 26 6e 62 73  urrent->.** &nbs
36ef0 70 3b 20 20 20 20 20 54 65 6d 70 6f 72 61 72 79  p;     Temporary
36f00 46 6f 6c 64 65 72 2d 3e 50 61 74 68 2d 3e 44 61  Folder->Path->Da
36f10 74 61 28 29 3b 0a 2a 2a 20 63 68 61 72 20 7a 50  ta();.** char zP
36f20 61 74 68 42 75 66 26 23 39 31 3b 4d 41 58 5f 50  athBuf&#91;MAX_P
36f30 41 54 48 20 2b 20 31 26 23 39 33 3b 3b 0a 2a 2a  ATH + 1&#93;;.**
36f40 20 6d 65 6d 73 65 74 28 7a 50 61 74 68 42 75 66   memset(zPathBuf
36f50 2c 20 30 2c 20 73 69 7a 65 6f 66 28 7a 50 61 74  , 0, sizeof(zPat
36f60 68 42 75 66 29 29 3b 0a 2a 2a 20 57 69 64 65 43  hBuf));.** WideC
36f70 68 61 72 54 6f 4d 75 6c 74 69 42 79 74 65 28 43  harToMultiByte(C
36f80 50 5f 55 54 46 38 2c 20 30 2c 20 7a 50 61 74 68  P_UTF8, 0, zPath
36f90 2c 20 2d 31 2c 20 7a 50 61 74 68 42 75 66 2c 20  , -1, zPathBuf, 
36fa0 73 69 7a 65 6f 66 28 7a 50 61 74 68 42 75 66 29  sizeof(zPathBuf)
36fb0 2c 0a 2a 2a 20 26 6e 62 73 70 3b 20 20 20 20 20  ,.** &nbsp;     
36fc0 4e 55 4c 4c 2c 20 4e 55 4c 4c 29 3b 0a 2a 2a 20  NULL, NULL);.** 
36fd0 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64 69 72  sqlite3_temp_dir
36fe0 65 63 74 6f 72 79 20 3d 20 73 71 6c 69 74 65 33  ectory = sqlite3
36ff0 5f 6d 70 72 69 6e 74 66 28 22 25 73 22 2c 20 7a  _mprintf("%s", z
37000 50 61 74 68 42 75 66 29 3b 0a 2a 2a 20 3c 2f 70  PathBuf);.** </p
37010 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
37020 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54 45 52  .*/.SQLITE_EXTER
37030 4e 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  N char *sqlite3_
37040 74 65 6d 70 5f 64 69 72 65 63 74 6f 72 79 3b 0a  temp_directory;.
37050 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
37060 20 4e 61 6d 65 20 4f 66 20 54 68 65 20 46 6f 6c   Name Of The Fol
37070 64 65 72 20 48 6f 6c 64 69 6e 67 20 44 61 74 61  der Holding Data
37080 62 61 73 65 20 46 69 6c 65 73 0a 2a 2a 0a 2a 2a  base Files.**.**
37090 20 5e 28 49 66 20 74 68 69 73 20 67 6c 6f 62 61   ^(If this globa
370a0 6c 20 76 61 72 69 61 62 6c 65 20 69 73 20 6d 61  l variable is ma
370b0 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 61  de to point to a
370c0 20 73 74 72 69 6e 67 20 77 68 69 63 68 20 69 73   string which is
370d0 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  .** the name of 
370e0 61 20 66 6f 6c 64 65 72 20 28 61 2e 6b 2e 61 2e  a folder (a.k.a.
370f0 20 64 69 72 65 63 74 6f 72 79 29 2c 20 74 68 65   directory), the
37100 6e 20 61 6c 6c 20 64 61 74 61 62 61 73 65 20 66  n all database f
37110 69 6c 65 73 0a 2a 2a 20 73 70 65 63 69 66 69 65  iles.** specifie
37120 64 20 77 69 74 68 20 61 20 72 65 6c 61 74 69 76  d with a relativ
37130 65 20 70 61 74 68 6e 61 6d 65 20 61 6e 64 20 63  e pathname and c
37140 72 65 61 74 65 64 20 6f 72 20 61 63 63 65 73 73  reated or access
37150 65 64 20 62 79 0a 2a 2a 20 53 51 4c 69 74 65 20  ed by.** SQLite 
37160 77 68 65 6e 20 75 73 69 6e 67 20 61 20 62 75 69  when using a bui
37170 6c 74 2d 69 6e 20 77 69 6e 64 6f 77 73 20 5b 73  lt-in windows [s
37180 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 56 46 53  qlite3_vfs | VFS
37190 5d 20 77 69 6c 6c 20 62 65 20 61 73 73 75 6d 65  ] will be assume
371a0 64 0a 2a 2a 20 74 6f 20 62 65 20 72 65 6c 61 74  d.** to be relat
371b0 69 76 65 20 74 6f 20 74 68 61 74 20 64 69 72 65  ive to that dire
371c0 63 74 6f 72 79 2e 29 5e 20 5e 49 66 20 74 68 69  ctory.)^ ^If thi
371d0 73 20 76 61 72 69 61 62 6c 65 20 69 73 20 61 20  s variable is a 
371e0 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 2c  NULL.** pointer,
371f0 20 74 68 65 6e 20 53 51 4c 69 74 65 20 61 73 73   then SQLite ass
37200 75 6d 65 73 20 74 68 61 74 20 61 6c 6c 20 64 61  umes that all da
37210 74 61 62 61 73 65 20 66 69 6c 65 73 20 73 70 65  tabase files spe
37220 63 69 66 69 65 64 0a 2a 2a 20 77 69 74 68 20 61  cified.** with a
37230 20 72 65 6c 61 74 69 76 65 20 70 61 74 68 6e 61   relative pathna
37240 6d 65 20 61 72 65 20 72 65 6c 61 74 69 76 65 20  me are relative 
37250 74 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20 64  to the current d
37260 69 72 65 63 74 6f 72 79 0a 2a 2a 20 66 6f 72 20  irectory.** for 
37270 74 68 65 20 70 72 6f 63 65 73 73 2e 20 20 4f 6e  the process.  On
37280 6c 79 20 74 68 65 20 77 69 6e 64 6f 77 73 20 56  ly the windows V
37290 46 53 20 6d 61 6b 65 73 20 75 73 65 20 6f 66 20  FS makes use of 
372a0 74 68 69 73 20 67 6c 6f 62 61 6c 0a 2a 2a 20 76  this global.** v
372b0 61 72 69 61 62 6c 65 3b 20 69 74 20 69 73 20 69  ariable; it is i
372c0 67 6e 6f 72 65 64 20 62 79 20 74 68 65 20 75 6e  gnored by the un
372d0 69 78 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 43 68  ix VFS..**.** Ch
372e0 61 6e 67 69 6e 67 20 74 68 65 20 76 61 6c 75 65  anging the value
372f0 20 6f 66 20 74 68 69 73 20 76 61 72 69 61 62 6c   of this variabl
37300 65 20 77 68 69 6c 65 20 61 20 64 61 74 61 62 61  e while a databa
37310 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
37320 0a 2a 2a 20 6f 70 65 6e 20 63 61 6e 20 72 65 73  .** open can res
37330 75 6c 74 20 69 6e 20 61 20 63 6f 72 72 75 70 74  ult in a corrupt
37340 20 64 61 74 61 62 61 73 65 2e 0a 2a 2a 0a 2a 2a   database..**.**
37350 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20   It is not safe 
37360 74 6f 20 72 65 61 64 20 6f 72 20 6d 6f 64 69 66  to read or modif
37370 79 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20  y this variable 
37380 69 6e 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65  in more than one
37390 0a 2a 2a 20 74 68 72 65 61 64 20 61 74 20 61 20  .** thread at a 
373a0 74 69 6d 65 2e 20 20 49 74 20 69 73 20 6e 6f 74  time.  It is not
373b0 20 73 61 66 65 20 74 6f 20 72 65 61 64 20 6f 72   safe to read or
373c0 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61 72   modify this var
373d0 69 61 62 6c 65 0a 2a 2a 20 69 66 20 61 20 5b 64  iable.** if a [d
373e0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
373f0 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20 75 73 65  on] is being use
37400 64 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69  d at the same ti
37410 6d 65 20 69 6e 20 61 20 73 65 70 61 72 61 74 65  me in a separate
37420 0a 2a 2a 20 74 68 72 65 61 64 2e 0a 2a 2a 20 49  .** thread..** I
37430 74 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74 68  t is intended th
37440 61 74 20 74 68 69 73 20 76 61 72 69 61 62 6c 65  at this variable
37450 20 62 65 20 73 65 74 20 6f 6e 63 65 0a 2a 2a 20   be set once.** 
37460 61 73 20 70 61 72 74 20 6f 66 20 70 72 6f 63 65  as part of proce
37470 73 73 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f  ss initializatio
37480 6e 20 61 6e 64 20 62 65 66 6f 72 65 20 61 6e 79  n and before any
37490 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
374a0 65 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 68 61  e.** routines ha
374b0 76 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 61  ve been called a
374c0 6e 64 20 74 68 61 74 20 74 68 69 73 20 76 61 72  nd that this var
374d0 69 61 62 6c 65 20 72 65 6d 61 69 6e 20 75 6e 63  iable remain unc
374e0 68 61 6e 67 65 64 0a 2a 2a 20 74 68 65 72 65 61  hanged.** therea
374f0 66 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  fter..**.** ^The
37500 20 5b 64 61 74 61 5f 73 74 6f 72 65 5f 64 69 72   [data_store_dir
37510 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 6d  ectory pragma] m
37520 61 79 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76  ay modify this v
37530 61 72 69 61 62 6c 65 20 61 6e 64 20 63 61 75 73  ariable and caus
37540 65 0a 2a 2a 20 69 74 20 74 6f 20 70 6f 69 6e 74  e.** it to point
37550 20 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69   to memory obtai
37560 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ned from [sqlite
37570 33 5f 6d 61 6c 6c 6f 63 5d 2e 20 20 5e 46 75 72  3_malloc].  ^Fur
37580 74 68 65 72 6d 6f 72 65 2c 0a 2a 2a 20 74 68 65  thermore,.** the
37590 20 5b 64 61 74 61 5f 73 74 6f 72 65 5f 64 69 72   [data_store_dir
375a0 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 61  ectory pragma] a
375b0 6c 77 61 79 73 20 61 73 73 75 6d 65 73 20 74 68  lways assumes th
375c0 61 74 20 61 6e 79 20 73 74 72 69 6e 67 0a 2a 2a  at any string.**
375d0 20 74 68 61 74 20 74 68 69 73 20 76 61 72 69 61   that this varia
375e0 62 6c 65 20 70 6f 69 6e 74 73 20 74 6f 20 69 73  ble points to is
375f0 20 68 65 6c 64 20 69 6e 20 6d 65 6d 6f 72 79 20   held in memory 
37600 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a  obtained from .*
37610 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  * [sqlite3_mallo
37620 63 5d 20 61 6e 64 20 74 68 65 20 70 72 61 67 6d  c] and the pragm
37630 61 20 6d 61 79 20 61 74 74 65 6d 70 74 20 74 6f  a may attempt to
37640 20 66 72 65 65 20 74 68 61 74 20 6d 65 6d 6f 72   free that memor
37650 79 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69  y.** using [sqli
37660 74 65 33 5f 66 72 65 65 5d 2e 0a 2a 2a 20 48 65  te3_free]..** He
37670 6e 63 65 2c 20 69 66 20 74 68 69 73 20 76 61 72  nce, if this var
37680 69 61 62 6c 65 20 69 73 20 6d 6f 64 69 66 69 65  iable is modifie
37690 64 20 64 69 72 65 63 74 6c 79 2c 20 65 69 74 68  d directly, eith
376a0 65 72 20 69 74 20 73 68 6f 75 6c 64 20 62 65 0a  er it should be.
376b0 2a 2a 20 6d 61 64 65 20 4e 55 4c 4c 20 6f 72 20  ** made NULL or 
376c0 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f  made to point to
376d0 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64   memory obtained
376e0 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
376f0 61 6c 6c 6f 63 5d 0a 2a 2a 20 6f 72 20 65 6c 73  alloc].** or els
37700 65 20 74 68 65 20 75 73 65 20 6f 66 20 74 68 65  e the use of the
37710 20 5b 64 61 74 61 5f 73 74 6f 72 65 5f 64 69 72   [data_store_dir
37720 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 73  ectory pragma] s
37730 68 6f 75 6c 64 20 62 65 20 61 76 6f 69 64 65 64  hould be avoided
37740 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54 45  ..*/.SQLITE_EXTE
37750 52 4e 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  RN char *sqlite3
37760 5f 64 61 74 61 5f 64 69 72 65 63 74 6f 72 79 3b  _data_directory;
37770 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
37780 3a 20 54 65 73 74 20 46 6f 72 20 41 75 74 6f 2d  : Test For Auto-
37790 43 6f 6d 6d 69 74 20 4d 6f 64 65 0a 2a 2a 20 4b  Commit Mode.** K
377a0 45 59 57 4f 52 44 53 3a 20 7b 61 75 74 6f 63 6f  EYWORDS: {autoco
377b0 6d 6d 69 74 20 6d 6f 64 65 7d 0a 2a 2a 0a 2a 2a  mmit mode}.**.**
377c0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65   ^The sqlite3_ge
377d0 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 29 20 69  t_autocommit() i
377e0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
377f0 20 6e 6f 6e 2d 7a 65 72 6f 20 6f 72 0a 2a 2a 20   non-zero or.** 
37800 7a 65 72 6f 20 69 66 20 74 68 65 20 67 69 76 65  zero if the give
37810 6e 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  n database conne
37820 63 74 69 6f 6e 20 69 73 20 6f 72 20 69 73 20 6e  ction is or is n
37830 6f 74 20 69 6e 20 61 75 74 6f 63 6f 6d 6d 69 74  ot in autocommit
37840 20 6d 6f 64 65 2c 0a 2a 2a 20 72 65 73 70 65 63   mode,.** respec
37850 74 69 76 65 6c 79 2e 20 20 5e 41 75 74 6f 63 6f  tively.  ^Autoco
37860 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 6f 6e 20  mmit mode is on 
37870 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 5e  by default..** ^
37880 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20  Autocommit mode 
37890 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 20 61  is disabled by a
378a0 20 5b 42 45 47 49 4e 5d 20 73 74 61 74 65 6d 65   [BEGIN] stateme
378b0 6e 74 2e 0a 2a 2a 20 5e 41 75 74 6f 63 6f 6d 6d  nt..** ^Autocomm
378c0 69 74 20 6d 6f 64 65 20 69 73 20 72 65 2d 65 6e  it mode is re-en
378d0 61 62 6c 65 64 20 62 79 20 61 20 5b 43 4f 4d 4d  abled by a [COMM
378e0 49 54 5d 20 6f 72 20 5b 52 4f 4c 4c 42 41 43 4b  IT] or [ROLLBACK
378f0 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 63 65 72 74  ]..**.** If cert
37900 61 69 6e 20 6b 69 6e 64 73 20 6f 66 20 65 72 72  ain kinds of err
37910 6f 72 73 20 6f 63 63 75 72 20 6f 6e 20 61 20 73  ors occur on a s
37920 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20  tatement within 
37930 61 20 6d 75 6c 74 69 2d 73 74 61 74 65 6d 65 6e  a multi-statemen
37940 74 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e  t.** transaction
37950 20 28 65 72 72 6f 72 73 20 69 6e 63 6c 75 64 69   (errors includi
37960 6e 67 20 5b 53 51 4c 49 54 45 5f 46 55 4c 4c 5d  ng [SQLITE_FULL]
37970 2c 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d  , [SQLITE_IOERR]
37980 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d  ,.** [SQLITE_NOM
37990 45 4d 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 55 53  EM], [SQLITE_BUS
379a0 59 5d 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f  Y], and [SQLITE_
379b0 49 4e 54 45 52 52 55 50 54 5d 29 20 74 68 65 6e  INTERRUPT]) then
379c0 20 74 68 65 0a 2a 2a 20 74 72 61 6e 73 61 63 74   the.** transact
379d0 69 6f 6e 20 6d 69 67 68 74 20 62 65 20 72 6f 6c  ion might be rol
379e0 6c 65 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 74  led back automat
379f0 69 63 61 6c 6c 79 2e 20 20 54 68 65 20 6f 6e 6c  ically.  The onl
37a00 79 20 77 61 79 20 74 6f 0a 2a 2a 20 66 69 6e 64  y way to.** find
37a10 20 6f 75 74 20 77 68 65 74 68 65 72 20 53 51 4c   out whether SQL
37a20 69 74 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ite automaticall
37a30 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 74 68  y rolled back th
37a40 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 61 66  e transaction af
37a50 74 65 72 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20  ter.** an error 
37a60 69 73 20 74 6f 20 75 73 65 20 74 68 69 73 20 66  is to use this f
37a70 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49  unction..**.** I
37a80 66 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64  f another thread
37a90 20 63 68 61 6e 67 65 73 20 74 68 65 20 61 75 74   changes the aut
37aa0 6f 63 6f 6d 6d 69 74 20 73 74 61 74 75 73 20 6f  ocommit status o
37ab0 66 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  f the database.*
37ac0 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69  * connection whi
37ad0 6c 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  le this routine 
37ae0 69 73 20 72 75 6e 6e 69 6e 67 2c 20 74 68 65 6e  is running, then
37af0 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
37b00 65 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e 65  e.** is undefine
37b10 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  d..*/.int sqlite
37b20 33 5f 67 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74  3_get_autocommit
37b30 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
37b40 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69 6e  ** CAPI3REF: Fin
37b50 64 20 54 68 65 20 44 61 74 61 62 61 73 65 20 48  d The Database H
37b60 61 6e 64 6c 65 20 4f 66 20 41 20 50 72 65 70 61  andle Of A Prepa
37b70 72 65 64 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a  red Statement.**
37b80 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
37b90 5f 64 62 5f 68 61 6e 64 6c 65 20 69 6e 74 65 72  _db_handle inter
37ba0 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
37bb0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
37bc0 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 0a 2a 2a  ction] handle.**
37bd0 20 74 6f 20 77 68 69 63 68 20 61 20 5b 70 72 65   to which a [pre
37be0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
37bf0 20 62 65 6c 6f 6e 67 73 2e 20 20 5e 54 68 65 20   belongs.  ^The 
37c00 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
37c10 74 69 6f 6e 5d 0a 2a 2a 20 72 65 74 75 72 6e 65  tion].** returne
37c20 64 20 62 79 20 73 71 6c 69 74 65 33 5f 64 62 5f  d by sqlite3_db_
37c30 68 61 6e 64 6c 65 20 69 73 20 74 68 65 20 73 61  handle is the sa
37c40 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  me [database con
37c50 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 74 68 61 74  nection].** that
37c60 20 77 61 73 20 74 68 65 20 66 69 72 73 74 20 61   was the first a
37c70 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 74 68  rgument.** to th
37c80 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  e [sqlite3_prepa
37c90 72 65 5f 76 32 28 29 5d 20 63 61 6c 6c 20 28 6f  re_v2()] call (o
37ca0 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 29 20  r its variants) 
37cb0 74 68 61 74 20 77 61 73 20 75 73 65 64 20 74 6f  that was used to
37cc0 0a 2a 2a 20 63 72 65 61 74 65 20 74 68 65 20 73  .** create the s
37cd0 74 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 65 20  tatement in the 
37ce0 66 69 72 73 74 20 70 6c 61 63 65 2e 0a 2a 2f 0a  first place..*/.
37cf0 73 71 6c 69 74 65 33 20 2a 73 71 6c 69 74 65 33  sqlite3 *sqlite3
37d00 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74  _db_handle(sqlit
37d10 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a  e3_stmt*);../*.*
37d20 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 74 75  * CAPI3REF: Retu
37d30 72 6e 20 54 68 65 20 46 69 6c 65 6e 61 6d 65 20  rn The Filename 
37d40 46 6f 72 20 41 20 44 61 74 61 62 61 73 65 20 43  For A Database C
37d50 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20  onnection.**.** 
37d60 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f  ^The sqlite3_db_
37d70 66 69 6c 65 6e 61 6d 65 28 44 2c 4e 29 20 69 6e  filename(D,N) in
37d80 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
37d90 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 66  a pointer to a f
37da0 69 6c 65 6e 61 6d 65 0a 2a 2a 20 61 73 73 6f 63  ilename.** assoc
37db0 69 61 74 65 64 20 77 69 74 68 20 64 61 74 61 62  iated with datab
37dc0 61 73 65 20 4e 20 6f 66 20 63 6f 6e 6e 65 63 74  ase N of connect
37dd0 69 6f 6e 20 44 2e 20 20 5e 54 68 65 20 6d 61 69  ion D.  ^The mai
37de0 6e 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 0a  n database file.
37df0 2a 2a 20 68 61 73 20 74 68 65 20 6e 61 6d 65 20  ** has the name 
37e00 22 6d 61 69 6e 22 2e 20 20 49 66 20 74 68 65 72  "main".  If ther
37e10 65 20 69 73 20 6e 6f 20 61 74 74 61 63 68 65 64  e is no attached
37e20 20 64 61 74 61 62 61 73 65 20 4e 20 6f 6e 20 74   database N on t
37e30 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63  he database.** c
37e40 6f 6e 6e 65 63 74 69 6f 6e 20 44 2c 20 6f 72 20  onnection D, or 
37e50 69 66 20 64 61 74 61 62 61 73 65 20 4e 20 69 73  if database N is
37e60 20 61 20 74 65 6d 70 6f 72 61 72 79 20 6f 72 20   a temporary or 
37e70 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61  in-memory databa
37e80 73 65 2c 20 74 68 65 6e 0a 2a 2a 20 61 20 4e 55  se, then.** a NU
37e90 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65  LL pointer is re
37ea0 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  turned..**.** ^T
37eb0 68 65 20 66 69 6c 65 6e 61 6d 65 20 72 65 74 75  he filename retu
37ec0 72 6e 65 64 20 62 79 20 74 68 69 73 20 66 75 6e  rned by this fun
37ed0 63 74 69 6f 6e 20 69 73 20 74 68 65 20 6f 75 74  ction is the out
37ee0 70 75 74 20 6f 66 20 74 68 65 0a 2a 2a 20 78 46  put of the.** xF
37ef0 75 6c 6c 50 61 74 68 6e 61 6d 65 20 6d 65 74 68  ullPathname meth
37f00 6f 64 20 6f 66 20 74 68 65 20 5b 56 46 53 5d 2e  od of the [VFS].
37f10 20 20 5e 49 6e 20 6f 74 68 65 72 20 77 6f 72 64    ^In other word
37f20 73 2c 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 0a  s, the filename.
37f30 2a 2a 20 77 69 6c 6c 20 62 65 20 61 6e 20 61 62  ** will be an ab
37f40 73 6f 6c 75 74 65 20 70 61 74 68 6e 61 6d 65 2c  solute pathname,
37f50 20 65 76 65 6e 20 69 66 20 74 68 65 20 66 69 6c   even if the fil
37f60 65 6e 61 6d 65 20 75 73 65 64 0a 2a 2a 20 74 6f  ename used.** to
37f70 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61   open the databa
37f80 73 65 20 6f 72 69 67 69 6e 61 6c 6c 79 20 77 61  se originally wa
37f90 73 20 61 20 55 52 49 20 6f 72 20 72 65 6c 61 74  s a URI or relat
37fa0 69 76 65 20 70 61 74 68 6e 61 6d 65 2e 0a 2a 2f  ive pathname..*/
37fb0 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
37fc0 69 74 65 33 5f 64 62 5f 66 69 6c 65 6e 61 6d 65  ite3_db_filename
37fd0 28 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 63 6f  (sqlite3 *db, co
37fe0 6e 73 74 20 63 68 61 72 20 2a 7a 44 62 4e 61 6d  nst char *zDbNam
37ff0 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  e);../*.** CAPI3
38000 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 69  REF: Determine i
38010 66 20 61 20 64 61 74 61 62 61 73 65 20 69 73 20  f a database is 
38020 72 65 61 64 2d 6f 6e 6c 79 0a 2a 2a 0a 2a 2a 20  read-only.**.** 
38030 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f  ^The sqlite3_db_
38040 72 65 61 64 6f 6e 6c 79 28 44 2c 4e 29 20 69 6e  readonly(D,N) in
38050 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
38060 31 20 69 66 20 74 68 65 20 64 61 74 61 62 61 73  1 if the databas
38070 65 20 4e 0a 2a 2a 20 6f 66 20 63 6f 6e 6e 65 63  e N.** of connec
38080 74 69 6f 6e 20 44 20 69 73 20 72 65 61 64 2d 6f  tion D is read-o
38090 6e 6c 79 2c 20 30 20 69 66 20 69 74 20 69 73 20  nly, 0 if it is 
380a0 72 65 61 64 2f 77 72 69 74 65 2c 20 6f 72 20 2d  read/write, or -
380b0 31 20 69 66 20 4e 20 69 73 20 6e 6f 74 0a 2a 2a  1 if N is not.**
380c0 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 64   the name of a d
380d0 61 74 61 62 61 73 65 20 6f 6e 20 63 6f 6e 6e 65  atabase on conne
380e0 63 74 69 6f 6e 20 44 2e 0a 2a 2f 0a 69 6e 74 20  ction D..*/.int 
380f0 73 71 6c 69 74 65 33 5f 64 62 5f 72 65 61 64 6f  sqlite3_db_reado
38100 6e 6c 79 28 73 71 6c 69 74 65 33 20 2a 64 62 2c  nly(sqlite3 *db,
38110 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44 62   const char *zDb
38120 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Name);../*.** CA
38130 50 49 33 52 45 46 3a 20 46 69 6e 64 20 74 68 65  PI3REF: Find the
38140 20 6e 65 78 74 20 70 72 65 70 61 72 65 64 20 73   next prepared s
38150 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e  tatement.**.** ^
38160 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 72  This interface r
38170 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
38180 20 74 6f 20 74 68 65 20 6e 65 78 74 20 5b 70 72   to the next [pr
38190 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
381a0 5d 20 61 66 74 65 72 0a 2a 2a 20 70 53 74 6d 74  ] after.** pStmt
381b0 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
381c0 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
381d0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 44 62 2e 20  onnection] pDb. 
381e0 20 5e 49 66 20 70 53 74 6d 74 20 69 73 20 4e 55   ^If pStmt is NU
381f0 4c 4c 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 20  LL.** then this 
38200 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
38210 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  s a pointer to t
38220 68 65 20 66 69 72 73 74 20 70 72 65 70 61 72 65  he first prepare
38230 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 61  d statement.** a
38240 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
38250 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
38260 65 63 74 69 6f 6e 20 70 44 62 2e 20 20 5e 49 66  ection pDb.  ^If
38270 20 6e 6f 20 70 72 65 70 61 72 65 64 20 73 74 61   no prepared sta
38280 74 65 6d 65 6e 74 0a 2a 2a 20 73 61 74 69 73 66  tement.** satisf
38290 69 65 73 20 74 68 65 20 63 6f 6e 64 69 74 69 6f  ies the conditio
382a0 6e 73 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69  ns of this routi
382b0 6e 65 2c 20 69 74 20 72 65 74 75 72 6e 73 20 4e  ne, it returns N
382c0 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  ULL..**.** The [
382d0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
382e0 69 6f 6e 5d 20 70 6f 69 6e 74 65 72 20 44 20 69  ion] pointer D i
382f0 6e 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b  n a call to.** [
38300 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d  sqlite3_next_stm
38310 74 28 44 2c 53 29 5d 20 6d 75 73 74 20 72 65 66  t(D,S)] must ref
38320 65 72 20 74 6f 20 61 6e 20 6f 70 65 6e 20 64 61  er to an open da
38330 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63  tabase.** connec
38340 74 69 6f 6e 20 61 6e 64 20 69 6e 20 70 61 72 74  tion and in part
38350 69 63 75 6c 61 72 20 6d 75 73 74 20 6e 6f 74 20  icular must not 
38360 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  be a NULL pointe
38370 72 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 73 74  r..*/.sqlite3_st
38380 6d 74 20 2a 73 71 6c 69 74 65 33 5f 6e 65 78 74  mt *sqlite3_next
38390 5f 73 74 6d 74 28 73 71 6c 69 74 65 33 20 2a 70  _stmt(sqlite3 *p
383a0 44 62 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  Db, sqlite3_stmt
383b0 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
383c0 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 6d 69   CAPI3REF: Commi
383d0 74 20 41 6e 64 20 52 6f 6c 6c 62 61 63 6b 20 4e  t And Rollback N
383e0 6f 74 69 66 69 63 61 74 69 6f 6e 20 43 61 6c 6c  otification Call
383f0 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  backs.**.** ^The
38400 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f   sqlite3_commit_
38410 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 65  hook() interface
38420 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c   registers a cal
38430 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f  lback.** functio
38440 6e 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20  n to be invoked 
38450 77 68 65 6e 65 76 65 72 20 61 20 74 72 61 6e 73  whenever a trans
38460 61 63 74 69 6f 6e 20 69 73 20 5b 43 4f 4d 4d 49  action is [COMMI
38470 54 20 7c 20 63 6f 6d 6d 69 74 74 65 64 5d 2e 0a  T | committed]..
38480 2a 2a 20 5e 41 6e 79 20 63 61 6c 6c 62 61 63 6b  ** ^Any callback
38490 20 73 65 74 20 62 79 20 61 20 70 72 65 76 69 6f   set by a previo
384a0 75 73 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74  us call to sqlit
384b0 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29  e3_commit_hook()
384c0 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65  .** for the same
384d0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
384e0 74 69 6f 6e 20 69 73 20 6f 76 65 72 72 69 64 64  tion is overridd
384f0 65 6e 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  en..** ^The sqli
38500 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f  te3_rollback_hoo
38510 6b 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  k() interface re
38520 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61  gisters a callba
38530 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74  ck.** function t
38540 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65  o be invoked whe
38550 6e 65 76 65 72 20 61 20 74 72 61 6e 73 61 63 74  never a transact
38560 69 6f 6e 20 69 73 20 5b 52 4f 4c 4c 42 41 43 4b  ion is [ROLLBACK
38570 20 7c 20 72 6f 6c 6c 65 64 20 62 61 63 6b 5d 2e   | rolled back].
38580 0a 2a 2a 20 5e 41 6e 79 20 63 61 6c 6c 62 61 63  .** ^Any callbac
38590 6b 20 73 65 74 20 62 79 20 61 20 70 72 65 76 69  k set by a previ
385a0 6f 75 73 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  ous call to sqli
385b0 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f  te3_rollback_hoo
385c0 6b 28 29 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73  k().** for the s
385d0 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ame database con
385e0 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76 65 72 72  nection is overr
385f0 69 64 64 65 6e 2e 0a 2a 2a 20 5e 54 68 65 20 70  idden..** ^The p
38600 41 72 67 20 61 72 67 75 6d 65 6e 74 20 69 73 20  Arg argument is 
38610 70 61 73 73 65 64 20 74 68 72 6f 75 67 68 20 74  passed through t
38620 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 0a  o the callback..
38630 2a 2a 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62  ** ^If the callb
38640 61 63 6b 20 6f 6e 20 61 20 63 6f 6d 6d 69 74 20  ack on a commit 
38650 68 6f 6f 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65  hook function re
38660 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 0a  turns non-zero,.
38670 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 6f 6d 6d  ** then the comm
38680 69 74 20 69 73 20 63 6f 6e 76 65 72 74 65 64 20  it is converted 
38690 69 6e 74 6f 20 61 20 72 6f 6c 6c 62 61 63 6b 2e  into a rollback.
386a0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
386b0 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28  te3_commit_hook(
386c0 44 2c 43 2c 50 29 20 61 6e 64 20 73 71 6c 69 74  D,C,P) and sqlit
386d0 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b  e3_rollback_hook
386e0 28 44 2c 43 2c 50 29 20 66 75 6e 63 74 69 6f 6e  (D,C,P) function
386f0 73 0a 2a 2a 20 72 65 74 75 72 6e 20 74 68 65 20  s.** return the 
38700 50 20 61 72 67 75 6d 65 6e 74 20 66 72 6f 6d 20  P argument from 
38710 74 68 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c  the previous cal
38720 6c 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75  l of the same fu
38730 6e 63 74 69 6f 6e 0a 2a 2a 20 6f 6e 20 74 68 65  nction.** on the
38740 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20   same [database 
38750 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c 20 6f  connection] D, o
38760 72 20 4e 55 4c 4c 20 66 6f 72 0a 2a 2a 20 74 68  r NULL for.** th
38770 65 20 66 69 72 73 74 20 63 61 6c 6c 20 66 6f 72  e first call for
38780 20 65 61 63 68 20 66 75 6e 63 74 69 6f 6e 20 6f   each function o
38790 6e 20 44 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63  n D..**.** The c
387a0 6f 6d 6d 69 74 20 61 6e 64 20 72 6f 6c 6c 62 61  ommit and rollba
387b0 63 6b 20 68 6f 6f 6b 20 63 61 6c 6c 62 61 63 6b  ck hook callback
387c0 73 20 61 72 65 20 6e 6f 74 20 72 65 65 6e 74 72  s are not reentr
387d0 61 6e 74 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c  ant..** The call
387e0 62 61 63 6b 20 69 6d 70 6c 65 6d 65 6e 74 61 74  back implementat
387f0 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20  ion must not do 
38800 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 69  anything that wi
38810 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65  ll modify.** the
38820 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
38830 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65  tion that invoke
38840 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 20  d the callback. 
38850 20 41 6e 79 20 61 63 74 69 6f 6e 73 0a 2a 2a 20   Any actions.**