/ Hex Artifact Content
Login

Artifact cbe846facaba903654b4136c97e7f57b3ac0bac7:


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 28 29 20 69  qlite3_close() i
2f20: 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 64  s called on a [d
2f30: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2f40: 6f 6e 5d 20 74 68 61 74 20 73 74 69 6c 6c 20 68  on] that still h
2f50: 61 73 0a 2a 2a 20 6f 75 74 73 74 61 6e 64 69 6e  as.** outstandin
2f60: 67 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  g [prepared stat
2f70: 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68  ements], [BLOB h
2f80: 61 6e 64 6c 65 73 5d 2c 20 61 6e 64 2f 6f 72 0a  andles], and/or.
2f90: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b  ** [sqlite3_back
2fa0: 75 70 5d 20 6f 62 6a 65 63 74 73 20 74 68 65 6e  up] objects then
2fb0: 20 69 74 20 72 65 74 75 72 6e 73 20 53 51 4c 49   it returns SQLI
2fc0: 54 45 5f 4f 4b 20 62 75 74 20 74 68 65 20 64 65  TE_OK but the de
2fd0: 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66  allocation.** of
2fe0: 20 72 65 73 6f 75 72 63 65 73 20 69 73 20 64 65   resources is de
2ff0: 66 65 72 72 65 64 20 75 6e 74 69 6c 20 61 6c 6c  ferred until all
3000: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
3010: 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68 61  ments], [BLOB ha
3020: 6e 64 6c 65 73 5d 2c 0a 2a 2a 20 61 6e 64 20 5b  ndles],.** and [
3030: 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d 20  sqlite3_backup] 
3040: 6f 62 6a 65 63 74 73 20 61 72 65 20 61 6c 73 6f  objects are also
3050: 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a 0a 2a   destroyed..**.*
3060: 2a 20 5e 49 66 20 61 6e 20 5b 73 71 6c 69 74 65  * ^If an [sqlite
3070: 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 64 65 73  3] object is des
3080: 74 72 6f 79 65 64 20 77 68 69 6c 65 20 61 20 74  troyed while a t
3090: 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 6f 70  ransaction is op
30a0: 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72 61 6e 73  en,.** the trans
30b0: 61 63 74 69 6f 6e 20 69 73 20 61 75 74 6f 6d 61  action is automa
30c0: 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62  tically rolled b
30d0: 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43  ack..**.** The C
30e0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73   parameter to [s
30f0: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d  qlite3_close(C)]
3100: 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c   and [sqlite3_cl
3110: 6f 73 65 5f 76 32 28 43 29 5d 0a 2a 2a 20 6d 75  ose_v2(C)].** mu
3120: 73 74 20 62 65 20 65 69 74 68 65 72 20 61 20 4e  st be either a N
3130: 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 6f  ULL.** pointer o
3140: 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f  r an [sqlite3] o
3150: 62 6a 65 63 74 20 70 6f 69 6e 74 65 72 20 6f 62  bject pointer ob
3160: 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b  tained.** from [
3170: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
3180: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
3190: 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  ()], or.** [sqli
31a0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20  te3_open_v2()], 
31b0: 61 6e 64 20 6e 6f 74 20 70 72 65 76 69 6f 75 73  and not previous
31c0: 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 5e 43  ly closed..** ^C
31d0: 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 63  alling sqlite3_c
31e0: 6c 6f 73 65 28 29 20 6f 72 20 73 71 6c 69 74 65  lose() or sqlite
31f0: 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 77 69 74  3_close_v2() wit
3200: 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  h a NULL pointer
3210: 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73 20  .** argument is 
3220: 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70  a harmless no-op
3230: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
3240: 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65 33 2a 29  _close(sqlite3*)
3250: 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c  ;.int sqlite3_cl
3260: 6f 73 65 5f 76 32 28 73 71 6c 69 74 65 33 2a 29  ose_v2(sqlite3*)
3270: 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74 79 70  ;../*.** The typ
3280: 65 20 66 6f 72 20 61 20 63 61 6c 6c 62 61 63 6b  e for a callback
3290: 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68   function..** Th
32a0: 69 73 20 69 73 20 6c 65 67 61 63 79 20 61 6e 64  is is legacy and
32b0: 20 64 65 70 72 65 63 61 74 65 64 2e 20 20 49 74   deprecated.  It
32c0: 20 69 73 20 69 6e 63 6c 75 64 65 64 20 66 6f 72   is included for
32d0: 20 68 69 73 74 6f 72 69 63 61 6c 0a 2a 2a 20 63   historical.** c
32e0: 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 61 6e 64  ompatibility and
32f0: 20 69 73 20 6e 6f 74 20 64 6f 63 75 6d 65 6e 74   is not document
3300: 65 64 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 69  ed..*/.typedef i
3310: 6e 74 20 28 2a 73 71 6c 69 74 65 33 5f 63 61 6c  nt (*sqlite3_cal
3320: 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74  lback)(void*,int
3330: 2c 63 68 61 72 2a 2a 2c 20 63 68 61 72 2a 2a 29  ,char**, char**)
3340: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
3350: 46 3a 20 4f 6e 65 2d 53 74 65 70 20 51 75 65 72  F: One-Step Quer
3360: 79 20 45 78 65 63 75 74 69 6f 6e 20 49 6e 74 65  y Execution Inte
3370: 72 66 61 63 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20  rface.**.** The 
3380: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69  sqlite3_exec() i
3390: 6e 74 65 72 66 61 63 65 20 69 73 20 61 20 63 6f  nterface is a co
33a0: 6e 76 65 6e 69 65 6e 63 65 20 77 72 61 70 70 65  nvenience wrappe
33b0: 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c  r around.** [sql
33c0: 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
33d0: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  )], [sqlite3_ste
33e0: 70 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74  p()], and [sqlit
33f0: 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2c 0a  e3_finalize()],.
3400: 2a 2a 20 74 68 61 74 20 61 6c 6c 6f 77 73 20 61  ** that allows a
3410: 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f  n application to
3420: 20 72 75 6e 20 6d 75 6c 74 69 70 6c 65 20 73 74   run multiple st
3430: 61 74 65 6d 65 6e 74 73 20 6f 66 20 53 51 4c 0a  atements of SQL.
3440: 2a 2a 20 77 69 74 68 6f 75 74 20 68 61 76 69 6e  ** without havin
3450: 67 20 74 6f 20 75 73 65 20 61 20 6c 6f 74 20 6f  g to use a lot o
3460: 66 20 43 20 63 6f 64 65 2e 20 0a 2a 2a 0a 2a 2a  f C code. .**.**
3470: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78   ^The sqlite3_ex
3480: 65 63 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  ec() interface r
3490: 75 6e 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65  uns zero or more
34a0: 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2c 0a   UTF-8 encoded,.
34b0: 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70  ** semicolon-sep
34c0: 61 72 61 74 65 20 53 51 4c 20 73 74 61 74 65 6d  arate SQL statem
34d0: 65 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74 6f  ents passed into
34e0: 20 69 74 73 20 32 6e 64 20 61 72 67 75 6d 65 6e   its 2nd argumen
34f0: 74 2c 0a 2a 2a 20 69 6e 20 74 68 65 20 63 6f 6e  t,.** in the con
3500: 74 65 78 74 20 6f 66 20 74 68 65 20 5b 64 61 74  text of the [dat
3510: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
3520: 5d 20 70 61 73 73 65 64 20 69 6e 20 61 73 20 69  ] passed in as i
3530: 74 73 20 31 73 74 0a 2a 2a 20 61 72 67 75 6d 65  ts 1st.** argume
3540: 6e 74 2e 20 20 5e 49 66 20 74 68 65 20 63 61 6c  nt.  ^If the cal
3550: 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6f  lback function o
3560: 66 20 74 68 65 20 33 72 64 20 61 72 67 75 6d 65  f the 3rd argume
3570: 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  nt to.** sqlite3
3580: 5f 65 78 65 63 28 29 20 69 73 20 6e 6f 74 20 4e  _exec() is not N
3590: 55 4c 4c 2c 20 74 68 65 6e 20 69 74 20 69 73 20  ULL, then it is 
35a0: 69 6e 76 6f 6b 65 64 20 66 6f 72 20 65 61 63 68  invoked for each
35b0: 20 72 65 73 75 6c 74 20 72 6f 77 0a 2a 2a 20 63   result row.** c
35c0: 6f 6d 69 6e 67 20 6f 75 74 20 6f 66 20 74 68 65  oming out of the
35d0: 20 65 76 61 6c 75 61 74 65 64 20 53 51 4c 20 73   evaluated SQL s
35e0: 74 61 74 65 6d 65 6e 74 73 2e 20 20 5e 54 68 65  tatements.  ^The
35f0: 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f   4th argument to
3600: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63  .** sqlite3_exec
3610: 28 29 20 69 73 20 72 65 6c 61 79 65 64 20 74 68  () is relayed th
3620: 72 6f 75 67 68 20 74 6f 20 74 68 65 20 31 73 74  rough to the 1st
3630: 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 65 61 63   argument of eac
3640: 68 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 6e  h.** callback in
3650: 76 6f 63 61 74 69 6f 6e 2e 20 20 5e 49 66 20 74  vocation.  ^If t
3660: 68 65 20 63 61 6c 6c 62 61 63 6b 20 70 6f 69 6e  he callback poin
3670: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65  ter to sqlite3_e
3680: 78 65 63 28 29 0a 2a 2a 20 69 73 20 4e 55 4c 4c  xec().** is NULL
3690: 2c 20 74 68 65 6e 20 6e 6f 20 63 61 6c 6c 62 61  , then no callba
36a0: 63 6b 20 69 73 20 65 76 65 72 20 69 6e 76 6f 6b  ck is ever invok
36b0: 65 64 20 61 6e 64 20 72 65 73 75 6c 74 20 72 6f  ed and result ro
36c0: 77 73 20 61 72 65 0a 2a 2a 20 69 67 6e 6f 72 65  ws are.** ignore
36d0: 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20  d..**.** ^If an 
36e0: 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68 69  error occurs whi
36f0: 6c 65 20 65 76 61 6c 75 61 74 69 6e 67 20 74 68  le evaluating th
3700: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  e SQL statements
3710: 20 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20   passed into.** 
3720: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 2c 20  sqlite3_exec(), 
3730: 74 68 65 6e 20 65 78 65 63 75 74 69 6f 6e 20 6f  then execution o
3740: 66 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74  f the current st
3750: 61 74 65 6d 65 6e 74 20 73 74 6f 70 73 20 61 6e  atement stops an
3760: 64 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20  d.** subsequent 
3770: 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 73  statements are s
3780: 6b 69 70 70 65 64 2e 20 20 5e 49 66 20 74 68 65  kipped.  ^If the
3790: 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   5th parameter t
37a0: 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  o sqlite3_exec()
37b0: 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20  .** is not NULL 
37c0: 74 68 65 6e 20 61 6e 79 20 65 72 72 6f 72 20 6d  then any error m
37d0: 65 73 73 61 67 65 20 69 73 20 77 72 69 74 74 65  essage is writte
37e0: 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62  n into memory ob
37f0: 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b  tained.** from [
3800: 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
3810: 5d 20 61 6e 64 20 70 61 73 73 65 64 20 62 61 63  ] and passed bac
3820: 6b 20 74 68 72 6f 75 67 68 20 74 68 65 20 35 74  k through the 5t
3830: 68 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20  h parameter..** 
3840: 54 6f 20 61 76 6f 69 64 20 6d 65 6d 6f 72 79 20  To avoid memory 
3850: 6c 65 61 6b 73 2c 20 74 68 65 20 61 70 70 6c 69  leaks, the appli
3860: 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 69 6e  cation should in
3870: 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66 72  voke [sqlite3_fr
3880: 65 65 28 29 5d 0a 2a 2a 20 6f 6e 20 65 72 72 6f  ee()].** on erro
3890: 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67  r message string
38a0: 73 20 72 65 74 75 72 6e 65 64 20 74 68 72 6f 75  s returned throu
38b0: 67 68 20 74 68 65 20 35 74 68 20 70 61 72 61 6d  gh the 5th param
38c0: 65 74 65 72 20 6f 66 0a 2a 2a 20 6f 66 20 73 71  eter of.** of sq
38d0: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 61 66 74  lite3_exec() aft
38e0: 65 72 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73  er the error mes
38f0: 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 6e  sage string is n
3900: 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65 64 2e  o longer needed.
3910: 0a 2a 2a 20 5e 49 66 20 74 68 65 20 35 74 68 20  .** ^If the 5th 
3920: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
3930: 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 6e  ite3_exec() is n
3940: 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 6e 6f 20 65  ot NULL and no e
3950: 72 72 6f 72 73 0a 2a 2a 20 6f 63 63 75 72 2c 20  rrors.** occur, 
3960: 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 65 78 65  then sqlite3_exe
3970: 63 28 29 20 73 65 74 73 20 74 68 65 20 70 6f 69  c() sets the poi
3980: 6e 74 65 72 20 69 6e 20 69 74 73 20 35 74 68 20  nter in its 5th 
3990: 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
39a0: 4e 55 4c 4c 20 62 65 66 6f 72 65 20 72 65 74 75  NULL before retu
39b0: 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  rning..**.** ^If
39c0: 20 61 6e 20 73 71 6c 69 74 65 33 5f 65 78 65 63   an sqlite3_exec
39d0: 28 29 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  () callback retu
39e0: 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68  rns non-zero, th
39f0: 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  e sqlite3_exec()
3a00: 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75  .** routine retu
3a10: 72 6e 73 20 53 51 4c 49 54 45 5f 41 42 4f 52 54  rns SQLITE_ABORT
3a20: 20 77 69 74 68 6f 75 74 20 69 6e 76 6f 6b 69 6e   without invokin
3a30: 67 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61  g the callback a
3a40: 67 61 69 6e 20 61 6e 64 0a 2a 2a 20 77 69 74 68  gain and.** with
3a50: 6f 75 74 20 72 75 6e 6e 69 6e 67 20 61 6e 79 20  out running any 
3a60: 73 75 62 73 65 71 75 65 6e 74 20 53 51 4c 20 73  subsequent SQL s
3a70: 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a  tatements..**.**
3a80: 20 5e 54 68 65 20 32 6e 64 20 61 72 67 75 6d 65   ^The 2nd argume
3a90: 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  nt to the sqlite
3aa0: 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63  3_exec() callbac
3ab0: 6b 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 68  k function is th
3ac0: 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63  e.** number of c
3ad0: 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65  olumns in the re
3ae0: 73 75 6c 74 2e 20 20 5e 54 68 65 20 33 72 64 20  sult.  ^The 3rd 
3af0: 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
3b00: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a  sqlite3_exec().*
3b10: 2a 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e  * callback is an
3b20: 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65   array of pointe
3b30: 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 6f 62  rs to strings ob
3b40: 74 61 69 6e 65 64 20 61 73 20 69 66 20 66 72 6f  tained as if fro
3b50: 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  m.** [sqlite3_co
3b60: 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 6f 6e  lumn_text()], on
3b70: 65 20 66 6f 72 20 65 61 63 68 20 63 6f 6c 75 6d  e for each colum
3b80: 6e 2e 20 20 5e 49 66 20 61 6e 20 65 6c 65 6d 65  n.  ^If an eleme
3b90: 6e 74 20 6f 66 20 61 0a 2a 2a 20 72 65 73 75 6c  nt of a.** resul
3ba0: 74 20 72 6f 77 20 69 73 20 4e 55 4c 4c 20 74 68  t row is NULL th
3bb0: 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  en the correspon
3bc0: 64 69 6e 67 20 73 74 72 69 6e 67 20 70 6f 69 6e  ding string poin
3bd0: 74 65 72 20 66 6f 72 20 74 68 65 0a 2a 2a 20 73  ter for the.** s
3be0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61  qlite3_exec() ca
3bf0: 6c 6c 62 61 63 6b 20 69 73 20 61 20 4e 55 4c 4c  llback is a NULL
3c00: 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20   pointer.  ^The 
3c10: 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  4th argument to 
3c20: 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65  the.** sqlite3_e
3c30: 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 69  xec() callback i
3c40: 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f  s an array of po
3c50: 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67  inters to string
3c60: 73 20 77 68 65 72 65 20 65 61 63 68 0a 2a 2a 20  s where each.** 
3c70: 65 6e 74 72 79 20 72 65 70 72 65 73 65 6e 74 73  entry represents
3c80: 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 63 6f 72   the name of cor
3c90: 72 65 73 70 6f 6e 64 69 6e 67 20 72 65 73 75 6c  responding resul
3ca0: 74 20 63 6f 6c 75 6d 6e 20 61 73 20 6f 62 74 61  t column as obta
3cb0: 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71  ined.** from [sq
3cc0: 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
3cd0: 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  e()]..**.** ^If 
3ce0: 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
3cf0: 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65  r to sqlite3_exe
3d00: 63 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  c() is a NULL po
3d10: 69 6e 74 65 72 2c 20 61 20 70 6f 69 6e 74 65 72  inter, a pointer
3d20: 0a 2a 2a 20 74 6f 20 61 6e 20 65 6d 70 74 79 20  .** to an empty 
3d30: 73 74 72 69 6e 67 2c 20 6f 72 20 61 20 70 6f 69  string, or a poi
3d40: 6e 74 65 72 20 74 68 61 74 20 63 6f 6e 74 61 69  nter that contai
3d50: 6e 73 20 6f 6e 6c 79 20 77 68 69 74 65 73 70 61  ns only whitespa
3d60: 63 65 20 61 6e 64 2f 6f 72 20 0a 2a 2a 20 53 51  ce and/or .** SQ
3d70: 4c 20 63 6f 6d 6d 65 6e 74 73 2c 20 74 68 65 6e  L comments, then
3d80: 20 6e 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   no SQL statemen
3d90: 74 73 20 61 72 65 20 65 76 61 6c 75 61 74 65 64  ts are evaluated
3da0: 20 61 6e 64 20 74 68 65 20 64 61 74 61 62 61 73   and the databas
3db0: 65 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e  e.** is not chan
3dc0: 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 73 74 72  ged..**.** Restr
3dd0: 69 63 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20 3c  ictions:.**.** <
3de0: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20  ul>.** <li> The 
3df0: 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
3e00: 20 69 6e 73 75 72 65 20 74 68 61 74 20 74 68 65   insure that the
3e10: 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 20 74   1st parameter t
3e20: 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  o sqlite3_exec()
3e30: 0a 2a 2a 20 20 20 20 20 20 69 73 20 61 20 76 61  .**      is a va
3e40: 6c 69 64 20 61 6e 64 20 6f 70 65 6e 20 5b 64 61  lid and open [da
3e50: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
3e60: 6e 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20  n]..** <li> The 
3e70: 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
3e80: 20 6e 6f 74 20 63 6c 6f 73 65 20 5b 64 61 74 61   not close [data
3e90: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
3ea0: 20 73 70 65 63 69 66 69 65 64 20 62 79 0a 2a 2a   specified by.**
3eb0: 20 20 20 20 20 20 74 68 65 20 31 73 74 20 70 61        the 1st pa
3ec0: 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
3ed0: 65 33 5f 65 78 65 63 28 29 20 77 68 69 6c 65 20  e3_exec() while 
3ee0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69  sqlite3_exec() i
3ef0: 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 6c  s running..** <l
3f00: 69 3e 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  i> The applicati
3f10: 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 6d 6f 64 69  on must not modi
3f20: 66 79 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  fy the SQL state
3f30: 6d 65 6e 74 20 74 65 78 74 20 70 61 73 73 65 64  ment text passed
3f40: 20 69 6e 74 6f 0a 2a 2a 20 20 20 20 20 20 74 68   into.**      th
3f50: 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  e 2nd parameter 
3f60: 6f 66 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  of sqlite3_exec(
3f70: 29 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f  ) while sqlite3_
3f80: 65 78 65 63 28 29 20 69 73 20 72 75 6e 6e 69 6e  exec() is runnin
3f90: 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 69  g..** </ul>.*/.i
3fa0: 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  nt sqlite3_exec(
3fb0: 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 20 20 20  .  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 2f 2a                /*
3fe0: 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73   An open databas
3ff0: 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
4000: 72 20 2a 73 71 6c 2c 20 20 20 20 20 20 20 20 20  r *sql,         
4010: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4020: 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65    /* SQL to be e
4030: 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 69 6e  valuated */.  in
4040: 74 20 28 2a 63 61 6c 6c 62 61 63 6b 29 28 76 6f  t (*callback)(vo
4050: 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 63  id*,int,char**,c
4060: 68 61 72 2a 2a 29 2c 20 20 2f 2a 20 43 61 6c 6c  har**),  /* Call
4070: 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2a 2f  back function */
4080: 0a 20 20 76 6f 69 64 20 2a 2c 20 20 20 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 2f 2a                /*
40b0: 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f   1st argument to
40c0: 20 63 61 6c 6c 62 61 63 6b 20 2a 2f 0a 20 20 63   callback */.  c
40d0: 68 61 72 20 2a 2a 65 72 72 6d 73 67 20 20 20 20  har **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 2f 2a 20 45 72 72            /* Err
4100: 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68  or msg written h
4110: 65 72 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  ere */.);../*.**
4120: 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c   CAPI3REF: Resul
4130: 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f  t Codes.** KEYWO
4140: 52 44 53 3a 20 53 51 4c 49 54 45 5f 4f 4b 20 7b  RDS: SQLITE_OK {
4150: 65 72 72 6f 72 20 63 6f 64 65 7d 20 7b 65 72 72  error code} {err
4160: 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59  or codes}.** KEY
4170: 57 4f 52 44 53 3a 20 7b 72 65 73 75 6c 74 20 63  WORDS: {result c
4180: 6f 64 65 7d 20 7b 72 65 73 75 6c 74 20 63 6f 64  ode} {result cod
4190: 65 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53  es}.**.** Many S
41a0: 51 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73 20  QLite functions 
41b0: 72 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67 65  return an intege
41c0: 72 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66 72  r result code fr
41d0: 6f 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77 6e  om the set shown
41e0: 0a 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 64 65  .** here in orde
41f0: 72 20 74 6f 20 69 6e 64 69 63 61 74 65 20 73 75  r to indicate su
4200: 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72 65  ccess or failure
4210: 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72 72 6f  ..**.** New erro
4220: 72 20 63 6f 64 65 73 20 6d 61 79 20 62 65 20 61  r codes may be a
4230: 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 76  dded in future v
4240: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
4250: 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  e..**.** See als
4260: 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  o: [SQLITE_IOERR
4270: 5f 52 45 41 44 20 7c 20 65 78 74 65 6e 64 65 64  _READ | extended
4280: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 2c 0a   result codes],.
4290: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 74 61 62  ** [sqlite3_vtab
42a0: 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28 29 5d 20  _on_conflict()] 
42b0: 5b 53 51 4c 49 54 45 5f 52 4f 4c 4c 42 41 43 4b  [SQLITE_ROLLBACK
42c0: 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d   | result codes]
42d0: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
42e0: 49 54 45 5f 4f 4b 20 20 20 20 20 20 20 20 20 20  ITE_OK          
42f0: 20 30 20 20 20 2f 2a 20 53 75 63 63 65 73 73 66   0   /* Successf
4300: 75 6c 20 72 65 73 75 6c 74 20 2a 2f 0a 2f 2a 20  ul result */./* 
4310: 62 65 67 69 6e 6e 69 6e 67 2d 6f 66 2d 65 72 72  beginning-of-err
4320: 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 23 64 65 66  or-codes */.#def
4330: 69 6e 65 20 53 51 4c 49 54 45 5f 45 52 52 4f 52  ine SQLITE_ERROR
4340: 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20 53          1   /* S
4350: 51 4c 20 65 72 72 6f 72 20 6f 72 20 6d 69 73 73  QL error or miss
4360: 69 6e 67 20 64 61 74 61 62 61 73 65 20 2a 2f 0a  ing database */.
4370: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4380: 4e 54 45 52 4e 41 4c 20 20 20 20 20 32 20 20 20  NTERNAL     2   
4390: 2f 2a 20 49 6e 74 65 72 6e 61 6c 20 6c 6f 67 69  /* Internal logi
43a0: 63 20 65 72 72 6f 72 20 69 6e 20 53 51 4c 69 74  c error in SQLit
43b0: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e */.#define SQL
43c0: 49 54 45 5f 50 45 52 4d 20 20 20 20 20 20 20 20  ITE_PERM        
43d0: 20 33 20 20 20 2f 2a 20 41 63 63 65 73 73 20 70   3   /* Access p
43e0: 65 72 6d 69 73 73 69 6f 6e 20 64 65 6e 69 65 64  ermission denied
43f0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4400: 54 45 5f 41 42 4f 52 54 20 20 20 20 20 20 20 20  TE_ABORT        
4410: 34 20 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20  4   /* Callback 
4420: 72 6f 75 74 69 6e 65 20 72 65 71 75 65 73 74 65  routine requeste
4430: 64 20 61 6e 20 61 62 6f 72 74 20 2a 2f 0a 23 64  d an abort */.#d
4440: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53  efine SQLITE_BUS
4450: 59 20 20 20 20 20 20 20 20 20 35 20 20 20 2f 2a  Y         5   /*
4460: 20 54 68 65 20 64 61 74 61 62 61 73 65 20 66 69   The database fi
4470: 6c 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a  le is locked */.
4480: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
4490: 4f 43 4b 45 44 20 20 20 20 20 20 20 36 20 20 20  OCKED       6   
44a0: 2f 2a 20 41 20 74 61 62 6c 65 20 69 6e 20 74 68  /* A table in th
44b0: 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6c 6f  e database is lo
44c0: 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  cked */.#define 
44d0: 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 20 20 20  SQLITE_NOMEM    
44e0: 20 20 20 20 37 20 20 20 2f 2a 20 41 20 6d 61 6c      7   /* A mal
44f0: 6c 6f 63 28 29 20 66 61 69 6c 65 64 20 2a 2f 0a  loc() failed */.
4500: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
4510: 45 41 44 4f 4e 4c 59 20 20 20 20 20 38 20 20 20  EADONLY     8   
4520: 2f 2a 20 41 74 74 65 6d 70 74 20 74 6f 20 77 72  /* Attempt to wr
4530: 69 74 65 20 61 20 72 65 61 64 6f 6e 6c 79 20 64  ite a readonly d
4540: 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65 66 69  atabase */.#defi
4550: 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 52 52  ne SQLITE_INTERR
4560: 55 50 54 20 20 20 20 39 20 20 20 2f 2a 20 4f 70  UPT    9   /* Op
4570: 65 72 61 74 69 6f 6e 20 74 65 72 6d 69 6e 61 74  eration terminat
4580: 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e  ed by sqlite3_in
4590: 74 65 72 72 75 70 74 28 29 2a 2f 0a 23 64 65 66  terrupt()*/.#def
45a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
45b0: 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20 53         10   /* S
45c0: 6f 6d 65 20 6b 69 6e 64 20 6f 66 20 64 69 73 6b  ome kind of disk
45d0: 20 49 2f 4f 20 65 72 72 6f 72 20 6f 63 63 75 72   I/O error occur
45e0: 72 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  red */.#define S
45f0: 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 20 20  QLITE_CORRUPT   
4600: 20 20 31 31 20 20 20 2f 2a 20 54 68 65 20 64 61    11   /* The da
4610: 74 61 62 61 73 65 20 64 69 73 6b 20 69 6d 61 67  tabase disk imag
4620: 65 20 69 73 20 6d 61 6c 66 6f 72 6d 65 64 20 2a  e is malformed *
4630: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4640: 5f 4e 4f 54 46 4f 55 4e 44 20 20 20 20 31 32 20  _NOTFOUND    12 
4650: 20 20 2f 2a 20 55 6e 6b 6e 6f 77 6e 20 6f 70 63    /* Unknown opc
4660: 6f 64 65 20 69 6e 20 73 71 6c 69 74 65 33 5f 66  ode in sqlite3_f
4670: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 20 2a 2f  ile_control() */
4680: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4690: 46 55 4c 4c 20 20 20 20 20 20 20 20 31 33 20 20  FULL        13  
46a0: 20 2f 2a 20 49 6e 73 65 72 74 69 6f 6e 20 66 61   /* Insertion fa
46b0: 69 6c 65 64 20 62 65 63 61 75 73 65 20 64 61 74  iled because dat
46c0: 61 62 61 73 65 20 69 73 20 66 75 6c 6c 20 2a 2f  abase is full */
46d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
46e0: 43 41 4e 54 4f 50 45 4e 20 20 20 20 31 34 20 20  CANTOPEN    14  
46f0: 20 2f 2a 20 55 6e 61 62 6c 65 20 74 6f 20 6f 70   /* Unable to op
4700: 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
4710: 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  file */.#define 
4720: 53 51 4c 49 54 45 5f 50 52 4f 54 4f 43 4f 4c 20  SQLITE_PROTOCOL 
4730: 20 20 20 31 35 20 20 20 2f 2a 20 44 61 74 61 62     15   /* Datab
4740: 61 73 65 20 6c 6f 63 6b 20 70 72 6f 74 6f 63 6f  ase lock protoco
4750: 6c 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69  l error */.#defi
4760: 6e 65 20 53 51 4c 49 54 45 5f 45 4d 50 54 59 20  ne SQLITE_EMPTY 
4770: 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20 44 61        16   /* Da
4780: 74 61 62 61 73 65 20 69 73 20 65 6d 70 74 79 20  tabase is empty 
4790: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
47a0: 45 5f 53 43 48 45 4d 41 20 20 20 20 20 20 31 37  E_SCHEMA      17
47b0: 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61     /* The databa
47c0: 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65  se schema change
47d0: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
47e0: 49 54 45 5f 54 4f 4f 42 49 47 20 20 20 20 20 20  ITE_TOOBIG      
47f0: 31 38 20 20 20 2f 2a 20 53 74 72 69 6e 67 20 6f  18   /* String o
4800: 72 20 42 4c 4f 42 20 65 78 63 65 65 64 73 20 73  r BLOB exceeds s
4810: 69 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a 23 64 65  ize limit */.#de
4820: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
4830: 54 52 41 49 4e 54 20 20 31 39 20 20 20 2f 2a 20  TRAINT  19   /* 
4840: 41 62 6f 72 74 20 64 75 65 20 74 6f 20 63 6f 6e  Abort due to con
4850: 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f  straint violatio
4860: 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  n */.#define SQL
4870: 49 54 45 5f 4d 49 53 4d 41 54 43 48 20 20 20 20  ITE_MISMATCH    
4880: 32 30 20 20 20 2f 2a 20 44 61 74 61 20 74 79 70  20   /* Data typ
4890: 65 20 6d 69 73 6d 61 74 63 68 20 2a 2f 0a 23 64  e mismatch */.#d
48a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53  efine SQLITE_MIS
48b0: 55 53 45 20 20 20 20 20 20 32 31 20 20 20 2f 2a  USE      21   /*
48c0: 20 4c 69 62 72 61 72 79 20 75 73 65 64 20 69 6e   Library used in
48d0: 63 6f 72 72 65 63 74 6c 79 20 2a 2f 0a 23 64 65  correctly */.#de
48e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4c 46  fine SQLITE_NOLF
48f0: 53 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20  S       22   /* 
4900: 55 73 65 73 20 4f 53 20 66 65 61 74 75 72 65 73  Uses OS features
4910: 20 6e 6f 74 20 73 75 70 70 6f 72 74 65 64 20 6f   not supported o
4920: 6e 20 68 6f 73 74 20 2a 2f 0a 23 64 65 66 69 6e  n host */.#defin
4930: 65 20 53 51 4c 49 54 45 5f 41 55 54 48 20 20 20  e SQLITE_AUTH   
4940: 20 20 20 20 20 32 33 20 20 20 2f 2a 20 41 75 74       23   /* Aut
4950: 68 6f 72 69 7a 61 74 69 6f 6e 20 64 65 6e 69 65  horization denie
4960: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
4970: 49 54 45 5f 46 4f 52 4d 41 54 20 20 20 20 20 20  ITE_FORMAT      
4980: 32 34 20 20 20 2f 2a 20 41 75 78 69 6c 69 61 72  24   /* Auxiliar
4990: 79 20 64 61 74 61 62 61 73 65 20 66 6f 72 6d 61  y database forma
49a0: 74 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69  t error */.#defi
49b0: 6e 65 20 53 51 4c 49 54 45 5f 52 41 4e 47 45 20  ne SQLITE_RANGE 
49c0: 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20 32 6e        25   /* 2n
49d0: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
49e0: 71 6c 69 74 65 33 5f 62 69 6e 64 20 6f 75 74 20  qlite3_bind out 
49f0: 6f 66 20 72 61 6e 67 65 20 2a 2f 0a 23 64 65 66  of range */.#def
4a00: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 41 44  ine SQLITE_NOTAD
4a10: 42 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20 46  B      26   /* F
4a20: 69 6c 65 20 6f 70 65 6e 65 64 20 74 68 61 74 20  ile opened that 
4a30: 69 73 20 6e 6f 74 20 61 20 64 61 74 61 62 61 73  is not a databas
4a40: 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e  e file */.#defin
4a50: 65 20 53 51 4c 49 54 45 5f 52 4f 57 20 20 20 20  e SQLITE_ROW    
4a60: 20 20 20 20 20 31 30 30 20 20 2f 2a 20 73 71 6c       100  /* sql
4a70: 69 74 65 33 5f 73 74 65 70 28 29 20 68 61 73 20  ite3_step() has 
4a80: 61 6e 6f 74 68 65 72 20 72 6f 77 20 72 65 61 64  another row read
4a90: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
4aa0: 49 54 45 5f 44 4f 4e 45 20 20 20 20 20 20 20 20  ITE_DONE        
4ab0: 31 30 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f  101  /* sqlite3_
4ac0: 73 74 65 70 28 29 20 68 61 73 20 66 69 6e 69 73  step() has finis
4ad0: 68 65 64 20 65 78 65 63 75 74 69 6e 67 20 2a 2f  hed executing */
4ae0: 0a 2f 2a 20 65 6e 64 2d 6f 66 2d 65 72 72 6f 72  ./* end-of-error
4af0: 2d 63 6f 64 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a  -codes */../*.**
4b00: 20 43 41 50 49 33 52 45 46 3a 20 45 78 74 65 6e   CAPI3REF: Exten
4b10: 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73  ded Result Codes
4b20: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 65  .** KEYWORDS: {e
4b30: 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f  xtended error co
4b40: 64 65 7d 20 7b 65 78 74 65 6e 64 65 64 20 65 72  de} {extended er
4b50: 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45  ror codes}.** KE
4b60: 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e 64 65  YWORDS: {extende
4b70: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 7d 20 7b  d result code} {
4b80: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
4b90: 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20  codes}.**.** In 
4ba0: 69 74 73 20 64 65 66 61 75 6c 74 20 63 6f 6e 66  its default conf
4bb0: 69 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69 74  iguration, SQLit
4bc0: 65 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20 72  e API routines r
4bd0: 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 32 36 20  eturn one of 26 
4be0: 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 53 51 4c 49  integer.** [SQLI
4bf0: 54 45 5f 4f 4b 20 7c 20 72 65 73 75 6c 74 20 63  TE_OK | result c
4c00: 6f 64 65 73 5d 2e 20 20 48 6f 77 65 76 65 72 2c  odes].  However,
4c10: 20 65 78 70 65 72 69 65 6e 63 65 20 68 61 73 20   experience has 
4c20: 73 68 6f 77 6e 20 74 68 61 74 20 6d 61 6e 79 20  shown that many 
4c30: 6f 66 0a 2a 2a 20 74 68 65 73 65 20 72 65 73 75  of.** these resu
4c40: 6c 74 20 63 6f 64 65 73 20 61 72 65 20 74 6f 6f  lt codes are too
4c50: 20 63 6f 61 72 73 65 2d 67 72 61 69 6e 65 64 2e   coarse-grained.
4c60: 20 20 54 68 65 79 20 64 6f 20 6e 6f 74 20 70 72    They do not pr
4c70: 6f 76 69 64 65 20 61 73 0a 2a 2a 20 6d 75 63 68  ovide as.** much
4c80: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f   information abo
4c90: 75 74 20 70 72 6f 62 6c 65 6d 73 20 61 73 20 70  ut problems as p
4ca0: 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 68 74  rogrammers might
4cb0: 20 6c 69 6b 65 2e 20 20 49 6e 20 61 6e 20 65 66   like.  In an ef
4cc0: 66 6f 72 74 20 74 6f 0a 2a 2a 20 61 64 64 72 65  fort to.** addre
4cd0: 73 73 20 74 68 69 73 2c 20 6e 65 77 65 72 20 76  ss this, newer v
4ce0: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
4cf0: 65 20 28 76 65 72 73 69 6f 6e 20 33 2e 33 2e 38  e (version 3.3.8
4d00: 20 61 6e 64 20 6c 61 74 65 72 29 20 69 6e 63 6c   and later) incl
4d10: 75 64 65 0a 2a 2a 20 73 75 70 70 6f 72 74 20 66  ude.** support f
4d20: 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 72 65  or additional re
4d30: 73 75 6c 74 20 63 6f 64 65 73 20 74 68 61 74 20  sult codes that 
4d40: 70 72 6f 76 69 64 65 20 6d 6f 72 65 20 64 65 74  provide more det
4d50: 61 69 6c 65 64 20 69 6e 66 6f 72 6d 61 74 69 6f  ailed informatio
4d60: 6e 0a 2a 2a 20 61 62 6f 75 74 20 65 72 72 6f 72  n.** about error
4d70: 73 2e 20 54 68 65 20 65 78 74 65 6e 64 65 64 20  s. The extended 
4d80: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65  result codes are
4d90: 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61   enabled or disa
4da0: 62 6c 65 64 0a 2a 2a 20 6f 6e 20 61 20 70 65 72  bled.** on a per
4db0: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
4dc0: 74 69 6f 6e 20 62 61 73 69 73 20 75 73 69 6e 67  tion basis using
4dd0: 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
4de0: 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74  _extended_result
4df0: 5f 63 6f 64 65 73 28 29 5d 20 41 50 49 2e 0a 2a  _codes()] API..*
4e00: 2a 0a 2a 2a 20 53 6f 6d 65 20 6f 66 20 74 68 65  *.** Some of the
4e10: 20 61 76 61 69 6c 61 62 6c 65 20 65 78 74 65 6e   available exten
4e20: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
4e30: 20 61 72 65 20 6c 69 73 74 65 64 20 68 65 72 65   are listed here
4e40: 2e 0a 2a 2a 20 4f 6e 65 20 6d 61 79 20 65 78 70  ..** One may exp
4e50: 65 63 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  ect the number o
4e60: 66 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c  f extended resul
4e70: 74 20 63 6f 64 65 73 20 77 69 6c 6c 20 62 65 20  t codes will be 
4e80: 65 78 70 61 6e 64 0a 2a 2a 20 6f 76 65 72 20 74  expand.** over t
4e90: 69 6d 65 2e 20 20 53 6f 66 74 77 61 72 65 20 74  ime.  Software t
4ea0: 68 61 74 20 75 73 65 73 20 65 78 74 65 6e 64 65  hat uses extende
4eb0: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 73  d result codes s
4ec0: 68 6f 75 6c 64 20 65 78 70 65 63 74 0a 2a 2a 20  hould expect.** 
4ed0: 74 6f 20 73 65 65 20 6e 65 77 20 72 65 73 75 6c  to see new resul
4ee0: 74 20 63 6f 64 65 73 20 69 6e 20 66 75 74 75 72  t codes in futur
4ef0: 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51  e releases of SQ
4f00: 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  Lite..**.** The 
4f10: 53 51 4c 49 54 45 5f 4f 4b 20 72 65 73 75 6c 74  SQLITE_OK result
4f20: 20 63 6f 64 65 20 77 69 6c 6c 20 6e 65 76 65 72   code will never
4f30: 20 62 65 20 65 78 74 65 6e 64 65 64 2e 20 20 49   be extended.  I
4f40: 74 20 77 69 6c 6c 20 61 6c 77 61 79 73 0a 2a 2a  t will always.**
4f50: 20 62 65 20 65 78 61 63 74 6c 79 20 7a 65 72 6f   be exactly zero
4f60: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
4f70: 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 20  ITE_IOERR_READ  
4f80: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
4f90: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 3c 3c  ITE_IOERR | (1<<
4fa0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4fb0: 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52  TE_IOERR_SHORT_R
4fc0: 45 41 44 20 20 20 20 20 20 20 20 28 53 51 4c 49  EAD        (SQLI
4fd0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c 3c 38  TE_IOERR | (2<<8
4fe0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
4ff0: 45 5f 49 4f 45 52 52 5f 57 52 49 54 45 20 20 20  E_IOERR_WRITE   
5000: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5010: 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c 38 29  E_IOERR | (3<<8)
5020: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5030: 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20 20 20 20  _IOERR_FSYNC    
5040: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5050: 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38 29 29  _IOERR | (4<<8))
5060: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5070: 49 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e 43 20  IOERR_DIR_FSYNC 
5080: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5090: 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29 29 0a  IOERR | (5<<8)).
50a0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
50b0: 4f 45 52 52 5f 54 52 55 4e 43 41 54 45 20 20 20  OERR_TRUNCATE   
50c0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
50d0: 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29 29 0a 23  OERR | (6<<8)).#
50e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
50f0: 45 52 52 5f 46 53 54 41 54 20 20 20 20 20 20 20  ERR_FSTAT       
5100: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5110: 45 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64  ERR | (7<<8)).#d
5120: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5130: 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20  RR_UNLOCK       
5140: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5150: 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65  RR | (8<<8)).#de
5160: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
5170: 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20 20 20  R_RDLOCK        
5180: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
5190: 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66  R | (9<<8)).#def
51a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
51b0: 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20  _DELETE         
51c0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
51d0: 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64 65 66   | (10<<8)).#def
51e0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
51f0: 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 20  _BLOCKED        
5200: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5210: 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64 65 66   | (11<<8)).#def
5220: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5230: 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 20 20  _NOMEM          
5240: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5250: 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64 65 66   | (12<<8)).#def
5260: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5270: 5f 41 43 43 45 53 53 20 20 20 20 20 20 20 20 20  _ACCESS         
5280: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5290: 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64 65 66   | (13<<8)).#def
52a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
52b0: 5f 43 48 45 43 4b 52 45 53 45 52 56 45 44 4c 4f  _CHECKRESERVEDLO
52c0: 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52  CK (SQLITE_IOERR
52d0: 20 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64 65 66   | (14<<8)).#def
52e0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
52f0: 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20  _LOCK           
5300: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5310: 20 7c 20 28 31 35 3c 3c 38 29 29 0a 23 64 65 66   | (15<<8)).#def
5320: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5330: 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20 20  _CLOSE          
5340: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5350: 20 7c 20 28 31 36 3c 3c 38 29 29 0a 23 64 65 66   | (16<<8)).#def
5360: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5370: 5f 44 49 52 5f 43 4c 4f 53 45 20 20 20 20 20 20  _DIR_CLOSE      
5380: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5390: 20 7c 20 28 31 37 3c 3c 38 29 29 0a 23 64 65 66   | (17<<8)).#def
53a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
53b0: 5f 53 48 4d 4f 50 45 4e 20 20 20 20 20 20 20 20  _SHMOPEN        
53c0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
53d0: 20 7c 20 28 31 38 3c 3c 38 29 29 0a 23 64 65 66   | (18<<8)).#def
53e0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
53f0: 5f 53 48 4d 53 49 5a 45 20 20 20 20 20 20 20 20  _SHMSIZE        
5400: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5410: 20 7c 20 28 31 39 3c 3c 38 29 29 0a 23 64 65 66   | (19<<8)).#def
5420: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5430: 5f 53 48 4d 4c 4f 43 4b 20 20 20 20 20 20 20 20  _SHMLOCK        
5440: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5450: 20 7c 20 28 32 30 3c 3c 38 29 29 0a 23 64 65 66   | (20<<8)).#def
5460: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5470: 5f 53 48 4d 4d 41 50 20 20 20 20 20 20 20 20 20  _SHMMAP         
5480: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5490: 20 7c 20 28 32 31 3c 3c 38 29 29 0a 23 64 65 66   | (21<<8)).#def
54a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
54b0: 5f 53 45 45 4b 20 20 20 20 20 20 20 20 20 20 20  _SEEK           
54c0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
54d0: 20 7c 20 28 32 32 3c 3c 38 29 29 0a 23 64 65 66   | (22<<8)).#def
54e0: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45  ine SQLITE_LOCKE
54f0: 44 5f 53 48 41 52 45 44 43 41 43 48 45 20 20 20  D_SHAREDCACHE   
5500: 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b 45     (SQLITE_LOCKE
5510: 44 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65  D |  (1<<8)).#de
5520: 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59  fine SQLITE_BUSY
5530: 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20 20 20  _RECOVERY       
5540: 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53 59      (SQLITE_BUSY
5550: 20 20 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64     |  (1<<8)).#d
5560: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e  efine SQLITE_CAN
5570: 54 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44 49 52 20  TOPEN_NOTEMPDIR 
5580: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e       (SQLITE_CAN
5590: 54 4f 50 45 4e 20 7c 20 28 31 3c 3c 38 29 29 0a  TOPEN | (1<<8)).
55a0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
55b0: 41 4e 54 4f 50 45 4e 5f 49 53 44 49 52 20 20 20  ANTOPEN_ISDIR   
55c0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43         (SQLITE_C
55d0: 41 4e 54 4f 50 45 4e 20 7c 20 28 32 3c 3c 38 29  ANTOPEN | (2<<8)
55e0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
55f0: 5f 43 41 4e 54 4f 50 45 4e 5f 46 55 4c 4c 50 41  _CANTOPEN_FULLPA
5600: 54 48 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  TH       (SQLITE
5610: 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 33 3c 3c  _CANTOPEN | (3<<
5620: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5630: 54 45 5f 43 4f 52 52 55 50 54 5f 56 54 41 42 20  TE_CORRUPT_VTAB 
5640: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
5650: 54 45 5f 43 4f 52 52 55 50 54 20 7c 20 28 31 3c  TE_CORRUPT | (1<
5660: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5670: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 52 45 43  ITE_READONLY_REC
5680: 4f 56 45 52 59 20 20 20 20 20 20 20 28 53 51 4c  OVERY       (SQL
5690: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28  ITE_READONLY | (
56a0: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
56b0: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 43  QLITE_READONLY_C
56c0: 41 4e 54 4c 4f 43 4b 20 20 20 20 20 20 20 28 53  ANTLOCK       (S
56d0: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c  QLITE_READONLY |
56e0: 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (2<<8)).#define
56f0: 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 5f 52 4f   SQLITE_ABORT_RO
5700: 4c 4c 42 41 43 4b 20 20 20 20 20 20 20 20 20 20  LLBACK          
5710: 28 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 7c 20  (SQLITE_ABORT | 
5720: 28 32 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43  (2<<8))../*.** C
5730: 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 46  API3REF: Flags F
5740: 6f 72 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65  or File Open Ope
5750: 72 61 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68  rations.**.** Th
5760: 65 73 65 20 62 69 74 20 76 61 6c 75 65 73 20 61  ese bit values a
5770: 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20  re intended for 
5780: 75 73 65 20 69 6e 20 74 68 65 0a 2a 2a 20 33 72  use in the.** 3r
5790: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
57a0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  he [sqlite3_open
57b0: 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65  _v2()] interface
57c0: 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20 34   and.** in the 4
57d0: 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
57e0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  the [sqlite3_vfs
57f0: 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 2e 0a  .xOpen] method..
5800: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5810: 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20  E_OPEN_READONLY 
5820: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
5830: 30 31 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  01  /* Ok for sq
5840: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
5850: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5860: 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
5870: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
5880: 30 32 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  02  /* Ok for sq
5890: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
58a0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
58b0: 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 20 20 20  E_OPEN_CREATE   
58c0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
58d0: 30 34 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  04  /* Ok for sq
58e0: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
58f0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5900: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43  E_OPEN_DELETEONC
5910: 4c 4f 53 45 20 20 20 20 30 78 30 30 30 30 30 30  LOSE    0x000000
5920: 30 38 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  08  /* VFS only 
5930: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5940: 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45  E_OPEN_EXCLUSIVE
5950: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
5960: 31 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  10  /* VFS only 
5970: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5980: 45 5f 4f 50 45 4e 5f 41 55 54 4f 50 52 4f 58 59  E_OPEN_AUTOPROXY
5990: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
59a0: 32 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  20  /* VFS only 
59b0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
59c0: 45 5f 4f 50 45 4e 5f 55 52 49 20 20 20 20 20 20  E_OPEN_URI      
59d0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
59e0: 34 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  40  /* Ok for sq
59f0: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
5a00: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5a10: 45 5f 4f 50 45 4e 5f 4d 45 4d 4f 52 59 20 20 20  E_OPEN_MEMORY   
5a20: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
5a30: 38 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  80  /* Ok for sq
5a40: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
5a50: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5a60: 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20 20  E_OPEN_MAIN_DB  
5a70: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 31          0x000001
5a80: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
5a90: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5aa0: 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20 20  E_OPEN_TEMP_DB  
5ab0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 32          0x000002
5ac0: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
5ad0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5ae0: 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54  E_OPEN_TRANSIENT
5af0: 5f 44 42 20 20 20 20 20 30 78 30 30 30 30 30 34  _DB     0x000004
5b00: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
5b10: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5b20: 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52  E_OPEN_MAIN_JOUR
5b30: 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 30 38  NAL     0x000008
5b40: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
5b50: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5b60: 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52  E_OPEN_TEMP_JOUR
5b70: 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 31 30  NAL     0x000010
5b80: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
5b90: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5ba0: 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41  E_OPEN_SUBJOURNA
5bb0: 4c 20 20 20 20 20 20 20 30 78 30 30 30 30 32 30  L       0x000020
5bc0: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
5bd0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5be0: 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f  E_OPEN_MASTER_JO
5bf0: 55 52 4e 41 4c 20 20 20 30 78 30 30 30 30 34 30  URNAL   0x000040
5c00: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
5c10: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5c20: 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 20 20  E_OPEN_NOMUTEX  
5c30: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 38 30          0x000080
5c40: 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  00  /* Ok for sq
5c50: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
5c60: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5c70: 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58  E_OPEN_FULLMUTEX
5c80: 20 20 20 20 20 20 20 20 30 78 30 30 30 31 30 30          0x000100
5c90: 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  00  /* Ok for sq
5ca0: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
5cb0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5cc0: 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43  E_OPEN_SHAREDCAC
5cd0: 48 45 20 20 20 20 20 20 30 78 30 30 30 32 30 30  HE      0x000200
5ce0: 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  00  /* Ok for sq
5cf0: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
5d00: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5d10: 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41  E_OPEN_PRIVATECA
5d20: 43 48 45 20 20 20 20 20 30 78 30 30 30 34 30 30  CHE     0x000400
5d30: 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  00  /* Ok for sq
5d40: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
5d50: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5d60: 45 5f 4f 50 45 4e 5f 57 41 4c 20 20 20 20 20 20  E_OPEN_WAL      
5d70: 20 20 20 20 20 20 20 20 30 78 30 30 30 38 30 30          0x000800
5d80: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
5d90: 2a 2f 0a 0a 2f 2a 20 52 65 73 65 72 76 65 64 3a  */../* Reserved:
5da0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
5db0: 20 20 20 20 20 20 20 20 20 30 78 30 30 46 30 30           0x00F00
5dc0: 30 30 30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  000 */../*.** CA
5dd0: 50 49 33 52 45 46 3a 20 44 65 76 69 63 65 20 43  PI3REF: Device C
5de0: 68 61 72 61 63 74 65 72 69 73 74 69 63 73 0a 2a  haracteristics.*
5df0: 2a 0a 2a 2a 20 54 68 65 20 78 44 65 76 69 63 65  *.** The xDevice
5e00: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20  Characteristics 
5e10: 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 5b 73  method of the [s
5e20: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
5e30: 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74  s].** object ret
5e40: 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20  urns an integer 
5e50: 77 68 69 63 68 20 69 73 20 61 20 76 65 63 74 6f  which is a vecto
5e60: 72 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 62 69  r of these.** bi
5e70: 74 20 76 61 6c 75 65 73 20 65 78 70 72 65 73 73  t values express
5e80: 69 6e 67 20 49 2f 4f 20 63 68 61 72 61 63 74 65  ing I/O characte
5e90: 72 69 73 74 69 63 73 20 6f 66 20 74 68 65 20 6d  ristics of the m
5ea0: 61 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20 64  ass storage.** d
5eb0: 65 76 69 63 65 20 74 68 61 74 20 68 6f 6c 64 73  evice that holds
5ec0: 20 74 68 65 20 66 69 6c 65 20 74 68 61 74 20 74   the file that t
5ed0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  he [sqlite3_io_m
5ee0: 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65 72  ethods].** refer
5ef0: 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  s to..**.** The 
5f00: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
5f10: 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61  MIC property mea
5f20: 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74  ns that all writ
5f30: 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a  es of.** any siz
5f40: 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54  e are atomic.  T
5f50: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
5f60: 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73  ATOMICnnn values
5f70: 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72  .** mean that wr
5f80: 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74  ites of blocks t
5f90: 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65  hat are nnn byte
5fa0: 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a  s in size and.**
5fb0: 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20   are aligned to 
5fc0: 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63 68  an address which
5fd0: 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d   is an integer m
5fe0: 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e  ultiple of.** nn
5ff0: 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54  n are atomic.  T
6000: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
6010: 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75  SAFE_APPEND valu
6020: 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20  e means.** that 
6030: 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70 70  when data is app
6040: 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c  ended to a file,
6050: 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70 70   the data is app
6060: 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74  ended.** first t
6070: 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20  hen the size of 
6080: 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74 65  the file is exte
6090: 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20  nded, never the 
60a0: 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f  other.** way aro
60b0: 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45  und.  The SQLITE
60c0: 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41  _IOCAP_SEQUENTIA
60d0: 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73  L property means
60e0: 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61   that.** informa
60f0: 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20  tion is written 
6100: 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73  to disk in the s
6110: 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c  ame order as cal
6120: 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28  ls.** to xWrite(
6130: 29 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  ).  The SQLITE_I
6140: 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f  OCAP_POWERSAFE_O
6150: 56 45 52 57 52 49 54 45 20 70 72 6f 70 65 72 74  VERWRITE propert
6160: 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20  y means that.** 
6170: 61 66 74 65 72 20 72 65 62 6f 6f 74 20 66 6f 6c  after reboot fol
6180: 6c 6f 77 69 6e 67 20 61 20 63 72 61 73 68 20 6f  lowing a crash o
6190: 72 20 70 6f 77 65 72 20 6c 6f 73 73 2c 20 74 68  r power loss, th
61a0: 65 20 6f 6e 6c 79 20 62 79 74 65 73 20 69 6e 20  e only bytes in 
61b0: 61 0a 2a 2a 20 66 69 6c 65 20 74 68 61 74 20 77  a.** file that w
61c0: 65 72 65 20 77 72 69 74 74 65 6e 20 61 74 20 74  ere written at t
61d0: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6c  he application l
61e0: 65 76 65 6c 20 6d 69 67 68 74 20 68 61 76 65 20  evel might have 
61f0: 63 68 61 6e 67 65 64 0a 2a 2a 20 61 6e 64 20 74  changed.** and t
6200: 68 61 74 20 61 64 6a 61 63 65 6e 74 20 62 79 74  hat adjacent byt
6210: 65 73 2c 20 65 76 65 6e 20 62 79 74 65 73 20 77  es, even bytes w
6220: 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20 73  ithin the same s
6230: 65 63 74 6f 72 20 61 72 65 0a 2a 2a 20 67 75 61  ector are.** gua
6240: 72 61 6e 74 65 65 64 20 74 6f 20 62 65 20 75 6e  ranteed to be un
6250: 63 68 61 6e 67 65 64 2e 0a 2a 2f 0a 23 64 65 66  changed..*/.#def
6260: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
6270: 5f 41 54 4f 4d 49 43 20 20 20 20 20 20 20 20 20  _ATOMIC         
6280: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
6290: 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  01.#define SQLIT
62a0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31  E_IOCAP_ATOMIC51
62b0: 32 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30  2              0
62c0: 78 30 30 30 30 30 30 30 32 0a 23 64 65 66 69 6e  x00000002.#defin
62d0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
62e0: 54 4f 4d 49 43 31 4b 20 20 20 20 20 20 20 20 20  TOMIC1K         
62f0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 34        0x00000004
6300: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6310: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 20 20  IOCAP_ATOMIC2K  
6320: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
6330: 30 30 30 30 30 30 38 0a 23 64 65 66 69 6e 65 20  0000008.#define 
6340: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
6350: 4d 49 43 34 4b 20 20 20 20 20 20 20 20 20 20 20  MIC4K           
6360: 20 20 20 20 30 78 30 30 30 30 30 30 31 30 0a 23      0x00000010.#
6370: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
6380: 43 41 50 5f 41 54 4f 4d 49 43 38 4b 20 20 20 20  CAP_ATOMIC8K    
6390: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
63a0: 30 30 30 32 30 0a 23 64 65 66 69 6e 65 20 53 51  00020.#define SQ
63b0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
63c0: 43 31 36 4b 20 20 20 20 20 20 20 20 20 20 20 20  C16K            
63d0: 20 20 30 78 30 30 30 30 30 30 34 30 0a 23 64 65    0x00000040.#de
63e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
63f0: 50 5f 41 54 4f 4d 49 43 33 32 4b 20 20 20 20 20  P_ATOMIC32K     
6400: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6410: 30 38 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  080.#define SQLI
6420: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36  TE_IOCAP_ATOMIC6
6430: 34 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  4K              
6440: 30 78 30 30 30 30 30 31 30 30 0a 23 64 65 66 69  0x00000100.#defi
6450: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
6460: 53 41 46 45 5f 41 50 50 45 4e 44 20 20 20 20 20  SAFE_APPEND     
6470: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 32 30         0x0000020
6480: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
6490: 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41  _IOCAP_SEQUENTIA
64a0: 4c 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78  L             0x
64b0: 30 30 30 30 30 34 30 30 0a 23 64 65 66 69 6e 65  00000400.#define
64c0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e   SQLITE_IOCAP_UN
64d0: 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f  DELETABLE_WHEN_O
64e0: 50 45 4e 20 20 30 78 30 30 30 30 30 38 30 30 0a  PEN  0x00000800.
64f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
6500: 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f  OCAP_POWERSAFE_O
6510: 56 45 52 57 52 49 54 45 20 20 20 20 30 78 30 30  VERWRITE    0x00
6520: 30 30 31 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41  001000../*.** CA
6530: 50 49 33 52 45 46 3a 20 46 69 6c 65 20 4c 6f 63  PI3REF: File Loc
6540: 6b 69 6e 67 20 4c 65 76 65 6c 73 0a 2a 2a 0a 2a  king Levels.**.*
6550: 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 6f 6e  * SQLite uses on
6560: 65 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65 67  e of these integ
6570: 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68 65  er values as the
6580: 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d   second.** argum
6590: 65 6e 74 20 74 6f 20 63 61 6c 6c 73 20 69 74 20  ent to calls it 
65a0: 6d 61 6b 65 73 20 74 6f 20 74 68 65 20 78 4c 6f  makes to the xLo
65b0: 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b  ck() and xUnlock
65c0: 28 29 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f 66  () methods.** of
65d0: 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f   an [sqlite3_io_
65e0: 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e  methods] object.
65f0: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
6600: 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20 20  TE_LOCK_NONE    
6610: 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20        0.#define 
6620: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52  SQLITE_LOCK_SHAR
6630: 45 44 20 20 20 20 20 20 20 20 31 0a 23 64 65 66  ED        1.#def
6640: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ine SQLITE_LOCK_
6650: 52 45 53 45 52 56 45 44 20 20 20 20 20 20 32 0a  RESERVED      2.
6660: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
6670: 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 20 20 20 20  OCK_PENDING     
6680: 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    3.#define SQLI
6690: 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56  TE_LOCK_EXCLUSIV
66a0: 45 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43  E     4../*.** C
66b0: 41 50 49 33 52 45 46 3a 20 53 79 6e 63 68 72 6f  API3REF: Synchro
66c0: 6e 69 7a 61 74 69 6f 6e 20 54 79 70 65 20 46 6c  nization Type Fl
66d0: 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53  ags.**.** When S
66e0: 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20 74 68  QLite invokes th
66f0: 65 20 78 53 79 6e 63 28 29 20 6d 65 74 68 6f 64  e xSync() method
6700: 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74   of an.** [sqlit
6710: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f  e3_io_methods] o
6720: 62 6a 65 63 74 20 69 74 20 75 73 65 73 20 61 20  bject it uses a 
6730: 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a  combination of.*
6740: 2a 20 74 68 65 73 65 20 69 6e 74 65 67 65 72 20  * these integer 
6750: 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 73 65  values as the se
6760: 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  cond argument..*
6770: 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 53 51  *.** When the SQ
6780: 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e  LITE_SYNC_DATAON
6790: 4c 59 20 66 6c 61 67 20 69 73 20 75 73 65 64 2c  LY flag is used,
67a0: 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74   it means that t
67b0: 68 65 0a 2a 2a 20 73 79 6e 63 20 6f 70 65 72 61  he.** sync opera
67c0: 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64 73 20  tion only needs 
67d0: 74 6f 20 66 6c 75 73 68 20 64 61 74 61 20 74 6f  to flush data to
67e0: 20 6d 61 73 73 20 73 74 6f 72 61 67 65 2e 20 20   mass storage.  
67f0: 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61  Inode.** informa
6800: 74 69 6f 6e 20 6e 65 65 64 20 6e 6f 74 20 62 65  tion need not be
6810: 20 66 6c 75 73 68 65 64 2e 20 49 66 20 74 68 65   flushed. If the
6820: 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74 73   lower four bits
6830: 20 6f 66 20 74 68 65 20 66 6c 61 67 0a 2a 2a 20   of the flag.** 
6840: 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e  equal SQLITE_SYN
6850: 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68 61 74 20 6d  C_NORMAL, that m
6860: 65 61 6e 73 20 74 6f 20 75 73 65 20 6e 6f 72 6d  eans to use norm
6870: 61 6c 20 66 73 79 6e 63 28 29 20 73 65 6d 61 6e  al fsync() seman
6880: 74 69 63 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20  tics..** If the 
6890: 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74 73 20  lower four bits 
68a0: 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e  equal SQLITE_SYN
68b0: 43 5f 46 55 4c 4c 2c 20 74 68 61 74 20 6d 65 61  C_FULL, that mea
68c0: 6e 73 0a 2a 2a 20 74 6f 20 75 73 65 20 4d 61 63  ns.** to use Mac
68d0: 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c   OS X style full
68e0: 73 79 6e 63 20 69 6e 73 74 65 61 64 20 6f 66 20  sync instead of 
68f0: 66 73 79 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 44  fsync()..**.** D
6900: 6f 20 6e 6f 74 20 63 6f 6e 66 75 73 65 20 74 68  o not confuse th
6910: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f  e SQLITE_SYNC_NO
6920: 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f  RMAL and SQLITE_
6930: 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 73 0a  SYNC_FULL flags.
6940: 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 50 52 41  ** with the [PRA
6950: 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d  GMA synchronous]
6960: 3d 4e 4f 52 4d 41 4c 20 61 6e 64 20 5b 50 52 41  =NORMAL and [PRA
6970: 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d  GMA synchronous]
6980: 3d 46 55 4c 4c 0a 2a 2a 20 73 65 74 74 69 6e 67  =FULL.** setting
6990: 73 2e 20 20 54 68 65 20 5b 73 79 6e 63 68 72 6f  s.  The [synchro
69a0: 6e 6f 75 73 20 70 72 61 67 6d 61 5d 20 64 65 74  nous pragma] det
69b0: 65 72 6d 69 6e 65 73 20 77 68 65 6e 20 63 61 6c  ermines when cal
69c0: 6c 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53 79  ls to the.** xSy
69d0: 6e 63 20 56 46 53 20 6d 65 74 68 6f 64 20 6f 63  nc VFS method oc
69e0: 63 75 72 20 61 6e 64 20 61 70 70 6c 69 65 73 20  cur and applies 
69f0: 75 6e 69 66 6f 72 6d 6c 79 20 61 63 72 6f 73 73  uniformly across
6a00: 20 61 6c 6c 20 70 6c 61 74 66 6f 72 6d 73 2e 0a   all platforms..
6a10: 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 53 59  ** The SQLITE_SY
6a20: 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51  NC_NORMAL and SQ
6a30: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66  LITE_SYNC_FULL f
6a40: 6c 61 67 73 20 64 65 74 65 72 6d 69 6e 65 20 68  lags determine h
6a50: 6f 77 0a 2a 2a 20 65 6e 65 72 67 65 74 69 63 20  ow.** energetic 
6a60: 6f 72 20 72 69 67 6f 72 6f 75 73 20 6f 72 20 66  or rigorous or f
6a70: 6f 72 63 65 66 75 6c 20 74 68 65 20 73 79 6e 63  orceful the sync
6a80: 20 6f 70 65 72 61 74 69 6f 6e 73 20 61 72 65 20   operations are 
6a90: 61 6e 64 0a 2a 2a 20 6f 6e 6c 79 20 6d 61 6b 65  and.** only make
6aa0: 20 61 20 64 69 66 66 65 72 65 6e 63 65 20 6f 6e   a difference on
6ab0: 20 4d 61 63 20 4f 53 58 20 66 6f 72 20 74 68 65   Mac OSX for the
6ac0: 20 64 65 66 61 75 6c 74 20 53 51 4c 69 74 65 20   default SQLite 
6ad0: 63 6f 64 65 2e 0a 2a 2a 20 28 54 68 69 72 64 2d  code..** (Third-
6ae0: 70 61 72 74 79 20 56 46 53 20 69 6d 70 6c 65 6d  party VFS implem
6af0: 65 6e 74 61 74 69 6f 6e 73 20 6d 69 67 68 74 20  entations might 
6b00: 61 6c 73 6f 20 6d 61 6b 65 20 74 68 65 20 64 69  also make the di
6b10: 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65 74  stinction.** bet
6b20: 77 65 65 6e 20 53 51 4c 49 54 45 5f 53 59 4e 43  ween SQLITE_SYNC
6b30: 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49  _NORMAL and SQLI
6b40: 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 62 75  TE_SYNC_FULL, bu
6b50: 74 20 61 6d 6f 6e 67 20 74 68 65 0a 2a 2a 20 6f  t among the.** o
6b60: 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 73  perating systems
6b70: 20 6e 61 74 69 76 65 6c 79 20 73 75 70 70 6f 72   natively suppor
6b80: 74 65 64 20 62 79 20 53 51 4c 69 74 65 2c 20 6f  ted by SQLite, o
6b90: 6e 6c 79 20 4d 61 63 20 4f 53 58 0a 2a 2a 20 63  nly Mac OSX.** c
6ba0: 61 72 65 73 20 61 62 6f 75 74 20 74 68 65 20 64  ares about the d
6bb0: 69 66 66 65 72 65 6e 63 65 2e 29 0a 2a 2f 0a 23  ifference.).*/.#
6bc0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59  define SQLITE_SY
6bd0: 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20 20  NC_NORMAL       
6be0: 20 30 78 30 30 30 30 32 0a 23 64 65 66 69 6e 65   0x00002.#define
6bf0: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c   SQLITE_SYNC_FUL
6c00: 4c 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30  L          0x000
6c10: 30 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  03.#define SQLIT
6c20: 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20  E_SYNC_DATAONLY 
6c30: 20 20 20 20 20 30 78 30 30 30 31 30 0a 0a 2f 2a       0x00010../*
6c40: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53  .** CAPI3REF: OS
6c50: 20 49 6e 74 65 72 66 61 63 65 20 4f 70 65 6e 20   Interface Open 
6c60: 46 69 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a  File Handle.**.*
6c70: 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69  * An [sqlite3_fi
6c80: 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65 70 72 65  le] object repre
6c90: 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20 66 69  sents an open fi
6ca0: 6c 65 20 69 6e 20 74 68 65 20 0a 2a 2a 20 5b 73  le in the .** [s
6cb0: 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 4f 53 20  qlite3_vfs | OS 
6cc0: 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72 5d  interface layer]
6cd0: 2e 20 20 49 6e 64 69 76 69 64 75 61 6c 20 4f 53  .  Individual OS
6ce0: 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69 6d   interface.** im
6cf0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69  plementations wi
6d00: 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 73 75  ll.** want to su
6d10: 62 63 6c 61 73 73 20 74 68 69 73 20 6f 62 6a 65  bclass this obje
6d20: 63 74 20 62 79 20 61 70 70 65 6e 64 69 6e 67 20  ct by appending 
6d30: 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64  additional field
6d40: 73 0a 2a 2a 20 66 6f 72 20 74 68 65 69 72 20 6f  s.** for their o
6d50: 77 6e 20 75 73 65 2e 20 20 54 68 65 20 70 4d 65  wn use.  The pMe
6d60: 74 68 6f 64 73 20 65 6e 74 72 79 20 69 73 20 61  thods entry is a
6d70: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a   pointer to an.*
6d80: 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  * [sqlite3_io_me
6d90: 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 74 68  thods] object th
6da0: 61 74 20 64 65 66 69 6e 65 73 20 6d 65 74 68 6f  at defines metho
6db0: 64 73 20 66 6f 72 20 70 65 72 66 6f 72 6d 69 6e  ds for performin
6dc0: 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72 61 74 69  g.** I/O operati
6dd0: 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70 65 6e 20  ons on the open 
6de0: 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  file..*/.typedef
6df0: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
6e00: 66 69 6c 65 20 73 71 6c 69 74 65 33 5f 66 69 6c  file sqlite3_fil
6e10: 65 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65  e;.struct sqlite
6e20: 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f 6e 73 74  3_file {.  const
6e30: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
6e40: 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70 4d 65 74  io_methods *pMet
6e50: 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74 68 6f 64  hods;  /* Method
6e60: 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e 20 66 69  s for an open fi
6e70: 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20  le */.};../*.** 
6e80: 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74  CAPI3REF: OS Int
6e90: 65 72 66 61 63 65 20 46 69 6c 65 20 56 69 72 74  erface File Virt
6ea0: 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f 62 6a 65  ual Methods Obje
6eb0: 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 66  ct.**.** Every f
6ec0: 69 6c 65 20 6f 70 65 6e 65 64 20 62 79 20 74 68  ile opened by th
6ed0: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78  e [sqlite3_vfs.x
6ee0: 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20 70 6f 70  Open] method pop
6ef0: 75 6c 61 74 65 73 20 61 6e 0a 2a 2a 20 5b 73 71  ulates an.** [sq
6f00: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
6f10: 63 74 20 28 6f 72 2c 20 6d 6f 72 65 20 63 6f 6d  ct (or, more com
6f20: 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 63 6c 61 73  monly, a subclas
6f30: 73 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  s of the.** [sql
6f40: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63  ite3_file] objec
6f50: 74 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65  t) with a pointe
6f60: 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65  r to an instance
6f70: 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 2e   of this object.
6f80: 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20  .** This object 
6f90: 64 65 66 69 6e 65 73 20 74 68 65 20 6d 65 74 68  defines the meth
6fa0: 6f 64 73 20 75 73 65 64 20 74 6f 20 70 65 72 66  ods used to perf
6fb0: 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f 70 65 72  orm various oper
6fc0: 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e 73  ations.** agains
6fd0: 74 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 20  t the open file 
6fe0: 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20 74  represented by t
6ff0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  he [sqlite3_file
7000: 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20  ] object..**.** 
7010: 49 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  If the [sqlite3_
7020: 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f  vfs.xOpen] metho
7030: 64 20 73 65 74 73 20 74 68 65 20 73 71 6c 69 74  d sets the sqlit
7040: 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73  e3_file.pMethods
7050: 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20 74 6f 20   element .** to 
7060: 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74  a non-NULL point
7070: 65 72 2c 20 74 68 65 6e 20 74 68 65 20 73 71 6c  er, then the sql
7080: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 2e  ite3_io_methods.
7090: 78 43 6c 6f 73 65 20 6d 65 74 68 6f 64 0a 2a 2a  xClose method.**
70a0: 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65 64 20   may be invoked 
70b0: 65 76 65 6e 20 69 66 20 74 68 65 20 5b 73 71 6c  even if the [sql
70c0: 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20  ite3_vfs.xOpen] 
70d0: 72 65 70 6f 72 74 65 64 20 74 68 61 74 20 69 74  reported that it
70e0: 20 66 61 69 6c 65 64 2e 20 20 54 68 65 0a 2a 2a   failed.  The.**
70f0: 20 6f 6e 6c 79 20 77 61 79 20 74 6f 20 70 72 65   only way to pre
7100: 76 65 6e 74 20 61 20 63 61 6c 6c 20 74 6f 20 78  vent a call to x
7110: 43 6c 6f 73 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  Close following 
7120: 61 20 66 61 69 6c 65 64 20 5b 73 71 6c 69 74 65  a failed [sqlite
7130: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 0a 2a 2a 20  3_vfs.xOpen].** 
7140: 69 73 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69  is for the [sqli
7150: 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 74  te3_vfs.xOpen] t
7160: 6f 20 73 65 74 20 74 68 65 20 73 71 6c 69 74 65  o set the sqlite
7170: 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20  3_file.pMethods 
7180: 65 6c 65 6d 65 6e 74 0a 2a 2a 20 74 6f 20 4e 55  element.** to NU
7190: 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c  LL..**.** The fl
71a0: 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ags argument to 
71b0: 78 53 79 6e 63 20 6d 61 79 20 62 65 20 6f 6e 65  xSync may be one
71c0: 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43   of [SQLITE_SYNC
71d0: 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20 5b  _NORMAL] or.** [
71e0: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c  SQLITE_SYNC_FULL
71f0: 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20 63 68  ].  The first ch
7200: 6f 69 63 65 20 69 73 20 74 68 65 20 6e 6f 72 6d  oice is the norm
7210: 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 20 54  al fsync()..** T
7220: 68 65 20 73 65 63 6f 6e 64 20 63 68 6f 69 63 65  he second choice
7230: 20 69 73 20 61 20 4d 61 63 20 4f 53 20 58 20 73   is a Mac OS X s
7240: 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 2e 20 20  tyle fullsync.  
7250: 54 68 65 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43  The [SQLITE_SYNC
7260: 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66 6c  _DATAONLY].** fl
7270: 61 67 20 6d 61 79 20 62 65 20 4f 52 65 64 20 69  ag may be ORed i
7280: 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68  n to indicate th
7290: 61 74 20 6f 6e 6c 79 20 74 68 65 20 64 61 74 61  at only the data
72a0: 20 6f 66 20 74 68 65 20 66 69 6c 65 0a 2a 2a 20   of the file.** 
72b0: 61 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e 6f 64  and not its inod
72c0: 65 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73 79  e needs to be sy
72d0: 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  nced..**.** The 
72e0: 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 74  integer values t
72f0: 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55  o xLock() and xU
7300: 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f 6e 65 20  nlock() are one 
7310: 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  of.** <ul>.** <l
7320: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
7330: 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b  NONE],.** <li> [
7340: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52  SQLITE_LOCK_SHAR
7350: 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  ED],.** <li> [SQ
7360: 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56  LITE_LOCK_RESERV
7370: 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  ED],.** <li> [SQ
7380: 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e  LITE_LOCK_PENDIN
7390: 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b  G], or.** <li> [
73a0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c  SQLITE_LOCK_EXCL
73b0: 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e  USIVE]..** </ul>
73c0: 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 6e 63 72  .** xLock() incr
73d0: 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 20  eases the lock. 
73e0: 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63 72 65 61  xUnlock() decrea
73f0: 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a  ses the lock..**
7400: 20 54 68 65 20 78 43 68 65 63 6b 52 65 73 65 72   The xCheckReser
7410: 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74 68 6f 64  vedLock() method
7420: 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20   checks whether 
7430: 61 6e 79 20 64 61 74 61 62 61 73 65 20 63 6f 6e  any database con
7440: 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74 68  nection,.** eith
7450: 65 72 20 69 6e 20 74 68 69 73 20 70 72 6f 63 65  er in this proce
7460: 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65 20 6f 74  ss or in some ot
7470: 68 65 72 20 70 72 6f 63 65 73 73 2c 20 69 73 20  her process, is 
7480: 68 6f 6c 64 69 6e 67 20 61 20 52 45 53 45 52 56  holding a RESERV
7490: 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c 20  ED,.** PENDING, 
74a0: 6f 72 20 45 58 43 4c 55 53 49 56 45 20 6c 6f 63  or EXCLUSIVE loc
74b0: 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65 2e 20 20  k on the file.  
74c0: 49 74 20 72 65 74 75 72 6e 73 20 74 72 75 65 0a  It returns true.
74d0: 2a 2a 20 69 66 20 73 75 63 68 20 61 20 6c 6f 63  ** if such a loc
74e0: 6b 20 65 78 69 73 74 73 20 61 6e 64 20 66 61 6c  k exists and fal
74f0: 73 65 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a  se otherwise..**
7500: 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65 43 6f 6e  .** The xFileCon
7510: 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64 20 69 73  trol() method is
7520: 20 61 20 67 65 6e 65 72 69 63 20 69 6e 74 65 72   a generic inter
7530: 66 61 63 65 20 74 68 61 74 20 61 6c 6c 6f 77 73  face that allows
7540: 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 53 20 69   custom.** VFS i
7550: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 74  mplementations t
7560: 6f 20 64 69 72 65 63 74 6c 79 20 63 6f 6e 74 72  o directly contr
7570: 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20  ol an open file 
7580: 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71  using the.** [sq
7590: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
75a0: 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  ol()] interface.
75b0: 20 20 54 68 65 20 73 65 63 6f 6e 64 20 22 6f 70    The second "op
75c0: 22 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e  " argument is an
75d0: 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6f 70 63 6f  .** integer opco
75e0: 64 65 2e 20 20 54 68 65 20 74 68 69 72 64 20 61  de.  The third a
75f0: 72 67 75 6d 65 6e 74 20 69 73 20 61 20 67 65 6e  rgument is a gen
7600: 65 72 69 63 20 70 6f 69 6e 74 65 72 20 69 6e 74  eric pointer int
7610: 65 6e 64 65 64 20 74 6f 0a 2a 2a 20 70 6f 69 6e  ended to.** poin
7620: 74 20 74 6f 20 61 20 73 74 72 75 63 74 75 72 65  t to a structure
7630: 20 74 68 61 74 20 6d 61 79 20 63 6f 6e 74 61 69   that may contai
7640: 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 73  n arguments or s
7650: 70 61 63 65 20 69 6e 20 77 68 69 63 68 20 74 6f  pace in which to
7660: 0a 2a 2a 20 77 72 69 74 65 20 72 65 74 75 72 6e  .** write return
7670: 20 76 61 6c 75 65 73 2e 20 20 50 6f 74 65 6e 74   values.  Potent
7680: 69 61 6c 20 75 73 65 73 20 66 6f 72 20 78 46 69  ial uses for xFi
7690: 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 67 68  leControl() migh
76a0: 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  t be.** function
76b0: 73 20 74 6f 20 65 6e 61 62 6c 65 20 62 6c 6f 63  s to enable bloc
76c0: 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69 74 68 20  king locks with 
76d0: 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20 63 68 61  timeouts, to cha
76e0: 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69  nge the.** locki
76f0: 6e 67 20 73 74 72 61 74 65 67 79 20 28 66 6f 72  ng strategy (for
7700: 20 65 78 61 6d 70 6c 65 20 74 6f 20 75 73 65 20   example to use 
7710: 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 29 2c  dot-file locks),
7720: 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a 2a 20 61   to inquire.** a
7730: 62 6f 75 74 20 74 68 65 20 73 74 61 74 75 73 20  bout the status 
7740: 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f  of a lock, or to
7750: 20 62 72 65 61 6b 20 73 74 61 6c 65 20 6c 6f 63   break stale loc
7760: 6b 73 2e 20 20 54 68 65 20 53 51 4c 69 74 65 0a  ks.  The SQLite.
7770: 2a 2a 20 63 6f 72 65 20 72 65 73 65 72 76 65 73  ** core reserves
7780: 20 61 6c 6c 20 6f 70 63 6f 64 65 73 20 6c 65 73   all opcodes les
7790: 73 20 74 68 61 6e 20 31 30 30 20 66 6f 72 20 69  s than 100 for i
77a0: 74 73 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20 41  ts own use..** A
77b0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c   [SQLITE_FCNTL_L
77c0: 4f 43 4b 53 54 41 54 45 20 7c 20 6c 69 73 74 20  OCKSTATE | list 
77d0: 6f 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65 73 73  of opcodes] less
77e0: 20 74 68 61 6e 20 31 30 30 20 69 73 20 61 76 61   than 100 is ava
77f0: 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69  ilable..** Appli
7800: 63 61 74 69 6f 6e 73 20 74 68 61 74 20 64 65 66  cations that def
7810: 69 6e 65 20 61 20 63 75 73 74 6f 6d 20 78 46 69  ine a custom xFi
7820: 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64  leControl method
7830: 20 73 68 6f 75 6c 64 20 75 73 65 20 6f 70 63 6f   should use opco
7840: 64 65 73 0a 2a 2a 20 67 72 65 61 74 65 72 20 74  des.** greater t
7850: 68 61 6e 20 31 30 30 20 74 6f 20 61 76 6f 69 64  han 100 to avoid
7860: 20 63 6f 6e 66 6c 69 63 74 73 2e 20 20 56 46 53   conflicts.  VFS
7870: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
7880: 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72   should.** retur
7890: 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55  n [SQLITE_NOTFOU
78a0: 4e 44 5d 20 66 6f 72 20 66 69 6c 65 20 63 6f 6e  ND] for file con
78b0: 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20 74 68 61  trol opcodes tha
78c0: 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a  t they do not.**
78d0: 20 72 65 63 6f 67 6e 69 7a 65 2e 0a 2a 2a 0a 2a   recognize..**.*
78e0: 2a 20 54 68 65 20 78 53 65 63 74 6f 72 53 69 7a  * The xSectorSiz
78f0: 65 28 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72  e() method retur
7900: 6e 73 20 74 68 65 20 73 65 63 74 6f 72 20 73 69  ns the sector si
7910: 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20 64 65 76  ze of the.** dev
7920: 69 63 65 20 74 68 61 74 20 75 6e 64 65 72 6c 69  ice that underli
7930: 65 73 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68  es the file.  Th
7940: 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20 69 73  e sector size is
7950: 20 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20   the.** minimum 
7960: 77 72 69 74 65 20 74 68 61 74 20 63 61 6e 20 62  write that can b
7970: 65 20 70 65 72 66 6f 72 6d 65 64 20 77 69 74 68  e performed with
7980: 6f 75 74 20 64 69 73 74 75 72 62 69 6e 67 0a 2a  out disturbing.*
7990: 2a 20 6f 74 68 65 72 20 62 79 74 65 73 20 69 6e  * other bytes in
79a0: 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20   the file.  The 
79b0: 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72  xDeviceCharacter
79c0: 69 73 74 69 63 73 28 29 0a 2a 2a 20 6d 65 74 68  istics().** meth
79d0: 6f 64 20 72 65 74 75 72 6e 73 20 61 20 62 69 74  od returns a bit
79e0: 20 76 65 63 74 6f 72 20 64 65 73 63 72 69 62 69   vector describi
79f0: 6e 67 20 62 65 68 61 76 69 6f 72 73 20 6f 66 20  ng behaviors of 
7a00: 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e  the.** underlyin
7a10: 67 20 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20  g device:.**.** 
7a20: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  <ul>.** <li> [SQ
7a30: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
7a40: 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  C].** <li> [SQLI
7a50: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35  TE_IOCAP_ATOMIC5
7a60: 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  12].** <li> [SQL
7a70: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
7a80: 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  1K].** <li> [SQL
7a90: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
7aa0: 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  2K].** <li> [SQL
7ab0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
7ac0: 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  4K].** <li> [SQL
7ad0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
7ae0: 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  8K].** <li> [SQL
7af0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
7b00: 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  16K].** <li> [SQ
7b10: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
7b20: 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  C32K].** <li> [S
7b30: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
7b40: 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  IC64K].** <li> [
7b50: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46  SQLITE_IOCAP_SAF
7b60: 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69  E_APPEND].** <li
7b70: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
7b80: 53 45 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c  SEQUENTIAL].** <
7b90: 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53  /ul>.**.** The S
7ba0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
7bb0: 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e  IC property mean
7bc0: 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65  s that all write
7bd0: 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65  s of.** any size
7be0: 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68   are atomic.  Th
7bf0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
7c00: 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a  TOMICnnn values.
7c10: 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69  ** mean that wri
7c20: 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68  tes of blocks th
7c30: 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73  at are nnn bytes
7c40: 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20   in size and.** 
7c50: 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61  are aligned to a
7c60: 6e 20 61 64 64 72 65 73 73 20 77 68 69 63 68 20  n address which 
7c70: 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75  is an integer mu
7c80: 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e  ltiple of.** nnn
7c90: 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68   are atomic.  Th
7ca0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53  e SQLITE_IOCAP_S
7cb0: 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65  AFE_APPEND value
7cc0: 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77   means.** that w
7cd0: 68 65 6e 20 64 61 74 61 20 69 73 20 61 70 70 65  hen data is appe
7ce0: 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20  nded to a file, 
7cf0: 74 68 65 20 64 61 74 61 20 69 73 20 61 70 70 65  the data is appe
7d00: 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68  nded.** first th
7d10: 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  en the size of t
7d20: 68 65 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e  he file is exten
7d30: 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f  ded, never the o
7d40: 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75  ther.** way arou
7d50: 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  nd.  The SQLITE_
7d60: 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c  IOCAP_SEQUENTIAL
7d70: 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20   property means 
7d80: 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74  that.** informat
7d90: 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74  ion is written t
7da0: 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61  o disk in the sa
7db0: 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c  me order as call
7dc0: 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29  s.** to xWrite()
7dd0: 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 78 52 65 61 64  ..**.** If xRead
7de0: 28 29 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54  () returns SQLIT
7df0: 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45  E_IOERR_SHORT_RE
7e00: 41 44 20 69 74 20 6d 75 73 74 20 61 6c 73 6f 20  AD it must also 
7e10: 66 69 6c 6c 0a 2a 2a 20 69 6e 20 74 68 65 20 75  fill.** in the u
7e20: 6e 72 65 61 64 20 70 6f 72 74 69 6f 6e 73 20 6f  nread portions o
7e30: 66 20 74 68 65 20 62 75 66 66 65 72 20 77 69 74  f the buffer wit
7e40: 68 20 7a 65 72 6f 73 2e 20 20 41 20 56 46 53 20  h zeros.  A VFS 
7e50: 74 68 61 74 0a 2a 2a 20 66 61 69 6c 73 20 74 6f  that.** fails to
7e60: 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74   zero-fill short
7e70: 20 72 65 61 64 73 20 6d 69 67 68 74 20 73 65 65   reads might see
7e80: 6d 20 74 6f 20 77 6f 72 6b 2e 20 20 48 6f 77 65  m to work.  Howe
7e90: 76 65 72 2c 0a 2a 2a 20 66 61 69 6c 75 72 65 20  ver,.** failure 
7ea0: 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f  to zero-fill sho
7eb0: 72 74 20 72 65 61 64 73 20 77 69 6c 6c 20 65 76  rt reads will ev
7ec0: 65 6e 74 75 61 6c 6c 79 20 6c 65 61 64 20 74 6f  entually lead to
7ed0: 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 72  .** database cor
7ee0: 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65  ruption..*/.type
7ef0: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
7f00: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 73 71  e3_io_methods sq
7f10: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
7f20: 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  ;.struct sqlite3
7f30: 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20  _io_methods {.  
7f40: 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20  int iVersion;.  
7f50: 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28 73 71  int (*xClose)(sq
7f60: 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20  lite3_file*);.  
7f70: 69 6e 74 20 28 2a 78 52 65 61 64 29 28 73 71 6c  int (*xRead)(sql
7f80: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 76 6f 69 64  ite3_file*, void
7f90: 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c  *, int iAmt, sql
7fa0: 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74  ite3_int64 iOfst
7fb0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 57 72 69 74  );.  int (*xWrit
7fc0: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e)(sqlite3_file*
7fd0: 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
7fe0: 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33  nt iAmt, sqlite3
7ff0: 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20  _int64 iOfst);. 
8000: 20 69 6e 74 20 28 2a 78 54 72 75 6e 63 61 74 65   int (*xTruncate
8010: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
8020: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73   sqlite3_int64 s
8030: 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53  ize);.  int (*xS
8040: 79 6e 63 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ync)(sqlite3_fil
8050: 65 2a 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a  e*, int flags);.
8060: 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 53 69 7a    int (*xFileSiz
8070: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e)(sqlite3_file*
8080: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
8090: 2a 70 53 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28  *pSize);.  int (
80a0: 2a 78 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f  *xLock)(sqlite3_
80b0: 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69  file*, int);.  i
80c0: 6e 74 20 28 2a 78 55 6e 6c 6f 63 6b 29 28 73 71  nt (*xUnlock)(sq
80d0: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
80e0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 68 65 63  );.  int (*xChec
80f0: 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 29 28 73  kReservedLock)(s
8100: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
8110: 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69  t *pResOut);.  i
8120: 6e 74 20 28 2a 78 46 69 6c 65 43 6f 6e 74 72 6f  nt (*xFileContro
8130: 6c 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  l)(sqlite3_file*
8140: 2c 20 69 6e 74 20 6f 70 2c 20 76 6f 69 64 20 2a  , int op, void *
8150: 70 41 72 67 29 3b 0a 20 20 69 6e 74 20 28 2a 78  pArg);.  int (*x
8160: 53 65 63 74 6f 72 53 69 7a 65 29 28 73 71 6c 69  SectorSize)(sqli
8170: 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e  te3_file*);.  in
8180: 74 20 28 2a 78 44 65 76 69 63 65 43 68 61 72 61  t (*xDeviceChara
8190: 63 74 65 72 69 73 74 69 63 73 29 28 73 71 6c 69  cteristics)(sqli
81a0: 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a  te3_file*);.  /*
81b0: 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61   Methods above a
81c0: 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72  re valid for ver
81d0: 73 69 6f 6e 20 31 20 2a 2f 0a 20 20 69 6e 74 20  sion 1 */.  int 
81e0: 28 2a 78 53 68 6d 4d 61 70 29 28 73 71 6c 69 74  (*xShmMap)(sqlit
81f0: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 69 50  e3_file*, int iP
8200: 67 2c 20 69 6e 74 20 70 67 73 7a 2c 20 69 6e 74  g, int pgsz, int
8210: 2c 20 76 6f 69 64 20 76 6f 6c 61 74 69 6c 65 2a  , void volatile*
8220: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d  *);.  int (*xShm
8230: 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69  Lock)(sqlite3_fi
8240: 6c 65 2a 2c 20 69 6e 74 20 6f 66 66 73 65 74 2c  le*, int offset,
8250: 20 69 6e 74 20 6e 2c 20 69 6e 74 20 66 6c 61 67   int n, int flag
8260: 73 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 53 68  s);.  void (*xSh
8270: 6d 42 61 72 72 69 65 72 29 28 73 71 6c 69 74 65  mBarrier)(sqlite
8280: 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20  3_file*);.  int 
8290: 28 2a 78 53 68 6d 55 6e 6d 61 70 29 28 73 71 6c  (*xShmUnmap)(sql
82a0: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20  ite3_file*, int 
82b0: 64 65 6c 65 74 65 46 6c 61 67 29 3b 0a 20 20 2f  deleteFlag);.  /
82c0: 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20  * Methods above 
82d0: 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65  are valid for ve
82e0: 72 73 69 6f 6e 20 32 20 2a 2f 0a 20 20 2f 2a 20  rsion 2 */.  /* 
82f0: 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65 74 68 6f  Additional metho
8300: 64 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20  ds may be added 
8310: 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
8320: 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20  es */.};../*.** 
8330: 43 41 50 49 33 52 45 46 3a 20 53 74 61 6e 64 61  CAPI3REF: Standa
8340: 72 64 20 46 69 6c 65 20 43 6f 6e 74 72 6f 6c 20  rd File Control 
8350: 4f 70 63 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68  Opcodes.**.** Th
8360: 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73  ese integer cons
8370: 74 61 6e 74 73 20 61 72 65 20 6f 70 63 6f 64 65  tants are opcode
8380: 73 20 66 6f 72 20 74 68 65 20 78 46 69 6c 65 43  s for the xFileC
8390: 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a  ontrol method.**
83a0: 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
83b0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
83c0: 65 63 74 20 61 6e 64 20 66 6f 72 20 74 68 65 20  ect and for the 
83d0: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
83e0: 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65  ntrol()].** inte
83f0: 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  rface..**.** The
8400: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c   [SQLITE_FCNTL_L
8410: 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63 6f 64 65  OCKSTATE] opcode
8420: 20 69 73 20 75 73 65 64 20 66 6f 72 20 64 65 62   is used for deb
8430: 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a 2a  ugging.  This.**
8440: 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20 74   opcode causes t
8450: 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20  he xFileControl 
8460: 6d 65 74 68 6f 64 20 74 6f 20 77 72 69 74 65 20  method to write 
8470: 74 68 65 20 63 75 72 72 65 6e 74 20 73 74 61 74  the current stat
8480: 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f 63 6b  e of.** the lock
8490: 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45   (one of [SQLITE
84a0: 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53 51  _LOCK_NONE], [SQ
84b0: 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44  LITE_LOCK_SHARED
84c0: 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c 4f  ],.** [SQLITE_LO
84d0: 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 20 5b 53  CK_RESERVED], [S
84e0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49  QLITE_LOCK_PENDI
84f0: 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  NG], or [SQLITE_
8500: 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 29  LOCK_EXCLUSIVE])
8510: 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69 6e 74 65  .** into an inte
8520: 67 65 72 20 74 68 61 74 20 74 68 65 20 70 41 72  ger that the pAr
8530: 67 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74  g argument point
8540: 73 20 74 6f 2e 20 54 68 69 73 20 63 61 70 61 62  s to. This capab
8550: 69 6c 69 74 79 0a 2a 2a 20 69 73 20 75 73 65 64  ility.** is used
8560: 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20   during testing 
8570: 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74  and only needs t
8580: 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 20 77  o be supported w
8590: 68 65 6e 20 53 51 4c 49 54 45 5f 54 45 53 54 0a  hen SQLITE_TEST.
85a0: 2a 2a 20 69 73 20 64 65 66 69 6e 65 64 2e 0a 2a  ** is defined..*
85b0: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 5b 5b  * <ul>.** <li>[[
85c0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a  SQLITE_FCNTL_SIZ
85d0: 45 5f 48 49 4e 54 5d 5d 0a 2a 2a 20 54 68 65 20  E_HINT]].** The 
85e0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49  [SQLITE_FCNTL_SI
85f0: 5a 45 5f 48 49 4e 54 5d 20 6f 70 63 6f 64 65 20  ZE_HINT] opcode 
8600: 69 73 20 75 73 65 64 20 62 79 20 53 51 4c 69 74  is used by SQLit
8610: 65 20 74 6f 20 67 69 76 65 20 74 68 65 20 56 46  e to give the VF
8620: 53 0a 2a 2a 20 6c 61 79 65 72 20 61 20 68 69 6e  S.** layer a hin
8630: 74 20 6f 66 20 68 6f 77 20 6c 61 72 67 65 20 74  t of how large t
8640: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
8650: 20 77 69 6c 6c 20 67 72 6f 77 20 74 6f 20 62 65   will grow to be
8660: 20 64 75 72 69 6e 67 20 74 68 65 0a 2a 2a 20 63   during the.** c
8670: 75 72 72 65 6e 74 20 74 72 61 6e 73 61 63 74 69  urrent transacti
8680: 6f 6e 2e 20 20 54 68 69 73 20 68 69 6e 74 20 69  on.  This hint i
8690: 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 64  s not guaranteed
86a0: 20 74 6f 20 62 65 20 61 63 63 75 72 61 74 65 20   to be accurate 
86b0: 62 75 74 20 69 74 0a 2a 2a 20 69 73 20 6f 66 74  but it.** is oft
86c0: 65 6e 20 63 6c 6f 73 65 2e 20 20 54 68 65 20 75  en close.  The u
86d0: 6e 64 65 72 6c 79 69 6e 67 20 56 46 53 20 6d 69  nderlying VFS mi
86e0: 67 68 74 20 63 68 6f 6f 73 65 20 74 6f 20 70 72  ght choose to pr
86f0: 65 61 6c 6c 6f 63 61 74 65 20 64 61 74 61 62 61  eallocate databa
8700: 73 65 0a 2a 2a 20 66 69 6c 65 20 73 70 61 63 65  se.** file space
8710: 20 62 61 73 65 64 20 6f 6e 20 74 68 69 73 20 68   based on this h
8720: 69 6e 74 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  int in order to 
8730: 68 65 6c 70 20 77 72 69 74 65 73 20 74 6f 20 74  help writes to t
8740: 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66  he database.** f
8750: 69 6c 65 20 72 75 6e 20 66 61 73 74 65 72 2e 0a  ile run faster..
8760: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
8770: 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53  TE_FCNTL_CHUNK_S
8780: 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  IZE]].** The [SQ
8790: 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b  LITE_FCNTL_CHUNK
87a0: 5f 53 49 5a 45 5d 20 6f 70 63 6f 64 65 20 69 73  _SIZE] opcode is
87b0: 20 75 73 65 64 20 74 6f 20 72 65 71 75 65 73 74   used to request
87c0: 20 74 68 61 74 20 74 68 65 20 56 46 53 0a 2a 2a   that the VFS.**
87d0: 20 65 78 74 65 6e 64 73 20 61 6e 64 20 74 72 75   extends and tru
87e0: 6e 63 61 74 65 73 20 74 68 65 20 64 61 74 61 62  ncates the datab
87f0: 61 73 65 20 66 69 6c 65 20 69 6e 20 63 68 75 6e  ase file in chun
8800: 6b 73 20 6f 66 20 61 20 73 69 7a 65 20 73 70 65  ks of a size spe
8810: 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 74 68 65  cified.** by the
8820: 20 75 73 65 72 2e 20 54 68 65 20 66 6f 75 72 74   user. The fourt
8830: 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73  h argument to [s
8840: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
8850: 72 6f 6c 28 29 5d 20 73 68 6f 75 6c 64 20 0a 2a  rol()] should .*
8860: 2a 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 69 6e  * point to an in
8870: 74 65 67 65 72 20 28 74 79 70 65 20 69 6e 74 29  teger (type int)
8880: 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20   containing the 
8890: 6e 65 77 20 63 68 75 6e 6b 2d 73 69 7a 65 20 74  new chunk-size t
88a0: 6f 20 75 73 65 0a 2a 2a 20 66 6f 72 20 74 68 65  o use.** for the
88b0: 20 6e 6f 6d 69 6e 61 74 65 64 20 64 61 74 61 62   nominated datab
88c0: 61 73 65 2e 20 41 6c 6c 6f 63 61 74 69 6e 67 20  ase. Allocating 
88d0: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 73 70  database file sp
88e0: 61 63 65 20 69 6e 20 6c 61 72 67 65 0a 2a 2a 20  ace in large.** 
88f0: 63 68 75 6e 6b 73 20 28 73 61 79 20 31 4d 42 20  chunks (say 1MB 
8900: 61 74 20 61 20 74 69 6d 65 29 2c 20 6d 61 79 20  at a time), may 
8910: 72 65 64 75 63 65 20 66 69 6c 65 2d 73 79 73 74  reduce file-syst
8920: 65 6d 20 66 72 61 67 6d 65 6e 74 61 74 69 6f 6e  em fragmentation
8930: 20 61 6e 64 0a 2a 2a 20 69 6d 70 72 6f 76 65 20   and.** improve 
8940: 70 65 72 66 6f 72 6d 61 6e 63 65 20 6f 6e 20 73  performance on s
8950: 6f 6d 65 20 73 79 73 74 65 6d 73 2e 0a 2a 2a 0a  ome systems..**.
8960: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
8970: 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54  FCNTL_FILE_POINT
8980: 45 52 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  ER]].** The [SQL
8990: 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50  ITE_FCNTL_FILE_P
89a0: 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20 69  OINTER] opcode i
89b0: 73 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e  s used to obtain
89c0: 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f   a pointer.** to
89d0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69   the [sqlite3_fi
89e0: 6c 65 5d 20 6f 62 6a 65 63 74 20 61 73 73 6f 63  le] object assoc
89f0: 69 61 74 65 64 20 77 69 74 68 20 61 20 70 61 72  iated with a par
8a00: 74 69 63 75 6c 61 72 20 64 61 74 61 62 61 73 65  ticular database
8a10: 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20  .** connection. 
8a20: 20 53 65 65 20 74 68 65 20 5b 73 71 6c 69 74 65   See the [sqlite
8a30: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
8a40: 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20  ] documentation 
8a50: 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61  for.** additiona
8a60: 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  l information..*
8a70: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
8a80: 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49  E_FCNTL_SYNC_OMI
8a90: 54 54 45 44 5d 5d 0a 2a 2a 20 5e 28 54 68 65 20  TTED]].** ^(The 
8aa0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59  [SQLITE_FCNTL_SY
8ab0: 4e 43 5f 4f 4d 49 54 54 45 44 5d 20 6f 70 63 6f  NC_OMITTED] opco
8ac0: 64 65 20 69 73 20 67 65 6e 65 72 61 74 65 64 20  de is generated 
8ad0: 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 0a 2a 2a  internally by.**
8ae0: 20 53 51 4c 69 74 65 20 61 6e 64 20 73 65 6e 74   SQLite and sent
8af0: 20 74 6f 20 61 6c 6c 20 56 46 53 65 73 20 69 6e   to all VFSes in
8b00: 20 70 6c 61 63 65 20 6f 66 20 61 20 63 61 6c 6c   place of a call
8b10: 20 74 6f 20 74 68 65 20 78 53 79 6e 63 20 6d 65   to the xSync me
8b20: 74 68 6f 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65  thod.** when the
8b30: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
8b40: 74 69 6f 6e 20 68 61 73 20 5b 50 52 41 47 4d 41  tion has [PRAGMA
8b50: 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 20 73 65   synchronous] se
8b60: 74 20 74 6f 20 4f 46 46 2e 29 5e 0a 2a 2a 20 53  t to OFF.)^.** S
8b70: 6f 6d 65 20 73 70 65 63 69 61 6c 69 7a 65 64 20  ome specialized 
8b80: 56 46 53 65 73 20 6e 65 65 64 20 74 68 69 73 20  VFSes need this 
8b90: 73 69 67 6e 61 6c 20 69 6e 20 6f 72 64 65 72 20  signal in order 
8ba0: 74 6f 20 6f 70 65 72 61 74 65 20 63 6f 72 72 65  to operate corre
8bb0: 63 74 6c 79 0a 2a 2a 20 77 68 65 6e 20 5b 50 52  ctly.** when [PR
8bc0: 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73  AGMA synchronous
8bd0: 20 7c 20 50 52 41 47 4d 41 20 73 79 6e 63 68 72   | PRAGMA synchr
8be0: 6f 6e 6f 75 73 3d 4f 46 46 5d 20 69 73 20 73 65  onous=OFF] is se
8bf0: 74 2c 20 62 75 74 20 6d 6f 73 74 20 0a 2a 2a 20  t, but most .** 
8c00: 56 46 53 65 73 20 64 6f 20 6e 6f 74 20 6e 65 65  VFSes do not nee
8c10: 64 20 74 68 69 73 20 73 69 67 6e 61 6c 20 61 6e  d this signal an
8c20: 64 20 73 68 6f 75 6c 64 20 73 69 6c 65 6e 74 6c  d should silentl
8c30: 79 20 69 67 6e 6f 72 65 20 74 68 69 73 20 6f 70  y ignore this op
8c40: 63 6f 64 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61  code..** Applica
8c50: 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 6e 6f 74  tions should not
8c60: 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66   call [sqlite3_f
8c70: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 77  ile_control()] w
8c80: 69 74 68 20 74 68 69 73 0a 2a 2a 20 6f 70 63 6f  ith this.** opco
8c90: 64 65 20 61 73 20 64 6f 69 6e 67 20 73 6f 20 6d  de as doing so m
8ca0: 61 79 20 64 69 73 72 75 70 74 20 74 68 65 20 6f  ay disrupt the o
8cb0: 70 65 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  peration of the 
8cc0: 73 70 65 63 69 61 6c 69 7a 65 64 20 56 46 53 65  specialized VFSe
8cd0: 73 0a 2a 2a 20 74 68 61 74 20 64 6f 20 72 65 71  s.** that do req
8ce0: 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a  uire it.  .**.**
8cf0: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
8d00: 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54  NTL_WIN32_AV_RET
8d10: 52 59 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  RY]].** ^The [SQ
8d20: 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32  LITE_FCNTL_WIN32
8d30: 5f 41 56 5f 52 45 54 52 59 5d 20 6f 70 63 6f 64  _AV_RETRY] opcod
8d40: 65 20 69 73 20 75 73 65 64 20 74 6f 20 63 6f 6e  e is used to con
8d50: 66 69 67 75 72 65 20 61 75 74 6f 6d 61 74 69 63  figure automatic
8d60: 0a 2a 2a 20 72 65 74 72 79 20 63 6f 75 6e 74 73  .** retry counts
8d70: 20 61 6e 64 20 69 6e 74 65 72 76 61 6c 73 20 66   and intervals f
8d80: 6f 72 20 63 65 72 74 61 69 6e 20 64 69 73 6b 20  or certain disk 
8d90: 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20 66  I/O operations f
8da0: 6f 72 20 74 68 65 0a 2a 2a 20 77 69 6e 64 6f 77  or the.** window
8db0: 73 20 5b 56 46 53 5d 20 69 6e 20 6f 72 64 65 72  s [VFS] in order
8dc0: 20 74 6f 20 70 72 6f 76 69 64 65 20 72 6f 62 75   to provide robu
8dd0: 73 74 6e 65 73 73 20 69 6e 20 74 68 65 20 70 72  stness in the pr
8de0: 65 73 65 6e 63 65 20 6f 66 0a 2a 2a 20 61 6e 74  esence of.** ant
8df0: 69 2d 76 69 72 75 73 20 70 72 6f 67 72 61 6d 73  i-virus programs
8e00: 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c 20 74  .  By default, t
8e10: 68 65 20 77 69 6e 64 6f 77 73 20 56 46 53 20 77  he windows VFS w
8e20: 69 6c 6c 20 72 65 74 72 79 20 66 69 6c 65 20 72  ill retry file r
8e30: 65 61 64 2c 0a 2a 2a 20 66 69 6c 65 20 77 72 69  ead,.** file wri
8e40: 74 65 2c 20 61 6e 64 20 66 69 6c 65 20 64 65 6c  te, and file del
8e50: 65 74 65 20 6f 70 65 72 61 74 69 6f 6e 73 20 75  ete operations u
8e60: 70 20 74 6f 20 31 30 20 74 69 6d 65 73 2c 20 77  p to 10 times, w
8e70: 69 74 68 20 61 20 64 65 6c 61 79 0a 2a 2a 20 6f  ith a delay.** o
8e80: 66 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  f 25 millisecond
8e90: 73 20 62 65 66 6f 72 65 20 74 68 65 20 66 69 72  s before the fir
8ea0: 73 74 20 72 65 74 72 79 20 61 6e 64 20 77 69 74  st retry and wit
8eb0: 68 20 74 68 65 20 64 65 6c 61 79 20 69 6e 63 72  h the delay incr
8ec0: 65 61 73 69 6e 67 0a 2a 2a 20 62 79 20 61 6e 20  easing.** by an 
8ed0: 61 64 64 69 74 69 6f 6e 61 6c 20 32 35 20 6d 69  additional 25 mi
8ee0: 6c 6c 69 73 65 63 6f 6e 64 73 20 77 69 74 68 20  lliseconds with 
8ef0: 65 61 63 68 20 73 75 62 73 65 71 75 65 6e 74 20  each subsequent 
8f00: 72 65 74 72 79 2e 20 20 54 68 69 73 0a 2a 2a 20  retry.  This.** 
8f10: 6f 70 63 6f 64 65 20 61 6c 6c 6f 77 73 20 74 68  opcode allows th
8f20: 65 73 65 20 74 77 6f 20 76 61 6c 75 65 73 20 28  ese two values (
8f30: 31 30 20 72 65 74 72 69 65 73 20 61 6e 64 20 32  10 retries and 2
8f40: 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f  5 milliseconds o
8f50: 66 20 64 65 6c 61 79 29 0a 2a 2a 20 74 6f 20 62  f delay).** to b
8f60: 65 20 61 64 6a 75 73 74 65 64 2e 20 20 54 68 65  e adjusted.  The
8f70: 20 76 61 6c 75 65 73 20 61 72 65 20 63 68 61 6e   values are chan
8f80: 67 65 64 20 66 6f 72 20 61 6c 6c 20 64 61 74 61  ged for all data
8f90: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
8fa0: 0a 2a 2a 20 77 69 74 68 69 6e 20 74 68 65 20 73  .** within the s
8fb0: 61 6d 65 20 70 72 6f 63 65 73 73 2e 20 20 54 68  ame process.  Th
8fc0: 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  e argument is a 
8fd0: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 61 72  pointer to an ar
8fe0: 72 61 79 20 6f 66 20 74 77 6f 0a 2a 2a 20 69 6e  ray of two.** in
8ff0: 74 65 67 65 72 73 20 77 68 65 72 65 20 74 68 65  tegers where the
9000: 20 66 69 72 73 74 20 69 6e 74 65 67 65 72 20 69   first integer i
9010: 20 74 68 65 20 6e 65 77 20 72 65 74 72 79 20 63   the new retry c
9020: 6f 75 6e 74 20 61 6e 64 20 74 68 65 20 73 65 63  ount and the sec
9030: 6f 6e 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20 69  ond.** integer i
9040: 73 20 74 68 65 20 64 65 6c 61 79 2e 20 20 49 66  s the delay.  If
9050: 20 65 69 74 68 65 72 20 69 6e 74 65 67 65 72 20   either integer 
9060: 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65  is negative, the
9070: 6e 20 74 68 65 20 73 65 74 74 69 6e 67 0a 2a 2a  n the setting.**
9080: 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 20   is not changed 
9090: 62 75 74 20 69 6e 73 74 65 61 64 20 74 68 65 20  but instead the 
90a0: 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20 74  prior value of t
90b0: 68 61 74 20 73 65 74 74 69 6e 67 20 69 73 20 77  hat setting is w
90c0: 72 69 74 74 65 6e 0a 2a 2a 20 69 6e 74 6f 20 74  ritten.** into t
90d0: 68 65 20 61 72 72 61 79 20 65 6e 74 72 79 2c 20  he array entry, 
90e0: 61 6c 6c 6f 77 69 6e 67 20 74 68 65 20 63 75 72  allowing the cur
90f0: 72 65 6e 74 20 72 65 74 72 79 20 73 65 74 74 69  rent retry setti
9100: 6e 67 73 20 74 6f 20 62 65 0a 2a 2a 20 69 6e 74  ngs to be.** int
9110: 65 72 72 6f 67 61 74 65 64 2e 20 20 54 68 65 20  errogated.  The 
9120: 7a 44 62 4e 61 6d 65 20 70 61 72 61 6d 65 74 65  zDbName paramete
9130: 72 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a  r is ignored..**
9140: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
9150: 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57  _FCNTL_PERSIST_W
9160: 41 4c 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  AL]].** ^The [SQ
9170: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49  LITE_FCNTL_PERSI
9180: 53 54 5f 57 41 4c 5d 20 6f 70 63 6f 64 65 20 69  ST_WAL] opcode i
9190: 73 20 75 73 65 64 20 74 6f 20 73 65 74 20 6f 72  s used to set or
91a0: 20 71 75 65 72 79 20 74 68 65 0a 2a 2a 20 70 65   query the.** pe
91b0: 72 73 69 73 74 65 6e 74 20 5b 57 41 4c 20 7c 20  rsistent [WAL | 
91c0: 57 72 69 74 65 20 41 68 65 61 64 20 4c 6f 67 5d  Write Ahead Log]
91d0: 20 73 65 74 74 69 6e 67 2e 20 20 42 79 20 64 65   setting.  By de
91e0: 66 61 75 6c 74 2c 20 74 68 65 20 61 75 78 69 6c  fault, the auxil
91f0: 69 61 72 79 0a 2a 2a 20 77 72 69 74 65 20 61 68  iary.** write ah
9200: 65 61 64 20 6c 6f 67 20 61 6e 64 20 73 68 61 72  ead log and shar
9210: 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c 65 73 20  ed memory files 
9220: 75 73 65 64 20 66 6f 72 20 74 72 61 6e 73 61 63  used for transac
9230: 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20  tion control.** 
9240: 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  are automaticall
9250: 79 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20 74  y deleted when t
9260: 68 65 20 6c 61 74 65 73 74 20 63 6f 6e 6e 65 63  he latest connec
9270: 74 69 6f 6e 20 74 6f 20 74 68 65 20 64 61 74 61  tion to the data
9280: 62 61 73 65 0a 2a 2a 20 63 6c 6f 73 65 73 2e 20  base.** closes. 
9290: 20 53 65 74 74 69 6e 67 20 70 65 72 73 69 73 74   Setting persist
92a0: 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 63 61 75  ent WAL mode cau
92b0: 73 65 73 20 74 68 6f 73 65 20 66 69 6c 65 73 20  ses those files 
92c0: 74 6f 20 70 65 72 73 69 73 74 20 61 66 74 65 72  to persist after
92d0: 0a 2a 2a 20 63 6c 6f 73 65 2e 20 20 50 65 72 73  .** close.  Pers
92e0: 69 73 74 69 6e 67 20 74 68 65 20 66 69 6c 65 73  isting the files
92f0: 20 69 73 20 75 73 65 66 75 6c 20 77 68 65 6e 20   is useful when 
9300: 6f 74 68 65 72 20 70 72 6f 63 65 73 73 65 73 20  other processes 
9310: 74 68 61 74 20 64 6f 20 6e 6f 74 0a 2a 2a 20 68  that do not.** h
9320: 61 76 65 20 77 72 69 74 65 20 70 65 72 6d 69 73  ave write permis
9330: 73 69 6f 6e 20 6f 6e 20 74 68 65 20 64 69 72 65  sion on the dire
9340: 63 74 6f 72 79 20 63 6f 6e 74 61 69 6e 69 6e 67  ctory containing
9350: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
9360: 6c 65 20 77 61 6e 74 0a 2a 2a 20 74 6f 20 72 65  le want.** to re
9370: 61 64 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ad the database 
9380: 66 69 6c 65 2c 20 61 73 20 74 68 65 20 57 41 4c  file, as the WAL
9390: 20 61 6e 64 20 73 68 61 72 65 64 20 6d 65 6d 6f   and shared memo
93a0: 72 79 20 66 69 6c 65 73 20 6d 75 73 74 20 65 78  ry files must ex
93b0: 69 73 74 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20  ist.** in order 
93c0: 66 6f 72 20 74 68 65 20 64 61 74 61 62 61 73 65  for the database
93d0: 20 74 6f 20 62 65 20 72 65 61 64 61 62 6c 65 2e   to be readable.
93e0: 20 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72    The fourth par
93f0: 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71  ameter to.** [sq
9400: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
9410: 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 73 20 6f  ol()] for this o
9420: 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 62 65 20  pcode should be 
9430: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
9440: 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61 74  integer..** That
9450: 20 69 6e 74 65 67 65 72 20 69 73 20 30 20 74 6f   integer is 0 to
9460: 20 64 69 73 61 62 6c 65 20 70 65 72 73 69 73 74   disable persist
9470: 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 6f 72 20  ent WAL mode or 
9480: 31 20 74 6f 20 65 6e 61 62 6c 65 20 70 65 72 73  1 to enable pers
9490: 69 73 74 65 6e 74 0a 2a 2a 20 57 41 4c 20 6d 6f  istent.** WAL mo
94a0: 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e 74 65  de.  If the inte
94b0: 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e 20  ger is -1, then 
94c0: 69 74 20 69 73 20 6f 76 65 72 77 72 69 74 74 65  it is overwritte
94d0: 6e 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65  n with the curre
94e0: 6e 74 0a 2a 2a 20 57 41 4c 20 70 65 72 73 69 73  nt.** WAL persis
94f0: 74 65 6e 63 65 20 73 65 74 74 69 6e 67 2e 0a 2a  tence setting..*
9500: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
9510: 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46  E_FCNTL_POWERSAF
9520: 45 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a 2a 2a  E_OVERWRITE]].**
9530: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43   ^The [SQLITE_FC
9540: 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56  NTL_POWERSAFE_OV
9550: 45 52 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 20  ERWRITE] opcode 
9560: 69 73 20 75 73 65 64 20 74 6f 20 73 65 74 20 6f  is used to set o
9570: 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a 20 70  r query the.** p
9580: 65 72 73 69 73 74 65 6e 74 20 22 70 6f 77 65 72  ersistent "power
9590: 73 61 66 65 2d 6f 76 65 72 77 72 69 74 65 22 20  safe-overwrite" 
95a0: 6f 72 20 22 50 53 4f 57 22 20 73 65 74 74 69 6e  or "PSOW" settin
95b0: 67 2e 20 20 54 68 65 20 50 53 4f 57 20 73 65 74  g.  The PSOW set
95c0: 74 69 6e 67 0a 2a 2a 20 64 65 74 65 72 6d 69 6e  ting.** determin
95d0: 65 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 49  es the [SQLITE_I
95e0: 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f  OCAP_POWERSAFE_O
95f0: 56 45 52 57 52 49 54 45 5d 20 62 69 74 20 6f 66  VERWRITE] bit of
9600: 20 74 68 65 0a 2a 2a 20 78 44 65 76 69 63 65 43   the.** xDeviceC
9610: 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20 6d  haracteristics m
9620: 65 74 68 6f 64 73 2e 20 54 68 65 20 66 6f 75 72  ethods. The four
9630: 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  th parameter to.
9640: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ** [sqlite3_file
9650: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f 72 20  _control()] for 
9660: 74 68 69 73 20 6f 70 63 6f 64 65 20 73 68 6f 75  this opcode shou
9670: 6c 64 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20  ld be a pointer 
9680: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e 0a 2a  to an integer..*
9690: 2a 20 54 68 61 74 20 69 6e 74 65 67 65 72 20 69  * That integer i
96a0: 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 7a  s 0 to disable z
96b0: 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 65 20  ero-damage mode 
96c0: 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c 65 20 7a  or 1 to enable z
96d0: 65 72 6f 2d 64 61 6d 61 67 65 0a 2a 2a 20 6d 6f  ero-damage.** mo
96e0: 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e 74 65  de.  If the inte
96f0: 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e 20  ger is -1, then 
9700: 69 74 20 69 73 20 6f 76 65 72 77 72 69 74 74 65  it is overwritte
9710: 6e 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65  n with the curre
9720: 6e 74 0a 2a 2a 20 7a 65 72 6f 2d 64 61 6d 61 67  nt.** zero-damag
9730: 65 20 6d 6f 64 65 20 73 65 74 74 69 6e 67 2e 0a  e mode setting..
9740: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
9750: 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49  TE_FCNTL_OVERWRI
9760: 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  TE]].** ^The [SQ
9770: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57  LITE_FCNTL_OVERW
9780: 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20  RITE] opcode is 
9790: 69 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c 69 74  invoked by SQLit
97a0: 65 20 61 66 74 65 72 20 6f 70 65 6e 69 6e 67 0a  e after opening.
97b0: 2a 2a 20 61 20 77 72 69 74 65 20 74 72 61 6e 73  ** a write trans
97c0: 61 63 74 69 6f 6e 20 74 6f 20 69 6e 64 69 63 61  action to indica
97d0: 74 65 20 74 68 61 74 2c 20 75 6e 6c 65 73 73 20  te that, unless 
97e0: 69 74 20 69 73 20 72 6f 6c 6c 65 64 20 62 61 63  it is rolled bac
97f0: 6b 20 66 6f 72 20 73 6f 6d 65 0a 2a 2a 20 72 65  k for some.** re
9800: 61 73 6f 6e 2c 20 74 68 65 20 65 6e 74 69 72 65  ason, the entire
9810: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77   database file w
9820: 69 6c 6c 20 62 65 20 6f 76 65 72 77 72 69 74 74  ill be overwritt
9830: 65 6e 20 62 79 20 74 68 65 20 63 75 72 72 65 6e  en by the curren
9840: 74 20 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f  t .** transactio
9850: 6e 2e 20 54 68 69 73 20 69 73 20 75 73 65 64 20  n. This is used 
9860: 62 79 20 56 41 43 55 55 4d 20 6f 70 65 72 61 74  by VACUUM operat
9870: 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  ions..**.** <li>
9880: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56  [[SQLITE_FCNTL_V
9890: 46 53 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 54 68 65  FSNAME]].** ^The
98a0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56   [SQLITE_FCNTL_V
98b0: 46 53 4e 41 4d 45 5d 20 6f 70 63 6f 64 65 20 63  FSNAME] opcode c
98c0: 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62  an be used to ob
98d0: 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f  tain the names o
98e0: 66 0a 2a 2a 20 61 6c 6c 20 5b 56 46 53 65 73 5d  f.** all [VFSes]
98f0: 20 69 6e 20 74 68 65 20 56 46 53 20 73 74 61 63   in the VFS stac
9900: 6b 2e 20 20 54 68 65 20 6e 61 6d 65 73 20 61 72  k.  The names ar
9910: 65 20 6f 66 20 61 6c 6c 20 56 46 53 20 73 68 69  e of all VFS shi
9920: 6d 73 20 61 6e 64 20 74 68 65 0a 2a 2a 20 66 69  ms and the.** fi
9930: 6e 61 6c 20 62 6f 74 74 6f 6d 2d 6c 65 76 65 6c  nal bottom-level
9940: 20 56 46 53 20 61 72 65 20 77 72 69 74 74 65 6e   VFS are written
9950: 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74   into memory obt
9960: 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b  ained from .** [
9970: 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
9980: 5d 20 61 6e 64 20 74 68 65 20 72 65 73 75 6c 74  ] and the result
9990: 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 74 68   is stored in th
99a0: 65 20 63 68 61 72 2a 20 76 61 72 69 61 62 6c 65  e char* variable
99b0: 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 66 6f 75  .** that the fou
99c0: 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 6f 66  rth parameter of
99d0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
99e0: 6f 6e 74 72 6f 6c 28 29 5d 20 70 6f 69 6e 74 73  ontrol()] points
99f0: 20 74 6f 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c   to..** The call
9a00: 65 72 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c  er is responsibl
9a10: 65 20 66 6f 72 20 66 72 65 65 69 6e 67 20 74 68  e for freeing th
9a20: 65 20 6d 65 6d 6f 72 79 20 77 68 65 6e 20 64 6f  e memory when do
9a30: 6e 65 2e 20 20 41 73 20 77 69 74 68 0a 2a 2a 20  ne.  As with.** 
9a40: 61 6c 6c 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c  all file-control
9a50: 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 72 65 20   actions, there 
9a60: 69 73 20 6e 6f 20 67 75 61 72 61 6e 74 65 65 20  is no guarantee 
9a70: 74 68 61 74 20 74 68 69 73 20 77 69 6c 6c 20 61  that this will a
9a80: 63 74 75 61 6c 6c 79 0a 2a 2a 20 64 6f 20 61 6e  ctually.** do an
9a90: 79 74 68 69 6e 67 2e 20 20 43 61 6c 6c 65 72 73  ything.  Callers
9aa0: 20 73 68 6f 75 6c 64 20 69 6e 69 74 69 61 6c 69   should initiali
9ab0: 7a 65 20 74 68 65 20 63 68 61 72 2a 20 76 61 72  ze the char* var
9ac0: 69 61 62 6c 65 20 74 6f 20 61 20 4e 55 4c 4c 0a  iable to a NULL.
9ad0: 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 20 63 61  ** pointer in ca
9ae0: 73 65 20 74 68 69 73 20 66 69 6c 65 2d 63 6f 6e  se this file-con
9af0: 74 72 6f 6c 20 69 73 20 6e 6f 74 20 69 6d 70 6c  trol is not impl
9b00: 65 6d 65 6e 74 65 64 2e 20 20 54 68 69 73 20 66  emented.  This f
9b10: 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 69  ile-control.** i
9b20: 73 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 64  s intended for d
9b30: 69 61 67 6e 6f 73 74 69 63 20 75 73 65 20 6f 6e  iagnostic use on
9b40: 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ly..**.** <li>[[
9b50: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41  SQLITE_FCNTL_PRA
9b60: 47 4d 41 5d 5d 0a 2a 2a 20 5e 57 68 65 6e 65 76  GMA]].** ^Whenev
9b70: 65 72 20 61 20 5b 50 52 41 47 4d 41 5d 20 73 74  er a [PRAGMA] st
9b80: 61 74 65 6d 65 6e 74 20 69 73 20 70 61 72 73 65  atement is parse
9b90: 64 2c 20 61 6e 20 5b 53 51 4c 49 54 45 5f 46 43  d, an [SQLITE_FC
9ba0: 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 0a 2a 2a 20  NTL_PRAGMA] .** 
9bb0: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20  file control is 
9bc0: 73 65 6e 74 20 74 6f 20 74 68 65 20 6f 70 65 6e  sent to the open
9bd0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
9be0: 6f 62 6a 65 63 74 20 63 6f 72 72 65 73 70 6f 6e  object correspon
9bf0: 64 69 6e 67 0a 2a 2a 20 74 6f 20 74 68 65 20 64  ding.** to the d
9c00: 61 74 61 62 61 73 65 20 66 69 6c 65 20 74 6f 20  atabase file to 
9c10: 77 68 69 63 68 20 74 68 65 20 70 72 61 67 6d 61  which the pragma
9c20: 20 73 74 61 74 65 6d 65 6e 74 20 72 65 66 65 72   statement refer
9c30: 73 2e 20 5e 54 68 65 20 61 72 67 75 6d 65 6e 74  s. ^The argument
9c40: 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 53 51 4c 49  .** to the [SQLI
9c50: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d  TE_FCNTL_PRAGMA]
9c60: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73   file control is
9c70: 20 61 6e 20 61 72 72 61 79 20 6f 66 0a 2a 2a 20   an array of.** 
9c80: 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69  pointers to stri
9c90: 6e 67 73 20 28 63 68 61 72 2a 2a 29 20 69 6e 20  ngs (char**) in 
9ca0: 77 68 69 63 68 20 74 68 65 20 73 65 63 6f 6e 64  which the second
9cb0: 20 65 6c 65 6d 65 6e 74 20 6f 66 20 74 68 65 20   element of the 
9cc0: 61 72 72 61 79 0a 2a 2a 20 69 73 20 74 68 65 20  array.** is the 
9cd0: 6e 61 6d 65 20 6f 66 20 74 68 65 20 70 72 61 67  name of the prag
9ce0: 6d 61 20 61 6e 64 20 74 68 65 20 74 68 69 72 64  ma and the third
9cf0: 20 65 6c 65 6d 65 6e 74 20 69 73 20 74 68 65 20   element is the 
9d00: 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 0a  argument to the.
9d10: 2a 2a 20 70 72 61 67 6d 61 20 6f 72 20 4e 55 4c  ** pragma or NUL
9d20: 4c 20 69 66 20 74 68 65 20 70 72 61 67 6d 61 20  L if the pragma 
9d30: 68 61 73 20 6e 6f 20 61 72 67 75 6d 65 6e 74 2e  has no argument.
9d40: 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 72 20 66    ^The handler f
9d50: 6f 72 20 61 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45  or an.** [SQLITE
9d60: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66  _FCNTL_PRAGMA] f
9d70: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 63 61 6e 20  ile control can 
9d80: 6f 70 74 69 6f 6e 61 6c 6c 79 20 6d 61 6b 65 20  optionally make 
9d90: 74 68 65 20 66 69 72 73 74 20 65 6c 65 6d 65 6e  the first elemen
9da0: 74 0a 2a 2a 20 6f 66 20 74 68 65 20 63 68 61 72  t.** of the char
9db0: 2a 2a 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e  ** argument poin
9dc0: 74 20 74 6f 20 61 20 73 74 72 69 6e 67 20 6f 62  t to a string ob
9dd0: 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  tained from [sql
9de0: 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d 0a  ite3_mprintf()].
9df0: 2a 2a 20 6f 72 20 74 68 65 20 65 71 75 69 76 61  ** or the equiva
9e00: 6c 65 6e 74 20 61 6e 64 20 74 68 61 74 20 73 74  lent and that st
9e10: 72 69 6e 67 20 77 69 6c 6c 20 62 65 63 6f 6d 65  ring will become
9e20: 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 20 74   the result of t
9e30: 68 65 20 70 72 61 67 6d 61 20 6f 72 0a 2a 2a 20  he pragma or.** 
9e40: 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  the error messag
9e50: 65 20 69 66 20 74 68 65 20 70 72 61 67 6d 61 20  e if the pragma 
9e60: 66 61 69 6c 73 2e 20 5e 49 66 20 74 68 65 0a 2a  fails. ^If the.*
9e70: 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  * [SQLITE_FCNTL_
9e80: 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e  PRAGMA] file con
9e90: 74 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b 53 51  trol returns [SQ
9ea0: 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20  LITE_NOTFOUND], 
9eb0: 74 68 65 6e 20 6e 6f 72 6d 61 6c 20 0a 2a 2a 20  then normal .** 
9ec0: 5b 50 52 41 47 4d 41 5d 20 70 72 6f 63 65 73 73  [PRAGMA] process
9ed0: 69 6e 67 20 63 6f 6e 74 69 6e 75 65 73 2e 20 20  ing continues.  
9ee0: 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ^If the [SQLITE_
9ef0: 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a  FCNTL_PRAGMA].**
9f00: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65   file control re
9f10: 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
9f20: 5d 2c 20 74 68 65 6e 20 74 68 65 20 70 61 72 73  ], then the pars
9f30: 65 72 20 61 73 73 75 6d 65 73 20 74 68 61 74 20  er assumes that 
9f40: 74 68 65 0a 2a 2a 20 56 46 53 20 68 61 73 20 68  the.** VFS has h
9f50: 61 6e 64 6c 65 64 20 74 68 65 20 50 52 41 47 4d  andled the PRAGM
9f60: 41 20 69 74 73 65 6c 66 20 61 6e 64 20 74 68 65  A itself and the
9f70: 20 70 61 72 73 65 72 20 67 65 6e 65 72 61 74 65   parser generate
9f80: 73 20 61 20 6e 6f 2d 6f 70 0a 2a 2a 20 70 72 65  s a no-op.** pre
9f90: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 2e  pared statement.
9fa0: 20 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54    ^If the [SQLIT
9fb0: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20  E_FCNTL_PRAGMA] 
9fc0: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74  file control ret
9fd0: 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 72 65 73 75  urns.** any resu
9fe0: 6c 74 20 63 6f 64 65 20 6f 74 68 65 72 20 74 68  lt code other th
9ff0: 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f  an [SQLITE_OK] o
a000: 72 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55  r [SQLITE_NOTFOU
a010: 4e 44 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a  ND], that means.
a020: 2a 2a 20 74 68 61 74 20 74 68 65 20 56 46 53 20  ** that the VFS 
a030: 65 6e 63 6f 75 6e 74 65 72 65 64 20 61 6e 20 65  encountered an e
a040: 72 72 6f 72 20 77 68 69 6c 65 20 68 61 6e 64 6c  rror while handl
a050: 69 6e 67 20 74 68 65 20 5b 50 52 41 47 4d 41 5d  ing the [PRAGMA]
a060: 20 61 6e 64 20 74 68 65 0a 2a 2a 20 63 6f 6d 70   and the.** comp
a070: 69 6c 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 50  ilation of the P
a080: 52 41 47 4d 41 20 66 61 69 6c 73 20 77 69 74 68  RAGMA fails with
a090: 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e 54 68 65   an error.  ^The
a0a0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50   [SQLITE_FCNTL_P
a0b0: 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20 63  RAGMA].** file c
a0c0: 6f 6e 74 72 6f 6c 20 6f 63 63 75 72 73 20 61 74  ontrol occurs at
a0d0: 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f   the beginning o
a0e0: 66 20 70 72 61 67 6d 61 20 73 74 61 74 65 6d 65  f pragma stateme
a0f0: 6e 74 20 61 6e 61 6c 79 73 69 73 20 61 6e 64 20  nt analysis and 
a100: 73 6f 0a 2a 2a 20 69 74 20 69 73 20 61 62 6c 65  so.** it is able
a110: 20 74 6f 20 6f 76 65 72 72 69 64 65 20 62 75 69   to override bui
a120: 6c 74 2d 69 6e 20 5b 50 52 41 47 4d 41 5d 20 73  lt-in [PRAGMA] s
a130: 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 3c 2f  tatements..** </
a140: 75 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ul>.*/.#define S
a150: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b  QLITE_FCNTL_LOCK
a160: 53 54 41 54 45 20 20 20 20 20 20 20 20 20 20 20  STATE           
a170: 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51      1.#define SQ
a180: 4c 49 54 45 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f  LITE_GET_LOCKPRO
a190: 58 59 46 49 4c 45 20 20 20 20 20 20 20 20 20 20  XYFILE          
a1a0: 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c     2.#define SQL
a1b0: 49 54 45 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58  ITE_SET_LOCKPROX
a1c0: 59 46 49 4c 45 20 20 20 20 20 20 20 20 20 20 20  YFILE           
a1d0: 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    3.#define SQLI
a1e0: 54 45 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20  TE_LAST_ERRNO   
a1f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
a200: 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   4.#define SQLIT
a210: 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e  E_FCNTL_SIZE_HIN
a220: 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  T               
a230: 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  5.#define SQLITE
a240: 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a  _FCNTL_CHUNK_SIZ
a250: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 36  E              6
a260: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
a270: 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54  FCNTL_FILE_POINT
a280: 45 52 20 20 20 20 20 20 20 20 20 20 20 20 37 0a  ER            7.
a290: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
a2a0: 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45  CNTL_SYNC_OMITTE
a2b0: 44 20 20 20 20 20 20 20 20 20 20 20 20 38 0a 23  D            8.#
a2c0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
a2d0: 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54  NTL_WIN32_AV_RET
a2e0: 52 59 20 20 20 20 20 20 20 20 20 20 39 0a 23 64  RY          9.#d
a2f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
a300: 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c 20 20  TL_PERSIST_WAL  
a310: 20 20 20 20 20 20 20 20 20 20 31 30 0a 23 64 65            10.#de
a320: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
a330: 4c 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20 20  L_OVERWRITE     
a340: 20 20 20 20 20 20 20 20 20 31 31 0a 23 64 65 66           11.#def
a350: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
a360: 5f 56 46 53 4e 41 4d 45 20 20 20 20 20 20 20 20  _VFSNAME        
a370: 20 20 20 20 20 20 20 20 31 32 0a 23 64 65 66 69          12.#defi
a380: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
a390: 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52  POWERSAFE_OVERWR
a3a0: 49 54 45 20 20 20 20 31 33 0a 23 64 65 66 69 6e  ITE    13.#defin
a3b0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50  e SQLITE_FCNTL_P
a3c0: 52 41 47 4d 41 20 20 20 20 20 20 20 20 20 20 20  RAGMA           
a3d0: 20 20 20 20 20 20 31 34 0a 0a 2f 2a 0a 2a 2a 20        14../*.** 
a3e0: 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20  CAPI3REF: Mutex 
a3f0: 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 54 68 65  Handle.**.** The
a400: 20 6d 75 74 65 78 20 6d 6f 64 75 6c 65 20 77 69   mutex module wi
a410: 74 68 69 6e 20 53 51 4c 69 74 65 20 64 65 66 69  thin SQLite defi
a420: 6e 65 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  nes [sqlite3_mut
a430: 65 78 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a 20  ex] to be an.** 
a440: 61 62 73 74 72 61 63 74 20 74 79 70 65 20 66 6f  abstract type fo
a450: 72 20 61 20 6d 75 74 65 78 20 6f 62 6a 65 63 74  r a mutex object
a460: 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f  .  The SQLite co
a470: 72 65 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a  re never looks.*
a480: 2a 20 61 74 20 74 68 65 20 69 6e 74 65 72 6e 61  * at the interna
a490: 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e  l representation
a4a0: 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f   of an [sqlite3_
a4b0: 6d 75 74 65 78 5d 2e 20 20 49 74 20 6f 6e 6c 79  mutex].  It only
a4c0: 0a 2a 2a 20 64 65 61 6c 73 20 77 69 74 68 20 70  .** deals with p
a4d0: 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 65 20 5b  ointers to the [
a4e0: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 6f  sqlite3_mutex] o
a4f0: 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74  bject..**.** Mut
a500: 65 78 65 73 20 61 72 65 20 63 72 65 61 74 65 64  exes are created
a510: 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
a520: 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a  mutex_alloc()]..
a530: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
a540: 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20  t sqlite3_mutex 
a550: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a 0a  sqlite3_mutex;..
a560: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
a570: 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f 62 6a  OS Interface Obj
a580: 65 63 74 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73  ect.**.** An ins
a590: 74 61 6e 63 65 20 6f 66 20 74 68 65 20 73 71 6c  tance of the sql
a5a0: 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20  ite3_vfs object 
a5b0: 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65  defines the inte
a5c0: 72 66 61 63 65 20 62 65 74 77 65 65 6e 0a 2a 2a  rface between.**
a5d0: 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   the SQLite core
a5e0: 20 61 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79   and the underly
a5f0: 69 6e 67 20 6f 70 65 72 61 74 69 6e 67 20 73 79  ing operating sy
a600: 73 74 65 6d 2e 20 20 54 68 65 20 22 76 66 73 22  stem.  The "vfs"
a610: 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 6d 65 20  .** in the name 
a620: 6f 66 20 74 68 65 20 6f 62 6a 65 63 74 20 73 74  of the object st
a630: 61 6e 64 73 20 66 6f 72 20 22 76 69 72 74 75 61  ands for "virtua
a640: 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 22 2e 20  l file system". 
a650: 20 53 65 65 0a 2a 2a 20 74 68 65 20 5b 56 46 53   See.** the [VFS
a660: 20 7c 20 56 46 53 20 64 6f 63 75 6d 65 6e 74 61   | VFS documenta
a670: 74 69 6f 6e 5d 20 66 6f 72 20 66 75 72 74 68 65  tion] for furthe
a680: 72 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  r information..*
a690: 2a 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 6f  *.** The value o
a6a0: 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66  f the iVersion f
a6b0: 69 65 6c 64 20 69 73 20 69 6e 69 74 69 61 6c 6c  ield is initiall
a6c0: 79 20 31 20 62 75 74 20 6d 61 79 20 62 65 20 6c  y 1 but may be l
a6d0: 61 72 67 65 72 20 69 6e 0a 2a 2a 20 66 75 74 75  arger in.** futu
a6e0: 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  re versions of S
a6f0: 51 4c 69 74 65 2e 20 20 41 64 64 69 74 69 6f 6e  QLite.  Addition
a700: 61 6c 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65  al fields may be
a710: 20 61 70 70 65 6e 64 65 64 20 74 6f 20 74 68 69   appended to thi
a720: 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 77 68 65 6e  s.** object when
a730: 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 76 61   the iVersion va
a740: 6c 75 65 20 69 73 20 69 6e 63 72 65 61 73 65 64  lue is increased
a750: 2e 20 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65  .  Note that the
a760: 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 6f 66   structure.** of
a770: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73   the sqlite3_vfs
a780: 20 6f 62 6a 65 63 74 20 63 68 61 6e 67 65 73 20   object changes 
a790: 69 6e 20 74 68 65 20 74 72 61 6e 73 61 63 74 69  in the transacti
a7a0: 6f 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 53 51  on between.** SQ
a7b0: 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35  Lite version 3.5
a7c0: 2e 39 20 61 6e 64 20 33 2e 36 2e 30 20 61 6e 64  .9 and 3.6.0 and
a7d0: 20 79 65 74 20 74 68 65 20 69 56 65 72 73 69 6f   yet the iVersio
a7e0: 6e 20 66 69 65 6c 64 20 77 61 73 20 6e 6f 74 0a  n field was not.
a7f0: 2a 2a 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a  ** modified..**.
a800: 2a 2a 20 54 68 65 20 73 7a 4f 73 46 69 6c 65 20  ** The szOsFile 
a810: 66 69 65 6c 64 20 69 73 20 74 68 65 20 73 69 7a  field is the siz
a820: 65 20 6f 66 20 74 68 65 20 73 75 62 63 6c 61 73  e of the subclas
a830: 73 65 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  sed [sqlite3_fil
a840: 65 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20  e].** structure 
a850: 75 73 65 64 20 62 79 20 74 68 69 73 20 56 46 53  used by this VFS
a860: 2e 20 20 6d 78 50 61 74 68 6e 61 6d 65 20 69 73  .  mxPathname is
a870: 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e   the maximum len
a880: 67 74 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74 68  gth of.** a path
a890: 6e 61 6d 65 20 69 6e 20 74 68 69 73 20 56 46 53  name in this VFS
a8a0: 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72  ..**.** Register
a8b0: 65 64 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f  ed sqlite3_vfs o
a8c0: 62 6a 65 63 74 73 20 61 72 65 20 6b 65 70 74 20  bjects are kept 
a8d0: 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73 74  on a linked list
a8e0: 20 66 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74 68   formed by.** th
a8f0: 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e  e pNext pointer.
a900: 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76    The [sqlite3_v
a910: 66 73 5f 72 65 67 69 73 74 65 72 28 29 5d 0a 2a  fs_register()].*
a920: 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 76  * and [sqlite3_v
a930: 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28 29 5d  fs_unregister()]
a940: 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6e 61   interfaces mana
a950: 67 65 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a 20  ge this list.** 
a960: 69 6e 20 61 20 74 68 72 65 61 64 2d 73 61 66 65  in a thread-safe
a970: 20 77 61 79 2e 20 20 54 68 65 20 5b 73 71 6c 69   way.  The [sqli
a980: 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d 20  te3_vfs_find()] 
a990: 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 73 65 61  interface.** sea
a9a0: 72 63 68 65 73 20 74 68 65 20 6c 69 73 74 2e 20  rches the list. 
a9b0: 20 4e 65 69 74 68 65 72 20 74 68 65 20 61 70 70   Neither the app
a9c0: 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 6e 6f  lication code no
a9d0: 72 20 74 68 65 20 56 46 53 0a 2a 2a 20 69 6d 70  r the VFS.** imp
a9e0: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75  lementation shou
a9f0: 6c 64 20 75 73 65 20 74 68 65 20 70 4e 65 78 74  ld use the pNext
aa00: 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
aa10: 54 68 65 20 70 4e 65 78 74 20 66 69 65 6c 64 20  The pNext field 
aa20: 69 73 20 74 68 65 20 6f 6e 6c 79 20 66 69 65 6c  is the only fiel
aa30: 64 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33  d in the sqlite3
aa40: 5f 76 66 73 0a 2a 2a 20 73 74 72 75 63 74 75 72  _vfs.** structur
aa50: 65 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69  e that SQLite wi
aa60: 6c 6c 20 65 76 65 72 20 6d 6f 64 69 66 79 2e 20  ll ever modify. 
aa70: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c   SQLite will onl
aa80: 79 20 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20 6d  y access.** or m
aa90: 6f 64 69 66 79 20 74 68 69 73 20 66 69 65 6c 64  odify this field
aaa0: 20 77 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20 61   while holding a
aab0: 20 70 61 72 74 69 63 75 6c 61 72 20 73 74 61 74   particular stat
aac0: 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68 65  ic mutex..** The
aad0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f   application sho
aae0: 75 6c 64 20 6e 65 76 65 72 20 6d 6f 64 69 66 79  uld never modify
aaf0: 20 61 6e 79 74 68 69 6e 67 20 77 69 74 68 69 6e   anything within
ab00: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73   the sqlite3_vfs
ab10: 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65 20  .** object once 
ab20: 74 68 65 20 6f 62 6a 65 63 74 20 68 61 73 20 62  the object has b
ab30: 65 65 6e 20 72 65 67 69 73 74 65 72 65 64 2e 0a  een registered..
ab40: 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65 20  **.** The zName 
ab50: 66 69 65 6c 64 20 68 6f 6c 64 73 20 74 68 65 20  field holds the 
ab60: 6e 61 6d 65 20 6f 66 20 74 68 65 20 56 46 53 20  name of the VFS 
ab70: 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20 6e 61 6d  module.  The nam
ab80: 65 20 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e 69  e must.** be uni
ab90: 71 75 65 20 61 63 72 6f 73 73 20 61 6c 6c 20 56  que across all V
aba0: 46 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a  FS modules..**.*
abb0: 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  * [[sqlite3_vfs.
abc0: 78 4f 70 65 6e 5d 5d 0a 2a 2a 20 5e 53 51 4c 69  xOpen]].** ^SQLi
abd0: 74 65 20 67 75 61 72 61 6e 74 65 65 73 20 74 68  te guarantees th
abe0: 61 74 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65  at the zFilename
abf0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f   parameter to xO
ac00: 70 65 6e 0a 2a 2a 20 69 73 20 65 69 74 68 65 72  pen.** is either
ac10: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
ac20: 6f 72 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e  or string obtain
ac30: 65 64 0a 2a 2a 20 66 72 6f 6d 20 78 46 75 6c 6c  ed.** from xFull
ac40: 50 61 74 68 6e 61 6d 65 28 29 20 77 69 74 68 20  Pathname() with 
ac50: 61 6e 20 6f 70 74 69 6f 6e 61 6c 20 73 75 66 66  an optional suff
ac60: 69 78 20 61 64 64 65 64 2e 0a 2a 2a 20 5e 49 66  ix added..** ^If
ac70: 20 61 20 73 75 66 66 69 78 20 69 73 20 61 64 64   a suffix is add
ac80: 65 64 20 74 6f 20 74 68 65 20 7a 46 69 6c 65 6e  ed to the zFilen
ac90: 61 6d 65 20 70 61 72 61 6d 65 74 65 72 2c 20 69  ame parameter, i
aca0: 74 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 73 69 73  t will.** consis
acb0: 74 20 6f 66 20 61 20 73 69 6e 67 6c 65 20 22 2d  t of a single "-
acc0: 22 20 63 68 61 72 61 63 74 65 72 20 66 6f 6c 6c  " character foll
acd0: 6f 77 65 64 20 62 79 20 6e 6f 20 6d 6f 72 65 20  owed by no more 
ace0: 74 68 61 6e 0a 2a 2a 20 31 31 20 61 6c 70 68 61  than.** 11 alpha
acf0: 6e 75 6d 65 72 69 63 20 61 6e 64 2f 6f 72 20 22  numeric and/or "
ad00: 2d 22 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a  -" characters..*
ad10: 2a 20 5e 53 51 4c 69 74 65 20 66 75 72 74 68 65  * ^SQLite furthe
ad20: 72 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61  r guarantees tha
ad30: 74 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20  t.** the string 
ad40: 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 6e  will be valid an
ad50: 64 20 75 6e 63 68 61 6e 67 65 64 20 75 6e 74 69  d unchanged unti
ad60: 6c 20 78 43 6c 6f 73 65 28 29 20 69 73 0a 2a 2a  l xClose() is.**
ad70: 20 63 61 6c 6c 65 64 2e 20 42 65 63 61 75 73 65   called. Because
ad80: 20 6f 66 20 74 68 65 20 70 72 65 76 69 6f 75 73   of the previous
ad90: 20 73 65 6e 74 65 6e 63 65 2c 0a 2a 2a 20 74 68   sentence,.** th
ada0: 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  e [sqlite3_file]
adb0: 20 63 61 6e 20 73 61 66 65 6c 79 20 73 74 6f 72   can safely stor
adc0: 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  e a pointer to t
add0: 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69  he.** filename i
ade0: 66 20 69 74 20 6e 65 65 64 73 20 74 6f 20 72 65  f it needs to re
adf0: 6d 65 6d 62 65 72 20 74 68 65 20 66 69 6c 65 6e  member the filen
ae00: 61 6d 65 20 66 6f 72 20 73 6f 6d 65 20 72 65 61  ame for some rea
ae10: 73 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 20 7a  son..** If the z
ae20: 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74  Filename paramet
ae30: 65 72 20 74 6f 20 78 4f 70 65 6e 20 69 73 20 61  er to xOpen is a
ae40: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68   NULL pointer th
ae50: 65 6e 20 78 4f 70 65 6e 0a 2a 2a 20 6d 75 73 74  en xOpen.** must
ae60: 20 69 6e 76 65 6e 74 20 69 74 73 20 6f 77 6e 20   invent its own 
ae70: 74 65 6d 70 6f 72 61 72 79 20 6e 61 6d 65 20 66  temporary name f
ae80: 6f 72 20 74 68 65 20 66 69 6c 65 2e 20 20 5e 57  or the file.  ^W
ae90: 68 65 6e 65 76 65 72 20 74 68 65 20 0a 2a 2a 20  henever the .** 
aea0: 78 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65  xFilename parame
aeb0: 74 65 72 20 69 73 20 4e 55 4c 4c 20 69 74 20 77  ter is NULL it w
aec0: 69 6c 6c 20 61 6c 73 6f 20 62 65 20 74 68 65 20  ill also be the 
aed0: 63 61 73 65 20 74 68 61 74 20 74 68 65 0a 2a 2a  case that the.**
aee0: 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72   flags parameter
aef0: 20 77 69 6c 6c 20 69 6e 63 6c 75 64 65 20 5b 53   will include [S
af00: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54  QLITE_OPEN_DELET
af10: 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a  EONCLOSE]..**.**
af20: 20 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d   The flags argum
af30: 65 6e 74 20 74 6f 20 78 4f 70 65 6e 28 29 20 69  ent to xOpen() i
af40: 6e 63 6c 75 64 65 73 20 61 6c 6c 20 62 69 74 73  ncludes all bits
af50: 20 73 65 74 20 69 6e 0a 2a 2a 20 74 68 65 20 66   set in.** the f
af60: 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f  lags argument to
af70: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
af80: 32 28 29 5d 2e 20 20 4f 72 20 69 66 20 5b 73 71  2()].  Or if [sq
af90: 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a  lite3_open()].**
afa0: 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   or [sqlite3_ope
afb0: 6e 31 36 28 29 5d 20 69 73 20 75 73 65 64 2c 20  n16()] is used, 
afc0: 74 68 65 6e 20 66 6c 61 67 73 20 69 6e 63 6c 75  then flags inclu
afd0: 64 65 73 20 61 74 20 6c 65 61 73 74 0a 2a 2a 20  des at least.** 
afe0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
aff0: 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54  DWRITE] | [SQLIT
b000: 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 2e 20  E_OPEN_CREATE]. 
b010: 0a 2a 2a 20 49 66 20 78 4f 70 65 6e 28 29 20 6f  .** If xOpen() o
b020: 70 65 6e 73 20 61 20 66 69 6c 65 20 72 65 61 64  pens a file read
b030: 2d 6f 6e 6c 79 20 74 68 65 6e 20 69 74 20 73 65  -only then it se
b040: 74 73 20 2a 70 4f 75 74 46 6c 61 67 73 20 74 6f  ts *pOutFlags to
b050: 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c  .** include [SQL
b060: 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c  ITE_OPEN_READONL
b070: 59 5d 2e 20 20 4f 74 68 65 72 20 62 69 74 73 20  Y].  Other bits 
b080: 69 6e 20 2a 70 4f 75 74 46 6c 61 67 73 20 6d 61  in *pOutFlags ma
b090: 79 20 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20  y be set..**.** 
b0a0: 5e 28 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c  ^(SQLite will al
b0b0: 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68  so add one of th
b0c0: 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67  e following flag
b0d0: 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29  s to the xOpen()
b0e0: 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 70 65 6e 64  .** call, depend
b0f0: 69 6e 67 20 6f 6e 20 74 68 65 20 6f 62 6a 65 63  ing on the objec
b100: 74 20 62 65 69 6e 67 20 6f 70 65 6e 65 64 3a 0a  t being opened:.
b110: 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
b120: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
b130: 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69  _MAIN_DB].** <li
b140: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
b150: 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a  MAIN_JOURNAL].**
b160: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
b170: 50 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a 2a 20  PEN_TEMP_DB].** 
b180: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
b190: 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d  EN_TEMP_JOURNAL]
b1a0: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
b1b0: 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54  E_OPEN_TRANSIENT
b1c0: 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  _DB].** <li>  [S
b1d0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f  QLITE_OPEN_SUBJO
b1e0: 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  URNAL].** <li>  
b1f0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53  [SQLITE_OPEN_MAS
b200: 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20  TER_JOURNAL].** 
b210: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
b220: 45 4e 5f 57 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e  EN_WAL].** </ul>
b230: 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 6c  )^.**.** The fil
b240: 65 20 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74 61  e I/O implementa
b250: 74 69 6f 6e 20 63 61 6e 20 75 73 65 20 74 68 65  tion can use the
b260: 20 6f 62 6a 65 63 74 20 74 79 70 65 20 66 6c 61   object type fla
b270: 67 73 20 74 6f 0a 2a 2a 20 63 68 61 6e 67 65 20  gs to.** change 
b280: 74 68 65 20 77 61 79 20 69 74 20 64 65 61 6c 73  the way it deals
b290: 20 77 69 74 68 20 66 69 6c 65 73 2e 20 20 46 6f   with files.  Fo
b2a0: 72 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70  r example, an ap
b2b0: 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 74 68 61  plication.** tha
b2c0: 74 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20  t does not care 
b2d0: 61 62 6f 75 74 20 63 72 61 73 68 20 72 65 63 6f  about crash reco
b2e0: 76 65 72 79 20 6f 72 20 72 6f 6c 6c 62 61 63 6b  very or rollback
b2f0: 20 6d 69 67 68 74 20 6d 61 6b 65 0a 2a 2a 20 74   might make.** t
b300: 68 65 20 6f 70 65 6e 20 6f 66 20 61 20 6a 6f 75  he open of a jou
b310: 72 6e 61 6c 20 66 69 6c 65 20 61 20 6e 6f 2d 6f  rnal file a no-o
b320: 70 2e 20 20 57 72 69 74 65 73 20 74 6f 20 74 68  p.  Writes to th
b330: 69 73 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64  is journal would
b340: 0a 2a 2a 20 61 6c 73 6f 20 62 65 20 6e 6f 2d 6f  .** also be no-o
b350: 70 73 2c 20 61 6e 64 20 61 6e 79 20 61 74 74 65  ps, and any atte
b360: 6d 70 74 20 74 6f 20 72 65 61 64 20 74 68 65 20  mpt to read the 
b370: 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 20 72 65  journal would re
b380: 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 49  turn.** SQLITE_I
b390: 4f 45 52 52 2e 20 20 4f 72 20 74 68 65 20 69 6d  OERR.  Or the im
b3a0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 67  plementation mig
b3b0: 68 74 20 72 65 63 6f 67 6e 69 7a 65 20 74 68 61  ht recognize tha
b3c0: 74 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  t a database.** 
b3d0: 66 69 6c 65 20 77 69 6c 6c 20 62 65 20 64 6f 69  file will be doi
b3e0: 6e 67 20 70 61 67 65 2d 61 6c 69 67 6e 65 64 20  ng page-aligned 
b3f0: 73 65 63 74 6f 72 20 72 65 61 64 73 20 61 6e 64  sector reads and
b400: 20 77 72 69 74 65 73 20 69 6e 20 61 20 72 61 6e   writes in a ran
b410: 64 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20 61 6e 64  dom.** order and
b420: 20 73 65 74 20 75 70 20 69 74 73 20 49 2f 4f 20   set up its I/O 
b430: 73 75 62 73 79 73 74 65 6d 20 61 63 63 6f 72 64  subsystem accord
b440: 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c  ingly..**.** SQL
b450: 69 74 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 61  ite might also a
b460: 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f  dd one of the fo
b470: 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f  llowing flags to
b480: 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f   the xOpen metho
b490: 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  d:.**.** <ul>.**
b4a0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50   <li> [SQLITE_OP
b4b0: 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45  EN_DELETEONCLOSE
b4c0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
b4d0: 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45  E_OPEN_EXCLUSIVE
b4e0: 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  ].** </ul>.**.**
b4f0: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   The [SQLITE_OPE
b500: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d  N_DELETEONCLOSE]
b510: 20 66 6c 61 67 20 6d 65 61 6e 73 20 74 68 65 20   flag means the 
b520: 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a  file should be.*
b530: 2a 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20 69  * deleted when i
b540: 74 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 5e 54  t is closed.  ^T
b550: 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
b560: 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a  DELETEONCLOSE].*
b570: 2a 20 77 69 6c 6c 20 62 65 20 73 65 74 20 66 6f  * will be set fo
b580: 72 20 54 45 4d 50 20 64 61 74 61 62 61 73 65 73  r TEMP databases
b590: 20 61 6e 64 20 74 68 65 69 72 20 6a 6f 75 72 6e   and their journ
b5a0: 61 6c 73 2c 20 74 72 61 6e 73 69 65 6e 74 0a 2a  als, transient.*
b5b0: 2a 20 64 61 74 61 62 61 73 65 73 2c 20 61 6e 64  * databases, and
b5c0: 20 73 75 62 6a 6f 75 72 6e 61 6c 73 2e 0a 2a 2a   subjournals..**
b5d0: 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
b5e0: 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d  _OPEN_EXCLUSIVE]
b5f0: 20 66 6c 61 67 20 69 73 20 61 6c 77 61 79 73 20   flag is always 
b600: 75 73 65 64 20 69 6e 20 63 6f 6e 6a 75 6e 63 74  used in conjunct
b610: 69 6f 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  ion.** with the 
b620: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45  [SQLITE_OPEN_CRE
b630: 41 54 45 5d 20 66 6c 61 67 2c 20 77 68 69 63 68  ATE] flag, which
b640: 20 61 72 65 20 62 6f 74 68 20 64 69 72 65 63 74   are both direct
b650: 6c 79 0a 2a 2a 20 61 6e 61 6c 6f 67 6f 75 73 20  ly.** analogous 
b660: 74 6f 20 74 68 65 20 4f 5f 45 58 43 4c 20 61 6e  to the O_EXCL an
b670: 64 20 4f 5f 43 52 45 41 54 20 66 6c 61 67 73 20  d O_CREAT flags 
b680: 6f 66 20 74 68 65 20 50 4f 53 49 58 20 6f 70 65  of the POSIX ope
b690: 6e 28 29 0a 2a 2a 20 41 50 49 2e 20 20 54 68 65  n().** API.  The
b6a0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43   SQLITE_OPEN_EXC
b6b0: 4c 55 53 49 56 45 20 66 6c 61 67 2c 20 77 68 65  LUSIVE flag, whe
b6c0: 6e 20 70 61 69 72 65 64 20 77 69 74 68 20 74 68  n paired with th
b6d0: 65 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 50 45  e .** SQLITE_OPE
b6e0: 4e 5f 43 52 45 41 54 45 2c 20 69 73 20 75 73 65  N_CREATE, is use
b6f0: 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68  d to indicate th
b700: 61 74 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 61  at file should a
b710: 6c 77 61 79 73 0a 2a 2a 20 62 65 20 63 72 65 61  lways.** be crea
b720: 74 65 64 2c 20 61 6e 64 20 74 68 61 74 20 69 74  ted, and that it
b730: 20 69 73 20 61 6e 20 65 72 72 6f 72 20 69 66 20   is an error if 
b740: 69 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74  it already exist
b750: 73 2e 0a 2a 2a 20 49 74 20 69 73 20 3c 69 3e 6e  s..** It is <i>n
b760: 6f 74 3c 2f 69 3e 20 75 73 65 64 20 74 6f 20 69  ot</i> used to i
b770: 6e 64 69 63 61 74 65 20 74 68 65 20 66 69 6c 65  ndicate the file
b780: 20 73 68 6f 75 6c 64 20 62 65 20 6f 70 65 6e 65   should be opene
b790: 64 20 0a 2a 2a 20 66 6f 72 20 65 78 63 6c 75 73  d .** for exclus
b7a0: 69 76 65 20 61 63 63 65 73 73 2e 0a 2a 2a 0a 2a  ive access..**.*
b7b0: 2a 20 5e 41 74 20 6c 65 61 73 74 20 73 7a 4f 73  * ^At least szOs
b7c0: 46 69 6c 65 20 62 79 74 65 73 20 6f 66 20 6d 65  File bytes of me
b7d0: 6d 6f 72 79 20 61 72 65 20 61 6c 6c 6f 63 61 74  mory are allocat
b7e0: 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20  ed by SQLite.** 
b7f0: 74 6f 20 68 6f 6c 64 20 74 68 65 20 20 5b 73 71  to hold the  [sq
b800: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 73 74 72 75  lite3_file] stru
b810: 63 74 75 72 65 20 70 61 73 73 65 64 20 61 73 20  cture passed as 
b820: 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 61 72 67  the third.** arg
b830: 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 2e 20  ument to xOpen. 
b840: 20 54 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f   The xOpen metho
b850: 64 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20  d does not have 
b860: 74 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 74  to.** allocate t
b870: 68 65 20 73 74 72 75 63 74 75 72 65 3b 20 69 74  he structure; it
b880: 20 73 68 6f 75 6c 64 20 6a 75 73 74 20 66 69 6c   should just fil
b890: 6c 20 69 74 20 69 6e 2e 20 20 4e 6f 74 65 20 74  l it in.  Note t
b8a0: 68 61 74 0a 2a 2a 20 74 68 65 20 78 4f 70 65 6e  hat.** the xOpen
b8b0: 20 6d 65 74 68 6f 64 20 6d 75 73 74 20 73 65 74   method must set
b8c0: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c   the sqlite3_fil
b8d0: 65 2e 70 4d 65 74 68 6f 64 73 20 74 6f 20 65 69  e.pMethods to ei
b8e0: 74 68 65 72 0a 2a 2a 20 61 20 76 61 6c 69 64 20  ther.** a valid 
b8f0: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
b900: 6f 64 73 5d 20 6f 62 6a 65 63 74 20 6f 72 20 74  ods] object or t
b910: 6f 20 4e 55 4c 4c 2e 20 20 78 4f 70 65 6e 20 6d  o NULL.  xOpen m
b920: 75 73 74 20 64 6f 0a 2a 2a 20 74 68 69 73 20 65  ust do.** this e
b930: 76 65 6e 20 69 66 20 74 68 65 20 6f 70 65 6e 20  ven if the open 
b940: 66 61 69 6c 73 2e 20 20 53 51 4c 69 74 65 20 65  fails.  SQLite e
b950: 78 70 65 63 74 73 20 74 68 61 74 20 74 68 65 20  xpects that the 
b960: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65  sqlite3_file.pMe
b970: 74 68 6f 64 73 0a 2a 2a 20 65 6c 65 6d 65 6e 74  thods.** element
b980: 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61   will be valid a
b990: 66 74 65 72 20 78 4f 70 65 6e 20 72 65 74 75 72  fter xOpen retur
b9a0: 6e 73 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66  ns regardless of
b9b0: 20 74 68 65 20 73 75 63 63 65 73 73 0a 2a 2a 20   the success.** 
b9c0: 6f 72 20 66 61 69 6c 75 72 65 20 6f 66 20 74 68  or failure of th
b9d0: 65 20 78 4f 70 65 6e 20 63 61 6c 6c 2e 0a 2a 2a  e xOpen call..**
b9e0: 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66  .** [[sqlite3_vf
b9f0: 73 2e 78 41 63 63 65 73 73 5d 5d 0a 2a 2a 20 5e  s.xAccess]].** ^
ba00: 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65  The flags argume
ba10: 6e 74 20 74 6f 20 78 41 63 63 65 73 73 28 29 20  nt to xAccess() 
ba20: 6d 61 79 20 62 65 20 5b 53 51 4c 49 54 45 5f 41  may be [SQLITE_A
ba30: 43 43 45 53 53 5f 45 58 49 53 54 53 5d 0a 2a 2a  CCESS_EXISTS].**
ba40: 20 74 6f 20 74 65 73 74 20 66 6f 72 20 74 68 65   to test for the
ba50: 20 65 78 69 73 74 65 6e 63 65 20 6f 66 20 61 20   existence of a 
ba60: 66 69 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45  file, or [SQLITE
ba70: 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54  _ACCESS_READWRIT
ba80: 45 5d 20 74 6f 0a 2a 2a 20 74 65 73 74 20 77 68  E] to.** test wh
ba90: 65 74 68 65 72 20 61 20 66 69 6c 65 20 69 73 20  ether a file is 
baa0: 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69  readable and wri
bab0: 74 61 62 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54  table, or [SQLIT
bac0: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 5d 0a 2a  E_ACCESS_READ].*
bad0: 2a 20 74 6f 20 74 65 73 74 20 77 68 65 74 68 65  * to test whethe
bae0: 72 20 61 20 66 69 6c 65 20 69 73 20 61 74 20 6c  r a file is at l
baf0: 65 61 73 74 20 72 65 61 64 61 62 6c 65 2e 20 20  east readable.  
bb00: 20 54 68 65 20 66 69 6c 65 20 63 61 6e 20 62 65   The file can be
bb10: 20 61 0a 2a 2a 20 64 69 72 65 63 74 6f 72 79 2e   a.** directory.
bb20: 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77  .**.** ^SQLite w
bb30: 69 6c 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f 63  ill always alloc
bb40: 61 74 65 20 61 74 20 6c 65 61 73 74 20 6d 78 50  ate at least mxP
bb50: 61 74 68 6e 61 6d 65 2b 31 20 62 79 74 65 73 20  athname+1 bytes 
bb60: 66 6f 72 20 74 68 65 0a 2a 2a 20 6f 75 74 70 75  for the.** outpu
bb70: 74 20 62 75 66 66 65 72 20 78 46 75 6c 6c 50 61  t buffer xFullPa
bb80: 74 68 6e 61 6d 65 2e 20 20 54 68 65 20 65 78 61  thname.  The exa
bb90: 63 74 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6f  ct size of the o
bba0: 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20  utput buffer.** 
bbb0: 69 73 20 61 6c 73 6f 20 70 61 73 73 65 64 20 61  is also passed a
bbc0: 73 20 61 20 70 61 72 61 6d 65 74 65 72 20 74 6f  s a parameter to
bbd0: 20 62 6f 74 68 20 20 6d 65 74 68 6f 64 73 2e 20   both  methods. 
bbe0: 49 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75  If the output bu
bbf0: 66 66 65 72 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c  ffer.** is not l
bc00: 61 72 67 65 20 65 6e 6f 75 67 68 2c 20 5b 53 51  arge enough, [SQ
bc10: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 73  LITE_CANTOPEN] s
bc20: 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65  hould be returne
bc30: 64 2e 20 53 69 6e 63 65 20 74 68 69 73 20 69 73  d. Since this is
bc40: 0a 2a 2a 20 68 61 6e 64 6c 65 64 20 61 73 20 61  .** handled as a
bc50: 20 66 61 74 61 6c 20 65 72 72 6f 72 20 62 79 20   fatal error by 
bc60: 53 51 4c 69 74 65 2c 20 76 66 73 20 69 6d 70 6c  SQLite, vfs impl
bc70: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75  ementations shou
bc80: 6c 64 20 65 6e 64 65 61 76 6f 72 0a 2a 2a 20 74  ld endeavor.** t
bc90: 6f 20 70 72 65 76 65 6e 74 20 74 68 69 73 20 62  o prevent this b
bca0: 79 20 73 65 74 74 69 6e 67 20 6d 78 50 61 74 68  y setting mxPath
bcb0: 6e 61 6d 65 20 74 6f 20 61 20 73 75 66 66 69 63  name to a suffic
bcc0: 69 65 6e 74 6c 79 20 6c 61 72 67 65 20 76 61 6c  iently large val
bcd0: 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52  ue..**.** The xR
bce0: 61 6e 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53 6c  andomness(), xSl
bcf0: 65 65 70 28 29 2c 20 78 43 75 72 72 65 6e 74 54  eep(), xCurrentT
bd00: 69 6d 65 28 29 2c 20 61 6e 64 20 78 43 75 72 72  ime(), and xCurr
bd10: 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 0a 2a  entTimeInt64().*
bd20: 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  * interfaces are
bd30: 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 61 20   not strictly a 
bd40: 70 61 72 74 20 6f 66 20 74 68 65 20 66 69 6c 65  part of the file
bd50: 73 79 73 74 65 6d 2c 20 62 75 74 20 74 68 65 79  system, but they
bd60: 20 61 72 65 0a 2a 2a 20 69 6e 63 6c 75 64 65 64   are.** included
bd70: 20 69 6e 20 74 68 65 20 56 46 53 20 73 74 72 75   in the VFS stru
bd80: 63 74 75 72 65 20 66 6f 72 20 63 6f 6d 70 6c 65  cture for comple
bd90: 74 65 6e 65 73 73 2e 0a 2a 2a 20 54 68 65 20 78  teness..** The x
bda0: 52 61 6e 64 6f 6d 6e 65 73 73 28 29 20 66 75 6e  Randomness() fun
bdb0: 63 74 69 6f 6e 20 61 74 74 65 6d 70 74 73 20 74  ction attempts t
bdc0: 6f 20 72 65 74 75 72 6e 20 6e 42 79 74 65 73 20  o return nBytes 
bdd0: 62 79 74 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64  bytes.** of good
bde0: 2d 71 75 61 6c 69 74 79 20 72 61 6e 64 6f 6d 6e  -quality randomn
bdf0: 65 73 73 20 69 6e 74 6f 20 7a 4f 75 74 2e 20 20  ess into zOut.  
be00: 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  The return value
be10: 20 69 73 0a 2a 2a 20 74 68 65 20 61 63 74 75 61   is.** the actua
be20: 6c 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  l number of byte
be30: 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20  s of randomness 
be40: 6f 62 74 61 69 6e 65 64 2e 0a 2a 2a 20 54 68 65  obtained..** The
be50: 20 78 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64   xSleep() method
be60: 20 63 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c   causes the call
be70: 69 6e 67 20 74 68 72 65 61 64 20 74 6f 20 73 6c  ing thread to sl
be80: 65 65 70 20 66 6f 72 20 61 74 0a 2a 2a 20 6c 65  eep for at.** le
be90: 61 73 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  ast the number o
bea0: 66 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 20 67  f microseconds g
beb0: 69 76 65 6e 2e 20 20 5e 54 68 65 20 78 43 75 72  iven.  ^The xCur
bec0: 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a 20 6d 65  rentTime().** me
bed0: 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 4a  thod returns a J
bee0: 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d 62 65 72  ulian Day Number
bef0: 20 66 6f 72 20 74 68 65 20 63 75 72 72 65 6e 74   for the current
bf00: 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20 61   date and time a
bf10: 73 0a 2a 2a 20 61 20 66 6c 6f 61 74 69 6e 67 20  s.** a floating 
bf20: 70 6f 69 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a 20  point value..** 
bf30: 5e 54 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d  ^The xCurrentTim
bf40: 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20  eInt64() method 
bf50: 72 65 74 75 72 6e 73 2c 20 61 73 20 61 6e 20 69  returns, as an i
bf60: 6e 74 65 67 65 72 2c 20 74 68 65 20 4a 75 6c 69  nteger, the Juli
bf70: 61 6e 0a 2a 2a 20 44 61 79 20 4e 75 6d 62 65 72  an.** Day Number
bf80: 20 6d 75 6c 74 69 70 6c 69 65 64 20 62 79 20 38   multiplied by 8
bf90: 36 34 30 30 30 30 30 20 28 74 68 65 20 6e 75 6d  6400000 (the num
bfa0: 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f  ber of milliseco
bfb0: 6e 64 73 20 69 6e 20 0a 2a 2a 20 61 20 32 34 2d  nds in .** a 24-
bfc0: 68 6f 75 72 20 64 61 79 29 2e 20 20 0a 2a 2a 20  hour day).  .** 
bfd0: 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65  ^SQLite will use
bfe0: 20 74 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d   the xCurrentTim
bff0: 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20  eInt64() method 
c000: 74 6f 20 67 65 74 20 74 68 65 20 63 75 72 72 65  to get the curre
c010: 6e 74 0a 2a 2a 20 64 61 74 65 20 61 6e 64 20 74  nt.** date and t
c020: 69 6d 65 20 69 66 20 74 68 61 74 20 6d 65 74 68  ime if that meth
c030: 6f 64 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20  od is available 
c040: 28 69 66 20 69 56 65 72 73 69 6f 6e 20 69 73 20  (if iVersion is 
c050: 32 20 6f 72 20 0a 2a 2a 20 67 72 65 61 74 65 72  2 or .** greater
c060: 20 61 6e 64 20 74 68 65 20 66 75 6e 63 74 69 6f   and the functio
c070: 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74  n pointer is not
c080: 20 4e 55 4c 4c 29 20 61 6e 64 20 77 69 6c 6c 20   NULL) and will 
c090: 66 61 6c 6c 20 62 61 63 6b 0a 2a 2a 20 74 6f 20  fall back.** to 
c0a0: 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 20 69  xCurrentTime() i
c0b0: 66 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e  f xCurrentTimeIn
c0c0: 74 36 34 28 29 20 69 73 20 75 6e 61 76 61 69 6c  t64() is unavail
c0d0: 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  able..**.** ^The
c0e0: 20 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 28   xSetSystemCall(
c0f0: 29 2c 20 78 47 65 74 53 79 73 74 65 6d 43 61 6c  ), xGetSystemCal
c100: 6c 28 29 2c 20 61 6e 64 20 78 4e 65 73 74 53 79  l(), and xNestSy
c110: 73 74 65 6d 43 61 6c 6c 28 29 20 69 6e 74 65 72  stemCall() inter
c120: 66 61 63 65 73 0a 2a 2a 20 61 72 65 20 6e 6f 74  faces.** are not
c130: 20 75 73 65 64 20 62 79 20 74 68 65 20 53 51 4c   used by the SQL
c140: 69 74 65 20 63 6f 72 65 2e 20 20 54 68 65 73 65  ite core.  These
c150: 20 6f 70 74 69 6f 6e 61 6c 20 69 6e 74 65 72 66   optional interf
c160: 61 63 65 73 20 61 72 65 20 70 72 6f 76 69 64 65  aces are provide
c170: 64 0a 2a 2a 20 62 79 20 73 6f 6d 65 20 56 46 53  d.** by some VFS
c180: 65 73 20 74 6f 20 66 61 63 69 6c 69 74 61 74 65  es to facilitate
c190: 20 74 65 73 74 69 6e 67 20 6f 66 20 74 68 65 20   testing of the 
c1a0: 56 46 53 20 63 6f 64 65 2e 20 42 79 20 6f 76 65  VFS code. By ove
c1b0: 72 72 69 64 69 6e 67 20 0a 2a 2a 20 73 79 73 74  rriding .** syst
c1c0: 65 6d 20 63 61 6c 6c 73 20 77 69 74 68 20 66 75  em calls with fu
c1d0: 6e 63 74 69 6f 6e 73 20 75 6e 64 65 72 20 69 74  nctions under it
c1e0: 73 20 63 6f 6e 74 72 6f 6c 2c 20 61 20 74 65 73  s control, a tes
c1f0: 74 20 70 72 6f 67 72 61 6d 20 63 61 6e 0a 2a 2a  t program can.**
c200: 20 73 69 6d 75 6c 61 74 65 20 66 61 75 6c 74 73   simulate faults
c210: 20 61 6e 64 20 65 72 72 6f 72 20 63 6f 6e 64 69   and error condi
c220: 74 69 6f 6e 73 20 74 68 61 74 20 77 6f 75 6c 64  tions that would
c230: 20 6f 74 68 65 72 77 69 73 65 20 62 65 20 64 69   otherwise be di
c240: 66 66 69 63 75 6c 74 0a 2a 2a 20 6f 72 20 69 6d  fficult.** or im
c250: 70 6f 73 73 69 62 6c 65 20 74 6f 20 69 6e 64 75  possible to indu
c260: 63 65 2e 20 20 54 68 65 20 73 65 74 20 6f 66 20  ce.  The set of 
c270: 73 79 73 74 65 6d 20 63 61 6c 6c 73 20 74 68 61  system calls tha
c280: 74 20 63 61 6e 20 62 65 20 6f 76 65 72 72 69 64  t can be overrid
c290: 64 65 6e 0a 2a 2a 20 76 61 72 69 65 73 20 66 72  den.** varies fr
c2a0: 6f 6d 20 6f 6e 65 20 56 46 53 20 74 6f 20 61 6e  om one VFS to an
c2b0: 6f 74 68 65 72 2c 20 61 6e 64 20 66 72 6f 6d 20  other, and from 
c2c0: 6f 6e 65 20 76 65 72 73 69 6f 6e 20 6f 66 20 74  one version of t
c2d0: 68 65 20 73 61 6d 65 20 56 46 53 20 74 6f 20 74  he same VFS to t
c2e0: 68 65 0a 2a 2a 20 6e 65 78 74 2e 20 20 41 70 70  he.** next.  App
c2f0: 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 75  lications that u
c300: 73 65 20 74 68 65 73 65 20 69 6e 74 65 72 66 61  se these interfa
c310: 63 65 73 20 6d 75 73 74 20 62 65 20 70 72 65 70  ces must be prep
c320: 61 72 65 64 20 66 6f 72 20 61 6e 79 0a 2a 2a 20  ared for any.** 
c330: 6f 72 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20  or all of these 
c340: 69 6e 74 65 72 66 61 63 65 73 20 74 6f 20 62 65  interfaces to be
c350: 20 4e 55 4c 4c 20 6f 72 20 66 6f 72 20 74 68 65   NULL or for the
c360: 69 72 20 62 65 68 61 76 69 6f 72 20 74 6f 20 63  ir behavior to c
c370: 68 61 6e 67 65 0a 2a 2a 20 66 72 6f 6d 20 6f 6e  hange.** from on
c380: 65 20 72 65 6c 65 61 73 65 20 74 6f 20 74 68 65  e release to the
c390: 20 6e 65 78 74 2e 20 20 41 70 70 6c 69 63 61 74   next.  Applicat
c3a0: 69 6f 6e 73 20 6d 75 73 74 20 6e 6f 74 20 61 74  ions must not at
c3b0: 74 65 6d 70 74 20 74 6f 20 61 63 63 65 73 73 0a  tempt to access.
c3c0: 2a 2a 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20  ** any of these 
c3d0: 6d 65 74 68 6f 64 73 20 69 66 20 74 68 65 20 69  methods if the i
c3e0: 56 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 56  Version of the V
c3f0: 46 53 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20  FS is less than 
c400: 33 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  3..*/.typedef st
c410: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73  ruct sqlite3_vfs
c420: 20 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a 74 79   sqlite3_vfs;.ty
c430: 70 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c  pedef void (*sql
c440: 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72  ite3_syscall_ptr
c450: 29 28 76 6f 69 64 29 3b 0a 73 74 72 75 63 74 20  )(void);.struct 
c460: 73 71 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20 20  sqlite3_vfs {.  
c470: 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 20 20 20  int iVersion;   
c480: 20 20 20 20 20 20 20 20 20 2f 2a 20 53 74 72 75           /* Stru
c490: 63 74 75 72 65 20 76 65 72 73 69 6f 6e 20 6e 75  cture version nu
c4a0: 6d 62 65 72 20 28 63 75 72 72 65 6e 74 6c 79 20  mber (currently 
c4b0: 33 29 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73  3) */.  int szOs
c4c0: 46 69 6c 65 3b 20 20 20 20 20 20 20 20 20 20 20  File;           
c4d0: 20 2f 2a 20 53 69 7a 65 20 6f 66 20 73 75 62 63   /* Size of subc
c4e0: 6c 61 73 73 65 64 20 73 71 6c 69 74 65 33 5f 66  lassed sqlite3_f
c4f0: 69 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50  ile */.  int mxP
c500: 61 74 68 6e 61 6d 65 3b 20 20 20 20 20 20 20 20  athname;        
c510: 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c    /* Maximum fil
c520: 65 20 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74  e pathname lengt
c530: 68 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76  h */.  sqlite3_v
c540: 66 73 20 2a 70 4e 65 78 74 3b 20 20 20 20 20 20  fs *pNext;      
c550: 2f 2a 20 4e 65 78 74 20 72 65 67 69 73 74 65 72  /* Next register
c560: 65 64 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73  ed VFS */.  cons
c570: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20  t char *zName;  
c580: 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20       /* Name of 
c590: 74 68 69 73 20 76 69 72 74 75 61 6c 20 66 69 6c  this virtual fil
c5a0: 65 20 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f  e system */.  vo
c5b0: 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20  id *pAppData;   
c5c0: 20 20 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65         /* Pointe
c5d0: 72 20 74 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e  r to application
c5e0: 2d 73 70 65 63 69 66 69 63 20 64 61 74 61 20 2a  -specific data *
c5f0: 2f 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29  /.  int (*xOpen)
c600: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
c610: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
c620: 2c 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  , sqlite3_file*,
c630: 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
c640: 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a  int flags, int *
c650: 70 4f 75 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e  pOutFlags);.  in
c660: 74 20 28 2a 78 44 65 6c 65 74 65 29 28 73 71 6c  t (*xDelete)(sql
c670: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
c680: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e   char *zName, in
c690: 74 20 73 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e  t syncDir);.  in
c6a0: 74 20 28 2a 78 41 63 63 65 73 73 29 28 73 71 6c  t (*xAccess)(sql
c6b0: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
c6c0: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e   char *zName, in
c6d0: 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 52  t flags, int *pR
c6e0: 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a  esOut);.  int (*
c6f0: 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73  xFullPathname)(s
c700: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
c710: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
c720: 69 6e 74 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a  int nOut, char *
c730: 7a 4f 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28  zOut);.  void *(
c740: 2a 78 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65  *xDlOpen)(sqlite
c750: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
c760: 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a  ar *zFilename);.
c770: 20 20 76 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f    void (*xDlErro
c780: 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  r)(sqlite3_vfs*,
c790: 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72   int nByte, char
c7a0: 20 2a 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f   *zErrMsg);.  vo
c7b0: 69 64 20 28 2a 28 2a 78 44 6c 53 79 6d 29 28 73  id (*(*xDlSym)(s
c7c0: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69 64  qlite3_vfs*,void
c7d0: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
c7e0: 53 79 6d 62 6f 6c 29 29 28 76 6f 69 64 29 3b 0a  Symbol))(void);.
c7f0: 20 20 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73    void (*xDlClos
c800: 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  e)(sqlite3_vfs*,
c810: 20 76 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28   void*);.  int (
c820: 2a 78 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71  *xRandomness)(sq
c830: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20  lite3_vfs*, int 
c840: 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75  nByte, char *zOu
c850: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65  t);.  int (*xSle
c860: 65 70 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ep)(sqlite3_vfs*
c870: 2c 20 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e  , int microsecon
c880: 64 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75  ds);.  int (*xCu
c890: 72 72 65 6e 74 54 69 6d 65 29 28 73 71 6c 69 74  rrentTime)(sqlit
c8a0: 65 33 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a  e3_vfs*, double*
c8b0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 47 65 74 4c  );.  int (*xGetL
c8c0: 61 73 74 45 72 72 6f 72 29 28 73 71 6c 69 74 65  astError)(sqlite
c8d0: 33 5f 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68 61  3_vfs*, int, cha
c8e0: 72 20 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20  r *);.  /*.  ** 
c8f0: 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76  The methods abov
c900: 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e  e are in version
c910: 20 31 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65   1 of the sqlite
c920: 5f 76 66 73 20 6f 62 6a 65 63 74 0a 20 20 2a 2a  _vfs object.  **
c930: 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68   definition.  Th
c940: 6f 73 65 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20  ose that follow 
c950: 61 72 65 20 61 64 64 65 64 20 69 6e 20 76 65 72  are added in ver
c960: 73 69 6f 6e 20 32 20 6f 72 20 6c 61 74 65 72 0a  sion 2 or later.
c970: 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 43 75    */.  int (*xCu
c980: 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 29 28  rrentTimeInt64)(
c990: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 73 71  sqlite3_vfs*, sq
c9a0: 6c 69 74 65 33 5f 69 6e 74 36 34 2a 29 3b 0a 20  lite3_int64*);. 
c9b0: 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74   /*.  ** The met
c9c0: 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69  hods above are i
c9d0: 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 61 6e 64  n versions 1 and
c9e0: 20 32 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65   2 of the sqlite
c9f0: 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a  _vfs object..  *
ca00: 2a 20 54 68 6f 73 65 20 62 65 6c 6f 77 20 61 72  * Those below ar
ca10: 65 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 33 20  e for version 3 
ca20: 61 6e 64 20 67 72 65 61 74 65 72 2e 0a 20 20 2a  and greater..  *
ca30: 2f 0a 20 20 69 6e 74 20 28 2a 78 53 65 74 53 79  /.  int (*xSetSy
ca40: 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65  stemCall)(sqlite
ca50: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
ca60: 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74  ar *zName, sqlit
ca70: 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 3b  e3_syscall_ptr);
ca80: 0a 20 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61  .  sqlite3_sysca
ca90: 6c 6c 5f 70 74 72 20 28 2a 78 47 65 74 53 79 73  ll_ptr (*xGetSys
caa0: 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33  temCall)(sqlite3
cab0: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
cac0: 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 63 6f 6e  r *zName);.  con
cad0: 73 74 20 63 68 61 72 20 2a 28 2a 78 4e 65 78 74  st char *(*xNext
cae0: 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69  SystemCall)(sqli
caf0: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
cb00: 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20  char *zName);.  
cb10: 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68  /*.  ** The meth
cb20: 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e  ods above are in
cb30: 20 76 65 72 73 69 6f 6e 73 20 31 20 74 68 72 6f   versions 1 thro
cb40: 75 67 68 20 33 20 6f 66 20 74 68 65 20 73 71 6c  ugh 3 of the sql
cb50: 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a  ite_vfs object..
cb60: 20 20 2a 2a 20 4e 65 77 20 66 69 65 6c 64 73 20    ** New fields 
cb70: 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 20  may be appended 
cb80: 69 6e 20 66 69 67 75 72 65 20 76 65 72 73 69 6f  in figure versio
cb90: 6e 73 2e 20 20 54 68 65 20 69 56 65 72 73 69 6f  ns.  The iVersio
cba0: 6e 0a 20 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c  n.  ** value wil
cbb0: 6c 20 69 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e  l increment when
cbc0: 65 76 65 72 20 74 68 69 73 20 68 61 70 70 65 6e  ever this happen
cbd0: 73 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a  s. .  */.};../*.
cbe0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61  ** CAPI3REF: Fla
cbf0: 67 73 20 66 6f 72 20 74 68 65 20 78 41 63 63 65  gs for the xAcce
cc00: 73 73 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a  ss VFS method.**
cc10: 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65  .** These intege
cc20: 72 20 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20  r constants can 
cc30: 62 65 20 75 73 65 64 20 61 73 20 74 68 65 20 74  be used as the t
cc40: 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74  hird parameter t
cc50: 6f 0a 2a 2a 20 74 68 65 20 78 41 63 63 65 73 73  o.** the xAccess
cc60: 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73   method of an [s
cc70: 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
cc80: 63 74 2e 20 20 54 68 65 79 20 64 65 74 65 72 6d  ct.  They determ
cc90: 69 6e 65 0a 2a 2a 20 77 68 61 74 20 6b 69 6e 64  ine.** what kind
cca0: 20 6f 66 20 70 65 72 6d 69 73 73 69 6f 6e 73 20   of permissions 
ccb0: 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68  the xAccess meth
ccc0: 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f  od is looking fo
ccd0: 72 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54  r..** With SQLIT
cce0: 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 2c  E_ACCESS_EXISTS,
ccf0: 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74   the xAccess met
cd00: 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68  hod.** simply ch
cd10: 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65  ecks whether the
cd20: 20 66 69 6c 65 20 65 78 69 73 74 73 2e 0a 2a 2a   file exists..**
cd30: 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43   With SQLITE_ACC
cd40: 45 53 53 5f 52 45 41 44 57 52 49 54 45 2c 20 74  ESS_READWRITE, t
cd50: 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f  he xAccess metho
cd60: 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74  d.** checks whet
cd70: 68 65 72 20 74 68 65 20 6e 61 6d 65 64 20 64 69  her the named di
cd80: 72 65 63 74 6f 72 79 20 69 73 20 62 6f 74 68 20  rectory is both 
cd90: 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69  readable and wri
cda0: 74 61 62 6c 65 0a 2a 2a 20 28 69 6e 20 6f 74 68  table.** (in oth
cdb0: 65 72 20 77 6f 72 64 73 2c 20 69 66 20 66 69 6c  er words, if fil
cdc0: 65 73 20 63 61 6e 20 62 65 20 61 64 64 65 64 2c  es can be added,
cdd0: 20 72 65 6d 6f 76 65 64 2c 20 61 6e 64 20 72 65   removed, and re
cde0: 6e 61 6d 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20  named within.** 
cdf0: 74 68 65 20 64 69 72 65 63 74 6f 72 79 29 2e 0a  the directory)..
ce00: 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43  ** The SQLITE_AC
ce10: 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 20 63  CESS_READWRITE c
ce20: 6f 6e 73 74 61 6e 74 20 69 73 20 63 75 72 72 65  onstant is curre
ce30: 6e 74 6c 79 20 75 73 65 64 20 6f 6e 6c 79 20 62  ntly used only b
ce40: 79 20 74 68 65 0a 2a 2a 20 5b 74 65 6d 70 5f 73  y the.** [temp_s
ce50: 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70  tore_directory p
ce60: 72 61 67 6d 61 5d 2c 20 74 68 6f 75 67 68 20 74  ragma], though t
ce70: 68 69 73 20 63 6f 75 6c 64 20 63 68 61 6e 67 65  his could change
ce80: 20 69 6e 20 61 20 66 75 74 75 72 65 0a 2a 2a 20   in a future.** 
ce90: 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74  release of SQLit
cea0: 65 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54  e..** With SQLIT
ceb0: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 2c 20 74  E_ACCESS_READ, t
cec0: 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f  he xAccess metho
ced0: 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74  d.** checks whet
cee0: 68 65 72 20 74 68 65 20 66 69 6c 65 20 69 73 20  her the file is 
cef0: 72 65 61 64 61 62 6c 65 2e 20 20 54 68 65 20 53  readable.  The S
cf00: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
cf10: 44 20 63 6f 6e 73 74 61 6e 74 20 69 73 0a 2a 2a  D constant is.**
cf20: 20 63 75 72 72 65 6e 74 6c 79 20 75 6e 75 73 65   currently unuse
cf30: 64 2c 20 74 68 6f 75 67 68 20 69 74 20 6d 69 67  d, though it mig
cf40: 68 74 20 62 65 20 75 73 65 64 20 69 6e 20 61 20  ht be used in a 
cf50: 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f  future release o
cf60: 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a  f.** SQLite..*/.
cf70: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
cf80: 43 43 45 53 53 5f 45 58 49 53 54 53 20 20 20 20  CCESS_EXISTS    
cf90: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
cfa0: 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54  _ACCESS_READWRIT
cfb0: 45 20 31 20 20 20 2f 2a 20 55 73 65 64 20 62 79  E 1   /* Used by
cfc0: 20 50 52 41 47 4d 41 20 74 65 6d 70 5f 73 74 6f   PRAGMA temp_sto
cfd0: 72 65 5f 64 69 72 65 63 74 6f 72 79 20 2a 2f 0a  re_directory */.
cfe0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
cff0: 43 43 45 53 53 5f 52 45 41 44 20 20 20 20 20 20  CCESS_READ      
d000: 32 20 20 20 2f 2a 20 55 6e 75 73 65 64 20 2a 2f  2   /* Unused */
d010: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
d020: 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20  : Flags for the 
d030: 78 53 68 6d 4c 6f 63 6b 20 56 46 53 20 6d 65 74  xShmLock VFS met
d040: 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  hod.**.** These 
d050: 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74  integer constant
d060: 73 20 64 65 66 69 6e 65 20 74 68 65 20 76 61 72  s define the var
d070: 69 6f 75 73 20 6c 6f 63 6b 69 6e 67 20 6f 70 65  ious locking ope
d080: 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f 77  rations.** allow
d090: 65 64 20 62 79 20 74 68 65 20 78 53 68 6d 4c 6f  ed by the xShmLo
d0a0: 63 6b 20 6d 65 74 68 6f 64 20 6f 66 20 5b 73 71  ck method of [sq
d0b0: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
d0c0: 5d 2e 20 20 54 68 65 0a 2a 2a 20 66 6f 6c 6c 6f  ].  The.** follo
d0d0: 77 69 6e 67 20 61 72 65 20 74 68 65 20 6f 6e 6c  wing are the onl
d0e0: 79 20 6c 65 67 61 6c 20 63 6f 6d 62 69 6e 61 74  y legal combinat
d0f0: 69 6f 6e 73 20 6f 66 20 66 6c 61 67 73 20 74 6f  ions of flags to
d100: 20 74 68 65 0a 2a 2a 20 78 53 68 6d 4c 6f 63 6b   the.** xShmLock
d110: 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c   method:.**.** <
d120: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c  ul>.** <li>  SQL
d130: 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53  ITE_SHM_LOCK | S
d140: 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44  QLITE_SHM_SHARED
d150: 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45  .** <li>  SQLITE
d160: 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49  _SHM_LOCK | SQLI
d170: 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45  TE_SHM_EXCLUSIVE
d180: 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45  .** <li>  SQLITE
d190: 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51  _SHM_UNLOCK | SQ
d1a0: 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a  LITE_SHM_SHARED.
d1b0: 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f  ** <li>  SQLITE_
d1c0: 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c  SHM_UNLOCK | SQL
d1d0: 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56  ITE_SHM_EXCLUSIV
d1e0: 45 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  E.** </ul>.**.**
d1f0: 20 57 68 65 6e 20 75 6e 6c 6f 63 6b 69 6e 67 2c   When unlocking,
d200: 20 74 68 65 20 73 61 6d 65 20 53 48 41 52 45 44   the same SHARED
d210: 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 66 6c   or EXCLUSIVE fl
d220: 61 67 20 6d 75 73 74 20 62 65 20 73 75 70 70 6c  ag must be suppl
d230: 69 65 64 20 61 73 0a 2a 2a 20 77 61 73 20 67 69  ied as.** was gi
d240: 76 65 6e 20 6e 6f 20 74 68 65 20 63 6f 72 72 65  ven no the corre
d250: 73 70 6f 6e 64 69 6e 67 20 6c 6f 63 6b 2e 20 20  sponding lock.  
d260: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c  .**.** The xShmL
d270: 6f 63 6b 20 6d 65 74 68 6f 64 20 63 61 6e 20 74  ock method can t
d280: 72 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65  ransition betwee
d290: 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 53  n unlocked and S
d2a0: 48 41 52 45 44 20 6f 72 0a 2a 2a 20 62 65 74 77  HARED or.** betw
d2b0: 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64  een unlocked and
d2c0: 20 45 58 43 4c 55 53 49 56 45 2e 20 20 49 74 20   EXCLUSIVE.  It 
d2d0: 63 61 6e 6e 6f 74 20 74 72 61 6e 73 69 74 69 6f  cannot transitio
d2e0: 6e 20 62 65 74 77 65 65 6e 20 53 48 41 52 45 44  n between SHARED
d2f0: 0a 2a 2a 20 61 6e 64 20 45 58 43 4c 55 53 49 56  .** and EXCLUSIV
d300: 45 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  E..*/.#define SQ
d310: 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20  LITE_SHM_UNLOCK 
d320: 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20        1.#define 
d330: 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20  SQLITE_SHM_LOCK 
d340: 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e          2.#defin
d350: 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41  e SQLITE_SHM_SHA
d360: 52 45 44 20 20 20 20 20 20 20 34 0a 23 64 65 66  RED       4.#def
d370: 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45  ine SQLITE_SHM_E
d380: 58 43 4c 55 53 49 56 45 20 20 20 20 38 0a 0a 2f  XCLUSIVE    8../
d390: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
d3a0: 61 78 69 6d 75 6d 20 78 53 68 6d 4c 6f 63 6b 20  aximum xShmLock 
d3b0: 69 6e 64 65 78 0a 2a 2a 0a 2a 2a 20 54 68 65 20  index.**.** The 
d3c0: 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20  xShmLock method 
d3d0: 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  on [sqlite3_io_m
d3e0: 65 74 68 6f 64 73 5d 20 6d 61 79 20 75 73 65 20  ethods] may use 
d3f0: 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 65  values.** betwee
d400: 6e 20 30 20 61 6e 64 20 74 68 69 73 20 75 70 70  n 0 and this upp
d410: 65 72 20 62 6f 75 6e 64 20 61 73 20 69 74 73 20  er bound as its 
d420: 22 6f 66 66 73 65 74 22 20 61 72 67 75 6d 65 6e  "offset" argumen
d430: 74 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65  t..** The SQLite
d440: 20 63 6f 72 65 20 77 69 6c 6c 20 6e 65 76 65 72   core will never
d450: 20 61 74 74 65 6d 70 74 20 74 6f 20 61 63 71 75   attempt to acqu
d460: 69 72 65 20 6f 72 20 72 65 6c 65 61 73 65 20 61  ire or release a
d470: 0a 2a 2a 20 6c 6f 63 6b 20 6f 75 74 73 69 64 65  .** lock outside
d480: 20 6f 66 20 74 68 69 73 20 72 61 6e 67 65 0a 2a   of this range.*
d490: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
d4a0: 5f 53 48 4d 5f 4e 4c 4f 43 4b 20 20 20 20 20 20  _SHM_NLOCK      
d4b0: 20 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49    8.../*.** CAPI
d4c0: 33 52 45 46 3a 20 49 6e 69 74 69 61 6c 69 7a 65  3REF: Initialize
d4d0: 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72   The SQLite Libr
d4e0: 61 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ary.**.** ^The s
d4f0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
d500: 65 28 29 20 72 6f 75 74 69 6e 65 20 69 6e 69 74  e() routine init
d510: 69 61 6c 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53  ializes the.** S
d520: 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20  QLite library.  
d530: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75  ^The sqlite3_shu
d540: 74 64 6f 77 6e 28 29 20 72 6f 75 74 69 6e 65 0a  tdown() routine.
d550: 2a 2a 20 64 65 61 6c 6c 6f 63 61 74 65 73 20 61  ** deallocates a
d560: 6e 79 20 72 65 73 6f 75 72 63 65 73 20 74 68 61  ny resources tha
d570: 74 20 77 65 72 65 20 61 6c 6c 6f 63 61 74 65 64  t were allocated
d580: 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74   by sqlite3_init
d590: 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a 20 54 68 65  ialize()..** The
d5a0: 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
d5b0: 64 65 73 69 67 6e 65 64 20 74 6f 20 61 69 64 20  designed to aid 
d5c0: 69 6e 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69  in process initi
d5d0: 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a  alization and.**
d5e0: 20 73 68 75 74 64 6f 77 6e 20 6f 6e 20 65 6d 62   shutdown on emb
d5f0: 65 64 64 65 64 20 73 79 73 74 65 6d 73 2e 20 20  edded systems.  
d600: 57 6f 72 6b 73 74 61 74 69 6f 6e 20 61 70 70 6c  Workstation appl
d610: 69 63 61 74 69 6f 6e 73 20 75 73 69 6e 67 0a 2a  ications using.*
d620: 2a 20 53 51 4c 69 74 65 20 6e 6f 72 6d 61 6c 6c  * SQLite normall
d630: 79 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 6f  y do not need to
d640: 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 6f   invoke either o
d650: 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
d660: 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74  ..**.** A call t
d670: 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  o sqlite3_initia
d680: 6c 69 7a 65 28 29 20 69 73 20 61 6e 20 22 65 66  lize() is an "ef
d690: 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66  fective" call if
d6a0: 20 69 74 20 69 73 0a 2a 2a 20 74 68 65 20 66 69   it is.** the fi
d6b0: 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33  rst time sqlite3
d6c0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73  _initialize() is
d6d0: 20 69 6e 76 6f 6b 65 64 20 64 75 72 69 6e 67 20   invoked during 
d6e0: 74 68 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 0a  the lifetime of.
d6f0: 2a 2a 20 74 68 65 20 70 72 6f 63 65 73 73 2c 20  ** the process, 
d700: 6f 72 20 69 66 20 69 74 20 69 73 20 74 68 65 20  or if it is the 
d710: 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74  first time sqlit
d720: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
d730: 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f  is invoked.** fo
d740: 6c 6c 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20 74  llowing a call t
d750: 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  o sqlite3_shutdo
d760: 77 6e 28 29 2e 20 20 5e 28 4f 6e 6c 79 20 61 6e  wn().  ^(Only an
d770: 20 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c 0a   effective call.
d780: 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 69 6e  ** of sqlite3_in
d790: 69 74 69 61 6c 69 7a 65 28 29 20 64 6f 65 73 20  itialize() does 
d7a0: 61 6e 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  any initializati
d7b0: 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 63  on.  All other c
d7c0: 61 6c 6c 73 0a 2a 2a 20 61 72 65 20 68 61 72 6d  alls.** are harm
d7d0: 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a  less no-ops.)^.*
d7e0: 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73  *.** A call to s
d7f0: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
d800: 29 20 69 73 20 61 6e 20 22 65 66 66 65 63 74 69  ) is an "effecti
d810: 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69  ve" call if it i
d820: 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 63  s the first.** c
d830: 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  all to sqlite3_s
d840: 68 75 74 64 6f 77 6e 28 29 20 73 69 6e 63 65 20  hutdown() since 
d850: 74 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33  the last sqlite3
d860: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 20 20  _initialize().  
d870: 5e 28 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66 66  ^(Only.** an eff
d880: 65 63 74 69 76 65 20 63 61 6c 6c 20 74 6f 20 73  ective call to s
d890: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
d8a0: 29 20 64 6f 65 73 20 61 6e 79 20 64 65 69 6e 69  ) does any deini
d8b0: 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 20  tialization..** 
d8c0: 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 69 64 20  All other valid 
d8d0: 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
d8e0: 5f 73 68 75 74 64 6f 77 6e 28 29 20 61 72 65 20  _shutdown() are 
d8f0: 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e  harmless no-ops.
d900: 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  )^.**.** The sql
d910: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
d920: 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74  ) interface is t
d930: 68 72 65 61 64 73 61 66 65 2c 20 62 75 74 20 73  hreadsafe, but s
d940: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
d950: 29 0a 2a 2a 20 69 73 20 6e 6f 74 2e 20 20 54 68  ).** is not.  Th
d960: 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  e sqlite3_shutdo
d970: 77 6e 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d  wn() interface m
d980: 75 73 74 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c  ust only be call
d990: 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 73 69 6e  ed from a.** sin
d9a0: 67 6c 65 20 74 68 72 65 61 64 2e 20 20 41 6c 6c  gle thread.  All
d9b0: 20 6f 70 65 6e 20 5b 64 61 74 61 62 61 73 65 20   open [database 
d9c0: 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 6d 75 73  connections] mus
d9d0: 74 20 62 65 20 63 6c 6f 73 65 64 20 61 6e 64 20  t be closed and 
d9e0: 61 6c 6c 0a 2a 2a 20 6f 74 68 65 72 20 53 51 4c  all.** other SQL
d9f0: 69 74 65 20 72 65 73 6f 75 72 63 65 73 20 6d 75  ite resources mu
da00: 73 74 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65  st be deallocate
da10: 64 20 70 72 69 6f 72 20 74 6f 20 69 6e 76 6f 6b  d prior to invok
da20: 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73  ing.** sqlite3_s
da30: 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a  hutdown()..**.**
da40: 20 41 6d 6f 6e 67 20 6f 74 68 65 72 20 74 68 69   Among other thi
da50: 6e 67 73 2c 20 5e 73 71 6c 69 74 65 33 5f 69 6e  ngs, ^sqlite3_in
da60: 69 74 69 61 6c 69 7a 65 28 29 20 77 69 6c 6c 20  itialize() will 
da70: 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65  invoke.** sqlite
da80: 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 53 69  3_os_init().  Si
da90: 6d 69 6c 61 72 6c 79 2c 20 5e 73 71 6c 69 74 65  milarly, ^sqlite
daa0: 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20  3_shutdown().** 
dab0: 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 73 71 6c 69  will invoke sqli
dac0: 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a  te3_os_end()..**
dad0: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
dae0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f  _initialize() ro
daf0: 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53  utine returns [S
db00: 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63  QLITE_OK] on suc
db10: 63 65 73 73 2e 0a 2a 2a 20 5e 49 66 20 66 6f 72  cess..** ^If for
db20: 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2c 20 73 71   some reason, sq
db30: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
db40: 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  () is unable to 
db50: 69 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a 20 74 68  initialize.** th
db60: 65 20 6c 69 62 72 61 72 79 20 28 70 65 72 68 61  e library (perha
db70: 70 73 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20  ps it is unable 
db80: 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65  to allocate a ne
db90: 65 64 65 64 20 72 65 73 6f 75 72 63 65 20 73 75  eded resource su
dba0: 63 68 0a 2a 2a 20 61 73 20 61 20 6d 75 74 65 78  ch.** as a mutex
dbb0: 29 20 69 74 20 72 65 74 75 72 6e 73 20 61 6e 20  ) it returns an 
dbc0: 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 74 68  [error code] oth
dbd0: 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
dbe0: 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  OK]..**.** ^The 
dbf0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
dc00: 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20  ze() routine is 
dc10: 63 61 6c 6c 65 64 20 69 6e 74 65 72 6e 61 6c 6c  called internall
dc20: 79 20 62 79 20 6d 61 6e 79 20 6f 74 68 65 72 0a  y by many other.
dc30: 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  ** SQLite interf
dc40: 61 63 65 73 20 73 6f 20 74 68 61 74 20 61 6e 20  aces so that an 
dc50: 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 75 61  application usua
dc60: 6c 6c 79 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65  lly does not nee
dc70: 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73  d to.** invoke s
dc80: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
dc90: 65 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20 46  e() directly.  F
dca0: 6f 72 20 65 78 61 6d 70 6c 65 2c 20 5b 73 71 6c  or example, [sql
dcb0: 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20  ite3_open()].** 
dcc0: 63 61 6c 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e  calls sqlite3_in
dcd0: 69 74 69 61 6c 69 7a 65 28 29 20 73 6f 20 74 68  itialize() so th
dce0: 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79  e SQLite library
dcf0: 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74   will be automat
dd00: 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69 61  ically.** initia
dd10: 6c 69 7a 65 64 20 77 68 65 6e 20 5b 73 71 6c 69  lized when [sqli
dd20: 74 65 33 5f 6f 70 65 6e 28 29 5d 20 69 73 20 63  te3_open()] is c
dd30: 61 6c 6c 65 64 20 69 66 20 69 74 20 68 61 73 20  alled if it has 
dd40: 6e 6f 74 20 62 65 20 69 6e 69 74 69 61 6c 69 7a  not be initializ
dd50: 65 64 0a 2a 2a 20 61 6c 72 65 61 64 79 2e 20 20  ed.** already.  
dd60: 5e 48 6f 77 65 76 65 72 2c 20 69 66 20 53 51 4c  ^However, if SQL
dd70: 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
dd80: 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45  with the [SQLITE
dd90: 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 0a  _OMIT_AUTOINIT].
dda0: 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  ** compile-time 
ddb0: 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65  option, then the
ddc0: 20 61 75 74 6f 6d 61 74 69 63 20 63 61 6c 6c 73   automatic calls
ddd0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74   to sqlite3_init
dde0: 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 61 72 65 20  ialize().** are 
ddf0: 6f 6d 69 74 74 65 64 20 61 6e 64 20 74 68 65 20  omitted and the 
de00: 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
de10: 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 69 6e   call sqlite3_in
de20: 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63  itialize() direc
de30: 74 6c 79 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20  tly.** prior to 
de40: 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20  using any other 
de50: 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
de60: 2e 20 20 46 6f 72 20 6d 61 78 69 6d 75 6d 20 70  .  For maximum p
de70: 6f 72 74 61 62 69 6c 69 74 79 2c 0a 2a 2a 20 69  ortability,.** i
de80: 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  t is recommended
de90: 20 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f   that applicatio
dea0: 6e 73 20 61 6c 77 61 79 73 20 69 6e 76 6f 6b 65  ns always invoke
deb0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
dec0: 69 7a 65 28 29 0a 2a 2a 20 64 69 72 65 63 74 6c  ize().** directl
ded0: 79 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67  y prior to using
dee0: 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74   any other SQLit
def0: 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46 75  e interface.  Fu
df00: 74 75 72 65 20 72 65 6c 65 61 73 65 73 0a 2a 2a  ture releases.**
df10: 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20 72   of SQLite may r
df20: 65 71 75 69 72 65 20 74 68 69 73 2e 20 20 49 6e  equire this.  In
df30: 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
df40: 65 20 62 65 68 61 76 69 6f 72 20 65 78 68 69 62  e behavior exhib
df50: 69 74 65 64 0a 2a 2a 20 77 68 65 6e 20 53 51 4c  ited.** when SQL
df60: 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
df70: 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 4f 4d 49  with [SQLITE_OMI
df80: 54 5f 41 55 54 4f 49 4e 49 54 5d 20 6d 69 67 68  T_AUTOINIT] migh
df90: 74 20 62 65 63 6f 6d 65 20 74 68 65 0a 2a 2a 20  t become the.** 
dfa0: 64 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72  default behavior
dfb0: 20 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20   in some future 
dfc0: 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74  release of SQLit
dfd0: 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  e..**.** The sql
dfe0: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 72  ite3_os_init() r
dff0: 6f 75 74 69 6e 65 20 64 6f 65 73 20 6f 70 65 72  outine does oper
e000: 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65  ating-system spe
e010: 63 69 66 69 63 0a 2a 2a 20 69 6e 69 74 69 61 6c  cific.** initial
e020: 69 7a 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 53  ization of the S
e030: 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20  QLite library.  
e040: 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  The sqlite3_os_e
e050: 6e 64 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  nd().** routine 
e060: 75 6e 64 6f 65 73 20 74 68 65 20 65 66 66 65 63  undoes the effec
e070: 74 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f  t of sqlite3_os_
e080: 69 6e 69 74 28 29 2e 20 20 54 79 70 69 63 61 6c  init().  Typical
e090: 20 74 61 73 6b 73 0a 2a 2a 20 70 65 72 66 6f 72   tasks.** perfor
e0a0: 6d 65 64 20 62 79 20 74 68 65 73 65 20 72 6f 75  med by these rou
e0b0: 74 69 6e 65 73 20 69 6e 63 6c 75 64 65 20 61 6c  tines include al
e0c0: 6c 6f 63 61 74 69 6f 6e 20 6f 72 20 64 65 61 6c  location or deal
e0d0: 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73  location.** of s
e0e0: 74 61 74 69 63 20 72 65 73 6f 75 72 63 65 73 2c  tatic resources,
e0f0: 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
e100: 6f 66 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62  of global variab
e110: 6c 65 73 2c 0a 2a 2a 20 73 65 74 74 69 6e 67 20  les,.** setting 
e120: 75 70 20 61 20 64 65 66 61 75 6c 74 20 5b 73 71  up a default [sq
e130: 6c 69 74 65 33 5f 76 66 73 5d 20 6d 6f 64 75 6c  lite3_vfs] modul
e140: 65 2c 20 6f 72 20 73 65 74 74 69 6e 67 20 75 70  e, or setting up
e150: 0a 2a 2a 20 61 20 64 65 66 61 75 6c 74 20 63 6f  .** a default co
e160: 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 73 69 6e  nfiguration usin
e170: 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  g [sqlite3_confi
e180: 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  g()]..**.** The 
e190: 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75  application shou
e1a0: 6c 64 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20  ld never invoke 
e1b0: 65 69 74 68 65 72 20 73 71 6c 69 74 65 33 5f 6f  either sqlite3_o
e1c0: 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f 72 20 73  s_init().** or s
e1d0: 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20  qlite3_os_end() 
e1e0: 64 69 72 65 63 74 6c 79 2e 20 20 54 68 65 20 61  directly.  The a
e1f0: 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
e200: 64 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a  d only invoke.**
e210: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
e220: 69 7a 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ize() and sqlite
e230: 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 54  3_shutdown().  T
e240: 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  he sqlite3_os_in
e250: 69 74 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  it().** interfac
e260: 65 20 69 73 20 63 61 6c 6c 65 64 20 61 75 74 6f  e is called auto
e270: 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c  matically by sql
e280: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
e290: 29 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33  ) and.** sqlite3
e2a0: 5f 6f 73 5f 65 6e 64 28 29 20 69 73 20 63 61 6c  _os_end() is cal
e2b0: 6c 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 73  led by sqlite3_s
e2c0: 68 75 74 64 6f 77 6e 28 29 2e 20 20 41 70 70 72  hutdown().  Appr
e2d0: 6f 70 72 69 61 74 65 0a 2a 2a 20 69 6d 70 6c 65  opriate.** imple
e2e0: 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20 73  mentations for s
e2f0: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
e300: 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f   and sqlite3_os_
e310: 65 6e 64 28 29 0a 2a 2a 20 61 72 65 20 62 75 69  end().** are bui
e320: 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 20 77  lt into SQLite w
e330: 68 65 6e 20 69 74 20 69 73 20 63 6f 6d 70 69 6c  hen it is compil
e340: 65 64 20 66 6f 72 20 55 6e 69 78 2c 20 57 69 6e  ed for Unix, Win
e350: 64 6f 77 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a 2a  dows, or OS/2..*
e360: 2a 20 57 68 65 6e 20 5b 63 75 73 74 6f 6d 20 62  * When [custom b
e370: 75 69 6c 64 73 20 7c 20 62 75 69 6c 74 20 66 6f  uilds | built fo
e380: 72 20 6f 74 68 65 72 20 70 6c 61 74 66 6f 72 6d  r other platform
e390: 73 5d 0a 2a 2a 20 28 75 73 69 6e 67 20 74 68 65  s].** (using the
e3a0: 20 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f 54 48 45   [SQLITE_OS_OTHE
e3b0: 52 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  R=1] compile-tim
e3c0: 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20 74 68 65  e.** option) the
e3d0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
e3e0: 74 20 73 75 70 70 6c 79 20 61 20 73 75 69 74 61  t supply a suita
e3f0: 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ble implementati
e400: 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  on for.** sqlite
e410: 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20  3_os_init() and 
e420: 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
e430: 2e 20 20 41 6e 20 61 70 70 6c 69 63 61 74 69 6f  .  An applicatio
e440: 6e 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20 69 6d  n-supplied.** im
e450: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
e460: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
e470: 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f  ) or sqlite3_os_
e480: 65 6e 64 28 29 0a 2a 2a 20 6d 75 73 74 20 72 65  end().** must re
e490: 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  turn [SQLITE_OK]
e4a0: 20 6f 6e 20 73 75 63 63 65 73 73 20 61 6e 64 20   on success and 
e4b0: 73 6f 6d 65 20 6f 74 68 65 72 20 5b 65 72 72 6f  some other [erro
e4c0: 72 20 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20  r code] upon.** 
e4d0: 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a 69 6e 74 20  failure..*/.int 
e4e0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
e4f0: 7a 65 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71  ze(void);.int sq
e500: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 76  lite3_shutdown(v
e510: 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  oid);.int sqlite
e520: 33 5f 6f 73 5f 69 6e 69 74 28 76 6f 69 64 29 3b  3_os_init(void);
e530: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f  .int sqlite3_os_
e540: 65 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a  end(void);../*.*
e550: 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66  * CAPI3REF: Conf
e560: 69 67 75 72 69 6e 67 20 54 68 65 20 53 51 4c 69  iguring The SQLi
e570: 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a  te Library.**.**
e580: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e   The sqlite3_con
e590: 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20  fig() interface 
e5a0: 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20  is used to make 
e5b0: 67 6c 6f 62 61 6c 20 63 6f 6e 66 69 67 75 72 61  global configura
e5c0: 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20  tion.** changes 
e5d0: 74 6f 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64  to SQLite in ord
e5e0: 65 72 20 74 6f 20 74 75 6e 65 20 53 51 4c 69 74  er to tune SQLit
e5f0: 65 20 74 6f 20 74 68 65 20 73 70 65 63 69 66 69  e to the specifi
e600: 63 20 6e 65 65 64 73 20 6f 66 0a 2a 2a 20 74 68  c needs of.** th
e610: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20  e application.  
e620: 54 68 65 20 64 65 66 61 75 6c 74 20 63 6f 6e 66  The default conf
e630: 69 67 75 72 61 74 69 6f 6e 20 69 73 20 72 65 63  iguration is rec
e640: 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6d 6f 73  ommended for mos
e650: 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e  t.** application
e660: 73 20 61 6e 64 20 73 6f 20 74 68 69 73 20 72 6f  s and so this ro
e670: 75 74 69 6e 65 20 69 73 20 75 73 75 61 6c 6c 79  utine is usually
e680: 20 6e 6f 74 20 6e 65 63 65 73 73 61 72 79 2e 20   not necessary. 
e690: 20 49 74 20 69 73 0a 2a 2a 20 70 72 6f 76 69 64   It is.** provid
e6a0: 65 64 20 74 6f 20 73 75 70 70 6f 72 74 20 72 61  ed to support ra
e6b0: 72 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  re applications 
e6c0: 77 69 74 68 20 75 6e 75 73 75 61 6c 20 6e 65 65  with unusual nee
e6d0: 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ds..**.** The sq
e6e0: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69  lite3_config() i
e6f0: 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20  nterface is not 
e700: 74 68 72 65 61 64 73 61 66 65 2e 20 20 54 68 65  threadsafe.  The
e710: 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20   application.** 
e720: 6d 75 73 74 20 69 6e 73 75 72 65 20 74 68 61 74  must insure that
e730: 20 6e 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65   no other SQLite
e740: 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
e750: 69 6e 76 6f 6b 65 64 20 62 79 20 6f 74 68 65 72  invoked by other
e760: 0a 2a 2a 20 74 68 72 65 61 64 73 20 77 68 69 6c  .** threads whil
e770: 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  e sqlite3_config
e780: 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20 20  () is running.  
e790: 46 75 72 74 68 65 72 6d 6f 72 65 2c 20 73 71 6c  Furthermore, sql
e7a0: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 0a 2a 2a  ite3_config().**
e7b0: 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 69 6e 76   may only be inv
e7c0: 6f 6b 65 64 20 70 72 69 6f 72 20 74 6f 20 6c 69  oked prior to li
e7d0: 62 72 61 72 79 20 69 6e 69 74 69 61 6c 69 7a 61  brary initializa
e7e0: 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73  tion using.** [s
e7f0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
e800: 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20 73 68  e()] or after sh
e810: 75 74 64 6f 77 6e 20 62 79 20 5b 73 71 6c 69 74  utdown by [sqlit
e820: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a  e3_shutdown()]..
e830: 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63  ** ^If sqlite3_c
e840: 6f 6e 66 69 67 28 29 20 69 73 20 63 61 6c 6c 65  onfig() is calle
e850: 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33  d after [sqlite3
e860: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 61  _initialize()] a
e870: 6e 64 20 62 65 66 6f 72 65 0a 2a 2a 20 5b 73 71  nd before.** [sq
e880: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
e890: 5d 20 74 68 65 6e 20 69 74 20 77 69 6c 6c 20 72  ] then it will r
e8a0: 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4d 49 53  eturn SQLITE_MIS
e8b0: 55 53 45 2e 0a 2a 2a 20 4e 6f 74 65 2c 20 68 6f  USE..** Note, ho
e8c0: 77 65 76 65 72 2c 20 74 68 61 74 20 5e 73 71 6c  wever, that ^sql
e8d0: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 63 61  ite3_config() ca
e8e0: 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 73 20 70  n be called as p
e8f0: 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a 20 69 6d  art of the.** im
e900: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
e910: 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  an application-d
e920: 65 66 69 6e 65 64 20 5b 73 71 6c 69 74 65 33 5f  efined [sqlite3_
e930: 6f 73 5f 69 6e 69 74 28 29 5d 2e 0a 2a 2a 0a 2a  os_init()]..**.*
e940: 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  * The first argu
e950: 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
e960: 63 6f 6e 66 69 67 28 29 20 69 73 20 61 6e 20 69  config() is an i
e970: 6e 74 65 67 65 72 0a 2a 2a 20 5b 63 6f 6e 66 69  nteger.** [confi
e980: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d  guration option]
e990: 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 73   that determines
e9a0: 0a 2a 2a 20 77 68 61 74 20 70 72 6f 70 65 72 74  .** what propert
e9b0: 79 20 6f 66 20 53 51 4c 69 74 65 20 69 73 20 74  y of SQLite is t
e9c0: 6f 20 62 65 20 63 6f 6e 66 69 67 75 72 65 64 2e  o be configured.
e9d0: 20 20 53 75 62 73 65 71 75 65 6e 74 20 61 72 67    Subsequent arg
e9e0: 75 6d 65 6e 74 73 0a 2a 2a 20 76 61 72 79 20 64  uments.** vary d
e9f0: 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20  epending on the 
ea00: 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f  [configuration o
ea10: 70 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65  ption].** in the
ea20: 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e   first argument.
ea30: 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 61 20 63  .**.** ^When a c
ea40: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
ea50: 69 6f 6e 20 69 73 20 73 65 74 2c 20 73 71 6c 69  ion is set, sqli
ea60: 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 72 65 74  te3_config() ret
ea70: 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  urns [SQLITE_OK]
ea80: 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6f 70 74  ..** ^If the opt
ea90: 69 6f 6e 20 69 73 20 75 6e 6b 6e 6f 77 6e 20 6f  ion is unknown o
eaa0: 72 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62  r SQLite is unab
eab0: 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 6f 70  le to set the op
eac0: 74 69 6f 6e 0a 2a 2a 20 74 68 65 6e 20 74 68 69  tion.** then thi
ead0: 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  s routine return
eae0: 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72  s a non-zero [er
eaf0: 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2f 0a 69 6e  ror code]..*/.in
eb00: 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  t sqlite3_config
eb10: 28 69 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a  (int, ...);../*.
eb20: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e  ** CAPI3REF: Con
eb30: 66 69 67 75 72 65 20 64 61 74 61 62 61 73 65 20  figure database 
eb40: 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 0a 2a  connections.**.*
eb50: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62  * The sqlite3_db
eb60: 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66  _config() interf
eb70: 61 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d  ace is used to m
eb80: 61 6b 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ake configuratio
eb90: 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20  n.** changes to 
eba0: 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  a [database conn
ebb0: 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20 69 6e  ection].  The in
ebc0: 74 65 72 66 61 63 65 20 69 73 20 73 69 6d 69 6c  terface is simil
ebd0: 61 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ar to.** [sqlite
ebe0: 33 5f 63 6f 6e 66 69 67 28 29 5d 20 65 78 63 65  3_config()] exce
ebf0: 70 74 20 74 68 61 74 20 74 68 65 20 63 68 61 6e  pt that the chan
ec00: 67 65 73 20 61 70 70 6c 79 20 74 6f 20 61 20 73  ges apply to a s
ec10: 69 6e 67 6c 65 0a 2a 2a 20 5b 64 61 74 61 62 61  ingle.** [databa
ec20: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28  se connection] (
ec30: 73 70 65 63 69 66 69 65 64 20 69 6e 20 74 68 65  specified in the
ec40: 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 29   first argument)
ec50: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f  ..**.** The seco
ec60: 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  nd argument to s
ec70: 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
ec80: 28 44 2c 56 2c 2e 2e 2e 29 20 20 69 73 20 74 68  (D,V,...)  is th
ec90: 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 42 43  e.** [SQLITE_DBC
eca0: 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20  ONFIG_LOOKASIDE 
ecb0: 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  | configuration 
ecc0: 76 65 72 62 5d 20 2d 20 61 6e 20 69 6e 74 65 67  verb] - an integ
ecd0: 65 72 20 63 6f 64 65 20 0a 2a 2a 20 74 68 61 74  er code .** that
ece0: 20 69 6e 64 69 63 61 74 65 73 20 77 68 61 74 20   indicates what 
ecf0: 61 73 70 65 63 74 20 6f 66 20 74 68 65 20 5b 64  aspect of the [d
ed00: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
ed10: 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20 63 6f 6e  on] is being con
ed20: 66 69 67 75 72 65 64 2e 0a 2a 2a 20 53 75 62 73  figured..** Subs
ed30: 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73  equent arguments
ed40: 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20   vary depending 
ed50: 6f 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61  on the configura
ed60: 74 69 6f 6e 20 76 65 72 62 2e 0a 2a 2a 0a 2a 2a  tion verb..**.**
ed70: 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74   ^Calls to sqlit
ed80: 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 72  e3_db_config() r
ed90: 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20  eturn SQLITE_OK 
eda0: 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a  if and only if.*
edb0: 2a 20 74 68 65 20 63 61 6c 6c 20 69 73 20 63 6f  * the call is co
edc0: 6e 73 69 64 65 72 65 64 20 73 75 63 63 65 73 73  nsidered success
edd0: 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ful..*/.int sqli
ede0: 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 73 71  te3_db_config(sq
edf0: 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 70 2c 20  lite3*, int op, 
ee00: 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ...);../*.** CAP
ee10: 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c  I3REF: Memory Al
ee20: 6c 6f 63 61 74 69 6f 6e 20 52 6f 75 74 69 6e 65  location Routine
ee30: 73 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61  s.**.** An insta
ee40: 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65  nce of this obje
ee50: 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 69  ct defines the i
ee60: 6e 74 65 72 66 61 63 65 20 62 65 74 77 65 65 6e  nterface between
ee70: 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 6c   SQLite.** and l
ee80: 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20  ow-level memory 
ee90: 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69  allocation routi
eea0: 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  nes..**.** This 
eeb0: 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 20 69  object is used i
eec0: 6e 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61 63 65  n only one place
eed0: 20 69 6e 20 74 68 65 20 53 51 4c 69 74 65 20 69   in the SQLite i
eee0: 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 41 20 70  nterface..** A p
eef0: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73  ointer to an ins
ef00: 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62  tance of this ob
ef10: 6a 65 63 74 20 69 73 20 74 68 65 20 61 72 67 75  ject is the argu
ef20: 6d 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  ment to.** [sqli
ef30: 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 68  te3_config()] wh
ef40: 65 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61  en the configura
ef50: 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 0a 2a  tion option is.*
ef60: 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  * [SQLITE_CONFIG
ef70: 5f 4d 41 4c 4c 4f 43 5d 20 6f 72 20 5b 53 51 4c  _MALLOC] or [SQL
ef80: 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41  ITE_CONFIG_GETMA
ef90: 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a 20 42 79 20 63  LLOC].  .** By c
efa0: 72 65 61 74 69 6e 67 20 61 6e 20 69 6e 73 74 61  reating an insta
efb0: 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65  nce of this obje
efc0: 63 74 0a 2a 2a 20 61 6e 64 20 70 61 73 73 69 6e  ct.** and passin
efd0: 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  g it to [sqlite3
efe0: 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45  _config]([SQLITE
eff0: 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 29  _CONFIG_MALLOC])
f000: 0a 2a 2a 20 64 75 72 69 6e 67 20 63 6f 6e 66 69  .** during confi
f010: 67 75 72 61 74 69 6f 6e 2c 20 61 6e 20 61 70 70  guration, an app
f020: 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 73 70 65  lication can spe
f030: 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74  cify an alternat
f040: 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c  ive.** memory al
f050: 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74  location subsyst
f060: 65 6d 20 66 6f 72 20 53 51 4c 69 74 65 20 74 6f  em for SQLite to
f070: 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20   use for all of 
f080: 69 74 73 0a 2a 2a 20 64 79 6e 61 6d 69 63 20 6d  its.** dynamic m
f090: 65 6d 6f 72 79 20 6e 65 65 64 73 2e 0a 2a 2a 0a  emory needs..**.
f0a0: 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 51 4c  ** Note that SQL
f0b0: 69 74 65 20 63 6f 6d 65 73 20 77 69 74 68 20 73  ite comes with s
f0c0: 65 76 65 72 61 6c 20 5b 62 75 69 6c 74 2d 69 6e  everal [built-in
f0d0: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
f0e0: 72 73 5d 0a 2a 2a 20 74 68 61 74 20 61 72 65 20  rs].** that are 
f0f0: 70 65 72 66 65 63 74 6c 79 20 61 64 65 71 75 61  perfectly adequa
f100: 74 65 20 66 6f 72 20 74 68 65 20 6f 76 65 72 77  te for the overw
f110: 68 65 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69 74 79  helming majority
f120: 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73   of applications
f130: 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 74 68 69  .** and that thi
f140: 73 20 6f 62 6a 65 63 74 20 69 73 20 6f 6e 6c 79  s object is only
f150: 20 75 73 65 66 75 6c 20 74 6f 20 61 20 74 69 6e   useful to a tin
f160: 79 20 6d 69 6e 6f 72 69 74 79 20 6f 66 20 61 70  y minority of ap
f170: 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 77 69  plications.** wi
f180: 74 68 20 73 70 65 63 69 61 6c 69 7a 65 64 20 6d  th specialized m
f190: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
f1a0: 20 72 65 71 75 69 72 65 6d 65 6e 74 73 2e 20 20   requirements.  
f1b0: 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 0a 2a  This object is.*
f1c0: 2a 20 61 6c 73 6f 20 75 73 65 64 20 64 75 72 69  * also used duri
f1d0: 6e 67 20 74 65 73 74 69 6e 67 20 6f 66 20 53 51  ng testing of SQ
f1e0: 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f  Lite in order to
f1f0: 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65   specify an alte
f200: 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72  rnative.** memor
f210: 79 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68 61 74  y allocator that
f220: 20 73 69 6d 75 6c 61 74 65 73 20 6d 65 6d 6f 72   simulates memor
f230: 79 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20  y out-of-memory 
f240: 63 6f 6e 64 69 74 69 6f 6e 73 20 69 6e 0a 2a 2a  conditions in.**
f250: 20 6f 72 64 65 72 20 74 6f 20 76 65 72 69 66 79   order to verify
f260: 20 74 68 61 74 20 53 51 4c 69 74 65 20 72 65 63   that SQLite rec
f270: 6f 76 65 72 73 20 67 72 61 63 65 66 75 6c 6c 79  overs gracefully
f280: 20 66 72 6f 6d 20 73 75 63 68 0a 2a 2a 20 63 6f   from such.** co
f290: 6e 64 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20  nditions..**.** 
f2a0: 54 68 65 20 78 4d 61 6c 6c 6f 63 2c 20 78 52 65  The xMalloc, xRe
f2b0: 61 6c 6c 6f 63 2c 20 61 6e 64 20 78 46 72 65 65  alloc, and xFree
f2c0: 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 77 6f   methods must wo
f2d0: 72 6b 20 6c 69 6b 65 20 74 68 65 0a 2a 2a 20 6d  rk like the.** m
f2e0: 61 6c 6c 6f 63 28 29 2c 20 72 65 61 6c 6c 6f 63  alloc(), realloc
f2f0: 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 66 75  () and free() fu
f300: 6e 63 74 69 6f 6e 73 20 66 72 6f 6d 20 74 68 65  nctions from the
f310: 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72   standard C libr
f320: 61 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ary..** ^SQLite 
f330: 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 20  guarantees that 
f340: 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
f350: 65 6e 74 20 74 6f 0a 2a 2a 20 78 52 65 61 6c 6c  ent to.** xReall
f360: 6f 63 20 69 73 20 61 6c 77 61 79 73 20 61 20 76  oc is always a v
f370: 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79  alue returned by
f380: 20 61 20 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f   a prior call to
f390: 20 78 52 6f 75 6e 64 75 70 2e 0a 2a 2a 0a 2a 2a   xRoundup..**.**
f3a0: 20 78 53 69 7a 65 20 73 68 6f 75 6c 64 20 72 65   xSize should re
f3b0: 74 75 72 6e 20 74 68 65 20 61 6c 6c 6f 63 61 74  turn the allocat
f3c0: 65 64 20 73 69 7a 65 20 6f 66 20 61 20 6d 65 6d  ed size of a mem
f3d0: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a  ory allocation.*
f3e0: 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74  * previously obt
f3f0: 61 69 6e 65 64 20 66 72 6f 6d 20 78 4d 61 6c 6c  ained from xMall
f400: 6f 63 20 6f 72 20 78 52 65 61 6c 6c 6f 63 2e 20  oc or xRealloc. 
f410: 20 54 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73   The allocated s
f420: 69 7a 65 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73  ize.** is always
f430: 20 61 74 20 6c 65 61 73 74 20 61 73 20 62 69 67   at least as big
f440: 20 61 73 20 74 68 65 20 72 65 71 75 65 73 74 65   as the requeste
f450: 64 20 73 69 7a 65 20 62 75 74 20 6d 61 79 20 62  d size but may b
f460: 65 20 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a 20  e larger..**.** 
f470: 54 68 65 20 78 52 6f 75 6e 64 75 70 20 6d 65 74  The xRoundup met
f480: 68 6f 64 20 72 65 74 75 72 6e 73 20 77 68 61 74  hod returns what
f490: 20 77 6f 75 6c 64 20 62 65 20 74 68 65 20 61 6c   would be the al
f4a0: 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66 0a  located size of.
f4b0: 2a 2a 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ** a memory allo
f4c0: 63 61 74 69 6f 6e 20 67 69 76 65 6e 20 61 20 70  cation given a p
f4d0: 61 72 74 69 63 75 6c 61 72 20 72 65 71 75 65 73  articular reques
f4e0: 74 65 64 20 73 69 7a 65 2e 20 20 4d 6f 73 74 20  ted size.  Most 
f4f0: 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61  memory.** alloca
f500: 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 6d 65  tors round up me
f510: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73  mory allocations
f520: 20 61 74 20 6c 65 61 73 74 20 74 6f 20 74 68 65   at least to the
f530: 20 6e 65 78 74 20 6d 75 6c 74 69 70 6c 65 0a 2a   next multiple.*
f540: 2a 20 6f 66 20 38 2e 20 20 53 6f 6d 65 20 61 6c  * of 8.  Some al
f550: 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75  locators round u
f560: 70 20 74 6f 20 61 20 6c 61 72 67 65 72 20 6d 75  p to a larger mu
f570: 6c 74 69 70 6c 65 20 6f 72 20 74 6f 20 61 20 70  ltiple or to a p
f580: 6f 77 65 72 20 6f 66 20 32 2e 0a 2a 2a 20 45 76  ower of 2..** Ev
f590: 65 72 79 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ery memory alloc
f5a0: 61 74 69 6f 6e 20 72 65 71 75 65 73 74 20 63 6f  ation request co
f5b0: 6d 69 6e 67 20 69 6e 20 74 68 72 6f 75 67 68 20  ming in through 
f5c0: 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
f5d0: 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65  )].** or [sqlite
f5e0: 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 66 69 72  3_realloc()] fir
f5f0: 73 74 20 63 61 6c 6c 73 20 78 52 6f 75 6e 64 75  st calls xRoundu
f600: 70 2e 20 20 49 66 20 78 52 6f 75 6e 64 75 70 20  p.  If xRoundup 
f610: 72 65 74 75 72 6e 73 20 30 2c 20 0a 2a 2a 20 74  returns 0, .** t
f620: 68 61 74 20 63 61 75 73 65 73 20 74 68 65 20 63  hat causes the c
f630: 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6d 65 6d  orresponding mem
f640: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74  ory allocation t
f650: 6f 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68  o fail..**.** Th
f660: 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 69  e xInit method i
f670: 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65 20 6d  nitializes the m
f680: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 2e  emory allocator.
f690: 20 20 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 0a    (For example,.
f6a0: 2a 2a 20 69 74 20 6d 69 67 68 74 20 61 6c 6c 6f  ** it might allo
f6b0: 63 61 74 65 20 61 6e 79 20 72 65 71 75 69 72 65  cate any require
f6c0: 20 6d 75 74 65 78 65 73 20 6f 72 20 69 6e 69 74   mutexes or init
f6d0: 69 61 6c 69 7a 65 20 69 6e 74 65 72 6e 61 6c 20  ialize internal 
f6e0: 64 61 74 61 0a 2a 2a 20 73 74 72 75 63 74 75 72  data.** structur
f6f0: 65 73 2e 20 20 54 68 65 20 78 53 68 75 74 64 6f  es.  The xShutdo
f700: 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 69 6e 76  wn method is inv
f710: 6f 6b 65 64 20 28 69 6e 64 69 72 65 63 74 6c 79  oked (indirectly
f720: 29 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ) by.** [sqlite3
f730: 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 61 6e 64  _shutdown()] and
f740: 20 73 68 6f 75 6c 64 20 64 65 61 6c 6c 6f 63 61   should dealloca
f750: 74 65 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73  te any resources
f760: 20 61 63 71 75 69 72 65 64 0a 2a 2a 20 62 79 20   acquired.** by 
f770: 78 49 6e 69 74 2e 20 20 54 68 65 20 70 41 70 70  xInit.  The pApp
f780: 44 61 74 61 20 70 6f 69 6e 74 65 72 20 69 73 20  Data pointer is 
f790: 75 73 65 64 20 61 73 20 74 68 65 20 6f 6e 6c 79  used as the only
f7a0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
f7b0: 20 78 49 6e 69 74 20 61 6e 64 20 78 53 68 75 74   xInit and xShut
f7c0: 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  down..**.** SQLi
f7d0: 74 65 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51  te holds the [SQ
f7e0: 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49  LITE_MUTEX_STATI
f7f0: 43 5f 4d 41 53 54 45 52 5d 20 6d 75 74 65 78 20  C_MASTER] mutex 
f800: 77 68 65 6e 20 69 74 20 69 6e 76 6f 6b 65 73 0a  when it invokes.
f810: 2a 2a 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74  ** the xInit met
f820: 68 6f 64 2c 20 73 6f 20 74 68 65 20 78 49 6e 69  hod, so the xIni
f830: 74 20 6d 65 74 68 6f 64 20 6e 65 65 64 20 6e 6f  t method need no
f840: 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65 2e  t be threadsafe.
f850: 20 20 54 68 65 0a 2a 2a 20 78 53 68 75 74 64 6f    The.** xShutdo
f860: 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 6f 6e 6c  wn method is onl
f870: 79 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 5b 73  y called from [s
f880: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
f890: 29 5d 20 73 6f 20 69 74 20 64 6f 65 73 0a 2a 2a  )] so it does.**
f8a0: 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20   not need to be 
f8b0: 74 68 72 65 61 64 73 61 66 65 20 65 69 74 68 65  threadsafe eithe
f8c0: 72 2e 20 20 46 6f 72 20 61 6c 6c 20 6f 74 68 65  r.  For all othe
f8d0: 72 20 6d 65 74 68 6f 64 73 2c 20 53 51 4c 69 74  r methods, SQLit
f8e0: 65 0a 2a 2a 20 68 6f 6c 64 73 20 74 68 65 20 5b  e.** holds the [
f8f0: 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41  SQLITE_MUTEX_STA
f900: 54 49 43 5f 4d 45 4d 5d 20 6d 75 74 65 78 20 61  TIC_MEM] mutex a
f910: 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 0a 2a 2a  s long as the.**
f920: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
f930: 4d 45 4d 53 54 41 54 55 53 5d 20 63 6f 6e 66 69  MEMSTATUS] confi
f940: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20  guration option 
f950: 69 73 20 74 75 72 6e 65 64 20 6f 6e 20 28 77 68  is turned on (wh
f960: 69 63 68 0a 2a 2a 20 69 74 20 69 73 20 62 79 20  ich.** it is by 
f970: 64 65 66 61 75 6c 74 29 20 61 6e 64 20 73 6f 20  default) and so 
f980: 74 68 65 20 6d 65 74 68 6f 64 73 20 61 72 65 20  the methods are 
f990: 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 73 65  automatically se
f9a0: 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a 20 48 6f 77  rialized..** How
f9b0: 65 76 65 72 2c 20 69 66 20 5b 53 51 4c 49 54 45  ever, if [SQLITE
f9c0: 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55  _CONFIG_MEMSTATU
f9d0: 53 5d 20 69 73 20 64 69 73 61 62 6c 65 64 2c 20  S] is disabled, 
f9e0: 74 68 65 6e 20 74 68 65 20 6f 74 68 65 72 0a 2a  then the other.*
f9f0: 2a 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 62  * methods must b
fa00: 65 20 74 68 72 65 61 64 73 61 66 65 20 6f 72 20  e threadsafe or 
fa10: 65 6c 73 65 20 6d 61 6b 65 20 74 68 65 69 72 20  else make their 
fa20: 6f 77 6e 20 61 72 72 61 6e 67 65 6d 65 6e 74 73  own arrangements
fa30: 20 66 6f 72 0a 2a 2a 20 73 65 72 69 61 6c 69 7a   for.** serializ
fa40: 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c  ation..**.** SQL
fa50: 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 69  ite will never i
fa60: 6e 76 6f 6b 65 20 78 49 6e 69 74 28 29 20 6d 6f  nvoke xInit() mo
fa70: 72 65 20 74 68 61 6e 20 6f 6e 63 65 20 77 69 74  re than once wit
fa80: 68 6f 75 74 20 61 6e 20 69 6e 74 65 72 76 65 6e  hout an interven
fa90: 69 6e 67 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 78  ing.** call to x
faa0: 53 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2f 0a 74  Shutdown()..*/.t
fab0: 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
fac0: 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
fad0: 73 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65  s sqlite3_mem_me
fae0: 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71  thods;.struct sq
faf0: 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
fb00: 73 20 7b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 4d  s {.  void *(*xM
fb10: 61 6c 6c 6f 63 29 28 69 6e 74 29 3b 20 20 20 20  alloc)(int);    
fb20: 20 20 20 20 20 2f 2a 20 4d 65 6d 6f 72 79 20 61       /* Memory a
fb30: 6c 6c 6f 63 61 74 69 6f 6e 20 66 75 6e 63 74 69  llocation functi
fb40: 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78  on */.  void (*x
fb50: 46 72 65 65 29 28 76 6f 69 64 2a 29 3b 20 20 20  Free)(void*);   
fb60: 20 20 20 20 20 20 20 2f 2a 20 46 72 65 65 20 61         /* Free a
fb70: 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f   prior allocatio
fb80: 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 28 2a 78  n */.  void *(*x
fb90: 52 65 61 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c 69  Realloc)(void*,i
fba0: 6e 74 29 3b 20 20 2f 2a 20 52 65 73 69 7a 65 20  nt);  /* Resize 
fbb0: 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f  an allocation */
fbc0: 0a 20 20 69 6e 74 20 28 2a 78 53 69 7a 65 29 28  .  int (*xSize)(
fbd0: 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20  void*);         
fbe0: 20 20 2f 2a 20 52 65 74 75 72 6e 20 74 68 65 20    /* Return the 
fbf0: 73 69 7a 65 20 6f 66 20 61 6e 20 61 6c 6c 6f 63  size of an alloc
fc00: 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28  ation */.  int (
fc10: 2a 78 52 6f 75 6e 64 75 70 29 28 69 6e 74 29 3b  *xRoundup)(int);
fc20: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52 6f 75            /* Rou
fc30: 6e 64 20 75 70 20 72 65 71 75 65 73 74 20 73 69  nd up request si
fc40: 7a 65 20 74 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e  ze to allocation
fc50: 20 73 69 7a 65 20 2a 2f 0a 20 20 69 6e 74 20 28   size */.  int (
fc60: 2a 78 49 6e 69 74 29 28 76 6f 69 64 2a 29 3b 20  *xInit)(void*); 
fc70: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 49 6e 69            /* Ini
fc80: 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f  tialize the memo
fc90: 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a  ry allocator */.
fca0: 20 20 76 6f 69 64 20 28 2a 78 53 68 75 74 64 6f    void (*xShutdo
fcb0: 77 6e 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20  wn)(void*);     
fcc0: 20 2f 2a 20 44 65 69 6e 69 74 69 61 6c 69 7a 65   /* Deinitialize
fcd0: 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   the memory allo
fce0: 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20  cator */.  void 
fcf0: 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20 20 20  *pAppData;      
fd00: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 72 67            /* Arg
fd10: 75 6d 65 6e 74 20 74 6f 20 78 49 6e 69 74 28 29  ument to xInit()
fd20: 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 28 29   and xShutdown()
fd30: 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.};../*.** CA
fd40: 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72  PI3REF: Configur
fd50: 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a  ation Options.**
fd60: 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6e 66   KEYWORDS: {conf
fd70: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
fd80: 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f  }.**.** These co
fd90: 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68 65 20  nstants are the 
fda0: 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65  available intege
fdb0: 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  r configuration 
fdc0: 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20  options that.** 
fdd0: 63 61 6e 20 62 65 20 70 61 73 73 65 64 20 61 73  can be passed as
fde0: 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
fdf0: 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  ent to the [sqli
fe00: 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e  te3_config()] in
fe10: 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e  terface..**.** N
fe20: 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ew configuration
fe30: 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20   options may be 
fe40: 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
fe50: 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69  releases of SQLi
fe60: 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20  te..** Existing 
fe70: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
fe80: 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64  tions might be d
fe90: 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70  iscontinued.  Ap
fea0: 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68  plications.** sh
feb0: 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72  ould check the r
fec0: 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20  eturn code from 
fed0: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
fee0: 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20  )] to make sure 
fef0: 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c  that.** the call
ff00: 20 77 6f 72 6b 65 64 2e 20 20 54 68 65 20 5b 73   worked.  The [s
ff10: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
ff20: 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20   interface will 
ff30: 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d  return a.** non-
ff40: 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65  zero [error code
ff50: 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e  ] if a discontin
ff60: 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74  ued or unsupport
ff70: 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ed configuration
ff80: 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e   option.** is in
ff90: 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c  voked..**.** <dl
ffa0: 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  >.** [[SQLITE_CO
ffb0: 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
ffc0: 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  D]] <dt>SQLITE_C
ffd0: 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
ffe0: 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  AD</dt>.** <dd>T
fff0: 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75  here are no argu
10000 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70  ments to this op
10010 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74  tion.  ^This opt
10020 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20  ion sets the.** 
10030 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
10040 20 74 6f 20 53 69 6e 67 6c 65 2d 74 68 72 65 61   to Single-threa
10050 64 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  d.  In other wor
10060 64 73 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a  ds, it disables.
10070 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 69 6e 67 20  ** all mutexing 
10080 61 6e 64 20 70 75 74 73 20 53 51 4c 69 74 65 20  and puts SQLite 
10090 69 6e 74 6f 20 61 20 6d 6f 64 65 20 77 68 65 72  into a mode wher
100a0 65 20 69 74 20 63 61 6e 20 6f 6e 6c 79 20 62 65  e it can only be
100b0 20 75 73 65 64 0a 2a 2a 20 62 79 20 61 20 73 69   used.** by a si
100c0 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20 20 5e  ngle thread.   ^
100d0 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
100e0 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68  piled with.** th
100f0 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
10100 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48  SAFE | SQLITE_TH
10110 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70  READSAFE=0] comp
10120 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
10130 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f  then.** it is no
10140 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 63 68  t possible to ch
10150 61 6e 67 65 20 74 68 65 20 5b 74 68 72 65 61 64  ange the [thread
10160 69 6e 67 20 6d 6f 64 65 5d 20 66 72 6f 6d 20 69  ing mode] from i
10170 74 73 20 64 65 66 61 75 6c 74 0a 2a 2a 20 76 61  ts default.** va
10180 6c 75 65 20 6f 66 20 53 69 6e 67 6c 65 2d 74 68  lue of Single-th
10190 72 65 61 64 20 61 6e 64 20 73 6f 20 5b 73 71 6c  read and so [sql
101a0 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77  ite3_config()] w
101b0 69 6c 6c 20 72 65 74 75 72 6e 20 0a 2a 2a 20 5b  ill return .** [
101c0 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66  SQLITE_ERROR] if
101d0 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65   called with the
101e0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
101f0 49 4e 47 4c 45 54 48 52 45 41 44 0a 2a 2a 20 63  INGLETHREAD.** c
10200 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
10210 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ion.</dd>.**.** 
10220 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
10230 4d 55 4c 54 49 54 48 52 45 41 44 5d 5d 20 3c 64  MULTITHREAD]] <d
10240 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
10250 4d 55 4c 54 49 54 48 52 45 41 44 3c 2f 64 74 3e  MULTITHREAD</dt>
10260 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72  .** <dd>There ar
10270 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74  e no arguments t
10280 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20  o this option.  
10290 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74  ^This option set
102a0 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64  s the.** [thread
102b0 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 4d 75 6c  ing mode] to Mul
102c0 74 69 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f  ti-thread.  In o
102d0 74 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64  ther words, it d
102e0 69 73 61 62 6c 65 73 0a 2a 2a 20 6d 75 74 65 78  isables.** mutex
102f0 69 6e 67 20 6f 6e 20 5b 64 61 74 61 62 61 73 65  ing on [database
10300 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64   connection] and
10310 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
10320 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a  ment] objects..*
10330 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
10340 6e 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65  n is responsible
10350 20 66 6f 72 20 73 65 72 69 61 6c 69 7a 69 6e 67   for serializing
10360 20 61 63 63 65 73 73 20 74 6f 0a 2a 2a 20 5b 64   access to.** [d
10370 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
10380 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72  ons] and [prepar
10390 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2e 20  ed statements]. 
103a0 20 42 75 74 20 6f 74 68 65 72 20 6d 75 74 65 78   But other mutex
103b0 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65  es.** are enable
103c0 64 20 73 6f 20 74 68 61 74 20 53 51 4c 69 74 65  d so that SQLite
103d0 20 77 69 6c 6c 20 62 65 20 73 61 66 65 20 74 6f   will be safe to
103e0 20 75 73 65 20 69 6e 20 61 20 6d 75 6c 74 69 2d   use in a multi-
103f0 74 68 72 65 61 64 65 64 0a 2a 2a 20 65 6e 76 69  threaded.** envi
10400 72 6f 6e 6d 65 6e 74 20 61 73 20 6c 6f 6e 67 20  ronment as long 
10410 61 73 20 6e 6f 20 74 77 6f 20 74 68 72 65 61 64  as no two thread
10420 73 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65  s attempt to use
10430 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 5b 64 61   the same.** [da
10440 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
10450 6e 5d 20 61 74 20 74 68 65 20 73 61 6d 65 20 74  n] at the same t
10460 69 6d 65 2e 20 20 5e 49 66 20 53 51 4c 69 74 65  ime.  ^If SQLite
10470 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
10480 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  h.** the [SQLITE
10490 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51  _THREADSAFE | SQ
104a0 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
104b0 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  0] compile-time 
104c0 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69  option then.** i
104d0 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c  t is not possibl
104e0 65 20 74 6f 20 73 65 74 20 74 68 65 20 4d 75 6c  e to set the Mul
104f0 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61  ti-thread [threa
10500 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a  ding mode] and.*
10510 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
10520 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e  g()] will return
10530 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
10540 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74  if called with t
10550 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e  he.** SQLITE_CON
10560 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20  FIG_MULTITHREAD 
10570 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
10580 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  tion.</dd>.**.**
10590 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
105a0 5f 53 45 52 49 41 4c 49 5a 45 44 5d 5d 20 3c 64  _SERIALIZED]] <d
105b0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
105c0 53 45 52 49 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a  SERIALIZED</dt>.
105d0 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65  ** <dd>There are
105e0 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f   no arguments to
105f0 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e   this option.  ^
10600 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73  This option sets
10610 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69   the.** [threadi
10620 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 65 72 69  ng mode] to Seri
10630 61 6c 69 7a 65 64 2e 20 49 6e 20 6f 74 68 65 72  alized. In other
10640 20 77 6f 72 64 73 2c 20 74 68 69 73 20 6f 70 74   words, this opt
10650 69 6f 6e 20 65 6e 61 62 6c 65 73 0a 2a 2a 20 61  ion enables.** a
10660 6c 6c 20 6d 75 74 65 78 65 73 20 69 6e 63 6c 75  ll mutexes inclu
10670 64 69 6e 67 20 74 68 65 20 72 65 63 75 72 73 69  ding the recursi
10680 76 65 0a 2a 2a 20 6d 75 74 65 78 65 73 20 6f 6e  ve.** mutexes on
10690 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
106a0 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70  ction] and [prep
106b0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
106c0 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 49 6e 20 74  objects..** In t
106d0 68 69 73 20 6d 6f 64 65 20 28 77 68 69 63 68 20  his mode (which 
106e0 69 73 20 74 68 65 20 64 65 66 61 75 6c 74 20 77  is the default w
106f0 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f  hen SQLite is co
10700 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 5b  mpiled with.** [
10710 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
10720 45 3d 31 5d 29 20 74 68 65 20 53 51 4c 69 74 65  E=1]) the SQLite
10730 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 69 74   library will it
10740 73 65 6c 66 20 73 65 72 69 61 6c 69 7a 65 20 61  self serialize a
10750 63 63 65 73 73 0a 2a 2a 20 74 6f 20 5b 64 61 74  ccess.** to [dat
10760 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
10770 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64  s] and [prepared
10780 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 73 6f 20   statements] so 
10790 74 68 61 74 20 74 68 65 0a 2a 2a 20 61 70 70 6c  that the.** appl
107a0 69 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65 20  ication is free 
107b0 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65 20  to use the same 
107c0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
107d0 74 69 6f 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a 20  tion] or the.** 
107e0 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73  same [prepared s
107f0 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 64 69 66  tatement] in dif
10800 66 65 72 65 6e 74 20 74 68 72 65 61 64 73 20 61  ferent threads a
10810 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e  t the same time.
10820 0a 2a 2a 20 5e 49 66 20 53 51 4c 69 74 65 20 69  .** ^If SQLite i
10830 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a  s compiled with.
10840 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  ** the [SQLITE_T
10850 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49  HREADSAFE | SQLI
10860 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d  TE_THREADSAFE=0]
10870 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
10880 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20  tion then.** it 
10890 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20  is not possible 
108a0 74 6f 20 73 65 74 20 74 68 65 20 53 65 72 69 61  to set the Seria
108b0 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67  lized [threading
108c0 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73   mode] and.** [s
108d0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
108e0 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51   will return [SQ
108f0 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63  LITE_ERROR] if c
10900 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a  alled with the.*
10910 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  * SQLITE_CONFIG_
10920 53 45 52 49 41 4c 49 5a 45 44 20 63 6f 6e 66 69  SERIALIZED confi
10930 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e  guration option.
10940 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
10950 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c  LITE_CONFIG_MALL
10960 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  OC]] <dt>SQLITE_
10970 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64  CONFIG_MALLOC</d
10980 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69  t>.** <dd> ^(Thi
10990 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  s option takes a
109a0 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
109b0 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e   which is a poin
109c0 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73  ter to an.** ins
109d0 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71  tance of the [sq
109e0 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
109f0 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54  s] structure.  T
10a00 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63  he argument spec
10a10 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61  ifies.** alterna
10a20 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d  tive low-level m
10a30 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
10a40 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20   routines to be 
10a50 75 73 65 64 20 69 6e 20 70 6c 61 63 65 20 6f 66  used in place of
10a60 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20 61  .** the memory a
10a70 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e  llocation routin
10a80 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51  es built into SQ
10a90 4c 69 74 65 2e 29 5e 20 5e 53 51 4c 69 74 65 20  Lite.)^ ^SQLite 
10aa0 6d 61 6b 65 73 0a 2a 2a 20 69 74 73 20 6f 77 6e  makes.** its own
10ab0 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66   private copy of
10ac0 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20   the content of 
10ad0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  the [sqlite3_mem
10ae0 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
10af0 75 72 65 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68  ure.** before th
10b00 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  e [sqlite3_confi
10b10 67 28 29 5d 20 63 61 6c 6c 20 72 65 74 75 72 6e  g()] call return
10b20 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  s.</dd>.**.** [[
10b30 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
10b40 54 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51  TMALLOC]] <dt>SQ
10b50 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
10b60 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ALLOC</dt>.** <d
10b70 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e  d> ^(This option
10b80 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
10b90 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
10ba0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
10bb0 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66  n.** instance of
10bc0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65   the [sqlite3_me
10bd0 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63  m_methods] struc
10be0 74 75 72 65 2e 20 20 54 68 65 20 5b 73 71 6c 69  ture.  The [sqli
10bf0 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d  te3_mem_methods]
10c00 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69 73  .** structure is
10c10 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65   filled with the
10c20 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e   currently defin
10c30 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ed memory alloca
10c40 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 29 5e  tion routines.)^
10c50 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20  .** This option 
10c60 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f  can be used to o
10c70 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61  verload the defa
10c80 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ult memory alloc
10c90 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65  ation.** routine
10ca0 73 20 77 69 74 68 20 61 20 77 72 61 70 70 65 72  s with a wrapper
10cb0 20 74 68 61 74 20 73 69 6d 75 6c 61 74 69 6f 6e   that simulation
10cc0 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  s memory allocat
10cd0 69 6f 6e 20 66 61 69 6c 75 72 65 20 6f 72 0a 2a  ion failure or.*
10ce0 2a 20 74 72 61 63 6b 73 20 6d 65 6d 6f 72 79 20  * tracks memory 
10cf0 75 73 61 67 65 2c 20 66 6f 72 20 65 78 61 6d 70  usage, for examp
10d00 6c 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  le. </dd>.**.** 
10d10 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
10d20 4d 45 4d 53 54 41 54 55 53 5d 5d 20 3c 64 74 3e  MEMSTATUS]] <dt>
10d30 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
10d40 4d 53 54 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20  MSTATUS</dt>.** 
10d50 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f  <dd> ^This optio
10d60 6e 20 74 61 6b 65 73 20 73 69 6e 67 6c 65 20 61  n takes single a
10d70 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20  rgument of type 
10d80 69 6e 74 2c 20 69 6e 74 65 72 70 72 65 74 65 64  int, interpreted
10d90 20 61 73 20 61 20 0a 2a 2a 20 62 6f 6f 6c 65 61   as a .** boolea
10da0 6e 2c 20 77 68 69 63 68 20 65 6e 61 62 6c 65 73  n, which enables
10db0 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65   or disables the
10dc0 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66 20 6d   collection of m
10dd0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
10de0 20 0a 2a 2a 20 73 74 61 74 69 73 74 69 63 73 2e   .** statistics.
10df0 20 5e 28 57 68 65 6e 20 6d 65 6d 6f 72 79 20 61   ^(When memory a
10e00 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73  llocation statis
10e10 74 69 63 73 20 61 72 65 20 64 69 73 61 62 6c 65  tics are disable
10e20 64 2c 20 74 68 65 20 0a 2a 2a 20 66 6f 6c 6c 6f  d, the .** follo
10e30 77 69 6e 67 20 53 51 4c 69 74 65 20 69 6e 74 65  wing SQLite inte
10e40 72 66 61 63 65 73 20 62 65 63 6f 6d 65 20 6e 6f  rfaces become no
10e50 6e 2d 6f 70 65 72 61 74 69 6f 6e 61 6c 3a 0a 2a  n-operational:.*
10e60 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c  *   <ul>.**   <l
10e70 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  i> [sqlite3_memo
10e80 72 79 5f 75 73 65 64 28 29 5d 0a 2a 2a 20 20 20  ry_used()].**   
10e90 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65  <li> [sqlite3_me
10ea0 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29  mory_highwater()
10eb0 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c  ].**   <li> [sql
10ec0 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c  ite3_soft_heap_l
10ed0 69 6d 69 74 36 34 28 29 5d 0a 2a 2a 20 20 20 3c  imit64()].**   <
10ee0 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 74 61  li> [sqlite3_sta
10ef0 74 75 73 28 29 5d 0a 2a 2a 20 20 20 3c 2f 75 6c  tus()].**   </ul
10f00 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72 79 20 61  >)^.** ^Memory a
10f10 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73  llocation statis
10f20 74 69 63 73 20 61 72 65 20 65 6e 61 62 6c 65 64  tics are enabled
10f30 20 62 79 20 64 65 66 61 75 6c 74 20 75 6e 6c 65   by default unle
10f40 73 73 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20  ss SQLite is.** 
10f50 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53  compiled with [S
10f60 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 4d 45  QLITE_DEFAULT_ME
10f70 4d 53 54 41 54 55 53 5d 3d 30 20 69 6e 20 77 68  MSTATUS]=0 in wh
10f80 69 63 68 20 63 61 73 65 20 6d 65 6d 6f 72 79 0a  ich case memory.
10f90 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74  ** allocation st
10fa0 61 74 69 73 74 69 63 73 20 61 72 65 20 64 69 73  atistics are dis
10fb0 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74  abled by default
10fc0 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ..** </dd>.**.**
10fd0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
10fe0 5f 53 43 52 41 54 43 48 5d 5d 20 3c 64 74 3e 53  _SCRATCH]] <dt>S
10ff0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52  QLITE_CONFIG_SCR
11000 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  ATCH</dt>.** <dd
11010 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73  > ^This option s
11020 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74 69  pecifies a stati
11030 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20  c memory buffer 
11040 74 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20  that SQLite can 
11050 75 73 65 20 66 6f 72 0a 2a 2a 20 73 63 72 61 74  use for.** scrat
11060 63 68 20 6d 65 6d 6f 72 79 2e 20 20 54 68 65 72  ch memory.  Ther
11070 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67 75  e are three argu
11080 6d 65 6e 74 73 3a 20 20 41 20 70 6f 69 6e 74 65  ments:  A pointe
11090 72 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 61  r an 8-byte.** a
110a0 6c 69 67 6e 65 64 20 6d 65 6d 6f 72 79 20 62 75  ligned memory bu
110b0 66 66 65 72 20 66 72 6f 6d 20 77 68 69 63 68 20  ffer from which 
110c0 74 68 65 20 73 63 72 61 74 63 68 20 61 6c 6c 6f  the scratch allo
110d0 63 61 74 69 6f 6e 73 20 77 69 6c 6c 20 62 65 0a  cations will be.
110e0 2a 2a 20 64 72 61 77 6e 2c 20 74 68 65 20 73 69  ** drawn, the si
110f0 7a 65 20 6f 66 20 65 61 63 68 20 73 63 72 61 74  ze of each scrat
11100 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 28 73  ch allocation (s
11110 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74 68 65 20 6d  z),.** and the m
11120 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
11130 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74   scratch allocat
11140 69 6f 6e 73 20 28 4e 29 2e 20 20 54 68 65 20 73  ions (N).  The s
11150 7a 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6d 75  z.** argument mu
11160 73 74 20 62 65 20 61 20 6d 75 6c 74 69 70 6c 65  st be a multiple
11170 20 6f 66 20 31 36 2e 0a 2a 2a 20 54 68 65 20 66   of 16..** The f
11180 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75  irst argument mu
11190 73 74 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20  st be a pointer 
111a0 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 61 6c 69  to an 8-byte ali
111b0 67 6e 65 64 20 62 75 66 66 65 72 0a 2a 2a 20 6f  gned buffer.** o
111c0 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20  f at least sz*N 
111d0 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e  bytes of memory.
111e0 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c  .** ^SQLite will
111f0 20 75 73 65 20 6e 6f 20 6d 6f 72 65 20 74 68 61   use no more tha
11200 6e 20 74 77 6f 20 73 63 72 61 74 63 68 20 62 75  n two scratch bu
11210 66 66 65 72 73 20 70 65 72 20 74 68 72 65 61 64  ffers per thread
11220 2e 20 20 53 6f 0a 2a 2a 20 4e 20 73 68 6f 75 6c  .  So.** N shoul
11230 64 20 62 65 20 73 65 74 20 74 6f 20 74 77 69 63  d be set to twic
11240 65 20 74 68 65 20 65 78 70 65 63 74 65 64 20 6d  e the expected m
11250 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
11260 20 74 68 72 65 61 64 73 2e 0a 2a 2a 20 5e 53 51   threads..** ^SQ
11270 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20  Lite will never 
11280 72 65 71 75 69 72 65 20 61 20 73 63 72 61 74 63  require a scratc
11290 68 20 62 75 66 66 65 72 20 74 68 61 74 20 69 73  h buffer that is
112a0 20 6d 6f 72 65 20 74 68 61 6e 20 36 0a 2a 2a 20   more than 6.** 
112b0 74 69 6d 65 73 20 74 68 65 20 64 61 74 61 62 61  times the databa
112c0 73 65 20 70 61 67 65 20 73 69 7a 65 2e 20 5e 49  se page size. ^I
112d0 66 20 53 51 4c 69 74 65 20 6e 65 65 64 73 20 6e  f SQLite needs n
112e0 65 65 64 73 20 61 64 64 69 74 69 6f 6e 61 6c 0a  eeds additional.
112f0 2a 2a 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72  ** scratch memor
11300 79 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73  y beyond what is
11310 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 69   provided by thi
11320 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  s configuration 
11330 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 0a 2a 2a  option, then .**
11340 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
11350 28 29 5d 20 77 69 6c 6c 20 62 65 20 75 73 65 64  ()] will be used
11360 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 6d   to obtain the m
11370 65 6d 6f 72 79 20 6e 65 65 64 65 64 2e 3c 2f 64  emory needed.</d
11380 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
11390 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43  E_CONFIG_PAGECAC
113a0 48 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  HE]] <dt>SQLITE_
113b0 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45  CONFIG_PAGECACHE
113c0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
113d0 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69  his option speci
113e0 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65  fies a static me
113f0 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68 61 74  mory buffer that
11400 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20   SQLite can use 
11410 66 6f 72 0a 2a 2a 20 74 68 65 20 64 61 74 61 62  for.** the datab
11420 61 73 65 20 70 61 67 65 20 63 61 63 68 65 20 77  ase page cache w
11430 69 74 68 20 74 68 65 20 64 65 66 61 75 6c 74 20  ith the default 
11440 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65  page cache imple
11450 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 0a 2a 2a 20  mentation.  .** 
11460 54 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69  This configurati
11470 6f 6e 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65  on should not be
11480 20 75 73 65 64 20 69 66 20 61 6e 20 61 70 70 6c   used if an appl
11490 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 20 70  ication-define p
114a0 61 67 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70  age.** cache imp
114b0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6c  lementation is l
114c0 6f 61 64 65 64 20 75 73 69 6e 67 20 74 68 65 20  oaded using the 
114d0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
114e0 41 43 48 45 32 20 6f 70 74 69 6f 6e 2e 0a 2a 2a  ACHE2 option..**
114f0 20 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65   There are three
11500 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68   arguments to th
11510 69 73 20 6f 70 74 69 6f 6e 3a 20 41 20 70 6f 69  is option: A poi
11520 6e 74 65 72 20 74 6f 20 38 2d 62 79 74 65 20 61  nter to 8-byte a
11530 6c 69 67 6e 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79  ligned.** memory
11540 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61  , the size of ea
11550 63 68 20 70 61 67 65 20 62 75 66 66 65 72 20 28  ch page buffer (
11560 73 7a 29 2c 20 61 6e 64 20 74 68 65 20 6e 75 6d  sz), and the num
11570 62 65 72 20 6f 66 20 70 61 67 65 73 20 28 4e 29  ber of pages (N)
11580 2e 0a 2a 2a 20 54 68 65 20 73 7a 20 61 72 67 75  ..** The sz argu
11590 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 74  ment should be t
115a0 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6c  he size of the l
115b0 61 72 67 65 73 74 20 64 61 74 61 62 61 73 65 20  argest database 
115c0 70 61 67 65 0a 2a 2a 20 28 61 20 70 6f 77 65 72  page.** (a power
115d0 20 6f 66 20 74 77 6f 20 62 65 74 77 65 65 6e 20   of two between 
115e0 35 31 32 20 61 6e 64 20 33 32 37 36 38 29 20 70  512 and 32768) p
115f0 6c 75 73 20 61 20 6c 69 74 74 6c 65 20 65 78 74  lus a little ext
11600 72 61 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 70  ra for each.** p
11610 61 67 65 20 68 65 61 64 65 72 2e 20 20 5e 54 68  age header.  ^Th
11620 65 20 70 61 67 65 20 68 65 61 64 65 72 20 73 69  e page header si
11630 7a 65 20 69 73 20 32 30 20 74 6f 20 34 30 20 62  ze is 20 to 40 b
11640 79 74 65 73 20 64 65 70 65 6e 64 69 6e 67 20 6f  ytes depending o
11650 6e 0a 2a 2a 20 74 68 65 20 68 6f 73 74 20 61 72  n.** the host ar
11660 63 68 69 74 65 63 74 75 72 65 2e 20 20 5e 49 74  chitecture.  ^It
11670 20 69 73 20 68 61 72 6d 6c 65 73 73 2c 20 61 70   is harmless, ap
11680 61 72 74 20 66 72 6f 6d 20 74 68 65 20 77 61 73  art from the was
11690 74 65 64 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74  ted memory,.** t
116a0 6f 20 6d 61 6b 65 20 73 7a 20 61 20 6c 69 74 74  o make sz a litt
116b0 6c 65 20 74 6f 6f 20 6c 61 72 67 65 2e 20 20 54  le too large.  T
116c0 68 65 20 66 69 72 73 74 0a 2a 2a 20 61 72 67 75  he first.** argu
116d0 6d 65 6e 74 20 73 68 6f 75 6c 64 20 70 6f 69 6e  ment should poin
116e0 74 20 74 6f 20 61 6e 20 61 6c 6c 6f 63 61 74 69  t to an allocati
116f0 6f 6e 20 6f 66 20 61 74 20 6c 65 61 73 74 20 73  on of at least s
11700 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d  z*N bytes of mem
11710 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ory..** ^SQLite 
11720 77 69 6c 6c 20 75 73 65 20 74 68 65 20 6d 65 6d  will use the mem
11730 6f 72 79 20 70 72 6f 76 69 64 65 64 20 62 79 20  ory provided by 
11740 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
11750 6e 74 20 74 6f 20 73 61 74 69 73 66 79 20 69 74  nt to satisfy it
11760 73 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6e 65 65 64  s.** memory need
11770 73 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20  s for the first 
11780 4e 20 70 61 67 65 73 20 74 68 61 74 20 69 74 20  N pages that it 
11790 61 64 64 73 20 74 6f 20 63 61 63 68 65 2e 20 20  adds to cache.  
117a0 5e 49 66 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a  ^If additional.*
117b0 2a 20 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d  * page cache mem
117c0 6f 72 79 20 69 73 20 6e 65 65 64 65 64 20 62 65  ory is needed be
117d0 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f  yond what is pro
117e0 76 69 64 65 64 20 62 79 20 74 68 69 73 20 6f 70  vided by this op
117f0 74 69 6f 6e 2c 20 74 68 65 6e 0a 2a 2a 20 53 51  tion, then.** SQ
11800 4c 69 74 65 20 67 6f 65 73 20 74 6f 20 5b 73 71  Lite goes to [sq
11810 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
11820 66 6f 72 20 74 68 65 20 61 64 64 69 74 69 6f 6e  for the addition
11830 61 6c 20 73 74 6f 72 61 67 65 20 73 70 61 63 65  al storage space
11840 2e 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65 72  ..** The pointer
11850 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72   in the first ar
11860 67 75 6d 65 6e 74 20 6d 75 73 74 0a 2a 2a 20 62  gument must.** b
11870 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20  e aligned to an 
11880 38 2d 62 79 74 65 20 62 6f 75 6e 64 61 72 79 20  8-byte boundary 
11890 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20 62 65  or subsequent be
118a0 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 74 65  havior of SQLite
118b0 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 75 6e 64 65  .** will be unde
118c0 66 69 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  fined.</dd>.**.*
118d0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
118e0 47 5f 48 45 41 50 5d 5d 20 3c 64 74 3e 53 51 4c  G_HEAP]] <dt>SQL
118f0 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3c  ITE_CONFIG_HEAP<
11900 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
11910 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66  is option specif
11920 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d  ies a static mem
11930 6f 72 79 20 62 75 66 66 65 72 20 74 68 61 74 20  ory buffer that 
11940 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a  SQLite will use.
11950 2a 2a 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74  ** for all of it
11960 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79  s dynamic memory
11970 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64   allocation need
11980 73 20 62 65 79 6f 6e 64 20 74 68 6f 73 65 20 70  s beyond those p
11990 72 6f 76 69 64 65 64 0a 2a 2a 20 66 6f 72 20 62  rovided.** for b
119a0 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  y [SQLITE_CONFIG
119b0 5f 53 43 52 41 54 43 48 5d 20 61 6e 64 20 5b 53  _SCRATCH] and [S
119c0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47  QLITE_CONFIG_PAG
119d0 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 54 68 65 72  ECACHE]..** Ther
119e0 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67 75  e are three argu
119f0 6d 65 6e 74 73 3a 20 41 6e 20 38 2d 62 79 74 65  ments: An 8-byte
11a00 20 61 6c 69 67 6e 65 64 20 70 6f 69 6e 74 65 72   aligned pointer
11a10 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c 0a   to the memory,.
11a20 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ** the number of
11a30 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 6d 65   bytes in the me
11a40 6d 6f 72 79 20 62 75 66 66 65 72 2c 20 61 6e 64  mory buffer, and
11a50 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c   the minimum all
11a60 6f 63 61 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a 2a  ocation size..**
11a70 20 5e 49 66 20 74 68 65 20 66 69 72 73 74 20 70   ^If the first p
11a80 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f  ointer (the memo
11a90 72 79 20 70 6f 69 6e 74 65 72 29 20 69 73 20 4e  ry pointer) is N
11aa0 55 4c 4c 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  ULL, then SQLite
11ab0 20 72 65 76 65 72 74 73 0a 2a 2a 20 74 6f 20 75   reverts.** to u
11ac0 73 69 6e 67 20 69 74 73 20 64 65 66 61 75 6c 74  sing its default
11ad0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
11ae0 72 20 28 74 68 65 20 73 79 73 74 65 6d 20 6d 61  r (the system ma
11af0 6c 6c 6f 63 28 29 20 69 6d 70 6c 65 6d 65 6e 74  lloc() implement
11b00 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f 69  ation),.** undoi
11b10 6e 67 20 61 6e 79 20 70 72 69 6f 72 20 69 6e 76  ng any prior inv
11b20 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 53 51 4c 49  ocation of [SQLI
11b30 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
11b40 5d 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 6d  ].  ^If the.** m
11b50 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 20 69 73  emory pointer is
11b60 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 65 69   not NULL and ei
11b70 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41  ther [SQLITE_ENA
11b80 42 4c 45 5f 4d 45 4d 53 59 53 33 5d 20 6f 72 0a  BLE_MEMSYS3] or.
11b90 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c  ** [SQLITE_ENABL
11ba0 45 5f 4d 45 4d 53 59 53 35 5d 20 61 72 65 20 64  E_MEMSYS5] are d
11bb0 65 66 69 6e 65 64 2c 20 74 68 65 6e 20 74 68 65  efined, then the
11bc0 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6d 65 6d   alternative mem
11bd0 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72  ory.** allocator
11be0 20 69 73 20 65 6e 67 61 67 65 64 20 74 6f 20 68   is engaged to h
11bf0 61 6e 64 6c 65 20 61 6c 6c 20 6f 66 20 53 51 4c  andle all of SQL
11c00 69 74 65 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ites memory allo
11c10 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a 2a  cation needs..**
11c20 20 54 68 65 20 66 69 72 73 74 20 70 6f 69 6e 74   The first point
11c30 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 70  er (the memory p
11c40 6f 69 6e 74 65 72 29 20 6d 75 73 74 20 62 65 20  ointer) must be 
11c50 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d  aligned to an 8-
11c60 62 79 74 65 0a 2a 2a 20 62 6f 75 6e 64 61 72 79  byte.** boundary
11c70 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20 62   or subsequent b
11c80 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 74  ehavior of SQLit
11c90 65 20 77 69 6c 6c 20 62 65 20 75 6e 64 65 66 69  e will be undefi
11ca0 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 6d 69 6e 69  ned..** The mini
11cb0 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  mum allocation s
11cc0 69 7a 65 20 69 73 20 63 61 70 70 65 64 20 61 74  ize is capped at
11cd0 20 32 2a 2a 31 32 2e 20 52 65 61 73 6f 6e 61 62   2**12. Reasonab
11ce0 6c 65 20 76 61 6c 75 65 73 0a 2a 2a 20 66 6f 72  le values.** for
11cf0 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c   the minimum all
11d00 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 61 72 65  ocation size are
11d10 20 32 2a 2a 35 20 74 68 72 6f 75 67 68 20 32 2a   2**5 through 2*
11d20 2a 38 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  *8.</dd>.**.** [
11d30 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
11d40 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  UTEX]] <dt>SQLIT
11d50 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 3c 2f  E_CONFIG_MUTEX</
11d60 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68  dt>.** <dd> ^(Th
11d70 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
11d80 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
11d90 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69  t which is a poi
11da0 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e  nter to an.** in
11db0 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73  stance of the [s
11dc0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
11dd0 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e  hods] structure.
11de0 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73    The argument s
11df0 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65  pecifies.** alte
11e00 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65  rnative low-leve
11e10 6c 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73  l mutex routines
11e20 20 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70   to be used in p
11e30 6c 61 63 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65  lace.** the mute
11e40 78 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74  x routines built
11e50 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20   into SQLite.)^ 
11e60 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61   ^SQLite makes a
11e70 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20   copy of the.** 
11e80 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 5b  content of the [
11e90 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65  sqlite3_mutex_me
11ea0 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65  thods] structure
11eb0 20 62 65 66 6f 72 65 20 74 68 65 20 63 61 6c 6c   before the call
11ec0 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
11ed0 63 6f 6e 66 69 67 28 29 5d 20 72 65 74 75 72 6e  config()] return
11ee0 73 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73  s. ^If SQLite is
11ef0 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
11f00 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48  * the [SQLITE_TH
11f10 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54  READSAFE | SQLIT
11f20 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20  E_THREADSAFE=0] 
11f30 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
11f40 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20  ion then.** the 
11f50 65 6e 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20  entire mutexing 
11f60 73 75 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69  subsystem is omi
11f70 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75  tted from the bu
11f80 69 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61  ild and hence ca
11f90 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  lls to.** [sqlit
11fa0 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74  e3_config()] wit
11fb0 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  h the SQLITE_CON
11fc0 46 49 47 5f 4d 55 54 45 58 20 63 6f 6e 66 69 67  FIG_MUTEX config
11fd0 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77  uration option w
11fe0 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53  ill.** return [S
11ff0 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64  QLITE_ERROR].</d
12000 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
12010 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45  E_CONFIG_GETMUTE
12020 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  X]] <dt>SQLITE_C
12030 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 3c 2f  ONFIG_GETMUTEX</
12040 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68  dt>.** <dd> ^(Th
12050 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
12060 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
12070 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69  t which is a poi
12080 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e  nter to an.** in
12090 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73  stance of the [s
120a0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
120b0 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e  hods] structure.
120c0 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65    The.** [sqlite
120d0 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d  3_mutex_methods]
120e0 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69 73  .** structure is
120f0 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65   filled with the
12100 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e   currently defin
12110 65 64 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65  ed mutex routine
12120 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74  s.)^.** This opt
12130 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20  ion can be used 
12140 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20  to overload the 
12150 64 65 66 61 75 6c 74 20 6d 75 74 65 78 20 61 6c  default mutex al
12160 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74  location.** rout
12170 69 6e 65 73 20 77 69 74 68 20 61 20 77 72 61 70  ines with a wrap
12180 70 65 72 20 75 73 65 64 20 74 6f 20 74 72 61 63  per used to trac
12190 6b 20 6d 75 74 65 78 20 75 73 61 67 65 20 66 6f  k mutex usage fo
121a0 72 20 70 65 72 66 6f 72 6d 61 6e 63 65 0a 2a 2a  r performance.**
121b0 20 70 72 6f 66 69 6c 69 6e 67 20 6f 72 20 74 65   profiling or te
121c0 73 74 69 6e 67 2c 20 66 6f 72 20 65 78 61 6d 70  sting, for examp
121d0 6c 65 2e 20 20 20 5e 49 66 20 53 51 4c 69 74 65  le.   ^If SQLite
121e0 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
121f0 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  h.** the [SQLITE
12200 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51  _THREADSAFE | SQ
12210 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
12220 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  0] compile-time 
12230 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74  option then.** t
12240 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65 78 69  he entire mutexi
12250 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69 73 20  ng subsystem is 
12260 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65  omitted from the
12270 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e 63 65   build and hence
12280 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71   calls to.** [sq
12290 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
122a0 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f  with the SQLITE_
122b0 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20  CONFIG_GETMUTEX 
122c0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
122d0 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74  tion will.** ret
122e0 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  urn [SQLITE_ERRO
122f0 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  R].</dd>.**.** [
12300 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c  [SQLITE_CONFIG_L
12310 4f 4f 4b 41 53 49 44 45 5d 5d 20 3c 64 74 3e 53  OOKASIDE]] <dt>S
12320 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f  QLITE_CONFIG_LOO
12330 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c  KASIDE</dt>.** <
12340 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f  dd> ^(This optio
12350 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75  n takes two argu
12360 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 65 72  ments that deter
12370 6d 69 6e 65 20 74 68 65 20 64 65 66 61 75 6c 74  mine the default
12380 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  .** memory alloc
12390 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 6c 6f  ation for the lo
123a0 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61  okaside memory a
123b0 6c 6c 6f 63 61 74 6f 72 20 6f 6e 20 65 61 63 68  llocator on each
123c0 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
123d0 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20  nnection].  The 
123e0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69  first argument i
123f0 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66  s the.** size of
12400 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20   each lookaside 
12410 62 75 66 66 65 72 20 73 6c 6f 74 20 61 6e 64 20  buffer slot and 
12420 74 68 65 20 73 65 63 6f 6e 64 20 69 73 20 74 68  the second is th
12430 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73  e number of.** s
12440 6c 6f 74 73 20 61 6c 6c 6f 63 61 74 65 64 20 74  lots allocated t
12450 6f 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20  o each database 
12460 63 6f 6e 6e 65 63 74 69 6f 6e 2e 29 5e 20 20 5e  connection.)^  ^
12470 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74  (This option set
12480 73 20 74 68 65 0a 2a 2a 20 3c 69 3e 64 65 66 61  s the.** <i>defa
12490 75 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 73 69 64  ult</i> lookasid
124a0 65 20 73 69 7a 65 2e 20 54 68 65 20 5b 53 51 4c  e size. The [SQL
124b0 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
124c0 4b 41 53 49 44 45 5d 0a 2a 2a 20 76 65 72 62 20  KASIDE].** verb 
124d0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63  to [sqlite3_db_c
124e0 6f 6e 66 69 67 28 29 5d 20 63 61 6e 20 62 65 20  onfig()] can be 
124f0 75 73 65 64 20 74 6f 20 63 68 61 6e 67 65 20 74  used to change t
12500 68 65 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20  he lookaside.** 
12510 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 6e  configuration on
12520 20 69 6e 64 69 76 69 64 75 61 6c 20 63 6f 6e 6e   individual conn
12530 65 63 74 69 6f 6e 73 2e 29 5e 20 3c 2f 64 64 3e  ections.)^ </dd>
12540 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
12550 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 5d 5d  CONFIG_PCACHE2]]
12560 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
12570 49 47 5f 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a  IG_PCACHE2</dt>.
12580 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f  ** <dd> ^(This o
12590 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
125a0 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
125b0 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ich is a pointer
125c0 20 74 6f 0a 2a 2a 20 61 6e 20 5b 73 71 6c 69 74   to.** an [sqlit
125d0 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64  e3_pcache_method
125e0 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 69  s2] object.  Thi
125f0 73 20 6f 62 6a 65 63 74 20 73 70 65 63 69 66 69  s object specifi
12600 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
12610 0a 2a 2a 20 74 6f 20 61 20 63 75 73 74 6f 6d 20  .** to a custom 
12620 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65  page cache imple
12630 6d 65 6e 74 61 74 69 6f 6e 2e 29 5e 20 20 5e 53  mentation.)^  ^S
12640 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f  QLite makes a co
12650 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 62 6a  py of the.** obj
12660 65 63 74 20 61 6e 64 20 75 73 65 73 20 69 74 20  ect and uses it 
12670 66 6f 72 20 70 61 67 65 20 63 61 63 68 65 20 6d  for page cache m
12680 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
12690 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  s.</dd>.**.** [[
126a0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
126b0 54 50 43 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53  TPCACHE2]] <dt>S
126c0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
126d0 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20  PCACHE2</dt>.** 
126e0 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69  <dd> ^(This opti
126f0 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
12700 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
12710 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
12720 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   an.** [sqlite3_
12730 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d  pcache_methods2]
12740 20 6f 62 6a 65 63 74 2e 20 20 53 51 4c 69 74 65   object.  SQLite
12750 20 63 6f 70 69 65 73 20 6f 66 20 74 68 65 20 63   copies of the c
12760 75 72 72 65 6e 74 0a 2a 2a 20 70 61 67 65 20 63  urrent.** page c
12770 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  ache implementat
12780 69 6f 6e 20 69 6e 74 6f 20 74 68 61 74 20 6f 62  ion into that ob
12790 6a 65 63 74 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a  ject.)^ </dd>.**
127a0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
127b0 46 49 47 5f 4c 4f 47 5d 5d 20 3c 64 74 3e 53 51  FIG_LOG]] <dt>SQ
127c0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 3c  LITE_CONFIG_LOG<
127d0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
127e0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
127f0 4c 4f 47 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  LOG option takes
12800 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 3a 20   two arguments: 
12810 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 0a 2a  a pointer to a.*
12820 2a 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20  * function with 
12830 61 20 63 61 6c 6c 20 73 69 67 6e 61 74 75 72 65  a call signature
12840 20 6f 66 20 76 6f 69 64 28 2a 29 28 76 6f 69 64   of void(*)(void
12850 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72  *,int,const char
12860 2a 29 2c 20 0a 2a 2a 20 61 6e 64 20 61 20 70 6f  *), .** and a po
12870 69 6e 74 65 72 20 74 6f 20 76 6f 69 64 2e 20 5e  inter to void. ^
12880 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  If the function 
12890 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e  pointer is not N
128a0 55 4c 4c 2c 20 69 74 20 69 73 0a 2a 2a 20 69 6e  ULL, it is.** in
128b0 76 6f 6b 65 64 20 62 79 20 5b 73 71 6c 69 74 65  voked by [sqlite
128c0 33 5f 6c 6f 67 28 29 5d 20 74 6f 20 70 72 6f 63  3_log()] to proc
128d0 65 73 73 20 65 61 63 68 20 6c 6f 67 67 69 6e 67  ess each logging
128e0 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65   event.  ^If the
128f0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69  .** function poi
12900 6e 74 65 72 20 69 73 20 4e 55 4c 4c 2c 20 74 68  nter is NULL, th
12910 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29  e [sqlite3_log()
12920 5d 20 69 6e 74 65 72 66 61 63 65 20 62 65 63 6f  ] interface beco
12930 6d 65 73 20 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a 20  mes a no-op..** 
12940 5e 54 68 65 20 76 6f 69 64 20 70 6f 69 6e 74 65  ^The void pointe
12950 72 20 74 68 61 74 20 69 73 20 74 68 65 20 73 65  r that is the se
12960 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
12970 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c   SQLITE_CONFIG_L
12980 4f 47 20 69 73 0a 2a 2a 20 70 61 73 73 65 64 20  OG is.** passed 
12990 74 68 72 6f 75 67 68 20 61 73 20 74 68 65 20 66  through as the f
129a0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
129b0 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  o the applicatio
129c0 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72  n-defined logger
129d0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 68 65  .** function whe
129e0 6e 65 76 65 72 20 74 68 61 74 20 66 75 6e 63 74  never that funct
129f0 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20  ion is invoked. 
12a00 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72   ^The second par
12a10 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65  ameter to.** the
12a20 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f 6e   logger function
12a30 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68   is a copy of th
12a40 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
12a50 72 20 74 6f 20 74 68 65 20 63 6f 72 72 65 73 70  r to the corresp
12a60 6f 6e 64 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74  onding.** [sqlit
12a70 65 33 5f 6c 6f 67 28 29 5d 20 63 61 6c 6c 20 61  e3_log()] call a
12a80 6e 64 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74  nd is intended t
12a90 6f 20 62 65 20 61 20 5b 72 65 73 75 6c 74 20 63  o be a [result c
12aa0 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65  ode] or an.** [e
12ab0 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
12ac0 6f 64 65 5d 2e 20 20 5e 54 68 65 20 74 68 69 72  ode].  ^The thir
12ad0 64 20 70 61 72 61 6d 65 74 65 72 20 70 61 73 73  d parameter pass
12ae0 65 64 20 74 6f 20 74 68 65 20 6c 6f 67 67 65 72  ed to the logger
12af0 20 69 73 0a 2a 2a 20 6c 6f 67 20 6d 65 73 73 61   is.** log messa
12b00 67 65 20 61 66 74 65 72 20 66 6f 72 6d 61 74 74  ge after formatt
12b10 69 6e 67 20 76 69 61 20 5b 73 71 6c 69 74 65 33  ing via [sqlite3
12b20 5f 73 6e 70 72 69 6e 74 66 28 29 5d 2e 0a 2a 2a  _snprintf()]..**
12b30 20 54 68 65 20 53 51 4c 69 74 65 20 6c 6f 67 67   The SQLite logg
12b40 69 6e 67 20 69 6e 74 65 72 66 61 63 65 20 69 73  ing interface is
12b50 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74 3b 20   not reentrant; 
12b60 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74  the logger funct
12b70 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69 65 64 20  ion.** supplied 
12b80 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  by the applicati
12b90 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 69 6e 76 6f  on must not invo
12ba0 6b 65 20 61 6e 79 20 53 51 4c 69 74 65 20 69 6e  ke any SQLite in
12bb0 74 65 72 66 61 63 65 2e 0a 2a 2a 20 49 6e 20 61  terface..** In a
12bc0 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64 20   multi-threaded 
12bd0 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20 74 68 65  application, the
12be0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
12bf0 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66  ined logger.** f
12c00 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 20  unction must be 
12c10 74 68 72 65 61 64 73 61 66 65 2e 20 3c 2f 64 64  threadsafe. </dd
12c20 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
12c30 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 5d 20 3c 64  _CONFIG_URI]] <d
12c40 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
12c50 55 52 49 0a 2a 2a 20 3c 64 64 3e 20 54 68 69 73  URI.** <dd> This
12c60 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
12c70 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
12c80 6f 66 20 74 79 70 65 20 69 6e 74 2e 20 49 66 20  of type int. If 
12c90 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 0a 2a  non-zero, then.*
12ca0 2a 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69  * URI handling i
12cb0 73 20 67 6c 6f 62 61 6c 6c 79 20 65 6e 61 62 6c  s globally enabl
12cc0 65 64 2e 20 49 66 20 74 68 65 20 70 61 72 61 6d  ed. If the param
12cd0 65 74 65 72 20 69 73 20 7a 65 72 6f 2c 20 74 68  eter is zero, th
12ce0 65 6e 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 0a  en URI handling.
12cf0 2a 2a 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64  ** is globally d
12d00 69 73 61 62 6c 65 64 2e 20 49 66 20 55 52 49 20  isabled. If URI 
12d10 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62  handling is glob
12d20 61 6c 6c 79 20 65 6e 61 62 6c 65 64 2c 20 61 6c  ally enabled, al
12d30 6c 20 66 69 6c 65 6e 61 6d 65 73 0a 2a 2a 20 70  l filenames.** p
12d40 61 73 73 65 64 20 74 6f 20 5b 73 71 6c 69 74 65  assed to [sqlite
12d50 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69  3_open()], [sqli
12d60 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20  te3_open_v2()], 
12d70 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
12d80 29 5d 20 6f 72 0a 2a 2a 20 73 70 65 63 69 66 69  )] or.** specifi
12d90 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 5b 41  ed as part of [A
12da0 54 54 41 43 48 5d 20 63 6f 6d 6d 61 6e 64 73 20  TTACH] commands 
12db0 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 20  are interpreted 
12dc0 61 73 20 55 52 49 73 2c 20 72 65 67 61 72 64 6c  as URIs, regardl
12dd0 65 73 73 0a 2a 2a 20 6f 66 20 77 68 65 74 68 65  ess.** of whethe
12de0 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 5b 53 51  r or not the [SQ
12df0 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66  LITE_OPEN_URI] f
12e00 6c 61 67 20 69 73 20 73 65 74 20 77 68 65 6e 20  lag is set when 
12e10 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  the database.** 
12e20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70  connection is op
12e30 65 6e 65 64 2e 20 49 66 20 69 74 20 69 73 20 67  ened. If it is g
12e40 6c 6f 62 61 6c 6c 79 20 64 69 73 61 62 6c 65 64  lobally disabled
12e50 2c 20 66 69 6c 65 6e 61 6d 65 73 20 61 72 65 0a  , filenames are.
12e60 2a 2a 20 6f 6e 6c 79 20 69 6e 74 65 72 70 72 65  ** only interpre
12e70 74 65 64 20 61 73 20 55 52 49 73 20 69 66 20 74  ted as URIs if t
12e80 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55  he SQLITE_OPEN_U
12e90 52 49 20 66 6c 61 67 20 69 73 20 73 65 74 20 77  RI flag is set w
12ea0 68 65 6e 20 74 68 65 0a 2a 2a 20 64 61 74 61 62  hen the.** datab
12eb0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
12ec0 73 20 6f 70 65 6e 65 64 2e 20 42 79 20 64 65 66  s opened. By def
12ed0 61 75 6c 74 2c 20 55 52 49 20 68 61 6e 64 6c 69  ault, URI handli
12ee0 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a  ng is globally.*
12ef0 2a 20 64 69 73 61 62 6c 65 64 2e 20 54 68 65 20  * disabled. The 
12f00 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 6d 61  default value ma
12f10 79 20 62 65 20 63 68 61 6e 67 65 64 20 62 79 20  y be changed by 
12f20 63 6f 6d 70 69 6c 69 6e 67 20 77 69 74 68 20 74  compiling with t
12f30 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 53  he.** [SQLITE_US
12f40 45 5f 55 52 49 5d 20 73 79 6d 62 6f 6c 20 64 65  E_URI] symbol de
12f50 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  fined..**.** [[S
12f60 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56  QLITE_CONFIG_COV
12f70 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e  ERING_INDEX_SCAN
12f80 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
12f90 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e  NFIG_COVERING_IN
12fa0 44 45 58 5f 53 43 41 4e 0a 2a 2a 20 3c 64 64 3e  DEX_SCAN.** <dd>
12fb0 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b   This option tak
12fc0 73 20 61 20 73 69 6e 67 6c 65 20 69 6e 74 65 67  s a single integ
12fd0 65 72 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  er argument whic
12fe0 68 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64  h is interpreted
12ff0 20 61 73 0a 2a 2a 20 61 20 62 6f 6f 6c 65 61 6e   as.** a boolean
13000 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 65 6e 61   in order to ena
13010 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 74  ble or disable t
13020 68 65 20 75 73 65 20 6f 66 20 63 6f 76 65 72 69  he use of coveri
13030 6e 67 20 69 6e 64 69 63 65 73 20 66 6f 72 0a 2a  ng indices for.*
13040 2a 20 66 75 6c 6c 20 74 61 62 6c 65 20 73 63 61  * full table sca
13050 6e 73 20 69 6e 20 74 68 65 20 71 75 65 72 79 20  ns in the query 
13060 6f 70 74 69 6d 69 7a 65 72 2e 20 20 54 68 65 20  optimizer.  The 
13070 64 65 66 61 75 6c 74 20 73 65 74 74 69 6e 67 20  default setting 
13080 69 73 20 64 65 74 65 72 6d 69 6e 65 64 0a 2a 2a  is determined.**
13090 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   by the [SQLITE_
130a0 41 4c 4c 4f 57 5f 43 4f 56 45 52 49 4e 47 5f 49  ALLOW_COVERING_I
130b0 4e 44 45 58 5f 53 43 41 4e 5d 20 63 6f 6d 70 69  NDEX_SCAN] compi
130c0 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20  le-time option, 
130d0 6f 72 20 69 73 20 22 6f 6e 22 0a 2a 2a 20 69 66  or is "on".** if
130e0 20 74 68 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69   that compile-ti
130f0 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6d 69  me option is omi
13100 74 74 65 64 2e 0a 2a 2a 20 54 68 65 20 61 62 69  tted..** The abi
13110 6c 69 74 79 20 74 6f 20 64 69 73 61 62 6c 65 20  lity to disable 
13120 74 68 65 20 75 73 65 20 6f 66 20 63 6f 76 65 72  the use of cover
13130 69 6e 67 20 69 6e 64 69 63 65 73 20 66 6f 72 20  ing indices for 
13140 66 75 6c 6c 20 74 61 62 6c 65 20 73 63 61 6e 73  full table scans
13150 0a 2a 2a 20 69 73 20 62 65 63 61 75 73 65 20 73  .** is because s
13160 6f 6d 65 20 69 6e 63 6f 72 72 65 63 74 6c 79 20  ome incorrectly 
13170 63 6f 64 65 64 20 6c 65 67 61 63 79 20 61 70 70  coded legacy app
13180 6c 69 63 61 74 69 6f 6e 73 20 6d 69 67 68 74 20  lications might 
13190 6d 61 6c 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d  malfunction.** m
131a0 61 6c 66 75 6e 63 74 69 6f 6e 20 77 68 65 6e 20  alfunction when 
131b0 74 68 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e  the optimization
131c0 20 69 73 20 65 6e 61 62 6c 65 64 2e 20 20 50 72   is enabled.  Pr
131d0 6f 76 69 64 69 6e 67 20 74 68 65 20 61 62 69 6c  oviding the abil
131e0 69 74 79 20 74 6f 0a 2a 2a 20 64 69 73 61 62 6c  ity to.** disabl
131f0 65 20 74 68 65 20 6f 70 74 69 6d 69 7a 61 74 69  e the optimizati
13200 6f 6e 20 61 6c 6c 6f 77 73 20 74 68 65 20 6f 6c  on allows the ol
13210 64 65 72 2c 20 62 75 67 67 79 20 61 70 70 6c 69  der, buggy appli
13220 63 61 74 69 6f 6e 20 63 6f 64 65 20 74 6f 20 77  cation code to w
13230 6f 72 6b 0a 2a 2a 20 77 69 74 68 6f 75 74 20 63  ork.** without c
13240 68 61 6e 67 65 20 65 76 65 6e 20 77 69 74 68 20  hange even with 
13250 6e 65 77 65 72 20 76 65 72 73 69 6f 6e 73 20 6f  newer versions o
13260 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20  f SQLite..**.** 
13270 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
13280 50 43 41 43 48 45 5d 5d 20 5b 5b 53 51 4c 49 54  PCACHE]] [[SQLIT
13290 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43  E_CONFIG_GETPCAC
132a0 48 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  HE]].** <dt>SQLI
132b0 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
132c0 20 61 6e 64 20 53 51 4c 49 54 45 5f 43 4f 4e 46   and SQLITE_CONF
132d0 49 47 5f 47 45 54 50 43 41 43 48 45 0a 2a 2a 20  IG_GETPCACHE.** 
132e0 3c 64 64 3e 20 54 68 65 73 65 20 6f 70 74 69 6f  <dd> These optio
132f0 6e 73 20 61 72 65 20 6f 62 73 6f 6c 65 74 65 20  ns are obsolete 
13300 61 6e 64 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62  and should not b
13310 65 20 75 73 65 64 20 62 79 20 6e 65 77 20 63 6f  e used by new co
13320 64 65 2e 0a 2a 2a 20 54 68 65 79 20 61 72 65 20  de..** They are 
13330 72 65 74 61 69 6e 65 64 20 66 6f 72 20 62 61 63  retained for bac
13340 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69  kwards compatibi
13350 6c 69 74 79 20 62 75 74 20 61 72 65 20 6e 6f 77  lity but are now
13360 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 20 3c 2f 64 6c   no-ops..** </dl
13370 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  >.*/.#define SQL
13380 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c  ITE_CONFIG_SINGL
13390 45 54 48 52 45 41 44 20 20 31 20 20 2f 2a 20 6e  ETHREAD  1  /* n
133a0 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  il */.#define SQ
133b0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54  LITE_CONFIG_MULT
133c0 49 54 48 52 45 41 44 20 20 20 32 20 20 2f 2a 20  ITHREAD   2  /* 
133d0 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nil */.#define S
133e0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52  QLITE_CONFIG_SER
133f0 49 41 4c 49 5a 45 44 20 20 20 20 33 20 20 2f 2a  IALIZED    3  /*
13400 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20   nil */.#define 
13410 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41  SQLITE_CONFIG_MA
13420 4c 4c 4f 43 20 20 20 20 20 20 20 20 34 20 20 2f  LLOC        4  /
13430 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65  * sqlite3_mem_me
13440 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e  thods* */.#defin
13450 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
13460 47 45 54 4d 41 4c 4c 4f 43 20 20 20 20 20 35 20  GETMALLOC     5 
13470 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f   /* sqlite3_mem_
13480 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66  methods* */.#def
13490 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
134a0 47 5f 53 43 52 41 54 43 48 20 20 20 20 20 20 20  G_SCRATCH       
134b0 36 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74  6  /* void*, int
134c0 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64   sz, int N */.#d
134d0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
134e0 46 49 47 5f 50 41 47 45 43 41 43 48 45 20 20 20  FIG_PAGECACHE   
134f0 20 20 37 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69    7  /* void*, i
13500 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a  nt sz, int N */.
13510 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
13520 4f 4e 46 49 47 5f 48 45 41 50 20 20 20 20 20 20  ONFIG_HEAP      
13530 20 20 20 20 38 20 20 2f 2a 20 76 6f 69 64 2a 2c      8  /* void*,
13540 20 69 6e 74 20 6e 42 79 74 65 2c 20 69 6e 74 20   int nByte, int 
13550 6d 69 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  min */.#define S
13560 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d  QLITE_CONFIG_MEM
13570 53 54 41 54 55 53 20 20 20 20 20 39 20 20 2f 2a  STATUS     9  /*
13580 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 23 64 65 66   boolean */.#def
13590 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
135a0 47 5f 4d 55 54 45 58 20 20 20 20 20 20 20 20 31  G_MUTEX        1
135b0 30 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75  0  /* sqlite3_mu
135c0 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a  tex_methods* */.
135d0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
135e0 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20 20  ONFIG_GETMUTEX  
135f0 20 20 20 31 31 20 20 2f 2a 20 73 71 6c 69 74 65     11  /* sqlite
13600 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a  3_mutex_methods*
13610 20 2a 2f 0a 2f 2a 20 70 72 65 76 69 6f 75 73 6c   */./* previousl
13620 79 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  y SQLITE_CONFIG_
13630 43 48 55 4e 4b 41 4c 4c 4f 43 20 31 32 20 77 68  CHUNKALLOC 12 wh
13640 69 63 68 20 69 73 20 6e 6f 77 20 75 6e 75 73 65  ich is now unuse
13650 64 2e 20 2a 2f 20 0a 23 64 65 66 69 6e 65 20 53  d. */ .#define S
13660 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f  QLITE_CONFIG_LOO
13670 4b 41 53 49 44 45 20 20 20 20 31 33 20 20 2f 2a  KASIDE    13  /*
13680 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66   int int */.#def
13690 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
136a0 47 5f 50 43 41 43 48 45 20 20 20 20 20 20 20 31  G_PCACHE       1
136b0 34 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23  4  /* no-op */.#
136c0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
136d0 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 20 20  NFIG_GETPCACHE  
136e0 20 20 31 35 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a    15  /* no-op *
136f0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
13700 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 20 20 20 20  _CONFIG_LOG     
13710 20 20 20 20 20 31 36 20 20 2f 2a 20 78 46 75 6e       16  /* xFun
13720 63 2c 20 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66  c, void* */.#def
13730 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
13740 47 5f 55 52 49 20 20 20 20 20 20 20 20 20 20 31  G_URI          1
13750 37 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65  7  /* int */.#de
13760 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
13770 49 47 5f 50 43 41 43 48 45 32 20 20 20 20 20 20  IG_PCACHE2      
13780 31 38 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70  18  /* sqlite3_p
13790 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 2a 20  cache_methods2* 
137a0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
137b0 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43  E_CONFIG_GETPCAC
137c0 48 45 32 20 20 20 31 39 20 20 2f 2a 20 73 71 6c  HE2   19  /* sql
137d0 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68  ite3_pcache_meth
137e0 6f 64 73 32 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  ods2* */.#define
137f0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43   SQLITE_CONFIG_C
13800 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43  OVERING_INDEX_SC
13810 41 4e 20 32 30 20 20 2f 2a 20 69 6e 74 20 2a 2f  AN 20  /* int */
13820 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
13830 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65  : Database Conne
13840 63 74 69 6f 6e 20 43 6f 6e 66 69 67 75 72 61 74  ction Configurat
13850 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 0a 2a  ion Options.**.*
13860 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74  * These constant
13870 73 20 61 72 65 20 74 68 65 20 61 76 61 69 6c 61  s are the availa
13880 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66  ble integer conf
13890 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
138a0 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65  s that.** can be
138b0 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73   passed as the s
138c0 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  econd argument t
138d0 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 64  o the [sqlite3_d
138e0 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65  b_config()] inte
138f0 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77  rface..**.** New
13900 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
13910 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64  ptions may be ad
13920 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65  ded in future re
13930 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65  leases of SQLite
13940 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f  ..** Existing co
13950 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
13960 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69 73  ons might be dis
13970 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c  continued.  Appl
13980 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75  ications.** shou
13990 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72 65 74  ld check the ret
139a0 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73  urn code from [s
139b0 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
139c0 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65  ()] to make sure
139d0 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c   that.** the cal
139e0 6c 20 77 6f 72 6b 65 64 2e 20 20 5e 54 68 65 20  l worked.  ^The 
139f0 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66  [sqlite3_db_conf
13a00 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  ig()] interface 
13a10 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a  will return a.**
13a20 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72   non-zero [error
13a30 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63   code] if a disc
13a40 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75  ontinued or unsu
13a50 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72  pported configur
13a60 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20  ation option.** 
13a70 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a  is invoked..**.*
13a80 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51  * <dl>.** <dt>SQ
13a90 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f  LITE_DBCONFIG_LO
13aa0 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20  OKASIDE</dt>.** 
13ab0 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f  <dd> ^This optio
13ac0 6e 20 74 61 6b 65 73 20 74 68 72 65 65 20 61 64  n takes three ad
13ad0 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e  ditional argumen
13ae0 74 73 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e  ts that determin
13af0 65 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61  e the .** [looka
13b00 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  side memory allo
13b10 63 61 74 6f 72 5d 20 63 6f 6e 66 69 67 75 72 61  cator] configura
13b20 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 5b 64 61  tion for the [da
13b30 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
13b40 6e 5d 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  n]..** ^The firs
13b50 74 20 61 72 67 75 6d 65 6e 74 20 28 74 68 65 20  t argument (the 
13b60 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
13b70 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63  to [sqlite3_db_c
13b80 6f 6e 66 69 67 28 29 5d 20 69 73 20 61 0a 2a 2a  onfig()] is a.**
13b90 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65   pointer to a me
13ba0 6d 6f 72 79 20 62 75 66 66 65 72 20 74 6f 20 75  mory buffer to u
13bb0 73 65 20 66 6f 72 20 6c 6f 6f 6b 61 73 69 64 65  se for lookaside
13bc0 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 54 68 65   memory..** ^The
13bd0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
13be0 61 66 74 65 72 20 74 68 65 20 53 51 4c 49 54 45  after the SQLITE
13bf0 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  _DBCONFIG_LOOKAS
13c00 49 44 45 20 76 65 72 62 0a 2a 2a 20 6d 61 79 20  IDE verb.** may 
13c10 62 65 20 4e 55 4c 4c 20 69 6e 20 77 68 69 63 68  be NULL in which
13c20 20 63 61 73 65 20 53 51 4c 69 74 65 20 77 69 6c   case SQLite wil
13c30 6c 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 0a 2a  l allocate the.*
13c40 2a 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66  * lookaside buff
13c50 65 72 20 69 74 73 65 6c 66 20 75 73 69 6e 67 20  er itself using 
13c60 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
13c70 29 5d 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  )]. ^The second 
13c80 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a  argument is the.
13c90 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20  ** size of each 
13ca0 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72  lookaside buffer
13cb0 20 73 6c 6f 74 2e 20 20 5e 54 68 65 20 74 68 69   slot.  ^The thi
13cc0 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  rd argument is t
13cd0 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20  he number of.** 
13ce0 73 6c 6f 74 73 2e 20 20 54 68 65 20 73 69 7a 65  slots.  The size
13cf0 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 20 69   of the buffer i
13d00 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  n the first argu
13d10 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 67 72 65  ment must be gre
13d20 61 74 65 72 20 74 68 61 6e 0a 2a 2a 20 6f 72 20  ater than.** or 
13d30 65 71 75 61 6c 20 74 6f 20 74 68 65 20 70 72 6f  equal to the pro
13d40 64 75 63 74 20 6f 66 20 74 68 65 20 73 65 63 6f  duct of the seco
13d50 6e 64 20 61 6e 64 20 74 68 69 72 64 20 61 72 67  nd and third arg
13d60 75 6d 65 6e 74 73 2e 20 20 54 68 65 20 62 75 66  uments.  The buf
13d70 66 65 72 0a 2a 2a 20 6d 75 73 74 20 62 65 20 61  fer.** must be a
13d80 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62  ligned to an 8-b
13d90 79 74 65 20 62 6f 75 6e 64 61 72 79 2e 20 20 5e  yte boundary.  ^
13da0 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  If the second ar
13db0 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 53 51 4c  gument to.** SQL
13dc0 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
13dd0 4b 41 53 49 44 45 20 69 73 20 6e 6f 74 20 61 20  KASIDE is not a 
13de0 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2c 20 69  multiple of 8, i
13df0 74 20 69 73 20 69 6e 74 65 72 6e 61 6c 6c 79 0a  t is internally.
13e00 2a 2a 20 72 6f 75 6e 64 65 64 20 64 6f 77 6e 20  ** rounded down 
13e10 74 6f 20 74 68 65 20 6e 65 78 74 20 73 6d 61 6c  to the next smal
13e20 6c 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20  ler multiple of 
13e30 38 2e 20 20 5e 28 54 68 65 20 6c 6f 6f 6b 61 73  8.  ^(The lookas
13e40 69 64 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 63 6f  ide memory.** co
13e50 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f 72 20  nfiguration for 
13e60 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  a database conne
13e70 63 74 69 6f 6e 20 63 61 6e 20 6f 6e 6c 79 20 62  ction can only b
13e80 65 20 63 68 61 6e 67 65 64 20 77 68 65 6e 20 74  e changed when t
13e90 68 61 74 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  hat.** connectio
13ea0 6e 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74  n is not current
13eb0 6c 79 20 75 73 69 6e 67 20 6c 6f 6f 6b 61 73 69  ly using lookasi
13ec0 64 65 20 6d 65 6d 6f 72 79 2c 20 6f 72 20 69 6e  de memory, or in
13ed0 20 6f 74 68 65 72 20 77 6f 72 64 73 0a 2a 2a 20   other words.** 
13ee0 77 68 65 6e 20 74 68 65 20 22 63 75 72 72 65 6e  when the "curren
13ef0 74 20 76 61 6c 75 65 22 20 72 65 74 75 72 6e 65  t value" returne
13f00 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  d by.** [sqlite3
13f10 5f 64 62 5f 73 74 61 74 75 73 5d 28 44 2c 5b 53  _db_status](D,[S
13f20 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f  QLITE_CONFIG_LOO
13f30 4b 41 53 49 44 45 5d 2c 2e 2e 2e 29 20 69 73 20  KASIDE],...) is 
13f40 7a 65 72 6f 2e 0a 2a 2a 20 41 6e 79 20 61 74 74  zero..** Any att
13f50 65 6d 70 74 20 74 6f 20 63 68 61 6e 67 65 20 74  empt to change t
13f60 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  he lookaside mem
13f70 6f 72 79 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ory configuratio
13f80 6e 20 77 68 65 6e 20 6c 6f 6f 6b 61 73 69 64 65  n when lookaside
13f90 0a 2a 2a 20 6d 65 6d 6f 72 79 20 69 73 20 69 6e  .** memory is in
13fa0 20 75 73 65 20 6c 65 61 76 65 73 20 74 68 65 20   use leaves the 
13fb0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 6e  configuration un
13fc0 63 68 61 6e 67 65 64 20 61 6e 64 20 72 65 74 75  changed and retu
13fd0 72 6e 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  rns .** [SQLITE_
13fe0 42 55 53 59 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a  BUSY].)^</dd>.**
13ff0 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44  .** <dt>SQLITE_D
14000 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46  BCONFIG_ENABLE_F
14010 4b 45 59 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  KEY</dt>.** <dd>
14020 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73   ^This option is
14030 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20   used to enable 
14040 6f 72 20 64 69 73 61 62 6c 65 20 74 68 65 20 65  or disable the e
14050 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 66 0a 2a 2a  nforcement of.**
14060 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 63 6f   [foreign key co
14070 6e 73 74 72 61 69 6e 74 73 5d 2e 20 20 54 68 65  nstraints].  The
14080 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f  re should be two
14090 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75   additional argu
140a0 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69  ments..** The fi
140b0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20  rst argument is 
140c0 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68  an integer which
140d0 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65   is 0 to disable
140e0 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 2c   FK enforcement,
140f0 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f 20  .** positive to 
14100 65 6e 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63  enable FK enforc
14110 65 6d 65 6e 74 20 6f 72 20 6e 65 67 61 74 69 76  ement or negativ
14120 65 20 74 6f 20 6c 65 61 76 65 20 46 4b 20 65 6e  e to leave FK en
14130 66 6f 72 63 65 6d 65 6e 74 0a 2a 2a 20 75 6e 63  forcement.** unc
14140 68 61 6e 67 65 64 2e 20 20 54 68 65 20 73 65 63  hanged.  The sec
14150 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
14160 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
14170 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68   integer into wh
14180 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65  ich.** is writte
14190 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69  n 0 or 1 to indi
141a0 63 61 74 65 20 77 68 65 74 68 65 72 20 46 4b 20  cate whether FK 
141b0 65 6e 66 6f 72 63 65 6d 65 6e 74 20 69 73 20 6f  enforcement is o
141c0 66 66 20 6f 72 20 6f 6e 0a 2a 2a 20 66 6f 6c 6c  ff or on.** foll
141d0 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e  owing this call.
141e0 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72    The second par
141f0 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61 20  ameter may be a 
14200 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e  NULL pointer, in
14210 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20 74  .** which case t
14220 68 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e  he FK enforcemen
14230 74 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74  t setting is not
14240 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20   reported back. 
14250 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
14260 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
14270 45 4e 41 42 4c 45 5f 54 52 49 47 47 45 52 3c 2f  ENABLE_TRIGGER</
14280 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69  dt>.** <dd> ^Thi
14290 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64  s option is used
142a0 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69   to enable or di
142b0 73 61 62 6c 65 20 5b 43 52 45 41 54 45 20 54 52  sable [CREATE TR
142c0 49 47 47 45 52 20 7c 20 74 72 69 67 67 65 72 73  IGGER | triggers
142d0 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f 75  ]..** There shou
142e0 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69 74 69  ld be two additi
142f0 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a  onal arguments..
14300 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
14310 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65  ument is an inte
14320 67 65 72 20 77 68 69 63 68 20 69 73 20 30 20 74  ger which is 0 t
14330 6f 20 64 69 73 61 62 6c 65 20 74 72 69 67 67 65  o disable trigge
14340 72 73 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20  rs,.** positive 
14350 74 6f 20 65 6e 61 62 6c 65 20 74 72 69 67 67 65  to enable trigge
14360 72 73 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74  rs or negative t
14370 6f 20 6c 65 61 76 65 20 74 68 65 20 73 65 74 74  o leave the sett
14380 69 6e 67 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a  ing unchanged..*
14390 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72  * The second par
143a0 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e  ameter is a poin
143b0 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  ter to an intege
143c0 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20  r into which.** 
143d0 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20  is written 0 or 
143e0 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68  1 to indicate wh
143f0 65 74 68 65 72 20 74 72 69 67 67 65 72 73 20 61  ether triggers a
14400 72 65 20 64 69 73 61 62 6c 65 64 20 6f 72 20 65  re disabled or e
14410 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77  nabled.** follow
14420 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20  ing this call.  
14430 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
14440 65 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55  eter may be a NU
14450 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a  LL pointer, in.*
14460 2a 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65  * which case the
14470 20 74 72 69 67 67 65 72 20 73 65 74 74 69 6e 67   trigger setting
14480 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 64   is not reported
14490 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a   back. </dd>.**.
144a0 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66  ** </dl>.*/.#def
144b0 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  ine SQLITE_DBCON
144c0 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20  FIG_LOOKASIDE   
144d0 20 20 20 20 31 30 30 31 20 20 2f 2a 20 76 6f 69      1001  /* voi
144e0 64 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64  d* int int */.#d
144f0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43  efine SQLITE_DBC
14500 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45  ONFIG_ENABLE_FKE
14510 59 20 20 20 20 20 31 30 30 32 20 20 2f 2a 20 69  Y     1002  /* i
14520 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69  nt int* */.#defi
14530 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  ne SQLITE_DBCONF
14540 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 45  IG_ENABLE_TRIGGE
14550 52 20 20 31 30 30 33 20 20 2f 2a 20 69 6e 74 20  R  1003  /* int 
14560 69 6e 74 2a 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a 20  int* */.../*.** 
14570 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65  CAPI3REF: Enable
14580 20 4f 72 20 44 69 73 61 62 6c 65 20 45 78 74 65   Or Disable Exte
14590 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65  nded Result Code
145a0 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s.**.** ^The sql
145b0 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65  ite3_extended_re
145c0 73 75 6c 74 5f 63 6f 64 65 73 28 29 20 72 6f 75  sult_codes() rou
145d0 74 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72 20  tine enables or 
145e0 64 69 73 61 62 6c 65 73 20 74 68 65 0a 2a 2a 20  disables the.** 
145f0 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  [extended result
14600 20 63 6f 64 65 73 5d 20 66 65 61 74 75 72 65 20   codes] feature 
14610 6f 66 20 53 51 4c 69 74 65 2e 20 5e 54 68 65 20  of SQLite. ^The 
14620 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 0a  extended result.
14630 2a 2a 20 63 6f 64 65 73 20 61 72 65 20 64 69 73  ** codes are dis
14640 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74  abled by default
14650 20 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 20   for historical 
14660 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a  compatibility..*
14670 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78  /.int sqlite3_ex
14680 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f  tended_result_co
14690 64 65 73 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e  des(sqlite3*, in
146a0 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a  t onoff);../*.**
146b0 20 43 41 50 49 33 52 45 46 3a 20 4c 61 73 74 20   CAPI3REF: Last 
146c0 49 6e 73 65 72 74 20 52 6f 77 69 64 0a 2a 2a 0a  Insert Rowid.**.
146d0 2a 2a 20 5e 45 61 63 68 20 65 6e 74 72 79 20 69  ** ^Each entry i
146e0 6e 20 61 6e 20 53 51 4c 69 74 65 20 74 61 62 6c  n an SQLite tabl
146f0 65 20 68 61 73 20 61 20 75 6e 69 71 75 65 20 36  e has a unique 6
14700 34 2d 62 69 74 20 73 69 67 6e 65 64 0a 2a 2a 20  4-bit signed.** 
14710 69 6e 74 65 67 65 72 20 6b 65 79 20 63 61 6c 6c  integer key call
14720 65 64 20 74 68 65 20 5b 52 4f 57 49 44 20 7c 20  ed the [ROWID | 
14730 22 72 6f 77 69 64 22 5d 2e 20 5e 54 68 65 20 72  "rowid"]. ^The r
14740 6f 77 69 64 20 69 73 20 61 6c 77 61 79 73 20 61  owid is always a
14750 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 61 73 20 61  vailable.** as a
14760 6e 20 75 6e 64 65 63 6c 61 72 65 64 20 63 6f 6c  n undeclared col
14770 75 6d 6e 20 6e 61 6d 65 64 20 52 4f 57 49 44 2c  umn named ROWID,
14780 20 4f 49 44 2c 20 6f 72 20 5f 52 4f 57 49 44 5f   OID, or _ROWID_
14790 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 6f 73   as long as thos
147a0 65 0a 2a 2a 20 6e 61 6d 65 73 20 61 72 65 20 6e  e.** names are n
147b0 6f 74 20 61 6c 73 6f 20 75 73 65 64 20 62 79 20  ot also used by 
147c0 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61  explicitly decla
147d0 72 65 64 20 63 6f 6c 75 6d 6e 73 2e 20 5e 49 66  red columns. ^If
147e0 0a 2a 2a 20 74 68 65 20 74 61 62 6c 65 20 68 61  .** the table ha
147f0 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 79  s a column of ty
14800 70 65 20 5b 49 4e 54 45 47 45 52 20 50 52 49 4d  pe [INTEGER PRIM
14810 41 52 59 20 4b 45 59 5d 20 74 68 65 6e 20 74 68  ARY KEY] then th
14820 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20  at column.** is 
14830 61 6e 6f 74 68 65 72 20 61 6c 69 61 73 20 66 6f  another alias fo
14840 72 20 74 68 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a  r the rowid..**.
14850 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65  ** ^This routine
14860 20 72 65 74 75 72 6e 73 20 74 68 65 20 5b 72 6f   returns the [ro
14870 77 69 64 5d 20 6f 66 20 74 68 65 20 6d 6f 73 74  wid] of the most
14880 20 72 65 63 65 6e 74 0a 2a 2a 20 73 75 63 63 65   recent.** succe
14890 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 69  ssful [INSERT] i
148a0 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65  nto the database
148b0 20 66 72 6f 6d 20 74 68 65 20 5b 64 61 74 61 62   from the [datab
148c0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a  ase connection].
148d0 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  ** in the first 
148e0 61 72 67 75 6d 65 6e 74 2e 20 20 5e 41 73 20 6f  argument.  ^As o
148f0 66 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  f SQLite version
14900 20 33 2e 37 2e 37 2c 20 74 68 69 73 20 72 6f 75   3.7.7, this rou
14910 74 69 6e 65 73 0a 2a 2a 20 72 65 63 6f 72 64 73  tines.** records
14920 20 74 68 65 20 6c 61 73 74 20 69 6e 73 65 72 74   the last insert
14930 20 72 6f 77 69 64 20 6f 66 20 62 6f 74 68 20 6f   rowid of both o
14940 72 64 69 6e 61 72 79 20 74 61 62 6c 65 73 20 61  rdinary tables a
14950 6e 64 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c  nd [virtual tabl
14960 65 73 5d 2e 0a 2a 2a 20 5e 49 66 20 6e 6f 20 73  es]..** ^If no s
14970 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52  uccessful [INSER
14980 54 5d 73 0a 2a 2a 20 68 61 76 65 20 65 76 65 72  T]s.** have ever
14990 20 6f 63 63 75 72 72 65 64 20 6f 6e 20 74 68 61   occurred on tha
149a0 74 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  t database conne
149b0 63 74 69 6f 6e 2c 20 7a 65 72 6f 20 69 73 20 72  ction, zero is r
149c0 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  eturned..**.** ^
149d0 28 49 66 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20  (If an [INSERT] 
149e0 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 61 20  occurs within a 
149f0 74 72 69 67 67 65 72 20 6f 72 20 77 69 74 68 69  trigger or withi
14a00 6e 20 61 20 5b 76 69 72 74 75 61 6c 20 74 61 62  n a [virtual tab
14a10 6c 65 5d 0a 2a 2a 20 6d 65 74 68 6f 64 2c 20 74  le].** method, t
14a20 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65  hen this routine
14a30 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 74 68 65   will return the
14a40 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20   [rowid] of the 
14a50 69 6e 73 65 72 74 65 64 0a 2a 2a 20 72 6f 77 20  inserted.** row 
14a60 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 74  as long as the t
14a70 72 69 67 67 65 72 20 6f 72 20 76 69 72 74 75 61  rigger or virtua
14a80 6c 20 74 61 62 6c 65 20 6d 65 74 68 6f 64 20 69  l table method i
14a90 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 42 75  s running..** Bu
14aa0 74 20 6f 6e 63 65 20 74 68 65 20 74 72 69 67 67  t once the trigg
14ab0 65 72 20 6f 72 20 76 69 72 74 75 61 6c 20 74 61  er or virtual ta
14ac0 62 6c 65 20 6d 65 74 68 6f 64 20 65 6e 64 73 2c  ble method ends,
14ad0 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
14ae0 6e 65 64 20 0a 2a 2a 20 62 79 20 74 68 69 73 20  ned .** by this 
14af0 72 6f 75 74 69 6e 65 20 72 65 76 65 72 74 73 20  routine reverts 
14b00 74 6f 20 77 68 61 74 20 69 74 20 77 61 73 20 62  to what it was b
14b10 65 66 6f 72 65 20 74 68 65 20 74 72 69 67 67 65  efore the trigge
14b20 72 20 6f 72 20 76 69 72 74 75 61 6c 0a 2a 2a 20  r or virtual.** 
14b30 74 61 62 6c 65 20 6d 65 74 68 6f 64 20 62 65 67  table method beg
14b40 61 6e 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20  an.)^.**.** ^An 
14b50 5b 49 4e 53 45 52 54 5d 20 74 68 61 74 20 66 61  [INSERT] that fa
14b60 69 6c 73 20 64 75 65 20 74 6f 20 61 20 63 6f 6e  ils due to a con
14b70 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f  straint violatio
14b80 6e 20 69 73 20 6e 6f 74 20 61 0a 2a 2a 20 73 75  n is not a.** su
14b90 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54  ccessful [INSERT
14ba0 5d 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 63  ] and does not c
14bb0 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65 20  hange the value 
14bc0 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73  returned by this
14bd0 0a 2a 2a 20 72 6f 75 74 69 6e 65 2e 20 20 5e 54  .** routine.  ^T
14be0 68 75 73 20 49 4e 53 45 52 54 20 4f 52 20 46 41  hus INSERT OR FA
14bf0 49 4c 2c 20 49 4e 53 45 52 54 20 4f 52 20 49 47  IL, INSERT OR IG
14c00 4e 4f 52 45 2c 20 49 4e 53 45 52 54 20 4f 52 20  NORE, INSERT OR 
14c10 52 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64  ROLLBACK,.** and
14c20 20 49 4e 53 45 52 54 20 4f 52 20 41 42 4f 52 54   INSERT OR ABORT
14c30 20 6d 61 6b 65 20 6e 6f 20 63 68 61 6e 67 65 73   make no changes
14c40 20 74 6f 20 74 68 65 20 72 65 74 75 72 6e 20 76   to the return v
14c50 61 6c 75 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20  alue of this.** 
14c60 72 6f 75 74 69 6e 65 20 77 68 65 6e 20 74 68 65  routine when the
14c70 69 72 20 69 6e 73 65 72 74 69 6f 6e 20 66 61 69  ir insertion fai
14c80 6c 73 2e 20 20 5e 28 57 68 65 6e 20 49 4e 53 45  ls.  ^(When INSE
14c90 52 54 20 4f 52 20 52 45 50 4c 41 43 45 0a 2a 2a  RT OR REPLACE.**
14ca0 20 65 6e 63 6f 75 6e 74 65 72 73 20 61 20 63 6f   encounters a co
14cb0 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69  nstraint violati
14cc0 6f 6e 2c 20 69 74 20 64 6f 65 73 20 6e 6f 74 20  on, it does not 
14cd0 66 61 69 6c 2e 20 20 54 68 65 0a 2a 2a 20 49 4e  fail.  The.** IN
14ce0 53 45 52 54 20 63 6f 6e 74 69 6e 75 65 73 20 74  SERT continues t
14cf0 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 66 74  o completion aft
14d00 65 72 20 64 65 6c 65 74 69 6e 67 20 72 6f 77 73  er deleting rows
14d10 20 74 68 61 74 20 63 61 75 73 65 64 0a 2a 2a 20   that caused.** 
14d20 74 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 20 70  the constraint p
14d30 72 6f 62 6c 65 6d 20 73 6f 20 49 4e 53 45 52 54  roblem so INSERT
14d40 20 4f 52 20 52 45 50 4c 41 43 45 20 77 69 6c 6c   OR REPLACE will
14d50 20 61 6c 77 61 79 73 20 63 68 61 6e 67 65 0a 2a   always change.*
14d60 2a 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  * the return val
14d70 75 65 20 6f 66 20 74 68 69 73 20 69 6e 74 65 72  ue of this inter
14d80 66 61 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 46  face.)^.**.** ^F
14d90 6f 72 20 74 68 65 20 70 75 72 70 6f 73 65 73 20  or the purposes 
14da0 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c  of this routine,
14db0 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 69 73 20   an [INSERT] is 
14dc0 63 6f 6e 73 69 64 65 72 65 64 20 74 6f 0a 2a 2a  considered to.**
14dd0 20 62 65 20 73 75 63 63 65 73 73 66 75 6c 20 65   be successful e
14de0 76 65 6e 20 69 66 20 69 74 20 69 73 20 73 75 62  ven if it is sub
14df0 73 65 71 75 65 6e 74 6c 79 20 72 6f 6c 6c 65 64  sequently rolled
14e00 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 69   back..**.** Thi
14e10 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 63  s function is ac
14e20 63 65 73 73 69 62 6c 65 20 74 6f 20 53 51 4c 20  cessible to SQL 
14e30 73 74 61 74 65 6d 65 6e 74 73 20 76 69 61 20 74  statements via t
14e40 68 65 0a 2a 2a 20 5b 6c 61 73 74 5f 69 6e 73 65  he.** [last_inse
14e50 72 74 5f 72 6f 77 69 64 28 29 20 53 51 4c 20 66  rt_rowid() SQL f
14e60 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20  unction]..**.** 
14e70 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68  If a separate th
14e80 72 65 61 64 20 70 65 72 66 6f 72 6d 73 20 61 20  read performs a 
14e90 6e 65 77 20 5b 49 4e 53 45 52 54 5d 20 6f 6e 20  new [INSERT] on 
14ea0 74 68 65 20 73 61 6d 65 0a 2a 2a 20 64 61 74 61  the same.** data
14eb0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
14ec0 77 68 69 6c 65 20 74 68 65 20 5b 73 71 6c 69 74  while the [sqlit
14ed0 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72  e3_last_insert_r
14ee0 6f 77 69 64 28 29 5d 0a 2a 2a 20 66 75 6e 63 74  owid()].** funct
14ef0 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 20 61  ion is running a
14f00 6e 64 20 74 68 75 73 20 63 68 61 6e 67 65 73 20  nd thus changes 
14f10 74 68 65 20 6c 61 73 74 20 69 6e 73 65 72 74 20  the last insert 
14f20 5b 72 6f 77 69 64 5d 2c 0a 2a 2a 20 74 68 65 6e  [rowid],.** then
14f30 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
14f40 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ned by [sqlite3_
14f50 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
14f60 64 28 29 5d 20 69 73 0a 2a 2a 20 75 6e 70 72 65  d()] is.** unpre
14f70 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6d 69 67  dictable and mig
14f80 68 74 20 6e 6f 74 20 65 71 75 61 6c 20 65 69 74  ht not equal eit
14f90 68 65 72 20 74 68 65 20 6f 6c 64 20 6f 72 20 74  her the old or t
14fa0 68 65 20 6e 65 77 0a 2a 2a 20 6c 61 73 74 20 69  he new.** last i
14fb0 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2e 0a 2a  nsert [rowid]..*
14fc0 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  /.sqlite3_int64 
14fd0 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73  sqlite3_last_ins
14fe0 65 72 74 5f 72 6f 77 69 64 28 73 71 6c 69 74 65  ert_rowid(sqlite
14ff0 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  3*);../*.** CAPI
15000 33 52 45 46 3a 20 43 6f 75 6e 74 20 54 68 65 20  3REF: Count The 
15010 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d  Number Of Rows M
15020 6f 64 69 66 69 65 64 0a 2a 2a 0a 2a 2a 20 5e 54  odified.**.** ^T
15030 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  his function ret
15040 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
15050 6f 66 20 64 61 74 61 62 61 73 65 20 72 6f 77 73  of database rows
15060 20 74 68 61 74 20 77 65 72 65 20 63 68 61 6e 67   that were chang
15070 65 64 0a 2a 2a 20 6f 72 20 69 6e 73 65 72 74 65  ed.** or inserte
15080 64 20 6f 72 20 64 65 6c 65 74 65 64 20 62 79 20  d or deleted by 
15090 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c  the most recentl
150a0 79 20 63 6f 6d 70 6c 65 74 65 64 20 53 51 4c 20  y completed SQL 
150b0 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 6f 6e 20  statement.** on 
150c0 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
150d0 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66  nnection] specif
150e0 69 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74  ied by the first
150f0 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e   parameter..** ^
15100 28 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20 74 68  (Only changes th
15110 61 74 20 61 72 65 20 64 69 72 65 63 74 6c 79 20  at are directly 
15120 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65  specified by the
15130 20 5b 49 4e 53 45 52 54 5d 2c 20 5b 55 50 44 41   [INSERT], [UPDA
15140 54 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 44 45 4c 45  TE],.** or [DELE
15150 54 45 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 72  TE] statement ar
15160 65 20 63 6f 75 6e 74 65 64 2e 20 20 41 75 78 69  e counted.  Auxi
15170 6c 69 61 72 79 20 63 68 61 6e 67 65 73 20 63 61  liary changes ca
15180 75 73 65 64 20 62 79 0a 2a 2a 20 74 72 69 67 67  used by.** trigg
15190 65 72 73 20 6f 72 20 5b 66 6f 72 65 69 67 6e 20  ers or [foreign 
151a0 6b 65 79 20 61 63 74 69 6f 6e 73 5d 20 61 72 65  key actions] are
151b0 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 29 5e 20   not counted.)^ 
151c0 55 73 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  Use the.** [sqli
151d0 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
151e0 73 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 74 6f  s()] function to
151f0 20 66 69 6e 64 20 74 68 65 20 74 6f 74 61 6c 20   find the total 
15200 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 6e 67 65  number of change
15210 73 0a 2a 2a 20 69 6e 63 6c 75 64 69 6e 67 20 63  s.** including c
15220 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79  hanges caused by
15230 20 74 72 69 67 67 65 72 73 20 61 6e 64 20 66 6f   triggers and fo
15240 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e  reign key action
15250 73 2e 0a 2a 2a 0a 2a 2a 20 5e 43 68 61 6e 67 65  s..**.** ^Change
15260 73 20 74 6f 20 61 20 76 69 65 77 20 74 68 61 74  s to a view that
15270 20 61 72 65 20 73 69 6d 75 6c 61 74 65 64 20 62   are simulated b
15280 79 20 61 6e 20 5b 49 4e 53 54 45 41 44 20 4f 46  y an [INSTEAD OF
15290 20 74 72 69 67 67 65 72 5d 0a 2a 2a 20 61 72 65   trigger].** are
152a0 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 20 20 4f   not counted.  O
152b0 6e 6c 79 20 72 65 61 6c 20 74 61 62 6c 65 20 63  nly real table c
152c0 68 61 6e 67 65 73 20 61 72 65 20 63 6f 75 6e 74  hanges are count
152d0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 20 22 72  ed..**.** ^(A "r
152e0 6f 77 20 63 68 61 6e 67 65 22 20 69 73 20 61 20  ow change" is a 
152f0 63 68 61 6e 67 65 20 74 6f 20 61 20 73 69 6e 67  change to a sing
15300 6c 65 20 72 6f 77 20 6f 66 20 61 20 73 69 6e 67  le row of a sing
15310 6c 65 20 74 61 62 6c 65 0a 2a 2a 20 63 61 75 73  le table.** caus
15320 65 64 20 62 79 20 61 6e 20 49 4e 53 45 52 54 2c  ed by an INSERT,
15330 20 44 45 4c 45 54 45 2c 20 6f 72 20 55 50 44 41   DELETE, or UPDA
15340 54 45 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 52  TE statement.  R
15350 6f 77 73 20 74 68 61 74 0a 2a 2a 20 61 72 65 20  ows that.** are 
15360 63 68 61 6e 67 65 64 20 61 73 20 73 69 64 65 20  changed as side 
15370 65 66 66 65 63 74 73 20 6f 66 20 5b 52 45 50 4c  effects of [REPL
15380 41 43 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74 20  ACE] constraint 
15390 72 65 73 6f 6c 75 74 69 6f 6e 2c 0a 2a 2a 20 72  resolution,.** r
153a0 6f 6c 6c 62 61 63 6b 2c 20 41 42 4f 52 54 20 70  ollback, ABORT p
153b0 72 6f 63 65 73 73 69 6e 67 2c 20 5b 44 52 4f 50  rocessing, [DROP
153c0 20 54 41 42 4c 45 5d 2c 20 6f 72 20 62 79 20 61   TABLE], or by a
153d0 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 63 68  ny other.** mech
153e0 61 6e 69 73 6d 73 20 64 6f 20 6e 6f 74 20 63 6f  anisms do not co
153f0 75 6e 74 20 61 73 20 64 69 72 65 63 74 20 72 6f  unt as direct ro
15400 77 20 63 68 61 6e 67 65 73 2e 29 5e 0a 2a 2a 0a  w changes.)^.**.
15410 2a 2a 20 41 20 22 74 72 69 67 67 65 72 20 63 6f  ** A "trigger co
15420 6e 74 65 78 74 22 20 69 73 20 61 20 73 63 6f 70  ntext" is a scop
15430 65 20 6f 66 20 65 78 65 63 75 74 69 6f 6e 20 74  e of execution t
15440 68 61 74 20 62 65 67 69 6e 73 20 61 6e 64 0a 2a  hat begins and.*
15450 2a 20 65 6e 64 73 20 77 69 74 68 20 74 68 65 20  * ends with the 
15460 73 63 72 69 70 74 20 6f 66 20 61 20 5b 43 52 45  script of a [CRE
15470 41 54 45 20 54 52 49 47 47 45 52 20 7c 20 74 72  ATE TRIGGER | tr
15480 69 67 67 65 72 5d 2e 20 0a 2a 2a 20 4d 6f 73 74  igger]. .** Most
15490 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
154a0 61 72 65 0a 2a 2a 20 65 76 61 6c 75 61 74 65 64  are.** evaluated
154b0 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e 79 20   outside of any 
154c0 74 72 69 67 67 65 72 2e 20 20 54 68 69 73 20 69  trigger.  This i
154d0 73 20 74 68 65 20 22 74 6f 70 20 6c 65 76 65 6c  s the "top level
154e0 22 0a 2a 2a 20 74 72 69 67 67 65 72 20 63 6f 6e  ".** trigger con
154f0 74 65 78 74 2e 20 20 49 66 20 61 20 74 72 69 67  text.  If a trig
15500 67 65 72 20 66 69 72 65 73 20 66 72 6f 6d 20 74  ger fires from t
15510 68 65 20 74 6f 70 20 6c 65 76 65 6c 2c 20 61 0a  he top level, a.
15520 2a 2a 20 6e 65 77 20 74 72 69 67 67 65 72 20 63  ** new trigger c
15530 6f 6e 74 65 78 74 20 69 73 20 65 6e 74 65 72 65  ontext is entere
15540 64 20 66 6f 72 20 74 68 65 20 64 75 72 61 74 69  d for the durati
15550 6f 6e 20 6f 66 20 74 68 61 74 20 6f 6e 65 0a 2a  on of that one.*
15560 2a 20 74 72 69 67 67 65 72 2e 20 20 53 75 62 74  * trigger.  Subt
15570 72 69 67 67 65 72 73 20 63 72 65 61 74 65 20 73  riggers create s
15580 75 62 63 6f 6e 74 65 78 74 73 20 66 6f 72 20 74  ubcontexts for t
15590 68 65 69 72 20 64 75 72 61 74 69 6f 6e 2e 0a 2a  heir duration..*
155a0 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 5b 73  *.** ^Calling [s
155b0 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 6f  qlite3_exec()] o
155c0 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  r [sqlite3_step(
155d0 29 5d 20 72 65 63 75 72 73 69 76 65 6c 79 20 64  )] recursively d
155e0 6f 65 73 0a 2a 2a 20 6e 6f 74 20 63 72 65 61 74  oes.** not creat
155f0 65 20 61 20 6e 65 77 20 74 72 69 67 67 65 72 20  e a new trigger 
15600 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 5e  context..**.** ^
15610 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65  This function re
15620 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
15630 20 6f 66 20 64 69 72 65 63 74 20 72 6f 77 20 63   of direct row c
15640 68 61 6e 67 65 73 20 69 6e 20 74 68 65 0a 2a 2a  hanges in the.**
15650 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 49 4e 53   most recent INS
15660 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20  ERT, UPDATE, or 
15670 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74  DELETE statement
15680 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65   within the same
15690 0a 2a 2a 20 74 72 69 67 67 65 72 20 63 6f 6e 74  .** trigger cont
156a0 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 75 73  ext..**.** ^Thus
156b0 2c 20 77 68 65 6e 20 63 61 6c 6c 65 64 20 66 72  , when called fr
156c0 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c  om the top level
156d0 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20  , this function 
156e0 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 6e  returns the.** n
156f0 75 6d 62 65 72 20 6f 66 20 63 68 61 6e 67 65 73  umber of changes
15700 20 69 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63   in the most rec
15710 65 6e 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41  ent INSERT, UPDA
15720 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a  TE, or DELETE.**
15730 20 74 68 61 74 20 61 6c 73 6f 20 6f 63 63 75 72   that also occur
15740 72 65 64 20 61 74 20 74 68 65 20 74 6f 70 20 6c  red at the top l
15750 65 76 65 6c 2e 20 20 5e 28 57 69 74 68 69 6e 20  evel.  ^(Within 
15760 74 68 65 20 62 6f 64 79 20 6f 66 20 61 20 74 72  the body of a tr
15770 69 67 67 65 72 2c 0a 2a 2a 20 74 68 65 20 73 71  igger,.** the sq
15780 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20  lite3_changes() 
15790 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65  interface can be
157a0 20 63 61 6c 6c 65 64 20 74 6f 20 66 69 6e 64 20   called to find 
157b0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a  the number of.**
157c0 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20   changes in the 
157d0 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f  most recently co
157e0 6d 70 6c 65 74 65 64 20 49 4e 53 45 52 54 2c 20  mpleted INSERT, 
157f0 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54  UPDATE, or DELET
15800 45 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 77  E.** statement w
15810 69 74 68 69 6e 20 74 68 65 20 62 6f 64 79 20 6f  ithin the body o
15820 66 20 74 68 65 20 73 61 6d 65 20 74 72 69 67 67  f the same trigg
15830 65 72 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20  er..** However, 
15840 74 68 65 20 6e 75 6d 62 65 72 20 72 65 74 75 72  the number retur
15850 6e 65 64 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63  ned does not inc
15860 6c 75 64 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20  lude changes.** 
15870 63 61 75 73 65 64 20 62 79 20 73 75 62 74 72 69  caused by subtri
15880 67 67 65 72 73 20 73 69 6e 63 65 20 74 68 6f 73  ggers since thos
15890 65 20 68 61 76 65 20 74 68 65 69 72 20 6f 77 6e  e have their own
158a0 20 63 6f 6e 74 65 78 74 2e 29 5e 0a 2a 2a 0a 2a   context.)^.**.*
158b0 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b  * See also the [
158c0 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68  sqlite3_total_ch
158d0 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61  anges()] interfa
158e0 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e  ce, the.** [coun
158f0 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61  t_changes pragma
15900 5d 2c 20 61 6e 64 20 74 68 65 20 5b 63 68 61 6e  ], and the [chan
15910 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69  ges() SQL functi
15920 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20  on]..**.** If a 
15930 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20  separate thread 
15940 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e  makes changes on
15950 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
15960 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
15970 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f   while [sqlite3_
15980 63 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75  changes()] is ru
15990 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76  nning then the v
159a0 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a  alue returned.**
159b0 20 69 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c   is unpredictabl
159c0 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e  e and not meanin
159d0 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  gful..*/.int sql
159e0 69 74 65 33 5f 63 68 61 6e 67 65 73 28 73 71 6c  ite3_changes(sql
159f0 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
15a00 41 50 49 33 52 45 46 3a 20 54 6f 74 61 6c 20 4e  API3REF: Total N
15a10 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f  umber Of Rows Mo
15a20 64 69 66 69 65 64 0a 2a 2a 0a 2a 2a 20 5e 54 68  dified.**.** ^Th
15a30 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  is function retu
15a40 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
15a50 66 20 72 6f 77 20 63 68 61 6e 67 65 73 20 63 61  f row changes ca
15a60 75 73 65 64 20 62 79 20 5b 49 4e 53 45 52 54 5d  used by [INSERT]
15a70 2c 0a 2a 2a 20 5b 55 50 44 41 54 45 5d 20 6f 72  ,.** [UPDATE] or
15a80 20 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 65 6d   [DELETE] statem
15a90 65 6e 74 73 20 73 69 6e 63 65 20 74 68 65 20 5b  ents since the [
15aa0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
15ab0 69 6f 6e 5d 20 77 61 73 20 6f 70 65 6e 65 64 2e  ion] was opened.
15ac0 0a 2a 2a 20 5e 28 54 68 65 20 63 6f 75 6e 74 20  .** ^(The count 
15ad0 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
15ae0 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
15af0 73 28 29 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c  s() includes all
15b00 20 63 68 61 6e 67 65 73 0a 2a 2a 20 66 72 6f 6d   changes.** from
15b10 20 61 6c 6c 20 5b 43 52 45 41 54 45 20 54 52 49   all [CREATE TRI
15b20 47 47 45 52 20 7c 20 74 72 69 67 67 65 72 5d 20  GGER | trigger] 
15b30 63 6f 6e 74 65 78 74 73 20 61 6e 64 20 63 68 61  contexts and cha
15b40 6e 67 65 73 20 6d 61 64 65 20 62 79 0a 2a 2a 20  nges made by.** 
15b50 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74  [foreign key act
15b60 69 6f 6e 73 5d 2e 20 48 6f 77 65 76 65 72 2c 0a  ions]. However,.
15b70 2a 2a 20 74 68 65 20 63 6f 75 6e 74 20 64 6f 65  ** the count doe
15b80 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 63 68  s not include ch
15b90 61 6e 67 65 73 20 75 73 65 64 20 74 6f 20 69 6d  anges used to im
15ba0 70 6c 65 6d 65 6e 74 20 5b 52 45 50 4c 41 43 45  plement [REPLACE
15bb0 5d 20 63 6f 6e 73 74 72 61 69 6e 74 73 2c 0a 2a  ] constraints,.*
15bc0 2a 20 64 6f 20 72 6f 6c 6c 62 61 63 6b 73 20 6f  * do rollbacks o
15bd0 72 20 41 42 4f 52 54 20 70 72 6f 63 65 73 73 69  r ABORT processi
15be0 6e 67 2c 20 6f 72 20 5b 44 52 4f 50 20 54 41 42  ng, or [DROP TAB
15bf0 4c 45 5d 20 70 72 6f 63 65 73 73 69 6e 67 2e 20  LE] processing. 
15c00 20 54 68 65 0a 2a 2a 20 63 6f 75 6e 74 20 64 6f   The.** count do
15c10 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 72  es not include r
15c20 6f 77 73 20 6f 66 20 76 69 65 77 73 20 74 68 61  ows of views tha
15c30 74 20 66 69 72 65 20 61 6e 20 5b 49 4e 53 54 45  t fire an [INSTE
15c40 41 44 20 4f 46 20 74 72 69 67 67 65 72 5d 2c 0a  AD OF trigger],.
15c50 2a 2a 20 74 68 6f 75 67 68 20 69 66 20 74 68 65  ** though if the
15c60 20 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67   INSTEAD OF trig
15c70 67 65 72 20 6d 61 6b 65 73 20 63 68 61 6e 67 65  ger makes change
15c80 73 20 6f 66 20 69 74 73 20 6f 77 6e 2c 20 74 68  s of its own, th
15c90 6f 73 65 20 63 68 61 6e 67 65 73 20 0a 2a 2a 20  ose changes .** 
15ca0 61 72 65 20 63 6f 75 6e 74 65 64 2e 29 5e 0a 2a  are counted.)^.*
15cb0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74  * ^The sqlite3_t
15cc0 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 66  otal_changes() f
15cd0 75 6e 63 74 69 6f 6e 20 63 6f 75 6e 74 73 20 74  unction counts t
15ce0 68 65 20 63 68 61 6e 67 65 73 20 61 73 20 73 6f  he changes as so
15cf0 6f 6e 20 61 73 0a 2a 2a 20 74 68 65 20 73 74 61  on as.** the sta
15d00 74 65 6d 65 6e 74 20 74 68 61 74 20 6d 61 6b 65  tement that make
15d10 73 20 74 68 65 6d 20 69 73 20 63 6f 6d 70 6c 65  s them is comple
15d20 74 65 64 20 28 77 68 65 6e 20 74 68 65 20 73 74  ted (when the st
15d30 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 0a 2a  atement handle.*
15d40 2a 20 69 73 20 70 61 73 73 65 64 20 74 6f 20 5b  * is passed to [
15d50 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
15d60 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e   or [sqlite3_fin
15d70 61 6c 69 7a 65 28 29 5d 29 2e 0a 2a 2a 0a 2a 2a  alize()])..**.**
15d80 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73   See also the [s
15d90 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29  qlite3_changes()
15da0 5d 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65  ] interface, the
15db0 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67  .** [count_chang
15dc0 65 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20  es pragma], and 
15dd0 74 68 65 20 5b 74 6f 74 61 6c 5f 63 68 61 6e 67  the [total_chang
15de0 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f  es() SQL functio
15df0 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73  n]..**.** If a s
15e00 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20 6d  eparate thread m
15e10 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20  akes changes on 
15e20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73  the same databas
15e30 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e connection.** 
15e40 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 74  while [sqlite3_t
15e50 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20  otal_changes()] 
15e60 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20  is running then 
15e70 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74  the value.** ret
15e80 75 72 6e 65 64 20 69 73 20 75 6e 70 72 65 64 69  urned is unpredi
15e90 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d  ctable and not m
15ea0 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e  eaningful..*/.in
15eb0 74 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f  t sqlite3_total_
15ec0 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a  changes(sqlite3*
15ed0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
15ee0 45 46 3a 20 49 6e 74 65 72 72 75 70 74 20 41 20  EF: Interrupt A 
15ef0 4c 6f 6e 67 2d 52 75 6e 6e 69 6e 67 20 51 75 65  Long-Running Que
15f00 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66  ry.**.** ^This f
15f10 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20 61  unction causes a
15f20 6e 79 20 70 65 6e 64 69 6e 67 20 64 61 74 61 62  ny pending datab
15f30 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f  ase operation to
15f40 20 61 62 6f 72 74 20 61 6e 64 0a 2a 2a 20 72 65   abort and.** re
15f50 74 75 72 6e 20 61 74 20 69 74 73 20 65 61 72 6c  turn at its earl
15f60 69 65 73 74 20 6f 70 70 6f 72 74 75 6e 69 74 79  iest opportunity
15f70 2e 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 69  . This routine i
15f80 73 20 74 79 70 69 63 61 6c 6c 79 0a 2a 2a 20 63  s typically.** c
15f90 61 6c 6c 65 64 20 69 6e 20 72 65 73 70 6f 6e 73  alled in respons
15fa0 65 20 74 6f 20 61 20 75 73 65 72 20 61 63 74 69  e to a user acti
15fb0 6f 6e 20 73 75 63 68 20 61 73 20 70 72 65 73 73  on such as press
15fc0 69 6e 67 20 22 43 61 6e 63 65 6c 22 0a 2a 2a 20  ing "Cancel".** 
15fd0 6f 72 20 43 74 72 6c 2d 43 20 77 68 65 72 65 20  or Ctrl-C where 
15fe0 74 68 65 20 75 73 65 72 20 77 61 6e 74 73 20 61  the user wants a
15ff0 20 6c 6f 6e 67 20 71 75 65 72 79 20 6f 70 65 72   long query oper
16000 61 74 69 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a 2a  ation to halt.**
16010 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a   immediately..**
16020 0a 2a 2a 20 5e 49 74 20 69 73 20 73 61 66 65 20  .** ^It is safe 
16030 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75  to call this rou
16040 74 69 6e 65 20 66 72 6f 6d 20 61 20 74 68 72 65  tine from a thre
16050 61 64 20 64 69 66 66 65 72 65 6e 74 20 66 72 6f  ad different fro
16060 6d 20 74 68 65 0a 2a 2a 20 74 68 72 65 61 64 20  m the.** thread 
16070 74 68 61 74 20 69 73 20 63 75 72 72 65 6e 74 6c  that is currentl
16080 79 20 72 75 6e 6e 69 6e 67 20 74 68 65 20 64 61  y running the da
16090 74 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e  tabase operation
160a0 2e 20 20 42 75 74 20 69 74 0a 2a 2a 20 69 73 20  .  But it.** is 
160b0 6e 6f 74 20 73 61 66 65 20 74 6f 20 63 61 6c 6c  not safe to call
160c0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69   this routine wi
160d0 74 68 20 61 20 5b 64 61 74 61 62 61 73 65 20 63  th a [database c
160e0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 0a  onnection] that.
160f0 2a 2a 20 69 73 20 63 6c 6f 73 65 64 20 6f 72 20  ** is closed or 
16100 6d 69 67 68 74 20 63 6c 6f 73 65 20 62 65 66 6f  might close befo
16110 72 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  re sqlite3_inter
16120 72 75 70 74 28 29 20 72 65 74 75 72 6e 73 2e 0a  rupt() returns..
16130 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 53 51 4c  **.** ^If an SQL
16140 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 76 65   operation is ve
16150 72 79 20 6e 65 61 72 6c 79 20 66 69 6e 69 73 68  ry nearly finish
16160 65 64 20 61 74 20 74 68 65 20 74 69 6d 65 20 77  ed at the time w
16170 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69  hen.** sqlite3_i
16180 6e 74 65 72 72 75 70 74 28 29 20 69 73 20 63 61  nterrupt() is ca
16190 6c 6c 65 64 2c 20 74 68 65 6e 20 69 74 20 6d 69  lled, then it mi
161a0 67 68 74 20 6e 6f 74 20 68 61 76 65 20 61 6e 20  ght not have an 
161b0 6f 70 70 6f 72 74 75 6e 69 74 79 0a 2a 2a 20 74  opportunity.** t
161c0 6f 20 62 65 20 69 6e 74 65 72 72 75 70 74 65 64  o be interrupted
161d0 20 61 6e 64 20 6d 69 67 68 74 20 63 6f 6e 74 69   and might conti
161e0 6e 75 65 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f  nue to completio
161f0 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 53 51 4c  n..**.** ^An SQL
16200 20 6f 70 65 72 61 74 69 6f 6e 20 74 68 61 74 20   operation that 
16210 69 73 20 69 6e 74 65 72 72 75 70 74 65 64 20 77  is interrupted w
16220 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  ill return [SQLI
16230 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2e 0a 2a  TE_INTERRUPT]..*
16240 2a 20 5e 49 66 20 74 68 65 20 69 6e 74 65 72 72  * ^If the interr
16250 75 70 74 65 64 20 53 51 4c 20 6f 70 65 72 61 74  upted SQL operat
16260 69 6f 6e 20 69 73 20 61 6e 20 49 4e 53 45 52 54  ion is an INSERT
16270 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c  , UPDATE, or DEL
16280 45 54 45 0a 2a 2a 20 74 68 61 74 20 69 73 20 69  ETE.** that is i
16290 6e 73 69 64 65 20 61 6e 20 65 78 70 6c 69 63 69  nside an explici
162a0 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74  t transaction, t
162b0 68 65 6e 20 74 68 65 20 65 6e 74 69 72 65 20 74  hen the entire t
162c0 72 61 6e 73 61 63 74 69 6f 6e 0a 2a 2a 20 77 69  ransaction.** wi
162d0 6c 6c 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63  ll be rolled bac
162e0 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e  k automatically.
162f0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
16300 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 44 29  te3_interrupt(D)
16310 20 63 61 6c 6c 20 69 73 20 69 6e 20 65 66 66 65   call is in effe
16320 63 74 20 75 6e 74 69 6c 20 61 6c 6c 20 63 75 72  ct until all cur
16330 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 0a 2a  rently running.*
16340 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  * SQL statements
16350 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f   on [database co
16360 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 63 6f 6d 70  nnection] D comp
16370 6c 65 74 65 2e 20 20 5e 41 6e 79 20 6e 65 77 20  lete.  ^Any new 
16380 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a  SQL statements.*
16390 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74  * that are start
163a0 65 64 20 61 66 74 65 72 20 74 68 65 20 73 71 6c  ed after the sql
163b0 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
163c0 20 63 61 6c 6c 20 61 6e 64 20 62 65 66 6f 72 65   call and before
163d0 20 74 68 65 20 0a 2a 2a 20 72 75 6e 6e 69 6e 67   the .** running
163e0 20 73 74 61 74 65 6d 65 6e 74 73 20 72 65 61 63   statements reac
163f0 68 65 73 20 7a 65 72 6f 20 61 72 65 20 69 6e 74  hes zero are int
16400 65 72 72 75 70 74 65 64 20 61 73 20 69 66 20 74  errupted as if t
16410 68 65 79 20 68 61 64 20 62 65 65 6e 0a 2a 2a 20  hey had been.** 
16420 72 75 6e 6e 69 6e 67 20 70 72 69 6f 72 20 74 6f  running prior to
16430 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74   the sqlite3_int
16440 65 72 72 75 70 74 28 29 20 63 61 6c 6c 2e 20 20  errupt() call.  
16450 5e 4e 65 77 20 53 51 4c 20 73 74 61 74 65 6d 65  ^New SQL stateme
16460 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20  nts.** that are 
16470 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68  started after th
16480 65 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d  e running statem
16490 65 6e 74 20 63 6f 75 6e 74 20 72 65 61 63 68 65  ent count reache
164a0 73 20 7a 65 72 6f 20 61 72 65 0a 2a 2a 20 6e 6f  s zero are.** no
164b0 74 20 65 66 66 65 63 74 65 64 20 62 79 20 74 68  t effected by th
164c0 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  e sqlite3_interr
164d0 75 70 74 28 29 2e 0a 2a 2a 20 5e 41 20 63 61 6c  upt()..** ^A cal
164e0 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 74  l to sqlite3_int
164f0 65 72 72 75 70 74 28 44 29 20 74 68 61 74 20 6f  errupt(D) that o
16500 63 63 75 72 73 20 77 68 65 6e 20 74 68 65 72 65  ccurs when there
16510 20 61 72 65 20 6e 6f 20 72 75 6e 6e 69 6e 67 0a   are no running.
16520 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ** SQL statement
16530 73 20 69 73 20 61 20 6e 6f 2d 6f 70 20 61 6e 64  s is a no-op and
16540 20 68 61 73 20 6e 6f 20 65 66 66 65 63 74 20 6f   has no effect o
16550 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  n SQL statements
16560 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61  .** that are sta
16570 72 74 65 64 20 61 66 74 65 72 20 74 68 65 20 73  rted after the s
16580 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
16590 28 29 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e  () call returns.
165a0 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 64 61  .**.** If the da
165b0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
165c0 6e 20 63 6c 6f 73 65 73 20 77 68 69 6c 65 20 5b  n closes while [
165d0 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
165e0 74 28 29 5d 0a 2a 2a 20 69 73 20 72 75 6e 6e 69  t()].** is runni
165f0 6e 67 20 74 68 65 6e 20 62 61 64 20 74 68 69 6e  ng then bad thin
16600 67 73 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 68  gs will likely h
16610 61 70 70 65 6e 2e 0a 2a 2f 0a 76 6f 69 64 20 73  appen..*/.void s
16620 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
16630 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
16640 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 74  ** CAPI3REF: Det
16650 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 4c  ermine If An SQL
16660 20 53 74 61 74 65 6d 65 6e 74 20 49 73 20 43 6f   Statement Is Co
16670 6d 70 6c 65 74 65 0a 2a 2a 0a 2a 2a 20 54 68 65  mplete.**.** The
16680 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
16690 75 73 65 66 75 6c 20 64 75 72 69 6e 67 20 63 6f  useful during co
166a0 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69 6e 70 75 74  mmand-line input
166b0 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 69 66   to determine if
166c0 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 6c   the.** currentl
166d0 79 20 65 6e 74 65 72 65 64 20 74 65 78 74 20 73  y entered text s
166e0 65 65 6d 73 20 74 6f 20 66 6f 72 6d 20 61 20 63  eems to form a c
166f0 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61 74  omplete SQL stat
16700 65 6d 65 6e 74 20 6f 72 0a 2a 2a 20 69 66 20 61  ement or.** if a
16710 64 64 69 74 69 6f 6e 61 6c 20 69 6e 70 75 74 20  dditional input 
16720 69 73 20 6e 65 65 64 65 64 20 62 65 66 6f 72 65  is needed before
16730 20 73 65 6e 64 69 6e 67 20 74 68 65 20 74 65 78   sending the tex
16740 74 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74 65  t into.** SQLite
16750 20 66 6f 72 20 70 61 72 73 69 6e 67 2e 20 20 5e   for parsing.  ^
16760 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72  These routines r
16770 65 74 75 72 6e 20 31 20 69 66 20 74 68 65 20 69  eturn 1 if the i
16780 6e 70 75 74 20 73 74 72 69 6e 67 0a 2a 2a 20 61  nput string.** a
16790 70 70 65 61 72 73 20 74 6f 20 62 65 20 61 20 63  ppears to be a c
167a0 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61 74  omplete SQL stat
167b0 65 6d 65 6e 74 2e 20 20 5e 41 20 73 74 61 74 65  ement.  ^A state
167c0 6d 65 6e 74 20 69 73 20 6a 75 64 67 65 64 20 74  ment is judged t
167d0 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65  o be.** complete
167e0 20 69 66 20 69 74 20 65 6e 64 73 20 77 69 74 68   if it ends with
167f0 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 20 74 6f 6b   a semicolon tok
16800 65 6e 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20  en and is not a 
16810 70 72 65 66 69 78 20 6f 66 20 61 0a 2a 2a 20 77  prefix of a.** w
16820 65 6c 6c 2d 66 6f 72 6d 65 64 20 43 52 45 41 54  ell-formed CREAT
16830 45 20 54 52 49 47 47 45 52 20 73 74 61 74 65 6d  E TRIGGER statem
16840 65 6e 74 2e 20 20 5e 53 65 6d 69 63 6f 6c 6f 6e  ent.  ^Semicolon
16850 73 20 74 68 61 74 20 61 72 65 20 65 6d 62 65 64  s that are embed
16860 64 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 73 74  ded within.** st
16870 72 69 6e 67 20 6c 69 74 65 72 61 6c 73 20 6f 72  ring literals or
16880 20 71 75 6f 74 65 64 20 69 64 65 6e 74 69 66 69   quoted identifi
16890 65 72 20 6e 61 6d 65 73 20 6f 72 20 63 6f 6d 6d  er names or comm
168a0 65 6e 74 73 20 61 72 65 20 6e 6f 74 0a 2a 2a 20  ents are not.** 
168b0 69 6e 64 65 70 65 6e 64 65 6e 74 20 74 6f 6b 65  independent toke
168c0 6e 73 20 28 74 68 65 79 20 61 72 65 20 70 61 72  ns (they are par
168d0 74 20 6f 66 20 74 68 65 20 74 6f 6b 65 6e 20 69  t of the token i
168e0 6e 20 77 68 69 63 68 20 74 68 65 79 20 61 72 65  n which they are
168f0 0a 2a 2a 20 65 6d 62 65 64 64 65 64 29 20 61 6e  .** embedded) an
16900 64 20 74 68 75 73 20 64 6f 20 6e 6f 74 20 63 6f  d thus do not co
16910 75 6e 74 20 61 73 20 61 20 73 74 61 74 65 6d 65  unt as a stateme
16920 6e 74 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20  nt terminator.  
16930 5e 57 68 69 74 65 73 70 61 63 65 0a 2a 2a 20 61  ^Whitespace.** a
16940 6e 64 20 63 6f 6d 6d 65 6e 74 73 20 74 68 61 74  nd comments that
16950 20 66 6f 6c 6c 6f 77 20 74 68 65 20 66 69 6e 61   follow the fina
16960 6c 20 73 65 6d 69 63 6f 6c 6f 6e 20 61 72 65 20  l semicolon are 
16970 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  ignored..**.** ^
16980 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72  These routines r
16990 65 74 75 72 6e 20 30 20 69 66 20 74 68 65 20 73  eturn 0 if the s
169a0 74 61 74 65 6d 65 6e 74 20 69 73 20 69 6e 63 6f  tatement is inco
169b0 6d 70 6c 65 74 65 2e 20 20 5e 49 66 20 61 0a 2a  mplete.  ^If a.*
169c0 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  * memory allocat
169d0 69 6f 6e 20 66 61 69 6c 73 2c 20 74 68 65 6e 20  ion fails, then 
169e0 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 69 73 20  SQLITE_NOMEM is 
169f0 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
16a00 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
16a10 64 6f 20 6e 6f 74 20 70 61 72 73 65 20 74 68 65  do not parse the
16a20 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
16a30 74 68 75 73 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74  thus.** will not
16a40 20 64 65 74 65 63 74 20 73 79 6e 74 61 63 74 69   detect syntacti
16a50 63 61 6c 6c 79 20 69 6e 63 6f 72 72 65 63 74 20  cally incorrect 
16a60 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20  SQL..**.** ^(If 
16a70 53 51 4c 69 74 65 20 68 61 73 20 6e 6f 74 20 62  SQLite has not b
16a80 65 65 6e 20 69 6e 69 74 69 61 6c 69 7a 65 64 20  een initialized 
16a90 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 69  using [sqlite3_i
16aa0 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 70 72 69  nitialize()] pri
16ab0 6f 72 20 0a 2a 2a 20 74 6f 20 69 6e 76 6f 6b 69  or .** to invoki
16ac0 6e 67 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  ng sqlite3_compl
16ad0 65 74 65 31 36 28 29 20 74 68 65 6e 20 73 71 6c  ete16() then sql
16ae0 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
16af0 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20  ) is invoked.** 
16b00 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79  automatically by
16b10 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74   sqlite3_complet
16b20 65 31 36 28 29 2e 20 20 49 66 20 74 68 61 74 20  e16().  If that 
16b30 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 66  initialization f
16b40 61 69 6c 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  ails,.** then th
16b50 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66  e return value f
16b60 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  rom sqlite3_comp
16b70 6c 65 74 65 31 36 28 29 20 77 69 6c 6c 20 62 65  lete16() will be
16b80 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a 20 72 65 67   non-zero.** reg
16b90 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68  ardless of wheth
16ba0 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 69 6e  er or not the in
16bb0 70 75 74 20 53 51 4c 20 69 73 20 63 6f 6d 70 6c  put SQL is compl
16bc0 65 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65  ete.)^.**.** The
16bd0 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74   input to [sqlit
16be0 65 33 5f 63 6f 6d 70 6c 65 74 65 28 29 5d 20 6d  e3_complete()] m
16bf0 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65  ust be a zero-te
16c00 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d  rminated.** UTF-
16c10 38 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  8 string..**.** 
16c20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 71  The input to [sq
16c30 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36  lite3_complete16
16c40 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65  ()] must be a ze
16c50 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ro-terminated.**
16c60 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 69   UTF-16 string i
16c70 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  n native byte or
16c80 64 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  der..*/.int sqli
16c90 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 63 6f 6e  te3_complete(con
16ca0 73 74 20 63 68 61 72 20 2a 73 71 6c 29 3b 0a 69  st char *sql);.i
16cb0 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  nt sqlite3_compl
16cc0 65 74 65 31 36 28 63 6f 6e 73 74 20 76 6f 69 64  ete16(const void
16cd0 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43   *sql);../*.** C
16ce0 41 50 49 33 52 45 46 3a 20 52 65 67 69 73 74 65  API3REF: Registe
16cf0 72 20 41 20 43 61 6c 6c 62 61 63 6b 20 54 6f 20  r A Callback To 
16d00 48 61 6e 64 6c 65 20 53 51 4c 49 54 45 5f 42 55  Handle SQLITE_BU
16d10 53 59 20 45 72 72 6f 72 73 0a 2a 2a 0a 2a 2a 20  SY Errors.**.** 
16d20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 65  ^This routine se
16d30 74 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75  ts a callback fu
16d40 6e 63 74 69 6f 6e 20 74 68 61 74 20 6d 69 67 68  nction that migh
16d50 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65  t be invoked whe
16d60 6e 65 76 65 72 0a 2a 2a 20 61 6e 20 61 74 74 65  never.** an atte
16d70 6d 70 74 20 69 73 20 6d 61 64 65 20 74 6f 20 6f  mpt is made to o
16d80 70 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 74  pen a database t
16d90 61 62 6c 65 20 74 68 61 74 20 61 6e 6f 74 68 65  able that anothe
16da0 72 20 74 68 72 65 61 64 0a 2a 2a 20 6f 72 20 70  r thread.** or p
16db0 72 6f 63 65 73 73 20 68 61 73 20 6c 6f 63 6b 65  rocess has locke
16dc0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  d..**.** ^If the
16dd0 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69   busy callback i
16de0 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b 53 51  s NULL, then [SQ
16df0 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53  LITE_BUSY] or [S
16e00 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43  QLITE_IOERR_BLOC
16e10 4b 45 44 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72  KED].** is retur
16e20 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 20  ned immediately 
16e30 75 70 6f 6e 20 65 6e 63 6f 75 6e 74 65 72 69 6e  upon encounterin
16e40 67 20 74 68 65 20 6c 6f 63 6b 2e 20 20 5e 49 66  g the lock.  ^If
16e50 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61   the busy callba
16e60 63 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c  ck.** is not NUL
16e70 4c 2c 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c  L, then the call
16e80 62 61 63 6b 20 6d 69 67 68 74 20 62 65 20 69 6e  back might be in
16e90 76 6f 6b 65 64 20 77 69 74 68 20 74 77 6f 20 61  voked with two a
16ea0 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  rguments..**.** 
16eb0 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d  ^The first argum
16ec0 65 6e 74 20 74 6f 20 74 68 65 20 62 75 73 79 20  ent to the busy 
16ed0 68 61 6e 64 6c 65 72 20 69 73 20 61 20 63 6f 70  handler is a cop
16ee0 79 20 6f 66 20 74 68 65 20 76 6f 69 64 2a 20 70  y of the void* p
16ef0 6f 69 6e 74 65 72 20 77 68 69 63 68 0a 2a 2a 20  ointer which.** 
16f00 69 73 20 74 68 65 20 74 68 69 72 64 20 61 72 67  is the third arg
16f10 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
16f20 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 2e  _busy_handler().
16f30 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72    ^The second ar
16f40 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 65  gument to.** the
16f50 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63 61   busy handler ca
16f60 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e 75  llback is the nu
16f70 6d 62 65 72 20 6f 66 20 74 69 6d 65 73 20 74 68  mber of times th
16f80 61 74 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  at the busy hand
16f90 6c 65 72 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20  ler has.** been 
16fa0 69 6e 76 6f 6b 65 64 20 66 6f 72 20 74 68 69 73  invoked for this
16fb0 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 2e 20   locking event. 
16fc0 20 5e 49 66 20 74 68 65 0a 2a 2a 20 62 75 73 79   ^If the.** busy
16fd0 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
16fe0 73 20 30 2c 20 74 68 65 6e 20 6e 6f 20 61 64 64  s 0, then no add
16ff0 69 74 69 6f 6e 61 6c 20 61 74 74 65 6d 70 74 73  itional attempts
17000 20 61 72 65 20 6d 61 64 65 20 74 6f 0a 2a 2a 20   are made to.** 
17010 61 63 63 65 73 73 20 74 68 65 20 64 61 74 61 62  access the datab
17020 61 73 65 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f  ase and [SQLITE_
17030 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45  BUSY] or [SQLITE
17040 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20  _IOERR_BLOCKED] 
17050 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20  is returned..** 
17060 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  ^If the callback
17070 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72   returns non-zer
17080 6f 2c 20 74 68 65 6e 20 61 6e 6f 74 68 65 72 20  o, then another 
17090 61 74 74 65 6d 70 74 0a 2a 2a 20 69 73 20 6d 61  attempt.** is ma
170a0 64 65 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 64  de to open the d
170b0 61 74 61 62 61 73 65 20 66 6f 72 20 72 65 61 64  atabase for read
170c0 69 6e 67 20 61 6e 64 20 74 68 65 20 63 79 63 6c  ing and the cycl
170d0 65 20 72 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a  e repeats..**.**
170e0 20 54 68 65 20 70 72 65 73 65 6e 63 65 20 6f 66   The presence of
170f0 20 61 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20   a busy handler 
17100 64 6f 65 73 20 6e 6f 74 20 67 75 61 72 61 6e 74  does not guarant
17110 65 65 20 74 68 61 74 20 69 74 20 77 69 6c 6c 20  ee that it will 
17120 62 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68  be invoked.** wh
17130 65 6e 20 74 68 65 72 65 20 69 73 20 6c 6f 63 6b  en there is lock
17140 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e 20 5e 49 66   contention. ^If
17150 20 53 51 4c 69 74 65 20 64 65 74 65 72 6d 69 6e   SQLite determin
17160 65 73 20 74 68 61 74 20 69 6e 76 6f 6b 69 6e 67  es that invoking
17170 20 74 68 65 20 62 75 73 79 0a 2a 2a 20 68 61 6e   the busy.** han
17180 64 6c 65 72 20 63 6f 75 6c 64 20 72 65 73 75 6c  dler could resul
17190 74 20 69 6e 20 61 20 64 65 61 64 6c 6f 63 6b 2c  t in a deadlock,
171a0 20 69 74 20 77 69 6c 6c 20 67 6f 20 61 68 65 61   it will go ahea
171b0 64 20 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 51  d and return [SQ
171c0 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 6f 72  LITE_BUSY].** or
171d0 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42   [SQLITE_IOERR_B
171e0 4c 4f 43 4b 45 44 5d 20 69 6e 73 74 65 61 64 20  LOCKED] instead 
171f0 6f 66 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20  of invoking the 
17200 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a  busy handler..**
17210 20 43 6f 6e 73 69 64 65 72 20 61 20 73 63 65 6e   Consider a scen
17220 61 72 69 6f 20 77 68 65 72 65 20 6f 6e 65 20 70  ario where one p
17230 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e  rocess is holdin
17240 67 20 61 20 72 65 61 64 20 6c 6f 63 6b 20 74 68  g a read lock th
17250 61 74 0a 2a 2a 20 69 74 20 69 73 20 74 72 79 69  at.** it is tryi
17260 6e 67 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f  ng to promote to
17270 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b   a reserved lock
17280 20 61 6e 64 0a 2a 2a 20 61 20 73 65 63 6f 6e 64   and.** a second
17290 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64   process is hold
172a0 69 6e 67 20 61 20 72 65 73 65 72 76 65 64 20 6c  ing a reserved l
172b0 6f 63 6b 20 74 68 61 74 20 69 74 20 69 73 20 74  ock that it is t
172c0 72 79 69 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d  rying.** to prom
172d0 6f 74 65 20 74 6f 20 61 6e 20 65 78 63 6c 75 73  ote to an exclus
172e0 69 76 65 20 6c 6f 63 6b 2e 20 20 54 68 65 20 66  ive lock.  The f
172f0 69 72 73 74 20 70 72 6f 63 65 73 73 20 63 61 6e  irst process can
17300 6e 6f 74 20 70 72 6f 63 65 65 64 0a 2a 2a 20 62  not proceed.** b
17310 65 63 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f  ecause it is blo
17320 63 6b 65 64 20 62 79 20 74 68 65 20 73 65 63 6f  cked by the seco
17330 6e 64 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e  nd and the secon
17340 64 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74  d process cannot
17350 0a 2a 2a 20 70 72 6f 63 65 65 64 20 62 65 63 61  .** proceed beca
17360 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65  use it is blocke
17370 64 20 62 79 20 74 68 65 20 66 69 72 73 74 2e 20  d by the first. 
17380 20 49 66 20 62 6f 74 68 20 70 72 6f 63 65 73 73   If both process
17390 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 65  es.** invoke the
173a0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2c 20   busy handlers, 
173b0 6e 65 69 74 68 65 72 20 77 69 6c 6c 20 6d 61 6b  neither will mak
173c0 65 20 61 6e 79 20 70 72 6f 67 72 65 73 73 2e 20  e any progress. 
173d0 20 54 68 65 72 65 66 6f 72 65 2c 0a 2a 2a 20 53   Therefore,.** S
173e0 51 4c 69 74 65 20 72 65 74 75 72 6e 73 20 5b 53  QLite returns [S
173f0 51 4c 49 54 45 5f 42 55 53 59 5d 20 66 6f 72 20  QLITE_BUSY] for 
17400 74 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73  the first proces
17410 73 2c 20 68 6f 70 69 6e 67 20 74 68 61 74 20 74  s, hoping that t
17420 68 69 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64 75  his.** will indu
17430 63 65 20 74 68 65 20 66 69 72 73 74 20 70 72 6f  ce the first pro
17440 63 65 73 73 20 74 6f 20 72 65 6c 65 61 73 65 20  cess to release 
17450 69 74 73 20 72 65 61 64 20 6c 6f 63 6b 20 61 6e  its read lock an
17460 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20 73  d allow.** the s
17470 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 74 6f  econd process to
17480 20 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20   proceed..**.** 
17490 5e 54 68 65 20 64 65 66 61 75 6c 74 20 62 75 73  ^The default bus
174a0 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55  y callback is NU
174b0 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b  LL..**.** ^The [
174c0 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 65 72 72  SQLITE_BUSY] err
174d0 6f 72 20 69 73 20 63 6f 6e 76 65 72 74 65 64 20  or is converted 
174e0 74 6f 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  to [SQLITE_IOERR
174f0 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 77 68 65  _BLOCKED].** whe
17500 6e 20 53 51 4c 69 74 65 20 69 73 20 69 6e 20 74  n SQLite is in t
17510 68 65 20 6d 69 64 64 6c 65 20 6f 66 20 61 20 6c  he middle of a l
17520 61 72 67 65 20 74 72 61 6e 73 61 63 74 69 6f 6e  arge transaction
17530 20 77 68 65 72 65 20 61 6c 6c 20 74 68 65 0a 2a   where all the.*
17540 2a 20 63 68 61 6e 67 65 73 20 77 69 6c 6c 20 6e  * changes will n
17550 6f 74 20 66 69 74 20 69 6e 74 6f 20 74 68 65 20  ot fit into the 
17560 69 6e 2d 6d 65 6d 6f 72 79 20 63 61 63 68 65 2e  in-memory cache.
17570 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a    SQLite will.**
17580 20 61 6c 72 65 61 64 79 20 68 6f 6c 64 20 61 20   already hold a 
17590 52 45 53 45 52 56 45 44 20 6c 6f 63 6b 20 6f 6e  RESERVED lock on
175a0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
175b0 6c 65 2c 20 62 75 74 20 69 74 20 6e 65 65 64 73  le, but it needs
175c0 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74  .** to promote t
175d0 68 69 73 20 6c 6f 63 6b 20 74 6f 20 45 58 43 4c  his lock to EXCL
175e0 55 53 49 56 45 20 73 6f 20 74 68 61 74 20 69 74  USIVE so that it
175f0 20 63 61 6e 20 73 70 69 6c 6c 20 63 61 63 68 65   can spill cache
17600 0a 2a 2a 20 70 61 67 65 73 20 69 6e 74 6f 20 74  .** pages into t
17610 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
17620 20 77 69 74 68 6f 75 74 20 68 61 72 6d 20 74 6f   without harm to
17630 20 63 6f 6e 63 75 72 72 65 6e 74 0a 2a 2a 20 72   concurrent.** r
17640 65 61 64 65 72 73 2e 20 20 5e 49 66 20 69 74 20  eaders.  ^If it 
17650 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 70 72 6f  is unable to pro
17660 6d 6f 74 65 20 74 68 65 20 6c 6f 63 6b 2c 20 74  mote the lock, t
17670 68 65 6e 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72  hen the in-memor
17680 79 0a 2a 2a 20 63 61 63 68 65 20 77 69 6c 6c 20  y.** cache will 
17690 62 65 20 6c 65 66 74 20 69 6e 20 61 6e 20 69 6e  be left in an in
176a0 63 6f 6e 73 69 73 74 65 6e 74 20 73 74 61 74 65  consistent state
176b0 20 61 6e 64 20 73 6f 20 74 68 65 20 65 72 72 6f   and so the erro
176c0 72 0a 2a 2a 20 63 6f 64 65 20 69 73 20 70 72 6f  r.** code is pro
176d0 6d 6f 74 65 64 20 66 72 6f 6d 20 74 68 65 20 72  moted from the r
176e0 65 6c 61 74 69 76 65 6c 79 20 62 65 6e 69 67 6e  elatively benign
176f0 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 74   [SQLITE_BUSY] t
17700 6f 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 65  o.** the more se
17710 76 65 72 65 20 5b 53 51 4c 49 54 45 5f 49 4f 45  vere [SQLITE_IOE
17720 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e 20 20 5e 54  RR_BLOCKED].  ^T
17730 68 69 73 20 65 72 72 6f 72 20 63 6f 64 65 20 70  his error code p
17740 72 6f 6d 6f 74 69 6f 6e 0a 2a 2a 20 66 6f 72 63  romotion.** forc
17750 65 73 20 61 6e 20 61 75 74 6f 6d 61 74 69 63 20  es an automatic 
17760 72 6f 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20  rollback of the 
17770 63 68 61 6e 67 65 73 2e 20 20 53 65 65 20 74 68  changes.  See th
17780 65 0a 2a 2a 20 3c 61 20 68 72 65 66 3d 22 2f 63  e.** <a href="/c
17790 76 73 74 72 61 63 2f 77 69 6b 69 3f 70 3d 43 6f  vstrac/wiki?p=Co
177a0 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e  rruptionFollowin
177b0 67 42 75 73 79 45 72 72 6f 72 22 3e 0a 2a 2a 20  gBusyError">.** 
177c0 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77  CorruptionFollow
177d0 69 6e 67 42 75 73 79 45 72 72 6f 72 3c 2f 61 3e  ingBusyError</a>
177e0 20 77 69 6b 69 20 70 61 67 65 20 66 6f 72 20 61   wiki page for a
177f0 20 64 69 73 63 75 73 73 69 6f 6e 20 6f 66 20 77   discussion of w
17800 68 79 0a 2a 2a 20 74 68 69 73 20 69 73 20 69 6d  hy.** this is im
17810 70 6f 72 74 61 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e  portant..**.** ^
17820 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20  (There can only 
17830 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79  be a single busy
17840 20 68 61 6e 64 6c 65 72 20 64 65 66 69 6e 65 64   handler defined
17850 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 5b 64 61   for each.** [da
17860 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
17870 6e 5d 2e 20 20 53 65 74 74 69 6e 67 20 61 20 6e  n].  Setting a n
17880 65 77 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  ew busy handler 
17890 63 6c 65 61 72 73 20 61 6e 79 0a 2a 2a 20 70 72  clears any.** pr
178a0 65 76 69 6f 75 73 6c 79 20 73 65 74 20 68 61 6e  eviously set han
178b0 64 6c 65 72 2e 29 5e 20 20 5e 4e 6f 74 65 20 74  dler.)^  ^Note t
178c0 68 61 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c  hat calling [sql
178d0 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75  ite3_busy_timeou
178e0 74 28 29 5d 0a 2a 2a 20 77 69 6c 6c 20 61 6c 73  t()].** will als
178f0 6f 20 73 65 74 20 6f 72 20 63 6c 65 61 72 20 74  o set or clear t
17900 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e  he busy handler.
17910 0a 2a 2a 0a 2a 2a 20 54 68 65 20 62 75 73 79 20  .**.** The busy 
17920 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 20  callback should 
17930 6e 6f 74 20 74 61 6b 65 20 61 6e 79 20 61 63 74  not take any act
17940 69 6f 6e 73 20 77 68 69 63 68 20 6d 6f 64 69 66  ions which modif
17950 79 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  y the.** databas
17960 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61  e connection tha
17970 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75  t invoked the bu
17980 73 79 20 68 61 6e 64 6c 65 72 2e 20 20 41 6e 79  sy handler.  Any
17990 20 73 75 63 68 20 61 63 74 69 6f 6e 73 0a 2a 2a   such actions.**
179a0 20 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 66   result in undef
179b0 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a  ined behavior..*
179c0 2a 20 0a 2a 2a 20 41 20 62 75 73 79 20 68 61 6e  * .** A busy han
179d0 64 6c 65 72 20 6d 75 73 74 20 6e 6f 74 20 63 6c  dler must not cl
179e0 6f 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65  ose the database
179f0 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f   connection.** o
17a00 72 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  r [prepared stat
17a10 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 6e 76 6f  ement] that invo
17a20 6b 65 64 20 74 68 65 20 62 75 73 79 20 68 61 6e  ked the busy han
17a30 64 6c 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  dler..*/.int sql
17a40 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
17a50 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28  r(sqlite3*, int(
17a60 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 29 2c 20 76  *)(void*,int), v
17a70 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  oid*);../*.** CA
17a80 50 49 33 52 45 46 3a 20 53 65 74 20 41 20 42 75  PI3REF: Set A Bu
17a90 73 79 20 54 69 6d 65 6f 75 74 0a 2a 2a 0a 2a 2a  sy Timeout.**.**
17aa0 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73   ^This routine s
17ab0 65 74 73 20 61 20 5b 73 71 6c 69 74 65 33 5f 62  ets a [sqlite3_b
17ac0 75 73 79 5f 68 61 6e 64 6c 65 72 20 7c 20 62 75  usy_handler | bu
17ad0 73 79 20 68 61 6e 64 6c 65 72 5d 20 74 68 61 74  sy handler] that
17ae0 20 73 6c 65 65 70 73 0a 2a 2a 20 66 6f 72 20 61   sleeps.** for a
17af0 20 73 70 65 63 69 66 69 65 64 20 61 6d 6f 75 6e   specified amoun
17b00 74 20 6f 66 20 74 69 6d 65 20 77 68 65 6e 20 61  t of time when a
17b10 20 74 61 62 6c 65 20 69 73 20 6c 6f 63 6b 65 64   table is locked
17b20 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 72 0a  .  ^The handler.
17b30 2a 2a 20 77 69 6c 6c 20 73 6c 65 65 70 20 6d 75  ** will sleep mu
17b40 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 75 6e 74  ltiple times unt
17b50 69 6c 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22  il at least "ms"
17b60 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66   milliseconds of
17b70 20 73 6c 65 65 70 69 6e 67 0a 2a 2a 20 68 61 76   sleeping.** hav
17b80 65 20 61 63 63 75 6d 75 6c 61 74 65 64 2e 20 20  e accumulated.  
17b90 5e 41 66 74 65 72 20 61 74 20 6c 65 61 73 74 20  ^After at least 
17ba0 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  "ms" millisecond
17bb0 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 2c 0a 2a  s of sleeping,.*
17bc0 2a 20 74 68 65 20 68 61 6e 64 6c 65 72 20 72 65  * the handler re
17bd0 74 75 72 6e 73 20 30 20 77 68 69 63 68 20 63 61  turns 0 which ca
17be0 75 73 65 73 20 5b 73 71 6c 69 74 65 33 5f 73 74  uses [sqlite3_st
17bf0 65 70 28 29 5d 20 74 6f 20 72 65 74 75 72 6e 0a  ep()] to return.
17c00 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  ** [SQLITE_BUSY]
17c10 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52   or [SQLITE_IOER
17c20 52 5f 42 4c 4f 43 4b 45 44 5d 2e 0a 2a 2a 0a 2a  R_BLOCKED]..**.*
17c30 2a 20 5e 43 61 6c 6c 69 6e 67 20 74 68 69 73 20  * ^Calling this 
17c40 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 6e 20  routine with an 
17c50 61 72 67 75 6d 65 6e 74 20 6c 65 73 73 20 74 68  argument less th
17c60 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a  an or equal to z
17c70 65 72 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f 66 66  ero.** turns off
17c80 20 61 6c 6c 20 62 75 73 79 20 68 61 6e 64 6c 65   all busy handle
17c90 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72  rs..**.** ^(Ther
17ca0 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20  e can only be a 
17cb0 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64  single busy hand
17cc0 6c 65 72 20 66 6f 72 20 61 20 70 61 72 74 69 63  ler for a partic
17cd0 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73  ular.** [databas
17ce0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e  e connection] an
17cf0 79 20 61 6e 79 20 67 69 76 65 6e 20 6d 6f 6d 65  y any given mome
17d00 6e 74 2e 20 20 49 66 20 61 6e 6f 74 68 65 72 20  nt.  If another 
17d10 62 75 73 79 20 68 61 6e 64 6c 65 72 0a 2a 2a 20  busy handler.** 
17d20 77 61 73 20 64 65 66 69 6e 65 64 20 20 28 75 73  was defined  (us
17d30 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73  ing [sqlite3_bus
17d40 79 5f 68 61 6e 64 6c 65 72 28 29 5d 29 20 70 72  y_handler()]) pr
17d50 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a  ior to calling.*
17d60 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20  * this routine, 
17d70 74 68 61 74 20 6f 74 68 65 72 20 62 75 73 79 20  that other busy 
17d80 68 61 6e 64 6c 65 72 20 69 73 20 63 6c 65 61 72  handler is clear
17d90 65 64 2e 29 5e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  ed.)^.*/.int sql
17da0 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75  ite3_busy_timeou
17db0 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20  t(sqlite3*, int 
17dc0 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ms);../*.** CAPI
17dd0 33 52 45 46 3a 20 43 6f 6e 76 65 6e 69 65 6e 63  3REF: Convenienc
17de0 65 20 52 6f 75 74 69 6e 65 73 20 46 6f 72 20 52  e Routines For R
17df0 75 6e 6e 69 6e 67 20 51 75 65 72 69 65 73 0a 2a  unning Queries.*
17e00 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 61 20 6c  *.** This is a l
17e10 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 20  egacy interface 
17e20 74 68 61 74 20 69 73 20 70 72 65 73 65 72 76 65  that is preserve
17e30 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20  d for backwards 
17e40 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a  compatibility..*
17e50 2a 20 55 73 65 20 6f 66 20 74 68 69 73 20 69 6e  * Use of this in
17e60 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20 72  terface is not r
17e70 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2a 0a 2a  ecommended..**.*
17e80 2a 20 44 65 66 69 6e 69 74 69 6f 6e 3a 20 41 20  * Definition: A 
17e90 3c 62 3e 72 65 73 75 6c 74 20 74 61 62 6c 65 3c  <b>result table<
17ea0 2f 62 3e 20 69 73 20 6d 65 6d 6f 72 79 20 64 61  /b> is memory da
17eb0 74 61 20 73 74 72 75 63 74 75 72 65 20 63 72 65  ta structure cre
17ec0 61 74 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b  ated by the.** [
17ed0 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
17ee0 65 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20  e()] interface. 
17ef0 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   A result table 
17f00 72 65 63 6f 72 64 73 20 74 68 65 0a 2a 2a 20 63  records the.** c
17f10 6f 6d 70 6c 65 74 65 20 71 75 65 72 79 20 72 65  omplete query re
17f20 73 75 6c 74 73 20 66 72 6f 6d 20 6f 6e 65 20 6f  sults from one o
17f30 72 20 6d 6f 72 65 20 71 75 65 72 69 65 73 2e 0a  r more queries..
17f40 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 20  **.** The table 
17f50 63 6f 6e 63 65 70 74 75 61 6c 6c 79 20 68 61 73  conceptually has
17f60 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77   a number of row
17f70 73 20 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20 20  s and columns.  
17f80 42 75 74 0a 2a 2a 20 74 68 65 73 65 20 6e 75 6d  But.** these num
17f90 62 65 72 73 20 61 72 65 20 6e 6f 74 20 70 61 72  bers are not par
17fa0 74 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  t of the result 
17fb0 74 61 62 6c 65 20 69 74 73 65 6c 66 2e 20 20 54  table itself.  T
17fc0 68 65 73 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20  hese.** numbers 
17fd0 61 72 65 20 6f 62 74 61 69 6e 65 64 20 73 65 70  are obtained sep
17fe0 61 72 61 74 65 6c 79 2e 20 20 4c 65 74 20 4e 20  arately.  Let N 
17ff0 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  be the number of
18000 20 72 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d 20 62   rows.** and M b
18010 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  e the number of 
18020 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41  columns..**.** A
18030 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73   result table is
18040 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69   an array of poi
18050 6e 74 65 72 73 20 74 6f 20 7a 65 72 6f 2d 74 65  nters to zero-te
18060 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73  rminated UTF-8 s
18070 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 72 65  trings..** There
18080 20 61 72 65 20 28 4e 2b 31 29 2a 4d 20 65 6c 65   are (N+1)*M ele
18090 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 61 72 72  ments in the arr
180a0 61 79 2e 20 20 54 68 65 20 66 69 72 73 74 20 4d  ay.  The first M
180b0 20 70 6f 69 6e 74 65 72 73 20 70 6f 69 6e 74 0a   pointers point.
180c0 2a 2a 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69  ** to zero-termi
180d0 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20 74 68  nated strings th
180e0 61 74 20 20 63 6f 6e 74 61 69 6e 20 74 68 65 20  at  contain the 
180f0 6e 61 6d 65 73 20 6f 66 20 74 68 65 20 63 6f 6c  names of the col
18100 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20 72 65 6d  umns..** The rem
18110 61 69 6e 69 6e 67 20 65 6e 74 72 69 65 73 20 61  aining entries a
18120 6c 6c 20 70 6f 69 6e 74 20 74 6f 20 71 75 65 72  ll point to quer
18130 79 20 72 65 73 75 6c 74 73 2e 20 20 4e 55 4c 4c  y results.  NULL
18140 20 76 61 6c 75 65 73 20 72 65 73 75 6c 74 0a 2a   values result.*
18150 2a 20 69 6e 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  * in NULL pointe
18160 72 73 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 76  rs.  All other v
18170 61 6c 75 65 73 20 61 72 65 20 69 6e 20 74 68 65  alues are in the
18180 69 72 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65  ir UTF-8 zero-te
18190 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69  rminated.** stri
181a0 6e 67 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f  ng representatio
181b0 6e 20 61 73 20 72 65 74 75 72 6e 65 64 20 62 79  n as returned by
181c0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
181d0 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  _text()]..**.** 
181e0 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 6d  A result table m
181f0 69 67 68 74 20 63 6f 6e 73 69 73 74 20 6f 66 20  ight consist of 
18200 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f  one or more memo
18210 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a  ry allocations..
18220 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66  ** It is not saf
18230 65 20 74 6f 20 70 61 73 73 20 61 20 72 65 73 75  e to pass a resu
18240 6c 74 20 74 61 62 6c 65 20 64 69 72 65 63 74 6c  lt table directl
18250 79 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72  y to [sqlite3_fr
18260 65 65 28 29 5d 2e 0a 2a 2a 20 41 20 72 65 73 75  ee()]..** A resu
18270 6c 74 20 74 61 62 6c 65 20 73 68 6f 75 6c 64 20  lt table should 
18280 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 75  be deallocated u
18290 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72  sing [sqlite3_fr
182a0 65 65 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a  ee_table()]..**.
182b0 2a 2a 20 5e 28 41 73 20 61 6e 20 65 78 61 6d 70  ** ^(As an examp
182c0 6c 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  le of the result
182d0 20 74 61 62 6c 65 20 66 6f 72 6d 61 74 2c 20 73   table format, s
182e0 75 70 70 6f 73 65 20 61 20 71 75 65 72 79 20 72  uppose a query r
182f0 65 73 75 6c 74 0a 2a 2a 20 69 73 20 61 73 20 66  esult.** is as f
18300 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ollows:.**.** <b
18310 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
18320 2a 2a 20 20 20 20 20 20 20 20 4e 61 6d 65 20 20  **        Name  
18330 20 20 20 20 20 20 7c 20 41 67 65 0a 2a 2a 20 20        | Age.**  
18340 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d        ----------
18350 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a  -------------.**
18360 20 20 20 20 20 20 20 20 41 6c 69 63 65 20 20 20          Alice   
18370 20 20 20 20 7c 20 34 33 0a 2a 2a 20 20 20 20 20      | 43.**     
18380 20 20 20 42 6f 62 20 20 20 20 20 20 20 20 20 7c     Bob         |
18390 20 32 38 0a 2a 2a 20 20 20 20 20 20 20 20 43 69   28.**        Ci
183a0 6e 64 79 20 20 20 20 20 20 20 7c 20 32 31 0a 2a  ndy       | 21.*
183b0 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
183c0 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 72  uote>.**.** Ther
183d0 65 20 61 72 65 20 74 77 6f 20 63 6f 6c 75 6d 6e  e are two column
183e0 20 28 4d 3d 3d 32 29 20 61 6e 64 20 74 68 72 65   (M==2) and thre
183f0 65 20 72 6f 77 73 20 28 4e 3d 3d 33 29 2e 20 20  e rows (N==3).  
18400 54 68 75 73 20 74 68 65 0a 2a 2a 20 72 65 73 75  Thus the.** resu
18410 6c 74 20 74 61 62 6c 65 20 68 61 73 20 38 20 65  lt table has 8 e
18420 6e 74 72 69 65 73 2e 20 20 53 75 70 70 6f 73 65  ntries.  Suppose
18430 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c   the result tabl
18440 65 20 69 73 20 73 74 6f 72 65 64 0a 2a 2a 20 69  e is stored.** i
18450 6e 20 61 6e 20 61 72 72 61 79 20 6e 61 6d 65 73  n an array names
18460 20 61 7a 52 65 73 75 6c 74 2e 20 20 54 68 65 6e   azResult.  Then
18470 20 61 7a 52 65 73 75 6c 74 20 68 6f 6c 64 73 20   azResult holds 
18480 74 68 69 73 20 63 6f 6e 74 65 6e 74 3a 0a 2a 2a  this content:.**
18490 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
184a0 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20  <pre>.**        
184b0 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 30 5d 20  azResult&#91;0] 
184c0 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20 20 20  = "Name";.**    
184d0 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
184e0 3b 31 5d 20 3d 20 22 41 67 65 22 3b 0a 2a 2a 20  ;1] = "Age";.** 
184f0 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
18500 23 39 31 3b 32 5d 20 3d 20 22 41 6c 69 63 65 22  #91;2] = "Alice"
18510 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
18520 73 75 6c 74 26 23 39 31 3b 33 5d 20 3d 20 22 34  sult&#91;3] = "4
18530 33 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  3";.**        az
18540 52 65 73 75 6c 74 26 23 39 31 3b 34 5d 20 3d 20  Result&#91;4] = 
18550 22 42 6f 62 22 3b 0a 2a 2a 20 20 20 20 20 20 20  "Bob";.**       
18560 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 35 5d   azResult&#91;5]
18570 20 3d 20 22 32 38 22 3b 0a 2a 2a 20 20 20 20 20   = "28";.**     
18580 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
18590 36 5d 20 3d 20 22 43 69 6e 64 79 22 3b 0a 2a 2a  6] = "Cindy";.**
185a0 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
185b0 26 23 39 31 3b 37 5d 20 3d 20 22 32 31 22 3b 0a  &#91;7] = "21";.
185c0 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
185d0 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  quote>)^.**.** ^
185e0 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  The sqlite3_get_
185f0 74 61 62 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e  table() function
18600 20 65 76 61 6c 75 61 74 65 73 20 6f 6e 65 20 6f   evaluates one o
18610 72 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d 69 63 6f  r more.** semico
18620 6c 6f 6e 2d 73 65 70 61 72 61 74 65 64 20 53 51  lon-separated SQ
18630 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e 20  L statements in 
18640 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  the zero-termina
18650 74 65 64 20 55 54 46 2d 38 0a 2a 2a 20 73 74 72  ted UTF-8.** str
18660 69 6e 67 20 6f 66 20 69 74 73 20 32 6e 64 20 70  ing of its 2nd p
18670 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72 65 74  arameter and ret
18680 75 72 6e 73 20 61 20 72 65 73 75 6c 74 20 74 61  urns a result ta
18690 62 6c 65 20 74 6f 20 74 68 65 0a 2a 2a 20 70 6f  ble to the.** po
186a0 69 6e 74 65 72 20 67 69 76 65 6e 20 69 6e 20 69  inter given in i
186b0 74 73 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  ts 3rd parameter
186c0 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 74 68  ..**.** After th
186d0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 68 61  e application ha
186e0 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20  s finished with 
186f0 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 20  the result from 
18700 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
18710 65 28 29 2c 0a 2a 2a 20 69 74 20 6d 75 73 74 20  e(),.** it must 
18720 70 61 73 73 20 74 68 65 20 72 65 73 75 6c 74 20  pass the result 
18730 74 61 62 6c 65 20 70 6f 69 6e 74 65 72 20 74 6f  table pointer to
18740 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61   sqlite3_free_ta
18750 62 6c 65 28 29 20 69 6e 20 6f 72 64 65 72 20 74  ble() in order t
18760 6f 0a 2a 2a 20 72 65 6c 65 61 73 65 20 74 68 65  o.** release the
18770 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 77 61 73   memory that was
18780 20 6d 61 6c 6c 6f 63 65 64 2e 20 20 42 65 63 61   malloced.  Beca
18790 75 73 65 20 6f 66 20 74 68 65 20 77 61 79 20 74  use of the way t
187a0 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  he.** [sqlite3_m
187b0 61 6c 6c 6f 63 28 29 5d 20 68 61 70 70 65 6e 73  alloc()] happens
187c0 20 77 69 74 68 69 6e 20 73 71 6c 69 74 65 33 5f   within sqlite3_
187d0 67 65 74 5f 74 61 62 6c 65 28 29 2c 20 74 68 65  get_table(), the
187e0 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63   calling.** func
187f0 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 74 72  tion must not tr
18800 79 20 74 6f 20 63 61 6c 6c 20 5b 73 71 6c 69 74  y to call [sqlit
18810 65 33 5f 66 72 65 65 28 29 5d 20 64 69 72 65 63  e3_free()] direc
18820 74 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 5b 73  tly.  Only.** [s
18830 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c  qlite3_free_tabl
18840 65 28 29 5d 20 69 73 20 61 62 6c 65 20 74 6f 20  e()] is able to 
18850 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f  release the memo
18860 72 79 20 70 72 6f 70 65 72 6c 79 20 61 6e 64 20  ry properly and 
18870 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68  safely..**.** Th
18880 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61  e sqlite3_get_ta
18890 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  ble() interface 
188a0 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61  is implemented a
188b0 73 20 61 20 77 72 61 70 70 65 72 20 61 72 6f 75  s a wrapper arou
188c0 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  nd.** [sqlite3_e
188d0 78 65 63 28 29 5d 2e 20 20 54 68 65 20 73 71 6c  xec()].  The sql
188e0 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
188f0 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6e 6f   routine does no
18900 74 20 68 61 76 65 20 61 63 63 65 73 73 0a 2a 2a  t have access.**
18910 20 74 6f 20 61 6e 79 20 69 6e 74 65 72 6e 61 6c   to any internal
18920 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65 73   data structures
18930 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 49 74 20   of SQLite.  It 
18940 75 73 65 73 20 6f 6e 6c 79 20 74 68 65 20 70 75  uses only the pu
18950 62 6c 69 63 0a 2a 2a 20 69 6e 74 65 72 66 61 63  blic.** interfac
18960 65 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e 20  e defined here. 
18970 20 41 73 20 61 20 63 6f 6e 73 65 71 75 65 6e 63   As a consequenc
18980 65 2c 20 65 72 72 6f 72 73 20 74 68 61 74 20 6f  e, errors that o
18990 63 63 75 72 20 69 6e 20 74 68 65 0a 2a 2a 20 77  ccur in the.** w
189a0 72 61 70 70 65 72 20 6c 61 79 65 72 20 6f 75 74  rapper layer out
189b0 73 69 64 65 20 6f 66 20 74 68 65 20 69 6e 74 65  side of the inte
189c0 72 6e 61 6c 20 5b 73 71 6c 69 74 65 33 5f 65 78  rnal [sqlite3_ex
189d0 65 63 28 29 5d 20 63 61 6c 6c 20 61 72 65 20 6e  ec()] call are n
189e0 6f 74 0a 2a 2a 20 72 65 66 6c 65 63 74 65 64 20  ot.** reflected 
189f0 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63 61  in subsequent ca
18a00 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
18a10 65 72 72 63 6f 64 65 28 29 5d 20 6f 72 0a 2a 2a  errcode()] or.**
18a20 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
18a30 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ()]..*/.int sqli
18a40 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 0a 20  te3_get_table(. 
18a50 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
18a60 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65         /* An ope
18a70 6e 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20  n database */.  
18a80 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c  const char *zSql
18a90 2c 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20  ,     /* SQL to 
18aa0 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a  be evaluated */.
18ab0 20 20 63 68 61 72 20 2a 2a 2a 70 61 7a 52 65 73    char ***pazRes
18ac0 75 6c 74 2c 20 20 20 20 2f 2a 20 52 65 73 75 6c  ult,    /* Resul
18ad0 74 73 20 6f 66 20 74 68 65 20 71 75 65 72 79 20  ts of the query 
18ae0 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 52 6f 77 2c  */.  int *pnRow,
18af0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75             /* Nu
18b00 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 72  mber of result r
18b10 6f 77 73 20 77 72 69 74 74 65 6e 20 68 65 72 65  ows written here
18b20 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 43 6f 6c   */.  int *pnCol
18b30 75 6d 6e 2c 20 20 20 20 20 20 20 20 2f 2a 20 4e  umn,        /* N
18b40 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20  umber of result 
18b50 63 6f 6c 75 6d 6e 73 20 77 72 69 74 74 65 6e 20  columns written 
18b60 68 65 72 65 20 2a 2f 0a 20 20 63 68 61 72 20 2a  here */.  char *
18b70 2a 70 7a 45 72 72 6d 73 67 20 20 20 20 20 20 20  *pzErrmsg       
18b80 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69  /* Error msg wri
18b90 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a  tten here */.);.
18ba0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65  void sqlite3_fre
18bb0 65 5f 74 61 62 6c 65 28 63 68 61 72 20 2a 2a 72  e_table(char **r
18bc0 65 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  esult);../*.** C
18bd0 41 50 49 33 52 45 46 3a 20 46 6f 72 6d 61 74 74  API3REF: Formatt
18be0 65 64 20 53 74 72 69 6e 67 20 50 72 69 6e 74 69  ed String Printi
18bf0 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a  ng Functions.**.
18c00 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
18c10 73 20 61 72 65 20 77 6f 72 6b 2d 61 6c 69 6b 65  s are work-alike
18c20 73 20 6f 66 20 74 68 65 20 22 70 72 69 6e 74 66  s of the "printf
18c30 28 29 22 20 66 61 6d 69 6c 79 20 6f 66 20 66 75  ()" family of fu
18c40 6e 63 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20  nctions.** from 
18c50 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c  the standard C l
18c60 69 62 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ibrary..**.** ^T
18c70 68 65 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e  he sqlite3_mprin
18c80 74 66 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  tf() and sqlite3
18c90 5f 76 6d 70 72 69 6e 74 66 28 29 20 72 6f 75 74  _vmprintf() rout
18ca0 69 6e 65 73 20 77 72 69 74 65 20 74 68 65 69 72  ines write their
18cb0 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e 74 6f  .** results into
18cc0 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64   memory obtained
18cd0 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
18ce0 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54 68 65  alloc()]..** The
18cf0 20 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65   strings returne
18d00 64 20 62 79 20 74 68 65 73 65 20 74 77 6f 20 72  d by these two r
18d10 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c 64 20 62  outines should b
18d20 65 0a 2a 2a 20 72 65 6c 65 61 73 65 64 20 62 79  e.** released by
18d30 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
18d40 5d 2e 20 20 5e 42 6f 74 68 20 72 6f 75 74 69 6e  ].  ^Both routin
18d50 65 73 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 4e  es return a.** N
18d60 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 5b  ULL pointer if [
18d70 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
18d80 5d 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61  ] is unable to a
18d90 6c 6c 6f 63 61 74 65 20 65 6e 6f 75 67 68 0a 2a  llocate enough.*
18da0 2a 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64  * memory to hold
18db0 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73   the resulting s
18dc0 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  tring..**.** ^(T
18dd0 68 65 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  he sqlite3_snpri
18de0 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73  ntf() routine is
18df0 20 73 69 6d 69 6c 61 72 20 74 6f 20 22 73 6e 70   similar to "snp
18e00 72 69 6e 74 66 28 29 22 20 66 72 6f 6d 0a 2a 2a  rintf()" from.**
18e10 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20   the standard C 
18e20 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20 72 65  library.  The re
18e30 73 75 6c 74 20 69 73 20 77 72 69 74 74 65 6e 20  sult is written 
18e40 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 62 75 66 66  into the.** buff
18e50 65 72 20 73 75 70 70 6c 69 65 64 20 61 73 20 74  er supplied as t
18e60 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
18e70 74 65 72 20 77 68 6f 73 65 20 73 69 7a 65 20 69  ter whose size i
18e80 73 20 67 69 76 65 6e 20 62 79 0a 2a 2a 20 74 68  s given by.** th
18e90 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
18ea0 72 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65  r. Note that the
18eb0 20 6f 72 64 65 72 20 6f 66 20 74 68 65 0a 2a 2a   order of the.**
18ec0 20 66 69 72 73 74 20 74 77 6f 20 70 61 72 61 6d   first two param
18ed0 65 74 65 72 73 20 69 73 20 72 65 76 65 72 73 65  eters is reverse
18ee0 64 20 66 72 6f 6d 20 73 6e 70 72 69 6e 74 66 28  d from snprintf(
18ef0 29 2e 29 5e 20 20 54 68 69 73 20 69 73 20 61 6e  ).)^  This is an
18f00 0a 2a 2a 20 68 69 73 74 6f 72 69 63 61 6c 20 61  .** historical a
18f10 63 63 69 64 65 6e 74 20 74 68 61 74 20 63 61 6e  ccident that can
18f20 6e 6f 74 20 62 65 20 66 69 78 65 64 20 77 69 74  not be fixed wit
18f30 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 0a 2a 2a  hout breaking.**
18f40 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61   backwards compa
18f50 74 69 62 69 6c 69 74 79 2e 20 20 5e 28 4e 6f 74  tibility.  ^(Not
18f60 65 20 61 6c 73 6f 20 74 68 61 74 20 73 71 6c 69  e also that sqli
18f70 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a  te3_snprintf().*
18f80 2a 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  * returns a poin
18f90 74 65 72 20 74 6f 20 69 74 73 20 62 75 66 66 65  ter to its buffe
18fa0 72 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65  r instead of the
18fb0 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68   number of.** ch
18fc0 61 72 61 63 74 65 72 73 20 61 63 74 75 61 6c 6c  aracters actuall
18fd0 79 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74  y written into t
18fe0 68 65 20 62 75 66 66 65 72 2e 29 5e 20 20 57 65  he buffer.)^  We
18ff0 20 61 64 6d 69 74 20 74 68 61 74 0a 2a 2a 20 74   admit that.** t
19000 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61  he number of cha
19010 72 61 63 74 65 72 73 20 77 72 69 74 74 65 6e 20  racters written 
19020 77 6f 75 6c 64 20 62 65 20 61 20 6d 6f 72 65 20  would be a more 
19030 75 73 65 66 75 6c 20 72 65 74 75 72 6e 0a 2a 2a  useful return.**
19040 20 76 61 6c 75 65 20 62 75 74 20 77 65 20 63 61   value but we ca
19050 6e 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20  nnot change the 
19060 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
19070 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e  f sqlite3_snprin
19080 74 66 28 29 0a 2a 2a 20 6e 6f 77 20 77 69 74 68  tf().** now with
19090 6f 75 74 20 62 72 65 61 6b 69 6e 67 20 63 6f 6d  out breaking com
190a0 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a  patibility..**.*
190b0 2a 20 5e 41 73 20 6c 6f 6e 67 20 61 73 20 74 68  * ^As long as th
190c0 65 20 62 75 66 66 65 72 20 73 69 7a 65 20 69 73  e buffer size is
190d0 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 7a 65   greater than ze
190e0 72 6f 2c 20 73 71 6c 69 74 65 33 5f 73 6e 70 72  ro, sqlite3_snpr
190f0 69 6e 74 66 28 29 0a 2a 2a 20 67 75 61 72 61 6e  intf().** guaran
19100 74 65 65 73 20 74 68 61 74 20 74 68 65 20 62 75  tees that the bu
19110 66 66 65 72 20 69 73 20 61 6c 77 61 79 73 20 7a  ffer is always z
19120 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20  ero-terminated. 
19130 20 5e 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 70   ^The first.** p
19140 61 72 61 6d 65 74 65 72 20 22 6e 22 20 69 73 20  arameter "n" is 
19150 74 68 65 20 74 6f 74 61 6c 20 73 69 7a 65 20 6f  the total size o
19160 66 20 74 68 65 20 62 75 66 66 65 72 2c 20 69 6e  f the buffer, in
19170 63 6c 75 64 69 6e 67 20 73 70 61 63 65 20 66 6f  cluding space fo
19180 72 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 20 74 65  r.** the zero te
19190 72 6d 69 6e 61 74 6f 72 2e 20 20 53 6f 20 74 68  rminator.  So th
191a0 65 20 6c 6f 6e 67 65 73 74 20 73 74 72 69 6e 67  e longest string
191b0 20 74 68 61 74 20 63 61 6e 20 62 65 20 63 6f 6d   that can be com
191c0 70 6c 65 74 65 6c 79 0a 2a 2a 20 77 72 69 74 74  pletely.** writt
191d0 65 6e 20 77 69 6c 6c 20 62 65 20 6e 2d 31 20 63  en will be n-1 c
191e0 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a  haracters..**.**
191f0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 73   ^The sqlite3_vs
19200 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e  nprintf() routin
19210 65 20 69 73 20 61 20 76 61 72 61 72 67 73 20 76  e is a varargs v
19220 65 72 73 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65  ersion of sqlite
19230 33 5f 73 6e 70 72 69 6e 74 66 28 29 2e 0a 2a 2a  3_snprintf()..**
19240 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
19250 65 73 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74  es all implement
19260 20 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e 61 6c   some additional
19270 20 66 6f 72 6d 61 74 74 69 6e 67 0a 2a 2a 20 6f   formatting.** o
19280 70 74 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20  ptions that are 
19290 75 73 65 66 75 6c 20 66 6f 72 20 63 6f 6e 73 74  useful for const
192a0 72 75 63 74 69 6e 67 20 53 51 4c 20 73 74 61 74  ructing SQL stat
192b0 65 6d 65 6e 74 73 2e 0a 2a 2a 20 41 6c 6c 20 6f  ements..** All o
192c0 66 20 74 68 65 20 75 73 75 61 6c 20 70 72 69 6e  f the usual prin
192d0 74 66 28 29 20 66 6f 72 6d 61 74 74 69 6e 67 20  tf() formatting 
192e0 6f 70 74 69 6f 6e 73 20 61 70 70 6c 79 2e 20 20  options apply.  
192f0 49 6e 20 61 64 64 69 74 69 6f 6e 2c 20 74 68 65  In addition, the
19300 72 65 0a 2a 2a 20 69 73 20 61 72 65 20 22 25 71  re.** is are "%q
19310 22 2c 20 22 25 51 22 2c 20 61 6e 64 20 22 25 7a  ", "%Q", and "%z
19320 22 20 6f 70 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  " options..**.**
19330 20 5e 28 54 68 65 20 25 71 20 6f 70 74 69 6f 6e   ^(The %q option
19340 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 73 20 69   works like %s i
19350 6e 20 74 68 61 74 20 69 74 20 73 75 62 73 74 69  n that it substi
19360 74 75 74 65 73 20 61 20 6e 75 6c 2d 74 65 72 6d  tutes a nul-term
19370 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67  inated.** string
19380 20 66 72 6f 6d 20 74 68 65 20 61 72 67 75 6d 65   from the argume
19390 6e 74 20 6c 69 73 74 2e 20 20 42 75 74 20 25 71  nt list.  But %q
193a0 20 61 6c 73 6f 20 64 6f 75 62 6c 65 73 20 65 76   also doubles ev
193b0 65 72 79 20 27 5c 27 27 20 63 68 61 72 61 63 74  ery '\'' charact
193c0 65 72 2e 0a 2a 2a 20 25 71 20 69 73 20 64 65 73  er..** %q is des
193d0 69 67 6e 65 64 20 66 6f 72 20 75 73 65 20 69 6e  igned for use in
193e0 73 69 64 65 20 61 20 73 74 72 69 6e 67 20 6c 69  side a string li
193f0 74 65 72 61 6c 2e 29 5e 20 20 42 79 20 64 6f 75  teral.)^  By dou
19400 62 6c 69 6e 67 20 65 61 63 68 20 27 5c 27 27 0a  bling each '\''.
19410 2a 2a 20 63 68 61 72 61 63 74 65 72 20 69 74 20  ** character it 
19420 65 73 63 61 70 65 73 20 74 68 61 74 20 63 68 61  escapes that cha
19430 72 61 63 74 65 72 20 61 6e 64 20 61 6c 6c 6f 77  racter and allow
19440 73 20 69 74 20 74 6f 20 62 65 20 69 6e 73 65 72  s it to be inser
19450 74 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20  ted into.** the 
19460 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f  string..**.** Fo
19470 72 20 65 78 61 6d 70 6c 65 2c 20 61 73 73 75 6d  r example, assum
19480 65 20 74 68 65 20 73 74 72 69 6e 67 20 76 61 72  e the string var
19490 69 61 62 6c 65 20 7a 54 65 78 74 20 63 6f 6e 74  iable zText cont
194a0 61 69 6e 73 20 74 65 78 74 20 61 73 20 66 6f 6c  ains text as fol
194b0 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  lows:.**.** <blo
194c0 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
194d0 20 20 63 68 61 72 20 2a 7a 54 65 78 74 20 3d 20    char *zText = 
194e0 22 49 74 27 73 20 61 20 68 61 70 70 79 20 64 61  "It's a happy da
194f0 79 21 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  y!";.** </pre></
19500 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
19510 2a 20 4f 6e 65 20 63 61 6e 20 75 73 65 20 74 68  * One can use th
19520 69 73 20 74 65 78 74 20 69 6e 20 61 6e 20 53 51  is text in an SQ
19530 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 73 20 66  L statement as f
19540 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ollows:.**.** <b
19550 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
19560 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d  **  char *zSQL =
19570 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66   sqlite3_mprintf
19580 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61  ("INSERT INTO ta
19590 62 6c 65 20 56 41 4c 55 45 53 28 27 25 71 27 29  ble VALUES('%q')
195a0 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73  ", zText);.**  s
195b0 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20  qlite3_exec(db, 
195c0 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a  zSQL, 0, 0, 0);.
195d0 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65  **  sqlite3_free
195e0 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65  (zSQL);.** </pre
195f0 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
19600 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65  *.** Because the
19610 20 25 71 20 66 6f 72 6d 61 74 20 73 74 72 69 6e   %q format strin
19620 67 20 69 73 20 75 73 65 64 2c 20 74 68 65 20 27  g is used, the '
19630 5c 27 27 20 63 68 61 72 61 63 74 65 72 20 69 6e  \'' character in
19640 20 7a 54 65 78 74 0a 2a 2a 20 69 73 20 65 73 63   zText.** is esc
19650 61 70 65 64 20 61 6e 64 20 74 68 65 20 53 51 4c  aped and the SQL
19660 20 67 65 6e 65 72 61 74 65 64 20 69 73 20 61 73   generated is as
19670 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20   follows:.**.** 
19680 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
19690 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54  >.**  INSERT INT
196a0 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28  O table1 VALUES(
196b0 27 49 74 27 27 73 20 61 20 68 61 70 70 79 20 64  'It''s a happy d
196c0 61 79 21 27 29 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  ay!').** </pre><
196d0 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
196e0 2a 2a 20 54 68 69 73 20 69 73 20 63 6f 72 72 65  ** This is corre
196f0 63 74 2e 20 20 48 61 64 20 77 65 20 75 73 65 64  ct.  Had we used
19700 20 25 73 20 69 6e 73 74 65 61 64 20 6f 66 20 25   %s instead of %
19710 71 2c 20 74 68 65 20 67 65 6e 65 72 61 74 65 64  q, the generated
19720 20 53 51 4c 0a 2a 2a 20 77 6f 75 6c 64 20 68 61   SQL.** would ha
19730 76 65 20 6c 6f 6f 6b 65 64 20 6c 69 6b 65 20 74  ve looked like t
19740 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  his:.**.** <bloc
19750 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
19760 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62   INSERT INTO tab
19770 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74 27 73  le1 VALUES('It's
19780 20 61 20 68 61 70 70 79 20 64 61 79 21 27 29 3b   a happy day!');
19790 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
197a0 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68  kquote>.**.** Th
197b0 69 73 20 73 65 63 6f 6e 64 20 65 78 61 6d 70 6c  is second exampl
197c0 65 20 69 73 20 61 6e 20 53 51 4c 20 73 79 6e 74  e is an SQL synt
197d0 61 78 20 65 72 72 6f 72 2e 20 20 41 73 20 61 20  ax error.  As a 
197e0 67 65 6e 65 72 61 6c 20 72 75 6c 65 20 79 6f 75  general rule you
197f0 20 73 68 6f 75 6c 64 0a 2a 2a 20 61 6c 77 61 79   should.** alway
19800 73 20 75 73 65 20 25 71 20 69 6e 73 74 65 61 64  s use %q instead
19810 20 6f 66 20 25 73 20 77 68 65 6e 20 69 6e 73 65   of %s when inse
19820 72 74 69 6e 67 20 74 65 78 74 20 69 6e 74 6f 20  rting text into 
19830 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c  a string literal
19840 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 51  ..**.** ^(The %Q
19850 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69   option works li
19860 6b 65 20 25 71 20 65 78 63 65 70 74 20 69 74 20  ke %q except it 
19870 61 6c 73 6f 20 61 64 64 73 20 73 69 6e 67 6c 65  also adds single
19880 20 71 75 6f 74 65 73 20 61 72 6f 75 6e 64 0a 2a   quotes around.*
19890 2a 20 74 68 65 20 6f 75 74 73 69 64 65 20 6f 66  * the outside of
198a0 20 74 68 65 20 74 6f 74 61 6c 20 73 74 72 69 6e   the total strin
198b0 67 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 6c 79  g.  Additionally
198c0 2c 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74  , if the paramet
198d0 65 72 20 69 6e 20 74 68 65 0a 2a 2a 20 61 72 67  er in the.** arg
198e0 75 6d 65 6e 74 20 6c 69 73 74 20 69 73 20 61 20  ument list is a 
198f0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 25 51  NULL pointer, %Q
19900 20 73 75 62 73 74 69 74 75 74 65 73 20 74 68 65   substitutes the
19910 20 74 65 78 74 20 22 4e 55 4c 4c 22 20 28 77 69   text "NULL" (wi
19920 74 68 6f 75 74 0a 2a 2a 20 73 69 6e 67 6c 65 20  thout.** single 
19930 71 75 6f 74 65 73 29 2e 29 5e 20 20 53 6f 2c 20  quotes).)^  So, 
19940 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 6f 6e 65  for example, one
19950 20 63 6f 75 6c 64 20 73 61 79 3a 0a 2a 2a 0a 2a   could say:.**.*
19960 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
19970 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53  re>.**  char *zS
19980 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72  QL = sqlite3_mpr
19990 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54  intf("INSERT INT
199a0 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28 25  O table VALUES(%
199b0 51 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20  Q)", zText);.** 
199c0 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62   sqlite3_exec(db
199d0 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29  , zSQL, 0, 0, 0)
199e0 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72  ;.**  sqlite3_fr
199f0 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70  ee(zSQL);.** </p
19a00 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
19a10 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20  .**.** The code 
19a20 61 62 6f 76 65 20 77 69 6c 6c 20 72 65 6e 64 65  above will rende
19a30 72 20 61 20 63 6f 72 72 65 63 74 20 53 51 4c 20  r a correct SQL 
19a40 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 65  statement in the
19a50 20 7a 53 51 4c 0a 2a 2a 20 76 61 72 69 61 62 6c   zSQL.** variabl
19a60 65 20 65 76 65 6e 20 69 66 20 74 68 65 20 7a 54  e even if the zT
19a70 65 78 74 20 76 61 72 69 61 62 6c 65 20 69 73 20  ext variable is 
19a80 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
19a90 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 22 25 7a 22  **.** ^(The "%z"
19aa0 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69   formatting opti
19ab0 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 22 25  on works like "%
19ac0 73 22 20 62 75 74 20 77 69 74 68 20 74 68 65 0a  s" but with the.
19ad0 2a 2a 20 61 64 64 69 74 69 6f 6e 20 74 68 61 74  ** addition that
19ae0 20 61 66 74 65 72 20 74 68 65 20 73 74 72 69 6e   after the strin
19af0 67 20 68 61 73 20 62 65 65 6e 20 72 65 61 64 20  g has been read 
19b00 61 6e 64 20 63 6f 70 69 65 64 20 69 6e 74 6f 0a  and copied into.
19b10 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 2c 20 5b  ** the result, [
19b20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20  sqlite3_free()] 
19b30 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65  is called on the
19b40 20 69 6e 70 75 74 20 73 74 72 69 6e 67 2e 29 5e   input string.)^
19b50 0a 2a 2f 0a 63 68 61 72 20 2a 73 71 6c 69 74 65  .*/.char *sqlite
19b60 33 5f 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20  3_mprintf(const 
19b70 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 63 68 61 72  char*,...);.char
19b80 20 2a 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e   *sqlite3_vmprin
19b90 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  tf(const char*, 
19ba0 76 61 5f 6c 69 73 74 29 3b 0a 63 68 61 72 20 2a  va_list);.char *
19bb0 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
19bc0 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74  (int,char*,const
19bd0 20 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 63 68   char*, ...);.ch
19be0 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 73 6e 70  ar *sqlite3_vsnp
19bf0 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c  rintf(int,char*,
19c00 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 5f  const char*, va_
19c10 6c 69 73 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  list);../*.** CA
19c20 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41  PI3REF: Memory A
19c30 6c 6c 6f 63 61 74 69 6f 6e 20 53 75 62 73 79 73  llocation Subsys
19c40 74 65 6d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51  tem.**.** The SQ
19c50 4c 69 74 65 20 63 6f 72 65 20 75 73 65 73 20 74  Lite core uses t
19c60 68 65 73 65 20 74 68 72 65 65 20 72 6f 75 74 69  hese three routi
19c70 6e 65 73 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69  nes for all of i
19c80 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e  ts own.** intern
19c90 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  al memory alloca
19ca0 74 69 6f 6e 20 6e 65 65 64 73 2e 20 22 43 6f 72  tion needs. "Cor
19cb0 65 22 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f  e" in the previo
19cc0 75 73 20 73 65 6e 74 65 6e 63 65 0a 2a 2a 20 64  us sentence.** d
19cd0 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20  oes not include 
19ce0 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d  operating-system
19cf0 20 73 70 65 63 69 66 69 63 20 56 46 53 20 69 6d   specific VFS im
19d00 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 54  plementation.  T
19d10 68 65 0a 2a 2a 20 57 69 6e 64 6f 77 73 20 56 46  he.** Windows VF
19d20 53 20 75 73 65 73 20 6e 61 74 69 76 65 20 6d 61  S uses native ma
19d30 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28  lloc() and free(
19d40 29 20 66 6f 72 20 73 6f 6d 65 20 6f 70 65 72 61  ) for some opera
19d50 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  tions..**.** ^Th
19d60 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  e sqlite3_malloc
19d70 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  () routine retur
19d80 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
19d90 61 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 6d 65  a block.** of me
19da0 6d 6f 72 79 20 61 74 20 6c 65 61 73 74 20 4e 20  mory at least N 
19db0 62 79 74 65 73 20 69 6e 20 6c 65 6e 67 74 68 2c  bytes in length,
19dc0 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20   where N is the 
19dd0 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49  parameter..** ^I
19de0 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  f sqlite3_malloc
19df0 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  () is unable to 
19e00 6f 62 74 61 69 6e 20 73 75 66 66 69 63 69 65 6e  obtain sufficien
19e10 74 20 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f 72 79  t free.** memory
19e20 2c 20 69 74 20 72 65 74 75 72 6e 73 20 61 20 4e  , it returns a N
19e30 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 49  ULL pointer.  ^I
19e40 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
19e50 4e 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  N to.** sqlite3_
19e60 6d 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f  malloc() is zero
19e70 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 68 65   or negative the
19e80 6e 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  n sqlite3_malloc
19e90 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20  () returns.** a 
19ea0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
19eb0 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c  .** ^Calling sql
19ec0 69 74 65 33 5f 66 72 65 65 28 29 20 77 69 74 68  ite3_free() with
19ed0 20 61 20 70 6f 69 6e 74 65 72 20 70 72 65 76 69   a pointer previ
19ee0 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 0a 2a  ously returned.*
19ef0 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c  * by sqlite3_mal
19f00 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33  loc() or sqlite3
19f10 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 6c 65 61  _realloc() relea
19f20 73 65 73 20 74 68 61 74 20 6d 65 6d 6f 72 79 20  ses that memory 
19f30 73 6f 0a 2a 2a 20 74 68 61 74 20 69 74 20 6d 69  so.** that it mi
19f40 67 68 74 20 62 65 20 72 65 75 73 65 64 2e 20 20  ght be reused.  
19f50 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66 72 65  ^The sqlite3_fre
19f60 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73 0a 2a  e() routine is.*
19f70 2a 20 61 20 6e 6f 2d 6f 70 20 69 66 20 69 73 20  * a no-op if is 
19f80 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55  called with a NU
19f90 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 50 61 73  LL pointer.  Pas
19fa0 73 69 6e 67 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  sing a NULL poin
19fb0 74 65 72 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65  ter.** to sqlite
19fc0 33 5f 66 72 65 65 28 29 20 69 73 20 68 61 72 6d  3_free() is harm
19fd0 6c 65 73 73 2e 20 20 41 66 74 65 72 20 62 65 69  less.  After bei
19fe0 6e 67 20 66 72 65 65 64 2c 20 6d 65 6d 6f 72 79  ng freed, memory
19ff0 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 65 69 74 68  .** should neith
1a000 65 72 20 62 65 20 72 65 61 64 20 6e 6f 72 20 77  er be read nor w
1a010 72 69 74 74 65 6e 2e 20 20 45 76 65 6e 20 72 65  ritten.  Even re
1a020 61 64 69 6e 67 20 70 72 65 76 69 6f 75 73 6c 79  ading previously
1a030 20 66 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79   freed.** memory
1a040 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 6e   might result in
1a050 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20   a segmentation 
1a060 66 61 75 6c 74 20 6f 72 20 6f 74 68 65 72 20 73  fault or other s
1a070 65 76 65 72 65 20 65 72 72 6f 72 2e 0a 2a 2a 20  evere error..** 
1a080 4d 65 6d 6f 72 79 20 63 6f 72 72 75 70 74 69 6f  Memory corruptio
1a090 6e 2c 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f  n, a segmentatio
1a0a0 6e 20 66 61 75 6c 74 2c 20 6f 72 20 6f 74 68 65  n fault, or othe
1a0b0 72 20 73 65 76 65 72 65 20 65 72 72 6f 72 0a 2a  r severe error.*
1a0c0 2a 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69  * might result i
1a0d0 66 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29  f sqlite3_free()
1a0e0 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20   is called with 
1a0f0 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74  a non-NULL point
1a100 65 72 20 74 68 61 74 0a 2a 2a 20 77 61 73 20 6e  er that.** was n
1a110 6f 74 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ot obtained from
1a120 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
1a130 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61  ) or sqlite3_rea
1a140 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28  lloc()..**.** ^(
1a150 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 61 6c  The sqlite3_real
1a160 6c 6f 63 28 29 20 69 6e 74 65 72 66 61 63 65 20  loc() interface 
1a170 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65 73 69  attempts to resi
1a180 7a 65 20 61 0a 2a 2a 20 70 72 69 6f 72 20 6d 65  ze a.** prior me
1a190 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
1a1a0 74 6f 20 62 65 20 61 74 20 6c 65 61 73 74 20 4e  to be at least N
1a1b0 20 62 79 74 65 73 2c 20 77 68 65 72 65 20 4e 20   bytes, where N 
1a1c0 69 73 20 74 68 65 0a 2a 2a 20 73 65 63 6f 6e 64  is the.** second
1a1d0 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 68 65   parameter.  The
1a1e0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
1a1f0 6f 6e 20 74 6f 20 62 65 20 72 65 73 69 7a 65 64  on to be resized
1a200 20 69 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a   is the first.**
1a210 20 70 61 72 61 6d 65 74 65 72 2e 29 5e 20 5e 20   parameter.)^ ^ 
1a220 49 66 20 74 68 65 20 66 69 72 73 74 20 70 61 72  If the first par
1a230 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
1a240 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69  3_realloc().** i
1a250 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
1a260 20 74 68 65 6e 20 69 74 73 20 62 65 68 61 76 69   then its behavi
1a270 6f 72 20 69 73 20 69 64 65 6e 74 69 63 61 6c 20  or is identical 
1a280 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71  to calling.** sq
1a290 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20  lite3_malloc(N) 
1a2a0 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 73  where N is the s
1a2b0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
1a2c0 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  to sqlite3_reall
1a2d0 6f 63 28 29 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  oc()..** ^If the
1a2e0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
1a2f0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61  r to sqlite3_rea
1a300 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 6f  lloc() is zero o
1a310 72 0a 2a 2a 20 6e 65 67 61 74 69 76 65 20 74 68  r.** negative th
1a320 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
1a330 69 73 20 65 78 61 63 74 6c 79 20 74 68 65 20 73  is exactly the s
1a340 61 6d 65 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a  ame as calling.*
1a350 2a 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 50  * sqlite3_free(P
1a360 29 20 77 68 65 72 65 20 50 20 69 73 20 74 68 65  ) where P is the
1a370 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
1a380 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   to sqlite3_real
1a390 6c 6f 63 28 29 2e 0a 2a 2a 20 5e 73 71 6c 69 74  loc()..** ^sqlit
1a3a0 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 74  e3_realloc() ret
1a3b0 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
1a3c0 6f 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  o a memory alloc
1a3d0 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c  ation.** of at l
1a3e0 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20  east N bytes in 
1a3f0 73 69 7a 65 20 6f 72 20 4e 55 4c 4c 20 69 66 20  size or NULL if 
1a400 73 75 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72  sufficient memor
1a410 79 20 69 73 20 75 6e 61 76 61 69 6c 61 62 6c 65  y is unavailable
1a420 2e 0a 2a 2a 20 5e 49 66 20 4d 20 69 73 20 74 68  ..** ^If M is th
1a430 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 70 72  e size of the pr
1a440 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20  ior allocation, 
1a450 74 68 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 79  then min(N,M) by
1a460 74 65 73 0a 2a 2a 20 6f 66 20 74 68 65 20 70 72  tes.** of the pr
1a470 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61  ior allocation a
1a480 72 65 20 63 6f 70 69 65 64 20 69 6e 74 6f 20 74  re copied into t
1a490 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20  he beginning of 
1a4a0 62 75 66 66 65 72 20 72 65 74 75 72 6e 65 64 0a  buffer returned.
1a4b0 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 72 65  ** by sqlite3_re
1a4c0 61 6c 6c 6f 63 28 29 20 61 6e 64 20 74 68 65 20  alloc() and the 
1a4d0 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e  prior allocation
1a4e0 20 69 73 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49   is freed..** ^I
1a4f0 66 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  f sqlite3_reallo
1a500 63 28 29 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c  c() returns NULL
1a510 2c 20 74 68 65 6e 20 74 68 65 20 70 72 69 6f 72  , then the prior
1a520 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 69   allocation.** i
1a530 73 20 6e 6f 74 20 66 72 65 65 64 2e 0a 2a 2a 0a  s not freed..**.
1a540 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 72  ** ^The memory r
1a550 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
1a560 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20  e3_malloc() and 
1a570 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1a580 29 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61  ).** is always a
1a590 6c 69 67 6e 65 64 20 74 6f 20 61 74 20 6c 65 61  ligned to at lea
1a5a0 73 74 20 61 6e 20 38 20 62 79 74 65 20 62 6f 75  st an 8 byte bou
1a5b0 6e 64 61 72 79 2c 20 6f 72 20 74 6f 20 61 0a 2a  ndary, or to a.*
1a5c0 2a 20 34 20 62 79 74 65 20 62 6f 75 6e 64 61 72  * 4 byte boundar
1a5d0 79 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45  y if the [SQLITE
1a5e0 5f 34 5f 42 59 54 45 5f 41 4c 49 47 4e 45 44 5f  _4_BYTE_ALIGNED_
1a5f0 4d 41 4c 4c 4f 43 5d 20 63 6f 6d 70 69 6c 65 2d  MALLOC] compile-
1a600 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 20 69  time.** option i
1a610 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e  s used..**.** In
1a620 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
1a630 33 2e 35 2e 30 20 61 6e 64 20 33 2e 35 2e 31 2c  3.5.0 and 3.5.1,
1a640 20 69 74 20 77 61 73 20 70 6f 73 73 69 62 6c 65   it was possible
1a650 20 74 6f 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68   to define.** th
1a660 65 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45  e SQLITE_OMIT_ME
1a670 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20  MORY_ALLOCATION 
1a680 77 68 69 63 68 20 77 6f 75 6c 64 20 63 61 75 73  which would caus
1a690 65 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 0a 2a  e the built-in.*
1a6a0 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
1a6b0 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
1a6c0 65 73 20 74 6f 20 62 65 20 6f 6d 69 74 74 65 64  es to be omitted
1a6d0 2e 20 20 54 68 61 74 20 63 61 70 61 62 69 6c 69  .  That capabili
1a6e0 74 79 0a 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67  ty.** is no long
1a6f0 65 72 20 70 72 6f 76 69 64 65 64 2e 20 20 4f 6e  er provided.  On
1a700 6c 79 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f  ly built-in memo
1a710 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 20 63 61  ry allocators ca
1a720 6e 20 62 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a  n be used..**.**
1a730 20 50 72 69 6f 72 20 74 6f 20 53 51 4c 69 74 65   Prior to SQLite
1a740 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e 31 30 2c   version 3.7.10,
1a750 20 74 68 65 20 57 69 6e 64 6f 77 73 20 4f 53 20   the Windows OS 
1a760 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72 20  interface layer 
1a770 63 61 6c 6c 65 64 0a 2a 2a 20 74 68 65 20 73 79  called.** the sy
1a780 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 61 6e  stem malloc() an
1a790 64 20 66 72 65 65 28 29 20 64 69 72 65 63 74 6c  d free() directl
1a7a0 79 20 77 68 65 6e 20 63 6f 6e 76 65 72 74 69 6e  y when convertin
1a7b0 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 73 20 62  g.** filenames b
1a7c0 65 74 77 65 65 6e 20 74 68 65 20 55 54 46 2d 38  etween the UTF-8
1a7d0 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 62   encoding used b
1a7e0 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20  y SQLite.** and 
1a7f0 77 68 61 74 65 76 65 72 20 66 69 6c 65 6e 61 6d  whatever filenam
1a800 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73  e encoding is us
1a810 65 64 20 62 79 20 74 68 65 20 70 61 72 74 69 63  ed by the partic
1a820 75 6c 61 72 20 57 69 6e 64 6f 77 73 0a 2a 2a 20  ular Windows.** 
1a830 69 6e 73 74 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d  installation.  M
1a840 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
1a850 20 65 72 72 6f 72 73 20 77 65 72 65 20 64 65 74   errors were det
1a860 65 63 74 65 64 2c 20 62 75 74 0a 2a 2a 20 74 68  ected, but.** th
1a870 65 79 20 77 65 72 65 20 72 65 70 6f 72 74 65 64  ey were reported
1a880 20 62 61 63 6b 20 61 73 20 5b 53 51 4c 49 54 45   back as [SQLITE
1a890 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a  _CANTOPEN] or.**
1a8a0 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 20   [SQLITE_IOERR] 
1a8b0 72 61 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c  rather than [SQL
1a8c0 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a  ITE_NOMEM]..**.*
1a8d0 2a 20 54 68 65 20 70 6f 69 6e 74 65 72 20 61 72  * The pointer ar
1a8e0 67 75 6d 65 6e 74 73 20 74 6f 20 5b 73 71 6c 69  guments to [sqli
1a8f0 74 65 33 5f 66 72 65 65 28 29 5d 20 61 6e 64 20  te3_free()] and 
1a900 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
1a910 28 29 5d 0a 2a 2a 20 6d 75 73 74 20 62 65 20 65  ()].** must be e
1a920 69 74 68 65 72 20 4e 55 4c 4c 20 6f 72 20 65 6c  ither NULL or el
1a930 73 65 20 70 6f 69 6e 74 65 72 73 20 6f 62 74 61  se pointers obta
1a940 69 6e 65 64 20 66 72 6f 6d 20 61 20 70 72 69 6f  ined from a prio
1a950 72 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 20  r.** invocation 
1a960 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  of [sqlite3_mall
1a970 6f 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  oc()] or [sqlite
1a980 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 74 68 61  3_realloc()] tha
1a990 74 20 68 61 76 65 0a 2a 2a 20 6e 6f 74 20 79 65  t have.** not ye
1a9a0 74 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64 2e  t been released.
1a9b0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69  .**.** The appli
1a9c0 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20  cation must not 
1a9d0 72 65 61 64 20 6f 72 20 77 72 69 74 65 20 61 6e  read or write an
1a9e0 79 20 70 61 72 74 20 6f 66 0a 2a 2a 20 61 20 62  y part of.** a b
1a9f0 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 61  lock of memory a
1aa00 66 74 65 72 20 69 74 20 68 61 73 20 62 65 65 6e  fter it has been
1aa10 20 72 65 6c 65 61 73 65 64 20 75 73 69 6e 67 0a   released using.
1aa20 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ** [sqlite3_free
1aa30 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
1aa40 72 65 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 76  realloc()]..*/.v
1aa50 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c  oid *sqlite3_mal
1aa60 6c 6f 63 28 69 6e 74 29 3b 0a 76 6f 69 64 20 2a  loc(int);.void *
1aa70 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1aa80 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69  void*, int);.voi
1aa90 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 76  d sqlite3_free(v
1aaa0 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  oid*);../*.** CA
1aab0 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41  PI3REF: Memory A
1aac0 6c 6c 6f 63 61 74 6f 72 20 53 74 61 74 69 73 74  llocator Statist
1aad0 69 63 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  ics.**.** SQLite
1aae0 20 70 72 6f 76 69 64 65 73 20 74 68 65 73 65 20   provides these 
1aaf0 74 77 6f 20 69 6e 74 65 72 66 61 63 65 73 20 66  two interfaces f
1ab00 6f 72 20 72 65 70 6f 72 74 69 6e 67 20 6f 6e 20  or reporting on 
1ab10 74 68 65 20 73 74 61 74 75 73 0a 2a 2a 20 6f 66  the status.** of
1ab20 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 61   the [sqlite3_ma
1ab30 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65  lloc()], [sqlite
1ab40 33 5f 66 72 65 65 28 29 5d 2c 20 61 6e 64 20 5b  3_free()], and [
1ab50 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1ab60 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 2c 20  )].** routines, 
1ab70 77 68 69 63 68 20 66 6f 72 6d 20 74 68 65 20 62  which form the b
1ab80 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61  uilt-in memory a
1ab90 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73  llocation subsys
1aba0 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  tem..**.** ^The 
1abb0 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
1abc0 75 73 65 64 28 29 5d 20 72 6f 75 74 69 6e 65 20  used()] routine 
1abd0 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
1abe0 65 72 20 6f 66 20 62 79 74 65 73 0a 2a 2a 20 6f  er of bytes.** o
1abf0 66 20 6d 65 6d 6f 72 79 20 63 75 72 72 65 6e 74  f memory current
1ac00 6c 79 20 6f 75 74 73 74 61 6e 64 69 6e 67 20 28  ly outstanding (
1ac10 6d 61 6c 6c 6f 63 65 64 20 62 75 74 20 6e 6f 74  malloced but not
1ac20 20 66 72 65 65 64 29 2e 0a 2a 2a 20 5e 54 68 65   freed)..** ^The
1ac30 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
1ac40 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 72 6f  _highwater()] ro
1ac50 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68  utine returns th
1ac60 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 76 61 6c  e maximum.** val
1ac70 75 65 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d  ue of [sqlite3_m
1ac80 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 73 69  emory_used()] si
1ac90 6e 63 65 20 74 68 65 20 68 69 67 68 2d 77 61 74  nce the high-wat
1aca0 65 72 20 6d 61 72 6b 0a 2a 2a 20 77 61 73 20 6c  er mark.** was l
1acb0 61 73 74 20 72 65 73 65 74 2e 20 20 5e 54 68 65  ast reset.  ^The
1acc0 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64   values returned
1acd0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d   by [sqlite3_mem
1ace0 6f 72 79 5f 75 73 65 64 28 29 5d 20 61 6e 64 0a  ory_used()] and.
1acf0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  ** [sqlite3_memo
1ad00 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20  ry_highwater()] 
1ad10 69 6e 63 6c 75 64 65 20 61 6e 79 20 6f 76 65 72  include any over
1ad20 68 65 61 64 0a 2a 2a 20 61 64 64 65 64 20 62 79  head.** added by
1ad30 20 53 51 4c 69 74 65 20 69 6e 20 69 74 73 20 69   SQLite in its i
1ad40 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
1ad50 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
1ad60 28 29 5d 2c 0a 2a 2a 20 62 75 74 20 6e 6f 74 20  ()],.** but not 
1ad70 6f 76 65 72 68 65 61 64 20 61 64 64 65 64 20 62  overhead added b
1ad80 79 20 74 68 65 20 61 6e 79 20 75 6e 64 65 72 6c  y the any underl
1ad90 79 69 6e 67 20 73 79 73 74 65 6d 20 6c 69 62 72  ying system libr
1ada0 61 72 79 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20  ary.** routines 
1adb0 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 6d 61  that [sqlite3_ma
1adc0 6c 6c 6f 63 28 29 5d 20 6d 61 79 20 63 61 6c 6c  lloc()] may call
1add0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d  ..**.** ^The mem
1ade0 6f 72 79 20 68 69 67 68 2d 77 61 74 65 72 20 6d  ory high-water m
1adf0 61 72 6b 20 69 73 20 72 65 73 65 74 20 74 6f 20  ark is reset to 
1ae00 74 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75  the current valu
1ae10 65 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  e of.** [sqlite3
1ae20 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20  _memory_used()] 
1ae30 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74  if and only if t
1ae40 68 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  he parameter to.
1ae50 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  ** [sqlite3_memo
1ae60 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20  ry_highwater()] 
1ae70 69 73 20 74 72 75 65 2e 20 20 5e 54 68 65 20 76  is true.  ^The v
1ae80 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a  alue returned.**
1ae90 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d   by [sqlite3_mem
1aea0 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 31 29  ory_highwater(1)
1aeb0 5d 20 69 73 20 74 68 65 20 68 69 67 68 2d 77 61  ] is the high-wa
1aec0 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 70 72 69 6f  ter mark.** prio
1aed0 72 20 74 6f 20 74 68 65 20 72 65 73 65 74 2e 0a  r to the reset..
1aee0 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  */.sqlite3_int64
1aef0 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f   sqlite3_memory_
1af00 75 73 65 64 28 76 6f 69 64 29 3b 0a 73 71 6c 69  used(void);.sqli
1af10 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  te3_int64 sqlite
1af20 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
1af30 65 72 28 69 6e 74 20 72 65 73 65 74 46 6c 61 67  er(int resetFlag
1af40 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1af50 45 46 3a 20 50 73 65 75 64 6f 2d 52 61 6e 64 6f  EF: Pseudo-Rando
1af60 6d 20 4e 75 6d 62 65 72 20 47 65 6e 65 72 61 74  m Number Generat
1af70 6f 72 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  or.**.** SQLite 
1af80 63 6f 6e 74 61 69 6e 73 20 61 20 68 69 67 68 2d  contains a high-
1af90 71 75 61 6c 69 74 79 20 70 73 65 75 64 6f 2d 72  quality pseudo-r
1afa0 61 6e 64 6f 6d 20 6e 75 6d 62 65 72 20 67 65 6e  andom number gen
1afb0 65 72 61 74 6f 72 20 28 50 52 4e 47 29 20 75 73  erator (PRNG) us
1afc0 65 64 20 74 6f 0a 2a 2a 20 73 65 6c 65 63 74 20  ed to.** select 
1afd0 72 61 6e 64 6f 6d 20 5b 52 4f 57 49 44 20 7c 20  random [ROWID | 
1afe0 52 4f 57 49 44 73 5d 20 77 68 65 6e 20 69 6e 73  ROWIDs] when ins
1aff0 65 72 74 69 6e 67 20 6e 65 77 20 72 65 63 6f 72  erting new recor
1b000 64 73 20 69 6e 74 6f 20 61 20 74 61 62 6c 65 20  ds into a table 
1b010 74 68 61 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20  that.** already 
1b020 75 73 65 73 20 74 68 65 20 6c 61 72 67 65 73 74  uses the largest
1b030 20 70 6f 73 73 69 62 6c 65 20 5b 52 4f 57 49 44   possible [ROWID
1b040 5d 2e 20 20 54 68 65 20 50 52 4e 47 20 69 73 20  ].  The PRNG is 
1b050 61 6c 73 6f 20 75 73 65 64 20 66 6f 72 0a 2a 2a  also used for.**
1b060 20 74 68 65 20 62 75 69 6c 64 2d 69 6e 20 72 61   the build-in ra
1b070 6e 64 6f 6d 28 29 20 61 6e 64 20 72 61 6e 64 6f  ndom() and rando
1b080 6d 62 6c 6f 62 28 29 20 53 51 4c 20 66 75 6e 63  mblob() SQL func
1b090 74 69 6f 6e 73 2e 20 20 54 68 69 73 20 69 6e 74  tions.  This int
1b0a0 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 0a 2a 2a  erface allows.**
1b0b0 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 6f   applications to
1b0c0 20 61 63 63 65 73 73 20 74 68 65 20 73 61 6d 65   access the same
1b0d0 20 50 52 4e 47 20 66 6f 72 20 6f 74 68 65 72 20   PRNG for other 
1b0e0 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a 20  purposes..**.** 
1b0f0 5e 41 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20  ^A call to this 
1b100 72 6f 75 74 69 6e 65 20 73 74 6f 72 65 73 20 4e  routine stores N
1b110 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d   bytes of random
1b120 6e 65 73 73 20 69 6e 74 6f 20 62 75 66 66 65 72  ness into buffer
1b130 20 50 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66   P..**.** ^The f
1b140 69 72 73 74 20 74 69 6d 65 20 74 68 69 73 20 72  irst time this r
1b150 6f 75 74 69 6e 65 20 69 73 20 69 6e 76 6f 6b 65  outine is invoke
1b160 64 20 28 65 69 74 68 65 72 20 69 6e 74 65 72 6e  d (either intern
1b170 61 6c 6c 79 20 6f 72 20 62 79 0a 2a 2a 20 74 68  ally or by.** th
1b180 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 29 20 74  e application) t
1b190 68 65 20 50 52 4e 47 20 69 73 20 73 65 65 64 65  he PRNG is seede
1b1a0 64 20 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e 65  d using randomne
1b1b0 73 73 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66  ss obtained.** f
1b1c0 72 6f 6d 20 74 68 65 20 78 52 61 6e 64 6f 6d 6e  rom the xRandomn
1b1d0 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68  ess method of th
1b1e0 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74  e default [sqlit
1b1f0 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a  e3_vfs] object..
1b200 2a 2a 20 5e 4f 6e 20 61 6c 6c 20 73 75 62 73 65  ** ^On all subse
1b210 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e  quent invocation
1b220 73 2c 20 74 68 65 20 70 73 65 75 64 6f 2d 72 61  s, the pseudo-ra
1b230 6e 64 6f 6d 6e 65 73 73 20 69 73 20 67 65 6e 65  ndomness is gene
1b240 72 61 74 65 64 0a 2a 2a 20 69 6e 74 65 72 6e 61  rated.** interna
1b250 6c 6c 79 20 61 6e 64 20 77 69 74 68 6f 75 74 20  lly and without 
1b260 72 65 63 6f 75 72 73 65 20 74 6f 20 74 68 65 20  recourse to the 
1b270 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 78 52  [sqlite3_vfs] xR
1b280 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d 65 74  andomness.** met
1b290 68 6f 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c  hod..*/.void sql
1b2a0 69 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28  ite3_randomness(
1b2b0 69 6e 74 20 4e 2c 20 76 6f 69 64 20 2a 50 29 3b  int N, void *P);
1b2c0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1b2d0 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 41  : Compile-Time A
1b2e0 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 43 61 6c  uthorization Cal
1b2f0 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68  lbacks.**.** ^Th
1b300 69 73 20 72 6f 75 74 69 6e 65 20 72 65 67 69 73  is routine regis
1b310 74 65 72 73 20 61 6e 20 61 75 74 68 6f 72 69 7a  ters an authoriz
1b320 65 72 20 63 61 6c 6c 62 61 63 6b 20 77 69 74 68  er callback with
1b330 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a   a particular.**
1b340 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
1b350 63 74 69 6f 6e 5d 2c 20 73 75 70 70 6c 69 65 64  ction], supplied
1b360 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72   in the first ar
1b370 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20  gument..** ^The 
1b380 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
1b390 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 61  ack is invoked a
1b3a0 73 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  s SQL statements
1b3b0 20 61 72 65 20 62 65 69 6e 67 20 63 6f 6d 70 69   are being compi
1b3c0 6c 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74  led.** by [sqlit
1b3d0 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72  e3_prepare()] or
1b3e0 20 69 74 73 20 76 61 72 69 61 6e 74 73 20 5b 73   its variants [s
1b3f0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
1b400 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  2()],.** [sqlite
1b410 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 61  3_prepare16()] a
1b420 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  nd [sqlite3_prep
1b430 61 72 65 31 36 5f 76 32 28 29 5d 2e 20 20 5e 41  are16_v2()].  ^A
1b440 74 20 76 61 72 69 6f 75 73 0a 2a 2a 20 70 6f 69  t various.** poi
1b450 6e 74 73 20 64 75 72 69 6e 67 20 74 68 65 20 63  nts during the c
1b460 6f 6d 70 69 6c 61 74 69 6f 6e 20 70 72 6f 63 65  ompilation proce
1b470 73 73 2c 20 61 73 20 6c 6f 67 69 63 20 69 73 20  ss, as logic is 
1b480 62 65 69 6e 67 20 63 72 65 61 74 65 64 0a 2a 2a  being created.**
1b490 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69   to perform vari
1b4a0 6f 75 73 20 61 63 74 69 6f 6e 73 2c 20 74 68 65  ous actions, the
1b4b0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
1b4c0 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
1b4d0 74 6f 0a 2a 2a 20 73 65 65 20 69 66 20 74 68 6f  to.** see if tho
1b4e0 73 65 20 61 63 74 69 6f 6e 73 20 61 72 65 20 61  se actions are a
1b4f0 6c 6c 6f 77 65 64 2e 20 20 5e 54 68 65 20 61 75  llowed.  ^The au
1b500 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1b510 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75  k should.** retu
1b520 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 74  rn [SQLITE_OK] t
1b530 6f 20 61 6c 6c 6f 77 20 74 68 65 20 61 63 74 69  o allow the acti
1b540 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f  on, [SQLITE_IGNO
1b550 52 45 5d 20 74 6f 20 64 69 73 61 6c 6c 6f 77 20  RE] to disallow 
1b560 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20  the.** specific 
1b570 61 63 74 69 6f 6e 20 62 75 74 20 61 6c 6c 6f 77  action but allow
1b580 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
1b590 6e 74 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20 74  nt to continue t
1b5a0 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64  o be.** compiled
1b5b0 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e  , or [SQLITE_DEN
1b5c0 59 5d 20 74 6f 20 63 61 75 73 65 20 74 68 65 20  Y] to cause the 
1b5d0 65 6e 74 69 72 65 20 53 51 4c 20 73 74 61 74 65  entire SQL state
1b5e0 6d 65 6e 74 20 74 6f 20 62 65 0a 2a 2a 20 72 65  ment to be.** re
1b5f0 6a 65 63 74 65 64 20 77 69 74 68 20 61 6e 20 65  jected with an e
1b600 72 72 6f 72 2e 20 20 5e 49 66 20 74 68 65 20 61  rror.  ^If the a
1b610 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
1b620 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e  ck returns.** an
1b630 79 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68  y value other th
1b640 61 6e 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52  an [SQLITE_IGNOR
1b650 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c  E], [SQLITE_OK],
1b660 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59   or [SQLITE_DENY
1b670 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 5b 73  ].** then the [s
1b680 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
1b690 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65  2()] or equivale
1b6a0 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69  nt call that tri
1b6b0 67 67 65 72 65 64 0a 2a 2a 20 74 68 65 20 61 75  ggered.** the au
1b6c0 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61  thorizer will fa
1b6d0 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72  il with an error
1b6e0 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20   message..**.** 
1b6f0 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63  When the callbac
1b700 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  k returns [SQLIT
1b710 45 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d 65 61 6e  E_OK], that mean
1b720 73 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a  s the operation.
1b730 2a 2a 20 72 65 71 75 65 73 74 65 64 20 69 73 20  ** requested is 
1b740 6f 6b 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 63  ok.  ^When the c
1b750 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
1b760 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74  [SQLITE_DENY], t
1b770 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  he.** [sqlite3_p
1b780 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
1b790 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20  equivalent call 
1b7a0 74 68 61 74 20 74 72 69 67 67 65 72 65 64 20 74  that triggered t
1b7b0 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72  he.** authorizer
1b7c0 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20   will fail with 
1b7d0 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  an error message
1b7e0 20 65 78 70 6c 61 69 6e 69 6e 67 20 74 68 61 74   explaining that
1b7f0 0a 2a 2a 20 61 63 63 65 73 73 20 69 73 20 64 65  .** access is de
1b800 6e 69 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68  nied. .**.** ^Th
1b810 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
1b820 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69  r to the authori
1b830 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
1b840 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 74 68  a copy of the th
1b850 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ird.** parameter
1b860 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
1b870 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29  set_authorizer()
1b880 20 69 6e 74 65 72 66 61 63 65 2e 20 5e 54 68 65   interface. ^The
1b890 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
1b8a0 72 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c  r.** to the call
1b8b0 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67  back is an integ
1b8c0 65 72 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20  er [SQLITE_COPY 
1b8d0 7c 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d 20 74  | action code] t
1b8e0 68 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a  hat specifies.**
1b8f0 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20   the particular 
1b900 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74  action to be aut
1b910 68 6f 72 69 7a 65 64 2e 20 5e 54 68 65 20 74 68  horized. ^The th
1b920 69 72 64 20 74 68 72 6f 75 67 68 20 73 69 78 74  ird through sixt
1b930 68 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20  h parameters.** 
1b940 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  to the callback 
1b950 61 72 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  are zero-termina
1b960 74 65 64 20 73 74 72 69 6e 67 73 20 74 68 61 74  ted strings that
1b970 20 63 6f 6e 74 61 69 6e 20 61 64 64 69 74 69 6f   contain additio
1b980 6e 61 6c 0a 2a 2a 20 64 65 74 61 69 6c 73 20 61  nal.** details a
1b990 62 6f 75 74 20 74 68 65 20 61 63 74 69 6f 6e 20  bout the action 
1b9a0 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64  to be authorized
1b9b0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
1b9c0 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b  action code is [
1b9d0 53 51 4c 49 54 45 5f 52 45 41 44 5d 0a 2a 2a 20  SQLITE_READ].** 
1b9e0 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  and the callback
1b9f0 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
1ba00 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68  _IGNORE] then th
1ba10 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  e.** [prepared s
1ba20 74 61 74 65 6d 65 6e 74 5d 20 73 74 61 74 65 6d  tatement] statem
1ba30 65 6e 74 20 69 73 20 63 6f 6e 73 74 72 75 63 74  ent is construct
1ba40 65 64 20 74 6f 20 73 75 62 73 74 69 74 75 74 65  ed to substitute
1ba50 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65  .** a NULL value
1ba60 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 74 68 65   in place of the
1ba70 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68   table column th
1ba80 61 74 20 77 6f 75 6c 64 20 68 61 76 65 0a 2a 2a  at would have.**
1ba90 20 62 65 65 6e 20 72 65 61 64 20 69 66 20 5b 53   been read if [S
1baa0 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20 62 65  QLITE_OK] had be
1bab0 65 6e 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68  en returned.  Th
1bac0 65 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  e [SQLITE_IGNORE
1bad0 5d 0a 2a 2a 20 72 65 74 75 72 6e 20 63 61 6e 20  ].** return can 
1bae0 62 65 20 75 73 65 64 20 74 6f 20 64 65 6e 79 20  be used to deny 
1baf0 61 6e 20 75 6e 74 72 75 73 74 65 64 20 75 73 65  an untrusted use
1bb00 72 20 61 63 63 65 73 73 20 74 6f 20 69 6e 64 69  r access to indi
1bb10 76 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e  vidual.** column
1bb20 73 20 6f 66 20 61 20 74 61 62 6c 65 2e 0a 2a 2a  s of a table..**
1bb30 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20   ^If the action 
1bb40 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f  code is [SQLITE_
1bb50 44 45 4c 45 54 45 5d 20 61 6e 64 20 74 68 65 20  DELETE] and the 
1bb60 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
1bb70 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f  .** [SQLITE_IGNO
1bb80 52 45 5d 20 74 68 65 6e 20 74 68 65 20 5b 44 45  RE] then the [DE
1bb90 4c 45 54 45 5d 20 6f 70 65 72 61 74 69 6f 6e 20  LETE] operation 
1bba0 70 72 6f 63 65 65 64 73 20 62 75 74 20 74 68 65  proceeds but the
1bbb0 0a 2a 2a 20 5b 74 72 75 6e 63 61 74 65 20 6f 70  .** [truncate op
1bbc0 74 69 6d 69 7a 61 74 69 6f 6e 5d 20 69 73 20 64  timization] is d
1bbd0 69 73 61 62 6c 65 64 20 61 6e 64 20 61 6c 6c 20  isabled and all 
1bbe0 72 6f 77 73 20 61 72 65 20 64 65 6c 65 74 65 64  rows are deleted
1bbf0 20 69 6e 64 69 76 69 64 75 61 6c 6c 79 2e 0a 2a   individually..*
1bc00 2a 0a 2a 2a 20 41 6e 20 61 75 74 68 6f 72 69 7a  *.** An authoriz
1bc10 65 72 20 69 73 20 75 73 65 64 20 77 68 65 6e 20  er is used when 
1bc20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1bc30 20 7c 20 70 72 65 70 61 72 69 6e 67 5d 0a 2a 2a   | preparing].**
1bc40 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
1bc50 66 72 6f 6d 20 61 6e 20 75 6e 74 72 75 73 74 65  from an untruste
1bc60 64 20 73 6f 75 72 63 65 2c 20 74 6f 20 65 6e 73  d source, to ens
1bc70 75 72 65 20 74 68 61 74 20 74 68 65 20 53 51 4c  ure that the SQL
1bc80 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 64   statements.** d
1bc90 6f 20 6e 6f 74 20 74 72 79 20 74 6f 20 61 63 63  o not try to acc
1bca0 65 73 73 20 64 61 74 61 20 74 68 65 79 20 61 72  ess data they ar
1bcb0 65 20 6e 6f 74 20 61 6c 6c 6f 77 65 64 20 74 6f  e not allowed to
1bcc0 20 73 65 65 2c 20 6f 72 20 74 68 61 74 20 74 68   see, or that th
1bcd0 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 74 72 79  ey do not.** try
1bce0 20 74 6f 20 65 78 65 63 75 74 65 20 6d 61 6c 69   to execute mali
1bcf0 63 69 6f 75 73 20 73 74 61 74 65 6d 65 6e 74 73  cious statements
1bd00 20 74 68 61 74 20 64 61 6d 61 67 65 20 74 68 65   that damage the
1bd10 20 64 61 74 61 62 61 73 65 2e 20 20 46 6f 72 0a   database.  For.
1bd20 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61  ** example, an a
1bd30 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79 20 61  pplication may a
1bd40 6c 6c 6f 77 20 61 20 75 73 65 72 20 74 6f 20 65  llow a user to e
1bd50 6e 74 65 72 20 61 72 62 69 74 72 61 72 79 0a 2a  nter arbitrary.*
1bd60 2a 20 53 51 4c 20 71 75 65 72 69 65 73 20 66 6f  * SQL queries fo
1bd70 72 20 65 76 61 6c 75 61 74 69 6f 6e 20 62 79 20  r evaluation by 
1bd80 61 20 64 61 74 61 62 61 73 65 2e 20 20 42 75 74  a database.  But
1bd90 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
1bda0 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e   does.** not wan
1bdb0 74 20 74 68 65 20 75 73 65 72 20 74 6f 20 62 65  t the user to be
1bdc0 20 61 62 6c 65 20 74 6f 20 6d 61 6b 65 20 61 72   able to make ar
1bdd0 62 69 74 72 61 72 79 20 63 68 61 6e 67 65 73 20  bitrary changes 
1bde0 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  to the.** databa
1bdf0 73 65 2e 20 20 41 6e 20 61 75 74 68 6f 72 69 7a  se.  An authoriz
1be00 65 72 20 63 6f 75 6c 64 20 74 68 65 6e 20 62 65  er could then be
1be10 20 70 75 74 20 69 6e 20 70 6c 61 63 65 20 77 68   put in place wh
1be20 69 6c 65 20 74 68 65 0a 2a 2a 20 75 73 65 72 2d  ile the.** user-
1be30 65 6e 74 65 72 65 64 20 53 51 4c 20 69 73 20 62  entered SQL is b
1be40 65 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72  eing [sqlite3_pr
1be50 65 70 61 72 65 20 7c 20 70 72 65 70 61 72 65 64  epare | prepared
1be60 5d 20 74 68 61 74 0a 2a 2a 20 64 69 73 61 6c 6c  ] that.** disall
1be70 6f 77 73 20 65 76 65 72 79 74 68 69 6e 67 20 65  ows everything e
1be80 78 63 65 70 74 20 5b 53 45 4c 45 43 54 5d 20 73  xcept [SELECT] s
1be90 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a  tatements..**.**
1bea0 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68   Applications th
1beb0 61 74 20 6e 65 65 64 20 74 6f 20 70 72 6f 63 65  at need to proce
1bec0 73 73 20 53 51 4c 20 66 72 6f 6d 20 75 6e 74 72  ss SQL from untr
1bed0 75 73 74 65 64 20 73 6f 75 72 63 65 73 0a 2a 2a  usted sources.**
1bee0 20 6d 69 67 68 74 20 61 6c 73 6f 20 63 6f 6e 73   might also cons
1bef0 69 64 65 72 20 6c 6f 77 65 72 69 6e 67 20 72 65  ider lowering re
1bf00 73 6f 75 72 63 65 20 6c 69 6d 69 74 73 20 75 73  source limits us
1bf10 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d  ing [sqlite3_lim
1bf20 69 74 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c 69 6d  it()].** and lim
1bf30 69 74 69 6e 67 20 64 61 74 61 62 61 73 65 20 73  iting database s
1bf40 69 7a 65 20 75 73 69 6e 67 20 74 68 65 20 5b 6d  ize using the [m
1bf50 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b  ax_page_count] [
1bf60 50 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20 61 64  PRAGMA].** in ad
1bf70 64 69 74 69 6f 6e 20 74 6f 20 75 73 69 6e 67 20  dition to using 
1bf80 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 2e 0a 2a  an authorizer..*
1bf90 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 61 20 73 69  *.** ^(Only a si
1bfa0 6e 67 6c 65 20 61 75 74 68 6f 72 69 7a 65 72 20  ngle authorizer 
1bfb0 63 61 6e 20 62 65 20 69 6e 20 70 6c 61 63 65 20  can be in place 
1bfc0 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20 63 6f  on a database co
1bfd0 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 74 20 61  nnection.** at a
1bfe0 20 74 69 6d 65 2e 20 20 45 61 63 68 20 63 61 6c   time.  Each cal
1bff0 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74  l to sqlite3_set
1c000 5f 61 75 74 68 6f 72 69 7a 65 72 20 6f 76 65 72  _authorizer over
1c010 72 69 64 65 73 20 74 68 65 0a 2a 2a 20 70 72 65  rides the.** pre
1c020 76 69 6f 75 73 20 63 61 6c 6c 2e 29 5e 20 20 5e  vious call.)^  ^
1c030 44 69 73 61 62 6c 65 20 74 68 65 20 61 75 74 68  Disable the auth
1c040 6f 72 69 7a 65 72 20 62 79 20 69 6e 73 74 61 6c  orizer by instal
1c050 6c 69 6e 67 20 61 20 4e 55 4c 4c 20 63 61 6c 6c  ling a NULL call
1c060 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 61 75 74  back..** The aut
1c070 68 6f 72 69 7a 65 72 20 69 73 20 64 69 73 61 62  horizer is disab
1c080 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a  led by default..
1c090 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72  **.** The author
1c0a0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75  izer callback mu
1c0b0 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69  st not do anythi
1c0c0 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64  ng that will mod
1c0d0 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62  ify.** the datab
1c0e0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  ase connection t
1c0f0 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20  hat invoked the 
1c100 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
1c110 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ack..** Note tha
1c120 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  t [sqlite3_prepa
1c130 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71  re_v2()] and [sq
1c140 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f  lite3_step()] bo
1c150 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a  th modify their.
1c160 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ** database conn
1c170 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20  ections for the 
1c180 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69  meaning of "modi
1c190 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 61  fy" in this para
1c1a0 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68  graph..**.** ^Wh
1c1b0 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  en [sqlite3_prep
1c1c0 61 72 65 5f 76 32 28 29 5d 20 69 73 20 75 73 65  are_v2()] is use
1c1d0 64 20 74 6f 20 70 72 65 70 61 72 65 20 61 20 73  d to prepare a s
1c1e0 74 61 74 65 6d 65 6e 74 2c 20 74 68 65 0a 2a 2a  tatement, the.**
1c1f0 20 73 74 61 74 65 6d 65 6e 74 20 6d 69 67 68 74   statement might
1c200 20 62 65 20 72 65 2d 70 72 65 70 61 72 65 64 20   be re-prepared 
1c210 64 75 72 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  during [sqlite3_
1c220 73 74 65 70 28 29 5d 20 64 75 65 20 74 6f 20 61  step()] due to a
1c230 20 0a 2a 2a 20 73 63 68 65 6d 61 20 63 68 61 6e   .** schema chan
1c240 67 65 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20  ge.  Hence, the 
1c250 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75  application shou
1c260 6c 64 20 65 6e 73 75 72 65 20 74 68 61 74 20 74  ld ensure that t
1c270 68 65 0a 2a 2a 20 63 6f 72 72 65 63 74 20 61 75  he.** correct au
1c280 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1c290 6b 20 72 65 6d 61 69 6e 73 20 69 6e 20 70 6c 61  k remains in pla
1c2a0 63 65 20 64 75 72 69 6e 67 20 74 68 65 20 5b 73  ce during the [s
1c2b0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a  qlite3_step()]..
1c2c0 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68 61 74  **.** ^Note that
1c2d0 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
1c2e0 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
1c2f0 6b 65 64 20 6f 6e 6c 79 20 64 75 72 69 6e 67 0a  ked only during.
1c300 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
1c310 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61  are()] or its va
1c320 72 69 61 6e 74 73 2e 20 20 41 75 74 68 6f 72 69  riants.  Authori
1c330 7a 61 74 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a 2a  zation is not.**
1c340 20 70 65 72 66 6f 72 6d 65 64 20 64 75 72 69 6e   performed durin
1c350 67 20 73 74 61 74 65 6d 65 6e 74 20 65 76 61 6c  g statement eval
1c360 75 61 74 69 6f 6e 20 69 6e 20 5b 73 71 6c 69 74  uation in [sqlit
1c370 65 33 5f 73 74 65 70 28 29 5d 2c 20 75 6e 6c 65  e3_step()], unle
1c380 73 73 0a 2a 2a 20 61 73 20 73 74 61 74 65 64 20  ss.** as stated 
1c390 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73 20  in the previous 
1c3a0 70 61 72 61 67 72 61 70 68 2c 20 73 71 6c 69 74  paragraph, sqlit
1c3b0 65 33 5f 73 74 65 70 28 29 20 69 6e 76 6f 6b 65  e3_step() invoke
1c3c0 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 65  s.** sqlite3_pre
1c3d0 70 61 72 65 5f 76 32 28 29 20 74 6f 20 72 65 70  pare_v2() to rep
1c3e0 72 65 70 61 72 65 20 61 20 73 74 61 74 65 6d 65  repare a stateme
1c3f0 6e 74 20 61 66 74 65 72 20 61 20 73 63 68 65 6d  nt after a schem
1c400 61 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a 69 6e 74  a change..*/.int
1c410 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74   sqlite3_set_aut
1c420 68 6f 72 69 7a 65 72 28 0a 20 20 73 71 6c 69 74  horizer(.  sqlit
1c430 65 33 2a 2c 0a 20 20 69 6e 74 20 28 2a 78 41 75  e3*,.  int (*xAu
1c440 74 68 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  th)(void*,int,co
1c450 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20  nst char*,const 
1c460 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72  char*,const char
1c470 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 0a  *,const char*),.
1c480 20 20 76 6f 69 64 20 2a 70 55 73 65 72 44 61 74    void *pUserDat
1c490 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  a.);../*.** CAPI
1c4a0 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72  3REF: Authorizer
1c4b0 20 52 65 74 75 72 6e 20 43 6f 64 65 73 0a 2a 2a   Return Codes.**
1c4c0 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33  .** The [sqlite3
1c4d0 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20  _set_authorizer 
1c4e0 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  | authorizer cal
1c4f0 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 5d 20  lback function] 
1c500 6d 75 73 74 0a 2a 2a 20 72 65 74 75 72 6e 20 65  must.** return e
1c510 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b  ither [SQLITE_OK
1c520 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 73  ] or one of thes
1c530 65 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20  e two constants 
1c540 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 73  in order.** to s
1c550 69 67 6e 61 6c 20 53 51 4c 69 74 65 20 77 68 65  ignal SQLite whe
1c560 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20  ther or not the 
1c570 61 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74  action is permit
1c580 74 65 64 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a  ted.  See the.**
1c590 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
1c5a0 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f  thorizer | autho
1c5b0 72 69 7a 65 72 20 64 6f 63 75 6d 65 6e 74 61 74  rizer documentat
1c5c0 69 6f 6e 5d 20 66 6f 72 20 61 64 64 69 74 69 6f  ion] for additio
1c5d0 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  nal.** informati
1c5e0 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74  on..**.** Note t
1c5f0 68 61 74 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52  hat SQLITE_IGNOR
1c600 45 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20 61  E is also used a
1c610 73 20 61 20 5b 53 51 4c 49 54 45 5f 52 4f 4c 4c  s a [SQLITE_ROLL
1c620 42 41 43 4b 20 7c 20 72 65 74 75 72 6e 20 63 6f  BACK | return co
1c630 64 65 5d 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20  de].** from the 
1c640 5b 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 6f 6e  [sqlite3_vtab_on
1c650 5f 63 6f 6e 66 6c 69 63 74 28 29 5d 20 69 6e 74  _conflict()] int
1c660 65 72 66 61 63 65 2e 0a 2a 2f 0a 23 64 65 66 69  erface..*/.#defi
1c670 6e 65 20 53 51 4c 49 54 45 5f 44 45 4e 59 20 20  ne SQLITE_DENY  
1c680 20 31 20 20 20 2f 2a 20 41 62 6f 72 74 20 74 68   1   /* Abort th
1c690 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
1c6a0 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 2a 2f  with an error */
1c6b0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1c6c0 49 47 4e 4f 52 45 20 32 20 20 20 2f 2a 20 44 6f  IGNORE 2   /* Do
1c6d0 6e 27 74 20 61 6c 6c 6f 77 20 61 63 63 65 73 73  n't allow access
1c6e0 2c 20 62 75 74 20 64 6f 6e 27 74 20 67 65 6e 65  , but don't gene
1c6f0 72 61 74 65 20 61 6e 20 65 72 72 6f 72 20 2a 2f  rate an error */
1c700 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1c710 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 41 63 74  : Authorizer Act
1c720 69 6f 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20  ion Codes.**.** 
1c730 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  The [sqlite3_set
1c740 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 20 69  _authorizer()] i
1c750 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65  nterface registe
1c760 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75  rs a callback fu
1c770 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 69  nction.** that i
1c780 73 20 69 6e 76 6f 6b 65 64 20 74 6f 20 61 75 74  s invoked to aut
1c790 68 6f 72 69 7a 65 20 63 65 72 74 61 69 6e 20 53  horize certain S
1c7a0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 63 74  QL statement act
1c7b0 69 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a 20 73 65  ions.  The.** se
1c7c0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74  cond parameter t
1c7d0 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69  o the callback i
1c7e0 73 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 64  s an integer cod
1c7f0 65 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73  e that specifies
1c800 0a 2a 2a 20 77 68 61 74 20 61 63 74 69 6f 6e 20  .** what action 
1c810 69 73 20 62 65 69 6e 67 20 61 75 74 68 6f 72 69  is being authori
1c820 7a 65 64 2e 20 20 54 68 65 73 65 20 61 72 65 20  zed.  These are 
1c830 74 68 65 20 69 6e 74 65 67 65 72 20 61 63 74 69  the integer acti
1c840 6f 6e 20 63 6f 64 65 73 20 74 68 61 74 0a 2a 2a  on codes that.**
1c850 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
1c860 63 61 6c 6c 62 61 63 6b 20 6d 61 79 20 62 65 20  callback may be 
1c870 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  passed..**.** Th
1c880 65 73 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20  ese action code 
1c890 76 61 6c 75 65 73 20 73 69 67 6e 69 66 79 20 77  values signify w
1c8a0 68 61 74 20 6b 69 6e 64 20 6f 66 20 6f 70 65 72  hat kind of oper
1c8b0 61 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 0a 2a  ation is to be.*
1c8c0 2a 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54  * authorized.  T
1c8d0 68 65 20 33 72 64 20 61 6e 64 20 34 74 68 20 70  he 3rd and 4th p
1c8e0 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 65  arameters to the
1c8f0 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a   authorization.*
1c900 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  * callback funct
1c910 69 6f 6e 20 77 69 6c 6c 20 62 65 20 70 61 72 61  ion will be para
1c920 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c 4c 20 64  meters or NULL d
1c930 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68 69 63  epending on whic
1c940 68 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 63 6f  h of these.** co
1c950 64 65 73 20 69 73 20 75 73 65 64 20 61 73 20 74  des is used as t
1c960 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
1c970 74 65 72 2e 20 20 5e 28 54 68 65 20 35 74 68 20  ter.  ^(The 5th 
1c980 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
1c990 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 63  .** authorizer c
1c9a0 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e  allback is the n
1c9b0 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62  ame of the datab
1c9c0 61 73 65 20 28 22 6d 61 69 6e 22 2c 20 22 74 65  ase ("main", "te
1c9d0 6d 70 22 2c 0a 2a 2a 20 65 74 63 2e 29 20 69 66  mp",.** etc.) if
1c9e0 20 61 70 70 6c 69 63 61 62 6c 65 2e 29 5e 20 20   applicable.)^  
1c9f0 5e 54 68 65 20 36 74 68 20 70 61 72 61 6d 65 74  ^The 6th paramet
1ca00 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72  er to the author
1ca10 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a  izer callback.**
1ca20 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
1ca30 74 68 65 20 69 6e 6e 65 72 2d 6d 6f 73 74 20 74  the inner-most t
1ca40 72 69 67 67 65 72 20 6f 72 20 76 69 65 77 20 74  rigger or view t
1ca50 68 61 74 20 69 73 20 72 65 73 70 6f 6e 73 69 62  hat is responsib
1ca60 6c 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61 63  le for.** the ac
1ca70 63 65 73 73 20 61 74 74 65 6d 70 74 20 6f 72 20  cess attempt or 
1ca80 4e 55 4c 4c 20 69 66 20 74 68 69 73 20 61 63 63  NULL if this acc
1ca90 65 73 73 20 61 74 74 65 6d 70 74 20 69 73 20 64  ess attempt is d
1caa0 69 72 65 63 74 6c 79 20 66 72 6f 6d 0a 2a 2a 20  irectly from.** 
1cab0 74 6f 70 2d 6c 65 76 65 6c 20 53 51 4c 20 63 6f  top-level SQL co
1cac0 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a  de..*/./********
1cad0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1cae0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1caf0 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a  *** 3rd ********
1cb00 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a 2a 2a  **** 4th *******
1cb10 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ****/.#define SQ
1cb20 4c 49 54 45 5f 43 52 45 41 54 45 5f 49 4e 44 45  LITE_CREATE_INDE
1cb30 58 20 20 20 20 20 20 20 20 20 20 31 20 20 20 2f  X          1   /
1cb40 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20  * Index Name    
1cb50 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
1cb60 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1cb70 49 54 45 5f 43 52 45 41 54 45 5f 54 41 42 4c 45  ITE_CREATE_TABLE
1cb80 20 20 20 20 20 20 20 20 20 20 32 20 20 20 2f 2a            2   /*
1cb90 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1cba0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1cbb0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1cbc0 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 49  TE_CREATE_TEMP_I
1cbd0 4e 44 45 58 20 20 20 20 20 33 20 20 20 2f 2a 20  NDEX     3   /* 
1cbe0 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20  Index Name      
1cbf0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1cc00 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1cc10 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 41  E_CREATE_TEMP_TA
1cc20 42 4c 45 20 20 20 20 20 34 20 20 20 2f 2a 20 54  BLE     4   /* T
1cc30 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
1cc40 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1cc50 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1cc60 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 52 49  _CREATE_TEMP_TRI
1cc70 47 47 45 52 20 20 20 35 20 20 20 2f 2a 20 54 72  GGER   5   /* Tr
1cc80 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61  igger Name    Ta
1cc90 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
1cca0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1ccb0 43 52 45 41 54 45 5f 54 45 4d 50 5f 56 49 45 57  CREATE_TEMP_VIEW
1ccc0 20 20 20 20 20 20 36 20 20 20 2f 2a 20 56 69 65        6   /* Vie
1ccd0 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c  w Name       NUL
1cce0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
1ccf0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
1cd00 52 45 41 54 45 5f 54 52 49 47 47 45 52 20 20 20  REATE_TRIGGER   
1cd10 20 20 20 20 20 37 20 20 20 2f 2a 20 54 72 69 67       7   /* Trig
1cd20 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c  ger Name    Tabl
1cd30 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
1cd40 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
1cd50 45 41 54 45 5f 56 49 45 57 20 20 20 20 20 20 20  EATE_VIEW       
1cd60 20 20 20 20 38 20 20 20 2f 2a 20 56 69 65 77 20      8   /* View 
1cd70 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20  Name       NULL 
1cd80 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
1cd90 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4c  efine SQLITE_DEL
1cda0 45 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20  ETE             
1cdb0 20 20 20 39 20 20 20 2f 2a 20 54 61 62 6c 65 20     9   /* Table 
1cdc0 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
1cdd0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
1cde0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
1cdf0 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20  _INDEX          
1ce00 20 31 30 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e   10   /* Index N
1ce10 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e  ame      Table N
1ce20 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
1ce30 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
1ce40 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 20  TABLE           
1ce50 31 31 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  11   /* Table Na
1ce60 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
1ce70 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
1ce80 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
1ce90 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 20 31  EMP_INDEX      1
1cea0 32 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d  2   /* Index Nam
1ceb0 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  e      Table Nam
1cec0 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
1ced0 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45  e SQLITE_DROP_TE
1cee0 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 20 31 33  MP_TABLE      13
1cef0 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
1cf00 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1cf10 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1cf20 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d   SQLITE_DROP_TEM
1cf30 50 5f 54 52 49 47 47 45 52 20 20 20 20 31 34 20  P_TRIGGER    14 
1cf40 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d    /* Trigger Nam
1cf50 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20  e    Table Name 
1cf60 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1cf70 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50  SQLITE_DROP_TEMP
1cf80 5f 56 49 45 57 20 20 20 20 20 20 20 31 35 20 20  _VIEW       15  
1cf90 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20   /* View Name   
1cfa0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
1cfb0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1cfc0 51 4c 49 54 45 5f 44 52 4f 50 5f 54 52 49 47 47  QLITE_DROP_TRIGG
1cfd0 45 52 20 20 20 20 20 20 20 20 20 31 36 20 20 20  ER         16   
1cfe0 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20  /* Trigger Name 
1cff0 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
1d000 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1d010 4c 49 54 45 5f 44 52 4f 50 5f 56 49 45 57 20 20  LITE_DROP_VIEW  
1d020 20 20 20 20 20 20 20 20 20 20 31 37 20 20 20 2f            17   /
1d030 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20  * View Name     
1d040 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1d050 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1d060 49 54 45 5f 49 4e 53 45 52 54 20 20 20 20 20 20  ITE_INSERT      
1d070 20 20 20 20 20 20 20 20 20 31 38 20 20 20 2f 2a           18   /*
1d080 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1d090 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1d0a0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1d0b0 54 45 5f 50 52 41 47 4d 41 20 20 20 20 20 20 20  TE_PRAGMA       
1d0c0 20 20 20 20 20 20 20 20 31 39 20 20 20 2f 2a 20          19   /* 
1d0d0 50 72 61 67 6d 61 20 4e 61 6d 65 20 20 20 20 20  Pragma Name     
1d0e0 31 73 74 20 61 72 67 20 6f 72 20 4e 55 4c 4c 20  1st arg or NULL 
1d0f0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1d100 45 5f 52 45 41 44 20 20 20 20 20 20 20 20 20 20  E_READ          
1d110 20 20 20 20 20 20 20 32 30 20 20 20 2f 2a 20 54         20   /* T
1d120 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43  able Name      C
1d130 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a  olumn Name     *
1d140 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1d150 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20 20 20  _SELECT         
1d160 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4e 55        21   /* NU
1d170 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 4e 55  LL            NU
1d180 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
1d190 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1d1a0 54 52 41 4e 53 41 43 54 49 4f 4e 20 20 20 20 20  TRANSACTION     
1d1b0 20 20 20 20 20 32 32 20 20 20 2f 2a 20 4f 70 65       22   /* Ope
1d1c0 72 61 74 69 6f 6e 20 20 20 20 20 20 20 4e 55 4c  ration       NUL
1d1d0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
1d1e0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
1d1f0 50 44 41 54 45 20 20 20 20 20 20 20 20 20 20 20  PDATE           
1d200 20 20 20 20 32 33 20 20 20 2f 2a 20 54 61 62 6c      23   /* Tabl
1d210 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75  e Name      Colu
1d220 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23  mn Name     */.#
1d230 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 54  define SQLITE_AT
1d240 54 41 43 48 20 20 20 20 20 20 20 20 20 20 20 20  TACH            
1d250 20 20 20 32 34 20 20 20 2f 2a 20 46 69 6c 65 6e     24   /* Filen
1d260 61 6d 65 20 20 20 20 20 20 20 20 4e 55 4c 4c 20  ame        NULL 
1d270 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
1d280 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 54  efine SQLITE_DET
1d290 41 43 48 20 20 20 20 20 20 20 20 20 20 20 20 20  ACH             
1d2a0 20 20 32 35 20 20 20 2f 2a 20 44 61 74 61 62 61    25   /* Databa
1d2b0 73 65 20 4e 61 6d 65 20 20 20 4e 55 4c 4c 20 20  se Name   NULL  
1d2c0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
1d2d0 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4c 54 45  fine SQLITE_ALTE
1d2e0 52 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20  R_TABLE         
1d2f0 20 32 36 20 20 20 2f 2a 20 44 61 74 61 62 61 73   26   /* Databas
1d300 65 20 4e 61 6d 65 20 20 20 54 61 62 6c 65 20 4e  e Name   Table N
1d310 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
1d320 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 49 4e 44  ine SQLITE_REIND
1d330 45 58 20 20 20 20 20 20 20 20 20 20 20 20 20 20  EX              
1d340 32 37 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61  27   /* Index Na
1d350 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
1d360 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
1d370 6e 65 20 53 51 4c 49 54 45 5f 41 4e 41 4c 59 5a  ne SQLITE_ANALYZ
1d380 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32  E              2
1d390 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  8   /* Table Nam
1d3a0 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
1d3b0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
1d3c0 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
1d3d0 56 54 41 42 4c 45 20 20 20 20 20 20 20 20 32 39  VTABLE        29
1d3e0 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
1d3f0 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d        Module Nam
1d400 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65  e     */.#define
1d410 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 54 41   SQLITE_DROP_VTA
1d420 42 4c 45 20 20 20 20 20 20 20 20 20 20 33 30 20  BLE          30 
1d430 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
1d440 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65       Module Name
1d450 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1d460 53 51 4c 49 54 45 5f 46 55 4e 43 54 49 4f 4e 20  SQLITE_FUNCTION 
1d470 20 20 20 20 20 20 20 20 20 20 20 20 33 31 20 20              31  
1d480 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20   /* NULL        
1d490 20 20 20 20 46 75 6e 63 74 69 6f 6e 20 4e 61 6d      Function Nam
1d4a0 65 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  e   */.#define S
1d4b0 51 4c 49 54 45 5f 53 41 56 45 50 4f 49 4e 54 20  QLITE_SAVEPOINT 
1d4c0 20 20 20 20 20 20 20 20 20 20 20 33 32 20 20 20             32   
1d4d0 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20  /* Operation    
1d4e0 20 20 20 53 61 76 65 70 6f 69 6e 74 20 4e 61 6d     Savepoint Nam
1d4f0 65 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  e  */.#define SQ
1d500 4c 49 54 45 5f 43 4f 50 59 20 20 20 20 20 20 20  LITE_COPY       
1d510 20 20 20 20 20 20 20 20 20 20 20 30 20 20 20 2f             0   /
1d520 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 73 65 64  * No longer used
1d530 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
1d540 52 45 46 3a 20 54 72 61 63 69 6e 67 20 41 6e 64  REF: Tracing And
1d550 20 50 72 6f 66 69 6c 69 6e 67 20 46 75 6e 63 74   Profiling Funct
1d560 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ions.**.** These
1d570 20 72 6f 75 74 69 6e 65 73 20 72 65 67 69 73 74   routines regist
1d580 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  er callback func
1d590 74 69 6f 6e 73 20 74 68 61 74 20 63 61 6e 20 62  tions that can b
1d5a0 65 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 72  e used for.** tr
1d5b0 61 63 69 6e 67 20 61 6e 64 20 70 72 6f 66 69 6c  acing and profil
1d5c0 69 6e 67 20 74 68 65 20 65 78 65 63 75 74 69 6f  ing the executio
1d5d0 6e 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65  n of SQL stateme
1d5e0 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  nts..**.** ^The 
1d5f0 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
1d600 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20  n registered by 
1d610 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20  sqlite3_trace() 
1d620 69 73 20 69 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a  is invoked at.**
1d630 20 76 61 72 69 6f 75 73 20 74 69 6d 65 73 20 77   various times w
1d640 68 65 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65  hen an SQL state
1d650 6d 65 6e 74 20 69 73 20 62 65 69 6e 67 20 72 75  ment is being ru
1d660 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 74  n by [sqlite3_st
1d670 65 70 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20 73  ep()]..** ^The s
1d680 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 63  qlite3_trace() c
1d690 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
1d6a0 65 64 20 77 69 74 68 20 61 20 55 54 46 2d 38 20  ed with a UTF-8 
1d6b0 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65  rendering of the
1d6c0 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  .** SQL statemen
1d6d0 74 20 74 65 78 74 20 61 73 20 74 68 65 20 73 74  t text as the st
1d6e0 61 74 65 6d 65 6e 74 20 66 69 72 73 74 20 62 65  atement first be
1d6f0 67 69 6e 73 20 65 78 65 63 75 74 69 6e 67 2e 0a  gins executing..
1d700 2a 2a 20 5e 28 41 64 64 69 74 69 6f 6e 61 6c 20  ** ^(Additional 
1d710 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20  sqlite3_trace() 
1d720 63 61 6c 6c 62 61 63 6b 73 20 6d 69 67 68 74 20  callbacks might 
1d730 6f 63 63 75 72 0a 2a 2a 20 61 73 20 65 61 63 68  occur.** as each
1d740 20 74 72 69 67 67 65 72 65 64 20 73 75 62 70 72   triggered subpr
1d750 6f 67 72 61 6d 20 69 73 20 65 6e 74 65 72 65 64  ogram is entered
1d760 2e 20 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 73  .  The callbacks
1d770 20 66 6f 72 20 74 72 69 67 67 65 72 73 0a 2a 2a   for triggers.**
1d780 20 63 6f 6e 74 61 69 6e 20 61 20 55 54 46 2d 38   contain a UTF-8
1d790 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 74 68 61   SQL comment tha
1d7a0 74 20 69 64 65 6e 74 69 66 69 65 73 20 74 68 65  t identifies the
1d7b0 20 74 72 69 67 67 65 72 2e 29 5e 0a 2a 2a 0a 2a   trigger.)^.**.*
1d7c0 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20  * ^The callback 
1d7d0 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65  function registe
1d7e0 72 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 70  red by sqlite3_p
1d7f0 72 6f 66 69 6c 65 28 29 20 69 73 20 69 6e 76 6f  rofile() is invo
1d800 6b 65 64 0a 2a 2a 20 61 73 20 65 61 63 68 20 53  ked.** as each S
1d810 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 69 6e  QL statement fin
1d820 69 73 68 65 73 2e 20 20 5e 54 68 65 20 70 72 6f  ishes.  ^The pro
1d830 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f  file callback co
1d840 6e 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20 6f 72  ntains.** the or
1d850 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74  iginal statement
1d860 20 74 65 78 74 20 61 6e 64 20 61 6e 20 65 73 74   text and an est
1d870 69 6d 61 74 65 20 6f 66 20 77 61 6c 6c 2d 63 6c  imate of wall-cl
1d880 6f 63 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66 20 68  ock time.** of h
1d890 6f 77 20 6c 6f 6e 67 20 74 68 61 74 20 73 74 61  ow long that sta
1d8a0 74 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 72  tement took to r
1d8b0 75 6e 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 6c  un.  ^The profil
1d8c0 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 69  e callback.** ti
1d8d0 6d 65 20 69 73 20 69 6e 20 75 6e 69 74 73 20 6f  me is in units o
1d8e0 66 20 6e 61 6e 6f 73 65 63 6f 6e 64 73 2c 20 68  f nanoseconds, h
1d8f0 6f 77 65 76 65 72 20 74 68 65 20 63 75 72 72 65  owever the curre
1d900 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  nt implementatio
1d910 6e 0a 2a 2a 20 69 73 20 6f 6e 6c 79 20 63 61 70  n.** is only cap
1d920 61 62 6c 65 20 6f 66 20 6d 69 6c 6c 69 73 65 63  able of millisec
1d930 6f 6e 64 20 72 65 73 6f 6c 75 74 69 6f 6e 20 73  ond resolution s
1d940 6f 20 74 68 65 20 73 69 78 20 6c 65 61 73 74 20  o the six least 
1d950 73 69 67 6e 69 66 69 63 61 6e 74 0a 2a 2a 20 64  significant.** d
1d960 69 67 69 74 73 20 69 6e 20 74 68 65 20 74 69 6d  igits in the tim
1d970 65 20 61 72 65 20 6d 65 61 6e 69 6e 67 6c 65 73  e are meaningles
1d980 73 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69  s.  Future versi
1d990 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a  ons of SQLite.**
1d9a0 20 6d 69 67 68 74 20 70 72 6f 76 69 64 65 20 67   might provide g
1d9b0 72 65 61 74 65 72 20 72 65 73 6f 6c 75 74 69 6f  reater resolutio
1d9c0 6e 20 6f 6e 20 74 68 65 20 70 72 6f 66 69 6c 65  n on the profile
1d9d0 72 20 63 61 6c 6c 62 61 63 6b 2e 20 20 54 68 65  r callback.  The
1d9e0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 6f 66  .** sqlite3_prof
1d9f0 69 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69  ile() function i
1da00 73 20 63 6f 6e 73 69 64 65 72 65 64 20 65 78 70  s considered exp
1da10 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73  erimental and is
1da20 0a 2a 2a 20 73 75 62 6a 65 63 74 20 74 6f 20 63  .** subject to c
1da30 68 61 6e 67 65 20 69 6e 20 66 75 74 75 72 65 20  hange in future 
1da40 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
1da50 74 65 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c  te..*/.void *sql
1da60 69 74 65 33 5f 74 72 61 63 65 28 73 71 6c 69 74  ite3_trace(sqlit
1da70 65 33 2a 2c 20 76 6f 69 64 28 2a 78 54 72 61 63  e3*, void(*xTrac
1da80 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63  e)(void*,const c
1da90 68 61 72 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 53  har*), void*);.S
1daa0 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54  QLITE_EXPERIMENT
1dab0 41 4c 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  AL void *sqlite3
1dac0 5f 70 72 6f 66 69 6c 65 28 73 71 6c 69 74 65 33  _profile(sqlite3
1dad0 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78 50 72 6f  *,.   void(*xPro
1dae0 66 69 6c 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73  file)(void*,cons
1daf0 74 20 63 68 61 72 2a 2c 73 71 6c 69 74 65 33 5f  t char*,sqlite3_
1db00 75 69 6e 74 36 34 29 2c 20 76 6f 69 64 2a 29 3b  uint64), void*);
1db10 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1db20 3a 20 51 75 65 72 79 20 50 72 6f 67 72 65 73 73  : Query Progress
1db30 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a   Callbacks.**.**
1db40 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72   ^The sqlite3_pr
1db50 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 44  ogress_handler(D
1db60 2c 4e 2c 58 2c 50 29 20 69 6e 74 65 72 66 61 63  ,N,X,P) interfac
1db70 65 20 63 61 75 73 65 73 20 74 68 65 20 63 61 6c  e causes the cal
1db80 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f  lback.** functio
1db90 6e 20 58 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65  n X to be invoke
1dba0 64 20 70 65 72 69 6f 64 69 63 61 6c 6c 79 20 64  d periodically d
1dbb0 75 72 69 6e 67 20 6c 6f 6e 67 20 72 75 6e 6e 69  uring long runni
1dbc0 6e 67 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b  ng calls to.** [
1dbd0 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c  sqlite3_exec()],
1dbe0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
1dbf0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 67  ] and [sqlite3_g
1dc00 65 74 5f 74 61 62 6c 65 28 29 5d 20 66 6f 72 0a  et_table()] for.
1dc10 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ** database conn
1dc20 65 63 74 69 6f 6e 20 44 2e 20 20 41 6e 20 65 78  ection D.  An ex
1dc30 61 6d 70 6c 65 20 75 73 65 20 66 6f 72 20 74 68  ample use for th
1dc40 69 73 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  is.** interface 
1dc50 69 73 20 74 6f 20 6b 65 65 70 20 61 20 47 55 49  is to keep a GUI
1dc60 20 75 70 64 61 74 65 64 20 64 75 72 69 6e 67 20   updated during 
1dc70 61 20 6c 61 72 67 65 20 71 75 65 72 79 2e 0a 2a  a large query..*
1dc80 2a 0a 2a 2a 20 5e 54 68 65 20 70 61 72 61 6d 65  *.** ^The parame
1dc90 74 65 72 20 50 20 69 73 20 70 61 73 73 65 64 20  ter P is passed 
1dca0 74 68 72 6f 75 67 68 20 61 73 20 74 68 65 20 6f  through as the o
1dcb0 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20 74 6f  nly parameter to
1dcc0 20 74 68 65 20 0a 2a 2a 20 63 61 6c 6c 62 61 63   the .** callbac
1dcd0 6b 20 66 75 6e 63 74 69 6f 6e 20 58 2e 20 20 5e  k function X.  ^
1dce0 54 68 65 20 70 61 72 61 6d 65 74 65 72 20 4e 20  The parameter N 
1dcf0 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  is the number of
1dd00 20 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 6d 61   .** [virtual ma
1dd10 63 68 69 6e 65 20 69 6e 73 74 72 75 63 74 69 6f  chine instructio
1dd20 6e 73 5d 20 74 68 61 74 20 61 72 65 20 65 76 61  ns] that are eva
1dd30 6c 75 61 74 65 64 20 62 65 74 77 65 65 6e 20 73  luated between s
1dd40 75 63 63 65 73 73 69 76 65 0a 2a 2a 20 69 6e 76  uccessive.** inv
1dd50 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  ocations of the 
1dd60 63 61 6c 6c 62 61 63 6b 20 58 2e 0a 2a 2a 0a 2a  callback X..**.*
1dd70 2a 20 5e 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65  * ^Only a single
1dd80 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65   progress handle
1dd90 72 20 6d 61 79 20 62 65 20 64 65 66 69 6e 65 64  r may be defined
1dda0 20 61 74 20 6f 6e 65 20 74 69 6d 65 20 70 65 72   at one time per
1ddb0 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
1ddc0 6e 6e 65 63 74 69 6f 6e 5d 3b 20 73 65 74 74 69  nnection]; setti
1ddd0 6e 67 20 61 20 6e 65 77 20 70 72 6f 67 72 65 73  ng a new progres
1dde0 73 20 68 61 6e 64 6c 65 72 20 63 61 6e 63 65 6c  s handler cancel
1ddf0 73 20 74 68 65 0a 2a 2a 20 6f 6c 64 20 6f 6e 65  s the.** old one
1de00 2e 20 20 5e 53 65 74 74 69 6e 67 20 70 61 72 61  .  ^Setting para
1de10 6d 65 74 65 72 20 58 20 74 6f 20 4e 55 4c 4c 20  meter X to NULL 
1de20 64 69 73 61 62 6c 65 73 20 74 68 65 20 70 72 6f  disables the pro
1de30 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a  gress handler..*
1de40 2a 20 5e 54 68 65 20 70 72 6f 67 72 65 73 73 20  * ^The progress 
1de50 68 61 6e 64 6c 65 72 20 69 73 20 61 6c 73 6f 20  handler is also 
1de60 64 69 73 61 62 6c 65 64 20 62 79 20 73 65 74 74  disabled by sett
1de70 69 6e 67 20 4e 20 74 6f 20 61 20 76 61 6c 75 65  ing N to a value
1de80 20 6c 65 73 73 0a 2a 2a 20 74 68 61 6e 20 31 2e   less.** than 1.
1de90 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 70  .**.** ^If the p
1dea0 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b  rogress callback
1deb0 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72   returns non-zer
1dec0 6f 2c 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e  o, the operation
1ded0 20 69 73 0a 2a 2a 20 69 6e 74 65 72 72 75 70 74   is.** interrupt
1dee0 65 64 2e 20 20 54 68 69 73 20 66 65 61 74 75 72  ed.  This featur
1def0 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  e can be used to
1df00 20 69 6d 70 6c 65 6d 65 6e 74 20 61 0a 2a 2a 20   implement a.** 
1df10 22 43 61 6e 63 65 6c 22 20 62 75 74 74 6f 6e 20  "Cancel" button 
1df20 6f 6e 20 61 20 47 55 49 20 70 72 6f 67 72 65 73  on a GUI progres
1df30 73 20 64 69 61 6c 6f 67 20 62 6f 78 2e 0a 2a 2a  s dialog box..**
1df40 0a 2a 2a 20 54 68 65 20 70 72 6f 67 72 65 73 73  .** The progress
1df50 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63   handler callbac
1df60 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e  k must not do an
1df70 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c  ything that will
1df80 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64   modify.** the d
1df90 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1dfa0 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20  on that invoked 
1dfb0 74 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e  the progress han
1dfc0 64 6c 65 72 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68  dler..** Note th
1dfd0 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  at [sqlite3_prep
1dfe0 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73  are_v2()] and [s
1dff0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62  qlite3_step()] b
1e000 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72  oth modify their
1e010 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e  .** database con
1e020 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65  nections for the
1e030 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64   meaning of "mod
1e040 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72  ify" in this par
1e050 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2f 0a 76 6f  agraph..**.*/.vo
1e060 69 64 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72  id sqlite3_progr
1e070 65 73 73 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69  ess_handler(sqli
1e080 74 65 33 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 2a  te3*, int, int(*
1e090 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29  )(void*), void*)
1e0a0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1e0b0 46 3a 20 4f 70 65 6e 69 6e 67 20 41 20 4e 65 77  F: Opening A New
1e0c0 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63   Database Connec
1e0d0 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  tion.**.** ^Thes
1e0e0 65 20 72 6f 75 74 69 6e 65 73 20 6f 70 65 6e 20  e routines open 
1e0f0 61 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62 61  an SQLite databa
1e100 73 65 20 66 69 6c 65 20 61 73 20 73 70 65 63 69  se file as speci
1e110 66 69 65 64 20 62 79 20 74 68 65 20 0a 2a 2a 20  fied by the .** 
1e120 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e  filename argumen
1e130 74 2e 20 5e 54 68 65 20 66 69 6c 65 6e 61 6d 65  t. ^The filename
1e140 20 61 72 67 75 6d 65 6e 74 20 69 73 20 69 6e 74   argument is int
1e150 65 72 70 72 65 74 65 64 20 61 73 20 55 54 46 2d  erpreted as UTF-
1e160 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  8 for.** sqlite3
1e170 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69  _open() and sqli
1e180 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 61 6e  te3_open_v2() an
1e190 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 74  d as UTF-16 in t
1e1a0 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 0a 2a  he native byte.*
1e1b0 2a 20 6f 72 64 65 72 20 66 6f 72 20 73 71 6c 69  * order for sqli
1e1c0 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 20 5e 28  te3_open16(). ^(
1e1d0 41 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  A [database conn
1e1e0 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 69  ection] handle i
1e1f0 73 20 75 73 75 61 6c 6c 79 0a 2a 2a 20 72 65 74  s usually.** ret
1e200 75 72 6e 65 64 20 69 6e 20 2a 70 70 44 62 2c 20  urned in *ppDb, 
1e210 65 76 65 6e 20 69 66 20 61 6e 20 65 72 72 6f 72  even if an error
1e220 20 6f 63 63 75 72 73 2e 20 20 54 68 65 20 6f 6e   occurs.  The on
1e230 6c 79 20 65 78 63 65 70 74 69 6f 6e 20 69 73 20  ly exception is 
1e240 74 68 61 74 0a 2a 2a 20 69 66 20 53 51 4c 69 74  that.** if SQLit
1e250 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61  e is unable to a
1e260 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74  llocate memory t
1e270 6f 20 68 6f 6c 64 20 74 68 65 20 5b 73 71 6c 69  o hold the [sqli
1e280 74 65 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a 20  te3] object,.** 
1e290 61 20 4e 55 4c 4c 20 77 69 6c 6c 20 62 65 20 77  a NULL will be w
1e2a0 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 70 44  ritten into *ppD
1e2b0 62 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 70  b instead of a p
1e2c0 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73  ointer to the [s
1e2d0 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65 63  qlite3].** objec
1e2e0 74 2e 29 5e 20 5e 28 49 66 20 74 68 65 20 64 61  t.)^ ^(If the da
1e2f0 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
1e300 20 28 61 6e 64 2f 6f 72 20 63 72 65 61 74 65 64   (and/or created
1e310 29 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2c 20  ) successfully, 
1e320 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  then.** [SQLITE_
1e330 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  OK] is returned.
1e340 20 20 4f 74 68 65 72 77 69 73 65 20 61 6e 20 5b    Otherwise an [
1e350 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72  error code] is r
1e360 65 74 75 72 6e 65 64 2e 29 5e 20 5e 54 68 65 0a  eturned.)^ ^The.
1e370 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  ** [sqlite3_errm
1e380 73 67 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  sg()] or [sqlite
1e390 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 20 72 6f  3_errmsg16()] ro
1e3a0 75 74 69 6e 65 73 20 63 61 6e 20 62 65 20 75 73  utines can be us
1e3b0 65 64 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20  ed to obtain.** 
1e3c0 61 6e 20 45 6e 67 6c 69 73 68 20 6c 61 6e 67 75  an English langu
1e3d0 61 67 65 20 64 65 73 63 72 69 70 74 69 6f 6e 20  age description 
1e3e0 6f 66 20 74 68 65 20 65 72 72 6f 72 20 66 6f 6c  of the error fol
1e3f0 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 75 72 65  lowing a failure
1e400 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68   of any.** of th
1e410 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  e sqlite3_open()
1e420 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a   routines..**.**
1e430 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 65 6e   ^The default en
1e440 63 6f 64 69 6e 67 20 66 6f 72 20 74 68 65 20 64  coding for the d
1e450 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20  atabase will be 
1e460 55 54 46 2d 38 20 69 66 0a 2a 2a 20 73 71 6c 69  UTF-8 if.** sqli
1e470 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71  te3_open() or sq
1e480 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
1e490 69 73 20 63 61 6c 6c 65 64 20 61 6e 64 0a 2a 2a  is called and.**
1e4a0 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e   UTF-16 in the n
1e4b0 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
1e4c0 20 69 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   if sqlite3_open
1e4d0 31 36 28 29 20 69 73 20 75 73 65 64 2e 0a 2a 2a  16() is used..**
1e4e0 0a 2a 2a 20 57 68 65 74 68 65 72 20 6f 72 20 6e  .** Whether or n
1e4f0 6f 74 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75  ot an error occu
1e500 72 73 20 77 68 65 6e 20 69 74 20 69 73 20 6f 70  rs when it is op
1e510 65 6e 65 64 2c 20 72 65 73 6f 75 72 63 65 73 0a  ened, resources.
1e520 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ** associated wi
1e530 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  th the [database
1e540 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e   connection] han
1e550 64 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 72 65  dle should be re
1e560 6c 65 61 73 65 64 20 62 79 0a 2a 2a 20 70 61 73  leased by.** pas
1e570 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69  sing it to [sqli
1e580 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 77 68 65  te3_close()] whe
1e590 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 65  n it is no longe
1e5a0 72 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a  r required..**.*
1e5b0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 70  * The sqlite3_op
1e5c0 65 6e 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63  en_v2() interfac
1e5d0 65 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c  e works like sql
1e5e0 69 74 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65  ite3_open().** e
1e5f0 78 63 65 70 74 20 74 68 61 74 20 69 74 20 61 63  xcept that it ac
1e600 63 65 70 74 73 20 74 77 6f 20 61 64 64 69 74 69  cepts two additi
1e610 6f 6e 61 6c 20 70 61 72 61 6d 65 74 65 72 73 20  onal parameters 
1e620 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 63  for additional c
1e630 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74  ontrol.** over t
1e640 68 65 20 6e 65 77 20 64 61 74 61 62 61 73 65 20  he new database 
1e650 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 28 54  connection.  ^(T
1e660 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74  he flags paramet
1e670 65 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  er to.** sqlite3
1e680 5f 6f 70 65 6e 5f 76 32 28 29 20 63 61 6e 20 74  _open_v2() can t
1e690 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68  ake one of.** th
1e6a0 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65  e following thre
1e6b0 65 20 76 61 6c 75 65 73 2c 20 6f 70 74 69 6f 6e  e values, option
1e6c0 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69  ally combined wi
1e6d0 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49  th the .** [SQLI
1e6e0 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d  TE_OPEN_NOMUTEX]
1e6f0 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46  , [SQLITE_OPEN_F
1e700 55 4c 4c 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49  ULLMUTEX], [SQLI
1e710 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41  TE_OPEN_SHAREDCA
1e720 43 48 45 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  CHE],.** [SQLITE
1e730 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43  _OPEN_PRIVATECAC
1e740 48 45 5d 2c 20 61 6e 64 2f 6f 72 20 5b 53 51 4c  HE], and/or [SQL
1e750 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c  ITE_OPEN_URI] fl
1e760 61 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c  ags:)^.**.** <dl
1e770 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49  >.** ^(<dt>[SQLI
1e780 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59  TE_OPEN_READONLY
1e790 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  ]</dt>.** <dd>Th
1e7a0 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
1e7b0 65 6e 65 64 20 69 6e 20 72 65 61 64 2d 6f 6e 6c  ened in read-onl
1e7c0 79 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20  y mode.  If the 
1e7d0 64 61 74 61 62 61 73 65 20 64 6f 65 73 20 6e 6f  database does no
1e7e0 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 65 78 69  t.** already exi
1e7f0 73 74 2c 20 61 6e 20 65 72 72 6f 72 20 69 73 20  st, an error is 
1e800 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e  returned.</dd>)^
1e810 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51  .**.** ^(<dt>[SQ
1e820 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
1e830 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  ITE]</dt>.** <dd
1e840 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73  >The database is
1e850 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64   opened for read
1e860 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 20  ing and writing 
1e870 69 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20  if possible, or 
1e880 72 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20  reading.** only 
1e890 69 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 77  if the file is w
1e8a0 72 69 74 65 20 70 72 6f 74 65 63 74 65 64 20 62  rite protected b
1e8b0 79 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20  y the operating 
1e8c0 73 79 73 74 65 6d 2e 20 20 49 6e 20 65 69 74 68  system.  In eith
1e8d0 65 72 0a 2a 2a 20 63 61 73 65 20 74 68 65 20 64  er.** case the d
1e8e0 61 74 61 62 61 73 65 20 6d 75 73 74 20 61 6c 72  atabase must alr
1e8f0 65 61 64 79 20 65 78 69 73 74 2c 20 6f 74 68 65  eady exist, othe
1e900 72 77 69 73 65 20 61 6e 20 65 72 72 6f 72 20 69  rwise an error i
1e910 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e  s returned.</dd>
1e920 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b  )^.**.** ^(<dt>[
1e930 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
1e940 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45  WRITE] | [SQLITE
1e950 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 3c 2f 64  _OPEN_CREATE]</d
1e960 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61  t>.** <dd>The da
1e970 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
1e980 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64   for reading and
1e990 20 77 72 69 74 69 6e 67 2c 20 61 6e 64 20 69 73   writing, and is
1e9a0 20 63 72 65 61 74 65 64 20 69 66 0a 2a 2a 20 69   created if.** i
1e9b0 74 20 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65 61  t does not alrea
1e9c0 64 79 20 65 78 69 73 74 2e 20 54 68 69 73 20 69  dy exist. This i
1e9d0 73 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 74  s the behavior t
1e9e0 68 61 74 20 69 73 20 61 6c 77 61 79 73 20 75 73  hat is always us
1e9f0 65 64 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  ed for.** sqlite
1ea00 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c  3_open() and sql
1ea10 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f  ite3_open16().</
1ea20 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a  dd>)^.** </dl>.*
1ea30 2a 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20  *.** If the 3rd 
1ea40 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
1ea50 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69  ite3_open_v2() i
1ea60 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65  s not one of the
1ea70 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73  .** combinations
1ea80 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 6f 70 74   shown above opt
1ea90 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64  ionally combined
1eaa0 20 77 69 74 68 20 6f 74 68 65 72 0a 2a 2a 20 5b   with other.** [
1eab0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
1eac0 4f 4e 4c 59 20 7c 20 53 51 4c 49 54 45 5f 4f 50  ONLY | SQLITE_OP
1ead0 45 4e 5f 2a 20 62 69 74 73 5d 0a 2a 2a 20 74 68  EN_* bits].** th
1eae0 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
1eaf0 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
1eb00 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b 53 51 4c  .** ^If the [SQL
1eb10 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58  ITE_OPEN_NOMUTEX
1eb20 5d 20 66 6c 61 67 20 69 73 20 73 65 74 2c 20 74  ] flag is set, t
1eb30 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
1eb40 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f   connection.** o
1eb50 70 65 6e 73 20 69 6e 20 74 68 65 20 6d 75 6c 74  pens in the mult
1eb60 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61 64  i-thread [thread
1eb70 69 6e 67 20 6d 6f 64 65 5d 20 61 73 20 6c 6f 6e  ing mode] as lon
1eb80 67 20 61 73 20 74 68 65 20 73 69 6e 67 6c 65 2d  g as the single-
1eb90 74 68 72 65 61 64 0a 2a 2a 20 6d 6f 64 65 20 68  thread.** mode h
1eba0 61 73 20 6e 6f 74 20 62 65 65 6e 20 73 65 74 20  as not been set 
1ebb0 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  at compile-time 
1ebc0 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 20 20  or start-time.  
1ebd0 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  ^If the.** [SQLI
1ebe0 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45  TE_OPEN_FULLMUTE
1ebf0 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74 20 74  X] flag is set t
1ec00 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
1ec10 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e   connection open
1ec20 73 0a 2a 2a 20 69 6e 20 74 68 65 20 73 65 72 69  s.** in the seri
1ec30 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e  alized [threadin
1ec40 67 20 6d 6f 64 65 5d 20 75 6e 6c 65 73 73 20 73  g mode] unless s
1ec50 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 77 61 73  ingle-thread was
1ec60 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73  .** previously s
1ec70 65 6c 65 63 74 65 64 20 61 74 20 63 6f 6d 70 69  elected at compi
1ec80 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74  le-time or start
1ec90 2d 74 69 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 5b  -time..** ^The [
1eca0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52  SQLITE_OPEN_SHAR
1ecb0 45 44 43 41 43 48 45 5d 20 66 6c 61 67 20 63 61  EDCACHE] flag ca
1ecc0 75 73 65 73 20 74 68 65 20 64 61 74 61 62 61 73  uses the databas
1ecd0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20  e connection to 
1ece0 62 65 0a 2a 2a 20 65 6c 69 67 69 62 6c 65 20 74  be.** eligible t
1ecf0 6f 20 75 73 65 20 5b 73 68 61 72 65 64 20 63 61  o use [shared ca
1ed00 63 68 65 20 6d 6f 64 65 5d 2c 20 72 65 67 61 72  che mode], regar
1ed10 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72  dless of whether
1ed20 20 6f 72 20 6e 6f 74 20 73 68 61 72 65 64 0a 2a   or not shared.*
1ed30 2a 20 63 61 63 68 65 20 69 73 20 65 6e 61 62 6c  * cache is enabl
1ed40 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
1ed50 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f  3_enable_shared_
1ed60 63 61 63 68 65 28 29 5d 2e 20 20 5e 54 68 65 0a  cache()].  ^The.
1ed70 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ** [SQLITE_OPEN_
1ed80 50 52 49 56 41 54 45 43 41 43 48 45 5d 20 66 6c  PRIVATECACHE] fl
1ed90 61 67 20 63 61 75 73 65 73 20 74 68 65 20 64 61  ag causes the da
1eda0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1edb0 6e 20 74 6f 20 6e 6f 74 0a 2a 2a 20 70 61 72 74  n to not.** part
1edc0 69 63 69 70 61 74 65 20 69 6e 20 5b 73 68 61 72  icipate in [shar
1edd0 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 20 65  ed cache mode] e
1ede0 76 65 6e 20 69 66 20 69 74 20 69 73 20 65 6e 61  ven if it is ena
1edf0 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  bled..**.** ^The
1ee00 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
1ee10 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65  r to sqlite3_ope
1ee20 6e 5f 76 32 28 29 20 69 73 20 74 68 65 20 6e 61  n_v2() is the na
1ee30 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71  me of the.** [sq
1ee40 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
1ee50 74 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 74  t that defines t
1ee60 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  he operating sys
1ee70 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68  tem interface th
1ee80 61 74 0a 2a 2a 20 74 68 65 20 6e 65 77 20 64 61  at.** the new da
1ee90 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1eea0 6e 20 73 68 6f 75 6c 64 20 75 73 65 2e 20 20 5e  n should use.  ^
1eeb0 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  If the fourth pa
1eec0 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 61 20  rameter is.** a 
1eed0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65  NULL pointer the
1eee0 6e 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73  n the default [s
1eef0 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
1ef00 63 74 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a  ct is used..**.*
1ef10 2a 20 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61  * ^If the filena
1ef20 6d 65 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22  me is ":memory:"
1ef30 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 65  , then a private
1ef40 2c 20 74 65 6d 70 6f 72 61 72 79 20 69 6e 2d 6d  , temporary in-m
1ef50 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 0a 2a  emory database.*
1ef60 2a 20 69 73 20 63 72 65 61 74 65 64 20 66 6f 72  * is created for
1ef70 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e   the connection.
1ef80 20 20 5e 54 68 69 73 20 69 6e 2d 6d 65 6d 6f 72    ^This in-memor
1ef90 79 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20  y database will 
1efa0 76 61 6e 69 73 68 20 77 68 65 6e 0a 2a 2a 20 74  vanish when.** t
1efb0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
1efc0 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64  ection is closed
1efd0 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f  .  Future versio
1efe0 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67  ns of SQLite mig
1eff0 68 74 0a 2a 2a 20 6d 61 6b 65 20 75 73 65 20 6f  ht.** make use o
1f000 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 70 65  f additional spe
1f010 63 69 61 6c 20 66 69 6c 65 6e 61 6d 65 73 20 74  cial filenames t
1f020 68 61 74 20 62 65 67 69 6e 20 77 69 74 68 20 74  hat begin with t
1f030 68 65 20 22 3a 22 20 63 68 61 72 61 63 74 65 72  he ":" character
1f040 2e 0a 2a 2a 20 49 74 20 69 73 20 72 65 63 6f 6d  ..** It is recom
1f050 6d 65 6e 64 65 64 20 74 68 61 74 20 77 68 65 6e  mended that when
1f060 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65   a database file
1f070 6e 61 6d 65 20 61 63 74 75 61 6c 6c 79 20 64 6f  name actually do
1f080 65 73 20 62 65 67 69 6e 20 77 69 74 68 0a 2a 2a  es begin with.**
1f090 20 61 20 22 3a 22 20 63 68 61 72 61 63 74 65 72   a ":" character
1f0a0 20 79 6f 75 20 73 68 6f 75 6c 64 20 70 72 65 66   you should pref
1f0b0 69 78 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  ix the filename 
1f0c0 77 69 74 68 20 61 20 70 61 74 68 6e 61 6d 65 20  with a pathname 
1f0d0 73 75 63 68 20 61 73 0a 2a 2a 20 22 2e 2f 22 20  such as.** "./" 
1f0e0 74 6f 20 61 76 6f 69 64 20 61 6d 62 69 67 75 69  to avoid ambigui
1f0f0 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  ty..**.** ^If th
1f100 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 61 6e  e filename is an
1f110 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 74   empty string, t
1f120 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74  hen a private, t
1f130 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64  emporary.** on-d
1f140 69 73 6b 20 64 61 74 61 62 61 73 65 20 77 69 6c  isk database wil
1f150 6c 20 62 65 20 63 72 65 61 74 65 64 2e 20 20 5e  l be created.  ^
1f160 54 68 69 73 20 70 72 69 76 61 74 65 20 64 61 74  This private dat
1f170 61 62 61 73 65 20 77 69 6c 6c 20 62 65 0a 2a 2a  abase will be.**
1f180 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64   automatically d
1f190 65 6c 65 74 65 64 20 61 73 20 73 6f 6f 6e 20 61  eleted as soon a
1f1a0 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  s the database c
1f1b0 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f  onnection is clo
1f1c0 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49  sed..**.** [[URI
1f1d0 20 66 69 6c 65 6e 61 6d 65 73 20 69 6e 20 73 71   filenames in sq
1f1e0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 5d 20 3c  lite3_open()]] <
1f1f0 68 33 3e 55 52 49 20 46 69 6c 65 6e 61 6d 65 73  h3>URI Filenames
1f200 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  </h3>.**.** ^If 
1f210 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 5d 20 69  [URI filename] i
1f220 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73  nterpretation is
1f230 20 65 6e 61 62 6c 65 64 2c 20 61 6e 64 20 74 68   enabled, and th
1f240 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d  e filename argum
1f250 65 6e 74 0a 2a 2a 20 62 65 67 69 6e 73 20 77 69  ent.** begins wi
1f260 74 68 20 22 66 69 6c 65 3a 22 2c 20 74 68 65 6e  th "file:", then
1f270 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73   the filename is
1f280 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
1f290 61 20 55 52 49 2e 20 5e 55 52 49 0a 2a 2a 20 66  a URI. ^URI.** f
1f2a0 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 65  ilename interpre
1f2b0 74 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65  tation is enable
1f2c0 64 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45  d if the [SQLITE
1f2d0 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20  _OPEN_URI] flag 
1f2e0 69 73 0a 2a 2a 20 73 65 74 20 69 6e 20 74 68 65  is.** set in the
1f2f0 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74   fourth argument
1f300 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   to sqlite3_open
1f310 5f 76 32 28 29 2c 20 6f 72 20 69 66 20 69 74 20  _v2(), or if it 
1f320 68 61 73 0a 2a 2a 20 62 65 65 6e 20 65 6e 61 62  has.** been enab
1f330 6c 65 64 20 67 6c 6f 62 61 6c 6c 79 20 75 73 69  led globally usi
1f340 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43  ng the [SQLITE_C
1f350 4f 4e 46 49 47 5f 55 52 49 5d 20 6f 70 74 69 6f  ONFIG_URI] optio
1f360 6e 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 73  n with the.** [s
1f370 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
1f380 20 6d 65 74 68 6f 64 20 6f 72 20 62 79 20 74 68   method or by th
1f390 65 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55 52  e [SQLITE_USE_UR
1f3a0 49 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  I] compile-time 
1f3b0 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 41 73 20 6f 66  option..** As of
1f3c0 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
1f3d0 33 2e 37 2e 37 2c 20 55 52 49 20 66 69 6c 65 6e  3.7.7, URI filen
1f3e0 61 6d 65 20 69 6e 74 65 72 70 72 65 74 61 74 69  ame interpretati
1f3f0 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 6f 66 66  on is turned off
1f400 0a 2a 2a 20 62 79 20 64 65 66 61 75 6c 74 2c 20  .** by default, 
1f410 62 75 74 20 66 75 74 75 72 65 20 72 65 6c 65 61  but future relea
1f420 73 65 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69  ses of SQLite mi
1f430 67 68 74 20 65 6e 61 62 6c 65 20 55 52 49 20 66  ght enable URI f
1f440 69 6c 65 6e 61 6d 65 0a 2a 2a 20 69 6e 74 65 72  ilename.** inter
1f450 70 72 65 74 61 74 69 6f 6e 20 62 79 20 64 65 66  pretation by def
1f460 61 75 6c 74 2e 20 20 53 65 65 20 22 5b 55 52 49  ault.  See "[URI
1f470 20 66 69 6c 65 6e 61 6d 65 73 5d 22 20 66 6f 72   filenames]" for
1f480 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69   additional.** i
1f490 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  nformation..**.*
1f4a0 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20  * URI filenames 
1f4b0 61 72 65 20 70 61 72 73 65 64 20 61 63 63 6f 72  are parsed accor
1f4c0 64 69 6e 67 20 74 6f 20 52 46 43 20 33 39 38 36  ding to RFC 3986
1f4d0 2e 20 5e 49 66 20 74 68 65 20 55 52 49 20 63 6f  . ^If the URI co
1f4e0 6e 74 61 69 6e 73 20 61 6e 0a 2a 2a 20 61 75 74  ntains an.** aut
1f4f0 68 6f 72 69 74 79 2c 20 74 68 65 6e 20 69 74 20  hority, then it 
1f500 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20 61  must be either a
1f510 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20 6f  n empty string o
1f520 72 20 74 68 65 20 73 74 72 69 6e 67 20 0a 2a 2a  r the string .**
1f530 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2e 20 5e 49   "localhost". ^I
1f540 66 20 74 68 65 20 61 75 74 68 6f 72 69 74 79 20  f the authority 
1f550 69 73 20 6e 6f 74 20 61 6e 20 65 6d 70 74 79 20  is not an empty 
1f560 73 74 72 69 6e 67 20 6f 72 20 22 6c 6f 63 61 6c  string or "local
1f570 68 6f 73 74 22 2c 20 61 6e 20 0a 2a 2a 20 65 72  host", an .** er
1f580 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 20  ror is returned 
1f590 74 6f 20 74 68 65 20 63 61 6c 6c 65 72 2e 20 5e  to the caller. ^
1f5a0 54 68 65 20 66 72 61 67 6d 65 6e 74 20 63 6f 6d  The fragment com
1f5b0 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 2c  ponent of a URI,
1f5c0 20 69 66 20 0a 2a 2a 20 70 72 65 73 65 6e 74 2c   if .** present,
1f5d0 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a   is ignored..**.
1f5e0 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20  ** ^SQLite uses 
1f5f0 74 68 65 20 70 61 74 68 20 63 6f 6d 70 6f 6e 65  the path compone
1f600 6e 74 20 6f 66 20 74 68 65 20 55 52 49 20 61 73  nt of the URI as
1f610 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
1f620 20 64 69 73 6b 20 66 69 6c 65 0a 2a 2a 20 77 68   disk file.** wh
1f630 69 63 68 20 63 6f 6e 74 61 69 6e 73 20 74 68 65  ich contains the
1f640 20 64 61 74 61 62 61 73 65 2e 20 5e 49 66 20 74   database. ^If t
1f650 68 65 20 70 61 74 68 20 62 65 67 69 6e 73 20 77  he path begins w
1f660 69 74 68 20 61 20 27 2f 27 20 63 68 61 72 61 63  ith a '/' charac
1f670 74 65 72 2c 20 0a 2a 2a 20 74 68 65 6e 20 69 74  ter, .** then it
1f680 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20   is interpreted 
1f690 61 73 20 61 6e 20 61 62 73 6f 6c 75 74 65 20 70  as an absolute p
1f6a0 61 74 68 2e 20 5e 49 66 20 74 68 65 20 70 61 74  ath. ^If the pat
1f6b0 68 20 64 6f 65 73 20 6e 6f 74 20 62 65 67 69 6e  h does not begin
1f6c0 20 0a 2a 2a 20 77 69 74 68 20 61 20 27 2f 27 20   .** with a '/' 
1f6d0 28 6d 65 61 6e 69 6e 67 20 74 68 61 74 20 74 68  (meaning that th
1f6e0 65 20 61 75 74 68 6f 72 69 74 79 20 73 65 63 74  e authority sect
1f6f0 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64 20 66  ion is omitted f
1f700 72 6f 6d 20 74 68 65 20 55 52 49 29 0a 2a 2a 20  rom the URI).** 
1f710 74 68 65 6e 20 74 68 65 20 70 61 74 68 20 69 73  then the path is
1f720 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
1f730 61 20 72 65 6c 61 74 69 76 65 20 70 61 74 68 2e  a relative path.
1f740 20 0a 2a 2a 20 5e 4f 6e 20 77 69 6e 64 6f 77 73   .** ^On windows
1f750 2c 20 74 68 65 20 66 69 72 73 74 20 63 6f 6d 70  , the first comp
1f760 6f 6e 65 6e 74 20 6f 66 20 61 6e 20 61 62 73 6f  onent of an abso
1f770 6c 75 74 65 20 70 61 74 68 20 0a 2a 2a 20 69 73  lute path .** is
1f780 20 61 20 64 72 69 76 65 20 73 70 65 63 69 66 69   a drive specifi
1f790 63 61 74 69 6f 6e 20 28 65 2e 67 2e 20 22 43 3a  cation (e.g. "C:
1f7a0 22 29 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 63 6f 72 65  ")..**.** [[core
1f7b0 20 55 52 49 20 71 75 65 72 79 20 70 61 72 61 6d   URI query param
1f7c0 65 74 65 72 73 5d 5d 0a 2a 2a 20 54 68 65 20 71  eters]].** The q
1f7d0 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f  uery component o
1f7e0 66 20 61 20 55 52 49 20 6d 61 79 20 63 6f 6e 74  f a URI may cont
1f7f0 61 69 6e 20 70 61 72 61 6d 65 74 65 72 73 20 74  ain parameters t
1f800 68 61 74 20 61 72 65 20 69 6e 74 65 72 70 72 65  hat are interpre
1f810 74 65 64 0a 2a 2a 20 65 69 74 68 65 72 20 62 79  ted.** either by
1f820 20 53 51 4c 69 74 65 20 69 74 73 65 6c 66 2c 20   SQLite itself, 
1f830 6f 72 20 62 79 20 61 20 5b 56 46 53 20 7c 20 63  or by a [VFS | c
1f840 75 73 74 6f 6d 20 56 46 53 20 69 6d 70 6c 65 6d  ustom VFS implem
1f850 65 6e 74 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 53 51  entation]..** SQ
1f860 4c 69 74 65 20 69 6e 74 65 72 70 72 65 74 73 20  Lite interprets 
1f870 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68  the following th
1f880 72 65 65 20 71 75 65 72 79 20 70 61 72 61 6d 65  ree query parame
1f890 74 65 72 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ters:.**.** <ul>
1f8a0 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 76 66  .**   <li> <b>vf
1f8b0 73 3c 2f 62 3e 3a 20 5e 54 68 65 20 22 76 66 73  s</b>: ^The "vfs
1f8c0 22 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20  " parameter may 
1f8d0 62 65 20 75 73 65 64 20 74 6f 20 73 70 65 63 69  be used to speci
1f8e0 66 79 20 74 68 65 20 6e 61 6d 65 20 6f 66 0a 2a  fy the name of.*
1f8f0 2a 20 20 20 20 20 61 20 56 46 53 20 6f 62 6a 65  *     a VFS obje
1f900 63 74 20 74 68 61 74 20 70 72 6f 76 69 64 65 73  ct that provides
1f910 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73   the operating s
1f920 79 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20  ystem interface 
1f930 74 68 61 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 20  that should.**  
1f940 20 20 20 62 65 20 75 73 65 64 20 74 6f 20 61 63     be used to ac
1f950 63 65 73 73 20 74 68 65 20 64 61 74 61 62 61 73  cess the databas
1f960 65 20 66 69 6c 65 20 6f 6e 20 64 69 73 6b 2e 20  e file on disk. 
1f970 5e 49 66 20 74 68 69 73 20 6f 70 74 69 6f 6e 20  ^If this option 
1f980 69 73 20 73 65 74 20 74 6f 0a 2a 2a 20 20 20 20  is set to.**    
1f990 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67   an empty string
1f9a0 20 74 68 65 20 64 65 66 61 75 6c 74 20 56 46 53   the default VFS
1f9b0 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e   object is used.
1f9c0 20 5e 53 70 65 63 69 66 79 69 6e 67 20 61 6e 20   ^Specifying an 
1f9d0 75 6e 6b 6e 6f 77 6e 0a 2a 2a 20 20 20 20 20 56  unknown.**     V
1f9e0 46 53 20 69 73 20 61 6e 20 65 72 72 6f 72 2e 20  FS is an error. 
1f9f0 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ^If sqlite3_open
1fa00 5f 76 32 28 29 20 69 73 20 75 73 65 64 20 61 6e  _v2() is used an
1fa10 64 20 74 68 65 20 76 66 73 20 6f 70 74 69 6f 6e  d the vfs option
1fa20 20 69 73 0a 2a 2a 20 20 20 20 20 70 72 65 73 65   is.**     prese
1fa30 6e 74 2c 20 74 68 65 6e 20 74 68 65 20 56 46 53  nt, then the VFS
1fa40 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68   specified by th
1fa50 65 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 70  e option takes p
1fa60 72 65 63 65 64 65 6e 63 65 20 6f 76 65 72 0a 2a  recedence over.*
1fa70 2a 20 20 20 20 20 74 68 65 20 76 61 6c 75 65 20  *     the value 
1fa80 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66 6f  passed as the fo
1fa90 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  urth parameter t
1faa0 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  o sqlite3_open_v
1fab0 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69  2()..**.**   <li
1fac0 3e 20 3c 62 3e 6d 6f 64 65 3c 2f 62 3e 3a 20 5e  > <b>mode</b>: ^
1fad0 28 54 68 65 20 6d 6f 64 65 20 70 61 72 61 6d 65  (The mode parame
1fae0 74 65 72 20 6d 61 79 20 62 65 20 73 65 74 20 74  ter may be set t
1faf0 6f 20 65 69 74 68 65 72 20 22 72 6f 22 2c 20 22  o either "ro", "
1fb00 72 77 22 2c 0a 2a 2a 20 20 20 20 20 22 72 77 63  rw",.**     "rwc
1fb10 22 2c 20 6f 72 20 22 6d 65 6d 6f 72 79 22 2e 20  ", or "memory". 
1fb20 41 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 73 65  Attempting to se
1fb30 74 20 69 74 20 74 6f 20 61 6e 79 20 6f 74 68 65  t it to any othe
1fb40 72 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 20 20  r value is.**   
1fb50 20 20 61 6e 20 65 72 72 6f 72 29 5e 2e 20 0a 2a    an error)^. .*
1fb60 2a 20 20 20 20 20 5e 49 66 20 22 72 6f 22 20 69  *     ^If "ro" i
1fb70 73 20 73 70 65 63 69 66 69 65 64 2c 20 74 68 65  s specified, the
1fb80 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  n the database i
1fb90 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61  s opened for rea
1fba0 64 2d 6f 6e 6c 79 20 0a 2a 2a 20 20 20 20 20 61  d-only .**     a
1fbb0 63 63 65 73 73 2c 20 6a 75 73 74 20 61 73 20 69  ccess, just as i
1fbc0 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  f the [SQLITE_OP
1fbd0 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 20 66 6c 61  EN_READONLY] fla
1fbe0 67 20 68 61 64 20 62 65 65 6e 20 73 65 74 20 69  g had been set i
1fbf0 6e 20 74 68 65 20 0a 2a 2a 20 20 20 20 20 74 68  n the .**     th
1fc00 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ird argument to 
1fc10 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
1fc20 29 2e 20 5e 49 66 20 74 68 65 20 6d 6f 64 65 20  ). ^If the mode 
1fc30 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 20 74 6f  option is set to
1fc40 20 0a 2a 2a 20 20 20 20 20 22 72 77 22 2c 20 74   .**     "rw", t
1fc50 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
1fc60 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72   is opened for r
1fc70 65 61 64 2d 77 72 69 74 65 20 28 62 75 74 20 6e  ead-write (but n
1fc80 6f 74 20 63 72 65 61 74 65 29 20 0a 2a 2a 20 20  ot create) .**  
1fc90 20 20 20 61 63 63 65 73 73 2c 20 61 73 20 69 66     access, as if
1fca0 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41   SQLITE_OPEN_REA
1fcb0 44 57 52 49 54 45 20 28 62 75 74 20 6e 6f 74 20  DWRITE (but not 
1fcc0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
1fcd0 54 45 29 20 68 61 64 20 0a 2a 2a 20 20 20 20 20  TE) had .**     
1fce0 62 65 65 6e 20 73 65 74 2e 20 5e 56 61 6c 75 65  been set. ^Value
1fcf0 20 22 72 77 63 22 20 69 73 20 65 71 75 69 76 61   "rwc" is equiva
1fd00 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20  lent to setting 
1fd10 62 6f 74 68 20 0a 2a 2a 20 20 20 20 20 53 51 4c  both .**     SQL
1fd20 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
1fd30 54 45 20 61 6e 64 20 53 51 4c 49 54 45 5f 4f 50  TE and SQLITE_OP
1fd40 45 4e 5f 43 52 45 41 54 45 2e 20 20 5e 49 66 20  EN_CREATE.  ^If 
1fd50 74 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20  the mode option 
1fd60 69 73 0a 2a 2a 20 20 20 20 20 73 65 74 20 74 6f  is.**     set to
1fd70 20 22 6d 65 6d 6f 72 79 22 20 74 68 65 6e 20 61   "memory" then a
1fd80 20 70 75 72 65 20 5b 69 6e 2d 6d 65 6d 6f 72 79   pure [in-memory
1fd90 20 64 61 74 61 62 61 73 65 5d 20 74 68 61 74 20   database] that 
1fda0 6e 65 76 65 72 20 72 65 61 64 73 0a 2a 2a 20 20  never reads.**  
1fdb0 20 20 20 6f 72 20 77 72 69 74 65 73 20 66 72 6f     or writes fro
1fdc0 6d 20 64 69 73 6b 20 69 73 20 75 73 65 64 2e 20  m disk is used. 
1fdd0 5e 49 74 20 69 73 20 61 6e 20 65 72 72 6f 72 20  ^It is an error 
1fde0 74 6f 20 73 70 65 63 69 66 79 20 61 20 76 61 6c  to specify a val
1fdf0 75 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20 74 68  ue for.**     th
1fe00 65 20 6d 6f 64 65 20 70 61 72 61 6d 65 74 65 72  e mode parameter
1fe10 20 74 68 61 74 20 69 73 20 6c 65 73 73 20 72 65   that is less re
1fe20 73 74 72 69 63 74 69 76 65 20 74 68 61 6e 20 74  strictive than t
1fe30 68 61 74 20 73 70 65 63 69 66 69 65 64 20 62 79  hat specified by
1fe40 0a 2a 2a 20 20 20 20 20 74 68 65 20 66 6c 61 67  .**     the flag
1fe50 73 20 70 61 73 73 65 64 20 69 6e 20 74 68 65 20  s passed in the 
1fe60 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
1fe70 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  to sqlite3_open_
1fe80 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c  v2()..**.**   <l
1fe90 69 3e 20 3c 62 3e 63 61 63 68 65 3c 2f 62 3e 3a  i> <b>cache</b>:
1fea0 20 5e 54 68 65 20 63 61 63 68 65 20 70 61 72 61   ^The cache para
1feb0 6d 65 74 65 72 20 6d 61 79 20 62 65 20 73 65 74  meter may be set
1fec0 20 74 6f 20 65 69 74 68 65 72 20 22 73 68 61 72   to either "shar
1fed0 65 64 22 20 6f 72 0a 2a 2a 20 20 20 20 20 22 70  ed" or.**     "p
1fee0 72 69 76 61 74 65 22 2e 20 5e 53 65 74 74 69 6e  rivate". ^Settin
1fef0 67 20 69 74 20 74 6f 20 22 73 68 61 72 65 64 22  g it to "shared"
1ff00 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74   is equivalent t
1ff10 6f 20 73 65 74 74 69 6e 67 20 74 68 65 0a 2a 2a  o setting the.**
1ff20 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e       SQLITE_OPEN
1ff30 5f 53 48 41 52 45 44 43 41 43 48 45 20 62 69 74  _SHAREDCACHE bit
1ff40 20 69 6e 20 74 68 65 20 66 6c 61 67 73 20 61 72   in the flags ar
1ff50 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20 74 6f  gument passed to
1ff60 0a 2a 2a 20 20 20 20 20 73 71 6c 69 74 65 33 5f  .**     sqlite3_
1ff70 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 53 65 74 74  open_v2(). ^Sett
1ff80 69 6e 67 20 74 68 65 20 63 61 63 68 65 20 70 61  ing the cache pa
1ff90 72 61 6d 65 74 65 72 20 74 6f 20 22 70 72 69 76  rameter to "priv
1ffa0 61 74 65 22 20 69 73 20 0a 2a 2a 20 20 20 20 20  ate" is .**     
1ffb0 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65  equivalent to se
1ffc0 74 74 69 6e 67 20 74 68 65 20 53 51 4c 49 54 45  tting the SQLITE
1ffd0 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43  _OPEN_PRIVATECAC
1ffe0 48 45 20 62 69 74 2e 0a 2a 2a 20 20 20 20 20 5e  HE bit..**     ^
1fff0 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  If sqlite3_open_
20000 76 32 28 29 20 69 73 20 75 73 65 64 20 61 6e 64  v2() is used and
20010 20 74 68 65 20 22 63 61 63 68 65 22 20 70 61 72   the "cache" par
20020 61 6d 65 74 65 72 20 69 73 20 70 72 65 73 65 6e  ameter is presen
20030 74 20 69 6e 0a 2a 2a 20 20 20 20 20 61 20 55 52  t in.**     a UR
20040 49 20 66 69 6c 65 6e 61 6d 65 2c 20 69 74 73 20  I filename, its 
20050 76 61 6c 75 65 20 6f 76 65 72 72 69 64 65 73 20  value overrides 
20060 61 6e 79 20 62 65 68 61 76 69 6f 75 72 20 72 65  any behaviour re
20070 71 75 65 73 74 65 64 20 62 79 20 73 65 74 74 69  quested by setti
20080 6e 67 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45  ng.**     SQLITE
20090 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43  _OPEN_PRIVATECAC
200a0 48 45 20 6f 72 20 53 51 4c 49 54 45 5f 4f 50 45  HE or SQLITE_OPE
200b0 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20 66 6c  N_SHAREDCACHE fl
200c0 61 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a  ag..** </ul>.**.
200d0 2a 2a 20 5e 53 70 65 63 69 66 79 69 6e 67 20 61  ** ^Specifying a
200e0 6e 20 75 6e 6b 6e 6f 77 6e 20 70 61 72 61 6d 65  n unknown parame
200f0 74 65 72 20 69 6e 20 74 68 65 20 71 75 65 72 79  ter in the query
20100 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20   component of a 
20110 55 52 49 20 69 73 20 6e 6f 74 20 61 6e 0a 2a 2a  URI is not an.**
20120 20 65 72 72 6f 72 2e 20 20 46 75 74 75 72 65 20   error.  Future 
20130 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
20140 74 65 20 6d 69 67 68 74 20 75 6e 64 65 72 73 74  te might underst
20150 61 6e 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 71  and additional q
20160 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65  uery.** paramete
20170 72 73 2e 20 20 53 65 65 20 22 5b 71 75 65 72 79  rs.  See "[query
20180 20 70 61 72 61 6d 65 74 65 72 73 20 77 69 74 68   parameters with
20190 20 73 70 65 63 69 61 6c 20 6d 65 61 6e 69 6e 67   special meaning
201a0 20 74 6f 20 53 51 4c 69 74 65 5d 22 20 66 6f 72   to SQLite]" for
201b0 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20 69  .** additional i
201c0 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  nformation..**.*
201d0 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65  * [[URI filename
201e0 20 65 78 61 6d 70 6c 65 73 5d 5d 20 3c 68 33 3e   examples]] <h3>
201f0 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 65 78 61  URI filename exa
20200 6d 70 6c 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a  mples</h3>.**.**
20210 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22   <table border="
20220 31 22 20 61 6c 69 67 6e 3d 63 65 6e 74 65 72 20  1" align=center 
20230 63 65 6c 6c 70 61 64 64 69 6e 67 3d 35 3e 0a 2a  cellpadding=5>.*
20240 2a 20 3c 74 72 3e 3c 74 68 3e 20 55 52 49 20 66  * <tr><th> URI f
20250 69 6c 65 6e 61 6d 65 73 20 3c 74 68 3e 20 52 65  ilenames <th> Re
20260 73 75 6c 74 73 0a 2a 2a 20 3c 74 72 3e 3c 74 64  sults.** <tr><td
20270 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 20 3c  > file:data.db <
20280 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  td> .**         
20290 20 4f 70 65 6e 20 74 68 65 20 66 69 6c 65 20 22   Open the file "
202a0 64 61 74 61 2e 64 62 22 20 69 6e 20 74 68 65 20  data.db" in the 
202b0 63 75 72 72 65 6e 74 20 64 69 72 65 63 74 6f 72  current director
202c0 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66  y..** <tr><td> f
202d0 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64  ile:/home/fred/d
202e0 61 74 61 2e 64 62 3c 62 72 3e 0a 2a 2a 20 20 20  ata.db<br>.**   
202f0 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 68         file:///h
20300 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62  ome/fred/data.db
20310 20 3c 62 72 3e 20 0a 2a 2a 20 20 20 20 20 20 20   <br> .**       
20320 20 20 20 66 69 6c 65 3a 2f 2f 6c 6f 63 61 6c 68     file://localh
20330 6f 73 74 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61  ost/home/fred/da
20340 74 61 2e 64 62 20 3c 62 72 3e 20 3c 74 64 3e 20  ta.db <br> <td> 
20350 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65  .**          Ope
20360 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  n the database f
20370 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f  ile "/home/fred/
20380 64 61 74 61 2e 64 62 22 2e 0a 2a 2a 20 3c 74 72  data.db"..** <tr
20390 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 2f 64 61 72  ><td> file://dar
203a0 6b 73 74 61 72 2f 68 6f 6d 65 2f 66 72 65 64 2f  kstar/home/fred/
203b0 64 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a  data.db <td> .**
203c0 20 20 20 20 20 20 20 20 20 20 41 6e 20 65 72 72            An err
203d0 6f 72 2e 20 22 64 61 72 6b 73 74 61 72 22 20 69  or. "darkstar" i
203e0 73 20 6e 6f 74 20 61 20 72 65 63 6f 67 6e 69 7a  s not a recogniz
203f0 65 64 20 61 75 74 68 6f 72 69 74 79 2e 0a 2a 2a  ed authority..**
20400 20 3c 74 72 3e 3c 74 64 20 73 74 79 6c 65 3d 22   <tr><td style="
20410 77 68 69 74 65 2d 73 70 61 63 65 3a 6e 6f 77 72  white-space:nowr
20420 61 70 22 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20  ap"> .**        
20430 20 20 66 69 6c 65 3a 2f 2f 2f 43 3a 2f 44 6f 63    file:///C:/Doc
20440 75 6d 65 6e 74 73 25 32 30 61 6e 64 25 32 30 53  uments%20and%20S
20450 65 74 74 69 6e 67 73 2f 66 72 65 64 2f 44 65 73  ettings/fred/Des
20460 6b 74 6f 70 2f 64 61 74 61 2e 64 62 0a 2a 2a 20  ktop/data.db.** 
20470 20 20 20 20 3c 74 64 3e 20 57 69 6e 64 6f 77 73      <td> Windows
20480 20 6f 6e 6c 79 3a 20 4f 70 65 6e 20 74 68 65 20   only: Open the 
20490 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20 6f  file "data.db" o
204a0 6e 20 66 72 65 64 27 73 20 64 65 73 6b 74 6f 70  n fred's desktop
204b0 20 6f 6e 20 64 72 69 76 65 0a 2a 2a 20 20 20 20   on drive.**    
204c0 20 20 20 20 20 20 43 3a 2e 20 4e 6f 74 65 20 74        C:. Note t
204d0 68 61 74 20 74 68 65 20 25 32 30 20 65 73 63 61  hat the %20 esca
204e0 70 69 6e 67 20 69 6e 20 74 68 69 73 20 65 78 61  ping in this exa
204f0 6d 70 6c 65 20 69 73 20 6e 6f 74 20 73 74 72 69  mple is not stri
20500 63 74 6c 79 20 0a 2a 2a 20 20 20 20 20 20 20 20  ctly .**        
20510 20 20 6e 65 63 65 73 73 61 72 79 20 2d 20 73 70    necessary - sp
20520 61 63 65 20 63 68 61 72 61 63 74 65 72 73 20 63  ace characters c
20530 61 6e 20 62 65 20 75 73 65 64 20 6c 69 74 65 72  an be used liter
20540 61 6c 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 20  ally.**         
20550 20 69 6e 20 55 52 49 20 66 69 6c 65 6e 61 6d 65   in URI filename
20560 73 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66  s..** <tr><td> f
20570 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65  ile:data.db?mode
20580 3d 72 6f 26 63 61 63 68 65 3d 70 72 69 76 61 74  =ro&cache=privat
20590 65 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20  e <td> .**      
205a0 20 20 20 20 4f 70 65 6e 20 66 69 6c 65 20 22 64      Open file "d
205b0 61 74 61 2e 64 62 22 20 69 6e 20 74 68 65 20 63  ata.db" in the c
205c0 75 72 72 65 6e 74 20 64 69 72 65 63 74 6f 72 79  urrent directory
205d0 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20 61   for read-only a
205e0 63 63 65 73 73 2e 0a 2a 2a 20 20 20 20 20 20 20  ccess..**       
205f0 20 20 20 52 65 67 61 72 64 6c 65 73 73 20 6f 66     Regardless of
20600 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
20610 73 68 61 72 65 64 2d 63 61 63 68 65 20 6d 6f 64  shared-cache mod
20620 65 20 69 73 20 65 6e 61 62 6c 65 64 20 62 79 0a  e is enabled by.
20630 2a 2a 20 20 20 20 20 20 20 20 20 20 64 65 66 61  **          defa
20640 75 6c 74 2c 20 75 73 65 20 61 20 70 72 69 76 61  ult, use a priva
20650 74 65 20 63 61 63 68 65 2e 0a 2a 2a 20 3c 74 72  te cache..** <tr
20660 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65  ><td> file:/home
20670 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 3f 76 66  /fred/data.db?vf
20680 73 3d 75 6e 69 78 2d 6e 6f 6c 6f 63 6b 20 3c 74  s=unix-nolock <t
20690 64 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f  d>.**          O
206a0 70 65 6e 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f  pen file "/home/
206b0 66 72 65 64 2f 64 61 74 61 2e 64 62 22 2e 20 55  fred/data.db". U
206c0 73 65 20 74 68 65 20 73 70 65 63 69 61 6c 20 56  se the special V
206d0 46 53 20 22 75 6e 69 78 2d 6e 6f 6c 6f 63 6b 22  FS "unix-nolock"
206e0 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69  ..** <tr><td> fi
206f0 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d  le:data.db?mode=
20700 72 65 61 64 6f 6e 6c 79 20 3c 74 64 3e 20 0a 2a  readonly <td> .*
20710 2a 20 20 20 20 20 20 20 20 20 20 41 6e 20 65 72  *          An er
20720 72 6f 72 2e 20 22 72 65 61 64 6f 6e 6c 79 22 20  ror. "readonly" 
20730 69 73 20 6e 6f 74 20 61 20 76 61 6c 69 64 20 6f  is not a valid o
20740 70 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 22 6d  ption for the "m
20750 6f 64 65 22 20 70 61 72 61 6d 65 74 65 72 2e 0a  ode" parameter..
20760 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 0a 2a  ** </table>.**.*
20770 2a 20 5e 55 52 49 20 68 65 78 61 64 65 63 69 6d  * ^URI hexadecim
20780 61 6c 20 65 73 63 61 70 65 20 73 65 71 75 65 6e  al escape sequen
20790 63 65 73 20 28 25 48 48 29 20 61 72 65 20 73 75  ces (%HH) are su
207a0 70 70 6f 72 74 65 64 20 77 69 74 68 69 6e 20 74  pported within t
207b0 68 65 20 70 61 74 68 20 61 6e 64 0a 2a 2a 20 71  he path and.** q
207c0 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20  uery components 
207d0 6f 66 20 61 20 55 52 49 2e 20 41 20 68 65 78 61  of a URI. A hexa
207e0 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73  decimal escape s
207f0 65 71 75 65 6e 63 65 20 63 6f 6e 73 69 73 74 73  equence consists
20800 20 6f 66 20 61 0a 2a 2a 20 70 65 72 63 65 6e 74   of a.** percent
20810 20 73 69 67 6e 20 2d 20 22 25 22 20 2d 20 66 6f   sign - "%" - fo
20820 6c 6c 6f 77 65 64 20 62 79 20 65 78 61 63 74 6c  llowed by exactl
20830 79 20 74 77 6f 20 68 65 78 61 64 65 63 69 6d 61  y two hexadecima
20840 6c 20 64 69 67 69 74 73 20 0a 2a 2a 20 73 70 65  l digits .** spe
20850 63 69 66 79 69 6e 67 20 61 6e 20 6f 63 74 65 74  cifying an octet
20860 20 76 61 6c 75 65 2e 20 5e 42 65 66 6f 72 65 20   value. ^Before 
20870 74 68 65 20 70 61 74 68 20 6f 72 20 71 75 65 72  the path or quer
20880 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20  y components of 
20890 61 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d  a.** URI filenam
208a0 65 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65  e are interprete
208b0 64 2c 20 74 68 65 79 20 61 72 65 20 65 6e 63 6f  d, they are enco
208c0 64 65 64 20 75 73 69 6e 67 20 55 54 46 2d 38 20  ded using UTF-8 
208d0 61 6e 64 20 61 6c 6c 20 0a 2a 2a 20 68 65 78 61  and all .** hexa
208e0 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73  decimal escape s
208f0 65 71 75 65 6e 63 65 73 20 72 65 70 6c 61 63 65  equences replace
20900 64 20 62 79 20 61 20 73 69 6e 67 6c 65 20 62 79  d by a single by
20910 74 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68  te containing th
20920 65 0a 2a 2a 20 63 6f 72 72 65 73 70 6f 6e 64 69  e.** correspondi
20930 6e 67 20 6f 63 74 65 74 2e 20 49 66 20 74 68 69  ng octet. If thi
20940 73 20 70 72 6f 63 65 73 73 20 67 65 6e 65 72 61  s process genera
20950 74 65 73 20 61 6e 20 69 6e 76 61 6c 69 64 20 55  tes an invalid U
20960 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 2c 0a 2a  TF-8 encoding,.*
20970 2a 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72  * the results ar
20980 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  e undefined..**.
20990 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69  ** <b>Note to Wi
209a0 6e 64 6f 77 73 20 75 73 65 72 73 3a 3c 2f 62 3e  ndows users:</b>
209b0 20 20 54 68 65 20 65 6e 63 6f 64 69 6e 67 20 75    The encoding u
209c0 73 65 64 20 66 6f 72 20 74 68 65 20 66 69 6c 65  sed for the file
209d0 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  name argument.**
209e0 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   of sqlite3_open
209f0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f  () and sqlite3_o
20a00 70 65 6e 5f 76 32 28 29 20 6d 75 73 74 20 62 65  pen_v2() must be
20a10 20 55 54 46 2d 38 2c 20 6e 6f 74 20 77 68 61 74   UTF-8, not what
20a20 65 76 65 72 0a 2a 2a 20 63 6f 64 65 70 61 67 65  ever.** codepage
20a30 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 64 65   is currently de
20a40 66 69 6e 65 64 2e 20 20 46 69 6c 65 6e 61 6d 65  fined.  Filename
20a50 73 20 63 6f 6e 74 61 69 6e 69 6e 67 20 69 6e 74  s containing int
20a60 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68  ernational.** ch
20a70 61 72 61 63 74 65 72 73 20 6d 75 73 74 20 62 65  aracters must be
20a80 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 55 54   converted to UT
20a90 46 2d 38 20 70 72 69 6f 72 20 74 6f 20 70 61 73  F-8 prior to pas
20aa0 73 69 6e 67 20 74 68 65 6d 20 69 6e 74 6f 0a 2a  sing them into.*
20ab0 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  * sqlite3_open()
20ac0 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   or sqlite3_open
20ad0 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e  _v2()..**.** <b>
20ae0 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 20  Note to Windows 
20af0 52 75 6e 74 69 6d 65 20 75 73 65 72 73 3a 3c 2f  Runtime users:</
20b00 62 3e 20 20 54 68 65 20 74 65 6d 70 6f 72 61 72  b>  The temporar
20b10 79 20 64 69 72 65 63 74 6f 72 79 20 6d 75 73 74  y directory must
20b20 20 62 65 20 73 65 74 0a 2a 2a 20 70 72 69 6f 72   be set.** prior
20b30 20 74 6f 20 63 61 6c 6c 69 6e 67 20 73 71 6c 69   to calling sqli
20b40 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71  te3_open() or sq
20b50 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e  lite3_open_v2().
20b60 20 20 4f 74 68 65 72 77 69 73 65 2c 20 76 61 72    Otherwise, var
20b70 69 6f 75 73 0a 2a 2a 20 66 65 61 74 75 72 65 73  ious.** features
20b80 20 74 68 61 74 20 72 65 71 75 69 72 65 20 74 68   that require th
20b90 65 20 75 73 65 20 6f 66 20 74 65 6d 70 6f 72 61  e use of tempora
20ba0 72 79 20 66 69 6c 65 73 20 6d 61 79 20 66 61 69  ry files may fai
20bb0 6c 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  l..**.** See als
20bc0 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 74 65 6d 70  o: [sqlite3_temp
20bd0 5f 64 69 72 65 63 74 6f 72 79 5d 0a 2a 2f 0a 69  _directory].*/.i
20be0 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  nt sqlite3_open(
20bf0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66  .  const char *f
20c00 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61  ilename,   /* Da
20c10 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20  tabase filename 
20c20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c  (UTF-8) */.  sql
20c30 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20  ite3 **ppDb     
20c40 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c       /* OUT: SQL
20c50 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f  ite db handle */
20c60 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
20c70 6f 70 65 6e 31 36 28 0a 20 20 63 6f 6e 73 74 20  open16(.  const 
20c80 76 6f 69 64 20 2a 66 69 6c 65 6e 61 6d 65 2c 20  void *filename, 
20c90 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69    /* Database fi
20ca0 6c 65 6e 61 6d 65 20 28 55 54 46 2d 31 36 29 20  lename (UTF-16) 
20cb0 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70  */.  sqlite3 **p
20cc0 70 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20  pDb          /* 
20cd0 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68  OUT: SQLite db h
20ce0 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20  andle */.);.int 
20cf0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
20d00 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66  .  const char *f
20d10 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61  ilename,   /* Da
20d20 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20  tabase filename 
20d30 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c  (UTF-8) */.  sql
20d40 69 74 65 33 20 2a 2a 70 70 44 62 2c 20 20 20 20  ite3 **ppDb,    
20d50 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c       /* OUT: SQL
20d60 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f  ite db handle */
20d70 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 20 20  .  int flags,   
20d80 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46 6c             /* Fl
20d90 61 67 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  ags */.  const c
20da0 68 61 72 20 2a 7a 56 66 73 20 20 20 20 20 20 20  har *zVfs       
20db0 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 56 46 53 20   /* Name of VFS 
20dc0 6d 6f 64 75 6c 65 20 74 6f 20 75 73 65 20 2a 2f  module to use */
20dd0 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
20de0 52 45 46 3a 20 4f 62 74 61 69 6e 20 56 61 6c 75  REF: Obtain Valu
20df0 65 73 20 46 6f 72 20 55 52 49 20 50 61 72 61 6d  es For URI Param
20e00 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  eters.**.** Thes
20e10 65 20 61 72 65 20 75 74 69 6c 69 74 79 20 72 6f  e are utility ro
20e20 75 74 69 6e 65 73 2c 20 75 73 65 66 75 6c 20 74  utines, useful t
20e30 6f 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61  o VFS implementa
20e40 74 69 6f 6e 73 2c 20 74 68 61 74 20 63 68 65 63  tions, that chec
20e50 6b 0a 2a 2a 20 74 6f 20 73 65 65 20 69 66 20 61  k.** to see if a
20e60 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77   database file w
20e70 61 73 20 61 20 55 52 49 20 74 68 61 74 20 63 6f  as a URI that co
20e80 6e 74 61 69 6e 65 64 20 61 20 73 70 65 63 69 66  ntained a specif
20e90 69 63 20 71 75 65 72 79 20 0a 2a 2a 20 70 61 72  ic query .** par
20ea0 61 6d 65 74 65 72 2c 20 61 6e 64 20 69 66 20 73  ameter, and if s
20eb0 6f 20 6f 62 74 61 69 6e 73 20 74 68 65 20 76 61  o obtains the va
20ec0 6c 75 65 20 6f 66 20 74 68 61 74 20 71 75 65 72  lue of that quer
20ed0 79 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a  y parameter..**.
20ee0 2a 2a 20 49 66 20 46 20 69 73 20 74 68 65 20 64  ** If F is the d
20ef0 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65  atabase filename
20f00 20 70 6f 69 6e 74 65 72 20 70 61 73 73 65 64 20   pointer passed 
20f10 69 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29  into the xOpen()
20f20 20 6d 65 74 68 6f 64 20 6f 66 20 0a 2a 2a 20 61   method of .** a
20f30 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
20f40 69 6f 6e 20 77 68 65 6e 20 74 68 65 20 66 6c 61  ion when the fla
20f50 67 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  gs parameter to 
20f60 78 4f 70 65 6e 28 29 20 68 61 73 20 6f 6e 65 20  xOpen() has one 
20f70 6f 72 20 0a 2a 2a 20 6d 6f 72 65 20 6f 66 20 74  or .** more of t
20f80 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
20f90 55 52 49 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  URI] or [SQLITE_
20fa0 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 20 62 69  OPEN_MAIN_DB] bi
20fb0 74 73 20 73 65 74 20 61 6e 64 0a 2a 2a 20 50 20  ts set and.** P 
20fc0 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  is the name of t
20fd0 68 65 20 71 75 65 72 79 20 70 61 72 61 6d 65 74  he query paramet
20fe0 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69  er, then.** sqli
20ff0 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65  te3_uri_paramete
21000 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73 20 74  r(F,P) returns t
21010 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  he value of the 
21020 50 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 69  P.** parameter i
21030 66 20 69 74 20 65 78 69 73 74 73 20 6f 72 20 61  f it exists or a
21040 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66   NULL pointer if
21050 20 50 20 64 6f 65 73 20 6e 6f 74 20 61 70 70 65   P does not appe
21060 61 72 20 61 73 20 61 20 0a 2a 2a 20 71 75 65 72  ar as a .** quer
21070 79 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 46  y parameter on F
21080 2e 20 20 49 66 20 50 20 69 73 20 61 20 71 75 65  .  If P is a que
21090 72 79 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20  ry parameter of 
210a0 46 0a 2a 2a 20 68 61 73 20 6e 6f 20 65 78 70 6c  F.** has no expl
210b0 69 63 69 74 20 76 61 6c 75 65 2c 20 74 68 65 6e  icit value, then
210c0 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72   sqlite3_uri_par
210d0 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74 75  ameter(F,P) retu
210e0 72 6e 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72  rns.** a pointer
210f0 20 74 6f 20 61 6e 20 65 6d 70 74 79 20 73 74 72   to an empty str
21100 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ing..**.** The s
21110 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65  qlite3_uri_boole
21120 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e  an(F,P,B) routin
21130 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 50  e assumes that P
21140 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e 0a 2a 2a   is a boolean.**
21150 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72   parameter and r
21160 65 74 75 72 6e 73 20 74 72 75 65 20 28 31 29 20  eturns true (1) 
21170 6f 72 20 66 61 6c 73 65 20 28 30 29 20 61 63 63  or false (0) acc
21180 6f 72 64 69 6e 67 20 74 6f 20 74 68 65 20 76 61  ording to the va
21190 6c 75 65 0a 2a 2a 20 6f 66 20 50 2e 20 20 54 68  lue.** of P.  Th
211a0 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f  e sqlite3_uri_bo
211b0 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75  olean(F,P,B) rou
211c0 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 72 75  tine returns tru
211d0 65 20 28 31 29 20 69 66 20 74 68 65 0a 2a 2a 20  e (1) if the.** 
211e0 76 61 6c 75 65 20 6f 66 20 71 75 65 72 79 20 70  value of query p
211f0 61 72 61 6d 65 74 65 72 20 50 20 69 73 20 6f 6e  arameter P is on
21200 65 20 6f 66 20 22 79 65 73 22 2c 20 22 74 72 75  e of "yes", "tru
21210 65 22 2c 20 6f 72 20 22 6f 6e 22 20 69 6e 20 61  e", or "on" in a
21220 6e 79 0a 2a 2a 20 63 61 73 65 20 6f 72 20 69 66  ny.** case or if
21230 20 74 68 65 20 76 61 6c 75 65 20 62 65 67 69 6e   the value begin
21240 73 20 77 69 74 68 20 61 20 6e 6f 6e 2d 7a 65 72  s with a non-zer
21250 6f 20 6e 75 6d 62 65 72 2e 20 20 54 68 65 20 0a  o number.  The .
21260 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62  ** sqlite3_uri_b
21270 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f  oolean(F,P,B) ro
21280 75 74 69 6e 65 73 20 72 65 74 75 72 6e 73 20 66  utines returns f
21290 61 6c 73 65 20 28 30 29 20 69 66 20 74 68 65 20  alse (0) if the 
212a0 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 71 75 65 72  value of.** quer
212b0 79 20 70 61 72 61 6d 65 74 65 72 20 50 20 69 73  y parameter P is
212c0 20 6f 6e 65 20 6f 66 20 22 6e 6f 22 2c 20 22 66   one of "no", "f
212d0 61 6c 73 65 22 2c 20 6f 72 20 22 6f 66 66 22 20  alse", or "off" 
212e0 69 6e 20 61 6e 79 20 63 61 73 65 20 6f 72 0a 2a  in any case or.*
212f0 2a 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 62  * if the value b
21300 65 67 69 6e 73 20 77 69 74 68 20 61 20 6e 75 6d  egins with a num
21310 65 72 69 63 20 7a 65 72 6f 2e 20 20 49 66 20 50  eric zero.  If P
21320 20 69 73 20 6e 6f 74 20 61 20 71 75 65 72 79 0a   is not a query.
21330 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20  ** parameter on 
21340 46 20 6f 72 20 69 66 20 74 68 65 20 76 61 6c 75  F or if the valu
21350 65 20 6f 66 20 50 20 69 73 20 64 6f 65 73 20 6e  e of P is does n
21360 6f 74 20 6d 61 74 63 68 20 61 6e 79 20 6f 66 20  ot match any of 
21370 74 68 65 0a 2a 2a 20 61 62 6f 76 65 2c 20 74 68  the.** above, th
21380 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62  en sqlite3_uri_b
21390 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 65  oolean(F,P,B) re
213a0 74 75 72 6e 73 20 28 42 21 3d 30 29 2e 0a 2a 2a  turns (B!=0)..**
213b0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
213c0 75 72 69 5f 69 6e 74 36 34 28 46 2c 50 2c 44 29  uri_int64(F,P,D)
213d0 20 72 6f 75 74 69 6e 65 20 63 6f 6e 76 65 72 74   routine convert
213e0 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50  s the value of P
213f0 20 69 6e 74 6f 20 61 0a 2a 2a 20 36 34 2d 62 69   into a.** 64-bi
21400 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  t signed integer
21410 20 61 6e 64 20 72 65 74 75 72 6e 73 20 74 68 61   and returns tha
21420 74 20 69 6e 74 65 67 65 72 2c 20 6f 72 20 44 20  t integer, or D 
21430 69 66 20 50 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a  if P does not.**
21440 20 65 78 69 73 74 2e 20 20 49 66 20 74 68 65 20   exist.  If the 
21450 76 61 6c 75 65 20 6f 66 20 50 20 69 73 20 73 6f  value of P is so
21460 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68  mething other th
21470 61 6e 20 61 6e 20 69 6e 74 65 67 65 72 2c 20 74  an an integer, t
21480 68 65 6e 0a 2a 2a 20 7a 65 72 6f 20 69 73 20 72  hen.** zero is r
21490 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 0a 2a 2a 20  eturned..** .** 
214a0 49 66 20 46 20 69 73 20 61 20 4e 55 4c 4c 20 70  If F is a NULL p
214b0 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 73 71 6c  ointer, then sql
214c0 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74  ite3_uri_paramet
214d0 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73 20  er(F,P) returns 
214e0 4e 55 4c 4c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69  NULL and.** sqli
214f0 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28  te3_uri_boolean(
21500 46 2c 50 2c 42 29 20 72 65 74 75 72 6e 73 20 42  F,P,B) returns B
21510 2e 20 20 49 66 20 46 20 69 73 20 6e 6f 74 20 61  .  If F is not a
21520 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61 6e   NULL pointer an
21530 64 0a 2a 2a 20 69 73 20 6e 6f 74 20 61 20 64 61  d.** is not a da
21540 74 61 62 61 73 65 20 66 69 6c 65 20 70 61 74 68  tabase file path
21550 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20 74 68 61  name pointer tha
21560 74 20 53 51 4c 69 74 65 20 70 61 73 73 65 64 20  t SQLite passed 
21570 69 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e 0a 2a  into the xOpen.*
21580 2a 20 56 46 53 20 6d 65 74 68 6f 64 2c 20 74 68  * VFS method, th
21590 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
215a0 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  of this routine 
215b0 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64  is undefined and
215c0 20 70 72 6f 62 61 62 6c 79 0a 2a 2a 20 75 6e 64   probably.** und
215d0 65 73 69 72 61 62 6c 65 2e 0a 2a 2f 0a 63 6f 6e  esirable..*/.con
215e0 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
215f0 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 63  _uri_parameter(c
21600 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65  onst char *zFile
21610 6e 61 6d 65 2c 20 63 6f 6e 73 74 20 63 68 61 72  name, const char
21620 20 2a 7a 50 61 72 61 6d 29 3b 0a 69 6e 74 20 73   *zParam);.int s
21630 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65  qlite3_uri_boole
21640 61 6e 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  an(const char *z
21650 46 69 6c 65 2c 20 63 6f 6e 73 74 20 63 68 61 72  File, const char
21660 20 2a 7a 50 61 72 61 6d 2c 20 69 6e 74 20 62 44   *zParam, int bD
21670 65 66 61 75 6c 74 29 3b 0a 73 71 6c 69 74 65 33  efault);.sqlite3
21680 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 75  _int64 sqlite3_u
21690 72 69 5f 69 6e 74 36 34 28 63 6f 6e 73 74 20 63  ri_int64(const c
216a0 68 61 72 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  har*, const char
216b0 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
216c0 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  );.../*.** CAPI3
216d0 52 45 46 3a 20 45 72 72 6f 72 20 43 6f 64 65 73  REF: Error Codes
216e0 20 41 6e 64 20 4d 65 73 73 61 67 65 73 0a 2a 2a   And Messages.**
216f0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
21700 5f 65 72 72 63 6f 64 65 28 29 20 69 6e 74 65 72  _errcode() inter
21710 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
21720 20 6e 75 6d 65 72 69 63 20 5b 72 65 73 75 6c 74   numeric [result
21730 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78   code] or.** [ex
21740 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
21750 64 65 5d 20 66 6f 72 20 74 68 65 20 6d 6f 73 74  de] for the most
21760 20 72 65 63 65 6e 74 20 66 61 69 6c 65 64 20 73   recent failed s
21770 71 6c 69 74 65 33 5f 2a 20 41 50 49 20 63 61 6c  qlite3_* API cal
21780 6c 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20  l.** associated 
21790 77 69 74 68 20 61 20 5b 64 61 74 61 62 61 73 65  with a [database
217a0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 49 66   connection]. If
217b0 20 61 20 70 72 69 6f 72 20 41 50 49 20 63 61 6c   a prior API cal
217c0 6c 20 66 61 69 6c 65 64 0a 2a 2a 20 62 75 74 20  l failed.** but 
217d0 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
217e0 41 50 49 20 63 61 6c 6c 20 73 75 63 63 65 65 64  API call succeed
217f0 65 64 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76  ed, the return v
21800 61 6c 75 65 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c  alue from.** sql
21810 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20 69  ite3_errcode() i
21820 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 5e 54  s undefined.  ^T
21830 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e  he sqlite3_exten
21840 64 65 64 5f 65 72 72 63 6f 64 65 28 29 0a 2a 2a  ded_errcode().**
21850 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 68   interface is th
21860 65 20 73 61 6d 65 20 65 78 63 65 70 74 20 74 68  e same except th
21870 61 74 20 69 74 20 61 6c 77 61 79 73 20 72 65 74  at it always ret
21880 75 72 6e 73 20 74 68 65 20 0a 2a 2a 20 5b 65 78  urns the .** [ex
21890 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
218a0 64 65 5d 20 65 76 65 6e 20 77 68 65 6e 20 65 78  de] even when ex
218b0 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
218c0 64 65 73 20 61 72 65 0a 2a 2a 20 64 69 73 61 62  des are.** disab
218d0 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  led..**.** ^The 
218e0 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29  sqlite3_errmsg()
218f0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 65 72 72   and sqlite3_err
21900 6d 73 67 31 36 28 29 20 72 65 74 75 72 6e 20 45  msg16() return E
21910 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 0a  nglish-language.
21920 2a 2a 20 74 65 78 74 20 74 68 61 74 20 64 65 73  ** text that des
21930 63 72 69 62 65 73 20 74 68 65 20 65 72 72 6f 72  cribes the error
21940 2c 20 61 73 20 65 69 74 68 65 72 20 55 54 46 2d  , as either UTF-
21950 38 20 6f 72 20 55 54 46 2d 31 36 20 72 65 73 70  8 or UTF-16 resp
21960 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 28 4d  ectively..** ^(M
21970 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68  emory to hold th
21980 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  e error message 
21990 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65  string is manage
219a0 64 20 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a 2a  d internally..**
219b0 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
219c0 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74   does not need t
219d0 6f 20 77 6f 72 72 79 20 61 62 6f 75 74 20 66 72  o worry about fr
219e0 65 65 69 6e 67 20 74 68 65 20 72 65 73 75 6c 74  eeing the result
219f0 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68  ..** However, th
21a00 65 20 65 72 72 6f 72 20 73 74 72 69 6e 67 20 6d  e error string m
21a10 69 67 68 74 20 62 65 20 6f 76 65 72 77 72 69 74  ight be overwrit
21a20 74 65 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74  ten or deallocat
21a30 65 64 20 62 79 0a 2a 2a 20 73 75 62 73 65 71 75  ed by.** subsequ
21a40 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 6f 74 68  ent calls to oth
21a50 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  er SQLite interf
21a60 61 63 65 20 66 75 6e 63 74 69 6f 6e 73 2e 29 5e  ace functions.)^
21a70 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
21a80 74 65 33 5f 65 72 72 73 74 72 28 29 20 69 6e 74  te3_errstr() int
21a90 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
21aa0 68 65 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75  he English-langu
21ab0 61 67 65 20 74 65 78 74 0a 2a 2a 20 74 68 61 74  age text.** that
21ac0 20 64 65 73 63 72 69 62 65 73 20 74 68 65 20 5b   describes the [
21ad0 72 65 73 75 6c 74 20 63 6f 64 65 5d 2c 20 61 73  result code], as
21ae0 20 55 54 46 2d 38 2e 0a 2a 2a 20 5e 28 4d 65 6d   UTF-8..** ^(Mem
21af0 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20  ory to hold the 
21b00 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74  error message st
21b10 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 20  ring is managed 
21b20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 61 6e  internally.** an
21b30 64 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 66 72  d must not be fr
21b40 65 65 64 20 62 79 20 74 68 65 20 61 70 70 6c 69  eed by the appli
21b50 63 61 74 69 6f 6e 29 5e 2e 0a 2a 2a 0a 2a 2a 20  cation)^..**.** 
21b60 57 68 65 6e 20 74 68 65 20 73 65 72 69 61 6c 69  When the seriali
21b70 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  zed [threading m
21b80 6f 64 65 5d 20 69 73 20 69 6e 20 75 73 65 2c 20  ode] is in use, 
21b90 69 74 20 6d 69 67 68 74 20 62 65 20 74 68 65 0a  it might be the.
21ba0 2a 2a 20 63 61 73 65 20 74 68 61 74 20 61 20 73  ** case that a s
21bb0 65 63 6f 6e 64 20 65 72 72 6f 72 20 6f 63 63 75  econd error occu
21bc0 72 73 20 6f 6e 20 61 20 73 65 70 61 72 61 74 65  rs on a separate
21bd0 20 74 68 72 65 61 64 20 69 6e 20 62 65 74 77 65   thread in betwe
21be0 65 6e 0a 2a 2a 20 74 68 65 20 74 69 6d 65 20 6f  en.** the time o
21bf0 66 20 74 68 65 20 66 69 72 73 74 20 65 72 72 6f  f the first erro
21c00 72 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 20 74  r and the call t
21c10 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63  o these interfac
21c20 65 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 68 61 74  es..** When that
21c30 20 68 61 70 70 65 6e 73 2c 20 74 68 65 20 73 65   happens, the se
21c40 63 6f 6e 64 20 65 72 72 6f 72 20 77 69 6c 6c 20  cond error will 
21c50 62 65 20 72 65 70 6f 72 74 65 64 20 73 69 6e 63  be reported sinc
21c60 65 20 74 68 65 73 65 0a 2a 2a 20 69 6e 74 65 72  e these.** inter
21c70 66 61 63 65 73 20 61 6c 77 61 79 73 20 72 65 70  faces always rep
21c80 6f 72 74 20 74 68 65 20 6d 6f 73 74 20 72 65 63  ort the most rec
21c90 65 6e 74 20 72 65 73 75 6c 74 2e 20 20 54 6f 20  ent result.  To 
21ca0 61 76 6f 69 64 0a 2a 2a 20 74 68 69 73 2c 20 65  avoid.** this, e
21cb0 61 63 68 20 74 68 72 65 61 64 20 63 61 6e 20 6f  ach thread can o
21cc0 62 74 61 69 6e 20 65 78 63 6c 75 73 69 76 65 20  btain exclusive 
21cd0 75 73 65 20 6f 66 20 74 68 65 20 5b 64 61 74 61  use of the [data
21ce0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
21cf0 20 44 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b 69 6e   D.** by invokin
21d00 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  g [sqlite3_mutex
21d10 5f 65 6e 74 65 72 5d 28 5b 73 71 6c 69 74 65 33  _enter]([sqlite3
21d20 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 62  _db_mutex](D)) b
21d30 65 66 6f 72 65 20 62 65 67 69 6e 6e 69 6e 67 0a  efore beginning.
21d40 2a 2a 20 74 6f 20 75 73 65 20 44 20 61 6e 64 20  ** to use D and 
21d50 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65  invoking [sqlite
21d60 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 5d 28 5b  3_mutex_leave]([
21d70 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78  sqlite3_db_mutex
21d80 5d 28 44 29 29 20 61 66 74 65 72 0a 2a 2a 20 61  ](D)) after.** a
21d90 6c 6c 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20  ll calls to the 
21da0 69 6e 74 65 72 66 61 63 65 73 20 6c 69 73 74 65  interfaces liste
21db0 64 20 68 65 72 65 20 61 72 65 20 63 6f 6d 70 6c  d here are compl
21dc0 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61  eted..**.** If a
21dd0 6e 20 69 6e 74 65 72 66 61 63 65 20 66 61 69 6c  n interface fail
21de0 73 20 77 69 74 68 20 53 51 4c 49 54 45 5f 4d 49  s with SQLITE_MI
21df0 53 55 53 45 2c 20 74 68 61 74 20 6d 65 61 6e 73  SUSE, that means
21e00 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 0a 2a   the interface.*
21e10 2a 20 77 61 73 20 69 6e 76 6f 6b 65 64 20 69 6e  * was invoked in
21e20 63 6f 72 72 65 63 74 6c 79 20 62 79 20 74 68 65  correctly by the
21e30 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 49   application.  I
21e40 6e 20 74 68 61 74 20 63 61 73 65 2c 20 74 68 65  n that case, the
21e50 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65 20 61  .** error code a
21e60 6e 64 20 6d 65 73 73 61 67 65 20 6d 61 79 20 6f  nd message may o
21e70 72 20 6d 61 79 20 6e 6f 74 20 62 65 20 73 65 74  r may not be set
21e80 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
21e90 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33  _errcode(sqlite3
21ea0 20 2a 64 62 29 3b 0a 69 6e 74 20 73 71 6c 69 74   *db);.int sqlit
21eb0 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63  e3_extended_errc
21ec0 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29  ode(sqlite3 *db)
21ed0 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  ;.const char *sq
21ee0 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 73 71 6c  lite3_errmsg(sql
21ef0 69 74 65 33 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f  ite3*);.const vo
21f00 69 64 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d  id *sqlite3_errm
21f10 73 67 31 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a  sg16(sqlite3*);.
21f20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
21f30 74 65 33 5f 65 72 72 73 74 72 28 69 6e 74 29 3b  te3_errstr(int);
21f40 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
21f50 3a 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20  : SQL Statement 
21f60 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52  Object.** KEYWOR
21f70 44 53 3a 20 7b 70 72 65 70 61 72 65 64 20 73 74  DS: {prepared st
21f80 61 74 65 6d 65 6e 74 7d 20 7b 70 72 65 70 61 72  atement} {prepar
21f90 65 64 20 73 74 61 74 65 6d 65 6e 74 73 7d 0a 2a  ed statements}.*
21fa0 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65  *.** An instance
21fb0 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20   of this object 
21fc0 72 65 70 72 65 73 65 6e 74 73 20 61 20 73 69 6e  represents a sin
21fd0 67 6c 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  gle SQL statemen
21fe0 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63  t..** This objec
21ff0 74 20 69 73 20 76 61 72 69 6f 75 73 6c 79 20 6b  t is variously k
22000 6e 6f 77 6e 20 61 73 20 61 20 22 70 72 65 70 61  nown as a "prepa
22010 72 65 64 20 73 74 61 74 65 6d 65 6e 74 22 20 6f  red statement" o
22020 72 20 61 0a 2a 2a 20 22 63 6f 6d 70 69 6c 65 64  r a.** "compiled
22030 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 22 20   SQL statement" 
22040 6f 72 20 73 69 6d 70 6c 79 20 61 73 20 61 20 22  or simply as a "
22050 73 74 61 74 65 6d 65 6e 74 22 2e 0a 2a 2a 0a 2a  statement"..**.*
22060 2a 20 54 68 65 20 6c 69 66 65 20 6f 66 20 61 20  * The life of a 
22070 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74  statement object
22080 20 67 6f 65 73 20 73 6f 6d 65 74 68 69 6e 67 20   goes something 
22090 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a  like this:.**.**
220a0 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72   <ol>.** <li> Cr
220b0 65 61 74 65 20 74 68 65 20 6f 62 6a 65 63 74 20  eate the object 
220c0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70  using [sqlite3_p
220d0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
220e0 61 20 72 65 6c 61 74 65 64 0a 2a 2a 20 20 20 20  a related.**    
220f0 20 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 3c    function..** <
22100 6c 69 3e 20 42 69 6e 64 20 76 61 6c 75 65 73 20  li> Bind values 
22110 74 6f 20 5b 68 6f 73 74 20 70 61 72 61 6d 65 74  to [host paramet
22120 65 72 73 5d 20 75 73 69 6e 67 20 74 68 65 20 73  ers] using the s
22130 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 0a  qlite3_bind_*().
22140 2a 2a 20 20 20 20 20 20 69 6e 74 65 72 66 61 63  **      interfac
22150 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20  es..** <li> Run 
22160 74 68 65 20 53 51 4c 20 62 79 20 63 61 6c 6c 69  the SQL by calli
22170 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ng [sqlite3_step
22180 28 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  ()] one or more 
22190 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52  times..** <li> R
221a0 65 73 65 74 20 74 68 65 20 73 74 61 74 65 6d 65  eset the stateme
221b0 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  nt using [sqlite
221c0 33 5f 72 65 73 65 74 28 29 5d 20 74 68 65 6e 20  3_reset()] then 
221d0 67 6f 20 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20  go back.**      
221e0 74 6f 20 73 74 65 70 20 32 2e 20 20 44 6f 20 74  to step 2.  Do t
221f0 68 69 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65  his zero or more
22200 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20   times..** <li> 
22210 44 65 73 74 72 6f 79 20 74 68 65 20 6f 62 6a 65  Destroy the obje
22220 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ct using [sqlite
22230 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a  3_finalize()]..*
22240 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65  * </ol>.**.** Re
22250 66 65 72 20 74 6f 20 64 6f 63 75 6d 65 6e 74 61  fer to documenta
22260 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75  tion on individu
22270 61 6c 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65  al methods above
22280 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a   for additional.
22290 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  ** information..
222a0 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
222b0 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 73  t sqlite3_stmt s
222c0 71 6c 69 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a  qlite3_stmt;../*
222d0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75  .** CAPI3REF: Ru
222e0 6e 2d 74 69 6d 65 20 4c 69 6d 69 74 73 0a 2a 2a  n-time Limits.**
222f0 0a 2a 2a 20 5e 28 54 68 69 73 20 69 6e 74 65 72  .** ^(This inter
22300 66 61 63 65 20 61 6c 6c 6f 77 73 20 74 68 65 20  face allows the 
22310 73 69 7a 65 20 6f 66 20 76 61 72 69 6f 75 73 20  size of various 
22320 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65  constructs to be
22330 20 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61   limited.** on a
22340 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63   connection by c
22350 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 2e  onnection basis.
22360 20 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61    The first para
22370 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20  meter is the.** 
22380 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
22390 74 69 6f 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69  tion] whose limi
223a0 74 20 69 73 20 74 6f 20 62 65 20 73 65 74 20 6f  t is to be set o
223b0 72 20 71 75 65 72 69 65 64 2e 20 20 54 68 65 0a  r queried.  The.
223c0 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  ** second parame
223d0 74 65 72 20 69 73 20 6f 6e 65 20 6f 66 20 74 68  ter is one of th
223e0 65 20 5b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72  e [limit categor
223f0 69 65 73 5d 20 74 68 61 74 20 64 65 66 69 6e 65  ies] that define
22400 20 61 0a 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63   a.** class of c
22410 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 20  onstructs to be 
22420 73 69 7a 65 20 6c 69 6d 69 74 65 64 2e 20 20 54  size limited.  T
22430 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
22440 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77  er is the.** new
22450 20 6c 69 6d 69 74 20 66 6f 72 20 74 68 61 74 20   limit for that 
22460 63 6f 6e 73 74 72 75 63 74 2e 29 5e 0a 2a 2a 0a  construct.)^.**.
22470 2a 2a 20 5e 49 66 20 74 68 65 20 6e 65 77 20 6c  ** ^If the new l
22480 69 6d 69 74 20 69 73 20 61 20 6e 65 67 61 74 69  imit is a negati
22490 76 65 20 6e 75 6d 62 65 72 2c 20 74 68 65 20 6c  ve number, the l
224a0 69 6d 69 74 20 69 73 20 75 6e 63 68 61 6e 67 65  imit is unchange
224b0 64 2e 0a 2a 2a 20 5e 28 46 6f 72 20 65 61 63 68  d..** ^(For each
224c0 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 20   limit category 
224d0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 3c 69 3e  SQLITE_LIMIT_<i>
224e0 4e 41 4d 45 3c 2f 69 3e 20 74 68 65 72 65 20 69  NAME</i> there i
224f0 73 20 61 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20  s a .** [limits 
22500 7c 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75  | hard upper bou
22510 6e 64 5d 0a 2a 2a 20 73 65 74 20 61 74 20 63 6f  nd].** set at co
22520 6d 70 69 6c 65 2d 74 69 6d 65 20 62 79 20 61 20  mpile-time by a 
22530 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
22540 61 63 72 6f 20 63 61 6c 6c 65 64 0a 2a 2a 20 5b  acro called.** [
22550 6c 69 6d 69 74 73 20 7c 20 53 51 4c 49 54 45 5f  limits | SQLITE_
22560 4d 41 58 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 5d  MAX_<i>NAME</i>]
22570 2e 0a 2a 2a 20 28 54 68 65 20 22 5f 4c 49 4d 49  ..** (The "_LIMI
22580 54 5f 22 20 69 6e 20 74 68 65 20 6e 61 6d 65 20  T_" in the name 
22590 69 73 20 63 68 61 6e 67 65 64 20 74 6f 20 22 5f  is changed to "_
225a0 4d 41 58 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41 74  MAX_".))^.** ^At
225b0 74 65 6d 70 74 73 20 74 6f 20 69 6e 63 72 65 61  tempts to increa
225c0 73 65 20 61 20 6c 69 6d 69 74 20 61 62 6f 76 65  se a limit above
225d0 20 69 74 73 20 68 61 72 64 20 75 70 70 65 72 20   its hard upper 
225e0 62 6f 75 6e 64 20 61 72 65 0a 2a 2a 20 73 69 6c  bound are.** sil
225f0 65 6e 74 6c 79 20 74 72 75 6e 63 61 74 65 64 20  ently truncated 
22600 74 6f 20 74 68 65 20 68 61 72 64 20 75 70 70 65  to the hard uppe
22610 72 20 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e  r bound..**.** ^
22620 52 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68  Regardless of wh
22630 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65  ether or not the
22640 20 6c 69 6d 69 74 20 77 61 73 20 63 68 61 6e 67   limit was chang
22650 65 64 2c 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c  ed, the .** [sql
22660 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 20 69 6e  ite3_limit()] in
22670 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
22680 74 68 65 20 70 72 69 6f 72 20 76 61 6c 75 65 20  the prior value 
22690 6f 66 20 74 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a  of the limit..**
226a0 20 5e 48 65 6e 63 65 2c 20 74 6f 20 66 69 6e 64   ^Hence, to find
226b0 20 74 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c   the current val
226c0 75 65 20 6f 66 20 61 20 6c 69 6d 69 74 20 77 69  ue of a limit wi
226d0 74 68 6f 75 74 20 63 68 61 6e 67 69 6e 67 20 69  thout changing i
226e0 74 2c 0a 2a 2a 20 73 69 6d 70 6c 79 20 69 6e 76  t,.** simply inv
226f0 6f 6b 65 20 74 68 69 73 20 69 6e 74 65 72 66 61  oke this interfa
22700 63 65 20 77 69 74 68 20 74 68 65 20 74 68 69 72  ce with the thir
22710 64 20 70 61 72 61 6d 65 74 65 72 20 73 65 74 20  d parameter set 
22720 74 6f 20 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e  to -1..**.** Run
22730 2d 74 69 6d 65 20 6c 69 6d 69 74 73 20 61 72 65  -time limits are
22740 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73   intended for us
22750 65 20 69 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  e in application
22760 73 20 74 68 61 74 20 6d 61 6e 61 67 65 0a 2a 2a  s that manage.**
22770 20 62 6f 74 68 20 74 68 65 69 72 20 6f 77 6e 20   both their own 
22780 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73  internal databas
22790 65 20 61 6e 64 20 61 6c 73 6f 20 64 61 74 61 62  e and also datab
227a0 61 73 65 73 20 74 68 61 74 20 61 72 65 20 63 6f  ases that are co
227b0 6e 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 75  ntrolled.** by u
227c0 6e 74 72 75 73 74 65 64 20 65 78 74 65 72 6e 61  ntrusted externa
227d0 6c 20 73 6f 75 72 63 65 73 2e 20 20 41 6e 20 65  l sources.  An e
227e0 78 61 6d 70 6c 65 20 61 70 70 6c 69 63 61 74 69  xample applicati
227f0 6f 6e 20 6d 69 67 68 74 20 62 65 20 61 0a 2a 2a  on might be a.**
22800 20 77 65 62 20 62 72 6f 77 73 65 72 20 74 68 61   web browser tha
22810 74 20 68 61 73 20 69 74 73 20 6f 77 6e 20 64 61  t has its own da
22820 74 61 62 61 73 65 73 20 66 6f 72 20 73 74 6f 72  tabases for stor
22830 69 6e 67 20 68 69 73 74 6f 72 79 20 61 6e 64 0a  ing history and.
22840 2a 2a 20 73 65 70 61 72 61 74 65 20 64 61 74 61  ** separate data
22850 62 61 73 65 73 20 63 6f 6e 74 72 6f 6c 6c 65 64  bases controlled
22860 20 62 79 20 4a 61 76 61 53 63 72 69 70 74 20 61   by JavaScript a
22870 70 70 6c 69 63 61 74 69 6f 6e 73 20 64 6f 77 6e  pplications down
22880 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66 66 20 74 68  loaded.** off th
22890 65 20 49 6e 74 65 72 6e 65 74 2e 20 20 54 68 65  e Internet.  The
228a0 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61   internal databa
228b0 73 65 73 20 63 61 6e 20 62 65 20 67 69 76 65 6e  ses can be given
228c0 20 74 68 65 0a 2a 2a 20 6c 61 72 67 65 2c 20 64   the.** large, d
228d0 65 66 61 75 6c 74 20 6c 69 6d 69 74 73 2e 20 20  efault limits.  
228e0 44 61 74 61 62 61 73 65 73 20 6d 61 6e 61 67 65  Databases manage
228f0 64 20 62 79 20 65 78 74 65 72 6e 61 6c 20 73 6f  d by external so
22900 75 72 63 65 73 20 63 61 6e 0a 2a 2a 20 62 65 20  urces can.** be 
22910 67 69 76 65 6e 20 6d 75 63 68 20 73 6d 61 6c 6c  given much small
22920 65 72 20 6c 69 6d 69 74 73 20 64 65 73 69 67 6e  er limits design
22930 65 64 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20  ed to prevent a 
22940 64 65 6e 69 61 6c 20 6f 66 20 73 65 72 76 69 63  denial of servic
22950 65 0a 2a 2a 20 61 74 74 61 63 6b 2e 20 20 44 65  e.** attack.  De
22960 76 65 6c 6f 70 65 72 73 20 6d 69 67 68 74 20 61  velopers might a
22970 6c 73 6f 20 77 61 6e 74 20 74 6f 20 75 73 65 20  lso want to use 
22980 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  the [sqlite3_set
22990 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 0a 2a  _authorizer()].*
229a0 2a 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 66  * interface to f
229b0 75 72 74 68 65 72 20 63 6f 6e 74 72 6f 6c 20 75  urther control u
229c0 6e 74 72 75 73 74 65 64 20 53 51 4c 2e 20 20 54  ntrusted SQL.  T
229d0 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 64  he size of the d
229e0 61 74 61 62 61 73 65 0a 2a 2a 20 63 72 65 61 74  atabase.** creat
229f0 65 64 20 62 79 20 61 6e 20 75 6e 74 72 75 73 74  ed by an untrust
22a00 65 64 20 73 63 72 69 70 74 20 63 61 6e 20 62 65  ed script can be
22a10 20 63 6f 6e 74 61 69 6e 65 64 20 75 73 69 6e 67   contained using
22a20 20 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67   the.** [max_pag
22a30 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41  e_count] [PRAGMA
22a40 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e  ]..**.** New run
22a50 2d 74 69 6d 65 20 6c 69 6d 69 74 20 63 61 74 65  -time limit cate
22a60 67 6f 72 69 65 73 20 6d 61 79 20 62 65 20 61 64  gories may be ad
22a70 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65  ded in future re
22a80 6c 65 61 73 65 73 2e 0a 2a 2f 0a 69 6e 74 20 73  leases..*/.int s
22a90 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 73 71 6c  qlite3_limit(sql
22aa0 69 74 65 33 2a 2c 20 69 6e 74 20 69 64 2c 20 69  ite3*, int id, i
22ab0 6e 74 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a  nt newVal);../*.
22ac0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e  ** CAPI3REF: Run
22ad0 2d 54 69 6d 65 20 4c 69 6d 69 74 20 43 61 74 65  -Time Limit Cate
22ae0 67 6f 72 69 65 73 0a 2a 2a 20 4b 45 59 57 4f 52  gories.** KEYWOR
22af0 44 53 3a 20 7b 6c 69 6d 69 74 20 63 61 74 65 67  DS: {limit categ
22b00 6f 72 79 7d 20 7b 2a 6c 69 6d 69 74 20 63 61 74  ory} {*limit cat
22b10 65 67 6f 72 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 54  egories}.**.** T
22b20 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 64  hese constants d
22b30 65 66 69 6e 65 20 76 61 72 69 6f 75 73 20 70 65  efine various pe
22b40 72 66 6f 72 6d 61 6e 63 65 20 6c 69 6d 69 74 73  rformance limits
22b50 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20  .** that can be 
22b60 6c 6f 77 65 72 65 64 20 61 74 20 72 75 6e 2d 74  lowered at run-t
22b70 69 6d 65 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ime using [sqlit
22b80 65 33 5f 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20  e3_limit()]..** 
22b90 54 68 65 20 73 79 6e 6f 70 73 69 73 20 6f 66 20  The synopsis of 
22ba0 74 68 65 20 6d 65 61 6e 69 6e 67 73 20 6f 66 20  the meanings of 
22bb0 74 68 65 20 76 61 72 69 6f 75 73 20 6c 69 6d 69  the various limi
22bc0 74 73 20 69 73 20 73 68 6f 77 6e 20 62 65 6c 6f  ts is shown belo
22bd0 77 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c  w..** Additional
22be0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20   information is 
22bf0 61 76 61 69 6c 61 62 6c 65 20 61 74 20 5b 6c 69  available at [li
22c00 6d 69 74 73 20 7c 20 4c 69 6d 69 74 73 20 69 6e  mits | Limits in
22c10 20 53 51 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20   SQLite]..**.** 
22c20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  <dl>.** [[SQLITE
22c30 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 5d 5d 20  _LIMIT_LENGTH]] 
22c40 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
22c50 49 54 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a  IT_LENGTH</dt>.*
22c60 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
22c70 6d 20 73 69 7a 65 20 6f 66 20 61 6e 79 20 73 74  m size of any st
22c80 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 6f 72 20  ring or BLOB or 
22c90 74 61 62 6c 65 20 72 6f 77 2c 20 69 6e 20 62 79  table row, in by
22ca0 74 65 73 2e 3c 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  tes.<dd>)^.**.**
22cb0 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
22cc0 53 51 4c 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c  SQL_LENGTH]] ^(<
22cd0 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
22ce0 53 51 4c 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a  SQL_LENGTH</dt>.
22cf0 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
22d00 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 61 6e 20  um length of an 
22d10 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 69  SQL statement, i
22d20 6e 20 62 79 74 65 73 2e 3c 2f 64 64 3e 29 5e 0a  n bytes.</dd>)^.
22d30 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
22d40 49 4d 49 54 5f 43 4f 4c 55 4d 4e 5d 5d 20 5e 28  IMIT_COLUMN]] ^(
22d50 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
22d60 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20  _COLUMN</dt>.** 
22d70 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
22d80 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
22d90 73 20 69 6e 20 61 20 74 61 62 6c 65 20 64 65 66  s in a table def
22da0 69 6e 69 74 69 6f 6e 20 6f 72 20 69 6e 20 74 68  inition or in th
22db0 65 0a 2a 2a 20 72 65 73 75 6c 74 20 73 65 74 20  e.** result set 
22dc0 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 6f 72  of a [SELECT] or
22dd0 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d   the maximum num
22de0 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
22df0 6e 20 61 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f 72  n an index.** or
22e00 20 69 6e 20 61 6e 20 4f 52 44 45 52 20 42 59 20   in an ORDER BY 
22e10 6f 72 20 47 52 4f 55 50 20 42 59 20 63 6c 61 75  or GROUP BY clau
22e20 73 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  se.</dd>)^.**.**
22e30 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
22e40 45 58 50 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c  EXPR_DEPTH]] ^(<
22e50 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
22e60 45 58 50 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a  EXPR_DEPTH</dt>.
22e70 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
22e80 75 6d 20 64 65 70 74 68 20 6f 66 20 74 68 65 20  um depth of the 
22e90 70 61 72 73 65 20 74 72 65 65 20 6f 6e 20 61 6e  parse tree on an
22ea0 79 20 65 78 70 72 65 73 73 69 6f 6e 2e 3c 2f 64  y expression.</d
22eb0 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d>)^.**.** [[SQL
22ec0 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55  ITE_LIMIT_COMPOU
22ed0 4e 44 5f 53 45 4c 45 43 54 5d 5d 20 5e 28 3c 64  ND_SELECT]] ^(<d
22ee0 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43  t>SQLITE_LIMIT_C
22ef0 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 3c 2f  OMPOUND_SELECT</
22f00 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
22f10 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
22f20 20 74 65 72 6d 73 20 69 6e 20 61 20 63 6f 6d 70   terms in a comp
22f30 6f 75 6e 64 20 53 45 4c 45 43 54 20 73 74 61 74  ound SELECT stat
22f40 65 6d 65 6e 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  ement.</dd>)^.**
22f50 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
22f60 49 54 5f 56 44 42 45 5f 4f 50 5d 5d 20 5e 28 3c  IT_VDBE_OP]] ^(<
22f70 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
22f80 56 44 42 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20  VDBE_OP</dt>.** 
22f90 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
22fa0 6e 75 6d 62 65 72 20 6f 66 20 69 6e 73 74 72 75  number of instru
22fb0 63 74 69 6f 6e 73 20 69 6e 20 61 20 76 69 72 74  ctions in a virt
22fc0 75 61 6c 20 6d 61 63 68 69 6e 65 20 70 72 6f 67  ual machine prog
22fd0 72 61 6d 0a 2a 2a 20 75 73 65 64 20 74 6f 20 69  ram.** used to i
22fe0 6d 70 6c 65 6d 65 6e 74 20 61 6e 20 53 51 4c 20  mplement an SQL 
22ff0 73 74 61 74 65 6d 65 6e 74 2e 20 20 54 68 69 73  statement.  This
23000 20 6c 69 6d 69 74 20 69 73 20 6e 6f 74 20 63 75   limit is not cu
23010 72 72 65 6e 74 6c 79 0a 2a 2a 20 65 6e 66 6f 72  rrently.** enfor
23020 63 65 64 2c 20 74 68 6f 75 67 68 20 74 68 61 74  ced, though that
23030 20 6d 69 67 68 74 20 62 65 20 61 64 64 65 64 20   might be added 
23040 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20 72  in some future r
23050 65 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c  elease of.** SQL
23060 69 74 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  ite.</dd>)^.**.*
23070 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
23080 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 5d 20  _FUNCTION_ARG]] 
23090 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
230a0 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 3c  IT_FUNCTION_ARG<
230b0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
230c0 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
230d0 66 20 61 72 67 75 6d 65 6e 74 73 20 6f 6e 20 61  f arguments on a
230e0 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e 29   function.</dd>)
230f0 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
23100 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 5d  _LIMIT_ATTACHED]
23110 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  ] ^(<dt>SQLITE_L
23120 49 4d 49 54 5f 41 54 54 41 43 48 45 44 3c 2f 64  IMIT_ATTACHED</d
23130 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
23140 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
23150 5b 41 54 54 41 43 48 20 7c 20 61 74 74 61 63 68  [ATTACH | attach
23160 65 64 20 64 61 74 61 62 61 73 65 73 5d 2e 29 5e  ed databases].)^
23170 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
23180 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f  LITE_LIMIT_LIKE_
23190 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 5d 5d  PATTERN_LENGTH]]
231a0 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  .** ^(<dt>SQLITE
231b0 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54  _LIMIT_LIKE_PATT
231c0 45 52 4e 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a  ERN_LENGTH</dt>.
231d0 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
231e0 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65  um length of the
231f0 20 70 61 74 74 65 72 6e 20 61 72 67 75 6d 65 6e   pattern argumen
23200 74 20 74 6f 20 74 68 65 20 5b 4c 49 4b 45 5d 20  t to the [LIKE] 
23210 6f 72 0a 2a 2a 20 5b 47 4c 4f 42 5d 20 6f 70 65  or.** [GLOB] ope
23220 72 61 74 6f 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a  rators.</dd>)^.*
23230 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
23240 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d  MIT_VARIABLE_NUM
23250 42 45 52 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53  BER]].** ^(<dt>S
23260 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49  QLITE_LIMIT_VARI
23270 41 42 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64 74 3e  ABLE_NUMBER</dt>
23280 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
23290 6d 75 6d 20 69 6e 64 65 78 20 6e 75 6d 62 65 72  mum index number
232a0 20 6f 66 20 61 6e 79 20 5b 70 61 72 61 6d 65 74   of any [paramet
232b0 65 72 5d 20 69 6e 20 61 6e 20 53 51 4c 20 73 74  er] in an SQL st
232c0 61 74 65 6d 65 6e 74 2e 29 5e 0a 2a 2a 0a 2a 2a  atement.)^.**.**
232d0 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
232e0 54 52 49 47 47 45 52 5f 44 45 50 54 48 5d 5d 20  TRIGGER_DEPTH]] 
232f0 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
23300 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48  IT_TRIGGER_DEPTH
23310 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
23320 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f   maximum depth o
23330 66 20 72 65 63 75 72 73 69 6f 6e 20 66 6f 72 20  f recursion for 
23340 74 72 69 67 67 65 72 73 2e 3c 2f 64 64 3e 29 5e  triggers.</dd>)^
23350 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65  .** </dl>.*/.#de
23360 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
23370 54 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20  T_LENGTH        
23380 20 20 20 20 20 20 20 20 20 20 20 20 30 0a 23 64              0.#d
23390 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
233a0 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 20 20 20  IT_SQL_LENGTH   
233b0 20 20 20 20 20 20 20 20 20 20 20 20 20 31 0a 23               1.#
233c0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
233d0 4d 49 54 5f 43 4f 4c 55 4d 4e 20 20 20 20 20 20  MIT_COLUMN      
233e0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 0a                2.
233f0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
23400 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 20  IMIT_EXPR_DEPTH 
23410 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 33                 3
23420 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
23430 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53  LIMIT_COMPOUND_S
23440 45 4c 45 43 54 20 20 20 20 20 20 20 20 20 20 20  ELECT           
23450 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
23460 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 20 20  _LIMIT_VDBE_OP  
23470 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
23480 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   5.#define SQLIT
23490 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e  E_LIMIT_FUNCTION
234a0 5f 41 52 47 20 20 20 20 20 20 20 20 20 20 20 20  _ARG            
234b0 20 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    6.#define SQLI
234c0 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45  TE_LIMIT_ATTACHE
234d0 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  D               
234e0 20 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c     7.#define SQL
234f0 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50  ITE_LIMIT_LIKE_P
23500 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 20 20 20  ATTERN_LENGTH   
23510 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51      8.#define SQ
23520 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41  LITE_LIMIT_VARIA
23530 42 4c 45 5f 4e 55 4d 42 45 52 20 20 20 20 20 20  BLE_NUMBER      
23540 20 20 20 20 20 39 0a 23 64 65 66 69 6e 65 20 53       9.#define S
23550 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47  QLITE_LIMIT_TRIG
23560 47 45 52 5f 44 45 50 54 48 20 20 20 20 20 20 20  GER_DEPTH       
23570 20 20 20 20 20 31 30 0a 0a 2f 2a 0a 2a 2a 20 43       10../*.** C
23580 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 69  API3REF: Compili
23590 6e 67 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d  ng An SQL Statem
235a0 65 6e 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ent.** KEYWORDS:
235b0 20 7b 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20   {SQL statement 
235c0 63 6f 6d 70 69 6c 65 72 7d 0a 2a 2a 0a 2a 2a 20  compiler}.**.** 
235d0 54 6f 20 65 78 65 63 75 74 65 20 61 6e 20 53 51  To execute an SQ
235e0 4c 20 71 75 65 72 79 2c 20 69 74 20 6d 75 73 74  L query, it must
235f0 20 66 69 72 73 74 20 62 65 20 63 6f 6d 70 69 6c   first be compil
23600 65 64 20 69 6e 74 6f 20 61 20 62 79 74 65 2d 63  ed into a byte-c
23610 6f 64 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75  ode.** program u
23620 73 69 6e 67 20 6f 6e 65 20 6f 66 20 74 68 65 73  sing one of thes
23630 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a  e routines..**.*
23640 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  * The first argu
23650 6d 65 6e 74 2c 20 22 64 62 22 2c 20 69 73 20 61  ment, "db", is a
23660 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
23670 63 74 69 6f 6e 5d 20 6f 62 74 61 69 6e 65 64 20  ction] obtained 
23680 66 72 6f 6d 20 61 0a 2a 2a 20 70 72 69 6f 72 20  from a.** prior 
23690 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20  successful call 
236a0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  to [sqlite3_open
236b0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
236c0 65 6e 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b  en_v2()] or.** [
236d0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
236e0 5d 2e 20 20 54 68 65 20 64 61 74 61 62 61 73 65  ].  The database
236f0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74   connection must
23700 20 6e 6f 74 20 68 61 76 65 20 62 65 65 6e 20 63   not have been c
23710 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  losed..**.** The
23720 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
23730 2c 20 22 7a 53 71 6c 22 2c 20 69 73 20 74 68 65  , "zSql", is the
23740 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65   statement to be
23750 20 63 6f 6d 70 69 6c 65 64 2c 20 65 6e 63 6f 64   compiled, encod
23760 65 64 0a 2a 2a 20 61 73 20 65 69 74 68 65 72 20  ed.** as either 
23770 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 2e  UTF-8 or UTF-16.
23780 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72    The sqlite3_pr
23790 65 70 61 72 65 28 29 20 61 6e 64 20 73 71 6c 69  epare() and sqli
237a0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
237b0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 75  .** interfaces u
237c0 73 65 20 55 54 46 2d 38 2c 20 61 6e 64 20 73 71  se UTF-8, and sq
237d0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
237e0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72  ) and sqlite3_pr
237f0 65 70 61 72 65 31 36 5f 76 32 28 29 0a 2a 2a 20  epare16_v2().** 
23800 75 73 65 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a  use UTF-16..**.*
23810 2a 20 5e 49 66 20 74 68 65 20 6e 42 79 74 65 20  * ^If the nByte 
23820 61 72 67 75 6d 65 6e 74 20 69 73 20 6c 65 73 73  argument is less
23830 20 74 68 61 6e 20 7a 65 72 6f 2c 20 74 68 65 6e   than zero, then
23840 20 7a 53 71 6c 20 69 73 20 72 65 61 64 20 75 70   zSql is read up
23850 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 72 73 74   to the.** first
23860 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
23870 2e 20 5e 49 66 20 6e 42 79 74 65 20 69 73 20 6e  . ^If nByte is n
23880 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65  on-negative, the
23890 6e 20 69 74 20 69 73 20 74 68 65 20 6d 61 78 69  n it is the maxi
238a0 6d 75 6d 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66  mum.** number of
238b0 20 20 62 79 74 65 73 20 72 65 61 64 20 66 72 6f    bytes read fro
238c0 6d 20 7a 53 71 6c 2e 20 20 5e 57 68 65 6e 20 6e  m zSql.  ^When n
238d0 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61  Byte is non-nega
238e0 74 69 76 65 2c 20 74 68 65 0a 2a 2a 20 7a 53 71  tive, the.** zSq
238f0 6c 20 73 74 72 69 6e 67 20 65 6e 64 73 20 61 74  l string ends at
23900 20 65 69 74 68 65 72 20 74 68 65 20 66 69 72 73   either the firs
23910 74 20 27 5c 30 30 30 27 20 6f 72 20 27 5c 75 30  t '\000' or '\u0
23920 30 30 30 27 20 63 68 61 72 61 63 74 65 72 20 6f  000' character o
23930 72 0a 2a 2a 20 74 68 65 20 6e 42 79 74 65 2d 74  r.** the nByte-t
23940 68 20 62 79 74 65 2c 20 77 68 69 63 68 65 76 65  h byte, whicheve
23950 72 20 63 6f 6d 65 73 20 66 69 72 73 74 2e 20 49  r comes first. I
23960 66 20 74 68 65 20 63 61 6c 6c 65 72 20 6b 6e 6f  f the caller kno
23970 77 73 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 73  ws.** that the s
23980 75 70 70 6c 69 65 64 20 73 74 72 69 6e 67 20 69  upplied string i
23990 73 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64  s nul-terminated
239a0 2c 20 74 68 65 6e 20 74 68 65 72 65 20 69 73 20  , then there is 
239b0 61 20 73 6d 61 6c 6c 0a 2a 2a 20 70 65 72 66 6f  a small.** perfo
239c0 72 6d 61 6e 63 65 20 61 64 76 61 6e 74 61 67 65  rmance advantage
239d0 20 74 6f 20 62 65 20 67 61 69 6e 65 64 20 62 79   to be gained by
239e0 20 70 61 73 73 69 6e 67 20 61 6e 20 6e 42 79 74   passing an nByt
239f0 65 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74  e parameter that
23a00 0a 2a 2a 20 69 73 20 65 71 75 61 6c 20 74 6f 20  .** is equal to 
23a10 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
23a20 74 65 73 20 69 6e 20 74 68 65 20 69 6e 70 75 74  tes in the input
23a30 20 73 74 72 69 6e 67 20 3c 69 3e 69 6e 63 6c 75   string <i>inclu
23a40 64 69 6e 67 3c 2f 69 3e 0a 2a 2a 20 74 68 65 20  ding</i>.** the 
23a50 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 6f 72 20 62  nul-terminator b
23a60 79 74 65 73 20 61 73 20 74 68 69 73 20 73 61 76  ytes as this sav
23a70 65 73 20 53 51 4c 69 74 65 20 66 72 6f 6d 20 68  es SQLite from h
23a80 61 76 69 6e 67 20 74 6f 0a 2a 2a 20 6d 61 6b 65  aving to.** make
23a90 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 69   a copy of the i
23aa0 6e 70 75 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a  nput string..**.
23ab0 2a 2a 20 5e 49 66 20 70 7a 54 61 69 6c 20 69 73  ** ^If pzTail is
23ac0 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 2a   not NULL then *
23ad0 70 7a 54 61 69 6c 20 69 73 20 6d 61 64 65 20 74  pzTail is made t
23ae0 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68 65 20 66  o point to the f
23af0 69 72 73 74 20 62 79 74 65 0a 2a 2a 20 70 61 73  irst byte.** pas
23b00 74 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65  t the end of the
23b10 20 66 69 72 73 74 20 53 51 4c 20 73 74 61 74 65   first SQL state
23b20 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 20 20 54  ment in zSql.  T
23b30 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e  hese routines on
23b40 6c 79 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 68  ly.** compile th
23b50 65 20 66 69 72 73 74 20 73 74 61 74 65 6d 65 6e  e first statemen
23b60 74 20 69 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a 70  t in zSql, so *p
23b70 7a 54 61 69 6c 20 69 73 20 6c 65 66 74 20 70 6f  zTail is left po
23b80 69 6e 74 69 6e 67 20 74 6f 0a 2a 2a 20 77 68 61  inting to.** wha
23b90 74 20 72 65 6d 61 69 6e 73 20 75 6e 63 6f 6d 70  t remains uncomp
23ba0 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 2a 70 70  iled..**.** ^*pp
23bb0 53 74 6d 74 20 69 73 20 6c 65 66 74 20 70 6f 69  Stmt is left poi
23bc0 6e 74 69 6e 67 20 74 6f 20 61 20 63 6f 6d 70 69  nting to a compi
23bd0 6c 65 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  led [prepared st
23be0 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 63 61  atement] that ca
23bf0 6e 20 62 65 0a 2a 2a 20 65 78 65 63 75 74 65 64  n be.** executed
23c00 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
23c10 73 74 65 70 28 29 5d 2e 20 20 5e 49 66 20 74 68  step()].  ^If th
23c20 65 72 65 20 69 73 20 61 6e 20 65 72 72 6f 72 2c  ere is an error,
23c30 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 0a   *ppStmt is set.
23c40 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 20 20 5e 49 66  ** to NULL.  ^If
23c50 20 74 68 65 20 69 6e 70 75 74 20 74 65 78 74 20   the input text 
23c60 63 6f 6e 74 61 69 6e 73 20 6e 6f 20 53 51 4c 20  contains no SQL 
23c70 28 69 66 20 74 68 65 20 69 6e 70 75 74 20 69 73  (if the input is
23c80 20 61 6e 20 65 6d 70 74 79 0a 2a 2a 20 73 74 72   an empty.** str
23c90 69 6e 67 20 6f 72 20 61 20 63 6f 6d 6d 65 6e 74  ing or a comment
23ca0 29 20 74 68 65 6e 20 2a 70 70 53 74 6d 74 20 69  ) then *ppStmt i
23cb0 73 20 73 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a  s set to NULL..*
23cc0 2a 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 70 72  * The calling pr
23cd0 6f 63 65 64 75 72 65 20 69 73 20 72 65 73 70 6f  ocedure is respo
23ce0 6e 73 69 62 6c 65 20 66 6f 72 20 64 65 6c 65 74  nsible for delet
23cf0 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 65 64  ing the compiled
23d00 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  .** SQL statemen
23d10 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  t using [sqlite3
23d20 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 61 66 74  _finalize()] aft
23d30 65 72 20 69 74 20 68 61 73 20 66 69 6e 69 73 68  er it has finish
23d40 65 64 20 77 69 74 68 20 69 74 2e 0a 2a 2a 20 70  ed with it..** p
23d50 70 53 74 6d 74 20 6d 61 79 20 6e 6f 74 20 62 65  pStmt may not be
23d60 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e   NULL..**.** ^On
23d70 20 73 75 63 63 65 73 73 2c 20 74 68 65 20 73 71   success, the sq
23d80 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 20  lite3_prepare() 
23d90 66 61 6d 69 6c 79 20 6f 66 20 72 6f 75 74 69 6e  family of routin
23da0 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  es return [SQLIT
23db0 45 5f 4f 4b 5d 3b 0a 2a 2a 20 6f 74 68 65 72 77  E_OK];.** otherw
23dc0 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f  ise an [error co
23dd0 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  de] is returned.
23de0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
23df0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20  e3_prepare_v2() 
23e00 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70  and sqlite3_prep
23e10 61 72 65 31 36 5f 76 32 28 29 20 69 6e 74 65 72  are16_v2() inter
23e20 66 61 63 65 73 20 61 72 65 0a 2a 2a 20 72 65 63  faces are.** rec
23e30 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 61 6c 6c  ommended for all
23e40 20 6e 65 77 20 70 72 6f 67 72 61 6d 73 2e 20 54   new programs. T
23e50 68 65 20 74 77 6f 20 6f 6c 64 65 72 20 69 6e 74  he two older int
23e60 65 72 66 61 63 65 73 20 61 72 65 20 72 65 74 61  erfaces are reta
23e70 69 6e 65 64 0a 2a 2a 20 66 6f 72 20 62 61 63 6b  ined.** for back
23e80 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c  wards compatibil
23e90 69 74 79 2c 20 62 75 74 20 74 68 65 69 72 20 75  ity, but their u
23ea0 73 65 20 69 73 20 64 69 73 63 6f 75 72 61 67 65  se is discourage
23eb0 64 2e 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 22 76  d..** ^In the "v
23ec0 32 22 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74  2" interfaces, t
23ed0 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74  he prepared stat
23ee0 65 6d 65 6e 74 0a 2a 2a 20 74 68 61 74 20 69 73  ement.** that is
23ef0 20 72 65 74 75 72 6e 65 64 20 28 74 68 65 20 5b   returned (the [
23f00 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62  sqlite3_stmt] ob
23f10 6a 65 63 74 29 20 63 6f 6e 74 61 69 6e 73 20 61  ject) contains a
23f20 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20   copy of the.** 
23f30 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 74 65 78  original SQL tex
23f40 74 2e 20 54 68 69 73 20 63 61 75 73 65 73 20 74  t. This causes t
23f50 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  he [sqlite3_step
23f60 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 74 6f  ()] interface to
23f70 0a 2a 2a 20 62 65 68 61 76 65 20 64 69 66 66 65  .** behave diffe
23f80 72 65 6e 74 6c 79 20 69 6e 20 74 68 72 65 65 20  rently in three 
23f90 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e  ways:.**.** <ol>
23fa0 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20  .** <li>.** ^If 
23fb0 74 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68  the database sch
23fc0 65 6d 61 20 63 68 61 6e 67 65 73 2c 20 69 6e 73  ema changes, ins
23fd0 74 65 61 64 20 6f 66 20 72 65 74 75 72 6e 69 6e  tead of returnin
23fe0 67 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41  g [SQLITE_SCHEMA
23ff0 5d 20 61 73 20 69 74 0a 2a 2a 20 61 6c 77 61 79  ] as it.** alway
24000 73 20 75 73 65 64 20 74 6f 20 64 6f 2c 20 5b 73  s used to do, [s
24010 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77  qlite3_step()] w
24020 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ill automaticall
24030 79 20 72 65 63 6f 6d 70 69 6c 65 20 74 68 65 20  y recompile the 
24040 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  SQL.** statement
24050 20 61 6e 64 20 74 72 79 20 74 6f 20 72 75 6e 20   and try to run 
24060 69 74 20 61 67 61 69 6e 2e 0a 2a 2a 20 3c 2f 6c  it again..** </l
24070 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a  i>.**.** <li>.**
24080 20 5e 57 68 65 6e 20 61 6e 20 65 72 72 6f 72 20   ^When an error 
24090 6f 63 63 75 72 73 2c 20 5b 73 71 6c 69 74 65 33  occurs, [sqlite3
240a0 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 72 65  _step()] will re
240b0 74 75 72 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20  turn one of the 
240c0 64 65 74 61 69 6c 65 64 0a 2a 2a 20 5b 65 72 72  detailed.** [err
240d0 6f 72 20 63 6f 64 65 73 5d 20 6f 72 20 5b 65 78  or codes] or [ex
240e0 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64  tended error cod
240f0 65 73 5d 2e 20 20 5e 54 68 65 20 6c 65 67 61 63  es].  ^The legac
24100 79 20 62 65 68 61 76 69 6f 72 20 77 61 73 20 74  y behavior was t
24110 68 61 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  hat.** [sqlite3_
24120 73 74 65 70 28 29 5d 20 77 6f 75 6c 64 20 6f 6e  step()] would on
24130 6c 79 20 72 65 74 75 72 6e 20 61 20 67 65 6e 65  ly return a gene
24140 72 69 63 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  ric [SQLITE_ERRO
24150 52 5d 20 72 65 73 75 6c 74 20 63 6f 64 65 0a 2a  R] result code.*
24160 2a 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63  * and the applic
24170 61 74 69 6f 6e 20 77 6f 75 6c 64 20 68 61 76 65  ation would have
24180 20 74 6f 20 6d 61 6b 65 20 61 20 73 65 63 6f 6e   to make a secon
24190 64 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  d call to [sqlit
241a0 65 33 5f 72 65 73 65 74 28 29 5d 0a 2a 2a 20 69  e3_reset()].** i
241b0 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20  n order to find 
241c0 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 63  the underlying c
241d0 61 75 73 65 20 6f 66 20 74 68 65 20 70 72 6f 62  ause of the prob
241e0 6c 65 6d 2e 20 57 69 74 68 20 74 68 65 20 22 76  lem. With the "v
241f0 32 22 20 70 72 65 70 61 72 65 0a 2a 2a 20 69 6e  2" prepare.** in
24200 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 75 6e  terfaces, the un
24210 64 65 72 6c 79 69 6e 67 20 72 65 61 73 6f 6e 20  derlying reason 
24220 66 6f 72 20 74 68 65 20 65 72 72 6f 72 20 69 73  for the error is
24230 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69   returned immedi
24240 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a  ately..** </li>.
24250 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49  **.** <li>.** ^I
24260 66 20 74 68 65 20 73 70 65 63 69 66 69 63 20 76  f the specific v
24270 61 6c 75 65 20 62 6f 75 6e 64 20 74 6f 20 5b 70  alue bound to [p
24280 61 72 61 6d 65 74 65 72 20 7c 20 68 6f 73 74 20  arameter | host 
24290 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68  parameter] in th
242a0 65 20 0a 2a 2a 20 57 48 45 52 45 20 63 6c 61 75  e .** WHERE clau
242b0 73 65 20 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e  se might influen
242c0 63 65 20 74 68 65 20 63 68 6f 69 63 65 20 6f 66  ce the choice of
242d0 20 71 75 65 72 79 20 70 6c 61 6e 20 66 6f 72 20   query plan for 
242e0 61 20 73 74 61 74 65 6d 65 6e 74 2c 0a 2a 2a 20  a statement,.** 
242f0 74 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65  then the stateme
24300 6e 74 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d  nt will be autom
24310 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69  atically recompi
24320 6c 65 64 2c 20 61 73 20 69 66 20 74 68 65 72 65  led, as if there
24330 20 68 61 64 20 62 65 65 6e 20 0a 2a 2a 20 61 20   had been .** a 
24340 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2c 20 6f  schema change, o
24350 6e 20 74 68 65 20 66 69 72 73 74 20 20 5b 73 71  n the first  [sq
24360 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 63 61  lite3_step()] ca
24370 6c 6c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79  ll following any
24380 20 63 68 61 6e 67 65 0a 2a 2a 20 74 6f 20 74 68   change.** to th
24390 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  e [sqlite3_bind_
243a0 74 65 78 74 20 7c 20 62 69 6e 64 69 6e 67 73 5d  text | bindings]
243b0 20 6f 66 20 74 68 61 74 20 5b 70 61 72 61 6d 65   of that [parame
243c0 74 65 72 5d 2e 20 0a 2a 2a 20 5e 54 68 65 20 73  ter]. .** ^The s
243d0 70 65 63 69 66 69 63 20 76 61 6c 75 65 20 6f 66  pecific value of
243e0 20 57 48 45 52 45 2d 63 6c 61 75 73 65 20 5b 70   WHERE-clause [p
243f0 61 72 61 6d 65 74 65 72 5d 20 6d 69 67 68 74 20  arameter] might 
24400 69 6e 66 6c 75 65 6e 63 65 20 74 68 65 20 0a 2a  influence the .*
24410 2a 20 63 68 6f 69 63 65 20 6f 66 20 71 75 65 72  * choice of quer
24420 79 20 70 6c 61 6e 20 69 66 20 74 68 65 20 70 61  y plan if the pa
24430 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6c  rameter is the l
24440 65 66 74 2d 68 61 6e 64 20 73 69 64 65 20 6f 66  eft-hand side of
24450 20 61 20 5b 4c 49 4b 45 5d 0a 2a 2a 20 6f 72 20   a [LIKE].** or 
24460 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 20  [GLOB] operator 
24470 6f 72 20 69 66 20 74 68 65 20 70 61 72 61 6d 65  or if the parame
24480 74 65 72 20 69 73 20 63 6f 6d 70 61 72 65 64 20  ter is compared 
24490 74 6f 20 61 6e 20 69 6e 64 65 78 65 64 20 63 6f  to an indexed co
244a0 6c 75 6d 6e 0a 2a 2a 20 61 6e 64 20 74 68 65 20  lumn.** and the 
244b0 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53  [SQLITE_ENABLE_S
244c0 54 41 54 33 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  TAT3] compile-ti
244d0 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 65 6e 61  me option is ena
244e0 62 6c 65 64 2e 0a 2a 2a 20 74 68 65 20 0a 2a 2a  bled..** the .**
244f0 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a   </li>.** </ol>.
24500 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70  */.int sqlite3_p
24510 72 65 70 61 72 65 28 0a 20 20 73 71 6c 69 74 65  repare(.  sqlite
24520 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
24530 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61    /* Database ha
24540 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
24550 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20  char *zSql,     
24560 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65    /* SQL stateme
24570 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65  nt, UTF-8 encode
24580 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65  d */.  int nByte
24590 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
245a0 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  * Maximum length
245b0 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65   of zSql in byte
245c0 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  s. */.  sqlite3_
245d0 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20  stmt **ppStmt,  
245e0 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e  /* OUT: Statemen
245f0 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  t handle */.  co
24600 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69  nst char **pzTai
24610 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f  l     /* OUT: Po
24620 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20  inter to unused 
24630 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20  portion of zSql 
24640 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  */.);.int sqlite
24650 33 5f 70 72 65 70 61 72 65 5f 76 32 28 0a 20 20  3_prepare_v2(.  
24660 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
24670 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
24680 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ase handle */.  
24690 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c  const char *zSql
246a0 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73  ,       /* SQL s
246b0 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20  tatement, UTF-8 
246c0 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74  encoded */.  int
246d0 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20   nByte,         
246e0 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20       /* Maximum 
246f0 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69  length of zSql i
24700 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71  n bytes. */.  sq
24710 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53  lite3_stmt **ppS
24720 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74  tmt,  /* OUT: St
24730 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a  atement handle *
24740 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
24750 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f  *pzTail     /* O
24760 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75  UT: Pointer to u
24770 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66  nused portion of
24780 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20   zSql */.);.int 
24790 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
247a0 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  6(.  sqlite3 *db
247b0 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ,            /* 
247c0 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  Database handle 
247d0 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
247e0 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20  *zSql,       /* 
247f0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55  SQL statement, U
24800 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f  TF-16 encoded */
24810 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20  .  int nByte,   
24820 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61             /* Ma
24830 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
24840 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a  zSql in bytes. *
24850 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  /.  sqlite3_stmt
24860 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f   **ppStmt,  /* O
24870 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61  UT: Statement ha
24880 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
24890 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20  void **pzTail   
248a0 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65    /* OUT: Pointe
248b0 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74  r to unused port
248c0 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29  ion of zSql */.)
248d0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72  ;.int sqlite3_pr
248e0 65 70 61 72 65 31 36 5f 76 32 28 0a 20 20 73 71  epare16_v2(.  sq
248f0 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
24900 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
24910 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  e handle */.  co
24920 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20  nst void *zSql, 
24930 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61        /* SQL sta
24940 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65  tement, UTF-16 e
24950 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20  ncoded */.  int 
24960 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20  nByte,          
24970 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c      /* Maximum l
24980 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e  ength of zSql in
24990 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c   bytes. */.  sql
249a0 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74  ite3_stmt **ppSt
249b0 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61  mt,  /* OUT: Sta
249c0 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f  tement handle */
249d0 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a  .  const void **
249e0 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55  pzTail     /* OU
249f0 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e  T: Pointer to un
24a00 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20  used portion of 
24a10 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a  zSql */.);../*.*
24a20 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 74 72  * CAPI3REF: Retr
24a30 69 65 76 69 6e 67 20 53 74 61 74 65 6d 65 6e 74  ieving Statement
24a40 20 53 51 4c 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73   SQL.**.** ^This
24a50 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62   interface can b
24a60 65 20 75 73 65 64 20 74 6f 20 72 65 74 72 69 65  e used to retrie
24a70 76 65 20 61 20 73 61 76 65 64 20 63 6f 70 79 20  ve a saved copy 
24a80 6f 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 0a  of the original.
24a90 2a 2a 20 53 51 4c 20 74 65 78 74 20 75 73 65 64  ** SQL text used
24aa0 20 74 6f 20 63 72 65 61 74 65 20 61 20 5b 70 72   to create a [pr
24ab0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
24ac0 5d 20 69 66 20 74 68 61 74 20 73 74 61 74 65 6d  ] if that statem
24ad0 65 6e 74 20 77 61 73 0a 2a 2a 20 63 6f 6d 70 69  ent was.** compi
24ae0 6c 65 64 20 75 73 69 6e 67 20 65 69 74 68 65 72  led using either
24af0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
24b00 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69  e_v2()] or [sqli
24b10 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
24b20 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68  ()]..*/.const ch
24b30 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 71 6c 28  ar *sqlite3_sql(
24b40 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
24b50 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
24b60 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65  I3REF: Determine
24b70 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65   If An SQL State
24b80 6d 65 6e 74 20 57 72 69 74 65 73 20 54 68 65 20  ment Writes The 
24b90 44 61 74 61 62 61 73 65 0a 2a 2a 0a 2a 2a 20 5e  Database.**.** ^
24ba0 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  The sqlite3_stmt
24bb0 5f 72 65 61 64 6f 6e 6c 79 28 58 29 20 69 6e 74  _readonly(X) int
24bc0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
24bd0 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69  rue (non-zero) i
24be0 66 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79 20 69 66  f.** and only if
24bf0 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
24c00 74 61 74 65 6d 65 6e 74 5d 20 58 20 6d 61 6b 65  tatement] X make
24c10 73 20 6e 6f 20 64 69 72 65 63 74 20 63 68 61 6e  s no direct chan
24c20 67 65 73 20 74 6f 0a 2a 2a 20 74 68 65 20 63 6f  ges to.** the co
24c30 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 64 61 74  ntent of the dat
24c40 61 62 61 73 65 20 66 69 6c 65 2e 0a 2a 2a 0a 2a  abase file..**.*
24c50 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 61 70 70  * Note that [app
24c60 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
24c70 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20   SQL functions] 
24c80 6f 72 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 74  or.** [virtual t
24c90 61 62 6c 65 73 5d 20 6d 69 67 68 74 20 63 68 61  ables] might cha
24ca0 6e 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65  nge the database
24cb0 20 69 6e 64 69 72 65 63 74 6c 79 20 61 73 20 61   indirectly as a
24cc0 20 73 69 64 65 20 65 66 66 65 63 74 2e 20 20 0a   side effect.  .
24cd0 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65  ** ^(For example
24ce0 2c 20 69 66 20 61 6e 20 61 70 70 6c 69 63 61 74  , if an applicat
24cf0 69 6f 6e 20 64 65 66 69 6e 65 73 20 61 20 66 75  ion defines a fu
24d00 6e 63 74 69 6f 6e 20 22 65 76 61 6c 28 29 22 20  nction "eval()" 
24d10 74 68 61 74 20 0a 2a 2a 20 63 61 6c 6c 73 20 5b  that .** calls [
24d20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c  sqlite3_exec()],
24d30 20 74 68 65 6e 20 74 68 65 20 66 6f 6c 6c 6f 77   then the follow
24d40 69 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ing SQL statemen
24d50 74 20 77 6f 75 6c 64 0a 2a 2a 20 63 68 61 6e 67  t would.** chang
24d60 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  e the database f
24d70 69 6c 65 20 74 68 72 6f 75 67 68 20 73 69 64 65  ile through side
24d80 2d 65 66 66 65 63 74 73 3a 0a 2a 2a 0a 2a 2a 20  -effects:.**.** 
24d90 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
24da0 3e 0a 2a 2a 20 20 20 20 53 45 4c 45 43 54 20 65  >.**    SELECT e
24db0 76 61 6c 28 27 44 45 4c 45 54 45 20 46 52 4f 4d  val('DELETE FROM
24dc0 20 74 31 27 29 20 46 52 4f 4d 20 74 32 3b 0a 2a   t1') FROM t2;.*
24dd0 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
24de0 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 75 74 20  uote>.**.** But 
24df0 62 65 63 61 75 73 65 20 74 68 65 20 5b 53 45 4c  because the [SEL
24e00 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 64  ECT] statement d
24e10 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74  oes not change t
24e20 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
24e30 0a 2a 2a 20 64 69 72 65 63 74 6c 79 2c 20 73 71  .** directly, sq
24e40 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f  lite3_stmt_reado
24e50 6e 6c 79 28 29 20 77 6f 75 6c 64 20 73 74 69 6c  nly() would stil
24e60 6c 20 72 65 74 75 72 6e 20 74 72 75 65 2e 29 5e  l return true.)^
24e70 0a 2a 2a 0a 2a 2a 20 5e 54 72 61 6e 73 61 63 74  .**.** ^Transact
24e80 69 6f 6e 20 63 6f 6e 74 72 6f 6c 20 73 74 61 74  ion control stat
24e90 65 6d 65 6e 74 73 20 73 75 63 68 20 61 73 20 5b  ements such as [
24ea0 42 45 47 49 4e 5d 2c 20 5b 43 4f 4d 4d 49 54 5d  BEGIN], [COMMIT]
24eb0 2c 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2c 0a 2a 2a  , [ROLLBACK],.**
24ec0 20 5b 53 41 56 45 50 4f 49 4e 54 5d 2c 20 61 6e   [SAVEPOINT], an
24ed0 64 20 5b 52 45 4c 45 41 53 45 5d 20 63 61 75 73  d [RELEASE] caus
24ee0 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72  e sqlite3_stmt_r
24ef0 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74  eadonly() to ret
24f00 75 72 6e 20 74 72 75 65 2c 0a 2a 2a 20 73 69 6e  urn true,.** sin
24f10 63 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  ce the statement
24f20 73 20 74 68 65 6d 73 65 6c 76 65 73 20 64 6f 20  s themselves do 
24f30 6e 6f 74 20 61 63 74 75 61 6c 6c 79 20 6d 6f 64  not actually mod
24f40 69 66 79 20 74 68 65 20 64 61 74 61 62 61 73 65  ify the database
24f50 20 62 75 74 0a 2a 2a 20 72 61 74 68 65 72 20 74   but.** rather t
24f60 68 65 79 20 63 6f 6e 74 72 6f 6c 20 74 68 65 20  hey control the 
24f70 74 69 6d 69 6e 67 20 6f 66 20 77 68 65 6e 20 6f  timing of when o
24f80 74 68 65 72 20 73 74 61 74 65 6d 65 6e 74 73 20  ther statements 
24f90 6d 6f 64 69 66 79 20 74 68 65 20 0a 2a 2a 20 64  modify the .** d
24fa0 61 74 61 62 61 73 65 2e 20 20 5e 54 68 65 20 5b  atabase.  ^The [
24fb0 41 54 54 41 43 48 5d 20 61 6e 64 20 5b 44 45 54  ATTACH] and [DET
24fc0 41 43 48 5d 20 73 74 61 74 65 6d 65 6e 74 73 20  ACH] statements 
24fd0 61 6c 73 6f 20 63 61 75 73 65 0a 2a 2a 20 73 71  also cause.** sq
24fe0 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f  lite3_stmt_reado
24ff0 6e 6c 79 28 29 20 74 6f 20 72 65 74 75 72 6e 20  nly() to return 
25000 74 72 75 65 20 73 69 6e 63 65 2c 20 77 68 69 6c  true since, whil
25010 65 20 74 68 6f 73 65 20 73 74 61 74 65 6d 65 6e  e those statemen
25020 74 73 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65  ts.** change the
25030 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
25040 66 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e  f a database con
25050 6e 65 63 74 69 6f 6e 2c 20 74 68 65 79 20 64 6f  nection, they do
25060 20 6e 6f 74 20 6d 61 6b 65 20 0a 2a 2a 20 63 68   not make .** ch
25070 61 6e 67 65 73 20 74 6f 20 74 68 65 20 63 6f 6e  anges to the con
25080 74 65 6e 74 20 6f 66 20 74 68 65 20 64 61 74 61  tent of the data
25090 62 61 73 65 20 66 69 6c 65 73 20 6f 6e 20 64 69  base files on di
250a0 73 6b 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  sk..*/.int sqlit
250b0 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79  e3_stmt_readonly
250c0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
250d0 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
250e0 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e  PI3REF: Determin
250f0 65 20 49 66 20 41 20 50 72 65 70 61 72 65 64 20  e If A Prepared 
25100 53 74 61 74 65 6d 65 6e 74 20 48 61 73 20 42 65  Statement Has Be
25110 65 6e 20 52 65 73 65 74 0a 2a 2a 0a 2a 2a 20 5e  en Reset.**.** ^
25120 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  The sqlite3_stmt
25130 5f 62 75 73 79 28 53 29 20 69 6e 74 65 72 66 61  _busy(S) interfa
25140 63 65 20 72 65 74 75 72 6e 73 20 74 72 75 65 20  ce returns true 
25150 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 20 74 68  (non-zero) if th
25160 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  e.** [prepared s
25170 74 61 74 65 6d 65 6e 74 5d 20 53 20 68 61 73 20  tatement] S has 
25180 62 65 65 6e 20 73 74 65 70 70 65 64 20 61 74 20  been stepped at 
25190 6c 65 61 73 74 20 6f 6e 63 65 20 75 73 69 6e 67  least once using
251a0 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74   .** [sqlite3_st
251b0 65 70 28 53 29 5d 20 62 75 74 20 68 61 73 20 6e  ep(S)] but has n
251c0 6f 74 20 72 75 6e 20 74 6f 20 63 6f 6d 70 6c 65  ot run to comple
251d0 74 69 6f 6e 20 61 6e 64 2f 6f 72 20 68 61 73 20  tion and/or has 
251e0 6e 6f 74 20 0a 2a 2a 20 62 65 65 6e 20 72 65 73  not .** been res
251f0 65 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  et using [sqlite
25200 33 5f 72 65 73 65 74 28 53 29 5d 2e 20 20 5e 54  3_reset(S)].  ^T
25210 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  he sqlite3_stmt_
25220 62 75 73 79 28 53 29 0a 2a 2a 20 69 6e 74 65 72  busy(S).** inter
25230 66 61 63 65 20 72 65 74 75 72 6e 73 20 66 61 6c  face returns fal
25240 73 65 20 69 66 20 53 20 69 73 20 61 20 4e 55 4c  se if S is a NUL
25250 4c 20 70 6f 69 6e 74 65 72 2e 20 20 49 66 20 53  L pointer.  If S
25260 20 69 73 20 6e 6f 74 20 61 20 0a 2a 2a 20 4e 55   is not a .** NU
25270 4c 4c 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 69  LL pointer and i
25280 73 20 6e 6f 74 20 61 20 70 6f 69 6e 74 65 72 20  s not a pointer 
25290 74 6f 20 61 20 76 61 6c 69 64 20 5b 70 72 65 70  to a valid [prep
252a0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a  ared statement].
252b0 2a 2a 20 6f 62 6a 65 63 74 2c 20 74 68 65 6e 20  ** object, then 
252c0 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20  the behavior is 
252d0 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72  undefined and pr
252e0 6f 62 61 62 6c 79 20 75 6e 64 65 73 69 72 61 62  obably undesirab
252f0 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69  le..**.** This i
25300 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20  nterface can be 
25310 75 73 65 64 20 69 6e 20 63 6f 6d 62 69 6e 61 74  used in combinat
25320 69 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78  ion [sqlite3_nex
25330 74 5f 73 74 6d 74 28 29 5d 0a 2a 2a 20 74 6f 20  t_stmt()].** to 
25340 6c 6f 63 61 74 65 20 61 6c 6c 20 70 72 65 70 61  locate all prepa
25350 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 20 61  red statements a
25360 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 61  ssociated with a
25370 20 64 61 74 61 62 61 73 65 20 0a 2a 2a 20 63 6f   database .** co
25380 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 61 72  nnection that ar
25390 65 20 69 6e 20 6e 65 65 64 20 6f 66 20 62 65 69  e in need of bei
253a0 6e 67 20 72 65 73 65 74 2e 20 20 54 68 69 73 20  ng reset.  This 
253b0 63 61 6e 20 62 65 20 75 73 65 64 2c 0a 2a 2a 20  can be used,.** 
253c0 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 6e 20  for example, in 
253d0 64 69 61 67 6e 6f 73 74 69 63 20 72 6f 75 74 69  diagnostic routi
253e0 6e 65 73 20 74 6f 20 73 65 61 72 63 68 20 66 6f  nes to search fo
253f0 72 20 70 72 65 70 61 72 65 64 20 0a 2a 2a 20 73  r prepared .** s
25400 74 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20 61  tatements that a
25410 72 65 20 68 6f 6c 64 69 6e 67 20 61 20 74 72 61  re holding a tra
25420 6e 73 61 63 74 69 6f 6e 20 6f 70 65 6e 2e 0a 2a  nsaction open..*
25430 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74  /.int sqlite3_st
25440 6d 74 5f 62 75 73 79 28 73 71 6c 69 74 65 33 5f  mt_busy(sqlite3_
25450 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  stmt*);../*.** C
25460 41 50 49 33 52 45 46 3a 20 44 79 6e 61 6d 69 63  API3REF: Dynamic
25470 61 6c 6c 79 20 54 79 70 65 64 20 56 61 6c 75 65  ally Typed Value
25480 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f   Object.** KEYWO
25490 52 44 53 3a 20 7b 70 72 6f 74 65 63 74 65 64 20  RDS: {protected 
254a0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 20 7b  sqlite3_value} {
254b0 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
254c0 74 65 33 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a  te3_value}.**.**
254d0 20 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65   SQLite uses the
254e0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
254f0 62 6a 65 63 74 20 74 6f 20 72 65 70 72 65 73 65  bject to represe
25500 6e 74 20 61 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a  nt all values.**
25510 20 74 68 61 74 20 63 61 6e 20 62 65 20 73 74 6f   that can be sto
25520 72 65 64 20 69 6e 20 61 20 64 61 74 61 62 61 73  red in a databas
25530 65 20 74 61 62 6c 65 2e 20 53 51 4c 69 74 65 20  e table. SQLite 
25540 75 73 65 73 20 64 79 6e 61 6d 69 63 20 74 79 70  uses dynamic typ
25550 69 6e 67 0a 2a 2a 20 66 6f 72 20 74 68 65 20 76  ing.** for the v
25560 61 6c 75 65 73 20 69 74 20 73 74 6f 72 65 73 2e  alues it stores.
25570 20 20 5e 56 61 6c 75 65 73 20 73 74 6f 72 65 64    ^Values stored
25580 20 69 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75   in sqlite3_valu
25590 65 20 6f 62 6a 65 63 74 73 0a 2a 2a 20 63 61 6e  e objects.** can
255a0 20 62 65 20 69 6e 74 65 67 65 72 73 2c 20 66 6c   be integers, fl
255b0 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c  oating point val
255c0 75 65 73 2c 20 73 74 72 69 6e 67 73 2c 20 42 4c  ues, strings, BL
255d0 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a  OBs, or NULL..**
255e0 0a 2a 2a 20 41 6e 20 73 71 6c 69 74 65 33 5f 76  .** An sqlite3_v
255f0 61 6c 75 65 20 6f 62 6a 65 63 74 20 6d 61 79 20  alue object may 
25600 62 65 20 65 69 74 68 65 72 20 22 70 72 6f 74 65  be either "prote
25610 63 74 65 64 22 20 6f 72 20 22 75 6e 70 72 6f 74  cted" or "unprot
25620 65 63 74 65 64 22 2e 0a 2a 2a 20 53 6f 6d 65 20  ected"..** Some 
25630 69 6e 74 65 72 66 61 63 65 73 20 72 65 71 75 69  interfaces requi
25640 72 65 20 61 20 70 72 6f 74 65 63 74 65 64 20 73  re a protected s
25650 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 20 20 4f  qlite3_value.  O
25660 74 68 65 72 20 69 6e 74 65 72 66 61 63 65 73 0a  ther interfaces.
25670 2a 2a 20 77 69 6c 6c 20 61 63 63 65 70 74 20 65  ** will accept e
25680 69 74 68 65 72 20 61 20 70 72 6f 74 65 63 74 65  ither a protecte
25690 64 20 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63  d or an unprotec
256a0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
256b0 65 2e 0a 2a 2a 20 45 76 65 72 79 20 69 6e 74 65  e..** Every inte
256c0 72 66 61 63 65 20 74 68 61 74 20 61 63 63 65 70  rface that accep
256d0 74 73 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ts sqlite3_value
256e0 20 61 72 67 75 6d 65 6e 74 73 20 73 70 65 63 69   arguments speci
256f0 66 69 65 73 0a 2a 2a 20 77 68 65 74 68 65 72 20  fies.** whether 
25700 6f 72 20 6e 6f 74 20 69 74 20 72 65 71 75 69 72  or not it requir
25710 65 73 20 61 20 70 72 6f 74 65 63 74 65 64 20 73  es a protected s
25720 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a  qlite3_value..**
25730 0a 2a 2a 20 54 68 65 20 74 65 72 6d 73 20 22 70  .** The terms "p
25740 72 6f 74 65 63 74 65 64 22 20 61 6e 64 20 22 75  rotected" and "u
25750 6e 70 72 6f 74 65 63 74 65 64 22 20 72 65 66 65  nprotected" refe
25760 72 20 74 6f 20 77 68 65 74 68 65 72 20 6f 72 20  r to whether or 
25770 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74 65 78 20 69  not.** a mutex i
25780 73 20 68 65 6c 64 2e 20 20 41 6e 20 69 6e 74 65  s held.  An inte
25790 72 6e 61 6c 20 6d 75 74 65 78 20 69 73 20 68 65  rnal mutex is he
257a0 6c 64 20 66 6f 72 20 61 20 70 72 6f 74 65 63 74  ld for a protect
257b0 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61  ed.** sqlite3_va
257c0 6c 75 65 20 6f 62 6a 65 63 74 20 62 75 74 20 6e  lue object but n
257d0 6f 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20  o mutex is held 
257e0 66 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74  for an unprotect
257f0 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61  ed.** sqlite3_va
25800 6c 75 65 20 6f 62 6a 65 63 74 2e 20 20 49 66 20  lue object.  If 
25810 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
25820 65 64 20 74 6f 20 62 65 20 73 69 6e 67 6c 65 2d  ed to be single-
25830 74 68 72 65 61 64 65 64 0a 2a 2a 20 28 77 69 74  threaded.** (wit
25840 68 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  h [SQLITE_THREAD
25850 53 41 46 45 3d 30 5d 20 61 6e 64 20 77 69 74 68  SAFE=0] and with
25860 20 5b 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64   [sqlite3_thread
25870 73 61 66 65 28 29 5d 20 72 65 74 75 72 6e 69 6e  safe()] returnin
25880 67 20 30 29 0a 2a 2a 20 6f 72 20 69 66 20 53 51  g 0).** or if SQ
25890 4c 69 74 65 20 69 73 20 72 75 6e 20 69 6e 20 6f  Lite is run in o
258a0 6e 65 20 6f 66 20 72 65 64 75 63 65 64 20 6d 75  ne of reduced mu
258b0 74 65 78 20 6d 6f 64 65 73 20 0a 2a 2a 20 5b 53  tex modes .** [S
258c0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e  QLITE_CONFIG_SIN
258d0 47 4c 45 54 48 52 45 41 44 5d 20 6f 72 20 5b 53  GLETHREAD] or [S
258e0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c  QLITE_CONFIG_MUL
258f0 54 49 54 48 52 45 41 44 5d 0a 2a 2a 20 74 68 65  TITHREAD].** the
25900 6e 20 74 68 65 72 65 20 69 73 20 6e 6f 20 64 69  n there is no di
25910 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65  stinction betwee
25920 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20  n protected and 
25930 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73  unprotected.** s
25940 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
25950 65 63 74 73 20 61 6e 64 20 74 68 65 79 20 63 61  ects and they ca
25960 6e 20 62 65 20 75 73 65 64 20 69 6e 74 65 72 63  n be used interc
25970 68 61 6e 67 65 61 62 6c 79 2e 20 20 48 6f 77 65  hangeably.  Howe
25980 76 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d 61 78 69  ver,.** for maxi
25990 6d 75 6d 20 63 6f 64 65 20 70 6f 72 74 61 62 69  mum code portabi
259a0 6c 69 74 79 20 69 74 20 69 73 20 72 65 63 6f 6d  lity it is recom
259b0 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c  mended that appl
259c0 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 74 69 6c  ications.** stil
259d0 6c 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74 69  l make the disti
259e0 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 70  nction between p
259f0 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70  rotected and unp
25a00 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69  rotected.** sqli
25a10 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
25a20 73 20 65 76 65 6e 20 77 68 65 6e 20 6e 6f 74 20  s even when not 
25a30 73 74 72 69 63 74 6c 79 20 72 65 71 75 69 72 65  strictly require
25a40 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  d..**.** ^The sq
25a50 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
25a60 63 74 73 20 74 68 61 74 20 61 72 65 20 70 61 73  cts that are pas
25a70 73 65 64 20 61 73 20 70 61 72 61 6d 65 74 65 72  sed as parameter
25a80 73 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6d  s into the.** im
25a90 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
25aa0 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66  [application-def
25ab0 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
25ac0 6e 73 5d 20 61 72 65 20 70 72 6f 74 65 63 74 65  ns] are protecte
25ad0 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  d..** ^The sqlit
25ae0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20  e3_value object 
25af0 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b  returned by.** [
25b00 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76  sqlite3_column_v
25b10 61 6c 75 65 28 29 5d 20 69 73 20 75 6e 70 72 6f  alue()] is unpro
25b20 74 65 63 74 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f  tected..** Unpro
25b30 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
25b40 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 6d 61 79  alue objects may
25b50 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69   only be used wi
25b60 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72  th.** [sqlite3_r
25b70 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 20 61  esult_value()] a
25b80 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  nd [sqlite3_bind
25b90 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54 68  _value()]..** Th
25ba0 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
25bb0 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f  _blob | sqlite3_
25bc0 76 61 6c 75 65 5f 74 79 70 65 28 29 5d 20 66 61  value_type()] fa
25bd0 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74 65 72  mily of.** inter
25be0 66 61 63 65 73 20 72 65 71 75 69 72 65 20 70 72  faces require pr
25bf0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
25c00 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 2e 0a 2a  value objects..*
25c10 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
25c20 20 4d 65 6d 20 73 71 6c 69 74 65 33 5f 76 61 6c   Mem sqlite3_val
25c30 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  ue;../*.** CAPI3
25c40 52 45 46 3a 20 53 51 4c 20 46 75 6e 63 74 69 6f  REF: SQL Functio
25c50 6e 20 43 6f 6e 74 65 78 74 20 4f 62 6a 65 63 74  n Context Object
25c60 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e 74 65  .**.** The conte
25c70 78 74 20 69 6e 20 77 68 69 63 68 20 61 6e 20 53  xt in which an S
25c80 51 4c 20 66 75 6e 63 74 69 6f 6e 20 65 78 65 63  QL function exec
25c90 75 74 65 73 20 69 73 20 73 74 6f 72 65 64 20 69  utes is stored i
25ca0 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  n an.** sqlite3_
25cb0 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 2e 20  context object. 
25cc0 20 5e 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61   ^A pointer to a
25cd0 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  n sqlite3_contex
25ce0 74 20 6f 62 6a 65 63 74 0a 2a 2a 20 69 73 20 61  t object.** is a
25cf0 6c 77 61 79 73 20 66 69 72 73 74 20 70 61 72 61  lways first para
25d00 6d 65 74 65 72 20 74 6f 20 5b 61 70 70 6c 69 63  meter to [applic
25d10 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
25d20 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a  L functions]..**
25d30 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
25d40 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
25d50 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  ction implementa
25d60 74 69 6f 6e 20 77 69 6c 6c 20 70 61 73 73 20 74  tion will pass t
25d70 68 69 73 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74  his.** pointer t
25d80 68 72 6f 75 67 68 20 69 6e 74 6f 20 63 61 6c 6c  hrough into call
25d90 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65  s to [sqlite3_re
25da0 73 75 6c 74 5f 69 6e 74 20 7c 20 73 71 6c 69 74  sult_int | sqlit
25db0 65 33 5f 72 65 73 75 6c 74 28 29 5d 2c 0a 2a 2a  e3_result()],.**
25dc0 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67   [sqlite3_aggreg
25dd0 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 5d 2c 20  ate_context()], 
25de0 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61  [sqlite3_user_da
25df0 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  ta()],.** [sqlit
25e00 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61  e3_context_db_ha
25e10 6e 64 6c 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65  ndle()], [sqlite
25e20 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 5d  3_get_auxdata()]
25e30 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b 73 71 6c  ,.** and/or [sql
25e40 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
25e50 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ()]..*/.typedef 
25e60 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 63  struct sqlite3_c
25e70 6f 6e 74 65 78 74 20 73 71 6c 69 74 65 33 5f 63  ontext sqlite3_c
25e80 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ontext;../*.** C
25e90 41 50 49 33 52 45 46 3a 20 42 69 6e 64 69 6e 67  API3REF: Binding
25ea0 20 56 61 6c 75 65 73 20 54 6f 20 50 72 65 70 61   Values To Prepa
25eb0 72 65 64 20 53 74 61 74 65 6d 65 6e 74 73 0a 2a  red Statements.*
25ec0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 68 6f 73  * KEYWORDS: {hos
25ed0 74 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 68 6f  t parameter} {ho
25ee0 73 74 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b  st parameters} {
25ef0 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e  host parameter n
25f00 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ame}.** KEYWORDS
25f10 3a 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72  : {SQL parameter
25f20 7d 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72  } {SQL parameter
25f30 73 7d 20 7b 70 61 72 61 6d 65 74 65 72 20 62 69  s} {parameter bi
25f40 6e 64 69 6e 67 7d 0a 2a 2a 0a 2a 2a 20 5e 28 49  nding}.**.** ^(I
25f50 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  n the SQL statem
25f60 65 6e 74 20 74 65 78 74 20 69 6e 70 75 74 20 74  ent text input t
25f70 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  o [sqlite3_prepa
25f80 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 69 74 73  re_v2()] and its
25f90 20 76 61 72 69 61 6e 74 73 2c 0a 2a 2a 20 6c 69   variants,.** li
25fa0 74 65 72 61 6c 73 20 6d 61 79 20 62 65 20 72 65  terals may be re
25fb0 70 6c 61 63 65 64 20 62 79 20 61 20 5b 70 61 72  placed by a [par
25fc0 61 6d 65 74 65 72 5d 20 74 68 61 74 20 6d 61 74  ameter] that mat
25fd0 63 68 65 73 20 6f 6e 65 20 6f 66 20 66 6f 6c 6c  ches one of foll
25fe0 6f 77 69 6e 67 0a 2a 2a 20 74 65 6d 70 6c 61 74  owing.** templat
25ff0 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  es:.**.** <ul>.*
26000 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c 69  * <li>  ?.** <li
26010 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20  >  ?NNN.** <li> 
26020 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 40   :VVV.** <li>  @
26030 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56 56  VVV.** <li>  $VV
26040 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  V.** </ul>.**.**
26050 20 49 6e 20 74 68 65 20 74 65 6d 70 6c 61 74 65   In the template
26060 73 20 61 62 6f 76 65 2c 20 4e 4e 4e 20 72 65 70  s above, NNN rep
26070 72 65 73 65 6e 74 73 20 61 6e 20 69 6e 74 65 67  resents an integ
26080 65 72 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20 61  er literal,.** a
26090 6e 64 20 56 56 56 20 72 65 70 72 65 73 65 6e 74  nd VVV represent
260a0 73 20 61 6e 20 61 6c 70 68 61 6e 75 6d 65 72 69  s an alphanumeri
260b0 63 20 69 64 65 6e 74 69 66 69 65 72 2e 29 5e 20  c identifier.)^ 
260c0 20 5e 54 68 65 20 76 61 6c 75 65 73 20 6f 66 20   ^The values of 
260d0 74 68 65 73 65 0a 2a 2a 20 70 61 72 61 6d 65 74  these.** paramet
260e0 65 72 73 20 28 61 6c 73 6f 20 63 61 6c 6c 65 64  ers (also called
260f0 20 22 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72   "host parameter
26100 20 6e 61 6d 65 73 22 20 6f 72 20 22 53 51 4c 20   names" or "SQL 
26110 70 61 72 61 6d 65 74 65 72 73 22 29 0a 2a 2a 20  parameters").** 
26120 63 61 6e 20 62 65 20 73 65 74 20 75 73 69 6e 67  can be set using
26130 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e   the sqlite3_bin
26140 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 64  d_*() routines d
26150 65 66 69 6e 65 64 20 68 65 72 65 2e 0a 2a 2a 0a  efined here..**.
26160 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72  ** ^The first ar
26170 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71  gument to the sq
26180 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72  lite3_bind_*() r
26190 6f 75 74 69 6e 65 73 20 69 73 20 61 6c 77 61 79  outines is alway
261a0 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74  s.** a pointer t
261b0 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  o the [sqlite3_s
261c0 74 6d 74 5d 20 6f 62 6a 65 63 74 20 72 65 74 75  tmt] object retu
261d0 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71  rned from.** [sq
261e0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
261f0 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61  ()] or its varia
26200 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  nts..**.** ^The 
26210 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
26220 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20  is the index of 
26230 74 68 65 20 53 51 4c 20 70 61 72 61 6d 65 74 65  the SQL paramete
26240 72 20 74 6f 20 62 65 20 73 65 74 2e 0a 2a 2a 20  r to be set..** 
26250 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 53 51  ^The leftmost SQ
26260 4c 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20  L parameter has 
26270 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2e 20 20  an index of 1.  
26280 5e 57 68 65 6e 20 74 68 65 20 73 61 6d 65 20 6e  ^When the same n
26290 61 6d 65 64 0a 2a 2a 20 53 51 4c 20 70 61 72 61  amed.** SQL para
262a0 6d 65 74 65 72 20 69 73 20 75 73 65 64 20 6d 6f  meter is used mo
262b0 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20 73 65  re than once, se
262c0 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75  cond and subsequ
262d0 65 6e 74 0a 2a 2a 20 6f 63 63 75 72 72 65 6e 63  ent.** occurrenc
262e0 65 73 20 68 61 76 65 20 74 68 65 20 73 61 6d 65  es have the same
262f0 20 69 6e 64 65 78 20 61 73 20 74 68 65 20 66 69   index as the fi
26300 72 73 74 20 6f 63 63 75 72 72 65 6e 63 65 2e 0a  rst occurrence..
26310 2a 2a 20 5e 54 68 65 20 69 6e 64 65 78 20 66 6f  ** ^The index fo
26320 72 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65  r named paramete
26330 72 73 20 63 61 6e 20 62 65 20 6c 6f 6f 6b 65 64  rs can be looked
26340 20 75 70 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a   up using the.**
26350 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
26360 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29  arameter_index()
26370 5d 20 41 50 49 20 69 66 20 64 65 73 69 72 65 64  ] API if desired
26380 2e 20 20 5e 54 68 65 20 69 6e 64 65 78 0a 2a 2a  .  ^The index.**
26390 20 66 6f 72 20 22 3f 4e 4e 4e 22 20 70 61 72 61   for "?NNN" para
263a0 6d 65 74 65 72 73 20 69 73 20 74 68 65 20 76 61  meters is the va
263b0 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 5e  lue of NNN..** ^
263c0 54 68 65 20 4e 4e 4e 20 76 61 6c 75 65 20 6d 75  The NNN value mu
263d0 73 74 20 62 65 20 62 65 74 77 65 65 6e 20 31 20  st be between 1 
263e0 61 6e 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33  and the [sqlite3
263f0 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 70 61 72  _limit()].** par
26400 61 6d 65 74 65 72 20 5b 53 51 4c 49 54 45 5f 4c  ameter [SQLITE_L
26410 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55  IMIT_VARIABLE_NU
26420 4d 42 45 52 5d 20 28 64 65 66 61 75 6c 74 20 76  MBER] (default v
26430 61 6c 75 65 3a 20 39 39 39 29 2e 0a 2a 2a 0a 2a  alue: 999)..**.*
26440 2a 20 5e 54 68 65 20 74 68 69 72 64 20 61 72 67  * ^The third arg
26450 75 6d 65 6e 74 20 69 73 20 74 68 65 20 76 61 6c  ument is the val
26460 75 65 20 74 6f 20 62 69 6e 64 20 74 6f 20 74 68  ue to bind to th
26470 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a  e parameter..**.
26480 2a 2a 20 5e 28 49 6e 20 74 68 6f 73 65 20 72 6f  ** ^(In those ro
26490 75 74 69 6e 65 73 20 74 68 61 74 20 68 61 76 65  utines that have
264a0 20 61 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65   a fourth argume
264b0 6e 74 2c 20 69 74 73 20 76 61 6c 75 65 20 69 73  nt, its value is
264c0 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f   the.** number o
264d0 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 70  f bytes in the p
264e0 61 72 61 6d 65 74 65 72 2e 20 20 54 6f 20 62 65  arameter.  To be
264f0 20 63 6c 65 61 72 3a 20 74 68 65 20 76 61 6c 75   clear: the valu
26500 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62  e is the.** numb
26510 65 72 20 6f 66 20 3c 75 3e 62 79 74 65 73 3c 2f  er of <u>bytes</
26520 75 3e 20 69 6e 20 74 68 65 20 76 61 6c 75 65 2c  u> in the value,
26530 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20   not the number 
26540 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e 29 5e  of characters.)^
26550 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 6f 75 72  .** ^If the four
26560 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
26570 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
26580 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 62  t() or sqlite3_b
26590 69 6e 64 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20  ind_text16().** 
265a0 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65  is negative, the
265b0 6e 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20  n the length of 
265c0 74 68 65 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a  the string is.**
265d0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
265e0 79 74 65 73 20 75 70 20 74 6f 20 74 68 65 20 66  ytes up to the f
265f0 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e  irst zero termin
26600 61 74 6f 72 2e 0a 2a 2a 20 49 66 20 74 68 65 20  ator..** If the 
26610 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
26620 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   to sqlite3_bind
26630 5f 62 6c 6f 62 28 29 20 69 73 20 6e 65 67 61 74  _blob() is negat
26640 69 76 65 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65  ive, then.** the
26650 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64   behavior is und
26660 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 61 20  efined..** If a 
26670 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 66 6f 75  non-negative fou
26680 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  rth parameter is
26690 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73 71 6c   provided to sql
266a0 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29  ite3_bind_text()
266b0 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 62  .** or sqlite3_b
266c0 69 6e 64 5f 74 65 78 74 31 36 28 29 20 74 68 65  ind_text16() the
266d0 6e 20 74 68 61 74 20 70 61 72 61 6d 65 74 65 72  n that parameter
266e0 20 6d 75 73 74 20 62 65 20 74 68 65 20 62 79 74   must be the byt
266f0 65 20 6f 66 66 73 65 74 0a 2a 2a 20 77 68 65 72  e offset.** wher
26700 65 20 74 68 65 20 4e 55 4c 20 74 65 72 6d 69 6e  e the NUL termin
26710 61 74 6f 72 20 77 6f 75 6c 64 20 6f 63 63 75 72  ator would occur
26720 20 61 73 73 75 6d 69 6e 67 20 74 68 65 20 73 74   assuming the st
26730 72 69 6e 67 20 77 65 72 65 20 4e 55 4c 0a 2a 2a  ring were NUL.**
26740 20 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 49 66   terminated.  If
26750 20 61 6e 79 20 4e 55 4c 20 63 68 61 72 61 63 74   any NUL charact
26760 65 72 73 20 6f 63 63 75 72 20 61 74 20 62 79 74  ers occur at byt
26770 65 20 6f 66 66 73 65 74 73 20 6c 65 73 73 20 74  e offsets less t
26780 68 61 6e 20 0a 2a 2a 20 74 68 65 20 76 61 6c 75  han .** the valu
26790 65 20 6f 66 20 74 68 65 20 66 6f 75 72 74 68 20  e of the fourth 
267a0 70 61 72 61 6d 65 74 65 72 20 74 68 65 6e 20 74  parameter then t
267b0 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72  he resulting str
267c0 69 6e 67 20 76 61 6c 75 65 20 77 69 6c 6c 0a 2a  ing value will.*
267d0 2a 20 63 6f 6e 74 61 69 6e 20 65 6d 62 65 64 64  * contain embedd
267e0 65 64 20 4e 55 4c 73 2e 20 20 54 68 65 20 72 65  ed NULs.  The re
267f0 73 75 6c 74 20 6f 66 20 65 78 70 72 65 73 73 69  sult of expressi
26800 6f 6e 73 20 69 6e 76 6f 6c 76 69 6e 67 20 73 74  ons involving st
26810 72 69 6e 67 73 0a 2a 2a 20 77 69 74 68 20 65 6d  rings.** with em
26820 62 65 64 64 65 64 20 4e 55 4c 73 20 69 73 20 75  bedded NULs is u
26830 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
26840 5e 54 68 65 20 66 69 66 74 68 20 61 72 67 75 6d  ^The fifth argum
26850 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62  ent to sqlite3_b
26860 69 6e 64 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69  ind_blob(), sqli
26870 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 2c  te3_bind_text(),
26880 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   and.** sqlite3_
26890 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20 69 73  bind_text16() is
268a0 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 75 73   a destructor us
268b0 65 64 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66  ed to dispose of
268c0 20 74 68 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20   the BLOB or.** 
268d0 73 74 72 69 6e 67 20 61 66 74 65 72 20 53 51 4c  string after SQL
268e0 69 74 65 20 68 61 73 20 66 69 6e 69 73 68 65 64  ite has finished
268f0 20 77 69 74 68 20 69 74 2e 20 20 5e 54 68 65 20   with it.  ^The 
26900 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 63 61  destructor is ca
26910 6c 6c 65 64 0a 2a 2a 20 74 6f 20 64 69 73 70 6f  lled.** to dispo
26920 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f  se of the BLOB o
26930 72 20 73 74 72 69 6e 67 20 65 76 65 6e 20 69 66  r string even if
26940 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c   the call to sql
26950 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29  ite3_bind_blob()
26960 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62 69 6e  ,.** sqlite3_bin
26970 64 5f 74 65 78 74 28 29 2c 20 6f 72 20 73 71 6c  d_text(), or sql
26980 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36  ite3_bind_text16
26990 28 29 20 66 61 69 6c 73 2e 20 20 0a 2a 2a 20 5e  () fails.  .** ^
269a0 49 66 20 74 68 65 20 66 69 66 74 68 20 61 72 67  If the fifth arg
269b0 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 74 68 65 20  ument is.** the 
269c0 73 70 65 63 69 61 6c 20 76 61 6c 75 65 20 5b 53  special value [S
269d0 51 4c 49 54 45 5f 53 54 41 54 49 43 5d 2c 20 74  QLITE_STATIC], t
269e0 68 65 6e 20 53 51 4c 69 74 65 20 61 73 73 75 6d  hen SQLite assum
269f0 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 69  es that the.** i
26a00 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 69 6e  nformation is in
26a10 20 73 74 61 74 69 63 2c 20 75 6e 6d 61 6e 61 67   static, unmanag
26a20 65 64 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65  ed space and doe
26a30 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65  s not need to be
26a40 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 74   freed..** ^If t
26a50 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e  he fifth argumen
26a60 74 20 68 61 73 20 74 68 65 20 76 61 6c 75 65 20  t has the value 
26a70 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e  [SQLITE_TRANSIEN
26a80 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69  T], then.** SQLi
26a90 74 65 20 6d 61 6b 65 73 20 69 74 73 20 6f 77 6e  te makes its own
26aa0 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66   private copy of
26ab0 20 74 68 65 20 64 61 74 61 20 69 6d 6d 65 64 69   the data immedi
26ac0 61 74 65 6c 79 2c 20 62 65 66 6f 72 65 0a 2a 2a  ately, before.**
26ad0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e   the sqlite3_bin
26ae0 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 20 72 65  d_*() routine re
26af0 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  turns..**.** ^Th
26b00 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a  e sqlite3_bind_z
26b10 65 72 6f 62 6c 6f 62 28 29 20 72 6f 75 74 69 6e  eroblob() routin
26b20 65 20 62 69 6e 64 73 20 61 20 42 4c 4f 42 20 6f  e binds a BLOB o
26b30 66 20 6c 65 6e 67 74 68 20 4e 20 74 68 61 74 0a  f length N that.
26b40 2a 2a 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74  ** is filled wit
26b50 68 20 7a 65 72 6f 65 73 2e 20 20 5e 41 20 7a 65  h zeroes.  ^A ze
26b60 72 6f 62 6c 6f 62 20 75 73 65 73 20 61 20 66 69  roblob uses a fi
26b70 78 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65  xed amount of me
26b80 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73 74 20 61 6e  mory.** (just an
26b90 20 69 6e 74 65 67 65 72 20 74 6f 20 68 6f 6c 64   integer to hold
26ba0 20 69 74 73 20 73 69 7a 65 29 20 77 68 69 6c 65   its size) while
26bb0 20 69 74 20 69 73 20 62 65 69 6e 67 20 70 72 6f   it is being pro
26bc0 63 65 73 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62  cessed..** Zerob
26bd0 6c 6f 62 73 20 61 72 65 20 69 6e 74 65 6e 64 65  lobs are intende
26be0 64 20 74 6f 20 73 65 72 76 65 20 61 73 20 70 6c  d to serve as pl
26bf0 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 42  aceholders for B
26c00 4c 4f 42 73 20 77 68 6f 73 65 0a 2a 2a 20 63 6f  LOBs whose.** co
26c10 6e 74 65 6e 74 20 69 73 20 6c 61 74 65 72 20 77  ntent is later w
26c20 72 69 74 74 65 6e 20 75 73 69 6e 67 0a 2a 2a 20  ritten using.** 
26c30 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70  [sqlite3_blob_op
26c40 65 6e 20 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c  en | incremental
26c50 20 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75 74 69   BLOB I/O] routi
26c60 6e 65 73 2e 0a 2a 2a 20 5e 41 20 6e 65 67 61 74  nes..** ^A negat
26c70 69 76 65 20 76 61 6c 75 65 20 66 6f 72 20 74 68  ive value for th
26c80 65 20 7a 65 72 6f 62 6c 6f 62 20 72 65 73 75 6c  e zeroblob resul
26c90 74 73 20 69 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e  ts in a zero-len
26ca0 67 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20  gth BLOB..**.** 
26cb0 5e 49 66 20 61 6e 79 20 6f 66 20 74 68 65 20 73  ^If any of the s
26cc0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20  qlite3_bind_*() 
26cd0 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c  routines are cal
26ce0 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c 20  led with a NULL 
26cf0 70 6f 69 6e 74 65 72 0a 2a 2a 20 66 6f 72 20 74  pointer.** for t
26d00 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
26d10 74 65 6d 65 6e 74 5d 20 6f 72 20 77 69 74 68 20  tement] or with 
26d20 61 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  a prepared state
26d30 6d 65 6e 74 20 66 6f 72 20 77 68 69 63 68 0a 2a  ment for which.*
26d40 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  * [sqlite3_step(
26d50 29 5d 20 68 61 73 20 62 65 65 6e 20 63 61 6c 6c  )] has been call
26d60 65 64 20 6d 6f 72 65 20 72 65 63 65 6e 74 6c 79  ed more recently
26d70 20 74 68 61 6e 20 5b 73 71 6c 69 74 65 33 5f 72   than [sqlite3_r
26d80 65 73 65 74 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e  eset()],.** then
26d90 20 74 68 65 20 63 61 6c 6c 20 77 69 6c 6c 20 72   the call will r
26da0 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4d 49  eturn [SQLITE_MI
26db0 53 55 53 45 5d 2e 20 20 49 66 20 61 6e 79 20 73  SUSE].  If any s
26dc0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 28 29 0a 2a  qlite3_bind_().*
26dd0 2a 20 72 6f 75 74 69 6e 65 20 69 73 20 70 61 73  * routine is pas
26de0 73 65 64 20 61 20 5b 70 72 65 70 61 72 65 64 20  sed a [prepared 
26df0 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20  statement] that 
26e00 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a  has been finaliz
26e10 65 64 2c 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c  ed, the.** resul
26e20 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61  t is undefined a
26e30 6e 64 20 70 72 6f 62 61 62 6c 79 20 68 61 72 6d  nd probably harm
26e40 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 42 69 6e 64  ful..**.** ^Bind
26e50 69 6e 67 73 20 61 72 65 20 6e 6f 74 20 63 6c 65  ings are not cle
26e60 61 72 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c  ared by the [sql
26e70 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 72 6f  ite3_reset()] ro
26e80 75 74 69 6e 65 2e 0a 2a 2a 20 5e 55 6e 62 6f 75  utine..** ^Unbou
26e90 6e 64 20 70 61 72 61 6d 65 74 65 72 73 20 61 72  nd parameters ar
26ea0 65 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  e interpreted as
26eb0 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68   NULL..**.** ^Th
26ec0 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
26ed0 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
26ee0 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20   [SQLITE_OK] on 
26ef0 73 75 63 63 65 73 73 20 6f 72 20 61 6e 0a 2a 2a  success or an.**
26f00 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66   [error code] if
26f10 20 61 6e 79 74 68 69 6e 67 20 67 6f 65 73 20 77   anything goes w
26f20 72 6f 6e 67 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54  rong..** ^[SQLIT
26f30 45 5f 52 41 4e 47 45 5d 20 69 73 20 72 65 74 75  E_RANGE] is retu
26f40 72 6e 65 64 20 69 66 20 74 68 65 20 70 61 72 61  rned if the para
26f50 6d 65 74 65 72 0a 2a 2a 20 69 6e 64 65 78 20 69  meter.** index i
26f60 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2e 20  s out of range. 
26f70 20 5e 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d   ^[SQLITE_NOMEM]
26f80 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20   is returned if 
26f90 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 2e 0a  malloc() fails..
26fa0 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
26fb0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
26fc0 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d  rameter_count()]
26fd0 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  ,.** [sqlite3_bi
26fe0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d  nd_parameter_nam
26ff0 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74  e()], and [sqlit
27000 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
27010 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69  r_index()]..*/.i
27020 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
27030 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d  blob(sqlite3_stm
27040 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76  t*, int, const v
27050 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69  oid*, int n, voi
27060 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e  d(*)(void*));.in
27070 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64  t sqlite3_bind_d
27080 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74  ouble(sqlite3_st
27090 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65  mt*, int, double
270a0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
270b0 69 6e 64 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f  ind_int(sqlite3_
270c0 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29  stmt*, int, int)
270d0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
270e0 6e 64 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33  nd_int64(sqlite3
270f0 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c  _stmt*, int, sql
27100 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 69 6e 74  ite3_int64);.int
27110 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75   sqlite3_bind_nu
27120 6c 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ll(sqlite3_stmt*
27130 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69  , int);.int sqli
27140 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 73 71  te3_bind_text(sq
27150 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
27160 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69  , const char*, i
27170 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f  nt n, void(*)(vo
27180 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74  id*));.int sqlit
27190 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 73  e3_bind_text16(s
271a0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
271b0 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  t, const void*, 
271c0 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  int, void(*)(voi
271d0 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  d*));.int sqlite
271e0 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 73 71 6c  3_bind_value(sql
271f0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
27200 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 76   const sqlite3_v
27210 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69  alue*);.int sqli
27220 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f  te3_bind_zeroblo
27230 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  b(sqlite3_stmt*,
27240 20 69 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f   int, int n);../
27250 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e  *.** CAPI3REF: N
27260 75 6d 62 65 72 20 4f 66 20 53 51 4c 20 50 61 72  umber Of SQL Par
27270 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 5e 54  ameters.**.** ^T
27280 68 69 73 20 72 6f 75 74 69 6e 65 20 63 61 6e 20  his routine can 
27290 62 65 20 75 73 65 64 20 74 6f 20 66 69 6e 64 20  be used to find 
272a0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 5b 53  the number of [S
272b0 51 4c 20 70 61 72 61 6d 65 74 65 72 73 5d 0a 2a  QL parameters].*
272c0 2a 20 69 6e 20 61 20 5b 70 72 65 70 61 72 65 64  * in a [prepared
272d0 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 53 51   statement].  SQ
272e0 4c 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65  L parameters are
272f0 20 74 6f 6b 65 6e 73 20 6f 66 20 74 68 65 0a 2a   tokens of the.*
27300 2a 20 66 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e  * form "?", "?NN
27310 4e 22 2c 20 22 3a 41 41 41 22 2c 20 22 24 41 41  N", ":AAA", "$AA
27320 41 22 2c 20 6f 72 20 22 40 41 41 41 22 20 74 68  A", or "@AAA" th
27330 61 74 20 73 65 72 76 65 20 61 73 0a 2a 2a 20 70  at serve as.** p
27340 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20  laceholders for 
27350 76 61 6c 75 65 73 20 74 68 61 74 20 61 72 65 20  values that are 
27360 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
27370 6f 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74  ob | bound].** t
27380 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 73  o the parameters
27390 20 61 74 20 61 20 6c 61 74 65 72 20 74 69 6d 65   at a later time
273a0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72  ..**.** ^(This r
273b0 6f 75 74 69 6e 65 20 61 63 74 75 61 6c 6c 79 20  outine actually 
273c0 72 65 74 75 72 6e 73 20 74 68 65 20 69 6e 64 65  returns the inde
273d0 78 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74  x of the largest
273e0 20 28 72 69 67 68 74 6d 6f 73 74 29 0a 2a 2a 20   (rightmost).** 
273f0 70 61 72 61 6d 65 74 65 72 2e 20 46 6f 72 20 61  parameter. For a
27400 6c 6c 20 66 6f 72 6d 73 20 65 78 63 65 70 74 20  ll forms except 
27410 3f 4e 4e 4e 2c 20 74 68 69 73 20 77 69 6c 6c 20  ?NNN, this will 
27420 63 6f 72 72 65 73 70 6f 6e 64 20 74 6f 20 74 68  correspond to th
27430 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 75  e.** number of u
27440 6e 69 71 75 65 20 70 61 72 61 6d 65 74 65 72 73  nique parameters
27450 2e 20 20 49 66 20 70 61 72 61 6d 65 74 65 72 73  .  If parameters
27460 20 6f 66 20 74 68 65 20 3f 4e 4e 4e 20 66 6f 72   of the ?NNN for
27470 6d 20 61 72 65 20 75 73 65 64 2c 0a 2a 2a 20 74  m are used,.** t
27480 68 65 72 65 20 6d 61 79 20 62 65 20 67 61 70 73  here may be gaps
27490 20 69 6e 20 74 68 65 20 6c 69 73 74 2e 29 5e 0a   in the list.)^.
274a0 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
274b0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
274c0 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28  ob|sqlite3_bind(
274d0 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
274e0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e  bind_parameter_n
274f0 61 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b  ame()], and.** [
27500 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
27510 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e  ameter_index()].
27520 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
27530 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63  bind_parameter_c
27540 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  ount(sqlite3_stm
27550 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
27560 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 41 20  3REF: Name Of A 
27570 48 6f 73 74 20 50 61 72 61 6d 65 74 65 72 0a 2a  Host Parameter.*
27580 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
27590 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
275a0 5f 6e 61 6d 65 28 50 2c 4e 29 20 69 6e 74 65 72  _name(P,N) inter
275b0 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20  face returns.** 
275c0 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
275d0 4e 2d 74 68 20 5b 53 51 4c 20 70 61 72 61 6d 65  N-th [SQL parame
275e0 74 65 72 5d 20 69 6e 20 74 68 65 20 5b 70 72 65  ter] in the [pre
275f0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
27600 20 50 2e 0a 2a 2a 20 5e 28 53 51 4c 20 70 61 72   P..** ^(SQL par
27610 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 66  ameters of the f
27620 6f 72 6d 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a  orm "?NNN" or ":
27630 41 41 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f  AAA" or "@AAA" o
27640 72 20 22 24 41 41 41 22 0a 2a 2a 20 68 61 76 65  r "$AAA".** have
27650 20 61 20 6e 61 6d 65 20 77 68 69 63 68 20 69 73   a name which is
27660 20 74 68 65 20 73 74 72 69 6e 67 20 22 3f 4e 4e   the string "?NN
27670 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20  N" or ":AAA" or 
27680 22 40 41 41 41 22 20 6f 72 20 22 24 41 41 41 22  "@AAA" or "$AAA"
27690 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79  .** respectively
276a0 2e 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f  ..** In other wo
276b0 72 64 73 2c 20 74 68 65 20 69 6e 69 74 69 61 6c  rds, the initial
276c0 20 22 3a 22 20 6f 72 20 22 24 22 20 6f 72 20 22   ":" or "$" or "
276d0 40 22 20 6f 72 20 22 3f 22 0a 2a 2a 20 69 73 20  @" or "?".** is 
276e0 69 6e 63 6c 75 64 65 64 20 61 73 20 70 61 72 74  included as part
276f0 20 6f 66 20 74 68 65 20 6e 61 6d 65 2e 29 5e 0a   of the name.)^.
27700 2a 2a 20 5e 50 61 72 61 6d 65 74 65 72 73 20 6f  ** ^Parameters o
27710 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 22 20 77  f the form "?" w
27720 69 74 68 6f 75 74 20 61 20 66 6f 6c 6c 6f 77 69  ithout a followi
27730 6e 67 20 69 6e 74 65 67 65 72 20 68 61 76 65 20  ng integer have 
27740 6e 6f 20 6e 61 6d 65 0a 2a 2a 20 61 6e 64 20 61  no name.** and a
27750 72 65 20 72 65 66 65 72 72 65 64 20 74 6f 20 61  re referred to a
27760 73 20 22 6e 61 6d 65 6c 65 73 73 22 20 6f 72 20  s "nameless" or 
27770 22 61 6e 6f 6e 79 6d 6f 75 73 20 70 61 72 61 6d  "anonymous param
27780 65 74 65 72 73 22 2e 0a 2a 2a 0a 2a 2a 20 5e 54  eters"..**.** ^T
27790 68 65 20 66 69 72 73 74 20 68 6f 73 74 20 70 61  he first host pa
277a0 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69  rameter has an i
277b0 6e 64 65 78 20 6f 66 20 31 2c 20 6e 6f 74 20 30  ndex of 1, not 0
277c0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
277d0 76 61 6c 75 65 20 4e 20 69 73 20 6f 75 74 20 6f  value N is out o
277e0 66 20 72 61 6e 67 65 20 6f 72 20 69 66 20 74 68  f range or if th
277f0 65 20 4e 2d 74 68 20 70 61 72 61 6d 65 74 65 72  e N-th parameter
27800 20 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c   is.** nameless,
27810 20 74 68 65 6e 20 4e 55 4c 4c 20 69 73 20 72 65   then NULL is re
27820 74 75 72 6e 65 64 2e 20 20 5e 54 68 65 20 72 65  turned.  ^The re
27830 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73  turned string is
27840 0a 2a 2a 20 61 6c 77 61 79 73 20 69 6e 20 55 54  .** always in UT
27850 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 65 76 65  F-8 encoding eve
27860 6e 20 69 66 20 74 68 65 20 6e 61 6d 65 64 20 70  n if the named p
27870 61 72 61 6d 65 74 65 72 20 77 61 73 0a 2a 2a 20  arameter was.** 
27880 6f 72 69 67 69 6e 61 6c 6c 79 20 73 70 65 63 69  originally speci
27890 66 69 65 64 20 61 73 20 55 54 46 2d 31 36 20 69  fied as UTF-16 i
278a0 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  n [sqlite3_prepa
278b0 72 65 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73  re16()] or.** [s
278c0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
278d0 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65  _v2()]..**.** Se
278e0 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
278f0 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74  _bind_blob|sqlit
27900 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b  e3_bind()],.** [
27910 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
27920 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c  ameter_count()],
27930 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
27940 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
27950 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e  index()]..*/.con
27960 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
27970 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
27980 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
27990 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  t*, int);../*.**
279a0 20 43 41 50 49 33 52 45 46 3a 20 49 6e 64 65 78   CAPI3REF: Index
279b0 20 4f 66 20 41 20 50 61 72 61 6d 65 74 65 72 20   Of A Parameter 
279c0 57 69 74 68 20 41 20 47 69 76 65 6e 20 4e 61 6d  With A Given Nam
279d0 65 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20  e.**.** ^Return 
279e0 74 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20  the index of an 
279f0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 67 69  SQL parameter gi
27a00 76 65 6e 20 69 74 73 20 6e 61 6d 65 2e 20 20 5e  ven its name.  ^
27a10 54 68 65 0a 2a 2a 20 69 6e 64 65 78 20 76 61 6c  The.** index val
27a20 75 65 20 72 65 74 75 72 6e 65 64 20 69 73 20 73  ue returned is s
27a30 75 69 74 61 62 6c 65 20 66 6f 72 20 75 73 65 20  uitable for use 
27a40 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a  as the second.**
27a50 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73   parameter to [s
27a60 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
27a70 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d  |sqlite3_bind()]
27a80 2e 20 20 5e 41 20 7a 65 72 6f 0a 2a 2a 20 69 73  .  ^A zero.** is
27a90 20 72 65 74 75 72 6e 65 64 20 69 66 20 6e 6f 20   returned if no 
27aa0 6d 61 74 63 68 69 6e 67 20 70 61 72 61 6d 65 74  matching paramet
27ab0 65 72 20 69 73 20 66 6f 75 6e 64 2e 20 20 5e 54  er is found.  ^T
27ac0 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  he parameter.** 
27ad0 6e 61 6d 65 20 6d 75 73 74 20 62 65 20 67 69 76  name must be giv
27ae0 65 6e 20 69 6e 20 55 54 46 2d 38 20 65 76 65 6e  en in UTF-8 even
27af0 20 69 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c   if the original
27b00 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 61   statement.** wa
27b10 73 20 70 72 65 70 61 72 65 64 20 66 72 6f 6d 20  s prepared from 
27b20 55 54 46 2d 31 36 20 74 65 78 74 20 75 73 69 6e  UTF-16 text usin
27b30 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  g [sqlite3_prepa
27b40 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a  re16_v2()]..**.*
27b50 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
27b60 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73  ite3_bind_blob|s
27b70 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a  qlite3_bind()],.
27b80 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
27b90 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74  _parameter_count
27ba0 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ()], and.** [sql
27bb0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
27bc0 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f  ter_index()]..*/
27bd0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
27be0 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65  d_parameter_inde
27bf0 78 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  x(sqlite3_stmt*,
27c00 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
27c10 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  me);../*.** CAPI
27c20 33 52 45 46 3a 20 52 65 73 65 74 20 41 6c 6c 20  3REF: Reset All 
27c30 42 69 6e 64 69 6e 67 73 20 4f 6e 20 41 20 50 72  Bindings On A Pr
27c40 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
27c50 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 74 72 61 72 79  .**.** ^Contrary
27c60 20 74 6f 20 74 68 65 20 69 6e 74 75 69 74 69 6f   to the intuitio
27c70 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b 73 71 6c 69  n of many, [sqli
27c80 74 65 33 5f 72 65 73 65 74 28 29 5d 20 64 6f 65  te3_reset()] doe
27c90 73 20 6e 6f 74 20 72 65 73 65 74 0a 2a 2a 20 74  s not reset.** t
27ca0 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  he [sqlite3_bind
27cb0 5f 62 6c 6f 62 20 7c 20 62 69 6e 64 69 6e 67 73  _blob | bindings
27cc0 5d 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64  ] on a [prepared
27cd0 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20   statement]..** 
27ce0 5e 55 73 65 20 74 68 69 73 20 72 6f 75 74 69 6e  ^Use this routin
27cf0 65 20 74 6f 20 72 65 73 65 74 20 61 6c 6c 20 68  e to reset all h
27d00 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 74  ost parameters t
27d10 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73  o NULL..*/.int s
27d20 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e  qlite3_clear_bin
27d30 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74  dings(sqlite3_st
27d40 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  mt*);../*.** CAP
27d50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66  I3REF: Number Of
27d60 20 43 6f 6c 75 6d 6e 73 20 49 6e 20 41 20 52 65   Columns In A Re
27d70 73 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e  sult Set.**.** ^
27d80 52 65 74 75 72 6e 20 74 68 65 20 6e 75 6d 62 65  Return the numbe
27d90 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
27da0 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 72  the result set r
27db0 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a  eturned by the.*
27dc0 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
27dd0 65 6d 65 6e 74 5d 2e 20 5e 54 68 69 73 20 72 6f  ement]. ^This ro
27de0 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30 20  utine returns 0 
27df0 69 66 20 70 53 74 6d 74 20 69 73 20 61 6e 20 53  if pStmt is an S
27e00 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  QL.** statement 
27e10 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 72 65  that does not re
27e20 74 75 72 6e 20 64 61 74 61 20 28 66 6f 72 20 65  turn data (for e
27e30 78 61 6d 70 6c 65 20 61 6e 20 5b 55 50 44 41 54  xample an [UPDAT
27e40 45 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  E])..**.** See a
27e50 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 64 61  lso: [sqlite3_da
27e60 74 61 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69  ta_count()].*/.i
27e70 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nt sqlite3_colum
27e80 6e 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f  n_count(sqlite3_
27e90 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
27ea0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
27eb0 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 6e 20 41  olumn Names In A
27ec0 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a   Result Set.**.*
27ed0 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65  * ^These routine
27ee0 73 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d  s return the nam
27ef0 65 20 61 73 73 69 67 6e 65 64 20 74 6f 20 61 20  e assigned to a 
27f00 70 61 72 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d  particular colum
27f10 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65 73 75  n.** in the resu
27f20 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c  lt set of a [SEL
27f30 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20  ECT] statement. 
27f40 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f   ^The sqlite3_co
27f50 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69  lumn_name().** i
27f60 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
27f70 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
27f80 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
27f90 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20  UTF-8 string.** 
27fa0 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  and sqlite3_colu
27fb0 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 72 65 74 75  mn_name16() retu
27fc0 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
27fd0 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
27fe0 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72  ed.** UTF-16 str
27ff0 69 6e 67 2e 20 20 5e 54 68 65 20 66 69 72 73 74  ing.  ^The first
28000 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
28010 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
28020 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61 74 20 69  ement].** that i
28030 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 5b 53  mplements the [S
28040 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74  ELECT] statement
28050 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61  . ^The second pa
28060 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a  rameter is the.*
28070 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e  * column number.
28080 20 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20    ^The leftmost 
28090 63 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d 62 65 72  column is number
280a0 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72   0..**.** ^The r
280b0 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 70  eturned string p
280c0 6f 69 6e 74 65 72 20 69 73 20 76 61 6c 69 64 20  ointer is valid 
280d0 75 6e 74 69 6c 20 65 69 74 68 65 72 20 74 68 65  until either the
280e0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
280f0 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20 64 65 73 74  ment].** is dest
28100 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74 65  royed by [sqlite
28110 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72  3_finalize()] or
28120 20 75 6e 74 69 6c 20 74 68 65 20 73 74 61 74 65   until the state
28130 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 69  ment is automati
28140 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61  cally.** reprepa
28150 72 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74  red by the first
28160 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
28170 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 61 20  3_step()] for a 
28180 70 61 72 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a  particular run.*
28190 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 6e  * or until the n
281a0 65 78 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73  ext call to.** s
281b0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
281c0 6d 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  me() or sqlite3_
281d0 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20  column_name16() 
281e0 6f 6e 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 75  on the same colu
281f0 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 73 71  mn..**.** ^If sq
28200 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66  lite3_malloc() f
28210 61 69 6c 73 20 64 75 72 69 6e 67 20 74 68 65 20  ails during the 
28220 70 72 6f 63 65 73 73 69 6e 67 20 6f 66 20 65 69  processing of ei
28230 74 68 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a 20  ther routine.** 
28240 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 64 75 72  (for example dur
28250 69 6e 67 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e  ing a conversion
28260 20 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55   from UTF-8 to U
28270 54 46 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a 2a  TF-16) then a.**
28280 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73   NULL pointer is
28290 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
282a0 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 61 20   ^The name of a 
282b0 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73  result column is
282c0 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68   the value of th
282d0 65 20 22 41 53 22 20 63 6c 61 75 73 65 20 66 6f  e "AS" clause fo
282e0 72 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 75 6d 6e  r.** that column
282f0 2c 20 69 66 20 74 68 65 72 65 20 69 73 20 61 6e  , if there is an
28300 20 41 53 20 63 6c 61 75 73 65 2e 20 20 49 66 20   AS clause.  If 
28310 74 68 65 72 65 20 69 73 20 6e 6f 20 41 53 20 63  there is no AS c
28320 6c 61 75 73 65 0a 2a 2a 20 74 68 65 6e 20 74 68  lause.** then th
28330 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 6f  e name of the co
28340 6c 75 6d 6e 20 69 73 20 75 6e 73 70 65 63 69 66  lumn is unspecif
28350 69 65 64 20 61 6e 64 20 6d 61 79 20 63 68 61 6e  ied and may chan
28360 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72  ge from.** one r
28370 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65  elease of SQLite
28380 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2f   to the next..*/
28390 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
283a0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
283b0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
283c0 69 6e 74 20 4e 29 3b 0a 63 6f 6e 73 74 20 76 6f  int N);.const vo
283d0 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
283e0 6d 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65  mn_name16(sqlite
283f0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b  3_stmt*, int N);
28400 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
28410 3a 20 53 6f 75 72 63 65 20 4f 66 20 44 61 74 61  : Source Of Data
28420 20 49 6e 20 41 20 51 75 65 72 79 20 52 65 73 75   In A Query Resu
28430 6c 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  lt.**.** ^These 
28440 72 6f 75 74 69 6e 65 73 20 70 72 6f 76 69 64 65  routines provide
28450 20 61 20 6d 65 61 6e 73 20 74 6f 20 64 65 74 65   a means to dete
28460 72 6d 69 6e 65 20 74 68 65 20 64 61 74 61 62 61  rmine the databa
28470 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 0a 2a  se, table, and.*
28480 2a 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74  * table column t
28490 68 61 74 20 69 73 20 74 68 65 20 6f 72 69 67 69  hat is the origi
284a0 6e 20 6f 66 20 61 20 70 61 72 74 69 63 75 6c 61  n of a particula
284b0 72 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  r result column 
284c0 69 6e 0a 2a 2a 20 5b 53 45 4c 45 43 54 5d 20 73  in.** [SELECT] s
284d0 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68  tatement..** ^Th
284e0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61  e name of the da
284f0 74 61 62 61 73 65 20 6f 72 20 74 61 62 6c 65 20  tabase or table 
28500 6f 72 20 63 6f 6c 75 6d 6e 20 63 61 6e 20 62 65  or column can be
28510 20 72 65 74 75 72 6e 65 64 20 61 73 0a 2a 2a 20   returned as.** 
28520 65 69 74 68 65 72 20 61 20 55 54 46 2d 38 20 6f  either a UTF-8 o
28530 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e  r UTF-16 string.
28540 20 20 5e 54 68 65 20 5f 64 61 74 61 62 61 73 65    ^The _database
28550 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  _ routines retur
28560 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73  n.** the databas
28570 65 20 6e 61 6d 65 2c 20 74 68 65 20 5f 74 61 62  e name, the _tab
28580 6c 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74  le_ routines ret
28590 75 72 6e 20 74 68 65 20 74 61 62 6c 65 20 6e 61  urn the table na
285a0 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74 68 65 20 6f  me, and.** the o
285b0 72 69 67 69 6e 5f 20 72 6f 75 74 69 6e 65 73 20  rigin_ routines 
285c0 72 65 74 75 72 6e 20 74 68 65 20 63 6f 6c 75 6d  return the colum
285d0 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20  n name..** ^The 
285e0 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20  returned string 
285f0 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 74  is valid until t
28600 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
28610 74 65 6d 65 6e 74 5d 20 69 73 20 64 65 73 74 72  tement] is destr
28620 6f 79 65 64 0a 2a 2a 20 75 73 69 6e 67 20 5b 73  oyed.** using [s
28630 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
28640 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20  )] or until the 
28650 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 75 74  statement is aut
28660 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65  omatically.** re
28670 70 72 65 70 61 72 65 64 20 62 79 20 74 68 65 20  prepared by the 
28680 66 69 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73  first call to [s
28690 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 66  qlite3_step()] f
286a0 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  or a particular 
286b0 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20  run.** or until 
286c0 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61  the same informa
286d0 74 69 6f 6e 20 69 73 20 72 65 71 75 65 73 74 65  tion is requeste
286e0 64 0a 2a 2a 20 61 67 61 69 6e 20 69 6e 20 61 20  d.** again in a 
286f0 64 69 66 66 65 72 65 6e 74 20 65 6e 63 6f 64 69  different encodi
28700 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e  ng..**.** ^The n
28710 61 6d 65 73 20 72 65 74 75 72 6e 65 64 20 61 72  ames returned ar
28720 65 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 75  e the original u
28730 6e 2d 61 6c 69 61 73 65 64 20 6e 61 6d 65 73 20  n-aliased names 
28740 6f 66 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  of the.** databa
28750 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 20 63  se, table, and c
28760 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  olumn..**.** ^Th
28770 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
28780 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66   to these interf
28790 61 63 65 73 20 69 73 20 61 20 5b 70 72 65 70 61  aces is a [prepa
287a0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a  red statement]..
287b0 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69  ** ^These functi
287c0 6f 6e 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72  ons return infor
287d0 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 74 68 65  mation about the
287e0 20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75   Nth result colu
287f0 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a  mn returned by.*
28800 2a 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2c  * the statement,
28810 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20   where N is the 
28820 73 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20  second function 
28830 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68  argument..** ^Th
28840 65 20 6c 65 66 74 2d 6d 6f 73 74 20 63 6f 6c 75  e left-most colu
28850 6d 6e 20 69 73 20 63 6f 6c 75 6d 6e 20 30 20 66  mn is column 0 f
28860 6f 72 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  or these routine
28870 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  s..**.** ^If the
28880 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75   Nth column retu
28890 72 6e 65 64 20 62 79 20 74 68 65 20 73 74 61 74  rned by the stat
288a0 65 6d 65 6e 74 20 69 73 20 61 6e 20 65 78 70 72  ement is an expr
288b0 65 73 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62  ession or.** sub
288c0 71 75 65 72 79 20 61 6e 64 20 69 73 20 6e 6f 74  query and is not
288d0 20 61 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c   a column value,
288e0 20 74 68 65 6e 20 61 6c 6c 20 6f 66 20 74 68 65   then all of the
288f0 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74  se functions ret
28900 75 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 5e 54  urn.** NULL.  ^T
28910 68 65 73 65 20 72 6f 75 74 69 6e 65 20 6d 69 67  hese routine mig
28920 68 74 20 61 6c 73 6f 20 72 65 74 75 72 6e 20 4e  ht also return N
28930 55 4c 4c 20 69 66 20 61 20 6d 65 6d 6f 72 79 20  ULL if a memory 
28940 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72  allocation error
28950 0a 2a 2a 20 6f 63 63 75 72 73 2e 20 20 5e 4f 74  .** occurs.  ^Ot
28960 68 65 72 77 69 73 65 2c 20 74 68 65 79 20 72 65  herwise, they re
28970 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66  turn the name of
28980 20 74 68 65 20 61 74 74 61 63 68 65 64 20 64 61   the attached da
28990 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 0a 2a  tabase, table,.*
289a0 2a 20 6f 72 20 63 6f 6c 75 6d 6e 20 74 68 61 74  * or column that
289b0 20 71 75 65 72 79 20 72 65 73 75 6c 74 20 63 6f   query result co
289c0 6c 75 6d 6e 20 77 61 73 20 65 78 74 72 61 63 74  lumn was extract
289d0 65 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e  ed from..**.** ^
289e0 41 73 20 77 69 74 68 20 61 6c 6c 20 6f 74 68 65  As with all othe
289f0 72 20 53 51 4c 69 74 65 20 41 50 49 73 2c 20 74  r SQLite APIs, t
28a00 68 6f 73 65 20 77 68 6f 73 65 20 6e 61 6d 65 73  hose whose names
28a10 20 65 6e 64 20 77 69 74 68 20 22 31 36 22 20 72   end with "16" r
28a20 65 74 75 72 6e 0a 2a 2a 20 55 54 46 2d 31 36 20  eturn.** UTF-16 
28a30 65 6e 63 6f 64 65 64 20 73 74 72 69 6e 67 73 20  encoded strings 
28a40 61 6e 64 20 74 68 65 20 6f 74 68 65 72 20 66 75  and the other fu
28a50 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 55  nctions return U
28a60 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  TF-8..**.** ^The
28a70 73 65 20 41 50 49 73 20 61 72 65 20 6f 6e 6c 79  se APIs are only
28a80 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 74 68   available if th
28a90 65 20 6c 69 62 72 61 72 79 20 77 61 73 20 63 6f  e library was co
28aa0 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a  mpiled with the.
28ab0 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c  ** [SQLITE_ENABL
28ac0 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54  E_COLUMN_METADAT
28ad0 41 5d 20 43 2d 70 72 65 70 72 6f 63 65 73 73 6f  A] C-preprocesso
28ae0 72 20 73 79 6d 62 6f 6c 2e 0a 2a 2a 0a 2a 2a 20  r symbol..**.** 
28af0 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74  If two or more t
28b00 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20  hreads call one 
28b10 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68 65 73 65  or more of these
28b20 20 72 6f 75 74 69 6e 65 73 20 61 67 61 69 6e 73   routines agains
28b30 74 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 70 72  t the same.** pr
28b40 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
28b50 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 61 74 20 74   and column at t
28b60 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65  he same time the
28b70 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72  n the results ar
28b80 65 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a  e.** undefined..
28b90 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20  **.** If two or 
28ba0 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63 61 6c  more threads cal
28bb0 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a  l one or more.**
28bc0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
28bd0 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 20 7c  _database_name |
28be0 20 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 74 61   column metadata
28bf0 20 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a 2a 20   interfaces].** 
28c00 66 6f 72 20 74 68 65 20 73 61 6d 65 20 5b 70 72  for the same [pr
28c10 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
28c20 5d 20 61 6e 64 20 72 65 73 75 6c 74 20 63 6f 6c  ] and result col
28c30 75 6d 6e 0a 2a 2a 20 61 74 20 74 68 65 20 73 61  umn.** at the sa
28c40 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65  me time then the
28c50 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64   results are und
28c60 65 66 69 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e 73 74  efined..*/.const
28c70 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
28c80 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e  olumn_database_n
28c90 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
28ca0 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f  *,int);.const vo
28cb0 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
28cc0 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65  mn_database_name
28cd0 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
28ce0 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61  ,int);.const cha
28cf0 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
28d00 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 73 71 6c  n_table_name(sql
28d10 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
28d20 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
28d30 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c  ite3_column_tabl
28d40 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33  e_name16(sqlite3
28d50 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e  _stmt*,int);.con
28d60 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
28d70 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e  _column_origin_n
28d80 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
28d90 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f  *,int);.const vo
28da0 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
28db0 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36  mn_origin_name16
28dc0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
28dd0 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
28de0 33 52 45 46 3a 20 44 65 63 6c 61 72 65 64 20 44  3REF: Declared D
28df0 61 74 61 74 79 70 65 20 4f 66 20 41 20 51 75 65  atatype Of A Que
28e00 72 79 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20  ry Result.**.** 
28e10 5e 28 54 68 65 20 66 69 72 73 74 20 70 61 72 61  ^(The first para
28e20 6d 65 74 65 72 20 69 73 20 61 20 5b 70 72 65 70  meter is a [prep
28e30 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
28e40 0a 2a 2a 20 49 66 20 74 68 69 73 20 73 74 61 74  .** If this stat
28e50 65 6d 65 6e 74 20 69 73 20 61 20 5b 53 45 4c 45  ement is a [SELE
28e60 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 6e  CT] statement an
28e70 64 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e  d the Nth column
28e80 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 74 75 72   of the.** retur
28e90 6e 65 64 20 72 65 73 75 6c 74 20 73 65 74 20 6f  ned result set o
28ea0 66 20 74 68 61 74 20 5b 53 45 4c 45 43 54 5d 20  f that [SELECT] 
28eb0 69 73 20 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d  is a table colum
28ec0 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70  n (not an.** exp
28ed0 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75  ression or subqu
28ee0 65 72 79 29 20 74 68 65 6e 20 74 68 65 20 64 65  ery) then the de
28ef0 63 6c 61 72 65 64 20 74 79 70 65 20 6f 66 20 74  clared type of t
28f00 68 65 20 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75  he table.** colu
28f10 6d 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29  mn is returned.)
28f20 5e 20 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63  ^  ^If the Nth c
28f30 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73  olumn of the res
28f40 75 6c 74 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a  ult set is an.**
28f50 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73   expression or s
28f60 75 62 71 75 65 72 79 2c 20 74 68 65 6e 20 61 20  ubquery, then a 
28f70 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20  NULL pointer is 
28f80 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 54 68  returned..** ^Th
28f90 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e  e returned strin
28fa0 67 20 69 73 20 61 6c 77 61 79 73 20 55 54 46 2d  g is always UTF-
28fb0 38 20 65 6e 63 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a  8 encoded..**.**
28fc0 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20   ^(For example, 
28fd0 67 69 76 65 6e 20 74 68 65 20 64 61 74 61 62 61  given the databa
28fe0 73 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a  se schema:.**.**
28ff0 20 43 52 45 41 54 45 20 54 41 42 4c 45 20 74 31   CREATE TABLE t1
29000 28 63 31 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a  (c1 VARIANT);.**
29010 0a 2a 2a 20 61 6e 64 20 74 68 65 20 66 6f 6c 6c  .** and the foll
29020 6f 77 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20  owing statement 
29030 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 3a 0a  to be compiled:.
29040 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63 31 20  **.** SELECT c1 
29050 2b 20 31 2c 20 63 31 20 46 52 4f 4d 20 74 31 3b  + 1, c1 FROM t1;
29060 0a 2a 2a 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74  .**.** this rout
29070 69 6e 65 20 77 6f 75 6c 64 20 72 65 74 75 72 6e  ine would return
29080 20 74 68 65 20 73 74 72 69 6e 67 20 22 56 41 52   the string "VAR
29090 49 41 4e 54 22 20 66 6f 72 20 74 68 65 20 73 65  IANT" for the se
290a0 63 6f 6e 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63  cond result.** c
290b0 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e  olumn (i==1), an
290c0 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  d a NULL pointer
290d0 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 72   for the first r
290e0 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d  esult column (i=
290f0 3d 30 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51  =0).)^.**.** ^SQ
29100 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69  Lite uses dynami
29110 63 20 72 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e  c run-time typin
29120 67 2e 20 20 5e 53 6f 20 6a 75 73 74 20 62 65 63  g.  ^So just bec
29130 61 75 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a  ause a column.**
29140 20 69 73 20 64 65 63 6c 61 72 65 64 20 74 6f 20   is declared to 
29150 63 6f 6e 74 61 69 6e 20 61 20 70 61 72 74 69 63  contain a partic
29160 75 6c 61 72 20 74 79 70 65 20 64 6f 65 73 20 6e  ular type does n
29170 6f 74 20 6d 65 61 6e 20 74 68 61 74 20 74 68 65  ot mean that the
29180 0a 2a 2a 20 64 61 74 61 20 73 74 6f 72 65 64 20  .** data stored 
29190 69 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69  in that column i
291a0 73 20 6f 66 20 74 68 65 20 64 65 63 6c 61 72 65  s of the declare
291b0 64 20 74 79 70 65 2e 20 20 53 51 4c 69 74 65 20  d type.  SQLite 
291c0 69 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74  is.** strongly t
291d0 79 70 65 64 2c 20 62 75 74 20 74 68 65 20 74 79  yped, but the ty
291e0 70 69 6e 67 20 69 73 20 64 79 6e 61 6d 69 63 20  ping is dynamic 
291f0 6e 6f 74 20 73 74 61 74 69 63 2e 20 20 5e 54 79  not static.  ^Ty
29200 70 65 0a 2a 2a 20 69 73 20 61 73 73 6f 63 69 61  pe.** is associa
29210 74 65 64 20 77 69 74 68 20 69 6e 64 69 76 69 64  ted with individ
29220 75 61 6c 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20  ual values, not 
29230 77 69 74 68 20 74 68 65 20 63 6f 6e 74 61 69 6e  with the contain
29240 65 72 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68  ers.** used to h
29250 6f 6c 64 20 74 68 6f 73 65 20 76 61 6c 75 65 73  old those values
29260 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20  ..*/.const char 
29270 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
29280 64 65 63 6c 74 79 70 65 28 73 71 6c 69 74 65 33  decltype(sqlite3
29290 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e  _stmt*,int);.con
292a0 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
292b0 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65  _column_decltype
292c0 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
292d0 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ,int);../*.** CA
292e0 50 49 33 52 45 46 3a 20 45 76 61 6c 75 61 74 65  PI3REF: Evaluate
292f0 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e   An SQL Statemen
29300 74 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61 20  t.**.** After a 
29310 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
29320 65 6e 74 5d 20 68 61 73 20 62 65 65 6e 20 70 72  ent] has been pr
29330 65 70 61 72 65 64 20 75 73 69 6e 67 20 65 69 74  epared using eit
29340 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  her.** [sqlite3_
29350 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
29360 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
29370 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65  e16_v2()] or one
29380 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79 0a 2a   of the legacy.*
29390 2a 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71  * interfaces [sq
293a0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d  lite3_prepare()]
293b0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   or [sqlite3_pre
293c0 70 61 72 65 31 36 28 29 5d 2c 20 74 68 69 73 20  pare16()], this 
293d0 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74  function.** must
293e0 20 62 65 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f   be called one o
293f0 72 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f 20  r more times to 
29400 65 76 61 6c 75 61 74 65 20 74 68 65 20 73 74 61  evaluate the sta
29410 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68  tement..**.** Th
29420 65 20 64 65 74 61 69 6c 73 20 6f 66 20 74 68 65  e details of the
29430 20 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68 65   behavior of the
29440 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
29450 69 6e 74 65 72 66 61 63 65 20 64 65 70 65 6e 64  interface depend
29460 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 74  .** on whether t
29470 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73  he statement was
29480 20 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 20   prepared using 
29490 74 68 65 20 6e 65 77 65 72 20 22 76 32 22 20 69  the newer "v2" i
294a0 6e 74 65 72 66 61 63 65 0a 2a 2a 20 5b 73 71 6c  nterface.** [sql
294b0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
294c0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
294d0 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20  prepare16_v2()] 
294e0 6f 72 20 74 68 65 20 6f 6c 64 65 72 20 6c 65 67  or the older leg
294f0 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  acy.** interface
29500 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
29510 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  e()] and [sqlite
29520 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2e 20  3_prepare16()]. 
29530 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 0a   The use of the.
29540 2a 2a 20 6e 65 77 20 22 76 32 22 20 69 6e 74 65  ** new "v2" inte
29550 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65  rface is recomme
29560 6e 64 65 64 20 66 6f 72 20 6e 65 77 20 61 70 70  nded for new app
29570 6c 69 63 61 74 69 6f 6e 73 20 62 75 74 20 74 68  lications but th
29580 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65  e legacy.** inte
29590 72 66 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74 69  rface will conti
295a0 6e 75 65 20 74 6f 20 62 65 20 73 75 70 70 6f 72  nue to be suppor
295b0 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74  ted..**.** ^In t
295c0 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66  he legacy interf
295d0 61 63 65 2c 20 74 68 65 20 72 65 74 75 72 6e 20  ace, the return 
295e0 76 61 6c 75 65 20 77 69 6c 6c 20 62 65 20 65 69  value will be ei
295f0 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 42 55 53  ther [SQLITE_BUS
29600 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44  Y],.** [SQLITE_D
29610 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f  ONE], [SQLITE_RO
29620 57 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  W], [SQLITE_ERRO
29630 52 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d  R], or [SQLITE_M
29640 49 53 55 53 45 5d 2e 0a 2a 2a 20 5e 57 69 74 68  ISUSE]..** ^With
29650 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66   the "v2" interf
29660 61 63 65 2c 20 61 6e 79 20 6f 66 20 74 68 65 20  ace, any of the 
29670 6f 74 68 65 72 20 5b 72 65 73 75 6c 74 20 63 6f  other [result co
29680 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65  des] or.** [exte
29690 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
296a0 73 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74 75  s] might be retu
296b0 72 6e 65 64 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a  rned as well..**
296c0 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 42 55 53  .** ^[SQLITE_BUS
296d0 59 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  Y] means that th
296e0 65 20 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e  e database engin
296f0 65 20 77 61 73 20 75 6e 61 62 6c 65 20 74 6f 20  e was unable to 
29700 61 63 71 75 69 72 65 20 74 68 65 0a 2a 2a 20 64  acquire the.** d
29710 61 74 61 62 61 73 65 20 6c 6f 63 6b 73 20 69 74  atabase locks it
29720 20 6e 65 65 64 73 20 74 6f 20 64 6f 20 69 74 73   needs to do its
29730 20 6a 6f 62 2e 20 20 5e 49 66 20 74 68 65 20 73   job.  ^If the s
29740 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 43  tatement is a [C
29750 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63  OMMIT].** or occ
29760 75 72 73 20 6f 75 74 73 69 64 65 20 6f 66 20 61  urs outside of a
29770 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73  n explicit trans
29780 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75  action, then you
29790 20 63 61 6e 20 72 65 74 72 79 20 74 68 65 0a 2a   can retry the.*
297a0 2a 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 49 66  * statement.  If
297b0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
297c0 73 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49 54 5d  s not a [COMMIT]
297d0 20 61 6e 64 20 6f 63 63 75 72 73 20 77 69 74 68   and occurs with
297e0 69 6e 20 61 6e 0a 2a 2a 20 65 78 70 6c 69 63 69  in an.** explici
297f0 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 68  t transaction th
29800 65 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f  en you should ro
29810 6c 6c 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73  llback the trans
29820 61 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a  action before.**
29830 20 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a   continuing..**.
29840 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 44 4f 4e 45  ** ^[SQLITE_DONE
29850 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  ] means that the
29860 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73 20 66   statement has f
29870 69 6e 69 73 68 65 64 20 65 78 65 63 75 74 69 6e  inished executin
29880 67 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c  g.** successfull
29890 79 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70  y.  sqlite3_step
298a0 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65  () should not be
298b0 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e   called again on
298c0 20 74 68 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a   this virtual.**
298d0 20 6d 61 63 68 69 6e 65 20 77 69 74 68 6f 75 74   machine without
298e0 20 66 69 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b   first calling [
298f0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
29900 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 76 69   to reset the vi
29910 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65  rtual.** machine
29920 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69   back to its ini
29930 74 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a  tial state..**.*
29940 2a 20 5e 49 66 20 74 68 65 20 53 51 4c 20 73 74  * ^If the SQL st
29950 61 74 65 6d 65 6e 74 20 62 65 69 6e 67 20 65 78  atement being ex
29960 65 63 75 74 65 64 20 72 65 74 75 72 6e 73 20 61  ecuted returns a
29970 6e 79 20 64 61 74 61 2c 20 74 68 65 6e 20 5b 53  ny data, then [S
29980 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73  QLITE_ROW].** is
29990 20 72 65 74 75 72 6e 65 64 20 65 61 63 68 20 74   returned each t
299a0 69 6d 65 20 61 20 6e 65 77 20 72 6f 77 20 6f 66  ime a new row of
299b0 20 64 61 74 61 20 69 73 20 72 65 61 64 79 20 66   data is ready f
299c0 6f 72 20 70 72 6f 63 65 73 73 69 6e 67 20 62 79  or processing by
299d0 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20   the.** caller. 
299e0 54 68 65 20 76 61 6c 75 65 73 20 6d 61 79 20 62  The values may b
299f0 65 20 61 63 63 65 73 73 65 64 20 75 73 69 6e 67  e accessed using
29a00 20 74 68 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 63   the [column acc
29a10 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a  ess functions]..
29a20 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  ** sqlite3_step(
29a30 29 20 69 73 20 63 61 6c 6c 65 64 20 61 67 61 69  ) is called agai
29a40 6e 20 74 6f 20 72 65 74 72 69 65 76 65 20 74 68  n to retrieve th
29a50 65 20 6e 65 78 74 20 72 6f 77 20 6f 66 20 64 61  e next row of da
29a60 74 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49  ta..**.** ^[SQLI
29a70 54 45 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20  TE_ERROR] means 
29a80 74 68 61 74 20 61 20 72 75 6e 2d 74 69 6d 65 20  that a run-time 
29a90 65 72 72 6f 72 20 28 73 75 63 68 20 61 73 20 61  error (such as a
29aa0 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76   constraint.** v
29ab0 69 6f 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f 63  iolation) has oc
29ac0 63 75 72 72 65 64 2e 20 20 73 71 6c 69 74 65 33  curred.  sqlite3
29ad0 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e  _step() should n
29ae0 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61  ot be called aga
29af0 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e  in on.** the VM.
29b00 20 4d 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f   More informatio
29b10 6e 20 6d 61 79 20 62 65 20 66 6f 75 6e 64 20 62  n may be found b
29b20 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  y calling [sqlit
29b30 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a  e3_errmsg()]..**
29b40 20 5e 57 69 74 68 20 74 68 65 20 6c 65 67 61 63   ^With the legac
29b50 79 20 69 6e 74 65 72 66 61 63 65 2c 20 61 20 6d  y interface, a m
29b60 6f 72 65 20 73 70 65 63 69 66 69 63 20 65 72 72  ore specific err
29b70 6f 72 20 63 6f 64 65 20 28 66 6f 72 20 65 78 61  or code (for exa
29b80 6d 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  mple,.** [SQLITE
29b90 5f 49 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53 51  _INTERRUPT], [SQ
29ba0 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53  LITE_SCHEMA], [S
29bb0 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20  QLITE_CORRUPT], 
29bc0 61 6e 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a  and so forth).**
29bd0 20 63 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 64   can be obtained
29be0 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c   by calling [sql
29bf0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e  ite3_reset()] on
29c00 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
29c10 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 5e  d statement].  ^
29c20 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74 65  In the "v2" inte
29c30 72 66 61 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f  rface,.** the mo
29c40 72 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f  re specific erro
29c50 72 20 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e  r code is return
29c60 65 64 20 64 69 72 65 63 74 6c 79 20 62 79 20 73  ed directly by s
29c70 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a  qlite3_step()..*
29c80 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53  *.** [SQLITE_MIS
29c90 55 53 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20  USE] means that 
29ca0 74 68 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65  the this routine
29cb0 20 77 61 73 20 63 61 6c 6c 65 64 20 69 6e 61 70   was called inap
29cc0 70 72 6f 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20  propriately..** 
29cd0 50 65 72 68 61 70 73 20 69 74 20 77 61 73 20 63  Perhaps it was c
29ce0 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 70 72 65 70  alled on a [prep
29cf0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
29d00 74 68 61 74 20 68 61 73 0a 2a 2a 20 61 6c 72 65  that has.** alre
29d10 61 64 79 20 62 65 65 6e 20 5b 73 71 6c 69 74 65  ady been [sqlite
29d20 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e  3_finalize | fin
29d30 61 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e  alized] or on on
29d40 65 20 74 68 61 74 20 68 61 64 0a 2a 2a 20 70 72  e that had.** pr
29d50 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65  eviously returne
29d60 64 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  d [SQLITE_ERROR]
29d70 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45   or [SQLITE_DONE
29d80 5d 2e 20 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a  ].  Or it could.
29d90 2a 2a 20 62 65 20 74 68 65 20 63 61 73 65 20 74  ** be the case t
29da0 68 61 74 20 74 68 65 20 73 61 6d 65 20 64 61 74  hat the same dat
29db0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
29dc0 20 69 73 20 62 65 69 6e 67 20 75 73 65 64 20 62   is being used b
29dd0 79 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65  y two or.** more
29de0 20 74 68 72 65 61 64 73 20 61 74 20 74 68 65 20   threads at the 
29df0 73 61 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74  same moment in t
29e00 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 61  ime..**.** For a
29e10 6c 6c 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  ll versions of S
29e20 51 4c 69 74 65 20 75 70 20 74 6f 20 61 6e 64 20  QLite up to and 
29e30 69 6e 63 6c 75 64 69 6e 67 20 33 2e 36 2e 32 33  including 3.6.23
29e40 2e 31 2c 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a  .1, a call to.**
29e50 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
29e60 29 5d 20 77 61 73 20 72 65 71 75 69 72 65 64 20  )] was required 
29e70 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 73 74  after sqlite3_st
29e80 65 70 28 29 20 72 65 74 75 72 6e 65 64 20 61 6e  ep() returned an
29e90 79 74 68 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20  ything.** other 
29ea0 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57  than [SQLITE_ROW
29eb0 5d 20 62 65 66 6f 72 65 20 61 6e 79 20 73 75 62  ] before any sub
29ec0 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69  sequent invocati
29ed0 6f 6e 20 6f 66 0a 2a 2a 20 73 71 6c 69 74 65 33  on of.** sqlite3
29ee0 5f 73 74 65 70 28 29 2e 20 20 46 61 69 6c 75 72  _step().  Failur
29ef0 65 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 70  e to reset the p
29f00 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
29f10 74 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c  t using .** [sql
29f20 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 77 6f  ite3_reset()] wo
29f30 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61 6e  uld result in an
29f40 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
29f50 20 72 65 74 75 72 6e 20 66 72 6f 6d 0a 2a 2a 20   return from.** 
29f60 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20  sqlite3_step(). 
29f70 20 42 75 74 20 61 66 74 65 72 20 76 65 72 73 69   But after versi
29f80 6f 6e 20 33 2e 36 2e 32 33 2e 31 2c 20 73 71 6c  on 3.6.23.1, sql
29f90 69 74 65 33 5f 73 74 65 70 28 29 20 62 65 67 61  ite3_step() bega
29fa0 6e 0a 2a 2a 20 63 61 6c 6c 69 6e 67 20 5b 73 71  n.** calling [sq
29fb0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 61  lite3_reset()] a
29fc0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e 20  utomatically in 
29fd0 74 68 69 73 20 63 69 72 63 75 6d 73 74 61 6e 63  this circumstanc
29fe0 65 20 72 61 74 68 65 72 0a 2a 2a 20 74 68 61 6e  e rather.** than
29ff0 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49   returning [SQLI
2a000 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 54 68 69  TE_MISUSE].  Thi
2a010 73 20 69 73 20 6e 6f 74 20 63 6f 6e 73 69 64 65  s is not conside
2a020 72 65 64 20 61 20 63 6f 6d 70 61 74 69 62 69 6c  red a compatibil
2a030 69 74 79 0a 2a 2a 20 62 72 65 61 6b 20 62 65 63  ity.** break bec
2a040 61 75 73 65 20 61 6e 79 20 61 70 70 6c 69 63 61  ause any applica
2a050 74 69 6f 6e 20 74 68 61 74 20 65 76 65 72 20 72  tion that ever r
2a060 65 63 65 69 76 65 73 20 61 6e 20 53 51 4c 49 54  eceives an SQLIT
2a070 45 5f 4d 49 53 55 53 45 20 65 72 72 6f 72 0a 2a  E_MISUSE error.*
2a080 2a 20 69 73 20 62 72 6f 6b 65 6e 20 62 79 20 64  * is broken by d
2a090 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 65 20  efinition.  The 
2a0a0 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54  [SQLITE_OMIT_AUT
2a0b0 4f 52 45 53 45 54 5d 20 63 6f 6d 70 69 6c 65 2d  ORESET] compile-
2a0c0 74 69 6d 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 63  time option.** c
2a0d0 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72 65  an be used to re
2a0e0 73 74 6f 72 65 20 74 68 65 20 6c 65 67 61 63 79  store the legacy
2a0f0 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a   behavior..**.**
2a100 20 3c 62 3e 47 6f 6f 66 79 20 49 6e 74 65 72 66   <b>Goofy Interf
2a110 61 63 65 20 41 6c 65 72 74 3a 3c 2f 62 3e 20 49  ace Alert:</b> I
2a120 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74  n the legacy int
2a130 65 72 66 61 63 65 2c 20 74 68 65 20 73 71 6c 69  erface, the sqli
2a140 74 65 33 5f 73 74 65 70 28 29 0a 2a 2a 20 41 50  te3_step().** AP
2a150 49 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73  I always returns
2a160 20 61 20 67 65 6e 65 72 69 63 20 65 72 72 6f 72   a generic error
2a170 20 63 6f 64 65 2c 20 5b 53 51 4c 49 54 45 5f 45   code, [SQLITE_E
2a180 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67  RROR], following
2a190 20 61 6e 79 0a 2a 2a 20 65 72 72 6f 72 20 6f 74   any.** error ot
2a1a0 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
2a1b0 5f 42 55 53 59 5d 20 61 6e 64 20 5b 53 51 4c 49  _BUSY] and [SQLI
2a1c0 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 59 6f 75  TE_MISUSE].  You
2a1d0 20 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73   must call.** [s
2a1e0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
2a1f0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  or [sqlite3_fina
2a200 6c 69 7a 65 28 29 5d 20 69 6e 20 6f 72 64 65 72  lize()] in order
2a210 20 74 6f 20 66 69 6e 64 20 6f 6e 65 20 6f 66 20   to find one of 
2a220 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20  the.** specific 
2a230 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 74 68  [error codes] th
2a240 61 74 20 62 65 74 74 65 72 20 64 65 73 63 72 69  at better descri
2a250 62 65 73 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a  bes the error..*
2a260 2a 20 57 65 20 61 64 6d 69 74 20 74 68 61 74 20  * We admit that 
2a270 74 68 69 73 20 69 73 20 61 20 67 6f 6f 66 79 20  this is a goofy 
2a280 64 65 73 69 67 6e 2e 20 20 54 68 65 20 70 72 6f  design.  The pro
2a290 62 6c 65 6d 20 68 61 73 20 62 65 65 6e 20 66 69  blem has been fi
2a2a0 78 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  xed.** with the 
2a2b0 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2e 20  "v2" interface. 
2a2c0 20 49 66 20 79 6f 75 20 70 72 65 70 61 72 65 20   If you prepare 
2a2d0 61 6c 6c 20 6f 66 20 79 6f 75 72 20 53 51 4c 20  all of your SQL 
2a2e0 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 73  statements.** us
2a2f0 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69  ing either [sqli
2a300 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
2a310 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ] or [sqlite3_pr
2a320 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 69 6e  epare16_v2()] in
2a330 73 74 65 61 64 0a 2a 2a 20 6f 66 20 74 68 65 20  stead.** of the 
2a340 6c 65 67 61 63 79 20 5b 73 71 6c 69 74 65 33 5f  legacy [sqlite3_
2a350 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b  prepare()] and [
2a360 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
2a370 36 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 2c  6()] interfaces,
2a380 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6d 6f 72  .** then the mor
2a390 65 20 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f  e specific [erro
2a3a0 72 20 63 6f 64 65 73 5d 20 61 72 65 20 72 65 74  r codes] are ret
2a3b0 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79 0a 2a  urned directly.*
2a3c0 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65  * by sqlite3_ste
2a3d0 70 28 29 2e 20 20 54 68 65 20 75 73 65 20 6f 66  p().  The use of
2a3e0 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66   the "v2" interf
2a3f0 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64  ace is recommend
2a400 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ed..*/.int sqlit
2a410 65 33 5f 73 74 65 70 28 73 71 6c 69 74 65 33 5f  e3_step(sqlite3_
2a420 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  stmt*);../*.** C
2a430 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20  API3REF: Number 
2a440 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20  of columns in a 
2a450 72 65 73 75 6c 74 20 73 65 74 0a 2a 2a 0a 2a 2a  result set.**.**
2a460 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61   ^The sqlite3_da
2a470 74 61 5f 63 6f 75 6e 74 28 50 29 20 69 6e 74 65  ta_count(P) inte
2a480 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68  rface returns th
2a490 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  e number of colu
2a4a0 6d 6e 73 20 69 6e 20 74 68 65 0a 2a 2a 20 63 75  mns in the.** cu
2a4b0 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65  rrent row of the
2a4c0 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 5b   result set of [
2a4d0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2a4e0 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 49 66 20 70 72  nt] P..** ^If pr
2a4f0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2a500 20 50 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65   P does not have
2a510 20 72 65 73 75 6c 74 73 20 72 65 61 64 79 20 74   results ready t
2a520 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 28 76 69 61  o return.** (via
2a530 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 5b 73   calls to the [s
2a540 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e  qlite3_column_in
2a550 74 20 7c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  t | sqlite3_colu
2a560 6d 6e 5f 2a 28 29 5d 20 6f 66 0a 2a 2a 20 69 6e  mn_*()] of.** in
2a570 74 65 72 66 61 63 65 73 29 20 74 68 65 6e 20 73  terfaces) then s
2a580 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e  qlite3_data_coun
2a590 74 28 50 29 20 72 65 74 75 72 6e 73 20 30 2e 0a  t(P) returns 0..
2a5a0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2a5b0 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f  data_count(P) ro
2a5c0 75 74 69 6e 65 20 61 6c 73 6f 20 72 65 74 75 72  utine also retur
2a5d0 6e 73 20 30 20 69 66 20 50 20 69 73 20 61 20 4e  ns 0 if P is a N
2a5e0 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20  ULL pointer..** 
2a5f0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74  ^The sqlite3_dat
2a600 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75 74 69  a_count(P) routi
2a610 6e 65 20 72 65 74 75 72 6e 73 20 30 20 69 66 20  ne returns 0 if 
2a620 74 68 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c  the previous cal
2a630 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  l to.** [sqlite3
2a640 5f 73 74 65 70 5d 28 50 29 20 72 65 74 75 72 6e  _step](P) return
2a650 65 64 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d  ed [SQLITE_DONE]
2a660 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
2a670 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 0a 2a 2a  data_count(P).**
2a680 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6e 6f 6e   will return non
2a690 2d 7a 65 72 6f 20 69 66 20 70 72 65 76 69 6f 75  -zero if previou
2a6a0 73 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  s call to [sqlit
2a6b0 65 33 5f 73 74 65 70 5d 28 50 29 20 72 65 74 75  e3_step](P) retu
2a6c0 72 6e 65 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  rned.** [SQLITE_
2a6d0 52 4f 57 5d 2c 20 65 78 63 65 70 74 20 69 6e 20  ROW], except in 
2a6e0 74 68 65 20 63 61 73 65 20 6f 66 20 74 68 65 20  the case of the 
2a6f0 5b 50 52 41 47 4d 41 20 69 6e 63 72 65 6d 65 6e  [PRAGMA incremen
2a700 74 61 6c 5f 76 61 63 75 75 6d 5d 0a 2a 2a 20 77  tal_vacuum].** w
2a710 68 65 72 65 20 69 74 20 61 6c 77 61 79 73 20 72  here it always r
2a720 65 74 75 72 6e 73 20 7a 65 72 6f 20 73 69 6e 63  eturns zero sinc
2a730 65 20 65 61 63 68 20 73 74 65 70 20 6f 66 20 74  e each step of t
2a740 68 61 74 20 6d 75 6c 74 69 2d 73 74 65 70 0a 2a  hat multi-step.*
2a750 2a 20 70 72 61 67 6d 61 20 72 65 74 75 72 6e 73  * pragma returns
2a760 20 30 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 64 61   0 columns of da
2a770 74 61 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  ta..**.** See al
2a780 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  so: [sqlite3_col
2a790 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a  umn_count()].*/.
2a7a0 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 61 74 61  int sqlite3_data
2a7b0 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73  _count(sqlite3_s
2a7c0 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
2a7d0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75  .** CAPI3REF: Fu
2a7e0 6e 64 61 6d 65 6e 74 61 6c 20 44 61 74 61 74 79  ndamental Dataty
2a7f0 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  pes.** KEYWORDS:
2a800 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 2a 2a 0a   SQLITE_TEXT.**.
2a810 2a 2a 20 5e 28 45 76 65 72 79 20 76 61 6c 75 65  ** ^(Every value
2a820 20 69 6e 20 53 51 4c 69 74 65 20 68 61 73 20 6f   in SQLite has o
2a830 6e 65 20 6f 66 20 66 69 76 65 20 66 75 6e 64 61  ne of five funda
2a840 6d 65 6e 74 61 6c 20 64 61 74 61 74 79 70 65 73  mental datatypes
2a850 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
2a860 3c 6c 69 3e 20 36 34 2d 62 69 74 20 73 69 67 6e  <li> 64-bit sign
2a870 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c  ed integer.** <l
2a880 69 3e 20 36 34 2d 62 69 74 20 49 45 45 45 20 66  i> 64-bit IEEE f
2a890 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75  loating point nu
2a8a0 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72  mber.** <li> str
2a8b0 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42  ing.** <li> BLOB
2a8c0 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a  .** <li> NULL.**
2a8d0 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54   </ul>)^.**.** T
2a8e0 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61  hese constants a
2a8f0 72 65 20 63 6f 64 65 73 20 66 6f 72 20 65 61 63  re codes for eac
2a900 68 20 6f 66 20 74 68 6f 73 65 20 74 79 70 65 73  h of those types
2a910 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ..**.** Note tha
2a920 74 20 74 68 65 20 53 51 4c 49 54 45 5f 54 45 58  t the SQLITE_TEX
2a930 54 20 63 6f 6e 73 74 61 6e 74 20 77 61 73 20 61  T constant was a
2a940 6c 73 6f 20 75 73 65 64 20 69 6e 20 53 51 4c 69  lso used in SQLi
2a950 74 65 20 76 65 72 73 69 6f 6e 20 32 0a 2a 2a 20  te version 2.** 
2a960 66 6f 72 20 61 20 63 6f 6d 70 6c 65 74 65 6c 79  for a completely
2a970 20 64 69 66 66 65 72 65 6e 74 20 6d 65 61 6e 69   different meani
2a980 6e 67 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68  ng.  Software th
2a990 61 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74  at links against
2a9a0 20 62 6f 74 68 0a 2a 2a 20 53 51 4c 69 74 65 20   both.** SQLite 
2a9b0 76 65 72 73 69 6f 6e 20 32 20 61 6e 64 20 53 51  version 2 and SQ
2a9c0 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 20 73  Lite version 3 s
2a9d0 68 6f 75 6c 64 20 75 73 65 20 53 51 4c 49 54 45  hould use SQLITE
2a9e0 33 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53  3_TEXT, not.** S
2a9f0 51 4c 49 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23  QLITE_TEXT..*/.#
2aa00 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
2aa10 54 45 47 45 52 20 20 31 0a 23 64 65 66 69 6e 65  TEGER  1.#define
2aa20 20 53 51 4c 49 54 45 5f 46 4c 4f 41 54 20 20 20   SQLITE_FLOAT   
2aa30 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   2.#define SQLIT
2aa40 45 5f 42 4c 4f 42 20 20 20 20 20 34 0a 23 64 65  E_BLOB     4.#de
2aa50 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 55 4c 4c  fine SQLITE_NULL
2aa60 20 20 20 20 20 35 0a 23 69 66 64 65 66 20 53 51       5.#ifdef SQ
2aa70 4c 49 54 45 5f 54 45 58 54 0a 23 20 75 6e 64 65  LITE_TEXT.# unde
2aa80 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 65  f SQLITE_TEXT.#e
2aa90 6c 73 65 0a 23 20 64 65 66 69 6e 65 20 53 51 4c  lse.# define SQL
2aaa0 49 54 45 5f 54 45 58 54 20 20 20 20 20 33 0a 23  ITE_TEXT     3.#
2aab0 65 6e 64 69 66 0a 23 64 65 66 69 6e 65 20 53 51  endif.#define SQ
2aac0 4c 49 54 45 33 5f 54 45 58 54 20 20 20 20 20 33  LITE3_TEXT     3
2aad0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2aae0 3a 20 52 65 73 75 6c 74 20 56 61 6c 75 65 73 20  : Result Values 
2aaf0 46 72 6f 6d 20 41 20 51 75 65 72 79 0a 2a 2a 20  From A Query.** 
2ab00 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d  KEYWORDS: {colum
2ab10 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f  n access functio
2ab20 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ns}.**.** These 
2ab30 72 6f 75 74 69 6e 65 73 20 66 6f 72 6d 20 74 68  routines form th
2ab40 65 20 22 72 65 73 75 6c 74 20 73 65 74 22 20 69  e "result set" i
2ab50 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
2ab60 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
2ab70 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69  return informati
2ab80 6f 6e 20 61 62 6f 75 74 20 61 20 73 69 6e 67 6c  on about a singl
2ab90 65 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20  e column of the 
2aba0 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65 73 75 6c  current.** resul
2abb0 74 20 72 6f 77 20 6f 66 20 61 20 71 75 65 72 79  t row of a query
2abc0 2e 20 20 5e 49 6e 20 65 76 65 72 79 20 63 61 73  .  ^In every cas
2abd0 65 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  e the first argu
2abe0 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65  ment is a pointe
2abf0 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 70 72 65  r.** to the [pre
2ac00 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2ac10 20 74 68 61 74 20 69 73 20 62 65 69 6e 67 20 65   that is being e
2ac20 76 61 6c 75 61 74 65 64 20 28 74 68 65 20 5b 73  valuated (the [s
2ac30 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a 2a  qlite3_stmt*].**
2ac40 20 74 68 61 74 20 77 61 73 20 72 65 74 75 72 6e   that was return
2ac50 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
2ac60 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
2ac70 72 20 6f 6e 65 20 6f 66 20 69 74 73 20 76 61 72  r one of its var
2ac80 69 61 6e 74 73 29 0a 2a 2a 20 61 6e 64 20 74 68  iants).** and th
2ac90 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
2aca0 74 20 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f  t is the index o
2acb0 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 66 6f 72  f the column for
2acc0 20 77 68 69 63 68 20 69 6e 66 6f 72 6d 61 74 69   which informati
2acd0 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20  on.** should be 
2ace0 72 65 74 75 72 6e 65 64 2e 20 5e 54 68 65 20 6c  returned. ^The l
2acf0 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f  eftmost column o
2ad00 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
2ad10 20 68 61 73 20 74 68 65 20 69 6e 64 65 78 20 30   has the index 0
2ad20 2e 0a 2a 2a 20 5e 54 68 65 20 6e 75 6d 62 65 72  ..** ^The number
2ad30 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74   of columns in t
2ad40 68 65 20 72 65 73 75 6c 74 20 63 61 6e 20 62 65  he result can be
2ad50 20 64 65 74 65 72 6d 69 6e 65 64 20 75 73 69 6e   determined usin
2ad60 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  g.** [sqlite3_co
2ad70 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 2e 0a 2a  lumn_count()]..*
2ad80 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53 51 4c 20  *.** If the SQL 
2ad90 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e  statement does n
2ada0 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 70 6f 69  ot currently poi
2adb0 6e 74 20 74 6f 20 61 20 76 61 6c 69 64 20 72 6f  nt to a valid ro
2adc0 77 2c 20 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20  w, or if the.** 
2add0 63 6f 6c 75 6d 6e 20 69 6e 64 65 78 20 69 73 20  column index is 
2ade0 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c 20 74 68  out of range, th
2adf0 65 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65  e result is unde
2ae00 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 73 65 20  fined..** These 
2ae10 72 6f 75 74 69 6e 65 73 20 6d 61 79 20 6f 6e 6c  routines may onl
2ae20 79 20 62 65 20 63 61 6c 6c 65 64 20 77 68 65 6e  y be called when
2ae30 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
2ae40 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c   call to.** [sql
2ae50 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73  ite3_step()] has
2ae60 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54   returned [SQLIT
2ae70 45 5f 52 4f 57 5d 20 61 6e 64 20 6e 65 69 74 68  E_ROW] and neith
2ae80 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72  er.** [sqlite3_r
2ae90 65 73 65 74 28 29 5d 20 6e 6f 72 20 5b 73 71 6c  eset()] nor [sql
2aea0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
2aeb0 20 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c 65   have been calle
2aec0 64 20 73 75 62 73 65 71 75 65 6e 74 6c 79 2e 0a  d subsequently..
2aed0 2a 2a 20 49 66 20 61 6e 79 20 6f 66 20 74 68 65  ** If any of the
2aee0 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
2aef0 63 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71  called after [sq
2af00 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
2af10 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  r.** [sqlite3_fi
2af20 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74  nalize()] or aft
2af30 65 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  er [sqlite3_step
2af40 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64  ()] has returned
2af50 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74  .** something ot
2af60 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
2af70 5f 52 4f 57 5d 2c 20 74 68 65 20 72 65 73 75 6c  _ROW], the resul
2af80 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64  ts are undefined
2af90 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c 69 74 65 33  ..** If [sqlite3
2afa0 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c  _step()] or [sql
2afb0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72  ite3_reset()] or
2afc0 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
2afd0 7a 65 28 29 5d 0a 2a 2a 20 61 72 65 20 63 61 6c  ze()].** are cal
2afe0 6c 65 64 20 66 72 6f 6d 20 61 20 64 69 66 66 65  led from a diffe
2aff0 72 65 6e 74 20 74 68 72 65 61 64 20 77 68 69 6c  rent thread whil
2b000 65 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72  e any of these r
2b010 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20 70  outines.** are p
2b020 65 6e 64 69 6e 67 2c 20 74 68 65 6e 20 74 68 65  ending, then the
2b030 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64   results are und
2b040 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  efined..**.** ^T
2b050 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  he sqlite3_colum
2b060 6e 5f 74 79 70 65 28 29 20 72 6f 75 74 69 6e 65  n_type() routine
2b070 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20   returns the.** 
2b080 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20  [SQLITE_INTEGER 
2b090 7c 20 64 61 74 61 74 79 70 65 20 63 6f 64 65 5d  | datatype code]
2b0a0 20 66 6f 72 20 74 68 65 20 69 6e 69 74 69 61 6c   for the initial
2b0b0 20 64 61 74 61 20 74 79 70 65 0a 2a 2a 20 6f 66   data type.** of
2b0c0 20 74 68 65 20 72 65 73 75 6c 74 20 63 6f 6c 75   the result colu
2b0d0 6d 6e 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e  mn.  ^The return
2b0e0 65 64 20 76 61 6c 75 65 20 69 73 20 6f 6e 65 20  ed value is one 
2b0f0 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47  of [SQLITE_INTEG
2b100 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ER],.** [SQLITE_
2b110 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f  FLOAT], [SQLITE_
2b120 54 45 58 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 42  TEXT], [SQLITE_B
2b130 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  LOB], or [SQLITE
2b140 5f 4e 55 4c 4c 5d 2e 20 20 54 68 65 20 76 61 6c  _NULL].  The val
2b150 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62  ue.** returned b
2b160 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
2b170 5f 74 79 70 65 28 29 20 69 73 20 6f 6e 6c 79 20  _type() is only 
2b180 6d 65 61 6e 69 6e 67 66 75 6c 20 69 66 20 6e 6f  meaningful if no
2b190 20 74 79 70 65 0a 2a 2a 20 63 6f 6e 76 65 72 73   type.** convers
2b1a0 69 6f 6e 73 20 68 61 76 65 20 6f 63 63 75 72 72  ions have occurr
2b1b0 65 64 20 61 73 20 64 65 73 63 72 69 62 65 64 20  ed as described 
2b1c0 62 65 6c 6f 77 2e 20 20 41 66 74 65 72 20 61 20  below.  After a 
2b1d0 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2c  type conversion,
2b1e0 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 72 65  .** the value re
2b1f0 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
2b200 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20  3_column_type() 
2b210 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 46  is undefined.  F
2b220 75 74 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e  uture.** version
2b230 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20  s of SQLite may 
2b240 63 68 61 6e 67 65 20 74 68 65 20 62 65 68 61 76  change the behav
2b250 69 6f 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 63  ior of sqlite3_c
2b260 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20  olumn_type().** 
2b270 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 74 79 70 65  following a type
2b280 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a   conversion..**.
2b290 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
2b2a0 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55  t is a BLOB or U
2b2b0 54 46 2d 38 20 73 74 72 69 6e 67 20 74 68 65 6e  TF-8 string then
2b2c0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c   the sqlite3_col
2b2d0 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20 72  umn_bytes().** r
2b2e0 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
2b2f0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
2b300 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20  es in that BLOB 
2b310 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49  or string..** ^I
2b320 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
2b330 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2c  a UTF-16 string,
2b340 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f   then sqlite3_co
2b350 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 63 6f 6e  lumn_bytes() con
2b360 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72  verts.** the str
2b370 69 6e 67 20 74 6f 20 55 54 46 2d 38 20 61 6e 64  ing to UTF-8 and
2b380 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68   then returns th
2b390 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
2b3a0 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  s..** ^If the re
2b3b0 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69  sult is a numeri
2b3c0 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c  c value then sql
2b3d0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2b3e0 73 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c  s() uses.** [sql
2b3f0 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d  ite3_snprintf()]
2b400 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74   to convert that
2b410 20 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d   value to a UTF-
2b420 38 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74  8 string and ret
2b430 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62  urns.** the numb
2b440 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
2b450 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e  hat string..** ^
2b460 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
2b470 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69   NULL, then sqli
2b480 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2b490 28 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e  () returns zero.
2b4a0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72  .**.** ^If the r
2b4b0 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20  esult is a BLOB 
2b4c0 6f 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67  or UTF-16 string
2b4d0 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65   then the sqlite
2b4e0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
2b4f0 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65  ().** routine re
2b500 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
2b510 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61   of bytes in tha
2b520 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67  t BLOB or string
2b530 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73  ..** ^If the res
2b540 75 6c 74 20 69 73 20 61 20 55 54 46 2d 38 20 73  ult is a UTF-8 s
2b550 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69  tring, then sqli
2b560 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2b570 31 36 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a  16() converts.**
2b580 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55   the string to U
2b590 54 46 2d 31 36 20 61 6e 64 20 74 68 65 6e 20 72  TF-16 and then r
2b5a0 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
2b5b0 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e  r of bytes..** ^
2b5c0 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
2b5d0 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65   a numeric value
2b5e0 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f   then sqlite3_co
2b5f0 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 75  lumn_bytes16() u
2b600 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ses.** [sqlite3_
2b610 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63  snprintf()] to c
2b620 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c 75  onvert that valu
2b630 65 20 74 6f 20 61 20 55 54 46 2d 31 36 20 73 74  e to a UTF-16 st
2b640 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73  ring and returns
2b650 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  .** the number o
2b660 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20  f bytes in that 
2b670 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74  string..** ^If t
2b680 68 65 20 72 65 73 75 6c 74 20 69 73 20 4e 55 4c  he result is NUL
2b690 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  L, then sqlite3_
2b6a0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
2b6b0 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a   returns zero..*
2b6c0 2a 0a 2a 2a 20 5e 54 68 65 20 76 61 6c 75 65 73  *.** ^The values
2b6d0 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71   returned by [sq
2b6e0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2b6f0 65 73 28 29 5d 20 61 6e 64 20 0a 2a 2a 20 5b 73  es()] and .** [s
2b700 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2b710 74 65 73 31 36 28 29 5d 20 64 6f 20 6e 6f 74 20  tes16()] do not 
2b720 69 6e 63 6c 75 64 65 20 74 68 65 20 7a 65 72 6f  include the zero
2b730 20 74 65 72 6d 69 6e 61 74 6f 72 73 20 61 74 20   terminators at 
2b740 74 68 65 20 65 6e 64 0a 2a 2a 20 6f 66 20 74 68  the end.** of th
2b750 65 20 73 74 72 69 6e 67 2e 20 20 5e 46 6f 72 20  e string.  ^For 
2b760 63 6c 61 72 69 74 79 3a 20 74 68 65 20 76 61 6c  clarity: the val
2b770 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 0a  ues returned by.
2b780 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
2b790 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e 64 20  mn_bytes()] and 
2b7a0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
2b7b0 62 79 74 65 73 31 36 28 29 5d 20 61 72 65 20 74  bytes16()] are t
2b7c0 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20  he number of.** 
2b7d0 62 79 74 65 73 20 69 6e 20 74 68 65 20 73 74 72  bytes in the str
2b7e0 69 6e 67 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d  ing, not the num
2b7f0 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72  ber of character
2b800 73 2e 0a 2a 2a 0a 2a 2a 20 5e 53 74 72 69 6e 67  s..**.** ^String
2b810 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  s returned by sq
2b820 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
2b830 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  t() and sqlite3_
2b840 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 2c  column_text16(),
2b850 0a 2a 2a 20 65 76 65 6e 20 65 6d 70 74 79 20 73  .** even empty s
2b860 74 72 69 6e 67 73 2c 20 61 72 65 20 61 6c 77 61  trings, are alwa
2b870 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  ys zero-terminat
2b880 65 64 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e  ed.  ^The return
2b890 0a 2a 2a 20 76 61 6c 75 65 20 66 72 6f 6d 20 73  .** value from s
2b8a0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
2b8b0 6f 62 28 29 20 66 6f 72 20 61 20 7a 65 72 6f 2d  ob() for a zero-
2b8c0 6c 65 6e 67 74 68 20 42 4c 4f 42 20 69 73 20 61  length BLOB is a
2b8d0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
2b8e0 2a 0a 2a 2a 20 5e 54 68 65 20 6f 62 6a 65 63 74  *.** ^The object
2b8f0 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71   returned by [sq
2b900 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c  lite3_column_val
2b910 75 65 28 29 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b  ue()] is an.** [
2b920 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
2b930 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
2b940 74 2e 20 20 41 6e 20 75 6e 70 72 6f 74 65 63 74  t.  An unprotect
2b950 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
2b960 20 6f 62 6a 65 63 74 0a 2a 2a 20 6d 61 79 20 6f   object.** may o
2b970 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69 74 68  nly be used with
2b980 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76   [sqlite3_bind_v
2b990 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  alue()] and [sql
2b9a0 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75  ite3_result_valu
2b9b0 65 28 29 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20  e()]..** If the 
2b9c0 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c  [unprotected sql
2b9d0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
2b9e0 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a  ct returned by.*
2b9f0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
2ba00 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 73  n_value()] is us
2ba10 65 64 20 69 6e 20 61 6e 79 20 6f 74 68 65 72 20  ed in any other 
2ba20 77 61 79 2c 20 69 6e 63 6c 75 64 69 6e 67 20 63  way, including c
2ba30 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75 74 69  alls.** to routi
2ba40 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65  nes like [sqlite
2ba50 33 5f 76 61 6c 75 65 5f 69 6e 74 28 29 5d 2c 20  3_value_int()], 
2ba60 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
2ba70 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73  ext()],.** or [s
2ba80 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74  qlite3_value_byt
2ba90 65 73 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20  es()], then the 
2baa0 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65  behavior is unde
2bab0 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  fined..**.** The
2bac0 73 65 20 72 6f 75 74 69 6e 65 73 20 61 74 74 65  se routines atte
2bad0 6d 70 74 20 74 6f 20 63 6f 6e 76 65 72 74 20 74  mpt to convert t
2bae0 68 65 20 76 61 6c 75 65 20 77 68 65 72 65 20 61  he value where a
2baf0 70 70 72 6f 70 72 69 61 74 65 2e 20 20 5e 46 6f  ppropriate.  ^Fo
2bb00 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 69 66  r.** example, if
2bb10 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65   the internal re
2bb20 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 69 73 20  presentation is 
2bb30 46 4c 4f 41 54 20 61 6e 64 20 61 20 74 65 78 74  FLOAT and a text
2bb40 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 72 65   result.** is re
2bb50 71 75 65 73 74 65 64 2c 20 5b 73 71 6c 69 74 65  quested, [sqlite
2bb60 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 69 73  3_snprintf()] is
2bb70 20 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79   used internally
2bb80 20 74 6f 20 70 65 72 66 6f 72 6d 20 74 68 65 0a   to perform the.
2bb90 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 75  ** conversion au
2bba0 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 5e 28  tomatically.  ^(
2bbb0 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 61  The following ta
2bbc0 62 6c 65 20 64 65 74 61 69 6c 73 20 74 68 65 20  ble details the 
2bbd0 63 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a 2a 20 74  conversions.** t
2bbe0 68 61 74 20 61 72 65 20 61 70 70 6c 69 65 64 3a  hat are applied:
2bbf0 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
2bc00 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f  te>.** <table bo
2bc10 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72  rder="1">.** <tr
2bc20 3e 3c 74 68 3e 20 49 6e 74 65 72 6e 61 6c 3c 62  ><th> Internal<b
2bc30 72 3e 54 79 70 65 20 3c 74 68 3e 20 52 65 71 75  r>Type <th> Requ
2bc40 65 73 74 65 64 3c 62 72 3e 54 79 70 65 20 3c 74  ested<br>Type <t
2bc50 68 3e 20 20 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a  h>  Conversion.*
2bc60 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e  *.** <tr><td>  N
2bc70 55 4c 4c 20 20 20 20 3c 74 64 3e 20 49 4e 54 45  ULL    <td> INTE
2bc80 47 45 52 20 20 20 3c 74 64 3e 20 52 65 73 75 6c  GER   <td> Resul
2bc90 74 20 69 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74  t is 0.** <tr><t
2bca0 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e  d>  NULL    <td>
2bcb0 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20    FLOAT    <td> 
2bcc0 52 65 73 75 6c 74 20 69 73 20 30 2e 30 0a 2a 2a  Result is 0.0.**
2bcd0 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20   <tr><td>  NULL 
2bce0 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20     <td>   TEXT  
2bcf0 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73    <td> Result is
2bd00 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a   NULL pointer.**
2bd10 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20   <tr><td>  NULL 
2bd20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20     <td>   BLOB  
2bd30 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73    <td> Result is
2bd40 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a   NULL pointer.**
2bd50 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45   <tr><td> INTEGE
2bd60 52 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20  R  <td>  FLOAT  
2bd70 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66    <td> Convert f
2bd80 72 6f 6d 20 69 6e 74 65 67 65 72 20 74 6f 20 66  rom integer to f
2bd90 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  loat.** <tr><td>
2bda0 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20   INTEGER  <td>  
2bdb0 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53   TEXT    <td> AS
2bdc0 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66  CII rendering of
2bdd0 20 74 68 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20   the integer.** 
2bde0 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52  <tr><td> INTEGER
2bdf0 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20    <td>   BLOB   
2be00 20 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 49 4e   <td> Same as IN
2be10 54 45 47 45 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c  TEGER->TEXT.** <
2be20 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20  tr><td>  FLOAT  
2be30 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20   <td> INTEGER   
2be40 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f  <td> Convert fro
2be50 6d 20 66 6c 6f 61 74 20 74 6f 20 69 6e 74 65 67  m float to integ
2be60 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  er.** <tr><td>  
2be70 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 54  FLOAT   <td>   T
2be80 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49  EXT    <td> ASCI
2be90 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74  I rendering of t
2bea0 68 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e  he float.** <tr>
2beb0 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74  <td>  FLOAT   <t
2bec0 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  d>   BLOB    <td
2bed0 3e 20 53 61 6d 65 20 61 73 20 46 4c 4f 41 54 2d  > Same as FLOAT-
2bee0 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64  >TEXT.** <tr><td
2bef0 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20  >  TEXT    <td> 
2bf00 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 55  INTEGER   <td> U
2bf10 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72  se atoi().** <tr
2bf20 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c  ><td>  TEXT    <
2bf30 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74  td>  FLOAT    <t
2bf40 64 3e 20 55 73 65 20 61 74 6f 66 28 29 0a 2a 2a  d> Use atof().**
2bf50 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20   <tr><td>  TEXT 
2bf60 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20     <td>   BLOB  
2bf70 20 20 3c 74 64 3e 20 4e 6f 20 63 68 61 6e 67 65    <td> No change
2bf80 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c  .** <tr><td>  BL
2bf90 4f 42 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47  OB    <td> INTEG
2bfa0 45 52 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72  ER   <td> Conver
2bfb0 74 20 74 6f 20 54 45 58 54 20 74 68 65 6e 20 75  t to TEXT then u
2bfc0 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72  se atoi().** <tr
2bfd0 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c  ><td>  BLOB    <
2bfe0 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74  td>  FLOAT    <t
2bff0 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20 54 45  d> Convert to TE
2c000 58 54 20 74 68 65 6e 20 75 73 65 20 61 74 6f 66  XT then use atof
2c010 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  ().** <tr><td>  
2c020 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 20 54  BLOB    <td>   T
2c030 45 58 54 20 20 20 20 3c 74 64 3e 20 41 64 64 20  EXT    <td> Add 
2c040 61 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  a zero terminato
2c050 72 20 69 66 20 6e 65 65 64 65 64 0a 2a 2a 20 3c  r if needed.** <
2c060 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f  /table>.** </blo
2c070 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a  ckquote>)^.**.**
2c080 20 54 68 65 20 74 61 62 6c 65 20 61 62 6f 76 65   The table above
2c090 20 6d 61 6b 65 73 20 72 65 66 65 72 65 6e 63 65   makes reference
2c0a0 20 74 6f 20 73 74 61 6e 64 61 72 64 20 43 20 6c   to standard C l
2c0b0 69 62 72 61 72 79 20 66 75 6e 63 74 69 6f 6e 73  ibrary functions
2c0c0 20 61 74 6f 69 28 29 0a 2a 2a 20 61 6e 64 20 61   atoi().** and a
2c0d0 74 6f 66 28 29 2e 20 20 53 51 4c 69 74 65 20 64  tof().  SQLite d
2c0e0 6f 65 73 20 6e 6f 74 20 72 65 61 6c 6c 79 20 75  oes not really u
2c0f0 73 65 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f  se these functio
2c100 6e 73 2e 20 20 49 74 20 68 61 73 20 69 74 73 0a  ns.  It has its.
2c110 2a 2a 20 6f 77 6e 20 65 71 75 69 76 61 6c 65 6e  ** own equivalen
2c120 74 20 69 6e 74 65 72 6e 61 6c 20 72 6f 75 74 69  t internal routi
2c130 6e 65 73 2e 20 20 54 68 65 20 61 74 6f 69 28 29  nes.  The atoi()
2c140 20 61 6e 64 20 61 74 6f 66 28 29 20 6e 61 6d 65   and atof() name
2c150 73 20 61 72 65 0a 2a 2a 20 75 73 65 64 20 69 6e  s are.** used in
2c160 20 74 68 65 20 74 61 62 6c 65 20 66 6f 72 20 62   the table for b
2c170 72 65 76 69 74 79 20 61 6e 64 20 62 65 63 61 75  revity and becau
2c180 73 65 20 74 68 65 79 20 61 72 65 20 66 61 6d 69  se they are fami
2c190 6c 69 61 72 20 74 6f 20 6d 6f 73 74 0a 2a 2a 20  liar to most.** 
2c1a0 43 20 70 72 6f 67 72 61 6d 6d 65 72 73 2e 0a 2a  C programmers..*
2c1b0 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 77  *.** Note that w
2c1c0 68 65 6e 20 74 79 70 65 20 63 6f 6e 76 65 72 73  hen type convers
2c1d0 69 6f 6e 73 20 6f 63 63 75 72 2c 20 70 6f 69 6e  ions occur, poin
2c1e0 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 62 79  ters returned by
2c1f0 20 70 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20   prior.** calls 
2c200 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  to sqlite3_colum
2c210 6e 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65  n_blob(), sqlite
2c220 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c  3_column_text(),
2c230 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74   and/or.** sqlit
2c240 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
2c250 28 29 20 6d 61 79 20 62 65 20 69 6e 76 61 6c 69  () may be invali
2c260 64 61 74 65 64 2e 0a 2a 2a 20 54 79 70 65 20 63  dated..** Type c
2c270 6f 6e 76 65 72 73 69 6f 6e 73 20 61 6e 64 20 70  onversions and p
2c280 6f 69 6e 74 65 72 20 69 6e 76 61 6c 69 64 61 74  ointer invalidat
2c290 69 6f 6e 73 20 6d 69 67 68 74 20 6f 63 63 75 72  ions might occur
2c2a0 0a 2a 2a 20 69 6e 20 74 68 65 20 66 6f 6c 6c 6f  .** in the follo
2c2b0 77 69 6e 67 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a  wing cases:.**.*
2c2c0 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54  * <ul>.** <li> T
2c2d0 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65  he initial conte
2c2e0 6e 74 20 69 73 20 61 20 42 4c 4f 42 20 61 6e 64  nt is a BLOB and
2c2f0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2c300 74 65 78 74 28 29 20 6f 72 0a 2a 2a 20 20 20 20  text() or.**    
2c310 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e    sqlite3_column
2c320 5f 74 65 78 74 31 36 28 29 20 69 73 20 63 61 6c  _text16() is cal
2c330 6c 65 64 2e 20 20 41 20 7a 65 72 6f 2d 74 65 72  led.  A zero-ter
2c340 6d 69 6e 61 74 6f 72 20 6d 69 67 68 74 0a 2a 2a  minator might.**
2c350 20 20 20 20 20 20 6e 65 65 64 20 74 6f 20 62 65        need to be
2c360 20 61 64 64 65 64 20 74 6f 20 74 68 65 20 73 74   added to the st
2c370 72 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c  ring.</li>.** <l
2c380 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63  i> The initial c
2c390 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 38 20  ontent is UTF-8 
2c3a0 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33  text and sqlite3
2c3b0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
2c3c0 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c  ) or.**      sql
2c3d0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2c3e0 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20  16() is called. 
2c3f0 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73   The content mus
2c400 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a  t be converted.*
2c410 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d 31 36  *      to UTF-16
2c420 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54  .</li>.** <li> T
2c430 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65  he initial conte
2c440 6e 74 20 69 73 20 55 54 46 2d 31 36 20 74 65 78  nt is UTF-16 tex
2c450 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f  t and sqlite3_co
2c460 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a  lumn_bytes() or.
2c470 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f  **      sqlite3_
2c480 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69 73  column_text() is
2c490 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f   called.  The co
2c4a0 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f  ntent must be co
2c4b0 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20  nverted.**      
2c4c0 74 6f 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a  to UTF-8.</li>.*
2c4d0 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 43  * </ul>.**.** ^C
2c4e0 6f 6e 76 65 72 73 69 6f 6e 73 20 62 65 74 77 65  onversions betwe
2c4f0 65 6e 20 55 54 46 2d 31 36 62 65 20 61 6e 64 20  en UTF-16be and 
2c500 55 54 46 2d 31 36 6c 65 20 61 72 65 20 61 6c 77  UTF-16le are alw
2c510 61 79 73 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63  ays done in plac
2c520 65 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20  e and do.** not 
2c530 69 6e 76 61 6c 69 64 61 74 65 20 61 20 70 72 69  invalidate a pri
2c540 6f 72 20 70 6f 69 6e 74 65 72 2c 20 74 68 6f 75  or pointer, thou
2c550 67 68 20 6f 66 20 63 6f 75 72 73 65 20 74 68 65  gh of course the
2c560 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20   content of the 
2c570 62 75 66 66 65 72 0a 2a 2a 20 74 68 61 74 20 74  buffer.** that t
2c580 68 65 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72  he prior pointer
2c590 20 72 65 66 65 72 65 6e 63 65 73 20 77 69 6c 6c   references will
2c5a0 20 68 61 76 65 20 62 65 65 6e 20 6d 6f 64 69 66   have been modif
2c5b0 69 65 64 2e 20 20 4f 74 68 65 72 20 6b 69 6e 64  ied.  Other kind
2c5c0 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65 72 73 69  s.** of conversi
2c5d0 6f 6e 20 61 72 65 20 64 6f 6e 65 20 69 6e 20 70  on are done in p
2c5e0 6c 61 63 65 20 77 68 65 6e 20 69 74 20 69 73 20  lace when it is 
2c5f0 70 6f 73 73 69 62 6c 65 2c 20 62 75 74 20 73 6f  possible, but so
2c600 6d 65 74 69 6d 65 73 20 74 68 65 79 0a 2a 2a 20  metimes they.** 
2c610 61 72 65 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65  are not possible
2c620 20 61 6e 64 20 69 6e 20 74 68 6f 73 65 20 63 61   and in those ca
2c630 73 65 73 20 70 72 69 6f 72 20 70 6f 69 6e 74 65  ses prior pointe
2c640 72 73 20 61 72 65 20 69 6e 76 61 6c 69 64 61 74  rs are invalidat
2c650 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 61  ed..**.** The sa
2c660 66 65 73 74 20 61 6e 64 20 65 61 73 69 65 73 74  fest and easiest
2c670 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 70 6f 6c   to remember pol
2c680 69 63 79 20 69 73 20 74 6f 20 69 6e 76 6f 6b 65  icy is to invoke
2c690 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a   these routines.
2c6a0 2a 2a 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65  ** in one of the
2c6b0 20 66 6f 6c 6c 6f 77 69 6e 67 20 77 61 79 73 3a   following ways:
2c6c0 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20  .**.** <ul>.**  
2c6d0 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75  <li>sqlite3_colu
2c6e0 6d 6e 5f 74 65 78 74 28 29 20 66 6f 6c 6c 6f 77  mn_text() follow
2c6f0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
2c700 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69  lumn_bytes()</li
2c710 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65  >.**  <li>sqlite
2c720 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20  3_column_blob() 
2c730 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69  followed by sqli
2c740 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2c750 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e  ()</li>.**  <li>
2c760 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2c770 65 78 74 31 36 28 29 20 66 6f 6c 6c 6f 77 65 64  ext16() followed
2c780 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
2c790 6d 6e 5f 62 79 74 65 73 31 36 28 29 3c 2f 6c 69  mn_bytes16()</li
2c7a0 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  >.** </ul>.**.**
2c7b0 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
2c7c0 20 79 6f 75 20 73 68 6f 75 6c 64 20 63 61 6c 6c   you should call
2c7d0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2c7e0 74 65 78 74 28 29 2c 0a 2a 2a 20 73 71 6c 69 74  text(),.** sqlit
2c7f0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
2c800 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c  , or sqlite3_col
2c810 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 69 72  umn_text16() fir
2c820 73 74 20 74 6f 20 66 6f 72 63 65 20 74 68 65 20  st to force the 
2c830 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74  result.** into t
2c840 68 65 20 64 65 73 69 72 65 64 20 66 6f 72 6d 61  he desired forma
2c850 74 2c 20 74 68 65 6e 20 69 6e 76 6f 6b 65 20 73  t, then invoke s
2c860 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2c870 74 65 73 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69  tes() or.** sqli
2c880 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2c890 31 36 28 29 20 74 6f 20 66 69 6e 64 20 74 68 65  16() to find the
2c8a0 20 73 69 7a 65 20 6f 66 20 74 68 65 20 72 65 73   size of the res
2c8b0 75 6c 74 2e 20 20 44 6f 20 6e 6f 74 20 6d 69 78  ult.  Do not mix
2c8c0 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c   calls.** to sql
2c8d0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2c8e0 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f  () or sqlite3_co
2c8f0 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 77 69 74 68  lumn_blob() with
2c900 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c   calls to.** sql
2c910 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2c920 73 31 36 28 29 2c 20 61 6e 64 20 64 6f 20 6e 6f  s16(), and do no
2c930 74 20 6d 69 78 20 63 61 6c 6c 73 20 74 6f 20 73  t mix calls to s
2c940 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2c950 78 74 31 36 28 29 0a 2a 2a 20 77 69 74 68 20 63  xt16().** with c
2c960 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
2c970 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 2e 0a  column_bytes()..
2c980 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 6f 69 6e 74  **.** ^The point
2c990 65 72 73 20 72 65 74 75 72 6e 65 64 20 61 72 65  ers returned are
2c9a0 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 61 20 74   valid until a t
2c9b0 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f  ype conversion o
2c9c0 63 63 75 72 73 20 61 73 0a 2a 2a 20 64 65 73 63  ccurs as.** desc
2c9d0 72 69 62 65 64 20 61 62 6f 76 65 2c 20 6f 72 20  ribed above, or 
2c9e0 75 6e 74 69 6c 20 5b 73 71 6c 69 74 65 33 5f 73  until [sqlite3_s
2c9f0 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  tep()] or [sqlit
2ca00 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a  e3_reset()] or.*
2ca10 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  * [sqlite3_final
2ca20 69 7a 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64  ize()] is called
2ca30 2e 20 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 73  .  ^The memory s
2ca40 70 61 63 65 20 75 73 65 64 20 74 6f 20 68 6f 6c  pace used to hol
2ca50 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20 61 6e 64  d strings.** and
2ca60 20 42 4c 4f 42 73 20 69 73 20 66 72 65 65 64 20   BLOBs is freed 
2ca70 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20  automatically.  
2ca80 44 6f 20 3c 62 3e 6e 6f 74 3c 2f 62 3e 20 70 61  Do <b>not</b> pa
2ca90 73 73 20 74 68 65 20 70 6f 69 6e 74 65 72 73 20  ss the pointers 
2caa0 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 73 71 6c  returned.** [sql
2cab0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
2cac0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 6f  ()], [sqlite3_co
2cad0 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 65 74  lumn_text()], et
2cae0 63 2e 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69  c. into.** [sqli
2caf0 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a  te3_free()]..**.
2cb00 2a 2a 20 5e 28 49 66 20 61 20 6d 65 6d 6f 72 79  ** ^(If a memory
2cb10 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f   allocation erro
2cb20 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20  r occurs during 
2cb30 74 68 65 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f  the evaluation o
2cb40 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 73  f any.** of thes
2cb50 65 20 72 6f 75 74 69 6e 65 73 2c 20 61 20 64 65  e routines, a de
2cb60 66 61 75 6c 74 20 76 61 6c 75 65 20 69 73 20 72  fault value is r
2cb70 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 64 65  eturned.  The de
2cb80 66 61 75 6c 74 20 76 61 6c 75 65 0a 2a 2a 20 69  fault value.** i
2cb90 73 20 65 69 74 68 65 72 20 74 68 65 20 69 6e 74  s either the int
2cba0 65 67 65 72 20 30 2c 20 74 68 65 20 66 6c 6f 61  eger 0, the floa
2cbb0 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65  ting point numbe
2cbc0 72 20 30 2e 30 2c 20 6f 72 20 61 20 4e 55 4c 4c  r 0.0, or a NULL
2cbd0 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e 20 20 53 75  .** pointer.  Su
2cbe0 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74  bsequent calls t
2cbf0 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  o [sqlite3_errco
2cc00 64 65 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72  de()] will retur
2cc10 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d  n.** [SQLITE_NOM
2cc20 45 4d 5d 2e 29 5e 0a 2a 2f 0a 63 6f 6e 73 74 20  EM].)^.*/.const 
2cc30 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
2cc40 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69 74 65  lumn_blob(sqlite
2cc50 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
2cc60 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  l);.int sqlite3_
2cc70 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 73 71 6c  column_bytes(sql
2cc80 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
2cc90 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74  iCol);.int sqlit
2cca0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
2ccb0 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
2ccc0 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 64 6f 75 62   int iCol);.doub
2ccd0 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  le sqlite3_colum
2cce0 6e 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33  n_double(sqlite3
2ccf0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
2cd00 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
2cd10 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65  olumn_int(sqlite
2cd20 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
2cd30 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36  l);.sqlite3_int6
2cd40 34 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  4 sqlite3_column
2cd50 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73  _int64(sqlite3_s
2cd60 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
2cd70 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20  .const unsigned 
2cd80 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
2cd90 6c 75 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74 65  lumn_text(sqlite
2cda0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
2cdb0 6c 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  l);.const void *
2cdc0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2cdd0 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ext16(sqlite3_st
2cde0 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
2cdf0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  int sqlite3_colu
2ce00 6d 6e 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f  mn_type(sqlite3_
2ce10 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
2ce20 3b 0a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  ;.sqlite3_value 
2ce30 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
2ce40 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74  value(sqlite3_st
2ce50 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
2ce60 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2ce70 20 44 65 73 74 72 6f 79 20 41 20 50 72 65 70 61   Destroy A Prepa
2ce80 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62  red Statement Ob
2ce90 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ject.**.** ^The 
2cea0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2ceb0 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63  () function is c
2cec0 61 6c 6c 65 64 20 74 6f 20 64 65 6c 65 74 65 20  alled to delete 
2ced0 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
2cee0 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 49 66 20 74  ement]..** ^If t
2cef0 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65  he most recent e
2cf00 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 74 68 65  valuation of the
2cf10 20 73 74 61 74 65 6d 65 6e 74 20 65 6e 63 6f 75   statement encou
2cf20 6e 74 65 72 65 64 20 6e 6f 20 65 72 72 6f 72 73  ntered no errors
2cf30 0a 2a 2a 20 6f 72 20 69 66 20 74 68 65 20 73 74  .** or if the st
2cf40 61 74 65 6d 65 6e 74 20 69 73 20 6e 65 76 65 72  atement is never
2cf50 20 62 65 65 6e 20 65 76 61 6c 75 61 74 65 64 2c   been evaluated,
2cf60 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 66 69   then sqlite3_fi
2cf70 6e 61 6c 69 7a 65 28 29 20 72 65 74 75 72 6e 73  nalize() returns
2cf80 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b 2e 20 20  .** SQLITE_OK.  
2cf90 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63  ^If the most rec
2cfa0 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f  ent evaluation o
2cfb0 66 20 73 74 61 74 65 6d 65 6e 74 20 53 20 66 61  f statement S fa
2cfc0 69 6c 65 64 2c 20 74 68 65 6e 0a 2a 2a 20 73 71  iled, then.** sq
2cfd0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53  lite3_finalize(S
2cfe0 29 20 72 65 74 75 72 6e 73 20 74 68 65 20 61 70  ) returns the ap
2cff0 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72  propriate [error
2d000 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78   code] or.** [ex
2d010 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64  tended error cod
2d020 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  e]..**.** ^The s
2d030 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2d040 53 29 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62  S) routine can b
2d050 65 20 63 61 6c 6c 65 64 20 61 74 20 61 6e 79 20  e called at any 
2d060 70 6f 69 6e 74 20 64 75 72 69 6e 67 0a 2a 2a 20  point during.** 
2d070 74 68 65 20 6c 69 66 65 20 63 79 63 6c 65 20 6f  the life cycle o
2d080 66 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  f [prepared stat
2d090 65 6d 65 6e 74 5d 20 53 3a 0a 2a 2a 20 62 65 66  ement] S:.** bef
2d0a0 6f 72 65 20 73 74 61 74 65 6d 65 6e 74 20 53 20  ore statement S 
2d0b0 69 73 20 65 76 65 72 20 65 76 61 6c 75 61 74 65  is ever evaluate
2d0c0 64 2c 20 61 66 74 65 72 0a 2a 2a 20 6f 6e 65 20  d, after.** one 
2d0d0 6f 72 20 6d 6f 72 65 20 63 61 6c 6c 73 20 74 6f  or more calls to
2d0e0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2d0f0 29 5d 2c 20 6f 72 20 61 66 74 65 72 20 61 6e 79  )], or after any
2d100 20 63 61 6c 6c 0a 2a 2a 20 74 6f 20 5b 73 71 6c   call.** to [sql
2d110 69 74 65 33 5f 73 74 65 70 28 29 5d 20 72 65 67  ite3_step()] reg
2d120 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68  ardless of wheth
2d130 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 73 74  er or not the st
2d140 61 74 65 6d 65 6e 74 20 68 61 73 0a 2a 2a 20 63  atement has.** c
2d150 6f 6d 70 6c 65 74 65 64 20 65 78 65 63 75 74 69  ompleted executi
2d160 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 76 6f 6b  on..**.** ^Invok
2d170 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 69 6e 61  ing sqlite3_fina
2d180 6c 69 7a 65 28 29 20 6f 6e 20 61 20 4e 55 4c 4c  lize() on a NULL
2d190 20 70 6f 69 6e 74 65 72 20 69 73 20 61 20 68 61   pointer is a ha
2d1a0 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a  rmless no-op..**
2d1b0 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
2d1c0 69 6f 6e 20 6d 75 73 74 20 66 69 6e 61 6c 69 7a  ion must finaliz
2d1d0 65 20 65 76 65 72 79 20 5b 70 72 65 70 61 72 65  e every [prepare
2d1e0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20  d statement] in 
2d1f0 6f 72 64 65 72 20 74 6f 20 61 76 6f 69 64 0a 2a  order to avoid.*
2d200 2a 20 72 65 73 6f 75 72 63 65 20 6c 65 61 6b 73  * resource leaks
2d210 2e 20 20 49 74 20 69 73 20 61 20 67 72 69 65 76  .  It is a griev
2d220 6f 75 73 20 65 72 72 6f 72 20 66 6f 72 20 74 68  ous error for th
2d230 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f  e application to
2d240 20 74 72 79 20 74 6f 20 75 73 65 0a 2a 2a 20 61   try to use.** a
2d250 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
2d260 65 6e 74 20 61 66 74 65 72 20 69 74 20 68 61 73  ent after it has
2d270 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2e   been finalized.
2d280 20 20 41 6e 79 20 75 73 65 20 6f 66 20 61 20 70    Any use of a p
2d290 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65  repared.** state
2d2a0 6d 65 6e 74 20 61 66 74 65 72 20 69 74 20 68 61  ment after it ha
2d2b0 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64  s been finalized
2d2c0 20 63 61 6e 20 72 65 73 75 6c 74 20 69 6e 20 75   can result in u
2d2d0 6e 64 65 66 69 6e 65 64 20 61 6e 64 0a 2a 2a 20  ndefined and.** 
2d2e0 75 6e 64 65 73 69 72 61 62 6c 65 20 62 65 68 61  undesirable beha
2d2f0 76 69 6f 72 20 73 75 63 68 20 61 73 20 73 65 67  vior such as seg
2d300 66 61 75 6c 74 73 20 61 6e 64 20 68 65 61 70 20  faults and heap 
2d310 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 69  corruption..*/.i
2d320 6e 74 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  nt sqlite3_final
2d330 69 7a 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ize(sqlite3_stmt
2d340 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
2d350 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74   CAPI3REF: Reset
2d360 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74   A Prepared Stat
2d370 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a  ement Object.**.
2d380 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72  ** The sqlite3_r
2d390 65 73 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 20  eset() function 
2d3a0 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 72 65 73  is called to res
2d3b0 65 74 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  et a [prepared s
2d3c0 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a  tatement].** obj
2d3d0 65 63 74 20 62 61 63 6b 20 74 6f 20 69 74 73 20  ect back to its 
2d3e0 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2c 20 72  initial state, r
2d3f0 65 61 64 79 20 74 6f 20 62 65 20 72 65 2d 65 78  eady to be re-ex
2d400 65 63 75 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20  ecuted..** ^Any 
2d410 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 76 61  SQL statement va
2d420 72 69 61 62 6c 65 73 20 74 68 61 74 20 68 61 64  riables that had
2d430 20 76 61 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f   values bound to
2d440 20 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 74   them using.** t
2d450 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  he [sqlite3_bind
2d460 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f  _blob | sqlite3_
2d470 62 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72 65  bind_*() API] re
2d480 74 61 69 6e 20 74 68 65 69 72 20 76 61 6c 75 65  tain their value
2d490 73 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69 74  s..** Use [sqlit
2d4a0 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67  e3_clear_binding
2d4b0 73 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68  s()] to reset th
2d4c0 65 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a  e bindings..**.*
2d4d0 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  * ^The [sqlite3_
2d4e0 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66  reset(S)] interf
2d4f0 61 63 65 20 72 65 73 65 74 73 20 74 68 65 20 5b  ace resets the [
2d500 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2d510 6e 74 5d 20 53 0a 2a 2a 20 62 61 63 6b 20 74 6f  nt] S.** back to
2d520 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f   the beginning o
2d530 66 20 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a 2a  f its program..*
2d540 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73  *.** ^If the mos
2d550 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f  t recent call to
2d560 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53   [sqlite3_step(S
2d570 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70  )] for the.** [p
2d580 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2d590 74 5d 20 53 20 72 65 74 75 72 6e 65 64 20 5b 53  t] S returned [S
2d5a0 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b 53  QLITE_ROW] or [S
2d5b0 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20  QLITE_DONE],.** 
2d5c0 6f 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 73  or if [sqlite3_s
2d5d0 74 65 70 28 53 29 5d 20 68 61 73 20 6e 65 76 65  tep(S)] has neve
2d5e0 72 20 62 65 66 6f 72 65 20 62 65 65 6e 20 63 61  r before been ca
2d5f0 6c 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20 74 68  lled on S,.** th
2d600 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  en [sqlite3_rese
2d610 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20 5b 53  t(S)] returns [S
2d620 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a  QLITE_OK]..**.**
2d630 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65   ^If the most re
2d640 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71  cent call to [sq
2d650 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66  lite3_step(S)] f
2d660 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61  or the.** [prepa
2d670 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
2d680 20 69 6e 64 69 63 61 74 65 64 20 61 6e 20 65 72   indicated an er
2d690 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20 5b 73 71  ror, then.** [sq
2d6a0 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20  lite3_reset(S)] 
2d6b0 72 65 74 75 72 6e 73 20 61 6e 20 61 70 70 72 6f  returns an appro
2d6c0 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f  priate [error co
2d6d0 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  de]..**.** ^The 
2d6e0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53  [sqlite3_reset(S
2d6f0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 64 6f 65  )] interface doe
2d700 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65  s not change the
2d710 20 76 61 6c 75 65 73 0a 2a 2a 20 6f 66 20 61 6e   values.** of an
2d720 79 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  y [sqlite3_bind_
2d730 62 6c 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20 6f  blob|bindings] o
2d740 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  n the [prepared 
2d750 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f  statement] S..*/
2d760 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 73  .int sqlite3_res
2d770 65 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  et(sqlite3_stmt 
2d780 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
2d790 43 41 50 49 33 52 45 46 3a 20 43 72 65 61 74 65  CAPI3REF: Create
2d7a0 20 4f 72 20 52 65 64 65 66 69 6e 65 20 53 51 4c   Or Redefine SQL
2d7b0 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4b 45   Functions.** KE
2d7c0 59 57 4f 52 44 53 3a 20 7b 66 75 6e 63 74 69 6f  YWORDS: {functio
2d7d0 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69  n creation routi
2d7e0 6e 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  nes}.** KEYWORDS
2d7f0 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  : {application-d
2d800 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
2d810 69 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ion}.** KEYWORDS
2d820 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  : {application-d
2d830 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
2d840 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ions}.**.** ^The
2d850 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 28 63 6f  se functions (co
2d860 6c 6c 65 63 74 69 76 65 6c 79 20 6b 6e 6f 77 6e  llectively known
2d870 20 61 73 20 22 66 75 6e 63 74 69 6f 6e 20 63 72   as "function cr
2d880 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 22  eation routines"
2d890 29 0a 2a 2a 20 61 72 65 20 75 73 65 64 20 74 6f  ).** are used to
2d8a0 20 61 64 64 20 53 51 4c 20 66 75 6e 63 74 69 6f   add SQL functio
2d8b0 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 65 73  ns or aggregates
2d8c0 20 6f 72 20 74 6f 20 72 65 64 65 66 69 6e 65 20   or to redefine 
2d8d0 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20  the behavior.** 
2d8e0 6f 66 20 65 78 69 73 74 69 6e 67 20 53 51 4c 20  of existing SQL 
2d8f0 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67  functions or agg
2d900 72 65 67 61 74 65 73 2e 20 20 54 68 65 20 6f 6e  regates.  The on
2d910 6c 79 20 64 69 66 66 65 72 65 6e 63 65 73 20 62  ly differences b
2d920 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 73 65 20  etween.** these 
2d930 72 6f 75 74 69 6e 65 73 20 61 72 65 20 74 68 65  routines are the
2d940 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 65   text encoding e
2d950 78 70 65 63 74 65 64 20 66 6f 72 0a 2a 2a 20 74  xpected for.** t
2d960 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
2d970 74 65 72 20 28 74 68 65 20 6e 61 6d 65 20 6f 66  ter (the name of
2d980 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 62 65   the function be
2d990 69 6e 67 20 63 72 65 61 74 65 64 29 0a 2a 2a 20  ing created).** 
2d9a0 61 6e 64 20 74 68 65 20 70 72 65 73 65 6e 63 65  and the presence
2d9b0 20 6f 72 20 61 62 73 65 6e 63 65 20 6f 66 20 61   or absence of a
2d9c0 20 64 65 73 74 72 75 63 74 6f 72 20 63 61 6c 6c   destructor call
2d9d0 62 61 63 6b 20 66 6f 72 0a 2a 2a 20 74 68 65 20  back for.** the 
2d9e0 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61  application data
2d9f0 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
2da00 5e 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d  ^The first param
2da10 65 74 65 72 20 69 73 20 74 68 65 20 5b 64 61 74  eter is the [dat
2da20 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2da30 5d 20 74 6f 20 77 68 69 63 68 20 74 68 65 20 53  ] to which the S
2da40 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69  QL.** function i
2da50 73 20 74 6f 20 62 65 20 61 64 64 65 64 2e 20 20  s to be added.  
2da60 5e 49 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69  ^If an applicati
2da70 6f 6e 20 75 73 65 73 20 6d 6f 72 65 20 74 68 61  on uses more tha
2da80 6e 20 6f 6e 65 20 64 61 74 61 62 61 73 65 0a 2a  n one database.*
2da90 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 65  * connection the
2daa0 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  n application-de
2dab0 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
2dac0 6f 6e 73 20 6d 75 73 74 20 62 65 20 61 64 64 65  ons must be adde
2dad0 64 0a 2a 2a 20 74 6f 20 65 61 63 68 20 64 61 74  d.** to each dat
2dae0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2daf0 20 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a   separately..**.
2db00 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70  ** ^The second p
2db10 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20  arameter is the 
2db20 6e 61 6d 65 20 6f 66 20 74 68 65 20 53 51 4c 20  name of the SQL 
2db30 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 63  function to be c
2db40 72 65 61 74 65 64 20 6f 72 0a 2a 2a 20 72 65 64  reated or.** red
2db50 65 66 69 6e 65 64 2e 20 20 5e 54 68 65 20 6c 65  efined.  ^The le
2db60 6e 67 74 68 20 6f 66 20 74 68 65 20 6e 61 6d 65  ngth of the name
2db70 20 69 73 20 6c 69 6d 69 74 65 64 20 74 6f 20 32   is limited to 2
2db80 35 35 20 62 79 74 65 73 20 69 6e 20 61 20 55 54  55 bytes in a UT
2db90 46 2d 38 0a 2a 2a 20 72 65 70 72 65 73 65 6e 74  F-8.** represent
2dba0 61 74 69 6f 6e 2c 20 65 78 63 6c 75 73 69 76 65  ation, exclusive
2dbb0 20 6f 66 20 74 68 65 20 7a 65 72 6f 2d 74 65 72   of the zero-ter
2dbc0 6d 69 6e 61 74 6f 72 2e 20 20 5e 4e 6f 74 65 20  minator.  ^Note 
2dbd0 74 68 61 74 20 74 68 65 20 6e 61 6d 65 0a 2a 2a  that the name.**
2dbe0 20 6c 65 6e 67 74 68 20 6c 69 6d 69 74 20 69 73   length limit is
2dbf0 20 69 6e 20 55 54 46 2d 38 20 62 79 74 65 73 2c   in UTF-8 bytes,
2dc00 20 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 20   not characters 
2dc10 6e 6f 72 20 55 54 46 2d 31 36 20 62 79 74 65 73  nor UTF-16 bytes
2dc20 2e 20 20 0a 2a 2a 20 5e 41 6e 79 20 61 74 74 65  .  .** ^Any atte
2dc30 6d 70 74 20 74 6f 20 63 72 65 61 74 65 20 61 20  mpt to create a 
2dc40 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20  function with a 
2dc50 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 77  longer name.** w
2dc60 69 6c 6c 20 72 65 73 75 6c 74 20 69 6e 20 5b 53  ill result in [S
2dc70 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 62 65  QLITE_MISUSE] be
2dc80 69 6e 67 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a  ing returned..**
2dc90 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20 70  .** ^The third p
2dca0 61 72 61 6d 65 74 65 72 20 28 6e 41 72 67 29 0a  arameter (nArg).
2dcb0 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72  ** is the number
2dcc0 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 74 68   of arguments th
2dcd0 61 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  at the SQL funct
2dce0 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67  ion or.** aggreg
2dcf0 61 74 65 20 74 61 6b 65 73 2e 20 5e 49 66 20 74  ate takes. ^If t
2dd00 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 69 73  his parameter is
2dd10 20 2d 31 2c 20 74 68 65 6e 20 74 68 65 20 53 51   -1, then the SQ
2dd20 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a  L function or.**
2dd30 20 61 67 67 72 65 67 61 74 65 20 6d 61 79 20 74   aggregate may t
2dd40 61 6b 65 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f  ake any number o
2dd50 66 20 61 72 67 75 6d 65 6e 74 73 20 62 65 74 77  f arguments betw
2dd60 65 65 6e 20 30 20 61 6e 64 20 74 68 65 20 6c 69  een 0 and the li
2dd70 6d 69 74 0a 2a 2a 20 73 65 74 20 62 79 20 5b 73  mit.** set by [s
2dd80 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53  qlite3_limit]([S
2dd90 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43  QLITE_LIMIT_FUNC
2dda0 54 49 4f 4e 5f 41 52 47 5d 29 2e 20 20 49 66 20  TION_ARG]).  If 
2ddb0 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72  the third.** par
2ddc0 61 6d 65 74 65 72 20 69 73 20 6c 65 73 73 20 74  ameter is less t
2ddd0 68 61 6e 20 2d 31 20 6f 72 20 67 72 65 61 74 65  han -1 or greate
2dde0 72 20 74 68 61 6e 20 31 32 37 20 74 68 65 6e 20  r than 127 then 
2ddf0 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 0a  the behavior is.
2de00 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  ** undefined..**
2de10 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20  .** ^The fourth 
2de20 70 61 72 61 6d 65 74 65 72 2c 20 65 54 65 78 74  parameter, eText
2de30 52 65 70 2c 20 73 70 65 63 69 66 69 65 73 20 77  Rep, specifies w
2de40 68 61 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55  hat.** [SQLITE_U
2de50 54 46 38 20 7c 20 74 65 78 74 20 65 6e 63 6f 64  TF8 | text encod
2de60 69 6e 67 5d 20 74 68 69 73 20 53 51 4c 20 66 75  ing] this SQL fu
2de70 6e 63 74 69 6f 6e 20 70 72 65 66 65 72 73 20 66  nction prefers f
2de80 6f 72 0a 2a 2a 20 69 74 73 20 70 61 72 61 6d 65  or.** its parame
2de90 74 65 72 73 2e 20 20 45 76 65 72 79 20 53 51 4c  ters.  Every SQL
2dea0 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d   function implem
2deb0 65 6e 74 61 74 69 6f 6e 20 6d 75 73 74 20 62 65  entation must be
2dec0 20 61 62 6c 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a   able to work.**
2ded0 20 77 69 74 68 20 55 54 46 2d 38 2c 20 55 54 46   with UTF-8, UTF
2dee0 2d 31 36 6c 65 2c 20 6f 72 20 55 54 46 2d 31 36  -16le, or UTF-16
2def0 62 65 2e 20 20 42 75 74 20 73 6f 6d 65 20 69 6d  be.  But some im
2df00 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 61  plementations ma
2df10 79 20 62 65 0a 2a 2a 20 6d 6f 72 65 20 65 66 66  y be.** more eff
2df20 69 63 69 65 6e 74 20 77 69 74 68 20 6f 6e 65 20  icient with one 
2df30 65 6e 63 6f 64 69 6e 67 20 74 68 61 6e 20 61 6e  encoding than an
2df40 6f 74 68 65 72 2e 20 20 5e 41 6e 20 61 70 70 6c  other.  ^An appl
2df50 69 63 61 74 69 6f 6e 20 6d 61 79 0a 2a 2a 20 69  ication may.** i
2df60 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 72  nvoke sqlite3_cr
2df70 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 20  eate_function() 
2df80 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  or sqlite3_creat
2df90 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 20 6d  e_function16() m
2dfa0 75 6c 74 69 70 6c 65 0a 2a 2a 20 74 69 6d 65 73  ultiple.** times
2dfb0 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 66   with the same f
2dfc0 75 6e 63 74 69 6f 6e 20 62 75 74 20 77 69 74 68  unction but with
2dfd0 20 64 69 66 66 65 72 65 6e 74 20 76 61 6c 75 65   different value
2dfe0 73 20 6f 66 20 65 54 65 78 74 52 65 70 2e 0a 2a  s of eTextRep..*
2dff0 2a 20 5e 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65  * ^When multiple
2e000 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
2e010 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e   of the same fun
2e020 63 74 69 6f 6e 20 61 72 65 20 61 76 61 69 6c 61  ction are availa
2e030 62 6c 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 77  ble, SQLite.** w
2e040 69 6c 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e 65  ill pick the one
2e050 20 74 68 61 74 20 69 6e 76 6f 6c 76 65 73 20 74   that involves t
2e060 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20  he least amount 
2e070 6f 66 20 64 61 74 61 20 63 6f 6e 76 65 72 73 69  of data conversi
2e080 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 72 65 20  on..** If there 
2e090 69 73 20 6f 6e 6c 79 20 61 20 73 69 6e 67 6c 65  is only a single
2e0a0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
2e0b0 77 68 69 63 68 20 64 6f 65 73 20 6e 6f 74 20 63  which does not c
2e0c0 61 72 65 20 77 68 61 74 20 74 65 78 74 0a 2a 2a  are what text.**
2e0d0 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65   encoding is use
2e0e0 64 2c 20 74 68 65 6e 20 74 68 65 20 66 6f 75 72  d, then the four
2e0f0 74 68 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75  th argument shou
2e100 6c 64 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 4e  ld be [SQLITE_AN
2e110 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  Y]..**.** ^(The 
2e120 66 69 66 74 68 20 70 61 72 61 6d 65 74 65 72 20  fifth parameter 
2e130 69 73 20 61 6e 20 61 72 62 69 74 72 61 72 79 20  is an arbitrary 
2e140 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 69 6d  pointer.  The im
2e150 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
2e160 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  the.** function 
2e170 63 61 6e 20 67 61 69 6e 20 61 63 63 65 73 73 20  can gain access 
2e180 74 6f 20 74 68 69 73 20 70 6f 69 6e 74 65 72 20  to this pointer 
2e190 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 75  using [sqlite3_u
2e1a0 73 65 72 5f 64 61 74 61 28 29 5d 2e 29 5e 0a 2a  ser_data()].)^.*
2e1b0 2a 0a 2a 2a 20 5e 54 68 65 20 73 69 78 74 68 2c  *.** ^The sixth,
2e1c0 20 73 65 76 65 6e 74 68 20 61 6e 64 20 65 69 67   seventh and eig
2e1d0 68 74 68 20 70 61 72 61 6d 65 74 65 72 73 2c 20  hth parameters, 
2e1e0 78 46 75 6e 63 2c 20 78 53 74 65 70 20 61 6e 64  xFunc, xStep and
2e1f0 20 78 46 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20   xFinal, are.** 
2e200 70 6f 69 6e 74 65 72 73 20 74 6f 20 43 2d 6c 61  pointers to C-la
2e210 6e 67 75 61 67 65 20 66 75 6e 63 74 69 6f 6e 73  nguage functions
2e220 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20   that implement 
2e230 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
2e240 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65   or.** aggregate
2e250 2e 20 5e 41 20 73 63 61 6c 61 72 20 53 51 4c 20  . ^A scalar SQL 
2e260 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65  function require
2e270 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  s an implementat
2e280 69 6f 6e 20 6f 66 20 74 68 65 20 78 46 75 6e 63  ion of the xFunc
2e290 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c  .** callback onl
2e2a0 79 3b 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73  y; NULL pointers
2e2b0 20 6d 75 73 74 20 62 65 20 70 61 73 73 65 64 20   must be passed 
2e2c0 61 73 20 74 68 65 20 78 53 74 65 70 20 61 6e 64  as the xStep and
2e2d0 20 78 46 69 6e 61 6c 0a 2a 2a 20 70 61 72 61 6d   xFinal.** param
2e2e0 65 74 65 72 73 2e 20 5e 41 6e 20 61 67 67 72 65  eters. ^An aggre
2e2f0 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f  gate SQL functio
2e300 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d  n requires an im
2e310 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
2e320 78 53 74 65 70 0a 2a 2a 20 61 6e 64 20 78 46 69  xStep.** and xFi
2e330 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c 20 70 6f 69  nal and NULL poi
2e340 6e 74 65 72 20 6d 75 73 74 20 62 65 20 70 61 73  nter must be pas
2e350 73 65 64 20 66 6f 72 20 78 46 75 6e 63 2e 20 5e  sed for xFunc. ^
2e360 54 6f 20 64 65 6c 65 74 65 20 61 6e 20 65 78 69  To delete an exi
2e370 73 74 69 6e 67 0a 2a 2a 20 53 51 4c 20 66 75 6e  sting.** SQL fun
2e380 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61  ction or aggrega
2e390 74 65 2c 20 70 61 73 73 20 4e 55 4c 4c 20 70 6f  te, pass NULL po
2e3a0 69 6e 74 65 72 73 20 66 6f 72 20 61 6c 6c 20 74  inters for all t
2e3b0 68 72 65 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  hree function.**
2e3c0 20 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a 0a 2a   callbacks..**.*
2e3d0 2a 20 5e 28 49 66 20 74 68 65 20 6e 69 6e 74 68  * ^(If the ninth
2e3e0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
2e3f0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
2e400 63 74 69 6f 6e 5f 76 32 28 29 20 69 73 20 6e 6f  ction_v2() is no
2e410 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 74 68 65 6e 20  t NULL,.** then 
2e420 69 74 20 69 73 20 64 65 73 74 72 75 63 74 6f 72  it is destructor
2e430 20 66 6f 72 20 74 68 65 20 61 70 70 6c 69 63 61   for the applica
2e440 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65  tion data pointe
2e450 72 2e 20 0a 2a 2a 20 54 68 65 20 64 65 73 74 72  r. .** The destr
2e460 75 63 74 6f 72 20 69 73 20 69 6e 76 6f 6b 65 64  uctor is invoked
2e470 20 77 68 65 6e 20 74 68 65 20 66 75 6e 63 74 69   when the functi
2e480 6f 6e 20 69 73 20 64 65 6c 65 74 65 64 2c 20 65  on is deleted, e
2e490 69 74 68 65 72 20 62 79 20 62 65 69 6e 67 0a 2a  ither by being.*
2e4a0 2a 20 6f 76 65 72 6c 6f 61 64 65 64 20 6f 72 20  * overloaded or 
2e4b0 77 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  when the databas
2e4c0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f  e connection clo
2e4d0 73 65 73 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 64  ses.)^.** ^The d
2e4e0 65 73 74 72 75 63 74 6f 72 20 69 73 20 61 6c 73  estructor is als
2e4f0 6f 20 69 6e 76 6f 6b 65 64 20 69 66 20 74 68 65  o invoked if the
2e500 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69   call to.** sqli
2e510 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2e520 69 6f 6e 5f 76 32 28 29 20 66 61 69 6c 73 2e 0a  ion_v2() fails..
2e530 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20 64 65 73  ** ^When the des
2e540 74 72 75 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b  tructor callback
2e550 20 6f 66 20 74 68 65 20 74 65 6e 74 68 20 70 61   of the tenth pa
2e560 72 61 6d 65 74 65 72 20 69 73 20 69 6e 76 6f 6b  rameter is invok
2e570 65 64 2c 20 69 74 0a 2a 2a 20 69 73 20 70 61 73  ed, it.** is pas
2e580 73 65 64 20 61 20 73 69 6e 67 6c 65 20 61 72 67  sed a single arg
2e590 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61  ument which is a
2e5a0 20 63 6f 70 79 20 6f 66 20 74 68 65 20 61 70 70   copy of the app
2e5b0 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 0a 2a  lication data .*
2e5c0 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68 20  * pointer which 
2e5d0 77 61 73 20 74 68 65 20 66 69 66 74 68 20 70 61  was the fifth pa
2e5e0 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
2e5f0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
2e600 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e  on_v2()..**.** ^
2e610 49 74 20 69 73 20 70 65 72 6d 69 74 74 65 64 20  It is permitted 
2e620 74 6f 20 72 65 67 69 73 74 65 72 20 6d 75 6c 74  to register mult
2e630 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  iple implementat
2e640 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65  ions of the same
2e650 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 77 69  .** functions wi
2e660 74 68 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65  th the same name
2e670 20 62 75 74 20 77 69 74 68 20 65 69 74 68 65 72   but with either
2e680 20 64 69 66 66 65 72 69 6e 67 20 6e 75 6d 62 65   differing numbe
2e690 72 73 20 6f 66 0a 2a 2a 20 61 72 67 75 6d 65 6e  rs of.** argumen
2e6a0 74 73 20 6f 72 20 64 69 66 66 65 72 69 6e 67 20  ts or differing 
2e6b0 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65  preferred text e
2e6c0 6e 63 6f 64 69 6e 67 73 2e 20 20 5e 53 51 4c 69  ncodings.  ^SQLi
2e6d0 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 74  te will use.** t
2e6e0 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
2e6f0 6e 20 74 68 61 74 20 6d 6f 73 74 20 63 6c 6f 73  n that most clos
2e700 65 6c 79 20 6d 61 74 63 68 65 73 20 74 68 65 20  ely matches the 
2e710 77 61 79 20 69 6e 20 77 68 69 63 68 20 74 68 65  way in which the
2e720 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  .** SQL function
2e730 20 69 73 20 75 73 65 64 2e 20 20 5e 41 20 66 75   is used.  ^A fu
2e740 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74  nction implement
2e750 61 74 69 6f 6e 20 77 69 74 68 20 61 20 6e 6f 6e  ation with a non
2e760 2d 6e 65 67 61 74 69 76 65 0a 2a 2a 20 6e 41 72  -negative.** nAr
2e770 67 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  g parameter is a
2e780 20 62 65 74 74 65 72 20 6d 61 74 63 68 20 74 68   better match th
2e790 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 69 6d  an a function im
2e7a0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74  plementation wit
2e7b0 68 0a 2a 2a 20 61 20 6e 65 67 61 74 69 76 65 20  h.** a negative 
2e7c0 6e 41 72 67 2e 20 20 5e 41 20 66 75 6e 63 74 69  nArg.  ^A functi
2e7d0 6f 6e 20 77 68 65 72 65 20 74 68 65 20 70 72 65  on where the pre
2e7e0 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f  ferred text enco
2e7f0 64 69 6e 67 0a 2a 2a 20 6d 61 74 63 68 65 73 20  ding.** matches 
2e800 74 68 65 20 64 61 74 61 62 61 73 65 20 65 6e 63  the database enc
2e810 6f 64 69 6e 67 20 69 73 20 61 20 62 65 74 74 65  oding is a bette
2e820 72 0a 2a 2a 20 6d 61 74 63 68 20 74 68 61 6e 20  r.** match than 
2e830 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65  a function where
2e840 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 69 73   the encoding is
2e850 20 64 69 66 66 65 72 65 6e 74 2e 20 20 0a 2a 2a   different.  .**
2e860 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65   ^A function whe
2e870 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20  re the encoding 
2e880 64 69 66 66 65 72 65 6e 63 65 20 69 73 20 62 65  difference is be
2e890 74 77 65 65 6e 20 55 54 46 31 36 6c 65 20 61 6e  tween UTF16le an
2e8a0 64 20 55 54 46 31 36 62 65 0a 2a 2a 20 69 73 20  d UTF16be.** is 
2e8b0 61 20 63 6c 6f 73 65 72 20 6d 61 74 63 68 20 74  a closer match t
2e8c0 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77  han a function w
2e8d0 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e  here the encodin
2e8e0 67 20 64 69 66 66 65 72 65 6e 63 65 20 69 73 0a  g difference is.
2e8f0 2a 2a 20 62 65 74 77 65 65 6e 20 55 54 46 38 20  ** between UTF8 
2e900 61 6e 64 20 55 54 46 31 36 2e 0a 2a 2a 0a 2a 2a  and UTF16..**.**
2e910 20 5e 42 75 69 6c 74 2d 69 6e 20 66 75 6e 63 74   ^Built-in funct
2e920 69 6f 6e 73 20 6d 61 79 20 62 65 20 6f 76 65 72  ions may be over
2e930 6c 6f 61 64 65 64 20 62 79 20 6e 65 77 20 61 70  loaded by new ap
2e940 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
2e950 64 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a  d functions..**.
2e960 2a 2a 20 5e 41 6e 20 61 70 70 6c 69 63 61 74 69  ** ^An applicati
2e970 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
2e980 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64  ion is permitted
2e990 20 74 6f 20 63 61 6c 6c 20 6f 74 68 65 72 0a 2a   to call other.*
2e9a0 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  * SQLite interfa
2e9b0 63 65 73 2e 20 20 48 6f 77 65 76 65 72 2c 20 73  ces.  However, s
2e9c0 75 63 68 20 63 61 6c 6c 73 20 6d 75 73 74 20 6e  uch calls must n
2e9d0 6f 74 0a 2a 2a 20 63 6c 6f 73 65 20 74 68 65 20  ot.** close the 
2e9e0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2e9f0 69 6f 6e 20 6e 6f 72 20 66 69 6e 61 6c 69 7a 65  ion nor finalize
2ea00 20 6f 72 20 72 65 73 65 74 20 74 68 65 20 70 72   or reset the pr
2ea10 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d  epared.** statem
2ea20 65 6e 74 20 69 6e 20 77 68 69 63 68 20 74 68 65  ent in which the
2ea30 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e   function is run
2ea40 6e 69 6e 67 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  ning..*/.int sql
2ea50 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2ea60 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 20  tion(.  sqlite3 
2ea70 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61  *db,.  const cha
2ea80 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65  r *zFunctionName
2ea90 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20  ,.  int nArg,.  
2eaa0 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20  int eTextRep,.  
2eab0 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f  void *pApp,.  vo
2eac0 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69  id (*xFunc)(sqli
2ead0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74  te3_context*,int
2eae0 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a  ,sqlite3_value**
2eaf0 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65  ),.  void (*xSte
2eb00 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  p)(sqlite3_conte
2eb10 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f  xt*,int,sqlite3_
2eb20 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64  value**),.  void
2eb30 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74   (*xFinal)(sqlit
2eb40 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a  e3_context*).);.
2eb50 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61  int sqlite3_crea
2eb60 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 0a 20  te_function16(. 
2eb70 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20   sqlite3 *db,.  
2eb80 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 46 75 6e  const void *zFun
2eb90 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74  ctionName,.  int
2eba0 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65   nArg,.  int eTe
2ebb0 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70  xtRep,.  void *p
2ebc0 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46  App,.  void (*xF
2ebd0 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  unc)(sqlite3_con
2ebe0 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
2ebf0 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f  3_value**),.  vo
2ec00 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69  id (*xStep)(sqli
2ec10 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74  te3_context*,int
2ec20 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a  ,sqlite3_value**
2ec30 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e  ),.  void (*xFin
2ec40 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  al)(sqlite3_cont
2ec50 65 78 74 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c  ext*).);.int sql
2ec60 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2ec70 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74  tion_v2(.  sqlit
2ec80 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20  e3 *db,.  const 
2ec90 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e  char *zFunctionN
2eca0 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c  ame,.  int nArg,
2ecb0 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c  .  int eTextRep,
2ecc0 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20  .  void *pApp,. 
2ecd0 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73   void (*xFunc)(s
2ece0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
2ecf0 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75  int,sqlite3_valu
2ed00 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78  e**),.  void (*x
2ed10 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f  Step)(sqlite3_co
2ed20 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74  ntext*,int,sqlit
2ed30 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76  e3_value**),.  v
2ed40 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71  oid (*xFinal)(sq
2ed50 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 2c  lite3_context*),
2ed60 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f  .  void(*xDestro
2ed70 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a  y)(void*).);../*
2ed80 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65  .** CAPI3REF: Te
2ed90 78 74 20 45 6e 63 6f 64 69 6e 67 73 0a 2a 2a 0a  xt Encodings.**.
2eda0 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
2edb0 74 20 64 65 66 69 6e 65 20 69 6e 74 65 67 65 72  t define integer
2edc0 20 63 6f 64 65 73 20 74 68 61 74 20 72 65 70 72   codes that repr
2edd0 65 73 65 6e 74 20 74 68 65 20 76 61 72 69 6f 75  esent the variou
2ede0 73 0a 2a 2a 20 74 65 78 74 20 65 6e 63 6f 64 69  s.** text encodi
2edf0 6e 67 73 20 73 75 70 70 6f 72 74 65 64 20 62 79  ngs supported by
2ee00 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66   SQLite..*/.#def
2ee10 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 38 20  ine SQLITE_UTF8 
2ee20 20 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66            1.#def
2ee30 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36  ine SQLITE_UTF16
2ee40 4c 45 20 20 20 20 20 20 20 20 32 0a 23 64 65 66  LE        2.#def
2ee50 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36  ine SQLITE_UTF16
2ee60 42 45 20 20 20 20 20 20 20 20 33 0a 23 64 65 66  BE        3.#def
2ee70 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36  ine SQLITE_UTF16
2ee80 20 20 20 20 20 20 20 20 20 20 34 20 20 20 20 2f            4    /
2ee90 2a 20 55 73 65 20 6e 61 74 69 76 65 20 62 79 74  * Use native byt
2eea0 65 20 6f 72 64 65 72 20 2a 2f 0a 23 64 65 66 69  e order */.#defi
2eeb0 6e 65 20 53 51 4c 49 54 45 5f 41 4e 59 20 20 20  ne SQLITE_ANY   
2eec0 20 20 20 20 20 20 20 20 20 35 20 20 20 20 2f 2a           5    /*
2eed0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
2eee0 66 75 6e 63 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f  function only */
2eef0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2ef00 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 20 20 38  UTF16_ALIGNED  8
2ef10 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63      /* sqlite3_c
2ef20 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20  reate_collation 
2ef30 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  only */../*.** C
2ef40 41 50 49 33 52 45 46 3a 20 44 65 70 72 65 63 61  API3REF: Depreca
2ef50 74 65 64 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a  ted Functions.**
2ef60 20 44 45 50 52 45 43 41 54 45 44 0a 2a 2a 0a 2a   DEPRECATED.**.*
2ef70 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  * These function
2ef80 73 20 61 72 65 20 5b 64 65 70 72 65 63 61 74 65  s are [deprecate
2ef90 64 5d 2e 20 20 49 6e 20 6f 72 64 65 72 20 74 6f  d].  In order to
2efa0 20 6d 61 69 6e 74 61 69 6e 0a 2a 2a 20 62 61 63   maintain.** bac
2efb0 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69  kwards compatibi
2efc0 6c 69 74 79 20 77 69 74 68 20 6f 6c 64 65 72 20  lity with older 
2efd0 63 6f 64 65 2c 20 74 68 65 73 65 20 66 75 6e 63  code, these func
2efe0 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20 0a  tions continue .
2eff0 2a 2a 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74  ** to be support
2f000 65 64 2e 20 20 48 6f 77 65 76 65 72 2c 20 6e 65  ed.  However, ne
2f010 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 73  w applications s
2f020 68 6f 75 6c 64 20 61 76 6f 69 64 0a 2a 2a 20 74  hould avoid.** t
2f030 68 65 20 75 73 65 20 6f 66 20 74 68 65 73 65 20  he use of these 
2f040 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 6f 20 68  functions.  To h
2f050 65 6c 70 20 65 6e 63 6f 75 72 61 67 65 20 70 65  elp encourage pe
2f060 6f 70 6c 65 20 74 6f 20 61 76 6f 69 64 0a 2a 2a  ople to avoid.**
2f070 20 75 73 69 6e 67 20 74 68 65 73 65 20 66 75 6e   using these fun
2f080 63 74 69 6f 6e 73 2c 20 77 65 20 61 72 65 20 6e  ctions, we are n
2f090 6f 74 20 67 6f 69 6e 67 20 74 6f 20 74 65 6c 6c  ot going to tell
2f0a0 20 79 6f 75 20 77 68 61 74 20 74 68 65 79 20 64   you what they d
2f0b0 6f 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51  o..*/.#ifndef SQ
2f0c0 4c 49 54 45 5f 4f 4d 49 54 5f 44 45 50 52 45 43  LITE_OMIT_DEPREC
2f0d0 41 54 45 44 0a 53 51 4c 49 54 45 5f 44 45 50 52  ATED.SQLITE_DEPR
2f0e0 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74  ECATED int sqlit
2f0f0 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 75  e3_aggregate_cou
2f100 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  nt(sqlite3_conte
2f110 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50  xt*);.SQLITE_DEP
2f120 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69  RECATED int sqli
2f130 74 65 33 5f 65 78 70 69 72 65 64 28 73 71 6c 69  te3_expired(sqli
2f140 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49  te3_stmt*);.SQLI
2f150 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e  TE_DEPRECATED in
2f160 74 20 73 71 6c 69 74 65 33 5f 74 72 61 6e 73 66  t sqlite3_transf
2f170 65 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69  er_bindings(sqli
2f180 74 65 33 5f 73 74 6d 74 2a 2c 20 73 71 6c 69 74  te3_stmt*, sqlit
2f190 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54  e3_stmt*);.SQLIT
2f1a0 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74  E_DEPRECATED int
2f1b0 20 73 71 6c 69 74 65 33 5f 67 6c 6f 62 61 6c 5f   sqlite3_global_
2f1c0 72 65 63 6f 76 65 72 28 76 6f 69 64 29 3b 0a 53  recover(void);.S
2f1d0 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
2f1e0 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 74 68   void sqlite3_th
2f1f0 72 65 61 64 5f 63 6c 65 61 6e 75 70 28 76 6f 69  read_cleanup(voi
2f200 64 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45  d);.SQLITE_DEPRE
2f210 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65  CATED int sqlite
2f220 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 76  3_memory_alarm(v
2f230 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c  oid(*)(void*,sql
2f240 69 74 65 33 5f 69 6e 74 36 34 2c 69 6e 74 29 2c  ite3_int64,int),
2f250 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e  void*,sqlite3_in
2f260 74 36 34 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a  t64);.#endif../*
2f270 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62  .** CAPI3REF: Ob
2f280 74 61 69 6e 69 6e 67 20 53 51 4c 20 46 75 6e 63  taining SQL Func
2f290 74 69 6f 6e 20 50 61 72 61 6d 65 74 65 72 20 56  tion Parameter V
2f2a0 61 6c 75 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20  alues.**.** The 
2f2b0 43 2d 6c 61 6e 67 75 61 67 65 20 69 6d 70 6c 65  C-language imple
2f2c0 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 53 51 4c  mentation of SQL
2f2d0 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61   functions and a
2f2e0 67 67 72 65 67 61 74 65 73 20 75 73 65 73 0a 2a  ggregates uses.*
2f2f0 2a 20 74 68 69 73 20 73 65 74 20 6f 66 20 69 6e  * this set of in
2f300 74 65 72 66 61 63 65 20 72 6f 75 74 69 6e 65 73  terface routines
2f310 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 70   to access the p
2f320 61 72 61 6d 65 74 65 72 20 76 61 6c 75 65 73 20  arameter values 
2f330 6f 6e 0a 2a 2a 20 74 68 65 20 66 75 6e 63 74 69  on.** the functi
2f340 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 2e  on or aggregate.
2f350 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 75 6e 63  .**.** The xFunc
2f360 20 28 66 6f 72 20 73 63 61 6c 61 72 20 66 75 6e   (for scalar fun
2f370 63 74 69 6f 6e 73 29 20 6f 72 20 78 53 74 65 70  ctions) or xStep
2f380 20 28 66 6f 72 20 61 67 67 72 65 67 61 74 65 73   (for aggregates
2f390 29 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20  ) parameters.** 
2f3a0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  to [sqlite3_crea
2f3b0 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61  te_function()] a
2f3c0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  nd [sqlite3_crea
2f3d0 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d  te_function16()]
2f3e0 0a 2a 2a 20 64 65 66 69 6e 65 20 63 61 6c 6c 62  .** define callb
2f3f0 61 63 6b 73 20 74 68 61 74 20 69 6d 70 6c 65 6d  acks that implem
2f400 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63  ent the SQL func
2f410 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67  tions and aggreg
2f420 61 74 65 73 2e 0a 2a 2a 20 54 68 65 20 33 72 64  ates..** The 3rd
2f430 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
2f440 65 73 65 20 63 61 6c 6c 62 61 63 6b 73 20 69 73  ese callbacks is
2f450 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69   an array of poi
2f460 6e 74 65 72 73 20 74 6f 0a 2a 2a 20 5b 70 72 6f  nters to.** [pro
2f470 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2f480 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 20 20  alue] objects.  
2f490 54 68 65 72 65 20 69 73 20 6f 6e 65 20 5b 73 71  There is one [sq
2f4a0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
2f4b0 65 63 74 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20  ect for.** each 
2f4c0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
2f4d0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 20 20   SQL function.  
2f4e0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
2f4f0 72 65 20 75 73 65 64 20 74 6f 0a 2a 2a 20 65 78  re used to.** ex
2f500 74 72 61 63 74 20 76 61 6c 75 65 73 20 66 72 6f  tract values fro
2f510 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  m the [sqlite3_v
2f520 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a  alue] objects..*
2f530 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
2f540 6e 65 73 20 77 6f 72 6b 20 6f 6e 6c 79 20 77 69  nes work only wi
2f550 74 68 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71  th [protected sq
2f560 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
2f570 65 63 74 73 2e 0a 2a 2a 20 41 6e 79 20 61 74 74  ects..** Any att
2f580 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65 73  empt to use thes
2f590 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 20 61 6e  e routines on an
2f5a0 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71   [unprotected sq
2f5b0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20  lite3_value].** 
2f5c0 6f 62 6a 65 63 74 20 72 65 73 75 6c 74 73 20 69  object results i
2f5d0 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61  n undefined beha
2f5e0 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  vior..**.** ^The
2f5f0 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b  se routines work
2f600 20 6a 75 73 74 20 6c 69 6b 65 20 74 68 65 20 63   just like the c
2f610 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 5b 63 6f  orresponding [co
2f620 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63  lumn access func
2f630 74 69 6f 6e 73 5d 0a 2a 2a 20 65 78 63 65 70 74  tions].** except
2f640 20 74 68 61 74 20 20 74 68 65 73 65 20 72 6f 75   that  these rou
2f650 74 69 6e 65 73 20 74 61 6b 65 20 61 20 73 69 6e  tines take a sin
2f660 67 6c 65 20 5b 70 72 6f 74 65 63 74 65 64 20 73  gle [protected s
2f670 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
2f680 6a 65 63 74 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  ject.** pointer 
2f690 69 6e 73 74 65 61 64 20 6f 66 20 61 20 5b 73 71  instead of a [sq
2f6a0 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 20 70 6f 69  lite3_stmt*] poi
2f6b0 6e 74 65 72 20 61 6e 64 20 61 6e 20 69 6e 74 65  nter and an inte
2f6c0 67 65 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65  ger column numbe
2f6d0 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  r..**.** ^The sq
2f6e0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
2f6f0 31 36 28 29 20 69 6e 74 65 72 66 61 63 65 20 65  16() interface e
2f700 78 74 72 61 63 74 73 20 61 20 55 54 46 2d 31 36  xtracts a UTF-16
2f710 20 73 74 72 69 6e 67 0a 2a 2a 20 69 6e 20 74 68   string.** in th
2f720 65 20 6e 61 74 69 76 65 20 62 79 74 65 2d 6f 72  e native byte-or
2f730 64 65 72 20 6f 66 20 74 68 65 20 68 6f 73 74 20  der of the host 
2f740 6d 61 63 68 69 6e 65 2e 20 20 5e 54 68 65 0a 2a  machine.  ^The.*
2f750 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  * sqlite3_value_
2f760 74 65 78 74 31 36 62 65 28 29 20 61 6e 64 20 73  text16be() and s
2f770 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
2f780 74 31 36 6c 65 28 29 20 69 6e 74 65 72 66 61 63  t16le() interfac
2f790 65 73 0a 2a 2a 20 65 78 74 72 61 63 74 20 55 54  es.** extract UT
2f7a0 46 2d 31 36 20 73 74 72 69 6e 67 73 20 61 73 20  F-16 strings as 
2f7b0 62 69 67 2d 65 6e 64 69 61 6e 20 61 6e 64 20 6c  big-endian and l
2f7c0 69 74 74 6c 65 2d 65 6e 64 69 61 6e 20 72 65 73  ittle-endian res
2f7d0 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a  pectively..**.**
2f7e0 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f 76   ^(The sqlite3_v
2f7f0 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70  alue_numeric_typ
2f800 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 61 74  e() interface at
2f810 74 65 6d 70 74 73 20 74 6f 20 61 70 70 6c 79 0a  tempts to apply.
2f820 2a 2a 20 6e 75 6d 65 72 69 63 20 61 66 66 69 6e  ** numeric affin
2f830 69 74 79 20 74 6f 20 74 68 65 20 76 61 6c 75 65  ity to the value
2f840 2e 20 20 54 68 69 73 20 6d 65 61 6e 73 20 74 68  .  This means th
2f850 61 74 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73  at an attempt is
2f860 0a 2a 2a 20 6d 61 64 65 20 74 6f 20 63 6f 6e 76  .** made to conv
2f870 65 72 74 20 74 68 65 20 76 61 6c 75 65 20 74 6f  ert the value to
2f880 20 61 6e 20 69 6e 74 65 67 65 72 20 6f 72 20 66   an integer or f
2f890 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 2e 20 20  loating point.  
2f8a0 49 66 0a 2a 2a 20 73 75 63 68 20 61 20 63 6f 6e  If.** such a con
2f8b0 76 65 72 73 69 6f 6e 20 69 73 20 70 6f 73 73 69  version is possi
2f8c0 62 6c 65 20 77 69 74 68 6f 75 74 20 6c 6f 73 73  ble without loss
2f8d0 20 6f 66 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20   of information 
2f8e0 28 69 6e 20 6f 74 68 65 72 0a 2a 2a 20 77 6f 72  (in other.** wor
2f8f0 64 73 2c 20 69 66 20 74 68 65 20 76 61 6c 75 65  ds, if the value
2f900 20 69 73 20 61 20 73 74 72 69 6e 67 20 74 68 61   is a string tha
2f910 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61 20 6e  t looks like a n
2f920 75 6d 62 65 72 29 0a 2a 2a 20 74 68 65 6e 20 74  umber).** then t
2f930 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73  he conversion is
2f940 20 70 65 72 66 6f 72 6d 65 64 2e 20 20 4f 74 68   performed.  Oth
2f950 65 72 77 69 73 65 20 6e 6f 20 63 6f 6e 76 65 72  erwise no conver
2f960 73 69 6f 6e 20 6f 63 63 75 72 73 2e 0a 2a 2a 20  sion occurs..** 
2f970 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45  The [SQLITE_INTE
2f980 47 45 52 20 7c 20 64 61 74 61 74 79 70 65 5d 20  GER | datatype] 
2f990 61 66 74 65 72 20 63 6f 6e 76 65 72 73 69 6f 6e  after conversion
2f9a0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 0a   is returned.)^.
2f9b0 2a 2a 0a 2a 2a 20 50 6c 65 61 73 65 20 70 61 79  **.** Please pay
2f9c0 20 70 61 72 74 69 63 75 6c 61 72 20 61 74 74 65   particular atte
2f9d0 6e 74 69 6f 6e 20 74 6f 20 74 68 65 20 66 61 63  ntion to the fac
2f9e0 74 20 74 68 61 74 20 74 68 65 20 70 6f 69 6e 74  t that the point
2f9f0 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66  er returned.** f
2fa00 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  rom [sqlite3_val
2fa10 75 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c  ue_blob()], [sql
2fa20 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28  ite3_value_text(
2fa30 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  )], or.** [sqlit
2fa40 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28  e3_value_text16(
2fa50 29 5d 20 63 61 6e 20 62 65 20 69 6e 76 61 6c 69  )] can be invali
2fa60 64 61 74 65 64 20 62 79 20 61 20 73 75 62 73 65  dated by a subse
2fa70 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a  quent call to.**
2fa80 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
2fa90 62 79 74 65 73 28 29 5d 2c 20 5b 73 71 6c 69 74  bytes()], [sqlit
2faa0 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36  e3_value_bytes16
2fab0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61  ()], [sqlite3_va
2fac0 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20  lue_text()],.** 
2fad0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  or [sqlite3_valu
2fae0 65 5f 74 65 78 74 31 36 28 29 5d 2e 0a 2a 2a 0a  e_text16()]..**.
2faf0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
2fb00 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64  s must be called
2fb10 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74   from the same t
2fb20 68 72 65 61 64 20 61 73 0a 2a 2a 20 74 68 65 20  hread as.** the 
2fb30 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 68 61  SQL function tha
2fb40 74 20 73 75 70 70 6c 69 65 64 20 74 68 65 20 5b  t supplied the [
2fb50 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 5d 20  sqlite3_value*] 
2fb60 70 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2f 0a 63  parameters..*/.c
2fb70 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
2fb80 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 73 71  e3_value_blob(sq
2fb90 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69  lite3_value*);.i
2fba0 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt sqlite3_value
2fbb0 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f 76  _bytes(sqlite3_v
2fbc0 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69  alue*);.int sqli
2fbd0 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31  te3_value_bytes1
2fbe0 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  6(sqlite3_value*
2fbf0 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74 65  );.double sqlite
2fc00 33 5f 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28 73  3_value_double(s
2fc10 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
2fc20 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  int sqlite3_valu
2fc30 65 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 76 61  e_int(sqlite3_va
2fc40 6c 75 65 2a 29 3b 0a 73 71 6c 69 74 65 33 5f 69  lue*);.sqlite3_i
2fc50 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 76 61 6c  nt64 sqlite3_val
2fc60 75 65 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33  ue_int64(sqlite3
2fc70 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20  _value*);.const 
2fc80 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73  unsigned char *s
2fc90 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
2fca0 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t(sqlite3_value*
2fcb0 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
2fcc0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
2fcd0 74 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  t16(sqlite3_valu
2fce0 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  e*);.const void 
2fcf0 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  *sqlite3_value_t
2fd00 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f  ext16le(sqlite3_
2fd10 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76  value*);.const v
2fd20 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c  oid *sqlite3_val
2fd30 75 65 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69  ue_text16be(sqli
2fd40 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74  te3_value*);.int
2fd50 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
2fd60 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  ype(sqlite3_valu
2fd70 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  e*);.int sqlite3
2fd80 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74  _value_numeric_t
2fd90 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  ype(sqlite3_valu
2fda0 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  e*);../*.** CAPI
2fdb0 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 41 67 67  3REF: Obtain Agg
2fdc0 72 65 67 61 74 65 20 46 75 6e 63 74 69 6f 6e 20  regate Function 
2fdd0 43 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 49 6d  Context.**.** Im
2fde0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66  plementations of
2fdf0 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66   aggregate SQL f
2fe00 75 6e 63 74 69 6f 6e 73 20 75 73 65 20 74 68 69  unctions use thi
2fe10 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 74 6f 20  s.** routine to 
2fe20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20  allocate memory 
2fe30 66 6f 72 20 73 74 6f 72 69 6e 67 20 74 68 65 69  for storing thei
2fe40 72 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e  r state..**.** ^
2fe50 54 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 74  The first time t
2fe60 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  he sqlite3_aggre
2fe70 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e  gate_context(C,N
2fe80 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c  ) routine is cal
2fe90 6c 65 64 20 0a 2a 2a 20 66 6f 72 20 61 20 70 61  led .** for a pa
2fea0 72 74 69 63 75 6c 61 72 20 61 67 67 72 65 67 61  rticular aggrega
2feb0 74 65 20 66 75 6e 63 74 69 6f 6e 2c 20 53 51 4c  te function, SQL
2fec0 69 74 65 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 73  ite.** allocates
2fed0 20 4e 20 6f 66 20 6d 65 6d 6f 72 79 2c 20 7a 65   N of memory, ze
2fee0 72 6f 65 73 20 6f 75 74 20 74 68 61 74 20 6d 65  roes out that me
2fef0 6d 6f 72 79 2c 20 61 6e 64 20 72 65 74 75 72 6e  mory, and return
2ff00 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74  s a pointer.** t
2ff10 6f 20 74 68 65 20 6e 65 77 20 6d 65 6d 6f 72 79  o the new memory
2ff20 2e 20 5e 4f 6e 20 73 65 63 6f 6e 64 20 61 6e 64  . ^On second and
2ff30 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   subsequent call
2ff40 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  s to.** sqlite3_
2ff50 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
2ff60 74 28 29 20 66 6f 72 20 74 68 65 20 73 61 6d 65  t() for the same
2ff70 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74   aggregate funct
2ff80 69 6f 6e 20 69 6e 73 74 61 6e 63 65 2c 0a 2a 2a  ion instance,.**
2ff90 20 74 68 65 20 73 61 6d 65 20 62 75 66 66 65 72   the same buffer
2ffa0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 53   is returned.  S
2ffb0 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
2ffc0 5f 63 6f 6e 74 65 78 74 28 29 20 69 73 20 6e 6f  _context() is no
2ffd0 72 6d 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64  rmally.** called
2ffe0 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 20 69   once for each i
2fff0 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 74 68 65  nvocation of the
30000 20 78 53 74 65 70 20 63 61 6c 6c 62 61 63 6b 20   xStep callback 
30010 61 6e 64 20 74 68 65 6e 20 6f 6e 65 0a 2a 2a 20  and then one.** 
30020 6c 61 73 74 20 74 69 6d 65 20 77 68 65 6e 20 74  last time when t
30030 68 65 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61  he xFinal callba
30040 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20  ck is invoked.  
30050 5e 28 57 68 65 6e 20 6e 6f 20 72 6f 77 73 20 6d  ^(When no rows m
30060 61 74 63 68 0a 2a 2a 20 61 6e 20 61 67 67 72 65  atch.** an aggre
30070 67 61 74 65 20 71 75 65 72 79 2c 20 74 68 65 20  gate query, the 
30080 78 53 74 65 70 28 29 20 63 61 6c 6c 62 61 63 6b  xStep() callback
30090 20 6f 66 20 74 68 65 20 61 67 67 72 65 67 61 74   of the aggregat
300a0 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 69 6d  e function.** im
300b0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20  plementation is 
300c0 6e 65 76 65 72 20 63 61 6c 6c 65 64 20 61 6e 64  never called and
300d0 20 78 46 69 6e 61 6c 28 29 20 69 73 20 63 61 6c   xFinal() is cal
300e0 6c 65 64 20 65 78 61 63 74 6c 79 20 6f 6e 63 65  led exactly once
300f0 2e 0a 2a 2a 20 49 6e 20 74 68 6f 73 65 20 63 61  ..** In those ca
30100 73 65 73 2c 20 73 71 6c 69 74 65 33 5f 61 67 67  ses, sqlite3_agg
30110 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29  regate_context()
30120 20 6d 69 67 68 74 20 62 65 20 63 61 6c 6c 65 64   might be called
30130 20 66 6f 72 20 74 68 65 0a 2a 2a 20 66 69 72 73   for the.** firs
30140 74 20 74 69 6d 65 20 66 72 6f 6d 20 77 69 74 68  t time from with
30150 69 6e 20 78 46 69 6e 61 6c 28 29 2e 29 5e 0a 2a  in xFinal().)^.*
30160 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
30170 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
30180 65 78 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e 65  ext(C,N) routine
30190 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20   returns a NULL 
301a0 70 6f 69 6e 74 65 72 20 69 66 20 4e 20 69 73 0a  pointer if N is.
301b0 2a 2a 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20  ** less than or 
301c0 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 20 6f 72  equal to zero or
301d0 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c   if a memory all
301e0 6f 63 61 74 65 20 65 72 72 6f 72 20 6f 63 63 75  ocate error occu
301f0 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  rs..**.** ^(The 
30200 61 6d 6f 75 6e 74 20 6f 66 20 73 70 61 63 65 20  amount of space 
30210 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c  allocated by sql
30220 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
30230 6f 6e 74 65 78 74 28 43 2c 4e 29 20 69 73 0a 2a  ontext(C,N) is.*
30240 2a 20 64 65 74 65 72 6d 69 6e 65 64 20 62 79 20  * determined by 
30250 74 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20  the N parameter 
30260 6f 6e 20 66 69 72 73 74 20 73 75 63 63 65 73 73  on first success
30270 66 75 6c 20 63 61 6c 6c 2e 20 20 43 68 61 6e 67  ful call.  Chang
30280 69 6e 67 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65  ing the.** value
30290 20 6f 66 20 4e 20 69 6e 20 73 75 62 73 65 71 75   of N in subsequ
302a0 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  ent call to sqli
302b0 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
302c0 6e 74 65 78 74 28 29 20 77 69 74 68 69 6e 0a 2a  ntext() within.*
302d0 2a 20 74 68 65 20 73 61 6d 65 20 61 67 67 72 65  * the same aggre
302e0 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e  gate function in
302f0 73 74 61 6e 63 65 20 77 69 6c 6c 20 6e 6f 74 20  stance will not 
30300 72 65 73 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72  resize the memor
30310 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 2e  y.** allocation.
30320 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65  )^.**.** ^SQLite
30330 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 66   automatically f
30340 72 65 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20  rees the memory 
30350 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 0a 2a 2a  allocated by .**
30360 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
30370 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 77 68 65  te_context() whe
30380 6e 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20  n the aggregate 
30390 71 75 65 72 79 20 63 6f 6e 63 6c 75 64 65 73 2e  query concludes.
303a0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  .**.** The first
303b0 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74 20   parameter must 
303c0 62 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  be a copy of the
303d0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
303e0 74 65 78 74 20 7c 20 53 51 4c 20 66 75 6e 63 74  text | SQL funct
303f0 69 6f 6e 20 63 6f 6e 74 65 78 74 5d 20 74 68 61  ion context] tha
30400 74 20 69 73 20 74 68 65 20 66 69 72 73 74 20 70  t is the first p
30410 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74  arameter.** to t
30420 68 65 20 78 53 74 65 70 20 6f 72 20 78 46 69 6e  he xStep or xFin
30430 61 6c 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74  al callback rout
30440 69 6e 65 20 74 68 61 74 20 69 6d 70 6c 65 6d 65  ine that impleme
30450 6e 74 73 20 74 68 65 20 61 67 67 72 65 67 61 74  nts the aggregat
30460 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a  e.** function..*
30470 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e  *.** This routin
30480 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64  e must be called
30490 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74   from the same t
304a0 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a  hread in which.*
304b0 2a 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20  * the aggregate 
304c0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  SQL function is 
304d0 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64  running..*/.void
304e0 20 2a 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67   *sqlite3_aggreg
304f0 61 74 65 5f 63 6f 6e 74 65 78 74 28 73 71 6c 69  ate_context(sqli
30500 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
30510 74 20 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a 2a  t nBytes);../*.*
30520 2a 20 43 41 50 49 33 52 45 46 3a 20 55 73 65 72  * CAPI3REF: User
30530 20 44 61 74 61 20 46 6f 72 20 46 75 6e 63 74 69   Data For Functi
30540 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ons.**.** ^The s
30550 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61  qlite3_user_data
30560 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  () interface ret
30570 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a  urns a copy of.*
30580 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74 68  * the pointer th
30590 61 74 20 77 61 73 20 74 68 65 20 70 55 73 65 72  at was the pUser
305a0 44 61 74 61 20 70 61 72 61 6d 65 74 65 72 20 28  Data parameter (
305b0 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65  the 5th paramete
305c0 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71  r).** of the [sq
305d0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
305e0 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20  ction()].** and 
305f0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
30600 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f  function16()] ro
30610 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67  utines that orig
30620 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74  inally.** regist
30630 65 72 65 64 20 74 68 65 20 61 70 70 6c 69 63 61  ered the applica
30640 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e  tion defined fun
30650 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  ction..**.** Thi
30660 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62  s routine must b
30670 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68  e called from th
30680 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e  e same thread in
30690 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 70   which.** the ap
306a0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
306b0 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75  d function is ru
306c0 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a  nning..*/.void *
306d0 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74  sqlite3_user_dat
306e0 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  a(sqlite3_contex
306f0 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
30700 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 43  3REF: Database C
30710 6f 6e 6e 65 63 74 69 6f 6e 20 46 6f 72 20 46 75  onnection For Fu
30720 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54  nctions.**.** ^T
30730 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  he sqlite3_conte
30740 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 20 69  xt_db_handle() i
30750 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
30760 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68   a copy of.** th
30770 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  e pointer to the
30780 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
30790 63 74 69 6f 6e 5d 20 28 74 68 65 20 31 73 74 20  ction] (the 1st 
307a0 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66  parameter).** of
307b0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72   the [sqlite3_cr
307c0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d  eate_function()]
307d0 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  .** and [sqlite3
307e0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
307f0 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74  16()] routines t
30800 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a  hat originally.*
30810 2a 20 72 65 67 69 73 74 65 72 65 64 20 74 68 65  * registered the
30820 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66   application def
30830 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a  ined function..*
30840 2f 0a 73 71 6c 69 74 65 33 20 2a 73 71 6c 69 74  /.sqlite3 *sqlit
30850 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61  e3_context_db_ha
30860 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e  ndle(sqlite3_con
30870 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  text*);../*.** C
30880 41 50 49 33 52 45 46 3a 20 46 75 6e 63 74 69 6f  API3REF: Functio
30890 6e 20 41 75 78 69 6c 69 61 72 79 20 44 61 74 61  n Auxiliary Data
308a0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f  .**.** The follo
308b0 77 69 6e 67 20 74 77 6f 20 66 75 6e 63 74 69 6f  wing two functio
308c0 6e 73 20 6d 61 79 20 62 65 20 75 73 65 64 20 62  ns may be used b
308d0 79 20 73 63 61 6c 61 72 20 53 51 4c 20 66 75 6e  y scalar SQL fun
308e0 63 74 69 6f 6e 73 20 74 6f 0a 2a 2a 20 61 73 73  ctions to.** ass
308f0 6f 63 69 61 74 65 20 6d 65 74 61 64 61 74 61 20  ociate metadata 
30900 77 69 74 68 20 61 72 67 75 6d 65 6e 74 20 76 61  with argument va
30910 6c 75 65 73 2e 20 49 66 20 74 68 65 20 73 61 6d  lues. If the sam
30920 65 20 76 61 6c 75 65 20 69 73 20 70 61 73 73 65  e value is passe
30930 64 20 74 6f 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65  d to.** multiple
30940 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20   invocations of 
30950 74 68 65 20 73 61 6d 65 20 53 51 4c 20 66 75 6e  the same SQL fun
30960 63 74 69 6f 6e 20 64 75 72 69 6e 67 20 71 75 65  ction during que
30970 72 79 20 65 78 65 63 75 74 69 6f 6e 2c 20 75 6e  ry execution, un
30980 64 65 72 0a 2a 2a 20 73 6f 6d 65 20 63 69 72 63  der.** some circ
30990 75 6d 73 74 61 6e 63 65 73 20 74 68 65 20 61 73  umstances the as
309a0 73 6f 63 69 61 74 65 64 20 6d 65 74 61 64 61 74  sociated metadat
309b0 61 20 6d 61 79 20 62 65 20 70 72 65 73 65 72 76  a may be preserv
309c0 65 64 2e 20 54 68 69 73 20 6d 61 79 0a 2a 2a 20  ed. This may.** 
309d0 62 65 20 75 73 65 64 2c 20 66 6f 72 20 65 78 61  be used, for exa
309e0 6d 70 6c 65 2c 20 74 6f 20 61 64 64 20 61 20 72  mple, to add a r
309f0 65 67 75 6c 61 72 2d 65 78 70 72 65 73 73 69 6f  egular-expressio
30a00 6e 20 6d 61 74 63 68 69 6e 67 20 73 63 61 6c 61  n matching scala
30a10 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 20 54  r.** function. T
30a20 68 65 20 63 6f 6d 70 69 6c 65 64 20 76 65 72 73  he compiled vers
30a30 69 6f 6e 20 6f 66 20 74 68 65 20 72 65 67 75 6c  ion of the regul
30a40 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20 69 73  ar expression is
30a50 20 73 74 6f 72 65 64 20 61 73 0a 2a 2a 20 6d 65   stored as.** me
30a60 74 61 64 61 74 61 20 61 73 73 6f 63 69 61 74 65  tadata associate
30a70 64 20 77 69 74 68 20 74 68 65 20 53 51 4c 20 76  d with the SQL v
30a80 61 6c 75 65 20 70 61 73 73 65 64 20 61 73 20 74  alue passed as t
30a90 68 65 20 72 65 67 75 6c 61 72 20 65 78 70 72 65  he regular expre
30aa0 73 73 69 6f 6e 0a 2a 2a 20 70 61 74 74 65 72 6e  ssion.** pattern
30ab0 2e 20 20 54 68 65 20 63 6f 6d 70 69 6c 65 64 20  .  The compiled 
30ac0 72 65 67 75 6c 61 72 20 65 78 70 72 65 73 73 69  regular expressi
30ad0 6f 6e 20 63 61 6e 20 62 65 20 72 65 75 73 65 64  on can be reused
30ae0 20 6f 6e 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20   on multiple.** 
30af0 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74  invocations of t
30b00 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e  he same function
30b10 20 73 6f 20 74 68 61 74 20 74 68 65 20 6f 72 69   so that the ori
30b20 67 69 6e 61 6c 20 70 61 74 74 65 72 6e 20 73 74  ginal pattern st
30b30 72 69 6e 67 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74  ring.** does not
30b40 20 6e 65 65 64 20 74 6f 20 62 65 20 72 65 63 6f   need to be reco
30b50 6d 70 69 6c 65 64 20 6f 6e 20 65 61 63 68 20 69  mpiled on each i
30b60 6e 76 6f 63 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  nvocation..**.**
30b70 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65   ^The sqlite3_ge
30b80 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74 65  t_auxdata() inte
30b90 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
30ba0 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d  pointer to the m
30bb0 65 74 61 64 61 74 61 0a 2a 2a 20 61 73 73 6f 63  etadata.** assoc
30bc0 69 61 74 65 64 20 62 79 20 74 68 65 20 73 71 6c  iated by the sql
30bd0 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
30be0 28 29 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68  () function with
30bf0 20 74 68 65 20 4e 74 68 20 61 72 67 75 6d 65 6e   the Nth argumen
30c00 74 0a 2a 2a 20 76 61 6c 75 65 20 74 6f 20 74 68  t.** value to th
30c10 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
30c20 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20  fined function. 
30c30 5e 49 66 20 6e 6f 20 6d 65 74 61 64 61 74 61 20  ^If no metadata 
30c40 68 61 73 20 62 65 65 6e 20 65 76 65 72 0a 2a 2a  has been ever.**
30c50 20 62 65 65 6e 20 73 65 74 20 66 6f 72 20 74 68   been set for th
30c60 65 20 4e 74 68 20 61 72 67 75 6d 65 6e 74 20 6f  e Nth argument o
30c70 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 2c 20  f the function, 
30c80 6f 72 20 69 66 20 74 68 65 20 63 6f 72 72 65 73  or if the corres
30c90 70 6f 6e 64 69 6e 67 0a 2a 2a 20 66 75 6e 63 74  ponding.** funct
30ca0 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 20 68 61  ion parameter ha
30cb0 73 20 63 68 61 6e 67 65 64 20 73 69 6e 63 65 20  s changed since 
30cc0 74 68 65 20 6d 65 74 61 2d 64 61 74 61 20 77 61  the meta-data wa
30cd0 73 20 73 65 74 2c 0a 2a 2a 20 74 68 65 6e 20 73  s set,.** then s
30ce0 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61  qlite3_get_auxda
30cf0 74 61 28 29 20 72 65 74 75 72 6e 73 20 61 20 4e  ta() returns a N
30d00 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ULL pointer..**.
30d10 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
30d20 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e  set_auxdata() in
30d30 74 65 72 66 61 63 65 20 73 61 76 65 73 20 74 68  terface saves th
30d40 65 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 70 6f  e metadata.** po
30d50 69 6e 74 65 64 20 74 6f 20 62 79 20 69 74 73 20  inted to by its 
30d60 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 61 73  3rd parameter as
30d70 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 66 6f   the metadata fo
30d80 72 20 74 68 65 20 4e 2d 74 68 0a 2a 2a 20 61 72  r the N-th.** ar
30d90 67 75 6d 65 6e 74 20 6f 66 20 74 68 65 20 61 70  gument of the ap
30da0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
30db0 64 20 66 75 6e 63 74 69 6f 6e 2e 20 20 53 75 62  d function.  Sub
30dc0 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73  sequent.** calls
30dd0 20 74 6f 20 73 71 6c 69 74 65 33 5f 67 65 74 5f   to sqlite3_get_
30de0 61 75 78 64 61 74 61 28 29 20 6d 69 67 68 74 20  auxdata() might 
30df0 72 65 74 75 72 6e 20 74 68 69 73 20 64 61 74 61  return this data
30e00 2c 20 69 66 20 69 74 20 68 61 73 0a 2a 2a 20 6e  , if it has.** n
30e10 6f 74 20 62 65 65 6e 20 64 65 73 74 72 6f 79 65  ot been destroye
30e20 64 2e 0a 2a 2a 20 5e 49 66 20 69 74 20 69 73 20  d..** ^If it is 
30e30 6e 6f 74 20 4e 55 4c 4c 2c 20 53 51 4c 69 74 65  not NULL, SQLite
30e40 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65   will invoke the
30e50 20 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 66   destructor.** f
30e60 75 6e 63 74 69 6f 6e 20 67 69 76 65 6e 20 62 79  unction given by
30e70 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74   the 4th paramet
30e80 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65  er to sqlite3_se
30e90 74 5f 61 75 78 64 61 74 61 28 29 20 6f 6e 0a 2a  t_auxdata() on.*
30ea0 2a 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 77  * the metadata w
30eb0 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f  hen the correspo
30ec0 6e 64 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 70  nding function p
30ed0 61 72 61 6d 65 74 65 72 20 63 68 61 6e 67 65 73  arameter changes
30ee0 0a 2a 2a 20 6f 72 20 77 68 65 6e 20 74 68 65 20  .** or when the 
30ef0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f  SQL statement co
30f00 6d 70 6c 65 74 65 73 2c 20 77 68 69 63 68 65 76  mpletes, whichev
30f10 65 72 20 63 6f 6d 65 73 20 66 69 72 73 74 2e 0a  er comes first..
30f20 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69 73 20  **.** SQLite is 
30f30 66 72 65 65 20 74 6f 20 63 61 6c 6c 20 74 68 65  free to call the
30f40 20 64 65 73 74 72 75 63 74 6f 72 20 61 6e 64 20   destructor and 
30f50 64 72 6f 70 20 6d 65 74 61 64 61 74 61 20 6f 6e  drop metadata on
30f60 20 61 6e 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65   any.** paramete
30f70 72 20 6f 66 20 61 6e 79 20 66 75 6e 63 74 69 6f  r of any functio
30f80 6e 20 61 74 20 61 6e 79 20 74 69 6d 65 2e 20 20  n at any time.  
30f90 5e 54 68 65 20 6f 6e 6c 79 20 67 75 61 72 61 6e  ^The only guaran
30fa0 74 65 65 20 69 73 20 74 68 61 74 0a 2a 2a 20 74  tee is that.** t
30fb0 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 77 69  he destructor wi
30fc0 6c 6c 20 62 65 20 63 61 6c 6c 65 64 20 62 65 66  ll be called bef
30fd0 6f 72 65 20 74 68 65 20 6d 65 74 61 64 61 74 61  ore the metadata
30fe0 20 69 73 20 64 72 6f 70 70 65 64 2e 0a 2a 2a 0a   is dropped..**.
30ff0 2a 2a 20 5e 28 49 6e 20 70 72 61 63 74 69 63 65  ** ^(In practice
31000 2c 20 6d 65 74 61 64 61 74 61 20 69 73 20 70 72  , metadata is pr
31010 65 73 65 72 76 65 64 20 62 65 74 77 65 65 6e 20  eserved between 
31020 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 73 20 66  function calls f
31030 6f 72 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e  or.** expression
31040 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e 73 74  s that are const
31050 61 6e 74 20 61 74 20 63 6f 6d 70 69 6c 65 20 74  ant at compile t
31060 69 6d 65 2e 20 54 68 69 73 20 69 6e 63 6c 75 64  ime. This includ
31070 65 73 20 6c 69 74 65 72 61 6c 0a 2a 2a 20 76 61  es literal.** va
31080 6c 75 65 73 20 61 6e 64 20 5b 70 61 72 61 6d 65  lues and [parame
31090 74 65 72 73 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54  ters].)^.**.** T
310a0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75  hese routines mu
310b0 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f  st be called fro
310c0 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61  m the same threa
310d0 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68  d in which.** th
310e0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69  e SQL function i
310f0 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f  s running..*/.vo
31100 69 64 20 2a 73 71 6c 69 74 65 33 5f 67 65 74 5f  id *sqlite3_get_
31110 61 75 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f  auxdata(sqlite3_
31120 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 29  context*, int N)
31130 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 73  ;.void sqlite3_s
31140 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74  et_auxdata(sqlit
31150 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74  e3_context*, int
31160 20 4e 2c 20 76 6f 69 64 2a 2c 20 76 6f 69 64 20   N, void*, void 
31170 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 0a 0a 2f  (*)(void*));.../
31180 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
31190 6f 6e 73 74 61 6e 74 73 20 44 65 66 69 6e 69 6e  onstants Definin
311a0 67 20 53 70 65 63 69 61 6c 20 44 65 73 74 72 75  g Special Destru
311b0 63 74 6f 72 20 42 65 68 61 76 69 6f 72 0a 2a 2a  ctor Behavior.**
311c0 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20 73 70  .** These are sp
311d0 65 63 69 61 6c 20 76 61 6c 75 65 73 20 66 6f 72  ecial values for
311e0 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20   the destructor 
311f0 74 68 61 74 20 69 73 20 70 61 73 73 65 64 20 69  that is passed i
31200 6e 20 61 73 20 74 68 65 0a 2a 2a 20 66 69 6e 61  n as the.** fina
31210 6c 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 72 6f  l argument to ro
31220 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c  utines like [sql
31230 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62  ite3_result_blob
31240 28 29 5d 2e 20 20 5e 49 66 20 74 68 65 20 64 65  ()].  ^If the de
31250 73 74 72 75 63 74 6f 72 0a 2a 2a 20 61 72 67 75  structor.** argu
31260 6d 65 6e 74 20 69 73 20 53 51 4c 49 54 45 5f 53  ment is SQLITE_S
31270 54 41 54 49 43 2c 20 69 74 20 6d 65 61 6e 73 20  TATIC, it means 
31280 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74  that the content
31290 20 70 6f 69 6e 74 65 72 20 69 73 20 63 6f 6e 73   pointer is cons
312a0 74 61 6e 74 0a 2a 2a 20 61 6e 64 20 77 69 6c 6c  tant.** and will
312b0 20 6e 65 76 65 72 20 63 68 61 6e 67 65 2e 20 20   never change.  
312c0 49 74 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64  It does not need
312d0 20 74 6f 20 62 65 20 64 65 73 74 72 6f 79 65 64   to be destroyed
312e0 2e 20 20 5e 54 68 65 0a 2a 2a 20 53 51 4c 49 54  .  ^The.** SQLIT
312f0 45 5f 54 52 41 4e 53 49 45 4e 54 20 76 61 6c 75  E_TRANSIENT valu
31300 65 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  e means that the
31310 20 63 6f 6e 74 65 6e 74 20 77 69 6c 6c 20 6c 69   content will li
31320 6b 65 6c 79 20 63 68 61 6e 67 65 20 69 6e 0a 2a  kely change in.*
31330 2a 20 74 68 65 20 6e 65 61 72 20 66 75 74 75 72  * the near futur
31340 65 20 61 6e 64 20 74 68 61 74 20 53 51 4c 69 74  e and that SQLit
31350 65 20 73 68 6f 75 6c 64 20 6d 61 6b 65 20 69 74  e should make it
31360 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f  s own private co
31370 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63 6f 6e  py of.** the con
31380 74 65 6e 74 20 62 65 66 6f 72 65 20 72 65 74 75  tent before retu
31390 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  rning..**.** The
313a0 20 74 79 70 65 64 65 66 20 69 73 20 6e 65 63 65   typedef is nece
313b0 73 73 61 72 79 20 74 6f 20 77 6f 72 6b 20 61 72  ssary to work ar
313c0 6f 75 6e 64 20 70 72 6f 62 6c 65 6d 73 20 69 6e  ound problems in
313d0 20 63 65 72 74 61 69 6e 0a 2a 2a 20 43 2b 2b 20   certain.** C++ 
313e0 63 6f 6d 70 69 6c 65 72 73 2e 20 20 53 65 65 20  compilers.  See 
313f0 74 69 63 6b 65 74 20 23 32 31 39 31 2e 0a 2a 2f  ticket #2191..*/
31400 0a 74 79 70 65 64 65 66 20 76 6f 69 64 20 28 2a  .typedef void (*
31410 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74  sqlite3_destruct
31420 6f 72 5f 74 79 70 65 29 28 76 6f 69 64 2a 29 3b  or_type)(void*);
31430 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
31440 53 54 41 54 49 43 20 20 20 20 20 20 28 28 73 71  STATIC      ((sq
31450 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72  lite3_destructor
31460 5f 74 79 70 65 29 30 29 0a 23 64 65 66 69 6e 65  _type)0).#define
31470 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e   SQLITE_TRANSIEN
31480 54 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64 65  T   ((sqlite3_de
31490 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 2d 31  structor_type)-1
314a0 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  )../*.** CAPI3RE
314b0 46 3a 20 53 65 74 74 69 6e 67 20 54 68 65 20 52  F: Setting The R
314c0 65 73 75 6c 74 20 4f 66 20 41 6e 20 53 51 4c 20  esult Of An SQL 
314d0 46 75 6e 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 54  Function.**.** T
314e0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
314f0 65 20 75 73 65 64 20 62 79 20 74 68 65 20 78 46  e used by the xF
31500 75 6e 63 20 6f 72 20 78 46 69 6e 61 6c 20 63 61  unc or xFinal ca
31510 6c 6c 62 61 63 6b 73 20 74 68 61 74 0a 2a 2a 20  llbacks that.** 
31520 69 6d 70 6c 65 6d 65 6e 74 20 53 51 4c 20 66 75  implement SQL fu
31530 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72  nctions and aggr
31540 65 67 61 74 65 73 2e 20 20 53 65 65 0a 2a 2a 20  egates.  See.** 
31550 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
31560 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20  function()] and 
31570 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
31580 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a  function16()].**
31590 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20   for additional 
315a0 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a  information..**.
315b0 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f  ** These functio
315c0 6e 73 20 77 6f 72 6b 20 76 65 72 79 20 6d 75 63  ns work very muc
315d0 68 20 6c 69 6b 65 20 74 68 65 20 5b 70 61 72 61  h like the [para
315e0 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 5d 20 66  meter binding] f
315f0 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 66 75 6e 63  amily of.** func
31600 74 69 6f 6e 73 20 75 73 65 64 20 74 6f 20 62 69  tions used to bi
31610 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 68 6f 73  nd values to hos
31620 74 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e 20  t parameters in 
31630 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
31640 6e 74 73 2e 0a 2a 2a 20 52 65 66 65 72 20 74 6f  nts..** Refer to
31650 20 74 68 65 20 5b 53 51 4c 20 70 61 72 61 6d 65   the [SQL parame
31660 74 65 72 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69  ter] documentati
31670 6f 6e 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  on for additiona
31680 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  l information..*
31690 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
316a0 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 20  3_result_blob() 
316b0 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74  interface sets t
316c0 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a  he result from.*
316d0 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  * an application
316e0 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
316f0 6e 20 74 6f 20 62 65 20 74 68 65 20 42 4c 4f 42  n to be the BLOB
31700 20 77 68 6f 73 65 20 63 6f 6e 74 65 6e 74 20 69   whose content i
31710 73 20 70 6f 69 6e 74 65 64 0a 2a 2a 20 74 6f 20  s pointed.** to 
31720 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  by the second pa
31730 72 61 6d 65 74 65 72 20 61 6e 64 20 77 68 69 63  rameter and whic
31740 68 20 69 73 20 4e 20 62 79 74 65 73 20 6c 6f 6e  h is N bytes lon
31750 67 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65  g where N is the
31760 0a 2a 2a 20 74 68 69 72 64 20 70 61 72 61 6d 65  .** third parame
31770 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ter..**.** ^The 
31780 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a  sqlite3_result_z
31790 65 72 6f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66  eroblob() interf
317a0 61 63 65 73 20 73 65 74 20 74 68 65 20 72 65 73  aces set the res
317b0 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70  ult of.** the ap
317c0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
317d0 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
317e0 20 61 20 42 4c 4f 42 20 63 6f 6e 74 61 69 6e 69   a BLOB containi
317f0 6e 67 20 61 6c 6c 20 7a 65 72 6f 0a 2a 2a 20 62  ng all zero.** b
31800 79 74 65 73 20 61 6e 64 20 4e 20 62 79 74 65 73  ytes and N bytes
31810 20 69 6e 20 73 69 7a 65 2c 20 77 68 65 72 65 20   in size, where 
31820 4e 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f  N is the value o
31830 66 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65  f the 2nd parame
31840 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ter..**.** ^The 
31850 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64  sqlite3_result_d
31860 6f 75 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63  ouble() interfac
31870 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c  e sets the resul
31880 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70  t from.** an app
31890 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
318a0 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
318b0 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  a floating point
318c0 20 76 61 6c 75 65 20 73 70 65 63 69 66 69 65 64   value specified
318d0 0a 2a 2a 20 62 79 20 69 74 73 20 32 6e 64 20 61  .** by its 2nd a
318e0 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e  rgument..**.** ^
318f0 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
31900 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73  lt_error() and s
31910 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
31920 72 6f 72 31 36 28 29 20 66 75 6e 63 74 69 6f 6e  ror16() function
31930 73 0a 2a 2a 20 63 61 75 73 65 20 74 68 65 20 69  s.** cause the i
31940 6d 70 6c 65 6d 65 6e 74 65 64 20 53 51 4c 20 66  mplemented SQL f
31950 75 6e 63 74 69 6f 6e 20 74 6f 20 74 68 72 6f 77  unction to throw
31960 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 2e 0a 2a   an exception..*
31970 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20 74  * ^SQLite uses t
31980 68 65 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65  he string pointe
31990 64 20 74 6f 20 62 79 20 74 68 65 0a 2a 2a 20 32  d to by the.** 2
319a0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20  nd parameter of 
319b0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
319c0 72 72 6f 72 28 29 20 6f 72 20 73 71 6c 69 74 65  rror() or sqlite
319d0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
319e0 28 29 0a 2a 2a 20 61 73 20 74 68 65 20 74 65 78  ().** as the tex
319f0 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 6d 65  t of an error me
31a00 73 73 61 67 65 2e 20 20 5e 53 51 4c 69 74 65 20  ssage.  ^SQLite 
31a10 69 6e 74 65 72 70 72 65 74 73 20 74 68 65 20 65  interprets the e
31a20 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20  rror.** message 
31a30 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69  string from sqli
31a40 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
31a50 28 29 20 61 73 20 55 54 46 2d 38 2e 20 5e 53 51  () as UTF-8. ^SQ
31a60 4c 69 74 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65  Lite.** interpre
31a70 74 73 20 74 68 65 20 73 74 72 69 6e 67 20 66 72  ts the string fr
31a80 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  om sqlite3_resul
31a90 74 5f 65 72 72 6f 72 31 36 28 29 20 61 73 20 55  t_error16() as U
31aa0 54 46 2d 31 36 20 69 6e 20 6e 61 74 69 76 65 0a  TF-16 in native.
31ab0 2a 2a 20 62 79 74 65 20 6f 72 64 65 72 2e 20 20  ** byte order.  
31ac0 5e 49 66 20 74 68 65 20 74 68 69 72 64 20 70 61  ^If the third pa
31ad0 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
31ae0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
31af0 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f  ).** or sqlite3_
31b00 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29  result_error16()
31b10 20 69 73 20 6e 65 67 61 74 69 76 65 20 74 68 65   is negative the
31b20 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 61  n SQLite takes a
31b30 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d  s the error.** m
31b40 65 73 73 61 67 65 20 61 6c 6c 20 74 65 78 74 20  essage all text 
31b50 75 70 20 74 68 72 6f 75 67 68 20 74 68 65 20 66  up through the f
31b60 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63  irst zero charac
31b70 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ter..** ^If the 
31b80 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
31b90 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  to sqlite3_resul
31ba0 74 5f 65 72 72 6f 72 28 29 20 6f 72 0a 2a 2a 20  t_error() or.** 
31bb0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
31bc0 72 72 6f 72 31 36 28 29 20 69 73 20 6e 6f 6e 2d  rror16() is non-
31bd0 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 53 51  negative then SQ
31be0 4c 69 74 65 20 74 61 6b 65 73 20 74 68 61 74 20  Lite takes that 
31bf0 6d 61 6e 79 0a 2a 2a 20 62 79 74 65 73 20 28 6e  many.** bytes (n
31c00 6f 74 20 63 68 61 72 61 63 74 65 72 73 29 20 66  ot characters) f
31c10 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61  rom the 2nd para
31c20 6d 65 74 65 72 20 61 73 20 74 68 65 20 65 72 72  meter as the err
31c30 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 20 5e  or message..** ^
31c40 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
31c50 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73  lt_error() and s
31c60 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
31c70 72 6f 72 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69  ror16().** routi
31c80 6e 65 73 20 6d 61 6b 65 20 61 20 70 72 69 76 61  nes make a priva
31c90 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 65  te copy of the e
31ca0 72 72 6f 72 20 6d 65 73 73 61 67 65 20 74 65 78  rror message tex
31cb0 74 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 79  t before.** they
31cc0 20 72 65 74 75 72 6e 2e 20 20 48 65 6e 63 65 2c   return.  Hence,
31cd0 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e   the calling fun
31ce0 63 74 69 6f 6e 20 63 61 6e 20 64 65 61 6c 6c 6f  ction can deallo
31cf0 63 61 74 65 20 6f 72 0a 2a 2a 20 6d 6f 64 69 66  cate or.** modif
31d00 79 20 74 68 65 20 74 65 78 74 20 61 66 74 65 72  y the text after
31d10 20 74 68 65 79 20 72 65 74 75 72 6e 20 77 69 74   they return wit
31d20 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e 54  hout harm..** ^T
31d30 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
31d40 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 29 20 66  t_error_code() f
31d50 75 6e 63 74 69 6f 6e 20 63 68 61 6e 67 65 73 20  unction changes 
31d60 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a  the error code.*
31d70 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 53 51  * returned by SQ
31d80 4c 69 74 65 20 61 73 20 61 20 72 65 73 75 6c 74  Lite as a result
31d90 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 69 6e 20   of an error in 
31da0 61 20 66 75 6e 63 74 69 6f 6e 2e 20 20 5e 42 79  a function.  ^By
31db0 20 64 65 66 61 75 6c 74 2c 0a 2a 2a 20 74 68 65   default,.** the
31dc0 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 53   error code is S
31dd0 51 4c 49 54 45 5f 45 52 52 4f 52 2e 20 20 5e 41  QLITE_ERROR.  ^A
31de0 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   subsequent call
31df0 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75   to sqlite3_resu
31e00 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72  lt_error().** or
31e10 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
31e20 65 72 72 6f 72 31 36 28 29 20 72 65 73 65 74 73  error16() resets
31e30 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20   the error code 
31e40 74 6f 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e  to SQLITE_ERROR.
31e50 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
31e60 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
31e70 5f 74 6f 6f 62 69 67 28 29 20 69 6e 74 65 72 66  _toobig() interf
31e80 61 63 65 20 63 61 75 73 65 73 20 53 51 4c 69 74  ace causes SQLit
31e90 65 20 74 6f 20 74 68 72 6f 77 20 61 6e 0a 2a 2a  e to throw an.**
31ea0 20 65 72 72 6f 72 20 69 6e 64 69 63 61 74 69 6e   error indicatin
31eb0 67 20 74 68 61 74 20 61 20 73 74 72 69 6e 67 20  g that a string 
31ec0 6f 72 20 42 4c 4f 42 20 69 73 20 74 6f 6f 20 6c  or BLOB is too l
31ed0 6f 6e 67 20 74 6f 20 72 65 70 72 65 73 65 6e 74  ong to represent
31ee0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
31ef0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
31f00 72 5f 6e 6f 6d 65 6d 28 29 20 69 6e 74 65 72 66  r_nomem() interf
31f10 61 63 65 20 63 61 75 73 65 73 20 53 51 4c 69 74  ace causes SQLit
31f20 65 20 74 6f 20 74 68 72 6f 77 20 61 6e 0a 2a 2a  e to throw an.**
31f30 20 65 72 72 6f 72 20 69 6e 64 69 63 61 74 69 6e   error indicatin
31f40 67 20 74 68 61 74 20 61 20 6d 65 6d 6f 72 79 20  g that a memory 
31f50 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 65  allocation faile
31f60 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  d..**.** ^The sq
31f70 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74  lite3_result_int
31f80 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74  () interface set
31f90 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  s the return val
31fa0 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70  ue.** of the app
31fb0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
31fc0 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
31fd0 74 68 65 20 33 32 2d 62 69 74 20 73 69 67 6e 65  the 32-bit signe
31fe0 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c  d integer.** val
31ff0 75 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20  ue given in the 
32000 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  2nd argument..**
32010 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
32020 73 75 6c 74 5f 69 6e 74 36 34 28 29 20 69 6e 74  sult_int64() int
32030 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20  erface sets the 
32040 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20  return value.** 
32050 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  of the applicati
32060 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
32070 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 36 34  ion to be the 64
32080 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65  -bit signed inte
32090 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76  ger.** value giv
320a0 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 20 61 72  en in the 2nd ar
320b0 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54  gument..**.** ^T
320c0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
320d0 74 5f 6e 75 6c 6c 28 29 20 69 6e 74 65 72 66 61  t_null() interfa
320e0 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75  ce sets the retu
320f0 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74  rn value.** of t
32100 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
32110 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
32120 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  to be NULL..**.*
32130 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
32140 65 73 75 6c 74 5f 74 65 78 74 28 29 2c 20 73 71  esult_text(), sq
32150 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
32160 74 31 36 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65  t16(),.** sqlite
32170 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c  3_result_text16l
32180 65 28 29 2c 20 61 6e 64 20 73 71 6c 69 74 65 33  e(), and sqlite3
32190 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65  _result_text16be
321a0 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  () interfaces.**
321b0 20 73 65 74 20 74 68 65 20 72 65 74 75 72 6e 20   set the return 
321c0 76 61 6c 75 65 20 6f 66 20 74 68 65 20 61 70 70  value of the app
321d0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
321e0 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 0a   function to be.
321f0 2a 2a 20 61 20 74 65 78 74 20 73 74 72 69 6e 67  ** a text string
32200 20 77 68 69 63 68 20 69 73 20 72 65 70 72 65 73   which is repres
32210 65 6e 74 65 64 20 61 73 20 55 54 46 2d 38 2c 20  ented as UTF-8, 
32220 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79  UTF-16 native by
32230 74 65 20 6f 72 64 65 72 2c 0a 2a 2a 20 55 54 46  te order,.** UTF
32240 2d 31 36 20 6c 69 74 74 6c 65 20 65 6e 64 69 61  -16 little endia
32250 6e 2c 20 6f 72 20 55 54 46 2d 31 36 20 62 69 67  n, or UTF-16 big
32260 20 65 6e 64 69 61 6e 2c 20 72 65 73 70 65 63 74   endian, respect
32270 69 76 65 6c 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74  ively..** ^SQLit
32280 65 20 74 61 6b 65 73 20 74 68 65 20 74 65 78 74  e takes the text
32290 20 72 65 73 75 6c 74 20 66 72 6f 6d 20 74 68 65   result from the
322a0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 66 72 6f   application fro
322b0 6d 0a 2a 2a 20 74 68 65 20 32 6e 64 20 70 61 72  m.** the 2nd par
322c0 61 6d 65 74 65 72 20 6f 66 20 74 68 65 20 73 71  ameter of the sq
322d0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
322e0 74 2a 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a  t* interfaces..*
322f0 2a 20 5e 49 66 20 74 68 65 20 33 72 64 20 70 61  * ^If the 3rd pa
32300 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73  rameter to the s
32310 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
32320 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  xt* interfaces.*
32330 2a 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74  * is negative, t
32340 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73  hen SQLite takes
32350 20 72 65 73 75 6c 74 20 74 65 78 74 20 66 72 6f   result text fro
32360 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65  m the 2nd parame
32370 74 65 72 0a 2a 2a 20 74 68 72 6f 75 67 68 20 74  ter.** through t
32380 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 63 68  he first zero ch
32390 61 72 61 63 74 65 72 2e 0a 2a 2a 20 5e 49 66 20  aracter..** ^If 
323a0 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65  the 3rd paramete
323b0 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  r to the sqlite3
323c0 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e  _result_text* in
323d0 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e  terfaces.** is n
323e0 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65  on-negative, the
323f0 6e 20 61 73 20 6d 61 6e 79 20 62 79 74 65 73 20  n as many bytes 
32400 28 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 29  (not characters)
32410 20 6f 66 20 74 68 65 20 74 65 78 74 0a 2a 2a 20   of the text.** 
32420 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68  pointed to by th
32430 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  e 2nd parameter 
32440 61 72 65 20 74 61 6b 65 6e 20 61 73 20 74 68 65  are taken as the
32450 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
32460 69 6e 65 64 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  ined.** function
32470 20 72 65 73 75 6c 74 2e 20 20 49 66 20 74 68 65   result.  If the
32480 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 69   3rd parameter i
32490 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20  s non-negative, 
324a0 74 68 65 6e 20 69 74 0a 2a 2a 20 6d 75 73 74 20  then it.** must 
324b0 62 65 20 74 68 65 20 62 79 74 65 20 6f 66 66 73  be the byte offs
324c0 65 74 20 69 6e 74 6f 20 74 68 65 20 73 74 72 69  et into the stri
324d0 6e 67 20 77 68 65 72 65 20 74 68 65 20 4e 55 4c  ng where the NUL
324e0 20 74 65 72 6d 69 6e 61 74 6f 72 20 77 6f 75 6c   terminator woul
324f0 64 0a 2a 2a 20 61 70 70 65 61 72 20 69 66 20 74  d.** appear if t
32500 68 65 20 73 74 72 69 6e 67 20 77 68 65 72 65 20  he string where 
32510 4e 55 4c 20 74 65 72 6d 69 6e 61 74 65 64 2e 20  NUL terminated. 
32520 20 49 66 20 61 6e 79 20 4e 55 4c 20 63 68 61 72   If any NUL char
32530 61 63 74 65 72 73 20 6f 63 63 75 72 0a 2a 2a 20  acters occur.** 
32540 69 6e 20 74 68 65 20 73 74 72 69 6e 67 20 61 74  in the string at
32550 20 61 20 62 79 74 65 20 6f 66 66 73 65 74 20 74   a byte offset t
32560 68 61 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e  hat is less than
32570 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68   the value of th
32580 65 20 33 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74  e 3rd.** paramet
32590 65 72 2c 20 74 68 65 6e 20 74 68 65 20 72 65 73  er, then the res
325a0 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 20 77 69  ulting string wi
325b0 6c 6c 20 63 6f 6e 74 61 69 6e 20 65 6d 62 65 64  ll contain embed
325c0 64 65 64 20 4e 55 4c 73 20 61 6e 64 20 74 68 65  ded NULs and the
325d0 0a 2a 2a 20 72 65 73 75 6c 74 20 6f 66 20 65 78  .** result of ex
325e0 70 72 65 73 73 69 6f 6e 73 20 6f 70 65 72 61 74  pressions operat
325f0 69 6e 67 20 6f 6e 20 73 74 72 69 6e 67 73 20 77  ing on strings w
32600 69 74 68 20 65 6d 62 65 64 64 65 64 20 4e 55 4c  ith embedded NUL
32610 73 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  s is undefined..
32620 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20 70  ** ^If the 4th p
32630 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
32640 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
32650 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a  ext* interfaces.
32660 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  ** or sqlite3_re
32670 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 61 20 6e  sult_blob is a n
32680 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c  on-NULL pointer,
32690 20 74 68 65 6e 20 53 51 4c 69 74 65 20 63 61 6c   then SQLite cal
326a0 6c 73 20 74 68 61 74 0a 2a 2a 20 66 75 6e 63 74  ls that.** funct
326b0 69 6f 6e 20 61 73 20 74 68 65 20 64 65 73 74 72  ion as the destr
326c0 75 63 74 6f 72 20 6f 6e 20 74 68 65 20 74 65 78  uctor on the tex
326d0 74 20 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c 74  t or BLOB result
326e0 20 77 68 65 6e 20 69 74 20 68 61 73 0a 2a 2a 20   when it has.** 
326f0 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74  finished using t
32700 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e  hat result..** ^
32710 49 66 20 74 68 65 20 34 74 68 20 70 61 72 61 6d  If the 4th param
32720 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69  eter to the sqli
32730 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a  te3_result_text*
32740 20 69 6e 74 65 72 66 61 63 65 73 20 6f 72 20 74   interfaces or t
32750 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73  o.** sqlite3_res
32760 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20  ult_blob is the 
32770 73 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74  special constant
32780 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20   SQLITE_STATIC, 
32790 74 68 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61  then SQLite.** a
327a0 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 20  ssumes that the 
327b0 74 65 78 74 20 6f 72 20 42 4c 4f 42 20 72 65 73  text or BLOB res
327c0 75 6c 74 20 69 73 20 69 6e 20 63 6f 6e 73 74 61  ult is in consta
327d0 6e 74 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65  nt space and doe
327e0 73 20 6e 6f 74 0a 2a 2a 20 63 6f 70 79 20 74 68  s not.** copy th
327f0 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65  e content of the
32800 20 70 61 72 61 6d 65 74 65 72 20 6e 6f 72 20 63   parameter nor c
32810 61 6c 6c 20 61 20 64 65 73 74 72 75 63 74 6f 72  all a destructor
32820 20 6f 6e 20 74 68 65 20 63 6f 6e 74 65 6e 74 0a   on the content.
32830 2a 2a 20 77 68 65 6e 20 69 74 20 68 61 73 20 66  ** when it has f
32840 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74 68  inished using th
32850 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49  at result..** ^I
32860 66 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65  f the 4th parame
32870 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ter to the sqlit
32880 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20  e3_result_text* 
32890 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72  interfaces.** or
328a0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
328b0 62 6c 6f 62 20 69 73 20 74 68 65 20 73 70 65 63  blob is the spec
328c0 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c  ial constant SQL
328d0 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 0a 2a 2a  ITE_TRANSIENT.**
328e0 20 74 68 65 6e 20 53 51 4c 69 74 65 20 6d 61 6b   then SQLite mak
328f0 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  es a copy of the
32900 20 72 65 73 75 6c 74 20 69 6e 74 6f 20 73 70 61   result into spa
32910 63 65 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ce obtained from
32920 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  .** from [sqlite
32930 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 62 65 66 6f  3_malloc()] befo
32940 72 65 20 69 74 20 72 65 74 75 72 6e 73 2e 0a 2a  re it returns..*
32950 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
32960 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29  3_result_value()
32970 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20   interface sets 
32980 74 68 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a  the result of.**
32990 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
329a0 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
329b0 6e 20 74 6f 20 62 65 20 61 20 63 6f 70 79 20 74  n to be a copy t
329c0 68 65 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74  he.** [unprotect
329d0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
329e0 5d 20 6f 62 6a 65 63 74 20 73 70 65 63 69 66 69  ] object specifi
329f0 65 64 20 62 79 20 74 68 65 20 32 6e 64 20 70 61  ed by the 2nd pa
32a00 72 61 6d 65 74 65 72 2e 20 20 5e 54 68 65 0a 2a  rameter.  ^The.*
32a10 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  * sqlite3_result
32a20 5f 76 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61  _value() interfa
32a30 63 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20  ce makes a copy 
32a40 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
32a50 76 61 6c 75 65 5d 0a 2a 2a 20 73 6f 20 74 68 61  value].** so tha
32a60 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  t the [sqlite3_v
32a70 61 6c 75 65 5d 20 73 70 65 63 69 66 69 65 64 20  alue] specified 
32a80 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  in the parameter
32a90 20 6d 61 79 20 63 68 61 6e 67 65 20 6f 72 0a 2a   may change or.*
32aa0 2a 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64  * be deallocated
32ab0 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 72   after sqlite3_r
32ac0 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 72 65  esult_value() re
32ad0 74 75 72 6e 73 20 77 69 74 68 6f 75 74 20 68 61  turns without ha
32ae0 72 6d 2e 0a 2a 2a 20 5e 41 20 5b 70 72 6f 74 65  rm..** ^A [prote
32af0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
32b00 75 65 5d 20 6f 62 6a 65 63 74 20 6d 61 79 20 61  ue] object may a
32b10 6c 77 61 79 73 20 62 65 20 75 73 65 64 20 77 68  lways be used wh
32b20 65 72 65 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f  ere an.** [unpro
32b30 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
32b40 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 69 73 20  alue] object is 
32b50 72 65 71 75 69 72 65 64 2c 20 73 6f 20 65 69 74  required, so eit
32b60 68 65 72 0a 2a 2a 20 6b 69 6e 64 20 6f 66 20 5b  her.** kind of [
32b70 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
32b80 62 6a 65 63 74 20 63 61 6e 20 62 65 20 75 73 65  bject can be use
32b90 64 20 77 69 74 68 20 74 68 69 73 20 69 6e 74 65  d with this inte
32ba0 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  rface..**.** If 
32bb0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  these routines a
32bc0 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 77  re called from w
32bd0 69 74 68 69 6e 20 74 68 65 20 64 69 66 66 65 72  ithin the differ
32be0 65 6e 74 20 74 68 72 65 61 64 0a 2a 2a 20 74 68  ent thread.** th
32bf0 61 6e 20 74 68 65 20 6f 6e 65 20 63 6f 6e 74 61  an the one conta
32c00 69 6e 69 6e 67 20 74 68 65 20 61 70 70 6c 69 63  ining the applic
32c10 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
32c20 6e 63 74 69 6f 6e 20 74 68 61 74 20 72 65 63 65  nction that rece
32c30 69 76 65 64 0a 2a 2a 20 74 68 65 20 5b 73 71 6c  ived.** the [sql
32c40 69 74 65 33 5f 63 6f 6e 74 65 78 74 5d 20 70 6f  ite3_context] po
32c50 69 6e 74 65 72 2c 20 74 68 65 20 72 65 73 75 6c  inter, the resul
32c60 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64  ts are undefined
32c70 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65  ..*/.void sqlite
32c80 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 73 71  3_result_blob(sq
32c90 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
32ca0 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
32cb0 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  , void(*)(void*)
32cc0 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
32cd0 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 73 71  result_double(sq
32ce0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
32cf0 64 6f 75 62 6c 65 29 3b 0a 76 6f 69 64 20 73 71  double);.void sq
32d00 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
32d10 6f 72 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  or(sqlite3_conte
32d20 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a  xt*, const char*
32d30 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c  , int);.void sql
32d40 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
32d50 72 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  r16(sqlite3_cont
32d60 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64  ext*, const void
32d70 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71  *, int);.void sq
32d80 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
32d90 6f 72 5f 74 6f 6f 62 69 67 28 73 71 6c 69 74 65  or_toobig(sqlite
32da0 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69  3_context*);.voi
32db0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
32dc0 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 73 71 6c  _error_nomem(sql
32dd0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a  ite3_context*);.
32de0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
32df0 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 73  ult_error_code(s
32e00 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
32e10 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69   int);.void sqli
32e20 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 73  te3_result_int(s
32e30 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
32e40 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69   int);.void sqli
32e50 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34  te3_result_int64
32e60 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
32e70 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
32e80 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
32e90 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 73 71 6c 69  result_null(sqli
32ea0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76  te3_context*);.v
32eb0 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
32ec0 6c 74 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f  lt_text(sqlite3_
32ed0 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20  context*, const 
32ee0 63 68 61 72 2a 2c 20 69 6e 74 2c 20 76 6f 69 64  char*, int, void
32ef0 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69  (*)(void*));.voi
32f00 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
32f10 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f  _text16(sqlite3_
32f20 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20  context*, const 
32f30 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64  void*, int, void
32f40 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69  (*)(void*));.voi
32f50 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
32f60 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65  _text16le(sqlite
32f70 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
32f80 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69  t void*, int,voi
32f90 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f  d(*)(void*));.vo
32fa0 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
32fb0 74 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69 74  t_text16be(sqlit
32fc0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e  e3_context*, con
32fd0 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f  st void*, int,vo
32fe0 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76  id(*)(void*));.v
32ff0 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
33000 6c 74 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33  lt_value(sqlite3
33010 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74  _context*, sqlit
33020 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 76 6f 69 64  e3_value*);.void
33030 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
33040 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33  zeroblob(sqlite3
33050 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e  _context*, int n
33060 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
33070 45 46 3a 20 44 65 66 69 6e 65 20 4e 65 77 20 43  EF: Define New C
33080 6f 6c 6c 61 74 69 6e 67 20 53 65 71 75 65 6e 63  ollating Sequenc
33090 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  es.**.** ^These 
330a0 66 75 6e 63 74 69 6f 6e 73 20 61 64 64 2c 20 72  functions add, r
330b0 65 6d 6f 76 65 2c 20 6f 72 20 6d 6f 64 69 66 79  emove, or modify
330c0 20 61 20 5b 63 6f 6c 6c 61 74 69 6f 6e 5d 20 61   a [collation] a
330d0 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69 74  ssociated.** wit
330e0 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  h the [database 
330f0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63  connection] spec
33100 69 66 69 65 64 20 61 73 20 74 68 65 20 66 69 72  ified as the fir
33110 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a  st argument..**.
33120 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20  ** ^The name of 
33130 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73  the collation is
33140 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a   a UTF-8 string.
33150 2a 2a 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63  ** for sqlite3_c
33160 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28  reate_collation(
33170 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 72  ) and sqlite3_cr
33180 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76  eate_collation_v
33190 32 28 29 0a 2a 2a 20 61 6e 64 20 61 20 55 54 46  2().** and a UTF
331a0 2d 31 36 20 73 74 72 69 6e 67 20 69 6e 20 6e 61  -16 string in na
331b0 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20  tive byte order 
331c0 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61  for sqlite3_crea
331d0 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29  te_collation16()
331e0 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6f 6e 20  ..** ^Collation 
331f0 6e 61 6d 65 73 20 74 68 61 74 20 63 6f 6d 70 61  names that compa
33200 72 65 20 65 71 75 61 6c 20 61 63 63 6f 72 64 69  re equal accordi
33210 6e 67 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ng to [sqlite3_s
33220 74 72 6e 69 63 6d 70 28 29 5d 20 61 72 65 0a 2a  trnicmp()] are.*
33230 2a 20 63 6f 6e 73 69 64 65 72 65 64 20 74 6f 20  * considered to 
33240 62 65 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65  be the same name
33250 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 74 68  ..**.** ^(The th
33260 69 72 64 20 61 72 67 75 6d 65 6e 74 20 28 65 54  ird argument (eT
33270 65 78 74 52 65 70 29 20 6d 75 73 74 20 62 65 20  extRep) must be 
33280 6f 6e 65 20 6f 66 20 74 68 65 20 63 6f 6e 73 74  one of the const
33290 61 6e 74 73 3a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  ants:.** <ul>.**
332a0 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54   <li> [SQLITE_UT
332b0 46 38 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  F8],.** <li> [SQ
332c0 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c 0a 2a  LITE_UTF16LE],.*
332d0 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55  * <li> [SQLITE_U
332e0 54 46 31 36 42 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e  TF16BE],.** <li>
332f0 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 2c   [SQLITE_UTF16],
33300 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c   or.** <li> [SQL
33310 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45  ITE_UTF16_ALIGNE
33320 44 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a  D]..** </ul>)^.*
33330 2a 20 5e 54 68 65 20 65 54 65 78 74 52 65 70 20  * ^The eTextRep 
33340 61 72 67 75 6d 65 6e 74 20 64 65 74 65 72 6d 69  argument determi
33350 6e 65 73 20 74 68 65 20 65 6e 63 6f 64 69 6e 67  nes the encoding
33360 20 6f 66 20 73 74 72 69 6e 67 73 20 70 61 73 73   of strings pass
33370 65 64 0a 2a 2a 20 74 6f 20 74 68 65 20 63 6f 6c  ed.** to the col
33380 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  lating function 
33390 63 61 6c 6c 62 61 63 6b 2c 20 78 43 61 6c 6c 62  callback, xCallb
333a0 61 63 6b 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  ack..** ^The [SQ
333b0 4c 49 54 45 5f 55 54 46 31 36 5d 20 61 6e 64 20  LITE_UTF16] and 
333c0 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c  [SQLITE_UTF16_AL
333d0 49 47 4e 45 44 5d 20 76 61 6c 75 65 73 20 66 6f  IGNED] values fo
333e0 72 20 65 54 65 78 74 52 65 70 0a 2a 2a 20 66 6f  r eTextRep.** fo
333f0 72 63 65 20 73 74 72 69 6e 67 73 20 74 6f 20 62  rce strings to b
33400 65 20 55 54 46 31 36 20 77 69 74 68 20 6e 61 74  e UTF16 with nat
33410 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a  ive byte order..
33420 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
33430 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d 20 76  UTF16_ALIGNED] v
33440 61 6c 75 65 20 66 6f 72 20 65 54 65 78 74 52 65  alue for eTextRe
33450 70 20 66 6f 72 63 65 73 20 73 74 72 69 6e 67 73  p forces strings
33460 20 74 6f 20 62 65 67 69 6e 0a 2a 2a 20 6f 6e 20   to begin.** on 
33470 61 6e 20 65 76 65 6e 20 62 79 74 65 20 61 64 64  an even byte add
33480 72 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ress..**.** ^The
33490 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74   fourth argument
334a0 2c 20 70 41 72 67 2c 20 69 73 20 61 6e 20 61 70  , pArg, is an ap
334b0 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70  plication data p
334c0 6f 69 6e 74 65 72 20 74 68 61 74 20 69 73 20 70  ointer that is p
334d0 61 73 73 65 64 0a 2a 2a 20 74 68 72 6f 75 67 68  assed.** through
334e0 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72   as the first ar
334f0 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 63 6f  gument to the co
33500 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
33510 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a   callback..**.**
33520 20 5e 54 68 65 20 66 69 66 74 68 20 61 72 67 75   ^The fifth argu
33530 6d 65 6e 74 2c 20 78 43 61 6c 6c 62 61 63 6b 2c  ment, xCallback,
33540 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
33550 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66   the collating f
33560 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 5e 4d 75 6c  unction..** ^Mul
33570 74 69 70 6c 65 20 63 6f 6c 6c 61 74 69 6e 67 20  tiple collating 
33580 66 75 6e 63 74 69 6f 6e 73 20 63 61 6e 20 62 65  functions can be
33590 20 72 65 67 69 73 74 65 72 65 64 20 75 73 69 6e   registered usin
335a0 67 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20  g the same name 
335b0 62 75 74 0a 2a 2a 20 77 69 74 68 20 64 69 66 66  but.** with diff
335c0 65 72 65 6e 74 20 65 54 65 78 74 52 65 70 20 70  erent eTextRep p
335d0 61 72 61 6d 65 74 65 72 73 20 61 6e 64 20 53 51  arameters and SQ
335e0 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 77 68  Lite will use wh
335f0 69 63 68 65 76 65 72 0a 2a 2a 20 66 75 6e 63 74  ichever.** funct
33600 69 6f 6e 20 72 65 71 75 69 72 65 73 20 74 68 65  ion requires the
33610 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66   least amount of
33620 20 64 61 74 61 20 74 72 61 6e 73 66 6f 72 6d 61   data transforma
33630 74 69 6f 6e 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  tion..** ^If the
33640 20 78 43 61 6c 6c 62 61 63 6b 20 61 72 67 75 6d   xCallback argum
33650 65 6e 74 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e  ent is NULL then
33660 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66   the collating f
33670 75 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 64 65  unction is.** de
33680 6c 65 74 65 64 2e 20 20 5e 57 68 65 6e 20 61 6c  leted.  ^When al
33690 6c 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63  l collating func
336a0 74 69 6f 6e 73 20 68 61 76 69 6e 67 20 74 68 65  tions having the
336b0 20 73 61 6d 65 20 6e 61 6d 65 20 61 72 65 20 64   same name are d
336c0 65 6c 65 74 65 64 2c 0a 2a 2a 20 74 68 61 74 20  eleted,.** that 
336d0 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 20  collation is no 
336e0 6c 6f 6e 67 65 72 20 75 73 61 62 6c 65 2e 0a 2a  longer usable..*
336f0 2a 0a 2a 2a 20 5e 54 68 65 20 63 6f 6c 6c 61 74  *.** ^The collat
33700 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c  ing function cal
33710 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
33720 20 77 69 74 68 20 61 20 63 6f 70 79 20 6f 66 20   with a copy of 
33730 74 68 65 20 70 41 72 67 20 0a 2a 2a 20 61 70 70  the pArg .** app
33740 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f  lication data po
33750 69 6e 74 65 72 20 61 6e 64 20 77 69 74 68 20 74  inter and with t
33760 77 6f 20 73 74 72 69 6e 67 73 20 69 6e 20 74 68  wo strings in th
33770 65 20 65 6e 63 6f 64 69 6e 67 20 73 70 65 63 69  e encoding speci
33780 66 69 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 65  fied.** by the e
33790 54 65 78 74 52 65 70 20 61 72 67 75 6d 65 6e 74  TextRep argument
337a0 2e 20 20 54 68 65 20 63 6f 6c 6c 61 74 69 6e 67  .  The collating
337b0 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 72   function must r
337c0 65 74 75 72 6e 20 61 6e 0a 2a 2a 20 69 6e 74 65  eturn an.** inte
337d0 67 65 72 20 74 68 61 74 20 69 73 20 6e 65 67 61  ger that is nega
337e0 74 69 76 65 2c 20 7a 65 72 6f 2c 20 6f 72 20 70  tive, zero, or p
337f0 6f 73 69 74 69 76 65 0a 2a 2a 20 69 66 20 74 68  ositive.** if th
33800 65 20 66 69 72 73 74 20 73 74 72 69 6e 67 20 69  e first string i
33810 73 20 6c 65 73 73 20 74 68 61 6e 2c 20 65 71 75  s less than, equ
33820 61 6c 20 74 6f 2c 20 6f 72 20 67 72 65 61 74 65  al to, or greate
33830 72 20 74 68 61 6e 20 74 68 65 20 73 65 63 6f 6e  r than the secon
33840 64 2c 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65  d,.** respective
33850 6c 79 2e 20 20 41 20 63 6f 6c 6c 61 74 69 6e 67  ly.  A collating
33860 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 61   function must a
33870 6c 77 61 79 73 20 72 65 74 75 72 6e 20 74 68 65  lways return the
33880 20 73 61 6d 65 20 61 6e 73 77 65 72 0a 2a 2a 20   same answer.** 
33890 67 69 76 65 6e 20 74 68 65 20 73 61 6d 65 20 69  given the same i
338a0 6e 70 75 74 73 2e 20 20 49 66 20 74 77 6f 20 6f  nputs.  If two o
338b0 72 20 6d 6f 72 65 20 63 6f 6c 6c 61 74 69 6e 67  r more collating
338c0 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 72   functions are r
338d0 65 67 69 73 74 65 72 65 64 0a 2a 2a 20 74 6f 20  egistered.** to 
338e0 74 68 65 20 73 61 6d 65 20 63 6f 6c 6c 61 74 69  the same collati
338f0 6f 6e 20 6e 61 6d 65 20 28 75 73 69 6e 67 20 64  on name (using d
33900 69 66 66 65 72 65 6e 74 20 65 54 65 78 74 52 65  ifferent eTextRe
33910 70 20 76 61 6c 75 65 73 29 20 74 68 65 6e 20 61  p values) then a
33920 6c 6c 0a 2a 2a 20 6d 75 73 74 20 67 69 76 65 20  ll.** must give 
33930 61 6e 20 65 71 75 69 76 61 6c 65 6e 74 20 61 6e  an equivalent an
33940 73 77 65 72 20 77 68 65 6e 20 69 6e 76 6f 6b 65  swer when invoke
33950 64 20 77 69 74 68 20 65 71 75 69 76 61 6c 65 6e  d with equivalen
33960 74 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68  t strings..** Th
33970 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63  e collating func
33980 74 69 6f 6e 20 6d 75 73 74 20 6f 62 65 79 20 74  tion must obey t
33990 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 70 72 6f  he following pro
339a0 70 65 72 74 69 65 73 20 66 6f 72 20 61 6c 6c 0a  perties for all.
339b0 2a 2a 20 73 74 72 69 6e 67 73 20 41 2c 20 42 2c  ** strings A, B,
339c0 20 61 6e 64 20 43 3a 0a 2a 2a 0a 2a 2a 20 3c 6f   and C:.**.** <o
339d0 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 3d  l>.** <li> If A=
339e0 3d 42 20 74 68 65 6e 20 42 3d 3d 41 2e 0a 2a 2a  =B then B==A..**
339f0 20 3c 6c 69 3e 20 49 66 20 41 3d 3d 42 20 61 6e   <li> If A==B an
33a00 64 20 42 3d 3d 43 20 74 68 65 6e 20 41 3d 3d 43  d B==C then A==C
33a10 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 26 6c  ..** <li> If A&l
33a20 74 3b 42 20 54 48 45 4e 20 42 26 67 74 3b 41 2e  t;B THEN B&gt;A.
33a30 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 26 6c 74  .** <li> If A&lt
33a40 3b 42 20 61 6e 64 20 42 26 6c 74 3b 43 20 74 68  ;B and B&lt;C th
33a50 65 6e 20 41 26 6c 74 3b 43 2e 0a 2a 2a 20 3c 2f  en A&lt;C..** </
33a60 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 63  ol>.**.** If a c
33a70 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
33a80 6e 20 66 61 69 6c 73 20 61 6e 79 20 6f 66 20 74  n fails any of t
33a90 68 65 20 61 62 6f 76 65 20 63 6f 6e 73 74 72 61  he above constra
33aa0 69 6e 74 73 20 61 6e 64 20 74 68 61 74 0a 2a 2a  ints and that.**
33ab0 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
33ac0 69 6f 6e 20 69 73 20 20 72 65 67 69 73 74 65 72  ion is  register
33ad0 65 64 20 61 6e 64 20 75 73 65 64 2c 20 74 68 65  ed and used, the
33ae0 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f  n the behavior o
33af0 66 20 53 51 4c 69 74 65 0a 2a 2a 20 69 73 20 75  f SQLite.** is u
33b00 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
33b10 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 72 65  ^The sqlite3_cre
33b20 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32  ate_collation_v2
33b30 28 29 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71  () works like sq
33b40 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
33b50 6c 61 74 69 6f 6e 28 29 0a 2a 2a 20 77 69 74 68  lation().** with
33b60 20 74 68 65 20 61 64 64 69 74 69 6f 6e 20 74 68   the addition th
33b70 61 74 20 74 68 65 20 78 44 65 73 74 72 6f 79 20  at the xDestroy 
33b80 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
33b90 6b 65 64 20 6f 6e 20 70 41 72 67 20 77 68 65 6e  ked on pArg when
33ba0 0a 2a 2a 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e  .** the collatin
33bb0 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 64 65  g function is de
33bc0 6c 65 74 65 64 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61  leted..** ^Colla
33bd0 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 61  ting functions a
33be0 72 65 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20  re deleted when 
33bf0 74 68 65 79 20 61 72 65 20 6f 76 65 72 72 69 64  they are overrid
33c00 64 65 6e 20 62 79 20 6c 61 74 65 72 0a 2a 2a 20  den by later.** 
33c10 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 63 6f 6c  calls to the col
33c20 6c 61 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20  lation creation 
33c30 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 77 68 65  functions or whe
33c40 6e 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61  n the.** [databa
33c50 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69  se connection] i
33c60 73 20 63 6c 6f 73 65 64 20 75 73 69 6e 67 20 5b  s closed using [
33c70 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d  sqlite3_close()]
33c80 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78 44 65  ..**.** ^The xDe
33c90 73 74 72 6f 79 20 63 61 6c 6c 62 61 63 6b 20 69  stroy callback i
33ca0 73 20 3c 75 3e 6e 6f 74 3c 2f 75 3e 20 63 61 6c  s <u>not</u> cal
33cb0 6c 65 64 20 69 66 20 74 68 65 20 0a 2a 2a 20 73  led if the .** s
33cc0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
33cd0 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 66 75 6e  llation_v2() fun
33ce0 63 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20 41 70  ction fails.  Ap
33cf0 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20  plications that 
33d00 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65  invoke.** sqlite
33d10 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
33d20 6f 6e 5f 76 32 28 29 20 77 69 74 68 20 61 20 6e  on_v2() with a n
33d30 6f 6e 2d 4e 55 4c 4c 20 78 44 65 73 74 72 6f 79  on-NULL xDestroy
33d40 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64   argument should
33d50 20 0a 2a 2a 20 63 68 65 63 6b 20 74 68 65 20 72   .** check the r
33d60 65 74 75 72 6e 20 63 6f 64 65 20 61 6e 64 20 64  eturn code and d
33d70 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20 61 70  ispose of the ap
33d80 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70  plication data p
33d90 6f 69 6e 74 65 72 0a 2a 2a 20 74 68 65 6d 73 65  ointer.** themse
33da0 6c 76 65 73 20 72 61 74 68 65 72 20 74 68 61 6e  lves rather than
33db0 20 65 78 70 65 63 74 69 6e 67 20 53 51 4c 69 74   expecting SQLit
33dc0 65 20 74 6f 20 64 65 61 6c 20 77 69 74 68 20 69  e to deal with i
33dd0 74 20 66 6f 72 20 74 68 65 6d 2e 0a 2a 2a 20 54  t for them..** T
33de0 68 69 73 20 69 73 20 64 69 66 66 65 72 65 6e 74  his is different
33df0 20 66 72 6f 6d 20 65 76 65 72 79 20 6f 74 68 65   from every othe
33e00 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  r SQLite interfa
33e10 63 65 2e 20 20 54 68 65 20 69 6e 63 6f 6e 73 69  ce.  The inconsi
33e20 73 74 65 6e 63 79 20 0a 2a 2a 20 69 73 20 75 6e  stency .** is un
33e30 66 6f 72 74 75 6e 61 74 65 20 62 75 74 20 63 61  fortunate but ca
33e40 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67 65 64 20  nnot be changed 
33e50 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67  without breaking
33e60 20 62 61 63 6b 77 61 72 64 73 20 0a 2a 2a 20 63   backwards .** c
33e70 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a  ompatibility..**
33e80 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 20 5b  .** See also:  [
33e90 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
33ea0 6e 5f 6e 65 65 64 65 64 28 29 5d 20 61 6e 64 20  n_needed()] and 
33eb0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69  [sqlite3_collati
33ec0 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 5d 2e 0a  on_needed16()]..
33ed0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
33ee0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28  reate_collation(
33ef0 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20  .  sqlite3*, .  
33f00 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
33f10 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52  e, .  int eTextR
33f20 65 70 2c 20 0a 20 20 76 6f 69 64 20 2a 70 41 72  ep, .  void *pAr
33f30 67 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61  g,.  int(*xCompa
33f40 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  re)(void*,int,co
33f50 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  nst void*,int,co
33f60 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e  nst void*).);.in
33f70 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  t sqlite3_create
33f80 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 0a 20  _collation_v2(. 
33f90 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f   sqlite3*, .  co
33fa0 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
33fb0 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70   .  int eTextRep
33fc0 2c 20 0a 20 20 76 6f 69 64 20 2a 70 41 72 67 2c  , .  void *pArg,
33fd0 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65  .  int(*xCompare
33fe0 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  )(void*,int,cons
33ff0 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  t void*,int,cons
34000 74 20 76 6f 69 64 2a 29 2c 0a 20 20 76 6f 69 64  t void*),.  void
34010 28 2a 78 44 65 73 74 72 6f 79 29 28 76 6f 69 64  (*xDestroy)(void
34020 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  *).);.int sqlite
34030 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
34040 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65 33 2a  on16(.  sqlite3*
34050 2c 20 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  , .  const void 
34060 2a 7a 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 65 54  *zName,.  int eT
34070 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 20  extRep, .  void 
34080 2a 70 41 72 67 2c 0a 20 20 69 6e 74 28 2a 78 43  *pArg,.  int(*xC
34090 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e  ompare)(void*,in
340a0 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e  t,const void*,in
340b0 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29  t,const void*).)
340c0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
340d0 46 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20 4e 65 65  F: Collation Nee
340e0 64 65 64 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a  ded Callbacks.**
340f0 0a 2a 2a 20 5e 54 6f 20 61 76 6f 69 64 20 68 61  .** ^To avoid ha
34100 76 69 6e 67 20 74 6f 20 72 65 67 69 73 74 65 72  ving to register
34110 20 61 6c 6c 20 63 6f 6c 6c 61 74 69 6f 6e 20 73   all collation s
34120 65 71 75 65 6e 63 65 73 20 62 65 66 6f 72 65 20  equences before 
34130 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 61  a database.** ca
34140 6e 20 62 65 20 75 73 65 64 2c 20 61 20 73 69 6e  n be used, a sin
34150 67 6c 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  gle callback fun
34160 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 72 65 67  ction may be reg
34170 69 73 74 65 72 65 64 20 77 69 74 68 20 74 68 65  istered with the
34180 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
34190 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 62 65 20  nnection] to be 
341a0 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72  invoked whenever
341b0 20 61 6e 20 75 6e 64 65 66 69 6e 65 64 20 63 6f   an undefined co
341c0 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65  llation.** seque
341d0 6e 63 65 20 69 73 20 72 65 71 75 69 72 65 64 2e  nce is required.
341e0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66  .**.** ^If the f
341f0 75 6e 63 74 69 6f 6e 20 69 73 20 72 65 67 69 73  unction is regis
34200 74 65 72 65 64 20 75 73 69 6e 67 20 74 68 65 20  tered using the 
34210 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
34220 6e 5f 6e 65 65 64 65 64 28 29 20 41 50 49 2c 0a  n_needed() API,.
34230 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20 70 61  ** then it is pa
34240 73 73 65 64 20 74 68 65 20 6e 61 6d 65 73 20 6f  ssed the names o
34250 66 20 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c  f undefined coll
34260 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20  ation sequences 
34270 61 73 20 73 74 72 69 6e 67 73 0a 2a 2a 20 65 6e  as strings.** en
34280 63 6f 64 65 64 20 69 6e 20 55 54 46 2d 38 2e 20  coded in UTF-8. 
34290 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c  ^If sqlite3_coll
342a0 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29  ation_needed16()
342b0 20 69 73 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65   is used,.** the
342c0 20 6e 61 6d 65 73 20 61 72 65 20 70 61 73 73 65   names are passe
342d0 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 6d  d as UTF-16 in m
342e0 61 63 68 69 6e 65 20 6e 61 74 69 76 65 20 62 79  achine native by
342f0 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 20 5e 41 20  te order..** ^A 
34300 63 61 6c 6c 20 74 6f 20 65 69 74 68 65 72 20 66  call to either f
34310 75 6e 63 74 69 6f 6e 20 72 65 70 6c 61 63 65 73  unction replaces
34320 20 74 68 65 20 65 78 69 73 74 69 6e 67 20 63 6f   the existing co
34330 6c 6c 61 74 69 6f 6e 2d 6e 65 65 64 65 64 20 63  llation-needed c
34340 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e  allback..**.** ^
34350 28 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61  (When the callba
34360 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 74  ck is invoked, t
34370 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
34380 74 20 70 61 73 73 65 64 20 69 73 20 61 20 63 6f  t passed is a co
34390 70 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73 65 63  py.** of the sec
343a0 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ond argument to 
343b0 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
343c0 6e 5f 6e 65 65 64 65 64 28 29 20 6f 72 0a 2a 2a  n_needed() or.**
343d0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69   sqlite3_collati
343e0 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 2e 20 20  on_needed16().  
343f0 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
34400 65 6e 74 20 69 73 20 74 68 65 20 64 61 74 61 62  ent is the datab
34410 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  ase.** connectio
34420 6e 2e 20 20 54 68 65 20 74 68 69 72 64 20 61 72  n.  The third ar
34430 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66  gument is one of
34440 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 20   [SQLITE_UTF8], 
34450 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d  [SQLITE_UTF16BE]
34460 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ,.** or [SQLITE_
34470 55 54 46 31 36 4c 45 5d 2c 20 69 6e 64 69 63 61  UTF16LE], indica
34480 74 69 6e 67 20 74 68 65 20 6d 6f 73 74 20 64 65  ting the most de
34490 73 69 72 61 62 6c 65 20 66 6f 72 6d 20 6f 66 20  sirable form of 
344a0 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a  the collation.**
344b0 20 73 65 71 75 65 6e 63 65 20 66 75 6e 63 74 69   sequence functi
344c0 6f 6e 20 72 65 71 75 69 72 65 64 2e 20 20 54 68  on required.  Th
344d0 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
344e0 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  er is the name o
344f0 66 20 74 68 65 0a 2a 2a 20 72 65 71 75 69 72 65  f the.** require
34500 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75  d collation sequ
34510 65 6e 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  ence.)^.**.** Th
34520 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  e callback funct
34530 69 6f 6e 20 73 68 6f 75 6c 64 20 72 65 67 69 73  ion should regis
34540 74 65 72 20 74 68 65 20 64 65 73 69 72 65 64 20  ter the desired 
34550 63 6f 6c 6c 61 74 69 6f 6e 20 75 73 69 6e 67 0a  collation using.
34560 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  ** [sqlite3_crea
34570 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 5d 2c  te_collation()],
34580 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
34590 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 5d 2c  _collation16()],
345a0 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
345b0 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
345c0 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73  _v2()]..*/.int s
345d0 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e  qlite3_collation
345e0 5f 6e 65 65 64 65 64 28 0a 20 20 73 71 6c 69 74  _needed(.  sqlit
345f0 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 20 0a  e3*, .  void*, .
34600 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c    void(*)(void*,
34610 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54 65  sqlite3*,int eTe
34620 78 74 52 65 70 2c 63 6f 6e 73 74 20 63 68 61 72  xtRep,const char
34630 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  *).);.int sqlite
34640 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
34650 65 64 31 36 28 0a 20 20 73 71 6c 69 74 65 33 2a  ed16(.  sqlite3*
34660 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 76 6f  , .  void*,.  vo
34670 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69  id(*)(void*,sqli
34680 74 65 33 2a 2c 69 6e 74 20 65 54 65 78 74 52 65  te3*,int eTextRe
34690 70 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29  p,const void*).)
346a0 3b 0a 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45  ;..#ifdef SQLITE
346b0 5f 48 41 53 5f 43 4f 44 45 43 0a 2f 2a 0a 2a 2a  _HAS_CODEC./*.**
346c0 20 53 70 65 63 69 66 79 20 74 68 65 20 6b 65 79   Specify the key
346d0 20 66 6f 72 20 61 6e 20 65 6e 63 72 79 70 74 65   for an encrypte
346e0 64 20 64 61 74 61 62 61 73 65 2e 20 20 54 68 69  d database.  Thi
346f0 73 20 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64  s routine should
34700 20 62 65 0a 2a 2a 20 63 61 6c 6c 65 64 20 72 69   be.** called ri
34710 67 68 74 20 61 66 74 65 72 20 73 71 6c 69 74 65  ght after sqlite
34720 33 5f 6f 70 65 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20  3_open()..**.** 
34730 54 68 65 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c  The code to impl
34740 65 6d 65 6e 74 20 74 68 69 73 20 41 50 49 20 69  ement this API i
34750 73 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65 20  s not available 
34760 69 6e 20 74 68 65 20 70 75 62 6c 69 63 20 72 65  in the public re
34770 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69  lease.** of SQLi
34780 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  te..*/.int sqlit
34790 65 33 5f 6b 65 79 28 0a 20 20 73 71 6c 69 74 65  e3_key(.  sqlite
347a0 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
347b0 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
347c0 62 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65 79  base to be rekey
347d0 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  ed */.  const vo
347e0 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b  id *pKey, int nK
347f0 65 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6b 65  ey     /* The ke
34800 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  y */.);../*.** C
34810 68 61 6e 67 65 20 74 68 65 20 6b 65 79 20 6f 6e  hange the key on
34820 20 61 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73   an open databas
34830 65 2e 20 20 49 66 20 74 68 65 20 63 75 72 72 65  e.  If the curre
34840 6e 74 20 64 61 74 61 62 61 73 65 20 69 73 20 6e  nt database is n
34850 6f 74 0a 2a 2a 20 65 6e 63 72 79 70 74 65 64 2c  ot.** encrypted,
34860 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69   this routine wi
34870 6c 6c 20 65 6e 63 72 79 70 74 20 69 74 2e 20 20  ll encrypt it.  
34880 49 66 20 70 4e 65 77 3d 3d 30 20 6f 72 20 6e 4e  If pNew==0 or nN
34890 65 77 3d 3d 30 2c 20 74 68 65 0a 2a 2a 20 64 61  ew==0, the.** da
348a0 74 61 62 61 73 65 20 69 73 20 64 65 63 72 79 70  tabase is decryp
348b0 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63  ted..**.** The c
348c0 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74  ode to implement
348d0 20 74 68 69 73 20 41 50 49 20 69 73 20 6e 6f 74   this API is not
348e0 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 68   available in th
348f0 65 20 70 75 62 6c 69 63 20 72 65 6c 65 61 73 65  e public release
34900 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  .** of SQLite..*
34910 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65  /.int sqlite3_re
34920 6b 65 79 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  key(.  sqlite3 *
34930 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  db,             
34940 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
34950 65 20 74 6f 20 62 65 20 72 65 6b 65 79 65 64 20  e to be rekeyed 
34960 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
34970 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20  *pKey, int nKey 
34980 20 20 20 20 2f 2a 20 54 68 65 20 6e 65 77 20 6b      /* The new k
34990 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ey */.);../*.** 
349a0 53 70 65 63 69 66 79 20 74 68 65 20 61 63 74 69  Specify the acti
349b0 76 61 74 69 6f 6e 20 6b 65 79 20 66 6f 72 20 61  vation key for a
349c0 20 53 45 45 20 64 61 74 61 62 61 73 65 2e 20 20   SEE database.  
349d0 55 6e 6c 65 73 73 20 0a 2a 2a 20 61 63 74 69 76  Unless .** activ
349e0 61 74 65 64 2c 20 6e 6f 6e 65 20 6f 66 20 74 68  ated, none of th
349f0 65 20 53 45 45 20 72 6f 75 74 69 6e 65 73 20 77  e SEE routines w
34a00 69 6c 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a 76 6f 69  ill work..*/.voi
34a10 64 20 73 71 6c 69 74 65 33 5f 61 63 74 69 76 61  d sqlite3_activa
34a20 74 65 5f 73 65 65 28 0a 20 20 63 6f 6e 73 74 20  te_see(.  const 
34a30 63 68 61 72 20 2a 7a 50 61 73 73 50 68 72 61 73  char *zPassPhras
34a40 65 20 20 20 20 20 20 20 20 2f 2a 20 41 63 74 69  e        /* Acti
34a50 76 61 74 69 6f 6e 20 70 68 72 61 73 65 20 2a 2f  vation phrase */
34a60 0a 29 3b 0a 23 65 6e 64 69 66 0a 0a 23 69 66 64  .);.#endif..#ifd
34a70 65 66 20 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  ef SQLITE_ENABLE
34a80 5f 43 45 52 4f 44 0a 2f 2a 0a 2a 2a 20 53 70 65  _CEROD./*.** Spe
34a90 63 69 66 79 20 74 68 65 20 61 63 74 69 76 61 74  cify the activat
34aa0 69 6f 6e 20 6b 65 79 20 66 6f 72 20 61 20 43 45  ion key for a CE
34ab0 52 4f 44 20 64 61 74 61 62 61 73 65 2e 20 20 55  ROD database.  U
34ac0 6e 6c 65 73 73 20 0a 2a 2a 20 61 63 74 69 76 61  nless .** activa
34ad0 74 65 64 2c 20 6e 6f 6e 65 20 6f 66 20 74 68 65  ted, none of the
34ae0 20 43 45 52 4f 44 20 72 6f 75 74 69 6e 65 73 20   CEROD routines 
34af0 77 69 6c 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a 76 6f  will work..*/.vo
34b00 69 64 20 73 71 6c 69 74 65 33 5f 61 63 74 69 76  id sqlite3_activ
34b10 61 74 65 5f 63 65 72 6f 64 28 0a 20 20 63 6f 6e  ate_cerod(.  con
34b20 73 74 20 63 68 61 72 20 2a 7a 50 61 73 73 50 68  st char *zPassPh
34b30 72 61 73 65 20 20 20 20 20 20 20 20 2f 2a 20 41  rase        /* A
34b40 63 74 69 76 61 74 69 6f 6e 20 70 68 72 61 73 65  ctivation phrase
34b50 20 2a 2f 0a 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f   */.);.#endif../
34b60 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
34b70 75 73 70 65 6e 64 20 45 78 65 63 75 74 69 6f 6e  uspend Execution
34b80 20 46 6f 72 20 41 20 53 68 6f 72 74 20 54 69 6d   For A Short Tim
34b90 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  e.**.** The sqli
34ba0 74 65 33 5f 73 6c 65 65 70 28 29 20 66 75 6e 63  te3_sleep() func
34bb0 74 69 6f 6e 20 63 61 75 73 65 73 20 74 68 65 20  tion causes the 
34bc0 63 75 72 72 65 6e 74 20 74 68 72 65 61 64 20 74  current thread t
34bd0 6f 20 73 75 73 70 65 6e 64 20 65 78 65 63 75 74  o suspend execut
34be0 69 6f 6e 0a 2a 2a 20 66 6f 72 20 61 74 20 6c 65  ion.** for at le
34bf0 61 73 74 20 61 20 6e 75 6d 62 65 72 20 6f 66 20  ast a number of 
34c00 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 73 70 65  milliseconds spe
34c10 63 69 66 69 65 64 20 69 6e 20 69 74 73 20 70 61  cified in its pa
34c20 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49  rameter..**.** I
34c30 66 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20  f the operating 
34c40 73 79 73 74 65 6d 20 64 6f 65 73 20 6e 6f 74 20  system does not 
34c50 73 75 70 70 6f 72 74 20 73 6c 65 65 70 20 72 65  support sleep re
34c60 71 75 65 73 74 73 20 77 69 74 68 0a 2a 2a 20 6d  quests with.** m
34c70 69 6c 6c 69 73 65 63 6f 6e 64 20 74 69 6d 65 20  illisecond time 
34c80 72 65 73 6f 6c 75 74 69 6f 6e 2c 20 74 68 65 6e  resolution, then
34c90 20 74 68 65 20 74 69 6d 65 20 77 69 6c 6c 20 62   the time will b
34ca0 65 20 72 6f 75 6e 64 65 64 20 75 70 20 74 6f 0a  e rounded up to.
34cb0 2a 2a 20 74 68 65 20 6e 65 61 72 65 73 74 20 73  ** the nearest s
34cc0 65 63 6f 6e 64 2e 20 54 68 65 20 6e 75 6d 62 65  econd. The numbe
34cd0 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  r of millisecond
34ce0 73 20 6f 66 20 73 6c 65 65 70 20 61 63 74 75 61  s of sleep actua
34cf0 6c 6c 79 0a 2a 2a 20 72 65 71 75 65 73 74 65 64  lly.** requested
34d00 20 66 72 6f 6d 20 74 68 65 20 6f 70 65 72 61 74   from the operat
34d10 69 6e 67 20 73 79 73 74 65 6d 20 69 73 20 72 65  ing system is re
34d20 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53  turned..**.** ^S
34d30 51 4c 69 74 65 20 69 6d 70 6c 65 6d 65 6e 74 73  QLite implements
34d40 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   this interface 
34d50 62 79 20 63 61 6c 6c 69 6e 67 20 74 68 65 20 78  by calling the x
34d60 53 6c 65 65 70 28 29 0a 2a 2a 20 6d 65 74 68 6f  Sleep().** metho
34d70 64 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74  d of the default
34d80 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f   [sqlite3_vfs] o
34d90 62 6a 65 63 74 2e 20 20 49 66 20 74 68 65 20 78  bject.  If the x
34da0 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 0a 2a  Sleep() method.*
34db0 2a 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74  * of the default
34dc0 20 56 46 53 20 69 73 20 6e 6f 74 20 69 6d 70 6c   VFS is not impl
34dd0 65 6d 65 6e 74 65 64 20 63 6f 72 72 65 63 74 6c  emented correctl
34de0 79 2c 20 6f 72 20 6e 6f 74 20 69 6d 70 6c 65 6d  y, or not implem
34df0 65 6e 74 65 64 20 61 74 0a 2a 2a 20 61 6c 6c 2c  ented at.** all,
34e00 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
34e10 6f 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6c  or of sqlite3_sl
34e20 65 65 70 28 29 20 6d 61 79 20 64 65 76 69 61 74  eep() may deviat
34e30 65 20 66 72 6f 6d 20 74 68 65 20 64 65 73 63 72  e from the descr
34e40 69 70 74 69 6f 6e 0a 2a 2a 20 69 6e 20 74 68 65  iption.** in the
34e50 20 70 72 65 76 69 6f 75 73 20 70 61 72 61 67 72   previous paragr
34e60 61 70 68 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  aphs..*/.int sql
34e70 69 74 65 33 5f 73 6c 65 65 70 28 69 6e 74 29 3b  ite3_sleep(int);
34e80 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
34e90 3a 20 4e 61 6d 65 20 4f 66 20 54 68 65 20 46 6f  : Name Of The Fo
34ea0 6c 64 65 72 20 48 6f 6c 64 69 6e 67 20 54 65 6d  lder Holding Tem
34eb0 70 6f 72 61 72 79 20 46 69 6c 65 73 0a 2a 2a 0a  porary Files.**.
34ec0 2a 2a 20 5e 28 49 66 20 74 68 69 73 20 67 6c 6f  ** ^(If this glo
34ed0 62 61 6c 20 76 61 72 69 61 62 6c 65 20 69 73 20  bal variable is 
34ee0 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f  made to point to
34ef0 20 61 20 73 74 72 69 6e 67 20 77 68 69 63 68 20   a string which 
34f00 69 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f  is.** the name o
34f10 66 20 61 20 66 6f 6c 64 65 72 20 28 61 2e 6b 2e  f a folder (a.k.
34f20 61 2e 20 64 69 72 65 63 74 6f 72 79 29 2c 20 74  a. directory), t
34f30 68 65 6e 20 61 6c 6c 20 74 65 6d 70 6f 72 61 72  hen all temporar
34f40 79 20 66 69 6c 65 73 0a 2a 2a 20 63 72 65 61 74  y files.** creat
34f50 65 64 20 62 79 20 53 51 4c 69 74 65 20 77 68 65  ed by SQLite whe
34f60 6e 20 75 73 69 6e 67 20 61 20 62 75 69 6c 74 2d  n using a built-
34f70 69 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20  in [sqlite3_vfs 
34f80 7c 20 56 46 53 5d 0a 2a 2a 20 77 69 6c 6c 20 62  | VFS].** will b
34f90 65 20 70 6c 61 63 65 64 20 69 6e 20 74 68 61 74  e placed in that
34fa0 20 64 69 72 65 63 74 6f 72 79 2e 29 5e 20 20 5e   directory.)^  ^
34fb0 49 66 20 74 68 69 73 20 76 61 72 69 61 62 6c 65  If this variable
34fc0 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  .** is a NULL po
34fd0 69 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 4c 69  inter, then SQLi
34fe0 74 65 20 70 65 72 66 6f 72 6d 73 20 61 20 73 65  te performs a se
34ff0 61 72 63 68 20 66 6f 72 20 61 6e 20 61 70 70 72  arch for an appr
35000 6f 70 72 69 61 74 65 0a 2a 2a 20 74 65 6d 70 6f  opriate.** tempo
35010 72 61 72 79 20 66 69 6c 65 20 64 69 72 65 63 74  rary file direct
35020 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73  ory..**.** It is
35030 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 72 65 61   not safe to rea
35040 64 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73  d or modify this
35050 20 76 61 72 69 61 62 6c 65 20 69 6e 20 6d 6f 72   variable in mor
35060 65 20 74 68 61 6e 20 6f 6e 65 0a 2a 2a 20 74 68  e than one.** th
35070 72 65 61 64 20 61 74 20 61 20 74 69 6d 65 2e 20  read at a time. 
35080 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20   It is not safe 
35090 74 6f 20 72 65 61 64 20 6f 72 20 6d 6f 64 69 66  to read or modif
350a0 79 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 0a  y this variable.
350b0 2a 2a 20 69 66 20 61 20 5b 64 61 74 61 62 61 73  ** if a [databas
350c0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73  e connection] is
350d0 20 62 65 69 6e 67 20 75 73 65 64 20 61 74 20 74   being used at t
350e0 68 65 20 73 61 6d 65 20 74 69 6d 65 20 69 6e 20  he same time in 
350f0 61 20 73 65 70 61 72 61 74 65 0a 2a 2a 20 74 68  a separate.** th
35100 72 65 61 64 2e 0a 2a 2a 20 49 74 20 69 73 20 69  read..** It is i
35110 6e 74 65 6e 64 65 64 20 74 68 61 74 20 74 68 69  ntended that thi
35120 73 20 76 61 72 69 61 62 6c 65 20 62 65 20 73 65  s variable be se
35130 74 20 6f 6e 63 65 0a 2a 2a 20 61 73 20 70 61 72  t once.** as par
35140 74 20 6f 66 20 70 72 6f 63 65 73 73 20 69 6e 69  t of process ini
35150 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 20  tialization and 
35160 62 65 66 6f 72 65 20 61 6e 79 20 53 51 4c 69 74  before any SQLit
35170 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72  e interface.** r
35180 6f 75 74 69 6e 65 73 20 68 61 76 65 20 62 65 65  outines have bee
35190 6e 20 63 61 6c 6c 65 64 20 61 6e 64 20 74 68 61  n called and tha
351a0 74 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20  t this variable 
351b0 72 65 6d 61 69 6e 20 75 6e 63 68 61 6e 67 65 64  remain unchanged
351c0 0a 2a 2a 20 74 68 65 72 65 61 66 74 65 72 2e 0a  .** thereafter..
351d0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 74 65 6d 70  **.** ^The [temp
351e0 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79  _store_directory
351f0 20 70 72 61 67 6d 61 5d 20 6d 61 79 20 6d 6f 64   pragma] may mod
35200 69 66 79 20 74 68 69 73 20 76 61 72 69 61 62 6c  ify this variabl
35210 65 20 61 6e 64 20 63 61 75 73 65 0a 2a 2a 20 69  e and cause.** i
35220 74 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 6d 65  t to point to me
35230 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72  mory obtained fr
35240 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
35250 6f 63 5d 2e 20 20 5e 46 75 72 74 68 65 72 6d 6f  oc].  ^Furthermo
35260 72 65 2c 0a 2a 2a 20 74 68 65 20 5b 74 65 6d 70  re,.** the [temp
35270 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79  _store_directory
35280 20 70 72 61 67 6d 61 5d 20 61 6c 77 61 79 73 20   pragma] always 
35290 61 73 73 75 6d 65 73 20 74 68 61 74 20 61 6e 79  assumes that any
352a0 20 73 74 72 69 6e 67 0a 2a 2a 20 74 68 61 74 20   string.** that 
352b0 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 70 6f  this variable po
352c0 69 6e 74 73 20 74 6f 20 69 73 20 68 65 6c 64 20  ints to is held 
352d0 69 6e 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e  in memory obtain
352e0 65 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c  ed from .** [sql
352f0 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 20 61 6e 64  ite3_malloc] and
35300 20 74 68 65 20 70 72 61 67 6d 61 20 6d 61 79 20   the pragma may 
35310 61 74 74 65 6d 70 74 20 74 6f 20 66 72 65 65 20  attempt to free 
35320 74 68 61 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 75  that memory.** u
35330 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72  sing [sqlite3_fr
35340 65 65 5d 2e 0a 2a 2a 20 48 65 6e 63 65 2c 20 69  ee]..** Hence, i
35350 66 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20  f this variable 
35360 69 73 20 6d 6f 64 69 66 69 65 64 20 64 69 72 65  is modified dire
35370 63 74 6c 79 2c 20 65 69 74 68 65 72 20 69 74 20  ctly, either it 
35380 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 6d 61 64  should be.** mad
35390 65 20 4e 55 4c 4c 20 6f 72 20 6d 61 64 65 20 74  e NULL or made t
353a0 6f 20 70 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72  o point to memor
353b0 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
353c0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d  [sqlite3_malloc]
353d0 0a 2a 2a 20 6f 72 20 65 6c 73 65 20 74 68 65 20  .** or else the 
353e0 75 73 65 20 6f 66 20 74 68 65 20 5b 74 65 6d 70  use of the [temp
353f0 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79  _store_directory
35400 20 70 72 61 67 6d 61 5d 20 73 68 6f 75 6c 64 20   pragma] should 
35410 62 65 20 61 76 6f 69 64 65 64 2e 0a 2a 2a 0a 2a  be avoided..**.*
35420 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e  * <b>Note to Win
35430 64 6f 77 73 20 52 75 6e 74 69 6d 65 20 75 73 65  dows Runtime use
35440 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 74 65 6d  rs:</b>  The tem
35450 70 6f 72 61 72 79 20 64 69 72 65 63 74 6f 72 79  porary directory
35460 20 6d 75 73 74 20 62 65 20 73 65 74 0a 2a 2a 20   must be set.** 
35470 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67  prior to calling
35480 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5d 20   [sqlite3_open] 
35490 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  or [sqlite3_open
354a0 5f 76 32 5d 2e 20 20 4f 74 68 65 72 77 69 73 65  _v2].  Otherwise
354b0 2c 20 76 61 72 69 6f 75 73 0a 2a 2a 20 66 65 61  , various.** fea
354c0 74 75 72 65 73 20 74 68 61 74 20 72 65 71 75 69  tures that requi
354d0 72 65 20 74 68 65 20 75 73 65 20 6f 66 20 74 65  re the use of te
354e0 6d 70 6f 72 61 72 79 20 66 69 6c 65 73 20 6d 61  mporary files ma
354f0 79 20 66 61 69 6c 2e 20 20 48 65 72 65 20 69 73  y fail.  Here is
35500 20 61 6e 0a 2a 2a 20 65 78 61 6d 70 6c 65 20 6f   an.** example o
35510 66 20 68 6f 77 20 74 6f 20 64 6f 20 74 68 69 73  f how to do this
35520 20 75 73 69 6e 67 20 43 2b 2b 20 77 69 74 68 20   using C++ with 
35530 74 68 65 20 57 69 6e 64 6f 77 73 20 52 75 6e 74  the Windows Runt
35540 69 6d 65 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ime:.**.** <bloc
35550 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
35560 4c 50 43 57 53 54 52 20 7a 50 61 74 68 20 3d 20  LPCWSTR zPath = 
35570 57 69 6e 64 6f 77 73 3a 3a 53 74 6f 72 61 67 65  Windows::Storage
35580 3a 3a 41 70 70 6c 69 63 61 74 69 6f 6e 44 61 74  ::ApplicationDat
35590 61 3a 3a 43 75 72 72 65 6e 74 2d 3e 0a 2a 2a 20  a::Current->.** 
355a0 26 6e 62 73 70 3b 20 20 20 20 20 54 65 6d 70 6f  &nbsp;     Tempo
355b0 72 61 72 79 46 6f 6c 64 65 72 2d 3e 50 61 74 68  raryFolder->Path
355c0 2d 3e 44 61 74 61 28 29 3b 0a 2a 2a 20 63 68 61  ->Data();.** cha
355d0 72 20 7a 50 61 74 68 42 75 66 26 23 39 31 3b 4d  r zPathBuf&#91;M
355e0 41 58 5f 50 41 54 48 20 2b 20 31 26 23 39 33 3b  AX_PATH + 1&#93;
355f0 3b 0a 2a 2a 20 6d 65 6d 73 65 74 28 7a 50 61 74  ;.** memset(zPat
35600 68 42 75 66 2c 20 30 2c 20 73 69 7a 65 6f 66 28  hBuf, 0, sizeof(
35610 7a 50 61 74 68 42 75 66 29 29 3b 0a 2a 2a 20 57  zPathBuf));.** W
35620 69 64 65 43 68 61 72 54 6f 4d 75 6c 74 69 42 79  ideCharToMultiBy
35630 74 65 28 43 50 5f 55 54 46 38 2c 20 30 2c 20 7a  te(CP_UTF8, 0, z
35640 50 61 74 68 2c 20 2d 31 2c 20 7a 50 61 74 68 42  Path, -1, zPathB
35650 75 66 2c 20 73 69 7a 65 6f 66 28 7a 50 61 74 68  uf, sizeof(zPath
35660 42 75 66 29 2c 0a 2a 2a 20 26 6e 62 73 70 3b 20  Buf),.** &nbsp; 
35670 20 20 20 20 4e 55 4c 4c 2c 20 4e 55 4c 4c 29 3b      NULL, NULL);
35680 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 74 65 6d 70  .** sqlite3_temp
35690 5f 64 69 72 65 63 74 6f 72 79 20 3d 20 73 71 6c  _directory = sql
356a0 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 25 73  ite3_mprintf("%s
356b0 22 2c 20 7a 50 61 74 68 42 75 66 29 3b 0a 2a 2a  ", zPathBuf);.**
356c0 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
356d0 6f 74 65 3e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45  ote>.*/.SQLITE_E
356e0 58 54 45 52 4e 20 63 68 61 72 20 2a 73 71 6c 69  XTERN char *sqli
356f0 74 65 33 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f  te3_temp_directo
35700 72 79 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  ry;../*.** CAPI3
35710 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 54 68 65  REF: Name Of The
35720 20 46 6f 6c 64 65 72 20 48 6f 6c 64 69 6e 67 20   Folder Holding 
35730 44 61 74 61 62 61 73 65 20 46 69 6c 65 73 0a 2a  Database Files.*
35740 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 69 73 20 67  *.** ^(If this g
35750 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 20 69  lobal variable i
35760 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20  s made to point 
35770 74 6f 20 61 20 73 74 72 69 6e 67 20 77 68 69 63  to a string whic
35780 68 20 69 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65  h is.** the name
35790 20 6f 66 20 61 20 66 6f 6c 64 65 72 20 28 61 2e   of a folder (a.
357a0 6b 2e 61 2e 20 64 69 72 65 63 74 6f 72 79 29 2c  k.a. directory),
357b0 20 74 68 65 6e 20 61 6c 6c 20 64 61 74 61 62 61   then all databa
357c0 73 65 20 66 69 6c 65 73 0a 2a 2a 20 73 70 65 63  se files.** spec
357d0 69 66 69 65 64 20 77 69 74 68 20 61 20 72 65 6c  ified with a rel
357e0 61 74 69 76 65 20 70 61 74 68 6e 61 6d 65 20 61  ative pathname a
357f0 6e 64 20 63 72 65 61 74 65 64 20 6f 72 20 61 63  nd created or ac
35800 63 65 73 73 65 64 20 62 79 0a 2a 2a 20 53 51 4c  cessed by.** SQL
35810 69 74 65 20 77 68 65 6e 20 75 73 69 6e 67 20 61  ite when using a
35820 20 62 75 69 6c 74 2d 69 6e 20 77 69 6e 64 6f 77   built-in window
35830 73 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c  s [sqlite3_vfs |
35840 20 56 46 53 5d 20 77 69 6c 6c 20 62 65 20 61 73   VFS] will be as
35850 73 75 6d 65 64 0a 2a 2a 20 74 6f 20 62 65 20 72  sumed.** to be r
35860 65 6c 61 74 69 76 65 20 74 6f 20 74 68 61 74 20  elative to that 
35870 64 69 72 65 63 74 6f 72 79 2e 29 5e 20 5e 49 66  directory.)^ ^If
35880 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 69   this variable i
35890 73 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e  s a NULL.** poin
358a0 74 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  ter, then SQLite
358b0 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 61 6c   assumes that al
358c0 6c 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 73  l database files
358d0 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 77 69   specified.** wi
358e0 74 68 20 61 20 72 65 6c 61 74 69 76 65 20 70 61  th a relative pa
358f0 74 68 6e 61 6d 65 20 61 72 65 20 72 65 6c 61 74  thname are relat
35900 69 76 65 20 74 6f 20 74 68 65 20 63 75 72 72 65  ive to the curre
35910 6e 74 20 64 69 72 65 63 74 6f 72 79 0a 2a 2a 20  nt directory.** 
35920 66 6f 72 20 74 68 65 20 70 72 6f 63 65 73 73 2e  for the process.
35930 20 20 4f 6e 6c 79 20 74 68 65 20 77 69 6e 64 6f    Only the windo
35940 77 73 20 56 46 53 20 6d 61 6b 65 73 20 75 73 65  ws VFS makes use
35950 20 6f 66 20 74 68 69 73 20 67 6c 6f 62 61 6c 0a   of this global.
35960 2a 2a 20 76 61 72 69 61 62 6c 65 3b 20 69 74 20  ** variable; it 
35970 69 73 20 69 67 6e 6f 72 65 64 20 62 79 20 74 68  is ignored by th
35980 65 20 75 6e 69 78 20 56 46 53 2e 0a 2a 2a 0a 2a  e unix VFS..**.*
35990 2a 20 43 68 61 6e 67 69 6e 67 20 74 68 65 20 76  * Changing the v
359a0 61 6c 75 65 20 6f 66 20 74 68 69 73 20 76 61 72  alue of this var
359b0 69 61 62 6c 65 20 77 68 69 6c 65 20 61 20 64 61  iable while a da
359c0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
359d0 6e 20 69 73 0a 2a 2a 20 6f 70 65 6e 20 63 61 6e  n is.** open can
359e0 20 72 65 73 75 6c 74 20 69 6e 20 61 20 63 6f 72   result in a cor
359f0 72 75 70 74 20 64 61 74 61 62 61 73 65 2e 0a 2a  rupt database..*
35a00 2a 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73  *.** It is not s
35a10 61 66 65 20 74 6f 20 72 65 61 64 20 6f 72 20 6d  afe to read or m
35a20 6f 64 69 66 79 20 74 68 69 73 20 76 61 72 69 61  odify this varia
35a30 62 6c 65 20 69 6e 20 6d 6f 72 65 20 74 68 61 6e  ble in more than
35a40 20 6f 6e 65 0a 2a 2a 20 74 68 72 65 61 64 20 61   one.** thread a
35a50 74 20 61 20 74 69 6d 65 2e 20 20 49 74 20 69 73  t a time.  It is
35a60 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 72 65 61   not safe to rea
35a70 64 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73  d or modify this
35a80 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 69 66 20   variable.** if 
35a90 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  a [database conn
35aa0 65 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67  ection] is being
35ab0 20 75 73 65 64 20 61 74 20 74 68 65 20 73 61 6d   used at the sam
35ac0 65 20 74 69 6d 65 20 69 6e 20 61 20 73 65 70 61  e time in a sepa
35ad0 72 61 74 65 0a 2a 2a 20 74 68 72 65 61 64 2e 0a  rate.** thread..
35ae0 2a 2a 20 49 74 20 69 73 20 69 6e 74 65 6e 64 65  ** It is intende
35af0 64 20 74 68 61 74 20 74 68 69 73 20 76 61 72 69  d that this vari
35b00 61 62 6c 65 20 62 65 20 73 65 74 20 6f 6e 63 65  able be set once
35b10 0a 2a 2a 20 61 73 20 70 61 72 74 20 6f 66 20 70  .** as part of p
35b20 72 6f 63 65 73 73 20 69 6e 69 74 69 61 6c 69 7a  rocess initializ
35b30 61 74 69 6f 6e 20 61 6e 64 20 62 65 66 6f 72 65  ation and before
35b40 20 61 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 65   any SQLite inte
35b50 72 66 61 63 65 0a 2a 2a 20 72 6f 75 74 69 6e 65  rface.** routine
35b60 73 20 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c  s have been call
35b70 65 64 20 61 6e 64 20 74 68 61 74 20 74 68 69 73  ed and that this
35b80 20 76 61 72 69 61 62 6c 65 20 72 65 6d 61 69 6e   variable remain
35b90 20 75 6e 63 68 61 6e 67 65 64 0a 2a 2a 20 74 68   unchanged.** th
35ba0 65 72 65 61 66 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  ereafter..**.** 
35bb0 5e 54 68 65 20 5b 64 61 74 61 5f 73 74 6f 72 65  ^The [data_store
35bc0 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d  _directory pragm
35bd0 61 5d 20 6d 61 79 20 6d 6f 64 69 66 79 20 74 68  a] may modify th
35be0 69 73 20 76 61 72 69 61 62 6c 65 20 61 6e 64 20  is variable and 
35bf0 63 61 75 73 65 0a 2a 2a 20 69 74 20 74 6f 20 70  cause.** it to p
35c00 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72 79 20 6f  oint to memory o
35c10 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
35c20 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 2e 20 20  lite3_malloc].  
35c30 5e 46 75 72 74 68 65 72 6d 6f 72 65 2c 0a 2a 2a  ^Furthermore,.**
35c40 20 74 68 65 20 5b 64 61 74 61 5f 73 74 6f 72 65   the [data_store
35c50 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d  _directory pragm
35c60 61 5d 20 61 6c 77 61 79 73 20 61 73 73 75 6d 65  a] always assume
35c70 73 20 74 68 61 74 20 61 6e 79 20 73 74 72 69 6e  s that any strin
35c80 67 0a 2a 2a 20 74 68 61 74 20 74 68 69 73 20 76  g.** that this v
35c90 61 72 69 61 62 6c 65 20 70 6f 69 6e 74 73 20 74  ariable points t
35ca0 6f 20 69 73 20 68 65 6c 64 20 69 6e 20 6d 65 6d  o is held in mem
35cb0 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ory obtained fro
35cc0 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  m .** [sqlite3_m
35cd0 61 6c 6c 6f 63 5d 20 61 6e 64 20 74 68 65 20 70  alloc] and the p
35ce0 72 61 67 6d 61 20 6d 61 79 20 61 74 74 65 6d 70  ragma may attemp
35cf0 74 20 74 6f 20 66 72 65 65 20 74 68 61 74 20 6d  t to free that m
35d00 65 6d 6f 72 79 0a 2a 2a 20 75 73 69 6e 67 20 5b  emory.** using [
35d10 73 71 6c 69 74 65 33 5f 66 72 65 65 5d 2e 0a 2a  sqlite3_free]..*
35d20 2a 20 48 65 6e 63 65 2c 20 69 66 20 74 68 69 73  * Hence, if this
35d30 20 76 61 72 69 61 62 6c 65 20 69 73 20 6d 6f 64   variable is mod
35d40 69 66 69 65 64 20 64 69 72 65 63 74 6c 79 2c 20  ified directly, 
35d50 65 69 74 68 65 72 20 69 74 20 73 68 6f 75 6c 64  either it should
35d60 20 62 65 0a 2a 2a 20 6d 61 64 65 20 4e 55 4c 4c   be.** made NULL
35d70 20 6f 72 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e   or made to poin
35d80 74 20 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61  t to memory obta
35d90 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  ined from [sqlit
35da0 65 33 5f 6d 61 6c 6c 6f 63 5d 0a 2a 2a 20 6f 72  e3_malloc].** or
35db0 20 65 6c 73 65 20 74 68 65 20 75 73 65 20 6f 66   else the use of
35dc0 20 74 68 65 20 5b 64 61 74 61 5f 73 74 6f 72 65   the [data_store
35dd0 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d  _directory pragm
35de0 61 5d 20 73 68 6f 75 6c 64 20 62 65 20 61 76 6f  a] should be avo
35df0 69 64 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  ided..*/.SQLITE_
35e00 45 58 54 45 52 4e 20 63 68 61 72 20 2a 73 71 6c  EXTERN char *sql
35e10 69 74 65 33 5f 64 61 74 61 5f 64 69 72 65 63 74  ite3_data_direct
35e20 6f 72 79 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ory;../*.** CAPI
35e30 33 52 45 46 3a 20 54 65 73 74 20 46 6f 72 20 41  3REF: Test For A
35e40 75 74 6f 2d 43 6f 6d 6d 69 74 20 4d 6f 64 65 0a  uto-Commit Mode.
35e50 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 75  ** KEYWORDS: {au
35e60 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 7d 0a 2a  tocommit mode}.*
35e70 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
35e80 33 5f 67 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74  3_get_autocommit
35e90 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  () interface ret
35ea0 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 20 6f 72  urns non-zero or
35eb0 0a 2a 2a 20 7a 65 72 6f 20 69 66 20 74 68 65 20  .** zero if the 
35ec0 67 69 76 65 6e 20 64 61 74 61 62 61 73 65 20 63  given database c
35ed0 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 72 20  onnection is or 
35ee0 69 73 20 6e 6f 74 20 69 6e 20 61 75 74 6f 63 6f  is not in autoco
35ef0 6d 6d 69 74 20 6d 6f 64 65 2c 0a 2a 2a 20 72 65  mmit mode,.** re
35f00 73 70 65 63 74 69 76 65 6c 79 2e 20 20 5e 41 75  spectively.  ^Au
35f10 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73  tocommit mode is
35f20 20 6f 6e 20 62 79 20 64 65 66 61 75 6c 74 2e 0a   on by default..
35f30 2a 2a 20 5e 41 75 74 6f 63 6f 6d 6d 69 74 20 6d  ** ^Autocommit m
35f40 6f 64 65 20 69 73 20 64 69 73 61 62 6c 65 64 20  ode is disabled 
35f50 62 79 20 61 20 5b 42 45 47 49 4e 5d 20 73 74 61  by a [BEGIN] sta
35f60 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 41 75 74 6f  tement..** ^Auto
35f70 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 72  commit mode is r
35f80 65 2d 65 6e 61 62 6c 65 64 20 62 79 20 61 20 5b  e-enabled by a [
35f90 43 4f 4d 4d 49 54 5d 20 6f 72 20 5b 52 4f 4c 4c  COMMIT] or [ROLL
35fa0 42 41 43 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  BACK]..**.** If 
35fb0 63 65 72 74 61 69 6e 20 6b 69 6e 64 73 20 6f 66  certain kinds of
35fc0 20 65 72 72 6f 72 73 20 6f 63 63 75 72 20 6f 6e   errors occur on
35fd0 20 61 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74   a statement wit
35fe0 68 69 6e 20 61 20 6d 75 6c 74 69 2d 73 74 61 74  hin a multi-stat
35ff0 65 6d 65 6e 74 0a 2a 2a 20 74 72 61 6e 73 61 63  ement.** transac
36000 74 69 6f 6e 20 28 65 72 72 6f 72 73 20 69 6e 63  tion (errors inc
36010 6c 75 64 69 6e 67 20 5b 53 51 4c 49 54 45 5f 46  luding [SQLITE_F
36020 55 4c 4c 5d 2c 20 5b 53 51 4c 49 54 45 5f 49 4f  ULL], [SQLITE_IO
36030 45 52 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  ERR],.** [SQLITE
36040 5f 4e 4f 4d 45 4d 5d 2c 20 5b 53 51 4c 49 54 45  _NOMEM], [SQLITE
36050 5f 42 55 53 59 5d 2c 20 61 6e 64 20 5b 53 51 4c  _BUSY], and [SQL
36060 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 29 20  ITE_INTERRUPT]) 
36070 74 68 65 6e 20 74 68 65 0a 2a 2a 20 74 72 61 6e  then the.** tran
36080 73 61 63 74 69 6f 6e 20 6d 69 67 68 74 20 62 65  saction might be
36090 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74   rolled back aut
360a0 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 54 68 65  omatically.  The
360b0 20 6f 6e 6c 79 20 77 61 79 20 74 6f 0a 2a 2a 20   only way to.** 
360c0 66 69 6e 64 20 6f 75 74 20 77 68 65 74 68 65 72  find out whether
360d0 20 53 51 4c 69 74 65 20 61 75 74 6f 6d 61 74 69   SQLite automati
360e0 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63  cally rolled bac
360f0 6b 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f  k the transactio
36100 6e 20 61 66 74 65 72 0a 2a 2a 20 61 6e 20 65 72  n after.** an er
36110 72 6f 72 20 69 73 20 74 6f 20 75 73 65 20 74 68  ror is to use th
36120 69 73 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a  is function..**.
36130 2a 2a 20 49 66 20 61 6e 6f 74 68 65 72 20 74 68  ** If another th
36140 72 65 61 64 20 63 68 61 6e 67 65 73 20 74 68 65  read changes the
36150 20 61 75 74 6f 63 6f 6d 6d 69 74 20 73 74 61 74   autocommit stat
36160 75 73 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  us of the databa
36170 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  se.** connection
36180 20 77 68 69 6c 65 20 74 68 69 73 20 72 6f 75 74   while this rout
36190 69 6e 65 20 69 73 20 72 75 6e 6e 69 6e 67 2c 20  ine is running, 
361a0 74 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20  then the return 
361b0 76 61 6c 75 65 0a 2a 2a 20 69 73 20 75 6e 64 65  value.** is unde
361c0 66 69 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71  fined..*/.int sq
361d0 6c 69 74 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f  lite3_get_autoco
361e0 6d 6d 69 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a  mmit(sqlite3*);.
361f0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
36200 20 46 69 6e 64 20 54 68 65 20 44 61 74 61 62 61   Find The Databa
36210 73 65 20 48 61 6e 64 6c 65 20 4f 66 20 41 20 50  se Handle Of A P
36220 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
36230 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  t.**.** ^The sql
36240 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 20 69  ite3_db_handle i
36250 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
36260 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
36270 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c  onnection] handl
36280 65 0a 2a 2a 20 74 6f 20 77 68 69 63 68 20 61 20  e.** to which a 
36290 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
362a0 65 6e 74 5d 20 62 65 6c 6f 6e 67 73 2e 20 20 5e  ent] belongs.  ^
362b0 54 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  The [database co
362c0 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 72 65 74  nnection].** ret
362d0 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
362e0 5f 64 62 5f 68 61 6e 64 6c 65 20 69 73 20 74 68  _db_handle is th
362f0 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65  e same [database
36300 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20   connection].** 
36310 74 68 61 74 20 77 61 73 20 74 68 65 20 66 69 72  that was the fir
36320 73 74 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74  st argument.** t
36330 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70  o the [sqlite3_p
36340 72 65 70 61 72 65 5f 76 32 28 29 5d 20 63 61 6c  repare_v2()] cal
36350 6c 20 28 6f 72 20 69 74 73 20 76 61 72 69 61 6e  l (or its varian
36360 74 73 29 20 74 68 61 74 20 77 61 73 20 75 73 65  ts) that was use
36370 64 20 74 6f 0a 2a 2a 20 63 72 65 61 74 65 20 74  d to.** create t
36380 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20  he statement in 
36390 74 68 65 20 66 69 72 73 74 20 70 6c 61 63 65 2e  the first place.
363a0 0a 2a 2f 0a 73 71 6c 69 74 65 33 20 2a 73 71 6c  .*/.sqlite3 *sql
363b0 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 28 73  ite3_db_handle(s
363c0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a  qlite3_stmt*);..
363d0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
363e0 52 65 74 75 72 6e 20 54 68 65 20 46 69 6c 65 6e  Return The Filen
363f0 61 6d 65 20 46 6f 72 20 41 20 44 61 74 61 62 61  ame For A Databa
36400 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se Connection.**
36410 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
36420 5f 64 62 5f 66 69 6c 65 6e 61 6d 65 28 44 2c 4e  _db_filename(D,N
36430 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
36440 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
36450 20 61 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 61   a filename.** a
36460 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 64  ssociated with d
36470 61 74 61 62 61 73 65 20 4e 20 6f 66 20 63 6f 6e  atabase N of con
36480 6e 65 63 74 69 6f 6e 20 44 2e 20 20 5e 54 68 65  nection D.  ^The
36490 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65 20 66   main database f
364a0 69 6c 65 0a 2a 2a 20 68 61 73 20 74 68 65 20 6e  ile.** has the n
364b0 61 6d 65 20 22 6d 61 69 6e 22 2e 20 20 49 66 20  ame "main".  If 
364c0 74 68 65 72 65 20 69 73 20 6e 6f 20 61 74 74 61  there is no atta
364d0 63 68 65 64 20 64 61 74 61 62 61 73 65 20 4e 20  ched database N 
364e0 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 0a  on the database.
364f0 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2c  ** connection D,
36500 20 6f 72 20 69 66 20 64 61 74 61 62 61 73 65 20   or if database 
36510 4e 20 69 73 20 61 20 74 65 6d 70 6f 72 61 72 79  N is a temporary
36520 20 6f 72 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61   or in-memory da
36530 74 61 62 61 73 65 2c 20 74 68 65 6e 0a 2a 2a 20  tabase, then.** 
36540 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69  a NULL pointer i
36550 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
36560 2a 20 5e 54 68 65 20 66 69 6c 65 6e 61 6d 65 20  * ^The filename 
36570 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73  returned by this
36580 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 68 65   function is the
36590 20 6f 75 74 70 75 74 20 6f 66 20 74 68 65 0a 2a   output of the.*
365a0 2a 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 20  * xFullPathname 
365b0 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 5b 56  method of the [V
365c0 46 53 5d 2e 20 20 5e 49 6e 20 6f 74 68 65 72 20  FS].  ^In other 
365d0 77 6f 72 64 73 2c 20 74 68 65 20 66 69 6c 65 6e  words, the filen
365e0 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 61  ame.** will be a
365f0 6e 20 61 62 73 6f 6c 75 74 65 20 70 61 74 68 6e  n absolute pathn
36600 61 6d 65 2c 20 65 76 65 6e 20 69 66 20 74 68 65  ame, even if the
36610 20 66 69 6c 65 6e 61 6d 65 20 75 73 65 64 0a 2a   filename used.*
36620 2a 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 61  * to open the da
36630 74 61 62 61 73 65 20 6f 72 69 67 69 6e 61 6c 6c  tabase originall
36640 79 20 77 61 73 20 61 20 55 52 49 20 6f 72 20 72  y was a URI or r
36650 65 6c 61 74 69 76 65 20 70 61 74 68 6e 61 6d 65  elative pathname
36660 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20  ..*/.const char 
36670 2a 73 71 6c 69 74 65 33 5f 64 62 5f 66 69 6c 65  *sqlite3_db_file
36680 6e 61 6d 65 28 73 71 6c 69 74 65 33 20 2a 64 62  name(sqlite3 *db
36690 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44  , const char *zD
366a0 62 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  bName);../*.** C
366b0 41 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69  API3REF: Determi
366c0 6e 65 20 69 66 20 61 20 64 61 74 61 62 61 73 65  ne if a database
366d0 20 69 73 20 72 65 61 64 2d 6f 6e 6c 79 0a 2a 2a   is read-only.**
366e0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
366f0 5f 64 62 5f 72 65 61 64 6f 6e 6c 79 28 44 2c 4e  _db_readonly(D,N
36700 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
36710 72 6e 73 20 31 20 69 66 20 74 68 65 20 64 61 74  rns 1 if the dat
36720 61 62 61 73 65 20 4e 0a 2a 2a 20 6f 66 20 63 6f  abase N.** of co
36730 6e 6e 65 63 74 69 6f 6e 20 44 20 69 73 20 72 65  nnection D is re
36740 61 64 2d 6f 6e 6c 79 2c 20 30 20 69 66 20 69 74  ad-only, 0 if it
36750 20 69 73 20 72 65 61 64 2f 77 72 69 74 65 2c 20   is read/write, 
36760 6f 72 20 2d 31 20 69 66 20 4e 20 69 73 20 6e 6f  or -1 if N is no
36770 74 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66  t.** the name of
36780 20 61 20 64 61 74 61 62 61 73 65 20 6f 6e 20 63   a database on c
36790 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 0a 2a 2f 0a  onnection D..*/.
367a0 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 62 5f 72  int sqlite3_db_r
367b0 65 61 64 6f 6e 6c 79 28 73 71 6c 69 74 65 33 20  eadonly(sqlite3 
367c0 2a 64 62 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  *db, const char 
367d0 2a 7a 44 62 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a  *zDbName);../*.*
367e0 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69 6e 64  * CAPI3REF: Find
367f0 20 74 68 65 20 6e 65 78 74 20 70 72 65 70 61 72   the next prepar
36800 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a  ed statement.**.
36810 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65 72 66 61  ** ^This interfa
36820 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ce returns a poi
36830 6e 74 65 72 20 74 6f 20 74 68 65 20 6e 65 78 74  nter to the next
36840 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
36850 6d 65 6e 74 5d 20 61 66 74 65 72 0a 2a 2a 20 70  ment] after.** p
36860 53 74 6d 74 20 61 73 73 6f 63 69 61 74 65 64 20  Stmt associated 
36870 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61  with the [databa
36880 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70  se connection] p
36890 44 62 2e 20 20 5e 49 66 20 70 53 74 6d 74 20 69  Db.  ^If pStmt i
368a0 73 20 4e 55 4c 4c 0a 2a 2a 20 74 68 65 6e 20 74  s NULL.** then t
368b0 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 72 65  his interface re
368c0 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
368d0 74 6f 20 74 68 65 20 66 69 72 73 74 20 70 72 65  to the first pre
368e0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a  pared statement.
368f0 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ** associated wi
36900 74 68 20 74 68 65 20 64 61 74 61 62 61 73 65 20  th the database 
36910 63 6f 6e 6e 65 63 74 69 6f 6e 20 70 44 62 2e 20  connection pDb. 
36920 20 5e 49 66 20 6e 6f 20 70 72 65 70 61 72 65 64   ^If no prepared
36930 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 73 61   statement.** sa
36940 74 69 73 66 69 65 73 20 74 68 65 20 63 6f 6e 64  tisfies the cond
36950 69 74 69 6f 6e 73 20 6f 66 20 74 68 69 73 20 72  itions of this r
36960 6f 75 74 69 6e 65 2c 20 69 74 20 72 65 74 75 72  outine, it retur
36970 6e 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54  ns NULL..**.** T
36980 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
36990 6e 65 63 74 69 6f 6e 5d 20 70 6f 69 6e 74 65 72  nection] pointer
369a0 20 44 20 69 6e 20 61 20 63 61 6c 6c 20 74 6f 0a   D in a call to.
369b0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74  ** [sqlite3_next
369c0 5f 73 74 6d 74 28 44 2c 53 29 5d 20 6d 75 73 74  _stmt(D,S)] must
369d0 20 72 65 66 65 72 20 74 6f 20 61 6e 20 6f 70 65   refer to an ope
369e0 6e 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f  n database.** co
369f0 6e 6e 65 63 74 69 6f 6e 20 61 6e 64 20 69 6e 20  nnection and in 
36a00 70 61 72 74 69 63 75 6c 61 72 20 6d 75 73 74 20  particular must 
36a10 6e 6f 74 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f  not be a NULL po
36a20 69 6e 74 65 72 2e 0a 2a 2f 0a 73 71 6c 69 74 65  inter..*/.sqlite
36a30 33 5f 73 74 6d 74 20 2a 73 71 6c 69 74 65 33 5f  3_stmt *sqlite3_
36a40 6e 65 78 74 5f 73 74 6d 74 28 73 71 6c 69 74 65  next_stmt(sqlite
36a50 33 20 2a 70 44 62 2c 20 73 71 6c 69 74 65 33 5f  3 *pDb, sqlite3_
36a60 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
36a70 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
36a80 6f 6d 6d 69 74 20 41 6e 64 20 52 6f 6c 6c 62 61  ommit And Rollba
36a90 63 6b 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e 20  ck Notification 
36aa0 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20  Callbacks.**.** 
36ab0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d  ^The sqlite3_com
36ac0 6d 69 74 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72  mit_hook() inter
36ad0 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61  face registers a
36ae0 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e   callback.** fun
36af0 63 74 69 6f 6e 20 74 6f 20 62 65 20 69 6e 76 6f  ction to be invo
36b00 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 20 74  ked whenever a t
36b10 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 5b 43  ransaction is [C
36b20 4f 4d 4d 49 54 20 7c 20 63 6f 6d 6d 69 74 74 65  OMMIT | committe
36b30 64 5d 2e 0a 2a 2a 20 5e 41 6e 79 20 63 61 6c 6c  d]..** ^Any call
36b40 62 61 63 6b 20 73 65 74 20 62 79 20 61 20 70 72  back set by a pr
36b50 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 73  evious call to s
36b60 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f  qlite3_commit_ho
36b70 6f 6b 28 29 0a 2a 2a 20 66 6f 72 20 74 68 65 20  ok().** for the 
36b80 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f  same database co
36b90 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76 65 72  nnection is over
36ba0 72 69 64 64 65 6e 2e 0a 2a 2a 20 5e 54 68 65 20  ridden..** ^The 
36bb0 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b  sqlite3_rollback
36bc0 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61 63  _hook() interfac
36bd0 65 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61  e registers a ca
36be0 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69  llback.** functi
36bf0 6f 6e 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64  on to be invoked
36c00 20 77 68 65 6e 65 76 65 72 20 61 20 74 72 61 6e   whenever a tran
36c10 73 61 63 74 69 6f 6e 20 69 73 20 5b 52 4f 4c 4c  saction is [ROLL
36c20 42 41 43 4b 20 7c 20 72 6f 6c 6c 65 64 20 62 61  BACK | rolled ba
36c30 63 6b 5d 2e 0a 2a 2a 20 5e 41 6e 79 20 63 61 6c  ck]..** ^Any cal
36c40 6c 62 61 63 6b 20 73 65 74 20 62 79 20 61 20 70  lback set by a p
36c50 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20  revious call to 
36c60 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b  sqlite3_rollback
36c70 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72 20 74  _hook().** for t
36c80 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
36c90 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f   connection is o
36ca0 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 20 5e 54  verridden..** ^T
36cb0 68 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74  he pArg argument
36cc0 20 69 73 20 70 61 73 73 65 64 20 74 68 72 6f 75   is passed throu
36cd0 67 68 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  gh to the callba
36ce0 63 6b 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 63  ck..** ^If the c
36cf0 61 6c 6c 62 61 63 6b 20 6f 6e 20 61 20 63 6f 6d  allback on a com
36d00 6d 69 74 20 68 6f 6f 6b 20 66 75 6e 63 74 69 6f  mit hook functio
36d10 6e 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65  n returns non-ze
36d20 72 6f 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  ro,.** then the 
36d30 63 6f 6d 6d 69 74 20 69 73 20 63 6f 6e 76 65 72  commit is conver
36d40 74 65 64 20 69 6e 74 6f 20 61 20 72 6f 6c 6c 62  ted into a rollb
36d50 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ack..**.** ^The 
36d60 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68  sqlite3_commit_h
36d70 6f 6f 6b 28 44 2c 43 2c 50 29 20 61 6e 64 20 73  ook(D,C,P) and s
36d80 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f  qlite3_rollback_
36d90 68 6f 6f 6b 28 44 2c 43 2c 50 29 20 66 75 6e 63  hook(D,C,P) func
36da0 74 69 6f 6e 73 0a 2a 2a 20 72 65 74 75 72 6e 20  tions.** return 
36db0 74 68 65 20 50 20 61 72 67 75 6d 65 6e 74 20 66  the P argument f
36dc0 72 6f 6d 20 74 68 65 20 70 72 65 76 69 6f 75 73  rom the previous
36dd0 20 63 61 6c 6c 20 6f 66 20 74 68 65 20 73 61 6d   call of the sam
36de0 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6f 6e  e function.** on
36df0 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62   the same [datab
36e00 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
36e10 44 2c 20 6f 72 20 4e 55 4c 4c 20 66 6f 72 0a 2a  D, or NULL for.*
36e20 2a 20 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c  * the first call
36e30 20 66 6f 72 20 65 61 63 68 20 66 75 6e 63 74 69   for each functi
36e40 6f 6e 20 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a 20 54  on on D..**.** T
36e50 68 65 20 63 6f 6d 6d 69 74 20 61 6e 64 20 72 6f  he commit and ro
36e60 6c 6c 62 61 63 6b 20 68 6f 6f 6b 20 63 61 6c 6c  llback hook call
36e70 62 61 63 6b 73 20 61 72 65 20 6e 6f 74 20 72 65  backs are not re
36e80 65 6e 74 72 61 6e 74 2e 0a 2a 2a 20 54 68 65 20  entrant..** The 
36e90 63 61 6c 6c 62 61 63 6b 20 69 6d 70 6c 65 6d 65  callback impleme
36ea0 6e 74 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  ntation must not
36eb0 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61   do anything tha
36ec0 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a  t will modify.**
36ed0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
36ee0 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e  nnection that in
36ef0 76 6f 6b 65 64 20 74 68 65 20 63 61 6c 6c 62 61  voked the callba
36f00 63 6b 2e 20 20 41 6e 79 20 61 63 74 69 6f 6e 73  ck.  Any actions
36f10 0a 2a 2a 20 74 6f 20 6d 6f 64 69 66 79 20 74 68  .** to modify th
36f20 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
36f30 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 64 65  ction must be de
36f40 66 65 72 72 65 64 20 75 6e 74 69 6c 20 61 66 74  ferred until aft
36f50 65 72 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65  er the.** comple
36f60 74 69 6f 6e 20 6f 66 20 74 68 65 20 5b 73 71 6c  tion of the [sql
36f70 69 74 65 33 5f 73 74 65 70 28 29 5d 20 63 61 6c  ite3_step()] cal
36f80 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64  l that triggered
36f90 20 74 68 65 20 63 6f 6d 6d 69 74 0a 2a 2a 20 6f   the commit.** o
36fa0 72 20 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f 6b 20  r rollback hook 
36fb0 69 6e 20 74 68 65 20 66 69 72 73 74 20 70 6c 61  in the first pla
36fc0 63 65 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  ce..** Note that
36fd0 20 72 75 6e 6e 69 6e 67 20 61 6e 79 20 6f 74 68   running any oth
36fe0 65 72 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  er SQL statement
36ff0 73 2c 20 69 6e 63 6c 75 64 69 6e 67 20 53 45 4c  s, including SEL
37000 45 43 54 20 73 74 61 74 65 6d 65 6e 74 73 2c 0a  ECT statements,.
37010 2a 2a 20 6f 72 20 6d 65 72 65 6c 79 20 63 61 6c  ** or merely cal
37020 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72  ling [sqlite3_pr
37030 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20  epare_v2()] and 
37040 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
37050 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20   will modify.** 
37060 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
37070 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65  nections for the
37080 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64   meaning of "mod
37090 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72  ify" in this par
370a0 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 52  agraph..**.** ^R
370b0 65 67 69 73 74 65 72 69 6e 67 20 61 20 4e 55 4c  egistering a NUL
370c0 4c 20 66 75 6e 63 74 69 6f 6e 20 64 69 73 61 62  L function disab
370d0 6c 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  les the callback
370e0 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 74 68  ..**.** ^When th
370f0 65 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20 63 61  e commit hook ca
37100 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 72  llback routine r
37110 65 74 75 72 6e 73 20 7a 65 72 6f 2c 20 74 68 65  eturns zero, the
37120 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 70 65   [COMMIT].** ope
37130 72 61 74 69 6f 6e 20 69 73 20 61 6c 6c 6f 77 65  ration is allowe
37140 64 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20 6e 6f  d to continue no
37150 72 6d 61 6c 6c 79 2e 20 20 5e 49 66 20 74 68 65  rmally.  ^If the
37160 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 0a 2a 2a 20   commit hook.** 
37170 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f  returns non-zero
37180 2c 20 74 68 65 6e 20 74 68 65 20 5b 43 4f 4d 4d  , then the [COMM
37190 49 54 5d 20 69 73 20 63 6f 6e 76 65 72 74 65 64  IT] is converted
371a0 20 69 6e 74 6f 20 61 20 5b 52 4f 4c 4c 42 41 43   into a [ROLLBAC
371b0 4b 5d 2e 0a 2a 2a 20 5e 54 68 65 20 72 6f 6c 6c  K]..** ^The roll
371c0 62 61 63 6b 20 68 6f 6f 6b 20 69 73 20 69 6e 76  back hook is inv
371d0 6f 6b 65 64 20 6f 6e 20 61 20 72 6f 6c 6c 62 61  oked on a rollba
371e0 63 6b 20 74 68 61 74 20 72 65 73 75 6c 74 73 20  ck that results 
371f0 66 72 6f 6d 20 61 20 63 6f 6d 6d 69 74 0a 2a 2a  from a commit.**
37200 20 68 6f 6f 6b 20 72 65 74 75 72 6e 69 6e 67 20   hook returning 
37210 6e 6f 6e 2d 7a 65 72 6f 2c 20 6a 75 73 74 20 61  non-zero, just a
37220 73 20 69 74 20 77 6f 75 6c 64 20 62 65 20 77 69  s it would be wi
37230 74 68 20 61 6e 79 20 6f 74 68 65 72 20 72 6f 6c  th any other rol
37240 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 46 6f  lback..**.** ^Fo
37250 72 20 74 68 65 20 70 75 72 70 6f 73 65 73 20 6f  r the purposes o
37260 66 20 74 68 69 73 20 41 50 49 2c 20 61 20 74 72  f this API, a tr
37270 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 73 61 69  ansaction is sai
37280 64 20 74 6f 20 68 61 76 65 20 62 65 65 6e 0a 2a  d to have been.*
37290 2a 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 69 66  * rolled back if
372a0 20 61 6e 20 65 78 70 6c 69 63 69 74 20 22 52 4f   an explicit "RO
372b0 4c 4c 42 41 43 4b 22 20 73 74 61 74 65 6d 65 6e  LLBACK" statemen
372c0 74 20 69 73 20 65 78 65 63 75 74 65 64 2c 20 6f  t is executed, o
372d0 72 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20 6f 72  r.** an error or
372e0 20 63 6f 6e 73 74 72 61 69 6e 74 20 63 61 75 73   constraint caus
372f0 65 73 20 61 6e 20 69 6d 70 6c 69 63 69 74 20 72  es an implicit r
37300 6f 6c 6c 62 61 63 6b 20 74 6f 20 6f 63 63 75 72  ollback to occur
37310 2e 0a 2a 2a 20 5e 54 68 65 20 72 6f 6c 6c 62 61  ..** ^The rollba
37320 63 6b 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 6e  ck callback is n
37330 6f 74 20 69 6e 76 6f 6b 65 64 20 69 66 20 61 20  ot invoked if a 
37340 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 0a 2a  transaction is.*
37350 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  * automatically 
37360 72 6f 6c 6c 65 64 20 62 61 63 6b 20 62 65 63 61  rolled back beca
37370 75 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65  use the database
37380 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63   connection is c
37390 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  losed..**.** See
373a0 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74   also the [sqlit
373b0 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 29  e3_update_hook()
373c0 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a  ] interface..*/.
373d0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
373e0 6d 6d 69 74 5f 68 6f 6f 6b 28 73 71 6c 69 74 65  mmit_hook(sqlite
373f0 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a  3*, int(*)(void*
37400 29 2c 20 76 6f 69 64 2a 29 3b 0a 76 6f 69 64 20  ), void*);.void 
37410 2a 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63  *sqlite3_rollbac
37420 6b 5f 68 6f 6f 6b 28 73 71 6c 69 74 65 33 2a 2c  k_hook(sqlite3*,
37430 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 20 2a 29   void(*)(void *)
37440 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  , void*);../*.**
37450 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 20   CAPI3REF: Data 
37460 43 68 61 6e 67 65 20 4e 6f 74 69 66 69 63 61 74  Change Notificat
37470 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a  ion Callbacks.**
37480 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
37490 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 29 20 69  _update_hook() i
374a0 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65  nterface registe
374b0 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75  rs a callback fu
374c0 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74 68 20 74  nction.** with t
374d0 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
374e0 6e 65 63 74 69 6f 6e 5d 20 69 64 65 6e 74 69 66  nection] identif
374f0 69 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74  ied by the first
37500 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20   argument.** to 
37510 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65  be invoked whene
37520 76 65 72 20 61 20 72 6f 77 20 69 73 20 75 70 64  ver a row is upd
37530 61 74 65 64 2c 20 69 6e 73 65 72 74 65 64 20 6f  ated, inserted o
37540 72 20 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 5e 41  r deleted..** ^A
37550 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20  ny callback set 
37560 62 79 20 61 20 70 72 65 76 69 6f 75 73 20 63 61  by a previous ca
37570 6c 6c 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74  ll to this funct
37580 69 6f 6e 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73  ion.** for the s
37590 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ame database con
375a0 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76 65 72 72  nection is overr
375b0 69 64 64 65 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  idden..**.** ^Th
375c0 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
375d0 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  t is a pointer t
375e0 6f 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 74  o the function t
375f0 6f 20 69 6e 76 6f 6b 65 20 77 68 65 6e 20 61 0a  o invoke when a.
37600 2a 2a 20 72 6f 77 20 69 73 20 75 70 64 61 74 65  ** row is update
37610 64 2c 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64  d, inserted or d
37620 65 6c 65 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20  eleted..** ^The 
37630 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
37640 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69  o the callback i
37650 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
37660 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 0a 2a  third argument.*
37670 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 75 70 64  * to sqlite3_upd
37680 61 74 65 5f 68 6f 6f 6b 28 29 2e 0a 2a 2a 20 5e  ate_hook()..** ^
37690 54 68 65 20 73 65 63 6f 6e 64 20 63 61 6c 6c 62  The second callb
376a0 61 63 6b 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ack argument is 
376b0 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49  one of [SQLITE_I
376c0 4e 53 45 52 54 5d 2c 20 5b 53 51 4c 49 54 45 5f  NSERT], [SQLITE_
376d0 44 45 4c 45 54 45 5d 2c 0a 2a 2a 20 6f 72 20 5b  DELETE],.** or [
376e0 53 51 4c 49 54 45 5f 55 50 44 41 54 45 5d 2c 20  SQLITE_UPDATE], 
376f0 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65  depending on the
37700 20 6f 70 65 72 61 74 69 6f 6e 20 74 68 61 74 20   operation that 
37710 63 61 75 73 65 64 20 74 68 65 20 63 61 6c 6c 62  caused the callb
37720 61 63 6b 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 76  ack.** to be inv
37730 6f 6b 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 74 68  oked..** ^The th
37740 69 72 64 20 61 6e 64 20 66 6f 75 72 74 68 20 61  ird and fourth a
37750 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 65 20  rguments to the 
37760 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e  callback contain
37770 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 65   pointers to the
37780 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 61 6e 64  .** database and
37790 20 74 61 62 6c 65 20 6e 61 6d 65 20 63 6f 6e 74   table name cont
377a0 61 69 6e 69 6e 67 20 74 68 65 20 61 66 66 65 63  aining the affec
377b0 74 65 64 20 72 6f 77 2e 0a 2a 2a 20 5e 54 68 65  ted row..** ^The
377c0 20 66 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20   final callback 
377d0 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
377e0 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20   [rowid] of the 
377f0 72 6f 77 2e 0a 2a 2a 20 5e 49 6e 20 74 68 65 20  row..** ^In the 
37800 63 61 73 65 20 6f 66 20 61 6e 20 75 70 64 61 74  case of an updat
37810 65 2c 20 74 68 69 73 20 69 73 20 74 68 65 20 5b  e, this is the [
37820 72 6f 77 69 64 5d 20 61 66 74 65 72 20 74 68 65  rowid] after the
37830 20 75 70 64 61 74 65 20 74 61 6b 65 73 20 70 6c   update takes pl
37840 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ace..**.** ^(The
37850 20 75 70 64 61 74 65 20 68 6f 6f 6b 20 69 73 20   update hook is 
37860 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e  not invoked when
37870 20 69 6e 74 65 72 6e 61 6c 20 73 79 73 74 65 6d   internal system
37880 20 74 61 62 6c 65 73 20 61 72 65 0a 2a 2a 20 6d   tables are.** m
37890 6f 64 69 66 69 65 64 20 28 69 2e 65 2e 20 73 71  odified (i.e. sq
378a0 6c 69 74 65 5f 6d 61 73 74 65 72 20 61 6e 64 20  lite_master and 
378b0 73 71 6c 69 74 65 5f 73 65 71 75 65 6e 63 65 29  sqlite_sequence)
378c0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68  .)^.**.** ^In th
378d0 65 20 63 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d  e current implem
378e0 65 6e 74 61 74 69 6f 6e 2c 20 74 68 65 20 75 70  entation, the up
378f0 64 61 74 65 20 68 6f 6f 6b 0a 2a 2a 20 69 73 20  date hook.** is 
37900 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e  not invoked when
37910 20 64 75 70 6c 69 63 61 74 69 6f 6e 20 72 6f 77   duplication row
37920 73 20 61 72 65 20 64 65 6c 65 74 65 64 20 62 65  s are deleted be
37930 63 61 75 73 65 20 6f 66 20 61 6e 0a 2a 2a 20 5b  cause of an.** [
37940 4f 4e 20 43 4f 4e 46 4c 49 43 54 20 7c 20 4f 4e  ON CONFLICT | ON
37950 20 43 4f 4e 46 4c 49 43 54 20 52 45 50 4c 41 43   CONFLICT REPLAC
37960 45 5d 20 63 6c 61 75 73 65 2e 20 20 5e 4e 6f 72  E] clause.  ^Nor
37970 20 69 73 20 74 68 65 20 75 70 64 61 74 65 20 68   is the update h
37980 6f 6f 6b 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20 77  ook.** invoked w
37990 68 65 6e 20 72 6f 77 73 20 61 72 65 20 64 65 6c  hen rows are del
379a0 65 74 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b  eted using the [
379b0 74 72 75 6e 63 61 74 65 20 6f 70 74 69 6d 69 7a  truncate optimiz
379c0 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 54 68 65 20 65  ation]..** The e
379d0 78 63 65 70 74 69 6f 6e 73 20 64 65 66 69 6e 65  xceptions define
379e0 64 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72  d in this paragr
379f0 61 70 68 20 6d 69 67 68 74 20 63 68 61 6e 67 65  aph might change
37a00 20 69 6e 20 61 20 66 75 74 75 72 65 0a 2a 2a 20   in a future.** 
37a10 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74  release of SQLit
37a20 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 75 70 64  e..**.** The upd
37a30 61 74 65 20 68 6f 6f 6b 20 69 6d 70 6c 65 6d 65  ate hook impleme
37a40 6e 74 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  ntation must not
37a50 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61   do anything tha
37a60 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a  t will modify.**
37a70 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
37a80 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e  nnection that in
37a90 76 6f 6b 65 64 20 74 68 65 20 75 70 64 61 74 65  voked the update
37aa0 20 68 6f 6f 6b 2e 20 20 41 6e 79 20 61 63 74 69   hook.  Any acti
37ab0 6f 6e 73 0a 2a 2a 20 74 6f 20 6d 6f 64 69 66 79  ons.** to modify
37ac0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
37ad0 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 62 65  nnection must be
37ae0 20 64 65 66 65 72 72 65 64 20 75 6e 74 69 6c 20   deferred until 
37af0 61 66 74 65 72 20 74 68 65 0a 2a 2a 20 63 6f 6d  after the.** com
37b00 70 6c 65 74 69 6f 6e 20 6f 66 20 74 68 65 20 5b  pletion of the [
37b10 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
37b20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65  call that trigge
37b30 72 65 64 20 74 68 65 20 75 70 64 61 74 65 20 68  red the update h
37b40 6f 6f 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ook..** Note tha
37b50 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  t [sqlite3_prepa
37b60 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71  re_v2()] and [sq
37b70 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f  lite3_step()] bo
37b80 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a  th modify their.
37b90 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ** database conn
37ba0 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20  ections for the 
37bb0 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69  meaning of "modi
37bc0 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 61  fy" in this para
37bd0 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  graph..**.** ^Th
37be0 65 20 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65  e sqlite3_update
37bf0 5f 68 6f 6f 6b 28 44 2c 43 2c 50 29 20 66 75 6e  _hook(D,C,P) fun
37c00 63 74 69 6f 6e 0a 2a 2a 20 72 65 74 75 72 6e 73  ction.** returns
37c10 20 74 68 65 20 50 20 61 72 67 75 6d 65 6e 74 20   the P argument 
37c20 66 72 6f 6d 20 74 68 65 20 70 72 65 76 69 6f 75  from the previou
37c30 73 20 63 61 6c 6c 0a 2a 2a 20 6f 6e 20 74 68 65  s call.** on the
37c40 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20   same [database 
37c50 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c 20 6f  connection] D, o
37c60 72 20 4e 55 4c 4c 20 66 6f 72 0a 2a 2a 20 74 68  r NULL for.** th
37c70 65 20 66 69 72 73 74 20 63 61 6c 6c 20 6f 6e 20  e first call on 
37c80 44 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  D..**.** See als
37c90 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  o the [sqlite3_c
37ca0 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 5d 20 61 6e  ommit_hook()] an
37cb0 64 20 5b 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62  d [sqlite3_rollb
37cc0 61 63 6b 5f 68 6f 6f 6b 28 29 5d 0a 2a 2a 20 69  ack_hook()].** i
37cd0 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2f 0a 76 6f  nterfaces..*/.vo
37ce0 69 64 20 2a 73 71 6c 69 74 65 33 5f 75 70 64 61  id *sqlite3_upda
37cf0 74 65 5f 68 6f 6f 6b 28 0a 20 20 73 71 6c 69 74  te_hook(.  sqlit
37d00 65 33 2a 2c 20 0a 20 20 76 6f 69 64 28 2a 29 28  e3*, .  void(*)(
37d10 76 6f 69 64 20 2a 2c 69 6e 74 20 2c 63 68 61 72  void *,int ,char
37d20 20 63 6f 6e 73 74 20 2a 2c 63 68 61 72 20 63 6f   const *,char co
37d30 6e 73 74 20 2a 2c 73 71 6c 69 74 65 33 5f 69 6e  nst *,sqlite3_in
37d40 74 36 34 29 2c 0a 20 20 76 6f 69 64 2a 0a 29 3b  t64),.  void*.);
37d50 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
37d60 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61  : Enable Or Disa
37d70 62 6c 65 20 53 68 61 72 65 64 20 50 61 67 65 72  ble Shared Pager
37d80 20 43 61 63 68 65 0a 2a 2a 0a 2a 2a 20 5e 28 54   Cache.**.** ^(T
37d90 68 69 73 20 72 6f 75 74 69 6e 65 20 65 6e 61 62  his routine enab
37da0 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20  les or disables 
37db0 74 68 65 20 73 68 61 72 69 6e 67 20 6f 66 20 74  the sharing of t
37dc0 68 65 20 64 61 74 61 62 61 73 65 20 63 61 63 68  he database cach
37dd0 65 0a 2a 2a 20 61 6e 64 20 73 63 68 65 6d 61 20  e.** and schema 
37de0 64 61 74 61 20 73 74 72 75 63 74 75 72 65 73 20  data structures 
37df0 62 65 74 77 65 65 6e 20 5b 64 61 74 61 62 61 73  between [databas
37e00 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 7c 20 63  e connection | c
37e10 6f 6e 6e 65 63 74 69 6f 6e 73 5d 0a 2a 2a 20 74  onnections].** t
37e20 6f 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62  o the same datab
37e30 61 73 65 2e 20 53 68 61 72 69 6e 67 20 69 73 20  ase. Sharing is 
37e40 65 6e 61 62 6c 65 64 20 69 66 20 74 68 65 20 61  enabled if the a
37e50 72 67 75 6d 65 6e 74 20 69 73 20 74 72 75 65 0a  rgument is true.
37e60 2a 2a 20 61 6e 64 20 64 69 73 61 62 6c 65 64 20  ** and disabled 
37e70 69 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20  if the argument 
37e80 69 73 20 66 61 6c 73 65 2e 29 5e 0a 2a 2a 0a 2a  is false.)^.**.*
37e90 2a 20 5e 43 61 63 68 65 20 73 68 61 72 69 6e 67  * ^Cache sharing
37ea0 20 69 73 20 65 6e 61 62 6c 65 64 20 61 6e 64 20   is enabled and 
37eb0 64 69 73 61 62 6c 65 64 20 66 6f 72 20 61 6e 20  disabled for an 
37ec0 65 6e 74 69 72 65 20 70 72 6f 63 65 73 73 2e 0a  entire process..
37ed0 2a 2a 20 54 68 69 73 20 69 73 20 61 20 63 68 61  ** This is a cha
37ee0 6e 67 65 20 61 73 20 6f 66 20 53 51 4c 69 74 65  nge as of SQLite
37ef0 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 2e 20   version 3.5.0. 
37f00 49 6e 20 70 72 69 6f 72 20 76 65 72 73 69 6f 6e  In prior version
37f10 73 20 6f 66 20 53 51 4c 69 74 65 2c 0a 2a 2a 20  s of SQLite,.** 
37f20 73 68 61 72 69 6e 67 20 77 61 73 20 65 6e 61 62  sharing was enab
37f30 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64 20  led or disabled 
37f40 66 6f 72 20 65 61 63 68 20 74 68 72 65 61 64 20  for each thread 
37f50 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a  separately..**.*
37f60 2a 20 5e 28 54 68 65 20 63 61 63 68 65 20 73 68  * ^(The cache sh
37f70 61 72 69 6e 67 20 6d 6f 64 65 20 73 65 74 20 62  aring mode set b
37f80 79 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65  y this interface
37f90 20 65 66 66 65 63 74 73 20 61 6c 6c 20 73 75 62   effects all sub
37fa0 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73  sequent.** calls
37fb0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   to [sqlite3_ope
37fc0 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f  n()], [sqlite3_o
37fd0 70 65 6e 5f 76 32 28 29 5d 2c 20 61 6e 64 20 5b  pen_v2()], and [
37fe0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
37ff0 5d 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 64  ]..** Existing d
38000 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
38010 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20 75 73 65  ons continue use
38020 20 74 68 65 20 73 68 61 72 69 6e 67 20 6d 6f 64   the sharing mod
38030 65 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 69 6e  e.** that was in
38040 20 65 66 66 65 63 74 20 61 74 20 74 68 65 20 74   effect at the t
38050 69 6d 65 20 74 68 65 79 20 77 65 72 65 20 6f 70  ime they were op
38060 65 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28  ened.)^.**.** ^(
38070 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74  This routine ret
38080 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  urns [SQLITE_OK]
38090 20 69 66 20 73 68 61 72 65 64 20 63 61 63 68 65   if shared cache
380a0 20 77 61 73 20 65 6e 61 62 6c 65 64 20 6f 72 20   was enabled or 
380b0 64 69 73 61 62 6c 65 64 0a 2a 2a 20 73 75 63 63  disabled.** succ
380c0 65 73 73 66 75 6c 6c 79 2e 20 20 41 6e 20 5b 65  essfully.  An [e
380d0 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65  rror code] is re
380e0 74 75 72 6e 65 64 20 6f 74 68 65 72 77 69 73 65  turned otherwise
380f0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 68 61 72 65  .)^.**.** ^Share
38100 64 20 63 61 63 68 65 20 69 73 20 64 69 73 61 62  d cache is disab
38110 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 20  led by default. 
38120 42 75 74 20 74 68 69 73 20 6d 69 67 68 74 20 63  But this might c
38130 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 66 75 74 75  hange in.** futu
38140 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53  re releases of S
38150 51 4c 69 74 65 2e 20 20 41 70 70 6c 69 63 61 74  QLite.  Applicat
38160 69 6f 6e 73 20 74 68 61 74 20 63 61 72 65 20 61  ions that care a
38170 62 6f 75 74 20 73 68 61 72 65 64 0a 2a 2a 20 63  bout shared.** c
38180 61 63 68 65 20 73 65 74 74 69 6e 67 20 73 68 6f  ache setting sho
38190 75 6c 64 20 73 65 74 20 69 74 20 65 78 70 6c 69  uld set it expli
381a0 63 69 74 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  citly..**.** Thi
381b0 73 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74  s interface is t
381c0 68 72 65 61 64 73 61 66 65 20 6f 6e 20 70 72 6f  hreadsafe on pro
381d0 63 65 73 73 6f 72 73 20 77 68 65 72 65 20 77 72  cessors where wr
381e0 69 74 69 6e 67 20 61 0a 2a 2a 20 33 32 2d 62 69  iting a.** 32-bi
381f0 74 20 69 6e 74 65 67 65 72 20 69 73 20 61 74 6f  t integer is ato
38200 6d 69 63 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 41  mic..**.** See A
38210 6c 73 6f 3a 20 20 5b 53 51 4c 69 74 65 20 53 68  lso:  [SQLite Sh
38220 61 72 65 64 2d 43 61 63 68 65 20 4d 6f 64 65 5d  ared-Cache Mode]
38230 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
38240 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61  enable_shared_ca
38250 63 68 65 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  che(int);../*.**
38260 20 43 41 50 49 33 52 45 46 3a 20 41 74 74 65 6d   CAPI3REF: Attem
38270 70 74 20 54 6f 20 46 72 65 65 20 48 65 61 70 20  pt To Free Heap 
38280 4d 65 6d 6f 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68  Memory.**.** ^Th
38290 65 20 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73  e sqlite3_releas
382a0 65 5f 6d 65 6d 6f 72 79 28 29 20 69 6e 74 65 72  e_memory() inter
382b0 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f  face attempts to
382c0 20 66 72 65 65 20 4e 20 62 79 74 65 73 0a 2a 2a   free N bytes.**
382d0 20 6f 66 20 68 65 61 70 20 6d 65 6d 6f 72 79 20   of heap memory 
382e0 62 79 20 64 65 61 6c 6c 6f 63 61 74 69 6e 67 20  by deallocating 
382f0 6e 6f 6e 2d 65 73 73 65 6e 74 69 61 6c 20 6d 65  non-essential me
38300 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73  mory allocations
38310 0a 2a 2a 20 68 65 6c 64 20 62 79 20 74 68 65 20  .** held by the 
38320 64 61 74 61 62 61 73 65 20 6c 69 62 72 61 72 79  database library
38330 2e 20 20 20 4d 65 6d 6f 72 79 20 75 73 65 64 20  .   Memory used 
38340 74 6f 20 63 61 63 68 65 20 64 61 74 61 62 61 73  to cache databas
38350 65 0a 2a 2a 20 70 61 67 65 73 20 74 6f 20 69 6d  e.** pages to im
38360 70 72 6f 76 65 20 70 65 72 66 6f 72 6d 61 6e 63  prove performanc
38370 65 20 69 73 20 61 6e 20 65 78 61 6d 70 6c 65 20  e is an example 
38380 6f 66 20 6e 6f 6e 2d 65 73 73 65 6e 74 69 61 6c  of non-essential
38390 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 73 71 6c   memory..** ^sql
383a0 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d  ite3_release_mem
383b0 6f 72 79 28 29 20 72 65 74 75 72 6e 73 20 74 68  ory() returns th
383c0 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
383d0 73 20 61 63 74 75 61 6c 6c 79 20 66 72 65 65 64  s actually freed
383e0 2c 0a 2a 2a 20 77 68 69 63 68 20 6d 69 67 68 74  ,.** which might
383f0 20 62 65 20 6d 6f 72 65 20 6f 72 20 6c 65 73 73   be more or less
38400 20 74 68 61 6e 20 74 68 65 20 61 6d 6f 75 6e 74   than the amount
38410 20 72 65 71 75 65 73 74 65 64 2e 0a 2a 2a 20 5e   requested..** ^
38420 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 6c 65  The sqlite3_rele
38430 61 73 65 5f 6d 65 6d 6f 72 79 28 29 20 72 6f 75  ase_memory() rou
38440 74 69 6e 65 20 69 73 20 61 20 6e 6f 2d 6f 70 20  tine is a no-op 
38450 72 65 74 75 72 6e 69 6e 67 20 7a 65 72 6f 0a 2a  returning zero.*
38460 2a 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 6e  * if SQLite is n
38470 6f 74 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  ot compiled with
38480 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f   [SQLITE_ENABLE_
38490 4d 45 4d 4f 52 59 5f 4d 41 4e 41 47 45 4d 45 4e  MEMORY_MANAGEMEN
384a0 54 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  T]..**.** See al
384b0 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f  so: [sqlite3_db_
384c0 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29  release_memory()
384d0 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ].*/.int sqlite3
384e0 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28  _release_memory(
384f0 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  int);../*.** CAP
38500 49 33 52 45 46 3a 20 46 72 65 65 20 4d 65 6d 6f  I3REF: Free Memo
38510 72 79 20 55 73 65 64 20 42 79 20 41 20 44 61 74  ry Used By A Dat
38520 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e  abase Connection
38530 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
38540 74 65 33 5f 64 62 5f 72 65 6c 65 61 73 65 5f 6d  te3_db_release_m
38550 65 6d 6f 72 79 28 44 29 20 69 6e 74 65 72 66 61  emory(D) interfa
38560 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 66  ce attempts to f
38570 72 65 65 20 61 73 20 6d 75 63 68 20 68 65 61 70  ree as much heap
38580 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 73 20 70 6f  .** memory as po
38590 73 73 69 62 6c 65 20 66 72 6f 6d 20 64 61 74 61  ssible from data
385a0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
385b0 44 2e 20 55 6e 6c 69 6b 65 20 74 68 65 0a 2a 2a  D. Unlike the.**
385c0 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73   [sqlite3_releas
385d0 65 5f 6d 65 6d 6f 72 79 28 29 5d 20 69 6e 74 65  e_memory()] inte
385e0 72 66 61 63 65 2c 20 74 68 69 73 20 69 6e 74 65  rface, this inte
385f0 72 66 61 63 65 20 69 73 20 65 66 66 65 63 74 20  rface is effect 
38600 65 76 65 6e 0a 2a 2a 20 77 68 65 6e 20 74 68 65  even.** when the
38610 6e 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  n [SQLITE_ENABLE
38620 5f 4d 45 4d 4f 52 59 5f 4d 41 4e 41 47 45 4d 45  _MEMORY_MANAGEME
38630 4e 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  NT] compile-time
38640 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 6f 6d   option is.** om
38650 69 74 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  itted..**.** See
38660 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
38670 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29  release_memory()
38680 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ].*/.int sqlite3
38690 5f 64 62 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f  _db_release_memo
386a0 72 79 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  ry(sqlite3*);../
386b0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49  *.** CAPI3REF: I
386c0 6d 70 6f 73 65 20 41 20 4c 69 6d 69 74 20 4f 6e  mpose A Limit On
386d0 20 48 65 61 70 20 53 69 7a 65 0a 2a 2a 0a 2a 2a   Heap Size.**.**
386e0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6f   ^The sqlite3_so
386f0 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28  ft_heap_limit64(
38700 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73  ) interface sets
38710 20 61 6e 64 2f 6f 72 20 71 75 65 72 69 65 73 20   and/or queries 
38720 74 68 65 0a 2a 2a 20 73 6f 66 74 20 6c 69 6d 69  the.** soft limi
38730 74 20 6f 6e 20 74 68 65 20 61 6d 6f 75 6e 74 20  t on the amount 
38740 6f 66 20 68 65 61 70 20 6d 65 6d 6f 72 79 20 74  of heap memory t
38750 68 61 74 20 6d 61 79 20 62 65 20 61 6c 6c 6f 63  hat may be alloc
38760 61 74 65 64 20 62 79 20 53 51 4c 69 74 65 2e 0a  ated by SQLite..
38770 2a 2a 20 5e 53 51 4c 69 74 65 20 73 74 72 69 76  ** ^SQLite striv
38780 65 73 20 74 6f 20 6b 65 65 70 20 68 65 61 70 20  es to keep heap 
38790 6d 65 6d 6f 72 79 20 75 74 69 6c 69 7a 61 74 69  memory utilizati
387a0 6f 6e 20 62 65 6c 6f 77 20 74 68 65 20 73 6f 66  on below the sof
387b0 74 20 68 65 61 70 0a 2a 2a 20 6c 69 6d 69 74 20  t heap.** limit 
387c0 62 79 20 72 65 64 75 63 69 6e 67 20 74 68 65 20  by reducing the 
387d0 6e 75 6d 62 65 72 20 6f 66 20 70 61 67 65 73 20  number of pages 
387e0 68 65 6c 64 20 69 6e 20 74 68 65 20 70 61 67 65  held in the page
387f0 20 63 61 63 68 65 0a 2a 2a 20 61 73 20 68 65 61   cache.** as hea
38800 70 20 6d 65 6d 6f 72 79 20 75 73 61 67 65 73 20  p memory usages 
38810 61 70 70 72 6f 61 63 68 65 73 20 74 68 65 20 6c  approaches the l
38820 69 6d 69 74 2e 0a 2a 2a 20 5e 54 68 65 20 73 6f  imit..** ^The so
38830 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69 73  ft heap limit is
38840 20 22 73 6f 66 74 22 20 62 65 63 61 75 73 65 20   "soft" because 
38850 65 76 65 6e 20 74 68 6f 75 67 68 20 53 51 4c 69  even though SQLi
38860 74 65 20 73 74 72 69 76 65 73 20 74 6f 20 73 74  te strives to st
38870 61 79 0a 2a 2a 20 62 65 6c 6f 77 20 74 68 65 20  ay.** below the 
38