/ Hex Artifact Content
Login

Artifact 39ddd714b62c651bfb5646440c594ca7ff6c7453:


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 4f 52 52 55 50 54 5f 56 54 41 42 20 20 20  _CORRUPT_VTAB   
5600: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5610: 5f 43 4f 52 52 55 50 54 20 7c 20 28 31 3c 3c 38  _CORRUPT | (1<<8
5620: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5630: 45 5f 52 45 41 44 4f 4e 4c 59 5f 52 45 43 4f 56  E_READONLY_RECOV
5640: 45 52 59 20 20 20 20 20 20 20 28 53 51 4c 49 54  ERY       (SQLIT
5650: 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 31 3c  E_READONLY | (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 43 41 4e  ITE_READONLY_CAN
5680: 54 4c 4f 43 4b 20 20 20 20 20 20 20 28 53 51 4c  TLOCK       (SQL
5690: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28  ITE_READONLY | (
56a0: 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  2<<8)).#define S
56b0: 51 4c 49 54 45 5f 41 42 4f 52 54 5f 52 4f 4c 4c  QLITE_ABORT_ROLL
56c0: 42 41 43 4b 20 20 20 20 20 20 20 20 20 20 28 53  BACK          (S
56d0: 51 4c 49 54 45 5f 41 42 4f 52 54 20 7c 20 28 32  QLITE_ABORT | (2
56e0: 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  <<8))../*.** CAP
56f0: 49 33 52 45 46 3a 20 46 6c 61 67 73 20 46 6f 72  I3REF: Flags For
5700: 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65 72 61   File Open Opera
5710: 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  tions.**.** Thes
5720: 65 20 62 69 74 20 76 61 6c 75 65 73 20 61 72 65  e bit values are
5730: 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73   intended for us
5740: 65 20 69 6e 20 74 68 65 0a 2a 2a 20 33 72 64 20  e in the.** 3rd 
5750: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
5760: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
5770: 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 61  2()] interface a
5780: 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20 34 74 68  nd.** in the 4th
5790: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
57a0: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78  e [sqlite3_vfs.x
57b0: 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 2e 0a 2a 2f  Open] method..*/
57c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
57d0: 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 20 20  OPEN_READONLY   
57e0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 31        0x00000001
57f0: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
5800: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
5810: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5820: 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 20  OPEN_READWRITE  
5830: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 32        0x00000002
5840: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
5850: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
5860: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5870: 4f 50 45 4e 5f 43 52 45 41 54 45 20 20 20 20 20  OPEN_CREATE     
5880: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 34        0x00000004
5890: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
58a0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
58b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
58c0: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f  OPEN_DELETEONCLO
58d0: 53 45 20 20 20 20 30 78 30 30 30 30 30 30 30 38  SE    0x00000008
58e0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
58f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5900: 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 20  OPEN_EXCLUSIVE  
5910: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 31 30        0x00000010
5920: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
5930: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5940: 4f 50 45 4e 5f 41 55 54 4f 50 52 4f 58 59 20 20  OPEN_AUTOPROXY  
5950: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 32 30        0x00000020
5960: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
5970: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5980: 4f 50 45 4e 5f 55 52 49 20 20 20 20 20 20 20 20  OPEN_URI        
5990: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 34 30        0x00000040
59a0: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
59b0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
59c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
59d0: 4f 50 45 4e 5f 4d 45 4d 4f 52 59 20 20 20 20 20  OPEN_MEMORY     
59e0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 38 30        0x00000080
59f0: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
5a00: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
5a10: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5a20: 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20 20 20 20  OPEN_MAIN_DB    
5a30: 20 20 20 20 20 20 30 78 30 30 30 30 30 31 30 30        0x00000100
5a40: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
5a50: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5a60: 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20 20 20 20  OPEN_TEMP_DB    
5a70: 20 20 20 20 20 20 30 78 30 30 30 30 30 32 30 30        0x00000200
5a80: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
5a90: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5aa0: 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44  OPEN_TRANSIENT_D
5ab0: 42 20 20 20 20 20 30 78 30 30 30 30 30 34 30 30  B     0x00000400
5ac0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
5ad0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5ae0: 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41  OPEN_MAIN_JOURNA
5af0: 4c 20 20 20 20 20 30 78 30 30 30 30 30 38 30 30  L     0x00000800
5b00: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
5b10: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5b20: 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41  OPEN_TEMP_JOURNA
5b30: 4c 20 20 20 20 20 30 78 30 30 30 30 31 30 30 30  L     0x00001000
5b40: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
5b50: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5b60: 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 20  OPEN_SUBJOURNAL 
5b70: 20 20 20 20 20 20 30 78 30 30 30 30 32 30 30 30        0x00002000
5b80: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
5b90: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5ba0: 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52  OPEN_MASTER_JOUR
5bb0: 4e 41 4c 20 20 20 30 78 30 30 30 30 34 30 30 30  NAL   0x00004000
5bc0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
5bd0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5be0: 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 20 20 20 20  OPEN_NOMUTEX    
5bf0: 20 20 20 20 20 20 30 78 30 30 30 30 38 30 30 30        0x00008000
5c00: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
5c10: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
5c20: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5c30: 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 20 20  OPEN_FULLMUTEX  
5c40: 20 20 20 20 20 20 30 78 30 30 30 31 30 30 30 30        0x00010000
5c50: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
5c60: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
5c70: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5c80: 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45  OPEN_SHAREDCACHE
5c90: 20 20 20 20 20 20 30 78 30 30 30 32 30 30 30 30        0x00020000
5ca0: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
5cb0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
5cc0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5cd0: 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48  OPEN_PRIVATECACH
5ce0: 45 20 20 20 20 20 30 78 30 30 30 34 30 30 30 30  E     0x00040000
5cf0: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
5d00: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
5d10: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5d20: 4f 50 45 4e 5f 57 41 4c 20 20 20 20 20 20 20 20  OPEN_WAL        
5d30: 20 20 20 20 20 20 30 78 30 30 30 38 30 30 30 30        0x00080000
5d40: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
5d50: 0a 0a 2f 2a 20 52 65 73 65 72 76 65 64 3a 20 20  ../* Reserved:  
5d60: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
5d70: 20 20 20 20 20 20 20 30 78 30 30 46 30 30 30 30         0x00F0000
5d80: 30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  0 */../*.** CAPI
5d90: 33 52 45 46 3a 20 44 65 76 69 63 65 20 43 68 61  3REF: Device Cha
5da0: 72 61 63 74 65 72 69 73 74 69 63 73 0a 2a 2a 0a  racteristics.**.
5db0: 2a 2a 20 54 68 65 20 78 44 65 76 69 63 65 43 68  ** The xDeviceCh
5dc0: 61 72 61 63 74 65 72 69 73 74 69 63 73 20 6d 65  aracteristics me
5dd0: 74 68 6f 64 20 6f 66 20 74 68 65 20 5b 73 71 6c  thod of the [sql
5de0: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
5df0: 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74 75 72  .** object retur
5e00: 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68  ns an integer wh
5e10: 69 63 68 20 69 73 20 61 20 76 65 63 74 6f 72 20  ich is a vector 
5e20: 6f 66 20 74 68 65 73 65 0a 2a 2a 20 62 69 74 20  of these.** bit 
5e30: 76 61 6c 75 65 73 20 65 78 70 72 65 73 73 69 6e  values expressin
5e40: 67 20 49 2f 4f 20 63 68 61 72 61 63 74 65 72 69  g I/O characteri
5e50: 73 74 69 63 73 20 6f 66 20 74 68 65 20 6d 61 73  stics of the mas
5e60: 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20 64 65 76  s storage.** dev
5e70: 69 63 65 20 74 68 61 74 20 68 6f 6c 64 73 20 74  ice that holds t
5e80: 68 65 20 66 69 6c 65 20 74 68 61 74 20 74 68 65  he file that the
5e90: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
5ea0: 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65 72 73 20  hods].** refers 
5eb0: 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51  to..**.** The SQ
5ec0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
5ed0: 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73  C property means
5ee0: 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73   that all writes
5ef0: 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20   of.** any size 
5f00: 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65  are atomic.  The
5f10: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
5f20: 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a  OMICnnn values.*
5f30: 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74  * mean that writ
5f40: 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61  es of blocks tha
5f50: 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20  t are nnn bytes 
5f60: 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61  in size and.** a
5f70: 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e  re aligned to an
5f80: 20 61 64 64 72 65 73 73 20 77 68 69 63 68 20 69   address which i
5f90: 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c  s an integer mul
5fa0: 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20  tiple of.** nnn 
5fb0: 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65  are atomic.  The
5fc0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41   SQLITE_IOCAP_SA
5fd0: 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20  FE_APPEND value 
5fe0: 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68  means.** that wh
5ff0: 65 6e 20 64 61 74 61 20 69 73 20 61 70 70 65 6e  en data is appen
6000: 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74  ded to a file, t
6010: 68 65 20 64 61 74 61 20 69 73 20 61 70 70 65 6e  he data is appen
6020: 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65  ded.** first the
6030: 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  n the size of th
6040: 65 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64  e file is extend
6050: 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74  ed, never the ot
6060: 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e  her.** way aroun
6070: 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  d.  The SQLITE_I
6080: 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20  OCAP_SEQUENTIAL 
6090: 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74  property means t
60a0: 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  hat.** informati
60b0: 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f  on is written to
60c0: 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d   disk in the sam
60d0: 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73  e order as calls
60e0: 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e  .** to xWrite().
60f0: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
6100: 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45  AP_POWERSAFE_OVE
6110: 52 57 52 49 54 45 20 70 72 6f 70 65 72 74 79 20  RWRITE property 
6120: 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 61 66  means that.** af
6130: 74 65 72 20 72 65 62 6f 6f 74 20 66 6f 6c 6c 6f  ter reboot follo
6140: 77 69 6e 67 20 61 20 63 72 61 73 68 20 6f 72 20  wing a crash or 
6150: 70 6f 77 65 72 20 6c 6f 73 73 2c 20 74 68 65 20  power loss, the 
6160: 6f 6e 6c 79 20 62 79 74 65 73 20 69 6e 20 61 0a  only bytes in a.
6170: 2a 2a 20 66 69 6c 65 20 74 68 61 74 20 77 65 72  ** file that wer
6180: 65 20 77 72 69 74 74 65 6e 20 61 74 20 74 68 65  e written at the
6190: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6c 65 76   application lev
61a0: 65 6c 20 6d 69 67 68 74 20 68 61 76 65 20 63 68  el might have ch
61b0: 61 6e 67 65 64 0a 2a 2a 20 61 6e 64 20 74 68 61  anged.** and tha
61c0: 74 20 61 64 6a 61 63 65 6e 74 20 62 79 74 65 73  t adjacent bytes
61d0: 2c 20 65 76 65 6e 20 62 79 74 65 73 20 77 69 74  , even bytes wit
61e0: 68 69 6e 20 74 68 65 20 73 61 6d 65 20 73 65 63  hin the same sec
61f0: 74 6f 72 20 61 72 65 0a 2a 2a 20 67 75 61 72 61  tor are.** guara
6200: 6e 74 65 65 64 20 74 6f 20 62 65 20 75 6e 63 68  nteed to be unch
6210: 61 6e 67 65 64 2e 0a 2a 2f 0a 23 64 65 66 69 6e  anged..*/.#defin
6220: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
6230: 54 4f 4d 49 43 20 20 20 20 20 20 20 20 20 20 20  TOMIC           
6240: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 31        0x00000001
6250: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6260: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 20  IOCAP_ATOMIC512 
6270: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
6280: 30 30 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20  0000002.#define 
6290: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
62a0: 4d 49 43 31 4b 20 20 20 20 20 20 20 20 20 20 20  MIC1K           
62b0: 20 20 20 20 30 78 30 30 30 30 30 30 30 34 0a 23      0x00000004.#
62c0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
62d0: 43 41 50 5f 41 54 4f 4d 49 43 32 4b 20 20 20 20  CAP_ATOMIC2K    
62e0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
62f0: 30 30 30 30 38 0a 23 64 65 66 69 6e 65 20 53 51  00008.#define SQ
6300: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
6310: 43 34 4b 20 20 20 20 20 20 20 20 20 20 20 20 20  C4K             
6320: 20 20 30 78 30 30 30 30 30 30 31 30 0a 23 64 65    0x00000010.#de
6330: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
6340: 50 5f 41 54 4f 4d 49 43 38 4b 20 20 20 20 20 20  P_ATOMIC8K      
6350: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6360: 30 32 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  020.#define SQLI
6370: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31  TE_IOCAP_ATOMIC1
6380: 36 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  6K              
6390: 30 78 30 30 30 30 30 30 34 30 0a 23 64 65 66 69  0x00000040.#defi
63a0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
63b0: 41 54 4f 4d 49 43 33 32 4b 20 20 20 20 20 20 20  ATOMIC32K       
63c0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 38         0x0000008
63d0: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
63e0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b  _IOCAP_ATOMIC64K
63f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
6400: 30 30 30 30 30 31 30 30 0a 23 64 65 66 69 6e 65  00000100.#define
6410: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41   SQLITE_IOCAP_SA
6420: 46 45 5f 41 50 50 45 4e 44 20 20 20 20 20 20 20  FE_APPEND       
6430: 20 20 20 20 20 30 78 30 30 30 30 30 32 30 30 0a       0x00000200.
6440: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
6450: 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20  OCAP_SEQUENTIAL 
6460: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
6470: 30 30 30 34 30 30 0a 23 64 65 66 69 6e 65 20 53  000400.#define S
6480: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45  QLITE_IOCAP_UNDE
6490: 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45  LETABLE_WHEN_OPE
64a0: 4e 20 20 30 78 30 30 30 30 30 38 30 30 0a 23 64  N  0x00000800.#d
64b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
64c0: 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45  AP_POWERSAFE_OVE
64d0: 52 57 52 49 54 45 20 20 20 20 30 78 30 30 30 30  RWRITE    0x0000
64e0: 31 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  1000../*.** CAPI
64f0: 33 52 45 46 3a 20 46 69 6c 65 20 4c 6f 63 6b 69  3REF: File Locki
6500: 6e 67 20 4c 65 76 65 6c 73 0a 2a 2a 0a 2a 2a 20  ng Levels.**.** 
6510: 53 51 4c 69 74 65 20 75 73 65 73 20 6f 6e 65 20  SQLite uses one 
6520: 6f 66 20 74 68 65 73 65 20 69 6e 74 65 67 65 72  of these integer
6530: 20 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 73   values as the s
6540: 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d 65 6e  econd.** argumen
6550: 74 20 74 6f 20 63 61 6c 6c 73 20 69 74 20 6d 61  t to calls it ma
6560: 6b 65 73 20 74 6f 20 74 68 65 20 78 4c 6f 63 6b  kes to the xLock
6570: 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29  () and xUnlock()
6580: 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f 66 20 61   methods.** of a
6590: 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  n [sqlite3_io_me
65a0: 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a  thods] object..*
65b0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
65c0: 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20 20 20 20  _LOCK_NONE      
65d0: 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51      0.#define SQ
65e0: 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44  LITE_LOCK_SHARED
65f0: 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e          1.#defin
6600: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45  e SQLITE_LOCK_RE
6610: 53 45 52 56 45 44 20 20 20 20 20 20 32 0a 23 64  SERVED      2.#d
6620: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43  efine SQLITE_LOC
6630: 4b 5f 50 45 4e 44 49 4e 47 20 20 20 20 20 20 20  K_PENDING       
6640: 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  3.#define SQLITE
6650: 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 20  _LOCK_EXCLUSIVE 
6660: 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50      4../*.** CAP
6670: 49 33 52 45 46 3a 20 53 79 6e 63 68 72 6f 6e 69  I3REF: Synchroni
6680: 7a 61 74 69 6f 6e 20 54 79 70 65 20 46 6c 61 67  zation Type Flag
6690: 73 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53 51 4c  s.**.** When SQL
66a0: 69 74 65 20 69 6e 76 6f 6b 65 73 20 74 68 65 20  ite invokes the 
66b0: 78 53 79 6e 63 28 29 20 6d 65 74 68 6f 64 20 6f  xSync() method o
66c0: 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  f an.** [sqlite3
66d0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
66e0: 65 63 74 20 69 74 20 75 73 65 73 20 61 20 63 6f  ect it uses a co
66f0: 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20  mbination of.** 
6700: 74 68 65 73 65 20 69 6e 74 65 67 65 72 20 76 61  these integer va
6710: 6c 75 65 73 20 61 73 20 74 68 65 20 73 65 63 6f  lues as the seco
6720: 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a  nd argument..**.
6730: 2a 2a 20 57 68 65 6e 20 74 68 65 20 53 51 4c 49  ** When the SQLI
6740: 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59  TE_SYNC_DATAONLY
6750: 20 66 6c 61 67 20 69 73 20 75 73 65 64 2c 20 69   flag is used, i
6760: 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  t means that the
6770: 0a 2a 2a 20 73 79 6e 63 20 6f 70 65 72 61 74 69  .** sync operati
6780: 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f  on only needs to
6790: 20 66 6c 75 73 68 20 64 61 74 61 20 74 6f 20 6d   flush data to m
67a0: 61 73 73 20 73 74 6f 72 61 67 65 2e 20 20 49 6e  ass storage.  In
67b0: 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  ode.** informati
67c0: 6f 6e 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 66  on need not be f
67d0: 6c 75 73 68 65 64 2e 20 49 66 20 74 68 65 20 6c  lushed. If the l
67e0: 6f 77 65 72 20 66 6f 75 72 20 62 69 74 73 20 6f  ower four bits o
67f0: 66 20 74 68 65 20 66 6c 61 67 0a 2a 2a 20 65 71  f the flag.** eq
6800: 75 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  ual SQLITE_SYNC_
6810: 4e 4f 52 4d 41 4c 2c 20 74 68 61 74 20 6d 65 61  NORMAL, that mea
6820: 6e 73 20 74 6f 20 75 73 65 20 6e 6f 72 6d 61 6c  ns to use normal
6830: 20 66 73 79 6e 63 28 29 20 73 65 6d 61 6e 74 69   fsync() semanti
6840: 63 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 6c 6f  cs..** If the lo
6850: 77 65 72 20 66 6f 75 72 20 62 69 74 73 20 65 71  wer four bits eq
6860: 75 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  ual SQLITE_SYNC_
6870: 46 55 4c 4c 2c 20 74 68 61 74 20 6d 65 61 6e 73  FULL, that means
6880: 0a 2a 2a 20 74 6f 20 75 73 65 20 4d 61 63 20 4f  .** to use Mac O
6890: 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79  S X style fullsy
68a0: 6e 63 20 69 6e 73 74 65 61 64 20 6f 66 20 66 73  nc instead of fs
68b0: 79 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 44 6f 20  ync()..**.** Do 
68c0: 6e 6f 74 20 63 6f 6e 66 75 73 65 20 74 68 65 20  not confuse the 
68d0: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d  SQLITE_SYNC_NORM
68e0: 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59  AL and SQLITE_SY
68f0: 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 73 0a 2a 2a  NC_FULL flags.**
6900: 20 77 69 74 68 20 74 68 65 20 5b 50 52 41 47 4d   with the [PRAGM
6910: 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d 4e  A synchronous]=N
6920: 4f 52 4d 41 4c 20 61 6e 64 20 5b 50 52 41 47 4d  ORMAL and [PRAGM
6930: 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d 46  A synchronous]=F
6940: 55 4c 4c 0a 2a 2a 20 73 65 74 74 69 6e 67 73 2e  ULL.** settings.
6950: 20 20 54 68 65 20 5b 73 79 6e 63 68 72 6f 6e 6f    The [synchrono
6960: 75 73 20 70 72 61 67 6d 61 5d 20 64 65 74 65 72  us pragma] deter
6970: 6d 69 6e 65 73 20 77 68 65 6e 20 63 61 6c 6c 73  mines when calls
6980: 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53 79 6e 63   to the.** xSync
6990: 20 56 46 53 20 6d 65 74 68 6f 64 20 6f 63 63 75   VFS method occu
69a0: 72 20 61 6e 64 20 61 70 70 6c 69 65 73 20 75 6e  r and applies un
69b0: 69 66 6f 72 6d 6c 79 20 61 63 72 6f 73 73 20 61  iformly across a
69c0: 6c 6c 20 70 6c 61 74 66 6f 72 6d 73 2e 0a 2a 2a  ll platforms..**
69d0: 20 54 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43   The SQLITE_SYNC
69e0: 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49  _NORMAL and SQLI
69f0: 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61  TE_SYNC_FULL fla
6a00: 67 73 20 64 65 74 65 72 6d 69 6e 65 20 68 6f 77  gs determine how
6a10: 0a 2a 2a 20 65 6e 65 72 67 65 74 69 63 20 6f 72  .** energetic or
6a20: 20 72 69 67 6f 72 6f 75 73 20 6f 72 20 66 6f 72   rigorous or for
6a30: 63 65 66 75 6c 20 74 68 65 20 73 79 6e 63 20 6f  ceful the sync o
6a40: 70 65 72 61 74 69 6f 6e 73 20 61 72 65 20 61 6e  perations are an
6a50: 64 0a 2a 2a 20 6f 6e 6c 79 20 6d 61 6b 65 20 61  d.** only make a
6a60: 20 64 69 66 66 65 72 65 6e 63 65 20 6f 6e 20 4d   difference on M
6a70: 61 63 20 4f 53 58 20 66 6f 72 20 74 68 65 20 64  ac OSX for the d
6a80: 65 66 61 75 6c 74 20 53 51 4c 69 74 65 20 63 6f  efault SQLite co
6a90: 64 65 2e 0a 2a 2a 20 28 54 68 69 72 64 2d 70 61  de..** (Third-pa
6aa0: 72 74 79 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e  rty VFS implemen
6ab0: 74 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 61 6c  tations might al
6ac0: 73 6f 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74  so make the dist
6ad0: 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65 74 77 65  inction.** betwe
6ae0: 65 6e 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e  en SQLITE_SYNC_N
6af0: 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45  ORMAL and SQLITE
6b00: 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 62 75 74 20  _SYNC_FULL, but 
6b10: 61 6d 6f 6e 67 20 74 68 65 0a 2a 2a 20 6f 70 65  among the.** ope
6b20: 72 61 74 69 6e 67 20 73 79 73 74 65 6d 73 20 6e  rating systems n
6b30: 61 74 69 76 65 6c 79 20 73 75 70 70 6f 72 74 65  atively supporte
6b40: 64 20 62 79 20 53 51 4c 69 74 65 2c 20 6f 6e 6c  d by SQLite, onl
6b50: 79 20 4d 61 63 20 4f 53 58 0a 2a 2a 20 63 61 72  y Mac OSX.** car
6b60: 65 73 20 61 62 6f 75 74 20 74 68 65 20 64 69 66  es about the dif
6b70: 66 65 72 65 6e 63 65 2e 29 0a 2a 2f 0a 23 64 65  ference.).*/.#de
6b80: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43  fine SQLITE_SYNC
6b90: 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20 20 20 30  _NORMAL        0
6ba0: 78 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53  x00002.#define S
6bb0: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20  QLITE_SYNC_FULL 
6bc0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 33           0x00003
6bd0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6be0: 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 20 20  SYNC_DATAONLY   
6bf0: 20 20 20 30 78 30 30 30 31 30 0a 0a 2f 2a 0a 2a     0x00010../*.*
6c00: 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49  * CAPI3REF: OS I
6c10: 6e 74 65 72 66 61 63 65 20 4f 70 65 6e 20 46 69  nterface Open Fi
6c20: 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20  le Handle.**.** 
6c30: 41 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  An [sqlite3_file
6c40: 5d 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65  ] object represe
6c50: 6e 74 73 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65  nts an open file
6c60: 20 69 6e 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c   in the .** [sql
6c70: 69 74 65 33 5f 76 66 73 20 7c 20 4f 53 20 69 6e  ite3_vfs | OS in
6c80: 74 65 72 66 61 63 65 20 6c 61 79 65 72 5d 2e 20  terface layer]. 
6c90: 20 49 6e 64 69 76 69 64 75 61 6c 20 4f 53 20 69   Individual OS i
6ca0: 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69 6d 70 6c  nterface.** impl
6cb0: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c  ementations will
6cc0: 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 73 75 62 63  .** want to subc
6cd0: 6c 61 73 73 20 74 68 69 73 20 6f 62 6a 65 63 74  lass this object
6ce0: 20 62 79 20 61 70 70 65 6e 64 69 6e 67 20 61 64   by appending ad
6cf0: 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 0a  ditional fields.
6d00: 2a 2a 20 66 6f 72 20 74 68 65 69 72 20 6f 77 6e  ** for their own
6d10: 20 75 73 65 2e 20 20 54 68 65 20 70 4d 65 74 68   use.  The pMeth
6d20: 6f 64 73 20 65 6e 74 72 79 20 69 73 20 61 20 70  ods entry is a p
6d30: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20  ointer to an.** 
6d40: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
6d50: 6f 64 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74  ods] object that
6d60: 20 64 65 66 69 6e 65 73 20 6d 65 74 68 6f 64 73   defines methods
6d70: 20 66 6f 72 20 70 65 72 66 6f 72 6d 69 6e 67 0a   for performing.
6d80: 2a 2a 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e  ** I/O operation
6d90: 73 20 6f 6e 20 74 68 65 20 6f 70 65 6e 20 66 69  s on the open fi
6da0: 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  le..*/.typedef s
6db0: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66 69  truct sqlite3_fi
6dc0: 6c 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 3b  le sqlite3_file;
6dd0: 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f  .struct sqlite3_
6de0: 66 69 6c 65 20 7b 0a 20 20 63 6f 6e 73 74 20 73  file {.  const s
6df0: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f  truct sqlite3_io
6e00: 5f 6d 65 74 68 6f 64 73 20 2a 70 4d 65 74 68 6f  _methods *pMetho
6e10: 64 73 3b 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20  ds;  /* Methods 
6e20: 66 6f 72 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65  for an open file
6e30: 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.};../*.** CA
6e40: 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72  PI3REF: OS Inter
6e50: 66 61 63 65 20 46 69 6c 65 20 56 69 72 74 75 61  face File Virtua
6e60: 6c 20 4d 65 74 68 6f 64 73 20 4f 62 6a 65 63 74  l Methods Object
6e70: 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 66 69 6c  .**.** Every fil
6e80: 65 20 6f 70 65 6e 65 64 20 62 79 20 74 68 65 20  e opened by the 
6e90: 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70  [sqlite3_vfs.xOp
6ea0: 65 6e 5d 20 6d 65 74 68 6f 64 20 70 6f 70 75 6c  en] method popul
6eb0: 61 74 65 73 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69  ates an.** [sqli
6ec0: 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74  te3_file] object
6ed0: 20 28 6f 72 2c 20 6d 6f 72 65 20 63 6f 6d 6d 6f   (or, more commo
6ee0: 6e 6c 79 2c 20 61 20 73 75 62 63 6c 61 73 73 20  nly, a subclass 
6ef0: 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  of the.** [sqlit
6f00: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 29  e3_file] object)
6f10: 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20   with a pointer 
6f20: 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  to an instance o
6f30: 66 20 74 68 69 73 20 6f 62 6a 65 63 74 2e 0a 2a  f this object..*
6f40: 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 64 65  * This object de
6f50: 66 69 6e 65 73 20 74 68 65 20 6d 65 74 68 6f 64  fines the method
6f60: 73 20 75 73 65 64 20 74 6f 20 70 65 72 66 6f 72  s used to perfor
6f70: 6d 20 76 61 72 69 6f 75 73 20 6f 70 65 72 61 74  m various operat
6f80: 69 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e 73 74 20  ions.** against 
6f90: 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 20 72 65  the open file re
6fa0: 70 72 65 73 65 6e 74 65 64 20 62 79 20 74 68 65  presented by the
6fb0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
6fc0: 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 49 66  object..**.** If
6fd0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   the [sqlite3_vf
6fe0: 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20  s.xOpen] method 
6ff0: 73 65 74 73 20 74 68 65 20 73 71 6c 69 74 65 33  sets the sqlite3
7000: 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65  _file.pMethods e
7010: 6c 65 6d 65 6e 74 20 0a 2a 2a 20 74 6f 20 61 20  lement .** to a 
7020: 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  non-NULL pointer
7030: 2c 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74  , then the sqlit
7040: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 2e 78 43  e3_io_methods.xC
7050: 6c 6f 73 65 20 6d 65 74 68 6f 64 0a 2a 2a 20 6d  lose method.** m
7060: 61 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 65 76  ay be invoked ev
7070: 65 6e 20 69 66 20 74 68 65 20 5b 73 71 6c 69 74  en if the [sqlit
7080: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 72 65  e3_vfs.xOpen] re
7090: 70 6f 72 74 65 64 20 74 68 61 74 20 69 74 20 66  ported that it f
70a0: 61 69 6c 65 64 2e 20 20 54 68 65 0a 2a 2a 20 6f  ailed.  The.** o
70b0: 6e 6c 79 20 77 61 79 20 74 6f 20 70 72 65 76 65  nly way to preve
70c0: 6e 74 20 61 20 63 61 6c 6c 20 74 6f 20 78 43 6c  nt a call to xCl
70d0: 6f 73 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20  ose following a 
70e0: 66 61 69 6c 65 64 20 5b 73 71 6c 69 74 65 33 5f  failed [sqlite3_
70f0: 76 66 73 2e 78 4f 70 65 6e 5d 0a 2a 2a 20 69 73  vfs.xOpen].** is
7100: 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65   for the [sqlite
7110: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 74 6f 20  3_vfs.xOpen] to 
7120: 73 65 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f  set the sqlite3_
7130: 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65 6c  file.pMethods el
7140: 65 6d 65 6e 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c  ement.** to NULL
7150: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67  ..**.** The flag
7160: 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 53  s argument to xS
7170: 79 6e 63 20 6d 61 79 20 62 65 20 6f 6e 65 20 6f  ync may be one o
7180: 66 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e  f [SQLITE_SYNC_N
7190: 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20 5b 53 51  ORMAL] or.** [SQ
71a0: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 5d 2e  LITE_SYNC_FULL].
71b0: 20 20 54 68 65 20 66 69 72 73 74 20 63 68 6f 69    The first choi
71c0: 63 65 20 69 73 20 74 68 65 20 6e 6f 72 6d 61 6c  ce is the normal
71d0: 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 20 54 68 65   fsync()..** The
71e0: 20 73 65 63 6f 6e 64 20 63 68 6f 69 63 65 20 69   second choice i
71f0: 73 20 61 20 4d 61 63 20 4f 53 20 58 20 73 74 79  s a Mac OS X sty
7200: 6c 65 20 66 75 6c 6c 73 79 6e 63 2e 20 20 54 68  le fullsync.  Th
7210: 65 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44  e [SQLITE_SYNC_D
7220: 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66 6c 61 67  ATAONLY].** flag
7230: 20 6d 61 79 20 62 65 20 4f 52 65 64 20 69 6e 20   may be ORed in 
7240: 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74  to indicate that
7250: 20 6f 6e 6c 79 20 74 68 65 20 64 61 74 61 20 6f   only the data o
7260: 66 20 74 68 65 20 66 69 6c 65 0a 2a 2a 20 61 6e  f the file.** an
7270: 64 20 6e 6f 74 20 69 74 73 20 69 6e 6f 64 65 20  d not its inode 
7280: 6e 65 65 64 73 20 74 6f 20 62 65 20 73 79 6e 63  needs to be sync
7290: 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e  ed..**.** The in
72a0: 74 65 67 65 72 20 76 61 6c 75 65 73 20 74 6f 20  teger values to 
72b0: 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c  xLock() and xUnl
72c0: 6f 63 6b 28 29 20 61 72 65 20 6f 6e 65 20 6f 66  ock() are one of
72d0: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
72e0: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f   [SQLITE_LOCK_NO
72f0: 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  NE],.** <li> [SQ
7300: 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44  LITE_LOCK_SHARED
7310: 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  ],.** <li> [SQLI
7320: 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44  TE_LOCK_RESERVED
7330: 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  ],.** <li> [SQLI
7340: 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d  TE_LOCK_PENDING]
7350: 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  , or.** <li> [SQ
7360: 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53  LITE_LOCK_EXCLUS
7370: 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  IVE]..** </ul>.*
7380: 2a 20 78 4c 6f 63 6b 28 29 20 69 6e 63 72 65 61  * xLock() increa
7390: 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 20 78 55  ses the lock. xU
73a0: 6e 6c 6f 63 6b 28 29 20 64 65 63 72 65 61 73 65  nlock() decrease
73b0: 73 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a 20 54  s the lock..** T
73c0: 68 65 20 78 43 68 65 63 6b 52 65 73 65 72 76 65  he xCheckReserve
73d0: 64 4c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 20 63  dLock() method c
73e0: 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 61 6e  hecks whether an
73f0: 79 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  y database conne
7400: 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74 68 65 72  ction,.** either
7410: 20 69 6e 20 74 68 69 73 20 70 72 6f 63 65 73 73   in this process
7420: 20 6f 72 20 69 6e 20 73 6f 6d 65 20 6f 74 68 65   or in some othe
7430: 72 20 70 72 6f 63 65 73 73 2c 20 69 73 20 68 6f  r process, is ho
7440: 6c 64 69 6e 67 20 61 20 52 45 53 45 52 56 45 44  lding a RESERVED
7450: 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c 20 6f 72  ,.** PENDING, or
7460: 20 45 58 43 4c 55 53 49 56 45 20 6c 6f 63 6b 20   EXCLUSIVE lock 
7470: 6f 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 49 74  on the file.  It
7480: 20 72 65 74 75 72 6e 73 20 74 72 75 65 0a 2a 2a   returns true.**
7490: 20 69 66 20 73 75 63 68 20 61 20 6c 6f 63 6b 20   if such a lock 
74a0: 65 78 69 73 74 73 20 61 6e 64 20 66 61 6c 73 65  exists and false
74b0: 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a   otherwise..**.*
74c0: 2a 20 54 68 65 20 78 46 69 6c 65 43 6f 6e 74 72  * The xFileContr
74d0: 6f 6c 28 29 20 6d 65 74 68 6f 64 20 69 73 20 61  ol() method is a
74e0: 20 67 65 6e 65 72 69 63 20 69 6e 74 65 72 66 61   generic interfa
74f0: 63 65 20 74 68 61 74 20 61 6c 6c 6f 77 73 20 63  ce that allows c
7500: 75 73 74 6f 6d 0a 2a 2a 20 56 46 53 20 69 6d 70  ustom.** VFS imp
7510: 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 74 6f 20  lementations to 
7520: 64 69 72 65 63 74 6c 79 20 63 6f 6e 74 72 6f 6c  directly control
7530: 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 75 73   an open file us
7540: 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  ing the.** [sqli
7550: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
7560: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20  ()] interface.  
7570: 54 68 65 20 73 65 63 6f 6e 64 20 22 6f 70 22 20  The second "op" 
7580: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 0a 2a  argument is an.*
7590: 2a 20 69 6e 74 65 67 65 72 20 6f 70 63 6f 64 65  * integer opcode
75a0: 2e 20 20 54 68 65 20 74 68 69 72 64 20 61 72 67  .  The third arg
75b0: 75 6d 65 6e 74 20 69 73 20 61 20 67 65 6e 65 72  ument is a gener
75c0: 69 63 20 70 6f 69 6e 74 65 72 20 69 6e 74 65 6e  ic pointer inten
75d0: 64 65 64 20 74 6f 0a 2a 2a 20 70 6f 69 6e 74 20  ded to.** point 
75e0: 74 6f 20 61 20 73 74 72 75 63 74 75 72 65 20 74  to a structure t
75f0: 68 61 74 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20  hat may contain 
7600: 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 73 70 61  arguments or spa
7610: 63 65 20 69 6e 20 77 68 69 63 68 20 74 6f 0a 2a  ce in which to.*
7620: 2a 20 77 72 69 74 65 20 72 65 74 75 72 6e 20 76  * write return v
7630: 61 6c 75 65 73 2e 20 20 50 6f 74 65 6e 74 69 61  alues.  Potentia
7640: 6c 20 75 73 65 73 20 66 6f 72 20 78 46 69 6c 65  l uses for xFile
7650: 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 67 68 74 20  Control() might 
7660: 62 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20  be.** functions 
7670: 74 6f 20 65 6e 61 62 6c 65 20 62 6c 6f 63 6b 69  to enable blocki
7680: 6e 67 20 6c 6f 63 6b 73 20 77 69 74 68 20 74 69  ng locks with ti
7690: 6d 65 6f 75 74 73 2c 20 74 6f 20 63 68 61 6e 67  meouts, to chang
76a0: 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69 6e 67  e the.** locking
76b0: 20 73 74 72 61 74 65 67 79 20 28 66 6f 72 20 65   strategy (for e
76c0: 78 61 6d 70 6c 65 20 74 6f 20 75 73 65 20 64 6f  xample to use do
76d0: 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 29 2c 20 74  t-file locks), t
76e0: 6f 20 69 6e 71 75 69 72 65 0a 2a 2a 20 61 62 6f  o inquire.** abo
76f0: 75 74 20 74 68 65 20 73 74 61 74 75 73 20 6f 66  ut the status of
7700: 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f 20 62   a lock, or to b
7710: 72 65 61 6b 20 73 74 61 6c 65 20 6c 6f 63 6b 73  reak stale locks
7720: 2e 20 20 54 68 65 20 53 51 4c 69 74 65 0a 2a 2a  .  The SQLite.**
7730: 20 63 6f 72 65 20 72 65 73 65 72 76 65 73 20 61   core reserves a
7740: 6c 6c 20 6f 70 63 6f 64 65 73 20 6c 65 73 73 20  ll opcodes less 
7750: 74 68 61 6e 20 31 30 30 20 66 6f 72 20 69 74 73  than 100 for its
7760: 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20 41 20 5b   own use..** A [
7770: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43  SQLITE_FCNTL_LOC
7780: 4b 53 54 41 54 45 20 7c 20 6c 69 73 74 20 6f 66  KSTATE | list of
7790: 20 6f 70 63 6f 64 65 73 5d 20 6c 65 73 73 20 74   opcodes] less t
77a0: 68 61 6e 20 31 30 30 20 69 73 20 61 76 61 69 6c  han 100 is avail
77b0: 61 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61  able..** Applica
77c0: 74 69 6f 6e 73 20 74 68 61 74 20 64 65 66 69 6e  tions that defin
77d0: 65 20 61 20 63 75 73 74 6f 6d 20 78 46 69 6c 65  e a custom xFile
77e0: 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 73  Control method s
77f0: 68 6f 75 6c 64 20 75 73 65 20 6f 70 63 6f 64 65  hould use opcode
7800: 73 0a 2a 2a 20 67 72 65 61 74 65 72 20 74 68 61  s.** greater tha
7810: 6e 20 31 30 30 20 74 6f 20 61 76 6f 69 64 20 63  n 100 to avoid c
7820: 6f 6e 66 6c 69 63 74 73 2e 20 20 56 46 53 20 69  onflicts.  VFS i
7830: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73  mplementations s
7840: 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20  hould.** return 
7850: 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44  [SQLITE_NOTFOUND
7860: 5d 20 66 6f 72 20 66 69 6c 65 20 63 6f 6e 74 72  ] for file contr
7870: 6f 6c 20 6f 70 63 6f 64 65 73 20 74 68 61 74 20  ol opcodes that 
7880: 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 72  they do not.** r
7890: 65 63 6f 67 6e 69 7a 65 2e 0a 2a 2a 0a 2a 2a 20  ecognize..**.** 
78a0: 54 68 65 20 78 53 65 63 74 6f 72 53 69 7a 65 28  The xSectorSize(
78b0: 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73  ) method returns
78c0: 20 74 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65   the sector size
78d0: 20 6f 66 20 74 68 65 0a 2a 2a 20 64 65 76 69 63   of the.** devic
78e0: 65 20 74 68 61 74 20 75 6e 64 65 72 6c 69 65 73  e that underlies
78f0: 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20   the file.  The 
7900: 73 65 63 74 6f 72 20 73 69 7a 65 20 69 73 20 74  sector size is t
7910: 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77 72  he.** minimum wr
7920: 69 74 65 20 74 68 61 74 20 63 61 6e 20 62 65 20  ite that can be 
7930: 70 65 72 66 6f 72 6d 65 64 20 77 69 74 68 6f 75  performed withou
7940: 74 20 64 69 73 74 75 72 62 69 6e 67 0a 2a 2a 20  t disturbing.** 
7950: 6f 74 68 65 72 20 62 79 74 65 73 20 69 6e 20 74  other bytes in t
7960: 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20 78 44  he file.  The xD
7970: 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73  eviceCharacteris
7980: 74 69 63 73 28 29 0a 2a 2a 20 6d 65 74 68 6f 64  tics().** method
7990: 20 72 65 74 75 72 6e 73 20 61 20 62 69 74 20 76   returns a bit v
79a0: 65 63 74 6f 72 20 64 65 73 63 72 69 62 69 6e 67  ector describing
79b0: 20 62 65 68 61 76 69 6f 72 73 20 6f 66 20 74 68   behaviors of th
79c0: 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20  e.** underlying 
79d0: 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75  device:.**.** <u
79e0: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  l>.** <li> [SQLI
79f0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 5d  TE_IOCAP_ATOMIC]
7a00: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
7a10: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32  _IOCAP_ATOMIC512
7a20: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
7a30: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b  E_IOCAP_ATOMIC1K
7a40: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
7a50: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b  E_IOCAP_ATOMIC2K
7a60: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
7a70: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b  E_IOCAP_ATOMIC4K
7a80: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
7a90: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b  E_IOCAP_ATOMIC8K
7aa0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
7ab0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36  E_IOCAP_ATOMIC16
7ac0: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
7ad0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33  TE_IOCAP_ATOMIC3
7ae0: 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  2K].** <li> [SQL
7af0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
7b00: 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  64K].** <li> [SQ
7b10: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f  LITE_IOCAP_SAFE_
7b20: 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e 20  APPEND].** <li> 
7b30: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45  [SQLITE_IOCAP_SE
7b40: 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 2f 75  QUENTIAL].** </u
7b50: 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c  l>.**.** The SQL
7b60: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
7b70: 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20   property means 
7b80: 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20  that all writes 
7b90: 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61  of.** any size a
7ba0: 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20  re atomic.  The 
7bb0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
7bc0: 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a  MICnnn values.**
7bd0: 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74 65   mean that write
7be0: 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74  s of blocks that
7bf0: 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69   are nnn bytes i
7c00: 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72  n size and.** ar
7c10: 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20  e aligned to an 
7c20: 61 64 64 72 65 73 73 20 77 68 69 63 68 20 69 73  address which is
7c30: 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74   an integer mult
7c40: 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61  iple of.** nnn a
7c50: 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20  re atomic.  The 
7c60: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46  SQLITE_IOCAP_SAF
7c70: 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d  E_APPEND value m
7c80: 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65  eans.** that whe
7c90: 6e 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64  n data is append
7ca0: 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68  ed to a file, th
7cb0: 65 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64  e data is append
7cc0: 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e  ed.** first then
7cd0: 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
7ce0: 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65   file is extende
7cf0: 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68  d, never the oth
7d00: 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64  er.** way around
7d10: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
7d20: 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70  CAP_SEQUENTIAL p
7d30: 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68  roperty means th
7d40: 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  at.** informatio
7d50: 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20  n is written to 
7d60: 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65  disk in the same
7d70: 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a   order as calls.
7d80: 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e 0a  ** to xWrite()..
7d90: 2a 2a 0a 2a 2a 20 49 66 20 78 52 65 61 64 28 29  **.** If xRead()
7da0: 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f   returns SQLITE_
7db0: 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44  IOERR_SHORT_READ
7dc0: 20 69 74 20 6d 75 73 74 20 61 6c 73 6f 20 66 69   it must also fi
7dd0: 6c 6c 0a 2a 2a 20 69 6e 20 74 68 65 20 75 6e 72  ll.** in the unr
7de0: 65 61 64 20 70 6f 72 74 69 6f 6e 73 20 6f 66 20  ead portions of 
7df0: 74 68 65 20 62 75 66 66 65 72 20 77 69 74 68 20  the buffer with 
7e00: 7a 65 72 6f 73 2e 20 20 41 20 56 46 53 20 74 68  zeros.  A VFS th
7e10: 61 74 0a 2a 2a 20 66 61 69 6c 73 20 74 6f 20 7a  at.** fails to z
7e20: 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72  ero-fill short r
7e30: 65 61 64 73 20 6d 69 67 68 74 20 73 65 65 6d 20  eads might seem 
7e40: 74 6f 20 77 6f 72 6b 2e 20 20 48 6f 77 65 76 65  to work.  Howeve
7e50: 72 2c 0a 2a 2a 20 66 61 69 6c 75 72 65 20 74 6f  r,.** failure 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 77 69 6c 6c 20 65 76 65 6e   reads will even
7e80: 74 75 61 6c 6c 79 20 6c 65 61 64 20 74 6f 0a 2a  tually lead to.*
7e90: 2a 20 64 61 74 61 62 61 73 65 20 63 6f 72 72 75  * database corru
7ea0: 70 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65  ption..*/.typede
7eb0: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
7ec0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69  _io_methods sqli
7ed0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a  te3_io_methods;.
7ee0: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69  struct sqlite3_i
7ef0: 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69 6e  o_methods {.  in
7f00: 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e  t iVersion;.  in
7f10: 74 20 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69  t (*xClose)(sqli
7f20: 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e  te3_file*);.  in
7f30: 74 20 28 2a 78 52 65 61 64 29 28 73 71 6c 69 74  t (*xRead)(sqlit
7f40: 65 33 5f 66 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c  e3_file*, void*,
7f50: 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74   int iAmt, sqlit
7f60: 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b  e3_int64 iOfst);
7f70: 0a 20 20 69 6e 74 20 28 2a 78 57 72 69 74 65 29  .  int (*xWrite)
7f80: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
7f90: 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
7fa0: 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69   iAmt, sqlite3_i
7fb0: 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69  nt64 iOfst);.  i
7fc0: 6e 74 20 28 2a 78 54 72 75 6e 63 61 74 65 29 28  nt (*xTruncate)(
7fd0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73  sqlite3_file*, s
7fe0: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 69 7a  qlite3_int64 siz
7ff0: 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e  e);.  int (*xSyn
8000: 63 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  c)(sqlite3_file*
8010: 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20  , int flags);.  
8020: 69 6e 74 20 28 2a 78 46 69 6c 65 53 69 7a 65 29  int (*xFileSize)
8030: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
8040: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 70  sqlite3_int64 *p
8050: 53 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78  Size);.  int (*x
8060: 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69  Lock)(sqlite3_fi
8070: 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74  le*, int);.  int
8080: 20 28 2a 78 55 6e 6c 6f 63 6b 29 28 73 71 6c 69   (*xUnlock)(sqli
8090: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b  te3_file*, int);
80a0: 0a 20 20 69 6e 74 20 28 2a 78 43 68 65 63 6b 52  .  int (*xCheckR
80b0: 65 73 65 72 76 65 64 4c 6f 63 6b 29 28 73 71 6c  eservedLock)(sql
80c0: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20  ite3_file*, int 
80d0: 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74  *pResOut);.  int
80e0: 20 28 2a 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 29   (*xFileControl)
80f0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
8100: 69 6e 74 20 6f 70 2c 20 76 6f 69 64 20 2a 70 41  int op, void *pA
8110: 72 67 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 65  rg);.  int (*xSe
8120: 63 74 6f 72 53 69 7a 65 29 28 73 71 6c 69 74 65  ctorSize)(sqlite
8130: 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20  3_file*);.  int 
8140: 28 2a 78 44 65 76 69 63 65 43 68 61 72 61 63 74  (*xDeviceCharact
8150: 65 72 69 73 74 69 63 73 29 28 73 71 6c 69 74 65  eristics)(sqlite
8160: 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a 20 4d  3_file*);.  /* M
8170: 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65  ethods above are
8180: 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69   valid for versi
8190: 6f 6e 20 31 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  on 1 */.  int (*
81a0: 78 53 68 6d 4d 61 70 29 28 73 71 6c 69 74 65 33  xShmMap)(sqlite3
81b0: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 69 50 67 2c  _file*, int iPg,
81c0: 20 69 6e 74 20 70 67 73 7a 2c 20 69 6e 74 2c 20   int pgsz, int, 
81d0: 76 6f 69 64 20 76 6f 6c 61 74 69 6c 65 2a 2a 29  void volatile**)
81e0: 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 4c 6f  ;.  int (*xShmLo
81f0: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ck)(sqlite3_file
8200: 2a 2c 20 69 6e 74 20 6f 66 66 73 65 74 2c 20 69  *, int offset, i
8210: 6e 74 20 6e 2c 20 69 6e 74 20 66 6c 61 67 73 29  nt n, int flags)
8220: 3b 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 6d 42  ;.  void (*xShmB
8230: 61 72 72 69 65 72 29 28 73 71 6c 69 74 65 33 5f  arrier)(sqlite3_
8240: 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  file*);.  int (*
8250: 78 53 68 6d 55 6e 6d 61 70 29 28 73 71 6c 69 74  xShmUnmap)(sqlit
8260: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 64 65  e3_file*, int de
8270: 6c 65 74 65 46 6c 61 67 29 3b 0a 20 20 2f 2a 20  leteFlag);.  /* 
8280: 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72  Methods above ar
8290: 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73  e valid for vers
82a0: 69 6f 6e 20 32 20 2a 2f 0a 20 20 2f 2a 20 41 64  ion 2 */.  /* Ad
82b0: 64 69 74 69 6f 6e 61 6c 20 6d 65 74 68 6f 64 73  ditional methods
82c0: 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e   may be added in
82d0: 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
82e0: 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.};../*.** CA
82f0: 50 49 33 52 45 46 3a 20 53 74 61 6e 64 61 72 64  PI3REF: Standard
8300: 20 46 69 6c 65 20 43 6f 6e 74 72 6f 6c 20 4f 70   File Control Op
8310: 63 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  codes.**.** Thes
8320: 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61  e integer consta
8330: 6e 74 73 20 61 72 65 20 6f 70 63 6f 64 65 73 20  nts are opcodes 
8340: 66 6f 72 20 74 68 65 20 78 46 69 6c 65 43 6f 6e  for the xFileCon
8350: 74 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f  trol method.** o
8360: 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69  f the [sqlite3_i
8370: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63  o_methods] objec
8380: 74 20 61 6e 64 20 66 6f 72 20 74 68 65 20 5b 73  t and for the [s
8390: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
83a0: 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66  rol()].** interf
83b0: 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  ace..**.** The [
83c0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43  SQLITE_FCNTL_LOC
83d0: 4b 53 54 41 54 45 5d 20 6f 70 63 6f 64 65 20 69  KSTATE] opcode i
83e0: 73 20 75 73 65 64 20 66 6f 72 20 64 65 62 75 67  s used for debug
83f0: 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a 2a 20 6f  ging.  This.** o
8400: 70 63 6f 64 65 20 63 61 75 73 65 73 20 74 68 65  pcode causes the
8410: 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65   xFileControl me
8420: 74 68 6f 64 20 74 6f 20 77 72 69 74 65 20 74 68  thod to write th
8430: 65 20 63 75 72 72 65 6e 74 20 73 74 61 74 65 20  e current state 
8440: 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f 63 6b 20 28  of.** the lock (
8450: 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 4c  one of [SQLITE_L
8460: 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53 51 4c 49  OCK_NONE], [SQLI
8470: 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c  TE_LOCK_SHARED],
8480: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  .** [SQLITE_LOCK
8490: 5f 52 45 53 45 52 56 45 44 5d 2c 20 5b 53 51 4c  _RESERVED], [SQL
84a0: 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47  ITE_LOCK_PENDING
84b0: 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4c 4f  ], or [SQLITE_LO
84c0: 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 29 0a 2a  CK_EXCLUSIVE]).*
84d0: 2a 20 69 6e 74 6f 20 61 6e 20 69 6e 74 65 67 65  * into an intege
84e0: 72 20 74 68 61 74 20 74 68 65 20 70 41 72 67 20  r that the pArg 
84f0: 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20  argument points 
8500: 74 6f 2e 20 54 68 69 73 20 63 61 70 61 62 69 6c  to. This capabil
8510: 69 74 79 0a 2a 2a 20 69 73 20 75 73 65 64 20 64  ity.** is used d
8520: 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20 61 6e  uring testing an
8530: 64 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20  d only needs to 
8540: 62 65 20 73 75 70 70 6f 72 74 65 64 20 77 68 65  be supported whe
8550: 6e 20 53 51 4c 49 54 45 5f 54 45 53 54 0a 2a 2a  n SQLITE_TEST.**
8560: 20 69 73 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 20   is defined..** 
8570: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  <ul>.** <li>[[SQ
8580: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f  LITE_FCNTL_SIZE_
8590: 48 49 4e 54 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53  HINT]].** The [S
85a0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45  QLITE_FCNTL_SIZE
85b0: 5f 48 49 4e 54 5d 20 6f 70 63 6f 64 65 20 69 73  _HINT] opcode is
85c0: 20 75 73 65 64 20 62 79 20 53 51 4c 69 74 65 20   used by SQLite 
85d0: 74 6f 20 67 69 76 65 20 74 68 65 20 56 46 53 0a  to give the VFS.
85e0: 2a 2a 20 6c 61 79 65 72 20 61 20 68 69 6e 74 20  ** layer a hint 
85f0: 6f 66 20 68 6f 77 20 6c 61 72 67 65 20 74 68 65  of how large the
8600: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77   database file w
8610: 69 6c 6c 20 67 72 6f 77 20 74 6f 20 62 65 20 64  ill grow to be d
8620: 75 72 69 6e 67 20 74 68 65 0a 2a 2a 20 63 75 72  uring the.** cur
8630: 72 65 6e 74 20 74 72 61 6e 73 61 63 74 69 6f 6e  rent transaction
8640: 2e 20 20 54 68 69 73 20 68 69 6e 74 20 69 73 20  .  This hint is 
8650: 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 64 20 74  not guaranteed t
8660: 6f 20 62 65 20 61 63 63 75 72 61 74 65 20 62 75  o be accurate bu
8670: 74 20 69 74 0a 2a 2a 20 69 73 20 6f 66 74 65 6e  t it.** is often
8680: 20 63 6c 6f 73 65 2e 20 20 54 68 65 20 75 6e 64   close.  The und
8690: 65 72 6c 79 69 6e 67 20 56 46 53 20 6d 69 67 68  erlying VFS migh
86a0: 74 20 63 68 6f 6f 73 65 20 74 6f 20 70 72 65 61  t choose to prea
86b0: 6c 6c 6f 63 61 74 65 20 64 61 74 61 62 61 73 65  llocate database
86c0: 0a 2a 2a 20 66 69 6c 65 20 73 70 61 63 65 20 62  .** file space b
86d0: 61 73 65 64 20 6f 6e 20 74 68 69 73 20 68 69 6e  ased on this hin
86e0: 74 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 68 65  t in order to he
86f0: 6c 70 20 77 72 69 74 65 73 20 74 6f 20 74 68 65  lp writes to the
8700: 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c   database.** fil
8710: 65 20 72 75 6e 20 66 61 73 74 65 72 2e 0a 2a 2a  e run faster..**
8720: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
8730: 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a  _FCNTL_CHUNK_SIZ
8740: 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  E]].** The [SQLI
8750: 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53  TE_FCNTL_CHUNK_S
8760: 49 5a 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75  IZE] opcode is u
8770: 73 65 64 20 74 6f 20 72 65 71 75 65 73 74 20 74  sed to request t
8780: 68 61 74 20 74 68 65 20 56 46 53 0a 2a 2a 20 65  hat the VFS.** e
8790: 78 74 65 6e 64 73 20 61 6e 64 20 74 72 75 6e 63  xtends and trunc
87a0: 61 74 65 73 20 74 68 65 20 64 61 74 61 62 61 73  ates the databas
87b0: 65 20 66 69 6c 65 20 69 6e 20 63 68 75 6e 6b 73  e file in chunks
87c0: 20 6f 66 20 61 20 73 69 7a 65 20 73 70 65 63 69   of a size speci
87d0: 66 69 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 75  fied.** by the u
87e0: 73 65 72 2e 20 54 68 65 20 66 6f 75 72 74 68 20  ser. The fourth 
87f0: 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c  argument to [sql
8800: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
8810: 6c 28 29 5d 20 73 68 6f 75 6c 64 20 0a 2a 2a 20  l()] should .** 
8820: 70 6f 69 6e 74 20 74 6f 20 61 6e 20 69 6e 74 65  point to an inte
8830: 67 65 72 20 28 74 79 70 65 20 69 6e 74 29 20 63  ger (type int) c
8840: 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 6e 65  ontaining the ne
8850: 77 20 63 68 75 6e 6b 2d 73 69 7a 65 20 74 6f 20  w chunk-size to 
8860: 75 73 65 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6e  use.** for the n
8870: 6f 6d 69 6e 61 74 65 64 20 64 61 74 61 62 61 73  ominated databas
8880: 65 2e 20 41 6c 6c 6f 63 61 74 69 6e 67 20 64 61  e. Allocating da
8890: 74 61 62 61 73 65 20 66 69 6c 65 20 73 70 61 63  tabase file spac
88a0: 65 20 69 6e 20 6c 61 72 67 65 0a 2a 2a 20 63 68  e in large.** ch
88b0: 75 6e 6b 73 20 28 73 61 79 20 31 4d 42 20 61 74  unks (say 1MB at
88c0: 20 61 20 74 69 6d 65 29 2c 20 6d 61 79 20 72 65   a time), may re
88d0: 64 75 63 65 20 66 69 6c 65 2d 73 79 73 74 65 6d  duce file-system
88e0: 20 66 72 61 67 6d 65 6e 74 61 74 69 6f 6e 20 61   fragmentation a
88f0: 6e 64 0a 2a 2a 20 69 6d 70 72 6f 76 65 20 70 65  nd.** improve pe
8900: 72 66 6f 72 6d 61 6e 63 65 20 6f 6e 20 73 6f 6d  rformance on som
8910: 65 20 73 79 73 74 65 6d 73 2e 0a 2a 2a 0a 2a 2a  e systems..**.**
8920: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
8930: 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52  NTL_FILE_POINTER
8940: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
8950: 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49  E_FCNTL_FILE_POI
8960: 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20 69 73 20  NTER] opcode is 
8970: 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 61  used to obtain a
8980: 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74   pointer.** to t
8990: 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  he [sqlite3_file
89a0: 5d 20 6f 62 6a 65 63 74 20 61 73 73 6f 63 69 61  ] object associa
89b0: 74 65 64 20 77 69 74 68 20 61 20 70 61 72 74 69  ted with a parti
89c0: 63 75 6c 61 72 20 64 61 74 61 62 61 73 65 0a 2a  cular database.*
89d0: 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 53  * connection.  S
89e0: 65 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ee the [sqlite3_
89f0: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20  file_control()] 
8a00: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  documentation fo
8a10: 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20  r.** additional 
8a20: 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a  information..**.
8a30: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
8a40: 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54  FCNTL_SYNC_OMITT
8a50: 45 44 5d 5d 0a 2a 2a 20 5e 28 54 68 65 20 5b 53  ED]].** ^(The [S
8a60: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43  QLITE_FCNTL_SYNC
8a70: 5f 4f 4d 49 54 54 45 44 5d 20 6f 70 63 6f 64 65  _OMITTED] opcode
8a80: 20 69 73 20 67 65 6e 65 72 61 74 65 64 20 69 6e   is generated in
8a90: 74 65 72 6e 61 6c 6c 79 20 62 79 0a 2a 2a 20 53  ternally by.** S
8aa0: 51 4c 69 74 65 20 61 6e 64 20 73 65 6e 74 20 74  QLite and sent t
8ab0: 6f 20 61 6c 6c 20 56 46 53 65 73 20 69 6e 20 70  o all VFSes in p
8ac0: 6c 61 63 65 20 6f 66 20 61 20 63 61 6c 6c 20 74  lace of a call t
8ad0: 6f 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68  o the xSync meth
8ae0: 6f 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 64  od.** when the d
8af0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
8b00: 6f 6e 20 68 61 73 20 5b 50 52 41 47 4d 41 20 73  on has [PRAGMA s
8b10: 79 6e 63 68 72 6f 6e 6f 75 73 5d 20 73 65 74 20  ynchronous] set 
8b20: 74 6f 20 4f 46 46 2e 29 5e 0a 2a 2a 20 53 6f 6d  to OFF.)^.** Som
8b30: 65 20 73 70 65 63 69 61 6c 69 7a 65 64 20 56 46  e specialized VF
8b40: 53 65 73 20 6e 65 65 64 20 74 68 69 73 20 73 69  Ses need this si
8b50: 67 6e 61 6c 20 69 6e 20 6f 72 64 65 72 20 74 6f  gnal in order to
8b60: 20 6f 70 65 72 61 74 65 20 63 6f 72 72 65 63 74   operate correct
8b70: 6c 79 0a 2a 2a 20 77 68 65 6e 20 5b 50 52 41 47  ly.** when [PRAG
8b80: 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 20 7c  MA synchronous |
8b90: 20 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e   PRAGMA synchron
8ba0: 6f 75 73 3d 4f 46 46 5d 20 69 73 20 73 65 74 2c  ous=OFF] is set,
8bb0: 20 62 75 74 20 6d 6f 73 74 20 0a 2a 2a 20 56 46   but most .** VF
8bc0: 53 65 73 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20  Ses do not need 
8bd0: 74 68 69 73 20 73 69 67 6e 61 6c 20 61 6e 64 20  this signal and 
8be0: 73 68 6f 75 6c 64 20 73 69 6c 65 6e 74 6c 79 20  should silently 
8bf0: 69 67 6e 6f 72 65 20 74 68 69 73 20 6f 70 63 6f  ignore this opco
8c00: 64 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69  de..** Applicati
8c10: 6f 6e 73 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63  ons should not c
8c20: 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  all [sqlite3_fil
8c30: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74  e_control()] wit
8c40: 68 20 74 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65  h this.** opcode
8c50: 20 61 73 20 64 6f 69 6e 67 20 73 6f 20 6d 61 79   as doing so may
8c60: 20 64 69 73 72 75 70 74 20 74 68 65 20 6f 70 65   disrupt the ope
8c70: 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 70  ration of the sp
8c80: 65 63 69 61 6c 69 7a 65 64 20 56 46 53 65 73 0a  ecialized VFSes.
8c90: 2a 2a 20 74 68 61 74 20 64 6f 20 72 65 71 75 69  ** that do requi
8ca0: 72 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c  re it.  .**.** <
8cb0: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
8cc0: 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59  L_WIN32_AV_RETRY
8cd0: 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  ]].** ^The [SQLI
8ce0: 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41  TE_FCNTL_WIN32_A
8cf0: 56 5f 52 45 54 52 59 5d 20 6f 70 63 6f 64 65 20  V_RETRY] opcode 
8d00: 69 73 20 75 73 65 64 20 74 6f 20 63 6f 6e 66 69  is used to confi
8d10: 67 75 72 65 20 61 75 74 6f 6d 61 74 69 63 0a 2a  gure automatic.*
8d20: 2a 20 72 65 74 72 79 20 63 6f 75 6e 74 73 20 61  * retry counts a
8d30: 6e 64 20 69 6e 74 65 72 76 61 6c 73 20 66 6f 72  nd intervals for
8d40: 20 63 65 72 74 61 69 6e 20 64 69 73 6b 20 49 2f   certain disk I/
8d50: 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20 66 6f 72  O operations for
8d60: 20 74 68 65 0a 2a 2a 20 77 69 6e 64 6f 77 73 20   the.** windows 
8d70: 5b 56 46 53 5d 20 69 6e 20 6f 72 64 65 72 20 74  [VFS] in order t
8d80: 6f 20 70 72 6f 76 69 64 65 20 72 6f 62 75 73 74  o provide robust
8d90: 6e 65 73 73 20 69 6e 20 74 68 65 20 70 72 65 73  ness in the pres
8da0: 65 6e 63 65 20 6f 66 0a 2a 2a 20 61 6e 74 69 2d  ence of.** anti-
8db0: 76 69 72 75 73 20 70 72 6f 67 72 61 6d 73 2e 20  virus programs. 
8dc0: 20 42 79 20 64 65 66 61 75 6c 74 2c 20 74 68 65   By default, the
8dd0: 20 77 69 6e 64 6f 77 73 20 56 46 53 20 77 69 6c   windows VFS wil
8de0: 6c 20 72 65 74 72 79 20 66 69 6c 65 20 72 65 61  l retry file rea
8df0: 64 2c 0a 2a 2a 20 66 69 6c 65 20 77 72 69 74 65  d,.** file write
8e00: 2c 20 61 6e 64 20 66 69 6c 65 20 64 65 6c 65 74  , and file delet
8e10: 65 20 6f 70 65 72 61 74 69 6f 6e 73 20 75 70 20  e operations up 
8e20: 74 6f 20 31 30 20 74 69 6d 65 73 2c 20 77 69 74  to 10 times, wit
8e30: 68 20 61 20 64 65 6c 61 79 0a 2a 2a 20 6f 66 20  h a delay.** of 
8e40: 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20  25 milliseconds 
8e50: 62 65 66 6f 72 65 20 74 68 65 20 66 69 72 73 74  before the first
8e60: 20 72 65 74 72 79 20 61 6e 64 20 77 69 74 68 20   retry and with 
8e70: 74 68 65 20 64 65 6c 61 79 20 69 6e 63 72 65 61  the delay increa
8e80: 73 69 6e 67 0a 2a 2a 20 62 79 20 61 6e 20 61 64  sing.** by an ad
8e90: 64 69 74 69 6f 6e 61 6c 20 32 35 20 6d 69 6c 6c  ditional 25 mill
8ea0: 69 73 65 63 6f 6e 64 73 20 77 69 74 68 20 65 61  iseconds with ea
8eb0: 63 68 20 73 75 62 73 65 71 75 65 6e 74 20 72 65  ch subsequent re
8ec0: 74 72 79 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70  try.  This.** op
8ed0: 63 6f 64 65 20 61 6c 6c 6f 77 73 20 74 68 65 73  code allows thes
8ee0: 65 20 74 77 6f 20 76 61 6c 75 65 73 20 28 31 30  e two values (10
8ef0: 20 72 65 74 72 69 65 73 20 61 6e 64 20 32 35 20   retries and 25 
8f00: 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20  milliseconds of 
8f10: 64 65 6c 61 79 29 0a 2a 2a 20 74 6f 20 62 65 20  delay).** to be 
8f20: 61 64 6a 75 73 74 65 64 2e 20 20 54 68 65 20 76  adjusted.  The v
8f30: 61 6c 75 65 73 20 61 72 65 20 63 68 61 6e 67 65  alues are change
8f40: 64 20 66 6f 72 20 61 6c 6c 20 64 61 74 61 62 61  d for all databa
8f50: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a  se connections.*
8f60: 2a 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d  * within the sam
8f70: 65 20 70 72 6f 63 65 73 73 2e 20 20 54 68 65 20  e process.  The 
8f80: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f  argument is a po
8f90: 69 6e 74 65 72 20 74 6f 20 61 6e 20 61 72 72 61  inter to an arra
8fa0: 79 20 6f 66 20 74 77 6f 0a 2a 2a 20 69 6e 74 65  y of two.** inte
8fb0: 67 65 72 73 20 77 68 65 72 65 20 74 68 65 20 66  gers where the f
8fc0: 69 72 73 74 20 69 6e 74 65 67 65 72 20 69 20 74  irst integer i t
8fd0: 68 65 20 6e 65 77 20 72 65 74 72 79 20 63 6f 75  he new retry cou
8fe0: 6e 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e  nt and the secon
8ff0: 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20 69 73 20  d.** integer is 
9000: 74 68 65 20 64 65 6c 61 79 2e 20 20 49 66 20 65  the delay.  If e
9010: 69 74 68 65 72 20 69 6e 74 65 67 65 72 20 69 73  ither integer is
9020: 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20   negative, then 
9030: 74 68 65 20 73 65 74 74 69 6e 67 0a 2a 2a 20 69  the setting.** i
9040: 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 20 62 75  s not changed bu
9050: 74 20 69 6e 73 74 65 61 64 20 74 68 65 20 70 72  t instead the pr
9060: 69 6f 72 20 76 61 6c 75 65 20 6f 66 20 74 68 61  ior value of tha
9070: 74 20 73 65 74 74 69 6e 67 20 69 73 20 77 72 69  t setting is wri
9080: 74 74 65 6e 0a 2a 2a 20 69 6e 74 6f 20 74 68 65  tten.** into the
9090: 20 61 72 72 61 79 20 65 6e 74 72 79 2c 20 61 6c   array entry, al
90a0: 6c 6f 77 69 6e 67 20 74 68 65 20 63 75 72 72 65  lowing the curre
90b0: 6e 74 20 72 65 74 72 79 20 73 65 74 74 69 6e 67  nt retry setting
90c0: 73 20 74 6f 20 62 65 0a 2a 2a 20 69 6e 74 65 72  s to be.** inter
90d0: 72 6f 67 61 74 65 64 2e 20 20 54 68 65 20 7a 44  rogated.  The zD
90e0: 62 4e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20  bName parameter 
90f0: 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a  is ignored..**.*
9100: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
9110: 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c  CNTL_PERSIST_WAL
9120: 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  ]].** ^The [SQLI
9130: 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54  TE_FCNTL_PERSIST
9140: 5f 57 41 4c 5d 20 6f 70 63 6f 64 65 20 69 73 20  _WAL] opcode is 
9150: 75 73 65 64 20 74 6f 20 73 65 74 20 6f 72 20 71  used to set or q
9160: 75 65 72 79 20 74 68 65 0a 2a 2a 20 70 65 72 73  uery the.** pers
9170: 69 73 74 65 6e 74 20 5b 57 41 4c 20 7c 20 57 72  istent [WAL | Wr
9180: 69 74 65 20 41 68 65 61 64 20 4c 6f 67 5d 20 73  ite Ahead Log] s
9190: 65 74 74 69 6e 67 2e 20 20 42 79 20 64 65 66 61  etting.  By defa
91a0: 75 6c 74 2c 20 74 68 65 20 61 75 78 69 6c 69 61  ult, the auxilia
91b0: 72 79 0a 2a 2a 20 77 72 69 74 65 20 61 68 65 61  ry.** write ahea
91c0: 64 20 6c 6f 67 20 61 6e 64 20 73 68 61 72 65 64  d log and shared
91d0: 20 6d 65 6d 6f 72 79 20 66 69 6c 65 73 20 75 73   memory files us
91e0: 65 64 20 66 6f 72 20 74 72 61 6e 73 61 63 74 69  ed for transacti
91f0: 6f 6e 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 61 72  on control.** ar
9200: 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  e automatically 
9210: 64 65 6c 65 74 65 64 20 77 68 65 6e 20 74 68 65  deleted when the
9220: 20 6c 61 74 65 73 74 20 63 6f 6e 6e 65 63 74 69   latest connecti
9230: 6f 6e 20 74 6f 20 74 68 65 20 64 61 74 61 62 61  on to the databa
9240: 73 65 0a 2a 2a 20 63 6c 6f 73 65 73 2e 20 20 53  se.** closes.  S
9250: 65 74 74 69 6e 67 20 70 65 72 73 69 73 74 65 6e  etting persisten
9260: 74 20 57 41 4c 20 6d 6f 64 65 20 63 61 75 73 65  t WAL mode cause
9270: 73 20 74 68 6f 73 65 20 66 69 6c 65 73 20 74 6f  s those files to
9280: 20 70 65 72 73 69 73 74 20 61 66 74 65 72 0a 2a   persist after.*
9290: 2a 20 63 6c 6f 73 65 2e 20 20 50 65 72 73 69 73  * close.  Persis
92a0: 74 69 6e 67 20 74 68 65 20 66 69 6c 65 73 20 69  ting the files i
92b0: 73 20 75 73 65 66 75 6c 20 77 68 65 6e 20 6f 74  s useful when ot
92c0: 68 65 72 20 70 72 6f 63 65 73 73 65 73 20 74 68  her processes th
92d0: 61 74 20 64 6f 20 6e 6f 74 0a 2a 2a 20 68 61 76  at do not.** hav
92e0: 65 20 77 72 69 74 65 20 70 65 72 6d 69 73 73 69  e write permissi
92f0: 6f 6e 20 6f 6e 20 74 68 65 20 64 69 72 65 63 74  on on the direct
9300: 6f 72 79 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  ory containing t
9310: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
9320: 20 77 61 6e 74 0a 2a 2a 20 74 6f 20 72 65 61 64   want.** to read
9330: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
9340: 6c 65 2c 20 61 73 20 74 68 65 20 57 41 4c 20 61  le, as the WAL a
9350: 6e 64 20 73 68 61 72 65 64 20 6d 65 6d 6f 72 79  nd shared memory
9360: 20 66 69 6c 65 73 20 6d 75 73 74 20 65 78 69 73   files must exis
9370: 74 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20 66 6f  t.** in order fo
9380: 72 20 74 68 65 20 64 61 74 61 62 61 73 65 20 74  r the database t
9390: 6f 20 62 65 20 72 65 61 64 61 62 6c 65 2e 20 20  o be readable.  
93a0: 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  The fourth param
93b0: 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  eter to.** [sqli
93c0: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
93d0: 28 29 5d 20 66 6f 72 20 74 68 69 73 20 6f 70 63  ()] for this opc
93e0: 6f 64 65 20 73 68 6f 75 6c 64 20 62 65 20 61 20  ode should be a 
93f0: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
9400: 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61 74 20 69  teger..** That i
9410: 6e 74 65 67 65 72 20 69 73 20 30 20 74 6f 20 64  nteger is 0 to d
9420: 69 73 61 62 6c 65 20 70 65 72 73 69 73 74 65 6e  isable persisten
9430: 74 20 57 41 4c 20 6d 6f 64 65 20 6f 72 20 31 20  t WAL mode or 1 
9440: 74 6f 20 65 6e 61 62 6c 65 20 70 65 72 73 69 73  to enable persis
9450: 74 65 6e 74 0a 2a 2a 20 57 41 4c 20 6d 6f 64 65  tent.** WAL mode
9460: 2e 20 20 49 66 20 74 68 65 20 69 6e 74 65 67 65  .  If the intege
9470: 72 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 69 74  r is -1, then it
9480: 20 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20   is overwritten 
9490: 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74  with the current
94a0: 0a 2a 2a 20 57 41 4c 20 70 65 72 73 69 73 74 65  .** WAL persiste
94b0: 6e 63 65 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a  nce setting..**.
94c0: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
94d0: 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f  FCNTL_POWERSAFE_
94e0: 4f 56 45 52 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e  OVERWRITE]].** ^
94f0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
9500: 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52  L_POWERSAFE_OVER
9510: 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 69 73  WRITE] opcode is
9520: 20 75 73 65 64 20 74 6f 20 73 65 74 20 6f 72 20   used to set or 
9530: 71 75 65 72 79 20 74 68 65 0a 2a 2a 20 70 65 72  query the.** per
9540: 73 69 73 74 65 6e 74 20 22 70 6f 77 65 72 73 61  sistent "powersa
9550: 66 65 2d 6f 76 65 72 77 72 69 74 65 22 20 6f 72  fe-overwrite" or
9560: 20 22 50 53 4f 57 22 20 73 65 74 74 69 6e 67 2e   "PSOW" setting.
9570: 20 20 54 68 65 20 50 53 4f 57 20 73 65 74 74 69    The PSOW setti
9580: 6e 67 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 65 73  ng.** determines
9590: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 49 4f 43   the [SQLITE_IOC
95a0: 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45  AP_POWERSAFE_OVE
95b0: 52 57 52 49 54 45 5d 20 62 69 74 20 6f 66 20 74  RWRITE] bit of t
95c0: 68 65 0a 2a 2a 20 78 44 65 76 69 63 65 43 68 61  he.** xDeviceCha
95d0: 72 61 63 74 65 72 69 73 74 69 63 73 20 6d 65 74  racteristics met
95e0: 68 6f 64 73 2e 20 54 68 65 20 66 6f 75 72 74 68  hods. The fourth
95f0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
9600: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
9610: 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68  ontrol()] for th
9620: 69 73 20 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64  is opcode should
9630: 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   be a pointer to
9640: 20 61 6e 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20   an integer..** 
9650: 54 68 61 74 20 69 6e 74 65 67 65 72 20 69 73 20  That integer is 
9660: 30 20 74 6f 20 64 69 73 61 62 6c 65 20 7a 65 72  0 to disable zer
9670: 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 65 20 6f 72  o-damage mode or
9680: 20 31 20 74 6f 20 65 6e 61 62 6c 65 20 7a 65 72   1 to enable zer
9690: 6f 2d 64 61 6d 61 67 65 0a 2a 2a 20 6d 6f 64 65  o-damage.** mode
96a0: 2e 20 20 49 66 20 74 68 65 20 69 6e 74 65 67 65  .  If the intege
96b0: 72 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 69 74  r is -1, then it
96c0: 20 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20   is overwritten 
96d0: 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74  with the current
96e0: 0a 2a 2a 20 7a 65 72 6f 2d 64 61 6d 61 67 65 20  .** zero-damage 
96f0: 6d 6f 64 65 20 73 65 74 74 69 6e 67 2e 0a 2a 2a  mode setting..**
9700: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
9710: 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45  _FCNTL_OVERWRITE
9720: 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  ]].** ^The [SQLI
9730: 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49  TE_FCNTL_OVERWRI
9740: 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 69 6e  TE] opcode is in
9750: 76 6f 6b 65 64 20 62 79 20 53 51 4c 69 74 65 20  voked by SQLite 
9760: 61 66 74 65 72 20 6f 70 65 6e 69 6e 67 0a 2a 2a  after opening.**
9770: 20 61 20 77 72 69 74 65 20 74 72 61 6e 73 61 63   a write transac
9780: 74 69 6f 6e 20 74 6f 20 69 6e 64 69 63 61 74 65  tion to indicate
9790: 20 74 68 61 74 2c 20 75 6e 6c 65 73 73 20 69 74   that, unless it
97a0: 20 69 73 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20   is rolled back 
97b0: 66 6f 72 20 73 6f 6d 65 0a 2a 2a 20 72 65 61 73  for some.** reas
97c0: 6f 6e 2c 20 74 68 65 20 65 6e 74 69 72 65 20 64  on, the entire d
97d0: 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 69 6c  atabase file wil
97e0: 6c 20 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e  l be overwritten
97f0: 20 62 79 20 74 68 65 20 63 75 72 72 65 6e 74 20   by the current 
9800: 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e  .** transaction.
9810: 20 54 68 69 73 20 69 73 20 75 73 65 64 20 62 79   This is used by
9820: 20 56 41 43 55 55 4d 20 6f 70 65 72 61 74 69 6f   VACUUM operatio
9830: 6e 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ns..**.** <li>[[
9840: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53  SQLITE_FCNTL_VFS
9850: 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b  NAME]].** ^The [
9860: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53  SQLITE_FCNTL_VFS
9870: 4e 41 4d 45 5d 20 6f 70 63 6f 64 65 20 63 61 6e  NAME] opcode can
9880: 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61   be used to obta
9890: 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 0a  in the names of.
98a0: 2a 2a 20 61 6c 6c 20 5b 56 46 53 65 73 5d 20 69  ** all [VFSes] i
98b0: 6e 20 74 68 65 20 56 46 53 20 73 74 61 63 6b 2e  n the VFS stack.
98c0: 20 20 54 68 65 20 6e 61 6d 65 73 20 61 72 65 20    The names are 
98d0: 6f 66 20 61 6c 6c 20 56 46 53 20 73 68 69 6d 73  of all VFS shims
98e0: 20 61 6e 64 20 74 68 65 0a 2a 2a 20 66 69 6e 61   and the.** fina
98f0: 6c 20 62 6f 74 74 6f 6d 2d 6c 65 76 65 6c 20 56  l bottom-level V
9900: 46 53 20 61 72 65 20 77 72 69 74 74 65 6e 20 69  FS are written i
9910: 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69  nto memory obtai
9920: 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71  ned from .** [sq
9930: 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
9940: 61 6e 64 20 74 68 65 20 72 65 73 75 6c 74 20 69  and the result i
9950: 73 20 73 74 6f 72 65 64 20 69 6e 20 74 68 65 20  s stored in the 
9960: 63 68 61 72 2a 20 76 61 72 69 61 62 6c 65 0a 2a  char* variable.*
9970: 2a 20 74 68 61 74 20 74 68 65 20 66 6f 75 72 74  * that the fourt
9980: 68 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 5b  h parameter of [
9990: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
99a0: 74 72 6f 6c 28 29 5d 20 70 6f 69 6e 74 73 20 74  trol()] points t
99b0: 6f 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 65 72  o..** The caller
99c0: 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20   is responsible 
99d0: 66 6f 72 20 66 72 65 65 69 6e 67 20 74 68 65 20  for freeing the 
99e0: 6d 65 6d 6f 72 79 20 77 68 65 6e 20 64 6f 6e 65  memory when done
99f0: 2e 20 20 41 73 20 77 69 74 68 0a 2a 2a 20 61 6c  .  As with.** al
9a00: 6c 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 61  l file-control a
9a10: 63 74 69 6f 6e 73 2c 20 74 68 65 72 65 20 69 73  ctions, there is
9a20: 20 6e 6f 20 67 75 61 72 61 6e 74 65 65 20 74 68   no guarantee th
9a30: 61 74 20 74 68 69 73 20 77 69 6c 6c 20 61 63 74  at this will act
9a40: 75 61 6c 6c 79 0a 2a 2a 20 64 6f 20 61 6e 79 74  ually.** do anyt
9a50: 68 69 6e 67 2e 20 20 43 61 6c 6c 65 72 73 20 73  hing.  Callers s
9a60: 68 6f 75 6c 64 20 69 6e 69 74 69 61 6c 69 7a 65  hould initialize
9a70: 20 74 68 65 20 63 68 61 72 2a 20 76 61 72 69 61   the char* varia
9a80: 62 6c 65 20 74 6f 20 61 20 4e 55 4c 4c 0a 2a 2a  ble to a NULL.**
9a90: 20 70 6f 69 6e 74 65 72 20 69 6e 20 63 61 73 65   pointer in case
9aa0: 20 74 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72   this file-contr
9ab0: 6f 6c 20 69 73 20 6e 6f 74 20 69 6d 70 6c 65 6d  ol is not implem
9ac0: 65 6e 74 65 64 2e 20 20 54 68 69 73 20 66 69 6c  ented.  This fil
9ad0: 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 69 73 20  e-control.** is 
9ae0: 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 64 69 61  intended for dia
9af0: 67 6e 6f 73 74 69 63 20 75 73 65 20 6f 6e 6c 79  gnostic use only
9b00: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
9b10: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d  LITE_FCNTL_PRAGM
9b20: 41 5d 5d 0a 2a 2a 20 5e 57 68 65 6e 65 76 65 72  A]].** ^Whenever
9b30: 20 61 20 5b 50 52 41 47 4d 41 5d 20 73 74 61 74   a [PRAGMA] stat
9b40: 65 6d 65 6e 74 20 69 73 20 70 61 72 73 65 64 2c  ement is parsed,
9b50: 20 61 6e 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54   an [SQLITE_FCNT
9b60: 4c 5f 50 52 41 47 4d 41 5d 20 0a 2a 2a 20 66 69  L_PRAGMA] .** fi
9b70: 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 73 65  le control is se
9b80: 6e 74 20 74 6f 20 74 68 65 20 6f 70 65 6e 20 5b  nt to the open [
9b90: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62  sqlite3_file] ob
9ba0: 6a 65 63 74 20 63 6f 72 72 65 73 70 6f 6e 64 69  ject correspondi
9bb0: 6e 67 0a 2a 2a 20 74 6f 20 74 68 65 20 64 61 74  ng.** to the dat
9bc0: 61 62 61 73 65 20 66 69 6c 65 20 74 6f 20 77 68  abase file to wh
9bd0: 69 63 68 20 74 68 65 20 70 72 61 67 6d 61 20 73  ich the pragma s
9be0: 74 61 74 65 6d 65 6e 74 20 72 65 66 65 72 73 2e  tatement refers.
9bf0: 20 5e 54 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a   ^The argument.*
9c00: 2a 20 74 6f 20 74 68 65 20 5b 53 51 4c 49 54 45  * to the [SQLITE
9c10: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66  _FCNTL_PRAGMA] f
9c20: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 61  ile control is a
9c30: 6e 20 61 72 72 61 79 20 6f 66 0a 2a 2a 20 70 6f  n array of.** po
9c40: 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67  inters to string
9c50: 73 20 28 63 68 61 72 2a 2a 29 20 69 6e 20 77 68  s (char**) in wh
9c60: 69 63 68 20 74 68 65 20 73 65 63 6f 6e 64 20 65  ich the second e
9c70: 6c 65 6d 65 6e 74 20 6f 66 20 74 68 65 20 61 72  lement of the ar
9c80: 72 61 79 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61  ray.** is the na
9c90: 6d 65 20 6f 66 20 74 68 65 20 70 72 61 67 6d 61  me of the pragma
9ca0: 20 61 6e 64 20 74 68 65 20 74 68 69 72 64 20 65   and the third e
9cb0: 6c 65 6d 65 6e 74 20 69 73 20 74 68 65 20 61 72  lement is the ar
9cc0: 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 0a 2a 2a  gument to the.**
9cd0: 20 70 72 61 67 6d 61 20 6f 72 20 4e 55 4c 4c 20   pragma or NULL 
9ce0: 69 66 20 74 68 65 20 70 72 61 67 6d 61 20 68 61  if the pragma ha
9cf0: 73 20 6e 6f 20 61 72 67 75 6d 65 6e 74 2e 20 20  s no argument.  
9d00: 5e 54 68 65 20 68 61 6e 64 6c 65 72 20 66 6f 72  ^The handler for
9d10: 20 61 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46   an.** [SQLITE_F
9d20: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c  CNTL_PRAGMA] fil
9d30: 65 20 63 6f 6e 74 72 6f 6c 20 63 61 6e 20 6f 70  e control can op
9d40: 74 69 6f 6e 61 6c 6c 79 20 6d 61 6b 65 20 74 68  tionally make th
9d50: 65 20 66 69 72 73 74 20 65 6c 65 6d 65 6e 74 0a  e first element.
9d60: 2a 2a 20 6f 66 20 74 68 65 20 63 68 61 72 2a 2a  ** of the char**
9d70: 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 20   argument point 
9d80: 74 6f 20 61 20 73 74 72 69 6e 67 20 6f 62 74 61  to a string obta
9d90: 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  ined from [sqlit
9da0: 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d 0a 2a 2a  e3_mprintf()].**
9db0: 20 6f 72 20 74 68 65 20 65 71 75 69 76 61 6c 65   or the equivale
9dc0: 6e 74 20 61 6e 64 20 74 68 61 74 20 73 74 72 69  nt and that stri
9dd0: 6e 67 20 77 69 6c 6c 20 62 65 63 6f 6d 65 20 74  ng will become t
9de0: 68 65 20 72 65 73 75 6c 74 20 6f 66 20 74 68 65  he result of the
9df0: 20 70 72 61 67 6d 61 20 6f 72 0a 2a 2a 20 74 68   pragma or.** th
9e00: 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  e error message 
9e10: 69 66 20 74 68 65 20 70 72 61 67 6d 61 20 66 61  if the pragma fa
9e20: 69 6c 73 2e 20 5e 49 66 20 74 68 65 0a 2a 2a 20  ils. ^If the.** 
9e30: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52  [SQLITE_FCNTL_PR
9e40: 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72  AGMA] file contr
9e50: 6f 6c 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  ol returns [SQLI
9e60: 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74 68  TE_NOTFOUND], th
9e70: 65 6e 20 6e 6f 72 6d 61 6c 20 0a 2a 2a 20 5b 50  en normal .** [P
9e80: 52 41 47 4d 41 5d 20 70 72 6f 63 65 73 73 69 6e  RAGMA] processin
9e90: 67 20 63 6f 6e 74 69 6e 75 65 73 2e 20 20 5e 49  g continues.  ^I
9ea0: 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  f the [SQLITE_FC
9eb0: 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20 66  NTL_PRAGMA].** f
9ec0: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75  ile control retu
9ed0: 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c  rns [SQLITE_OK],
9ee0: 20 74 68 65 6e 20 74 68 65 20 70 61 72 73 65 72   then the parser
9ef0: 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68   assumes that th
9f00: 65 0a 2a 2a 20 56 46 53 20 68 61 73 20 68 61 6e  e.** VFS has han
9f10: 64 6c 65 64 20 74 68 65 20 50 52 41 47 4d 41 20  dled the PRAGMA 
9f20: 69 74 73 65 6c 66 20 61 6e 64 20 74 68 65 20 70  itself and the p
9f30: 61 72 73 65 72 20 67 65 6e 65 72 61 74 65 73 20  arser generates 
9f40: 61 20 6e 6f 2d 6f 70 0a 2a 2a 20 70 72 65 70 61  a no-op.** prepa
9f50: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  red statement.  
9f60: 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ^If the [SQLITE_
9f70: 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69  FCNTL_PRAGMA] fi
9f80: 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72  le control retur
9f90: 6e 73 0a 2a 2a 20 61 6e 79 20 72 65 73 75 6c 74  ns.** any result
9fa0: 20 63 6f 64 65 20 6f 74 68 65 72 20 74 68 61 6e   code other than
9fb0: 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20   [SQLITE_OK] or 
9fc0: 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44  [SQLITE_NOTFOUND
9fd0: 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a 2a 2a  ], that means.**
9fe0: 20 74 68 61 74 20 74 68 65 20 56 46 53 20 65 6e   that the VFS en
9ff0: 63 6f 75 6e 74 65 72 65 64 20 61 6e 20 65 72 72  countered an err
a000: 6f 72 20 77 68 69 6c 65 20 68 61 6e 64 6c 69 6e  or while handlin
a010: 67 20 74 68 65 20 5b 50 52 41 47 4d 41 5d 20 61  g the [PRAGMA] a
a020: 6e 64 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c  nd the.** compil
a030: 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 50 52 41  ation of the PRA
a040: 47 4d 41 20 66 61 69 6c 73 20 77 69 74 68 20 61  GMA fails with a
a050: 6e 20 65 72 72 6f 72 2e 20 20 5e 54 68 65 20 5b  n error.  ^The [
a060: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41  SQLITE_FCNTL_PRA
a070: 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e  GMA].** file con
a080: 74 72 6f 6c 20 6f 63 63 75 72 73 20 61 74 20 74  trol occurs at t
a090: 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20  he beginning of 
a0a0: 70 72 61 67 6d 61 20 73 74 61 74 65 6d 65 6e 74  pragma statement
a0b0: 20 61 6e 61 6c 79 73 69 73 20 61 6e 64 20 73 6f   analysis and so
a0c0: 0a 2a 2a 20 69 74 20 69 73 20 61 62 6c 65 20 74  .** it is able t
a0d0: 6f 20 6f 76 65 72 72 69 64 65 20 62 75 69 6c 74  o override built
a0e0: 2d 69 6e 20 5b 50 52 41 47 4d 41 5d 20 73 74 61  -in [PRAGMA] sta
a0f0: 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 3c 2f 75 6c  tements..** </ul
a100: 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  >.*/.#define SQL
a110: 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54  ITE_FCNTL_LOCKST
a120: 41 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20  ATE             
a130: 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    1.#define SQLI
a140: 54 45 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59  TE_GET_LOCKPROXY
a150: 46 49 4c 45 20 20 20 20 20 20 20 20 20 20 20 20  FILE            
a160: 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   2.#define SQLIT
a170: 45 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46  E_SET_LOCKPROXYF
a180: 49 4c 45 20 20 20 20 20 20 20 20 20 20 20 20 20  ILE             
a190: 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  3.#define SQLITE
a1a0: 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20 20 20  _LAST_ERRNO     
a1b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 34                 4
a1c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
a1d0: 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 20  FCNTL_SIZE_HINT 
a1e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 35 0a                5.
a1f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
a200: 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 20  CNTL_CHUNK_SIZE 
a210: 20 20 20 20 20 20 20 20 20 20 20 20 20 36 0a 23               6.#
a220: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
a230: 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52  NTL_FILE_POINTER
a240: 20 20 20 20 20 20 20 20 20 20 20 20 37 0a 23 64              7.#d
a250: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
a260: 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 20  TL_SYNC_OMITTED 
a270: 20 20 20 20 20 20 20 20 20 20 20 38 0a 23 64 65             8.#de
a280: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
a290: 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59  L_WIN32_AV_RETRY
a2a0: 20 20 20 20 20 20 20 20 20 20 39 0a 23 64 65 66            9.#def
a2b0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
a2c0: 5f 50 45 52 53 49 53 54 5f 57 41 4c 20 20 20 20  _PERSIST_WAL    
a2d0: 20 20 20 20 20 20 20 20 31 30 0a 23 64 65 66 69          10.#defi
a2e0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
a2f0: 4f 56 45 52 57 52 49 54 45 20 20 20 20 20 20 20  OVERWRITE       
a300: 20 20 20 20 20 20 20 31 31 0a 23 64 65 66 69 6e         11.#defin
a310: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56  e SQLITE_FCNTL_V
a320: 46 53 4e 41 4d 45 20 20 20 20 20 20 20 20 20 20  FSNAME          
a330: 20 20 20 20 20 20 31 32 0a 23 64 65 66 69 6e 65        12.#define
a340: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f   SQLITE_FCNTL_PO
a350: 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54  WERSAFE_OVERWRIT
a360: 45 20 20 20 20 31 33 0a 23 64 65 66 69 6e 65 20  E    13.#define 
a370: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41  SQLITE_FCNTL_PRA
a380: 47 4d 41 20 20 20 20 20 20 20 20 20 20 20 20 20  GMA             
a390: 20 20 20 20 31 34 0a 0a 2f 2a 0a 2a 2a 20 43 41      14../*.** CA
a3a0: 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20 48 61  PI3REF: Mutex Ha
a3b0: 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d  ndle.**.** The m
a3c0: 75 74 65 78 20 6d 6f 64 75 6c 65 20 77 69 74 68  utex module with
a3d0: 69 6e 20 53 51 4c 69 74 65 20 64 65 66 69 6e 65  in SQLite define
a3e0: 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  s [sqlite3_mutex
a3f0: 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a 20 61 62  ] to be an.** ab
a400: 73 74 72 61 63 74 20 74 79 70 65 20 66 6f 72 20  stract type for 
a410: 61 20 6d 75 74 65 78 20 6f 62 6a 65 63 74 2e 20  a mutex object. 
a420: 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   The SQLite core
a430: 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a 2a 20   never looks.** 
a440: 61 74 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20  at the internal 
a450: 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 6f  representation o
a460: 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 6d 75  f an [sqlite3_mu
a470: 74 65 78 5d 2e 20 20 49 74 20 6f 6e 6c 79 0a 2a  tex].  It only.*
a480: 2a 20 64 65 61 6c 73 20 77 69 74 68 20 70 6f 69  * deals with poi
a490: 6e 74 65 72 73 20 74 6f 20 74 68 65 20 5b 73 71  nters to the [sq
a4a0: 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 6f 62 6a  lite3_mutex] obj
a4b0: 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74 65 78  ect..**.** Mutex
a4c0: 65 73 20 61 72 65 20 63 72 65 61 74 65 64 20 75  es are created u
a4d0: 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75  sing [sqlite3_mu
a4e0: 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f  tex_alloc()]..*/
a4f0: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
a500: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 73 71  sqlite3_mutex sq
a510: 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a 0a 2f 2a  lite3_mutex;../*
a520: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53  .** CAPI3REF: OS
a530: 20 49 6e 74 65 72 66 61 63 65 20 4f 62 6a 65 63   Interface Objec
a540: 74 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61  t.**.** An insta
a550: 6e 63 65 20 6f 66 20 74 68 65 20 73 71 6c 69 74  nce of the sqlit
a560: 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 64 65  e3_vfs object de
a570: 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66  fines the interf
a580: 61 63 65 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74  ace between.** t
a590: 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 61  he SQLite core a
a5a0: 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e  nd the underlyin
a5b0: 67 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  g operating syst
a5c0: 65 6d 2e 20 20 54 68 65 20 22 76 66 73 22 0a 2a  em.  The "vfs".*
a5d0: 2a 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66  * in the name of
a5e0: 20 74 68 65 20 6f 62 6a 65 63 74 20 73 74 61 6e   the object stan
a5f0: 64 73 20 66 6f 72 20 22 76 69 72 74 75 61 6c 20  ds for "virtual 
a600: 66 69 6c 65 20 73 79 73 74 65 6d 22 2e 20 20 53  file system".  S
a610: 65 65 0a 2a 2a 20 74 68 65 20 5b 56 46 53 20 7c  ee.** the [VFS |
a620: 20 56 46 53 20 64 6f 63 75 6d 65 6e 74 61 74 69   VFS documentati
a630: 6f 6e 5d 20 66 6f 72 20 66 75 72 74 68 65 72 20  on] for further 
a640: 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a  information..**.
a650: 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 6f 66 20  ** The value of 
a660: 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66 69 65  the iVersion fie
a670: 6c 64 20 69 73 20 69 6e 69 74 69 61 6c 6c 79 20  ld is initially 
a680: 31 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72  1 but may be lar
a690: 67 65 72 20 69 6e 0a 2a 2a 20 66 75 74 75 72 65  ger in.** future
a6a0: 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
a6b0: 69 74 65 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c  ite.  Additional
a6c0: 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61   fields may be a
a6d0: 70 70 65 6e 64 65 64 20 74 6f 20 74 68 69 73 0a  ppended to this.
a6e0: 2a 2a 20 6f 62 6a 65 63 74 20 77 68 65 6e 20 74  ** object when t
a6f0: 68 65 20 69 56 65 72 73 69 6f 6e 20 76 61 6c 75  he iVersion valu
a700: 65 20 69 73 20 69 6e 63 72 65 61 73 65 64 2e 20  e is increased. 
a710: 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 73   Note that the s
a720: 74 72 75 63 74 75 72 65 0a 2a 2a 20 6f 66 20 74  tructure.** of t
a730: 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f  he sqlite3_vfs o
a740: 62 6a 65 63 74 20 63 68 61 6e 67 65 73 20 69 6e  bject changes in
a750: 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e   the transaction
a760: 20 62 65 74 77 65 65 6e 0a 2a 2a 20 53 51 4c 69   between.** SQLi
a770: 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 39  te version 3.5.9
a780: 20 61 6e 64 20 33 2e 36 2e 30 20 61 6e 64 20 79   and 3.6.0 and y
a790: 65 74 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20  et the iVersion 
a7a0: 66 69 65 6c 64 20 77 61 73 20 6e 6f 74 0a 2a 2a  field was not.**
a7b0: 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a 2a 2a   modified..**.**
a7c0: 20 54 68 65 20 73 7a 4f 73 46 69 6c 65 20 66 69   The szOsFile fi
a7d0: 65 6c 64 20 69 73 20 74 68 65 20 73 69 7a 65 20  eld is the size 
a7e0: 6f 66 20 74 68 65 20 73 75 62 63 6c 61 73 73 65  of the subclasse
a7f0: 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  d [sqlite3_file]
a800: 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 75 73  .** structure us
a810: 65 64 20 62 79 20 74 68 69 73 20 56 46 53 2e 20  ed by this VFS. 
a820: 20 6d 78 50 61 74 68 6e 61 6d 65 20 69 73 20 74   mxPathname is t
a830: 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  he maximum lengt
a840: 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74 68 6e 61  h of.** a pathna
a850: 6d 65 20 69 6e 20 74 68 69 73 20 56 46 53 2e 0a  me in this VFS..
a860: 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72 65 64  **.** Registered
a870: 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a   sqlite3_vfs obj
a880: 65 63 74 73 20 61 72 65 20 6b 65 70 74 20 6f 6e  ects are kept on
a890: 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73 74 20 66   a linked list f
a8a0: 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74 68 65 20  ormed by.** the 
a8b0: 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 20 20  pNext pointer.  
a8c0: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  The [sqlite3_vfs
a8d0: 5f 72 65 67 69 73 74 65 72 28 29 5d 0a 2a 2a 20  _register()].** 
a8e0: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  and [sqlite3_vfs
a8f0: 5f 75 6e 72 65 67 69 73 74 65 72 28 29 5d 20 69  _unregister()] i
a900: 6e 74 65 72 66 61 63 65 73 20 6d 61 6e 61 67 65  nterfaces manage
a910: 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a 20 69 6e   this list.** in
a920: 20 61 20 74 68 72 65 61 64 2d 73 61 66 65 20 77   a thread-safe w
a930: 61 79 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65  ay.  The [sqlite
a940: 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d 20 69 6e  3_vfs_find()] in
a950: 74 65 72 66 61 63 65 0a 2a 2a 20 73 65 61 72 63  terface.** searc
a960: 68 65 73 20 74 68 65 20 6c 69 73 74 2e 20 20 4e  hes the list.  N
a970: 65 69 74 68 65 72 20 74 68 65 20 61 70 70 6c 69  either the appli
a980: 63 61 74 69 6f 6e 20 63 6f 64 65 20 6e 6f 72 20  cation code nor 
a990: 74 68 65 20 56 46 53 0a 2a 2a 20 69 6d 70 6c 65  the VFS.** imple
a9a0: 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64  mentation should
a9b0: 20 75 73 65 20 74 68 65 20 70 4e 65 78 74 20 70   use the pNext p
a9c0: 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  ointer..**.** Th
a9d0: 65 20 70 4e 65 78 74 20 66 69 65 6c 64 20 69 73  e pNext field is
a9e0: 20 74 68 65 20 6f 6e 6c 79 20 66 69 65 6c 64 20   the only field 
a9f0: 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76  in the sqlite3_v
aa00: 66 73 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20  fs.** structure 
aa10: 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c  that SQLite will
aa20: 20 65 76 65 72 20 6d 6f 64 69 66 79 2e 20 20 53   ever modify.  S
aa30: 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c 79 20  QLite will only 
aa40: 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20 6d 6f 64  access.** or mod
aa50: 69 66 79 20 74 68 69 73 20 66 69 65 6c 64 20 77  ify this field w
aa60: 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20 61 20 70  hile holding a p
aa70: 61 72 74 69 63 75 6c 61 72 20 73 74 61 74 69 63  articular static
aa80: 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68 65 20 61   mutex..** The a
aa90: 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
aaa0: 64 20 6e 65 76 65 72 20 6d 6f 64 69 66 79 20 61  d never modify a
aab0: 6e 79 74 68 69 6e 67 20 77 69 74 68 69 6e 20 74  nything within t
aac0: 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a  he sqlite3_vfs.*
aad0: 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65 20 74 68  * object once th
aae0: 65 20 6f 62 6a 65 63 74 20 68 61 73 20 62 65 65  e object has bee
aaf0: 6e 20 72 65 67 69 73 74 65 72 65 64 2e 0a 2a 2a  n registered..**
ab00: 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65 20 66 69  .** The zName fi
ab10: 65 6c 64 20 68 6f 6c 64 73 20 74 68 65 20 6e 61  eld holds the na
ab20: 6d 65 20 6f 66 20 74 68 65 20 56 46 53 20 6d 6f  me of the VFS mo
ab30: 64 75 6c 65 2e 20 20 54 68 65 20 6e 61 6d 65 20  dule.  The name 
ab40: 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e 69 71 75  must.** be uniqu
ab50: 65 20 61 63 72 6f 73 73 20 61 6c 6c 20 56 46 53  e across all VFS
ab60: 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20   modules..**.** 
ab70: 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f  [[sqlite3_vfs.xO
ab80: 70 65 6e 5d 5d 0a 2a 2a 20 5e 53 51 4c 69 74 65  pen]].** ^SQLite
ab90: 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74   guarantees that
aba0: 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70   the zFilename p
abb0: 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65  arameter to xOpe
abc0: 6e 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20 61  n.** is either a
abd0: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72   NULL pointer or
abe0: 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64   string obtained
abf0: 0a 2a 2a 20 66 72 6f 6d 20 78 46 75 6c 6c 50 61  .** from xFullPa
ac00: 74 68 6e 61 6d 65 28 29 20 77 69 74 68 20 61 6e  thname() with an
ac10: 20 6f 70 74 69 6f 6e 61 6c 20 73 75 66 66 69 78   optional suffix
ac20: 20 61 64 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 61   added..** ^If a
ac30: 20 73 75 66 66 69 78 20 69 73 20 61 64 64 65 64   suffix is added
ac40: 20 74 6f 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d   to the zFilenam
ac50: 65 20 70 61 72 61 6d 65 74 65 72 2c 20 69 74 20  e parameter, it 
ac60: 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 73 69 73 74 20  will.** consist 
ac70: 6f 66 20 61 20 73 69 6e 67 6c 65 20 22 2d 22 20  of a single "-" 
ac80: 63 68 61 72 61 63 74 65 72 20 66 6f 6c 6c 6f 77  character follow
ac90: 65 64 20 62 79 20 6e 6f 20 6d 6f 72 65 20 74 68  ed by no more th
aca0: 61 6e 0a 2a 2a 20 31 31 20 61 6c 70 68 61 6e 75  an.** 11 alphanu
acb0: 6d 65 72 69 63 20 61 6e 64 2f 6f 72 20 22 2d 22  meric and/or "-"
acc0: 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 20   characters..** 
acd0: 5e 53 51 4c 69 74 65 20 66 75 72 74 68 65 72 20  ^SQLite further 
ace0: 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 0a  guarantees that.
acf0: 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 77 69  ** the string wi
ad00: 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 6e 64 20  ll be valid and 
ad10: 75 6e 63 68 61 6e 67 65 64 20 75 6e 74 69 6c 20  unchanged until 
ad20: 78 43 6c 6f 73 65 28 29 20 69 73 0a 2a 2a 20 63  xClose() is.** c
ad30: 61 6c 6c 65 64 2e 20 42 65 63 61 75 73 65 20 6f  alled. Because o
ad40: 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 73  f the previous s
ad50: 65 6e 74 65 6e 63 65 2c 0a 2a 2a 20 74 68 65 20  entence,.** the 
ad60: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 63  [sqlite3_file] c
ad70: 61 6e 20 73 61 66 65 6c 79 20 73 74 6f 72 65 20  an safely store 
ad80: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
ad90: 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 66 20  .** filename if 
ada0: 69 74 20 6e 65 65 64 73 20 74 6f 20 72 65 6d 65  it needs to reme
adb0: 6d 62 65 72 20 74 68 65 20 66 69 6c 65 6e 61 6d  mber the filenam
adc0: 65 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f  e for some reaso
add0: 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 20 7a 46 69  n..** If the zFi
ade0: 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72  lename parameter
adf0: 20 74 6f 20 78 4f 70 65 6e 20 69 73 20 61 20 4e   to xOpen is a N
ae00: 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e  ULL pointer then
ae10: 20 78 4f 70 65 6e 0a 2a 2a 20 6d 75 73 74 20 69   xOpen.** must i
ae20: 6e 76 65 6e 74 20 69 74 73 20 6f 77 6e 20 74 65  nvent its own te
ae30: 6d 70 6f 72 61 72 79 20 6e 61 6d 65 20 66 6f 72  mporary name for
ae40: 20 74 68 65 20 66 69 6c 65 2e 20 20 5e 57 68 65   the file.  ^Whe
ae50: 6e 65 76 65 72 20 74 68 65 20 0a 2a 2a 20 78 46  never the .** xF
ae60: 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65  ilename paramete
ae70: 72 20 69 73 20 4e 55 4c 4c 20 69 74 20 77 69 6c  r is NULL it wil
ae80: 6c 20 61 6c 73 6f 20 62 65 20 74 68 65 20 63 61  l also be the ca
ae90: 73 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 66  se that the.** f
aea0: 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 77  lags parameter w
aeb0: 69 6c 6c 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c  ill include [SQL
aec0: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f  ITE_OPEN_DELETEO
aed0: 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a 20 54  NCLOSE]..**.** T
aee0: 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e  he flags argumen
aef0: 74 20 74 6f 20 78 4f 70 65 6e 28 29 20 69 6e 63  t to xOpen() inc
af00: 6c 75 64 65 73 20 61 6c 6c 20 62 69 74 73 20 73  ludes all bits s
af10: 65 74 20 69 6e 0a 2a 2a 20 74 68 65 20 66 6c 61  et in.** the fla
af20: 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b  gs argument to [
af30: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
af40: 29 5d 2e 20 20 4f 72 20 69 66 20 5b 73 71 6c 69  )].  Or if [sqli
af50: 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 6f  te3_open()].** o
af60: 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  r [sqlite3_open1
af70: 36 28 29 5d 20 69 73 20 75 73 65 64 2c 20 74 68  6()] is used, th
af80: 65 6e 20 66 6c 61 67 73 20 69 6e 63 6c 75 64 65  en flags include
af90: 73 20 61 74 20 6c 65 61 73 74 0a 2a 2a 20 5b 53  s at least.** [S
afa0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
afb0: 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f  RITE] | [SQLITE_
afc0: 4f 50 45 4e 5f 43 52 45 41 54 45 5d 2e 20 0a 2a  OPEN_CREATE]. .*
afd0: 2a 20 49 66 20 78 4f 70 65 6e 28 29 20 6f 70 65  * If xOpen() ope
afe0: 6e 73 20 61 20 66 69 6c 65 20 72 65 61 64 2d 6f  ns a file read-o
aff0: 6e 6c 79 20 74 68 65 6e 20 69 74 20 73 65 74 73  nly then it sets
b000: 20 2a 70 4f 75 74 46 6c 61 67 73 20 74 6f 0a 2a   *pOutFlags to.*
b010: 2a 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54  * include [SQLIT
b020: 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d  E_OPEN_READONLY]
b030: 2e 20 20 4f 74 68 65 72 20 62 69 74 73 20 69 6e  .  Other bits in
b040: 20 2a 70 4f 75 74 46 6c 61 67 73 20 6d 61 79 20   *pOutFlags may 
b050: 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28  be set..**.** ^(
b060: 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 73 6f  SQLite will also
b070: 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20   add one of the 
b080: 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20  following flags 
b090: 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 0a 2a  to the xOpen().*
b0a0: 2a 20 63 61 6c 6c 2c 20 64 65 70 65 6e 64 69 6e  * call, dependin
b0b0: 67 20 6f 6e 20 74 68 65 20 6f 62 6a 65 63 74 20  g on the object 
b0c0: 62 65 69 6e 67 20 6f 70 65 6e 65 64 3a 0a 2a 2a  being opened:.**
b0d0: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
b0e0: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d    [SQLITE_OPEN_M
b0f0: 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20  AIN_DB].** <li> 
b100: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41   [SQLITE_OPEN_MA
b110: 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c  IN_JOURNAL].** <
b120: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
b130: 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a 2a 20 3c 6c  N_TEMP_DB].** <l
b140: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
b150: 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a  _TEMP_JOURNAL].*
b160: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
b170: 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44  OPEN_TRANSIENT_D
b180: 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  B].** <li>  [SQL
b190: 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52  ITE_OPEN_SUBJOUR
b1a0: 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  NAL].** <li>  [S
b1b0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45  QLITE_OPEN_MASTE
b1c0: 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c  R_JOURNAL].** <l
b1d0: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
b1e0: 5f 57 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e  _WAL].** </ul>)^
b1f0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 6c 65 20  .**.** The file 
b200: 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  I/O implementati
b210: 6f 6e 20 63 61 6e 20 75 73 65 20 74 68 65 20 6f  on can use the o
b220: 62 6a 65 63 74 20 74 79 70 65 20 66 6c 61 67 73  bject type flags
b230: 20 74 6f 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68   to.** change th
b240: 65 20 77 61 79 20 69 74 20 64 65 61 6c 73 20 77  e way it deals w
b250: 69 74 68 20 66 69 6c 65 73 2e 20 20 46 6f 72 20  ith files.  For 
b260: 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c  example, an appl
b270: 69 63 61 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20  ication.** that 
b280: 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 61 62  does not care ab
b290: 6f 75 74 20 63 72 61 73 68 20 72 65 63 6f 76 65  out crash recove
b2a0: 72 79 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 6d  ry or rollback m
b2b0: 69 67 68 74 20 6d 61 6b 65 0a 2a 2a 20 74 68 65  ight make.** the
b2c0: 20 6f 70 65 6e 20 6f 66 20 61 20 6a 6f 75 72 6e   open of a journ
b2d0: 61 6c 20 66 69 6c 65 20 61 20 6e 6f 2d 6f 70 2e  al file a no-op.
b2e0: 20 20 57 72 69 74 65 73 20 74 6f 20 74 68 69 73    Writes to this
b2f0: 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 0a 2a   journal would.*
b300: 2a 20 61 6c 73 6f 20 62 65 20 6e 6f 2d 6f 70 73  * also be no-ops
b310: 2c 20 61 6e 64 20 61 6e 79 20 61 74 74 65 6d 70  , and any attemp
b320: 74 20 74 6f 20 72 65 61 64 20 74 68 65 20 6a 6f  t to read the jo
b330: 75 72 6e 61 6c 20 77 6f 75 6c 64 20 72 65 74 75  urnal would retu
b340: 72 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 45  rn.** SQLITE_IOE
b350: 52 52 2e 20 20 4f 72 20 74 68 65 20 69 6d 70 6c  RR.  Or the impl
b360: 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 67 68 74  ementation might
b370: 20 72 65 63 6f 67 6e 69 7a 65 20 74 68 61 74 20   recognize that 
b380: 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69  a database.** fi
b390: 6c 65 20 77 69 6c 6c 20 62 65 20 64 6f 69 6e 67  le will be doing
b3a0: 20 70 61 67 65 2d 61 6c 69 67 6e 65 64 20 73 65   page-aligned se
b3b0: 63 74 6f 72 20 72 65 61 64 73 20 61 6e 64 20 77  ctor reads and w
b3c0: 72 69 74 65 73 20 69 6e 20 61 20 72 61 6e 64 6f  rites in a rando
b3d0: 6d 0a 2a 2a 20 6f 72 64 65 72 20 61 6e 64 20 73  m.** order and s
b3e0: 65 74 20 75 70 20 69 74 73 20 49 2f 4f 20 73 75  et up its I/O su
b3f0: 62 73 79 73 74 65 6d 20 61 63 63 6f 72 64 69 6e  bsystem accordin
b400: 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  gly..**.** SQLit
b410: 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 61 64 64  e might also add
b420: 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c   one of the foll
b430: 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74  owing flags to t
b440: 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 3a  he xOpen method:
b450: 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
b460: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  li> [SQLITE_OPEN
b470: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a  _DELETEONCLOSE].
b480: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
b490: 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 0a  OPEN_EXCLUSIVE].
b4a0: 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54  ** </ul>.**.** T
b4b0: 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
b4c0: 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 20 66  DELETEONCLOSE] f
b4d0: 6c 61 67 20 6d 65 61 6e 73 20 74 68 65 20 66 69  lag means the fi
b4e0: 6c 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20  le should be.** 
b4f0: 64 65 6c 65 74 65 64 20 77 68 65 6e 20 69 74 20  deleted when it 
b500: 69 73 20 63 6c 6f 73 65 64 2e 20 20 5e 54 68 65  is closed.  ^The
b510: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45   [SQLITE_OPEN_DE
b520: 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20  LETEONCLOSE].** 
b530: 77 69 6c 6c 20 62 65 20 73 65 74 20 66 6f 72 20  will be set for 
b540: 54 45 4d 50 20 64 61 74 61 62 61 73 65 73 20 61  TEMP databases a
b550: 6e 64 20 74 68 65 69 72 20 6a 6f 75 72 6e 61 6c  nd their journal
b560: 73 2c 20 74 72 61 6e 73 69 65 6e 74 0a 2a 2a 20  s, transient.** 
b570: 64 61 74 61 62 61 73 65 73 2c 20 61 6e 64 20 73  databases, and s
b580: 75 62 6a 6f 75 72 6e 61 6c 73 2e 0a 2a 2a 0a 2a  ubjournals..**.*
b590: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f  * ^The [SQLITE_O
b5a0: 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 20 66  PEN_EXCLUSIVE] f
b5b0: 6c 61 67 20 69 73 20 61 6c 77 61 79 73 20 75 73  lag is always us
b5c0: 65 64 20 69 6e 20 63 6f 6e 6a 75 6e 63 74 69 6f  ed in conjunctio
b5d0: 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 53  n.** with the [S
b5e0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
b5f0: 45 5d 20 66 6c 61 67 2c 20 77 68 69 63 68 20 61  E] flag, which a
b600: 72 65 20 62 6f 74 68 20 64 69 72 65 63 74 6c 79  re both directly
b610: 0a 2a 2a 20 61 6e 61 6c 6f 67 6f 75 73 20 74 6f  .** analogous to
b620: 20 74 68 65 20 4f 5f 45 58 43 4c 20 61 6e 64 20   the O_EXCL and 
b630: 4f 5f 43 52 45 41 54 20 66 6c 61 67 73 20 6f 66  O_CREAT flags of
b640: 20 74 68 65 20 50 4f 53 49 58 20 6f 70 65 6e 28   the POSIX open(
b650: 29 0a 2a 2a 20 41 50 49 2e 20 20 54 68 65 20 53  ).** API.  The S
b660: 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55  QLITE_OPEN_EXCLU
b670: 53 49 56 45 20 66 6c 61 67 2c 20 77 68 65 6e 20  SIVE flag, when 
b680: 70 61 69 72 65 64 20 77 69 74 68 20 74 68 65 20  paired with the 
b690: 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  .** SQLITE_OPEN_
b6a0: 43 52 45 41 54 45 2c 20 69 73 20 75 73 65 64 20  CREATE, is used 
b6b0: 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74  to indicate that
b6c0: 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 61 6c 77   file should alw
b6d0: 61 79 73 0a 2a 2a 20 62 65 20 63 72 65 61 74 65  ays.** be create
b6e0: 64 2c 20 61 6e 64 20 74 68 61 74 20 69 74 20 69  d, and that it i
b6f0: 73 20 61 6e 20 65 72 72 6f 72 20 69 66 20 69 74  s an error if it
b700: 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 73 2e   already exists.
b710: 0a 2a 2a 20 49 74 20 69 73 20 3c 69 3e 6e 6f 74  .** It is <i>not
b720: 3c 2f 69 3e 20 75 73 65 64 20 74 6f 20 69 6e 64  </i> used to ind
b730: 69 63 61 74 65 20 74 68 65 20 66 69 6c 65 20 73  icate the file s
b740: 68 6f 75 6c 64 20 62 65 20 6f 70 65 6e 65 64 20  hould be opened 
b750: 0a 2a 2a 20 66 6f 72 20 65 78 63 6c 75 73 69 76  .** for exclusiv
b760: 65 20 61 63 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20  e access..**.** 
b770: 5e 41 74 20 6c 65 61 73 74 20 73 7a 4f 73 46 69  ^At least szOsFi
b780: 6c 65 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f  le bytes of memo
b790: 72 79 20 61 72 65 20 61 6c 6c 6f 63 61 74 65 64  ry are allocated
b7a0: 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 74 6f   by SQLite.** to
b7b0: 20 68 6f 6c 64 20 74 68 65 20 20 5b 73 71 6c 69   hold the  [sqli
b7c0: 74 65 33 5f 66 69 6c 65 5d 20 73 74 72 75 63 74  te3_file] struct
b7d0: 75 72 65 20 70 61 73 73 65 64 20 61 73 20 74 68  ure passed as th
b7e0: 65 20 74 68 69 72 64 0a 2a 2a 20 61 72 67 75 6d  e third.** argum
b7f0: 65 6e 74 20 74 6f 20 78 4f 70 65 6e 2e 20 20 54  ent to xOpen.  T
b800: 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20  he xOpen method 
b810: 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 74 6f  does not have to
b820: 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 74 68 65  .** allocate the
b830: 20 73 74 72 75 63 74 75 72 65 3b 20 69 74 20 73   structure; it s
b840: 68 6f 75 6c 64 20 6a 75 73 74 20 66 69 6c 6c 20  hould just fill 
b850: 69 74 20 69 6e 2e 20 20 4e 6f 74 65 20 74 68 61  it in.  Note tha
b860: 74 0a 2a 2a 20 74 68 65 20 78 4f 70 65 6e 20 6d  t.** the xOpen m
b870: 65 74 68 6f 64 20 6d 75 73 74 20 73 65 74 20 74  ethod must set t
b880: 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e  he sqlite3_file.
b890: 70 4d 65 74 68 6f 64 73 20 74 6f 20 65 69 74 68  pMethods to eith
b8a0: 65 72 0a 2a 2a 20 61 20 76 61 6c 69 64 20 5b 73  er.** a valid [s
b8b0: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
b8c0: 73 5d 20 6f 62 6a 65 63 74 20 6f 72 20 74 6f 20  s] object or to 
b8d0: 4e 55 4c 4c 2e 20 20 78 4f 70 65 6e 20 6d 75 73  NULL.  xOpen mus
b8e0: 74 20 64 6f 0a 2a 2a 20 74 68 69 73 20 65 76 65  t do.** this eve
b8f0: 6e 20 69 66 20 74 68 65 20 6f 70 65 6e 20 66 61  n if the open fa
b900: 69 6c 73 2e 20 20 53 51 4c 69 74 65 20 65 78 70  ils.  SQLite exp
b910: 65 63 74 73 20 74 68 61 74 20 74 68 65 20 73 71  ects that the sq
b920: 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68  lite3_file.pMeth
b930: 6f 64 73 0a 2a 2a 20 65 6c 65 6d 65 6e 74 20 77  ods.** element w
b940: 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 66 74  ill be valid aft
b950: 65 72 20 78 4f 70 65 6e 20 72 65 74 75 72 6e 73  er xOpen returns
b960: 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74   regardless of t
b970: 68 65 20 73 75 63 63 65 73 73 0a 2a 2a 20 6f 72  he success.** or
b980: 20 66 61 69 6c 75 72 65 20 6f 66 20 74 68 65 20   failure of the 
b990: 78 4f 70 65 6e 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a  xOpen call..**.*
b9a0: 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  * [[sqlite3_vfs.
b9b0: 78 41 63 63 65 73 73 5d 5d 0a 2a 2a 20 5e 54 68  xAccess]].** ^Th
b9c0: 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74  e flags argument
b9d0: 20 74 6f 20 78 41 63 63 65 73 73 28 29 20 6d 61   to xAccess() ma
b9e0: 79 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 43 43  y be [SQLITE_ACC
b9f0: 45 53 53 5f 45 58 49 53 54 53 5d 0a 2a 2a 20 74  ESS_EXISTS].** t
ba00: 6f 20 74 65 73 74 20 66 6f 72 20 74 68 65 20 65  o test for the e
ba10: 78 69 73 74 65 6e 63 65 20 6f 66 20 61 20 66 69  xistence of a fi
ba20: 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41  le, or [SQLITE_A
ba30: 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 5d  CCESS_READWRITE]
ba40: 20 74 6f 0a 2a 2a 20 74 65 73 74 20 77 68 65 74   to.** test whet
ba50: 68 65 72 20 61 20 66 69 6c 65 20 69 73 20 72 65  her a file is re
ba60: 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61  adable and writa
ba70: 62 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ble, or [SQLITE_
ba80: 41 43 43 45 53 53 5f 52 45 41 44 5d 0a 2a 2a 20  ACCESS_READ].** 
ba90: 74 6f 20 74 65 73 74 20 77 68 65 74 68 65 72 20  to test whether 
baa0: 61 20 66 69 6c 65 20 69 73 20 61 74 20 6c 65 61  a file is at lea
bab0: 73 74 20 72 65 61 64 61 62 6c 65 2e 20 20 20 54  st readable.   T
bac0: 68 65 20 66 69 6c 65 20 63 61 6e 20 62 65 20 61  he file can be a
bad0: 0a 2a 2a 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a  .** directory..*
bae0: 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c  *.** ^SQLite wil
baf0: 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f 63 61 74  l always allocat
bb00: 65 20 61 74 20 6c 65 61 73 74 20 6d 78 50 61 74  e at least mxPat
bb10: 68 6e 61 6d 65 2b 31 20 62 79 74 65 73 20 66 6f  hname+1 bytes fo
bb20: 72 20 74 68 65 0a 2a 2a 20 6f 75 74 70 75 74 20  r the.** output 
bb30: 62 75 66 66 65 72 20 78 46 75 6c 6c 50 61 74 68  buffer xFullPath
bb40: 6e 61 6d 65 2e 20 20 54 68 65 20 65 78 61 63 74  name.  The exact
bb50: 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6f 75 74   size of the out
bb60: 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69 73  put buffer.** is
bb70: 20 61 6c 73 6f 20 70 61 73 73 65 64 20 61 73 20   also passed as 
bb80: 61 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62  a parameter to b
bb90: 6f 74 68 20 20 6d 65 74 68 6f 64 73 2e 20 49 66  oth  methods. If
bba0: 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 66 66   the output buff
bbb0: 65 72 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c 61 72  er.** is not lar
bbc0: 67 65 20 65 6e 6f 75 67 68 2c 20 5b 53 51 4c 49  ge enough, [SQLI
bbd0: 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 73 68 6f  TE_CANTOPEN] sho
bbe0: 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e  uld be returned.
bbf0: 20 53 69 6e 63 65 20 74 68 69 73 20 69 73 0a 2a   Since this is.*
bc00: 2a 20 68 61 6e 64 6c 65 64 20 61 73 20 61 20 66  * handled as a f
bc10: 61 74 61 6c 20 65 72 72 6f 72 20 62 79 20 53 51  atal error by SQ
bc20: 4c 69 74 65 2c 20 76 66 73 20 69 6d 70 6c 65 6d  Lite, vfs implem
bc30: 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64  entations should
bc40: 20 65 6e 64 65 61 76 6f 72 0a 2a 2a 20 74 6f 20   endeavor.** to 
bc50: 70 72 65 76 65 6e 74 20 74 68 69 73 20 62 79 20  prevent this by 
bc60: 73 65 74 74 69 6e 67 20 6d 78 50 61 74 68 6e 61  setting mxPathna
bc70: 6d 65 20 74 6f 20 61 20 73 75 66 66 69 63 69 65  me to a sufficie
bc80: 6e 74 6c 79 20 6c 61 72 67 65 20 76 61 6c 75 65  ntly large value
bc90: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 61 6e  ..**.** The xRan
bca0: 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53 6c 65 65  domness(), xSlee
bcb0: 70 28 29 2c 20 78 43 75 72 72 65 6e 74 54 69 6d  p(), xCurrentTim
bcc0: 65 28 29 2c 20 61 6e 64 20 78 43 75 72 72 65 6e  e(), and xCurren
bcd0: 74 54 69 6d 65 49 6e 74 36 34 28 29 0a 2a 2a 20  tTimeInt64().** 
bce0: 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 6e  interfaces are n
bcf0: 6f 74 20 73 74 72 69 63 74 6c 79 20 61 20 70 61  ot strictly a pa
bd00: 72 74 20 6f 66 20 74 68 65 20 66 69 6c 65 73 79  rt of the filesy
bd10: 73 74 65 6d 2c 20 62 75 74 20 74 68 65 79 20 61  stem, but they a
bd20: 72 65 0a 2a 2a 20 69 6e 63 6c 75 64 65 64 20 69  re.** included i
bd30: 6e 20 74 68 65 20 56 46 53 20 73 74 72 75 63 74  n the VFS struct
bd40: 75 72 65 20 66 6f 72 20 63 6f 6d 70 6c 65 74 65  ure for complete
bd50: 6e 65 73 73 2e 0a 2a 2a 20 54 68 65 20 78 52 61  ness..** The xRa
bd60: 6e 64 6f 6d 6e 65 73 73 28 29 20 66 75 6e 63 74  ndomness() funct
bd70: 69 6f 6e 20 61 74 74 65 6d 70 74 73 20 74 6f 20  ion attempts to 
bd80: 72 65 74 75 72 6e 20 6e 42 79 74 65 73 20 62 79  return nBytes by
bd90: 74 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64 2d 71  tes.** of good-q
bda0: 75 61 6c 69 74 79 20 72 61 6e 64 6f 6d 6e 65 73  uality randomnes
bdb0: 73 20 69 6e 74 6f 20 7a 4f 75 74 2e 20 20 54 68  s into zOut.  Th
bdc0: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 69  e return value i
bdd0: 73 0a 2a 2a 20 74 68 65 20 61 63 74 75 61 6c 20  s.** the actual 
bde0: 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
bdf0: 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62  of randomness ob
be00: 74 61 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 78  tained..** The x
be10: 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 20 63  Sleep() method c
be20: 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c 69 6e  auses the callin
be30: 67 20 74 68 72 65 61 64 20 74 6f 20 73 6c 65 65  g thread to slee
be40: 70 20 66 6f 72 20 61 74 0a 2a 2a 20 6c 65 61 73  p for at.** leas
be50: 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  t the number of 
be60: 6d 69 63 72 6f 73 65 63 6f 6e 64 73 20 67 69 76  microseconds giv
be70: 65 6e 2e 20 20 5e 54 68 65 20 78 43 75 72 72 65  en.  ^The xCurre
be80: 6e 74 54 69 6d 65 28 29 0a 2a 2a 20 6d 65 74 68  ntTime().** meth
be90: 6f 64 20 72 65 74 75 72 6e 73 20 61 20 4a 75 6c  od returns a Jul
bea0: 69 61 6e 20 44 61 79 20 4e 75 6d 62 65 72 20 66  ian Day Number f
beb0: 6f 72 20 74 68 65 20 63 75 72 72 65 6e 74 20 64  or the current d
bec0: 61 74 65 20 61 6e 64 20 74 69 6d 65 20 61 73 0a  ate and time as.
bed0: 2a 2a 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f  ** a floating po
bee0: 69 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a 20 5e 54  int value..** ^T
bef0: 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49  he xCurrentTimeI
bf00: 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20 72 65  nt64() method re
bf10: 74 75 72 6e 73 2c 20 61 73 20 61 6e 20 69 6e 74  turns, as an int
bf20: 65 67 65 72 2c 20 74 68 65 20 4a 75 6c 69 61 6e  eger, the Julian
bf30: 0a 2a 2a 20 44 61 79 20 4e 75 6d 62 65 72 20 6d  .** Day Number m
bf40: 75 6c 74 69 70 6c 69 65 64 20 62 79 20 38 36 34  ultiplied by 864
bf50: 30 30 30 30 30 20 28 74 68 65 20 6e 75 6d 62 65  00000 (the numbe
bf60: 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  r of millisecond
bf70: 73 20 69 6e 20 0a 2a 2a 20 61 20 32 34 2d 68 6f  s in .** a 24-ho
bf80: 75 72 20 64 61 79 29 2e 20 20 0a 2a 2a 20 5e 53  ur day).  .** ^S
bf90: 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 74  QLite will use t
bfa0: 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49  he xCurrentTimeI
bfb0: 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20 74 6f  nt64() method to
bfc0: 20 67 65 74 20 74 68 65 20 63 75 72 72 65 6e 74   get the current
bfd0: 0a 2a 2a 20 64 61 74 65 20 61 6e 64 20 74 69 6d  .** date and tim
bfe0: 65 20 69 66 20 74 68 61 74 20 6d 65 74 68 6f 64  e if that method
bff0: 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 28 69   is available (i
c000: 66 20 69 56 65 72 73 69 6f 6e 20 69 73 20 32 20  f iVersion is 2 
c010: 6f 72 20 0a 2a 2a 20 67 72 65 61 74 65 72 20 61  or .** greater a
c020: 6e 64 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  nd the function 
c030: 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e  pointer is not N
c040: 55 4c 4c 29 20 61 6e 64 20 77 69 6c 6c 20 66 61  ULL) and will fa
c050: 6c 6c 20 62 61 63 6b 0a 2a 2a 20 74 6f 20 78 43  ll back.** to xC
c060: 75 72 72 65 6e 74 54 69 6d 65 28 29 20 69 66 20  urrentTime() if 
c070: 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36  xCurrentTimeInt6
c080: 34 28 29 20 69 73 20 75 6e 61 76 61 69 6c 61 62  4() is unavailab
c090: 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78  le..**.** ^The x
c0a0: 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 2c  SetSystemCall(),
c0b0: 20 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c 28   xGetSystemCall(
c0c0: 29 2c 20 61 6e 64 20 78 4e 65 73 74 53 79 73 74  ), and xNestSyst
c0d0: 65 6d 43 61 6c 6c 28 29 20 69 6e 74 65 72 66 61  emCall() interfa
c0e0: 63 65 73 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 75  ces.** are not u
c0f0: 73 65 64 20 62 79 20 74 68 65 20 53 51 4c 69 74  sed by the SQLit
c100: 65 20 63 6f 72 65 2e 20 20 54 68 65 73 65 20 6f  e core.  These o
c110: 70 74 69 6f 6e 61 6c 20 69 6e 74 65 72 66 61 63  ptional interfac
c120: 65 73 20 61 72 65 20 70 72 6f 76 69 64 65 64 0a  es are provided.
c130: 2a 2a 20 62 79 20 73 6f 6d 65 20 56 46 53 65 73  ** by some VFSes
c140: 20 74 6f 20 66 61 63 69 6c 69 74 61 74 65 20 74   to facilitate t
c150: 65 73 74 69 6e 67 20 6f 66 20 74 68 65 20 56 46  esting of the VF
c160: 53 20 63 6f 64 65 2e 20 42 79 20 6f 76 65 72 72  S code. By overr
c170: 69 64 69 6e 67 20 0a 2a 2a 20 73 79 73 74 65 6d  iding .** system
c180: 20 63 61 6c 6c 73 20 77 69 74 68 20 66 75 6e 63   calls with func
c190: 74 69 6f 6e 73 20 75 6e 64 65 72 20 69 74 73 20  tions under its 
c1a0: 63 6f 6e 74 72 6f 6c 2c 20 61 20 74 65 73 74 20  control, a test 
c1b0: 70 72 6f 67 72 61 6d 20 63 61 6e 0a 2a 2a 20 73  program can.** s
c1c0: 69 6d 75 6c 61 74 65 20 66 61 75 6c 74 73 20 61  imulate faults a
c1d0: 6e 64 20 65 72 72 6f 72 20 63 6f 6e 64 69 74 69  nd error conditi
c1e0: 6f 6e 73 20 74 68 61 74 20 77 6f 75 6c 64 20 6f  ons that would o
c1f0: 74 68 65 72 77 69 73 65 20 62 65 20 64 69 66 66  therwise be diff
c200: 69 63 75 6c 74 0a 2a 2a 20 6f 72 20 69 6d 70 6f  icult.** or impo
c210: 73 73 69 62 6c 65 20 74 6f 20 69 6e 64 75 63 65  ssible to induce
c220: 2e 20 20 54 68 65 20 73 65 74 20 6f 66 20 73 79  .  The set of sy
c230: 73 74 65 6d 20 63 61 6c 6c 73 20 74 68 61 74 20  stem calls that 
c240: 63 61 6e 20 62 65 20 6f 76 65 72 72 69 64 64 65  can be overridde
c250: 6e 0a 2a 2a 20 76 61 72 69 65 73 20 66 72 6f 6d  n.** varies from
c260: 20 6f 6e 65 20 56 46 53 20 74 6f 20 61 6e 6f 74   one VFS to anot
c270: 68 65 72 2c 20 61 6e 64 20 66 72 6f 6d 20 6f 6e  her, and from on
c280: 65 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65  e version of the
c290: 20 73 61 6d 65 20 56 46 53 20 74 6f 20 74 68 65   same VFS to the
c2a0: 0a 2a 2a 20 6e 65 78 74 2e 20 20 41 70 70 6c 69  .** next.  Appli
c2b0: 63 61 74 69 6f 6e 73 20 74 68 61 74 20 75 73 65  cations that use
c2c0: 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65   these interface
c2d0: 73 20 6d 75 73 74 20 62 65 20 70 72 65 70 61 72  s must be prepar
c2e0: 65 64 20 66 6f 72 20 61 6e 79 0a 2a 2a 20 6f 72  ed for any.** or
c2f0: 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 69 6e   all of these in
c300: 74 65 72 66 61 63 65 73 20 74 6f 20 62 65 20 4e  terfaces to be N
c310: 55 4c 4c 20 6f 72 20 66 6f 72 20 74 68 65 69 72  ULL or for their
c320: 20 62 65 68 61 76 69 6f 72 20 74 6f 20 63 68 61   behavior to cha
c330: 6e 67 65 0a 2a 2a 20 66 72 6f 6d 20 6f 6e 65 20  nge.** from one 
c340: 72 65 6c 65 61 73 65 20 74 6f 20 74 68 65 20 6e  release to the n
c350: 65 78 74 2e 20 20 41 70 70 6c 69 63 61 74 69 6f  ext.  Applicatio
c360: 6e 73 20 6d 75 73 74 20 6e 6f 74 20 61 74 74 65  ns must not atte
c370: 6d 70 74 20 74 6f 20 61 63 63 65 73 73 0a 2a 2a  mpt to access.**
c380: 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 6d 65   any of these me
c390: 74 68 6f 64 73 20 69 66 20 74 68 65 20 69 56 65  thods if the iVe
c3a0: 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 56 46 53  rsion of the VFS
c3b0: 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 33 2e   is less than 3.
c3c0: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
c3d0: 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20 73  ct sqlite3_vfs s
c3e0: 71 6c 69 74 65 33 5f 76 66 73 3b 0a 74 79 70 65  qlite3_vfs;.type
c3f0: 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 74  def void (*sqlit
c400: 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 28  e3_syscall_ptr)(
c410: 76 6f 69 64 29 3b 0a 73 74 72 75 63 74 20 73 71  void);.struct sq
c420: 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20 20 69 6e  lite3_vfs {.  in
c430: 74 20 69 56 65 72 73 69 6f 6e 3b 20 20 20 20 20  t iVersion;     
c440: 20 20 20 20 20 20 20 2f 2a 20 53 74 72 75 63 74         /* Struct
c450: 75 72 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62  ure version numb
c460: 65 72 20 28 63 75 72 72 65 6e 74 6c 79 20 33 29  er (currently 3)
c470: 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73 46 69   */.  int szOsFi
c480: 6c 65 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f  le;            /
c490: 2a 20 53 69 7a 65 20 6f 66 20 73 75 62 63 6c 61  * Size of subcla
c4a0: 73 73 65 64 20 73 71 6c 69 74 65 33 5f 66 69 6c  ssed sqlite3_fil
c4b0: 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50 61 74  e */.  int mxPat
c4c0: 68 6e 61 6d 65 3b 20 20 20 20 20 20 20 20 20 20  hname;          
c4d0: 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c 65 20  /* Maximum file 
c4e0: 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74 68 20  pathname length 
c4f0: 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76 66 73  */.  sqlite3_vfs
c500: 20 2a 70 4e 65 78 74 3b 20 20 20 20 20 20 2f 2a   *pNext;      /*
c510: 20 4e 65 78 74 20 72 65 67 69 73 74 65 72 65 64   Next registered
c520: 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73 74 20   VFS */.  const 
c530: 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20 20 20  char *zName;    
c540: 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68     /* Name of th
c550: 69 73 20 76 69 72 74 75 61 6c 20 66 69 6c 65 20  is virtual file 
c560: 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f 69 64  system */.  void
c570: 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20 20   *pAppData;     
c580: 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65 72 20       /* Pointer 
c590: 74 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73  to application-s
c5a0: 70 65 63 69 66 69 63 20 64 61 74 61 20 2a 2f 0a  pecific data */.
c5b0: 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73    int (*xOpen)(s
c5c0: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
c5d0: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
c5e0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 0a 20  sqlite3_file*,. 
c5f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 69 6e                in
c600: 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 4f  t flags, int *pO
c610: 75 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20  utFlags);.  int 
c620: 28 2a 78 44 65 6c 65 74 65 29 28 73 71 6c 69 74  (*xDelete)(sqlit
c630: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
c640: 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20  har *zName, int 
c650: 73 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e 74 20  syncDir);.  int 
c660: 28 2a 78 41 63 63 65 73 73 29 28 73 71 6c 69 74  (*xAccess)(sqlit
c670: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
c680: 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20  har *zName, int 
c690: 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 52 65 73  flags, int *pRes
c6a0: 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46  Out);.  int (*xF
c6b0: 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73 71 6c  ullPathname)(sql
c6c0: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
c6d0: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e   char *zName, in
c6e0: 74 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a 7a 4f  t nOut, char *zO
c6f0: 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28 2a 78  ut);.  void *(*x
c700: 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f  DlOpen)(sqlite3_
c710: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
c720: 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a 20 20   *zFilename);.  
c730: 76 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f 72 29  void (*xDlError)
c740: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69  (sqlite3_vfs*, i
c750: 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a  nt nByte, char *
c760: 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f 69 64  zErrMsg);.  void
c770: 20 28 2a 28 2a 78 44 6c 53 79 6d 29 28 73 71 6c   (*(*xDlSym)(sql
c780: 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69 64 2a 2c  ite3_vfs*,void*,
c790: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 79   const char *zSy
c7a0: 6d 62 6f 6c 29 29 28 76 6f 69 64 29 3b 0a 20 20  mbol))(void);.  
c7b0: 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73 65 29  void (*xDlClose)
c7c0: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 76  (sqlite3_vfs*, v
c7d0: 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  oid*);.  int (*x
c7e0: 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71 6c 69  Randomness)(sqli
c7f0: 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42  te3_vfs*, int nB
c800: 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29  yte, char *zOut)
c810: 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65 65 70  ;.  int (*xSleep
c820: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
c830: 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73  int microseconds
c840: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 72  );.  int (*xCurr
c850: 65 6e 74 54 69 6d 65 29 28 73 71 6c 69 74 65 33  entTime)(sqlite3
c860: 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a 29 3b  _vfs*, double*);
c870: 0a 20 20 69 6e 74 20 28 2a 78 47 65 74 4c 61 73  .  int (*xGetLas
c880: 74 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f  tError)(sqlite3_
c890: 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68 61 72 20  vfs*, int, char 
c8a0: 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68  *);.  /*.  ** Th
c8b0: 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20  e methods above 
c8c0: 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 20 31  are in version 1
c8d0: 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76   of the sqlite_v
c8e0: 66 73 20 6f 62 6a 65 63 74 0a 20 20 2a 2a 20 64  fs object.  ** d
c8f0: 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 6f 73  efinition.  Thos
c900: 65 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 61 72  e that follow ar
c910: 65 20 61 64 64 65 64 20 69 6e 20 76 65 72 73 69  e added in versi
c920: 6f 6e 20 32 20 6f 72 20 6c 61 74 65 72 0a 20 20  on 2 or later.  
c930: 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 72  */.  int (*xCurr
c940: 65 6e 74 54 69 6d 65 49 6e 74 36 34 29 28 73 71  entTimeInt64)(sq
c950: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 73 71 6c 69  lite3_vfs*, sqli
c960: 74 65 33 5f 69 6e 74 36 34 2a 29 3b 0a 20 20 2f  te3_int64*);.  /
c970: 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f  *.  ** The metho
c980: 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20  ds above are in 
c990: 76 65 72 73 69 6f 6e 73 20 31 20 61 6e 64 20 32  versions 1 and 2
c9a0: 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76   of the sqlite_v
c9b0: 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a 20  fs object..  ** 
c9c0: 54 68 6f 73 65 20 62 65 6c 6f 77 20 61 72 65 20  Those below are 
c9d0: 66 6f 72 20 76 65 72 73 69 6f 6e 20 33 20 61 6e  for version 3 an
c9e0: 64 20 67 72 65 61 74 65 72 2e 0a 20 20 2a 2f 0a  d greater..  */.
c9f0: 20 20 69 6e 74 20 28 2a 78 53 65 74 53 79 73 74    int (*xSetSyst
ca00: 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f  emCall)(sqlite3_
ca10: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
ca20: 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33   *zName, sqlite3
ca30: 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 3b 0a 20  _syscall_ptr);. 
ca40: 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c   sqlite3_syscall
ca50: 5f 70 74 72 20 28 2a 78 47 65 74 53 79 73 74 65  _ptr (*xGetSyste
ca60: 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76  mCall)(sqlite3_v
ca70: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
ca80: 2a 7a 4e 61 6d 65 29 3b 0a 20 20 63 6f 6e 73 74  *zName);.  const
ca90: 20 63 68 61 72 20 2a 28 2a 78 4e 65 78 74 53 79   char *(*xNextSy
caa0: 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65  stemCall)(sqlite
cab0: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
cac0: 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 2f 2a  ar *zName);.  /*
cad0: 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64  .  ** The method
cae0: 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76  s above are in v
caf0: 65 72 73 69 6f 6e 73 20 31 20 74 68 72 6f 75 67  ersions 1 throug
cb00: 68 20 33 20 6f 66 20 74 68 65 20 73 71 6c 69 74  h 3 of the sqlit
cb10: 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20  e_vfs object..  
cb20: 2a 2a 20 4e 65 77 20 66 69 65 6c 64 73 20 6d 61  ** New fields ma
cb30: 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 69 6e  y be appended in
cb40: 20 66 69 67 75 72 65 20 76 65 72 73 69 6f 6e 73   figure versions
cb50: 2e 20 20 54 68 65 20 69 56 65 72 73 69 6f 6e 0a  .  The iVersion.
cb60: 20 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c 6c 20    ** value will 
cb70: 69 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e 65 76  increment whenev
cb80: 65 72 20 74 68 69 73 20 68 61 70 70 65 6e 73 2e  er this happens.
cb90: 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a   .  */.};../*.**
cba0: 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73   CAPI3REF: Flags
cbb0: 20 66 6f 72 20 74 68 65 20 78 41 63 63 65 73 73   for the xAccess
cbc0: 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a   VFS method.**.*
cbd0: 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20  * These integer 
cbe0: 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20 62 65  constants can be
cbf0: 20 75 73 65 64 20 61 73 20 74 68 65 20 74 68 69   used as the thi
cc00: 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  rd parameter to.
cc10: 2a 2a 20 74 68 65 20 78 41 63 63 65 73 73 20 6d  ** the xAccess m
cc20: 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73 71 6c  ethod of an [sql
cc30: 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
cc40: 2e 20 20 54 68 65 79 20 64 65 74 65 72 6d 69 6e  .  They determin
cc50: 65 0a 2a 2a 20 77 68 61 74 20 6b 69 6e 64 20 6f  e.** what kind o
cc60: 66 20 70 65 72 6d 69 73 73 69 6f 6e 73 20 74 68  f permissions th
cc70: 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64  e xAccess method
cc80: 20 69 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f 72 2e   is looking for.
cc90: 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f  .** With SQLITE_
cca0: 41 43 43 45 53 53 5f 45 58 49 53 54 53 2c 20 74  ACCESS_EXISTS, t
ccb0: 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f  he xAccess metho
ccc0: 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68 65 63  d.** simply chec
ccd0: 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20 66  ks whether the f
cce0: 69 6c 65 20 65 78 69 73 74 73 2e 0a 2a 2a 20 57  ile exists..** W
ccf0: 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53  ith SQLITE_ACCES
cd00: 53 5f 52 45 41 44 57 52 49 54 45 2c 20 74 68 65  S_READWRITE, the
cd10: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a   xAccess method.
cd20: 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 65  ** checks whethe
cd30: 72 20 74 68 65 20 6e 61 6d 65 64 20 64 69 72 65  r the named dire
cd40: 63 74 6f 72 79 20 69 73 20 62 6f 74 68 20 72 65  ctory is both re
cd50: 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61  adable and writa
cd60: 62 6c 65 0a 2a 2a 20 28 69 6e 20 6f 74 68 65 72  ble.** (in other
cd70: 20 77 6f 72 64 73 2c 20 69 66 20 66 69 6c 65 73   words, if files
cd80: 20 63 61 6e 20 62 65 20 61 64 64 65 64 2c 20 72   can be added, r
cd90: 65 6d 6f 76 65 64 2c 20 61 6e 64 20 72 65 6e 61  emoved, and rena
cda0: 6d 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68  med within.** th
cdb0: 65 20 64 69 72 65 63 74 6f 72 79 29 2e 0a 2a 2a  e directory)..**
cdc0: 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43 45   The SQLITE_ACCE
cdd0: 53 53 5f 52 45 41 44 57 52 49 54 45 20 63 6f 6e  SS_READWRITE con
cde0: 73 74 61 6e 74 20 69 73 20 63 75 72 72 65 6e 74  stant is current
cdf0: 6c 79 20 75 73 65 64 20 6f 6e 6c 79 20 62 79 20  ly used only by 
ce00: 74 68 65 0a 2a 2a 20 5b 74 65 6d 70 5f 73 74 6f  the.** [temp_sto
ce10: 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61  re_directory pra
ce20: 67 6d 61 5d 2c 20 74 68 6f 75 67 68 20 74 68 69  gma], though thi
ce30: 73 20 63 6f 75 6c 64 20 63 68 61 6e 67 65 20 69  s could change i
ce40: 6e 20 61 20 66 75 74 75 72 65 0a 2a 2a 20 72 65  n a future.** re
ce50: 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e  lease of SQLite.
ce60: 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f  .** With SQLITE_
ce70: 41 43 43 45 53 53 5f 52 45 41 44 2c 20 74 68 65  ACCESS_READ, the
ce80: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a   xAccess method.
ce90: 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 65  ** checks whethe
cea0: 72 20 74 68 65 20 66 69 6c 65 20 69 73 20 72 65  r the file is re
ceb0: 61 64 61 62 6c 65 2e 20 20 54 68 65 20 53 51 4c  adable.  The SQL
cec0: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20  ITE_ACCESS_READ 
ced0: 63 6f 6e 73 74 61 6e 74 20 69 73 0a 2a 2a 20 63  constant is.** c
cee0: 75 72 72 65 6e 74 6c 79 20 75 6e 75 73 65 64 2c  urrently unused,
cef0: 20 74 68 6f 75 67 68 20 69 74 20 6d 69 67 68 74   though it might
cf00: 20 62 65 20 75 73 65 64 20 69 6e 20 61 20 66 75   be used in a fu
cf10: 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66 0a  ture release of.
cf20: 2a 2a 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64  ** SQLite..*/.#d
cf30: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43  efine SQLITE_ACC
cf40: 45 53 53 5f 45 58 49 53 54 53 20 20 20 20 30 0a  ESS_EXISTS    0.
cf50: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
cf60: 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 20  CCESS_READWRITE 
cf70: 31 20 20 20 2f 2a 20 55 73 65 64 20 62 79 20 50  1   /* Used by P
cf80: 52 41 47 4d 41 20 74 65 6d 70 5f 73 74 6f 72 65  RAGMA temp_store
cf90: 5f 64 69 72 65 63 74 6f 72 79 20 2a 2f 0a 23 64  _directory */.#d
cfa0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43  efine SQLITE_ACC
cfb0: 45 53 53 5f 52 45 41 44 20 20 20 20 20 20 32 20  ESS_READ      2 
cfc0: 20 20 2f 2a 20 55 6e 75 73 65 64 20 2a 2f 0a 0a    /* Unused */..
cfd0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
cfe0: 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78 53  Flags for the xS
cff0: 68 6d 4c 6f 63 6b 20 56 46 53 20 6d 65 74 68 6f  hmLock VFS metho
d000: 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e  d.**.** These in
d010: 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20  teger constants 
d020: 64 65 66 69 6e 65 20 74 68 65 20 76 61 72 69 6f  define the vario
d030: 75 73 20 6c 6f 63 6b 69 6e 67 20 6f 70 65 72 61  us locking opera
d040: 74 69 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f 77 65 64  tions.** allowed
d050: 20 62 79 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b   by the xShmLock
d060: 20 6d 65 74 68 6f 64 20 6f 66 20 5b 73 71 6c 69   method of [sqli
d070: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 2e  te3_io_methods].
d080: 20 20 54 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69    The.** followi
d090: 6e 67 20 61 72 65 20 74 68 65 20 6f 6e 6c 79 20  ng are the only 
d0a0: 6c 65 67 61 6c 20 63 6f 6d 62 69 6e 61 74 69 6f  legal combinatio
d0b0: 6e 73 20 6f 66 20 66 6c 61 67 73 20 74 6f 20 74  ns of flags to t
d0c0: 68 65 0a 2a 2a 20 78 53 68 6d 4c 6f 63 6b 20 6d  he.** xShmLock m
d0d0: 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  ethod:.**.** <ul
d0e0: 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54  >.** <li>  SQLIT
d0f0: 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c  E_SHM_LOCK | SQL
d100: 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a  ITE_SHM_SHARED.*
d110: 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53  * <li>  SQLITE_S
d120: 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45  HM_LOCK | SQLITE
d130: 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a 2a  _SHM_EXCLUSIVE.*
d140: 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53  * <li>  SQLITE_S
d150: 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49  HM_UNLOCK | SQLI
d160: 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a 2a  TE_SHM_SHARED.**
d170: 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48   <li>  SQLITE_SH
d180: 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 54  M_UNLOCK | SQLIT
d190: 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a  E_SHM_EXCLUSIVE.
d1a0: 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 57  ** </ul>.**.** W
d1b0: 68 65 6e 20 75 6e 6c 6f 63 6b 69 6e 67 2c 20 74  hen unlocking, t
d1c0: 68 65 20 73 61 6d 65 20 53 48 41 52 45 44 20 6f  he same SHARED o
d1d0: 72 20 45 58 43 4c 55 53 49 56 45 20 66 6c 61 67  r EXCLUSIVE flag
d1e0: 20 6d 75 73 74 20 62 65 20 73 75 70 70 6c 69 65   must be supplie
d1f0: 64 20 61 73 0a 2a 2a 20 77 61 73 20 67 69 76 65  d as.** was give
d200: 6e 20 6e 6f 20 74 68 65 20 63 6f 72 72 65 73 70  n no the corresp
d210: 6f 6e 64 69 6e 67 20 6c 6f 63 6b 2e 20 20 0a 2a  onding lock.  .*
d220: 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63  *.** The xShmLoc
d230: 6b 20 6d 65 74 68 6f 64 20 63 61 6e 20 74 72 61  k method can tra
d240: 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e 20  nsition between 
d250: 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 53 48 41  unlocked and SHA
d260: 52 45 44 20 6f 72 0a 2a 2a 20 62 65 74 77 65 65  RED or.** betwee
d270: 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 45  n unlocked and E
d280: 58 43 4c 55 53 49 56 45 2e 20 20 49 74 20 63 61  XCLUSIVE.  It ca
d290: 6e 6e 6f 74 20 74 72 61 6e 73 69 74 69 6f 6e 20  nnot transition 
d2a0: 62 65 74 77 65 65 6e 20 53 48 41 52 45 44 0a 2a  between SHARED.*
d2b0: 2a 20 61 6e 64 20 45 58 43 4c 55 53 49 56 45 2e  * and EXCLUSIVE.
d2c0: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
d2d0: 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 20 20  TE_SHM_UNLOCK   
d2e0: 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51      1.#define SQ
d2f0: 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 20 20  LITE_SHM_LOCK   
d300: 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20        2.#define 
d310: 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45  SQLITE_SHM_SHARE
d320: 44 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e  D       4.#defin
d330: 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43  e SQLITE_SHM_EXC
d340: 4c 55 53 49 56 45 20 20 20 20 38 0a 0a 2f 2a 0a  LUSIVE    8../*.
d350: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 61 78  ** CAPI3REF: Max
d360: 69 6d 75 6d 20 78 53 68 6d 4c 6f 63 6b 20 69 6e  imum xShmLock in
d370: 64 65 78 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53  dex.**.** The xS
d380: 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 6e  hmLock method on
d390: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
d3a0: 68 6f 64 73 5d 20 6d 61 79 20 75 73 65 20 76 61  hods] may use va
d3b0: 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20  lues.** between 
d3c0: 30 20 61 6e 64 20 74 68 69 73 20 75 70 70 65 72  0 and this upper
d3d0: 20 62 6f 75 6e 64 20 61 73 20 69 74 73 20 22 6f   bound as its "o
d3e0: 66 66 73 65 74 22 20 61 72 67 75 6d 65 6e 74 2e  ffset" argument.
d3f0: 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63  .** The SQLite c
d400: 6f 72 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 61  ore will never a
d410: 74 74 65 6d 70 74 20 74 6f 20 61 63 71 75 69 72  ttempt to acquir
d420: 65 20 6f 72 20 72 65 6c 65 61 73 65 20 61 0a 2a  e or release a.*
d430: 2a 20 6c 6f 63 6b 20 6f 75 74 73 69 64 65 20 6f  * lock outside o
d440: 66 20 74 68 69 73 20 72 61 6e 67 65 0a 2a 2f 0a  f this range.*/.
d450: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
d460: 48 4d 5f 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20  HM_NLOCK        
d470: 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  8.../*.** CAPI3R
d480: 45 46 3a 20 49 6e 69 74 69 61 6c 69 7a 65 20 54  EF: Initialize T
d490: 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72  he SQLite Librar
d4a0: 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  y.**.** ^The sql
d4b0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
d4c0: 29 20 72 6f 75 74 69 6e 65 20 69 6e 69 74 69 61  ) routine initia
d4d0: 6c 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53 51 4c  lizes the.** SQL
d4e0: 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 5e 54  ite library.  ^T
d4f0: 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  he sqlite3_shutd
d500: 6f 77 6e 28 29 20 72 6f 75 74 69 6e 65 0a 2a 2a  own() routine.**
d510: 20 64 65 61 6c 6c 6f 63 61 74 65 73 20 61 6e 79   deallocates any
d520: 20 72 65 73 6f 75 72 63 65 73 20 74 68 61 74 20   resources that 
d530: 77 65 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62  were allocated b
d540: 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  y sqlite3_initia
d550: 6c 69 7a 65 28 29 2e 0a 2a 2a 20 54 68 65 73 65  lize()..** These
d560: 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 64 65   routines are de
d570: 73 69 67 6e 65 64 20 74 6f 20 61 69 64 20 69 6e  signed to aid in
d580: 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61 6c   process initial
d590: 69 7a 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 73  ization and.** s
d5a0: 68 75 74 64 6f 77 6e 20 6f 6e 20 65 6d 62 65 64  hutdown on embed
d5b0: 64 65 64 20 73 79 73 74 65 6d 73 2e 20 20 57 6f  ded systems.  Wo
d5c0: 72 6b 73 74 61 74 69 6f 6e 20 61 70 70 6c 69 63  rkstation applic
d5d0: 61 74 69 6f 6e 73 20 75 73 69 6e 67 0a 2a 2a 20  ations using.** 
d5e0: 53 51 4c 69 74 65 20 6e 6f 72 6d 61 6c 6c 79 20  SQLite normally 
d5f0: 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 69  do not need to i
d600: 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 6f 66 20  nvoke either of 
d610: 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a  these routines..
d620: 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20  **.** A call to 
d630: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
d640: 7a 65 28 29 20 69 73 20 61 6e 20 22 65 66 66 65  ze() is an "effe
d650: 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69  ctive" call if i
d660: 74 20 69 73 0a 2a 2a 20 74 68 65 20 66 69 72 73  t is.** the firs
d670: 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69  t time sqlite3_i
d680: 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69  nitialize() is i
d690: 6e 76 6f 6b 65 64 20 64 75 72 69 6e 67 20 74 68  nvoked during th
d6a0: 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 0a 2a 2a  e lifetime of.**
d6b0: 20 74 68 65 20 70 72 6f 63 65 73 73 2c 20 6f 72   the process, or
d6c0: 20 69 66 20 69 74 20 69 73 20 74 68 65 20 66 69   if it is the fi
d6d0: 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33  rst time sqlite3
d6e0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73  _initialize() is
d6f0: 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f 6c 6c   invoked.** foll
d700: 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20  owing a call to 
d710: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
d720: 28 29 2e 20 20 5e 28 4f 6e 6c 79 20 61 6e 20 65  ().  ^(Only an e
d730: 66 66 65 63 74 69 76 65 20 63 61 6c 6c 0a 2a 2a  ffective call.**
d740: 20 6f 66 20 73 71 6c 69 74 65 33 5f 69 6e 69 74   of sqlite3_init
d750: 69 61 6c 69 7a 65 28 29 20 64 6f 65 73 20 61 6e  ialize() does an
d760: 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  y initialization
d770: 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 63 61 6c  .  All other cal
d780: 6c 73 0a 2a 2a 20 61 72 65 20 68 61 72 6d 6c 65  ls.** are harmle
d790: 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a  ss no-ops.)^.**.
d7a0: 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c  ** A call to sql
d7b0: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20  ite3_shutdown() 
d7c0: 69 73 20 61 6e 20 22 65 66 66 65 63 74 69 76 65  is an "effective
d7d0: 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73 20  " call if it is 
d7e0: 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 63 61 6c  the first.** cal
d7f0: 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75  l to sqlite3_shu
d800: 74 64 6f 77 6e 28 29 20 73 69 6e 63 65 20 74 68  tdown() since th
d810: 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33 5f 69  e last sqlite3_i
d820: 6e 69 74 69 61 6c 69 7a 65 28 29 2e 20 20 5e 28  nitialize().  ^(
d830: 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66 66 65 63  Only.** an effec
d840: 74 69 76 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c  tive call to sql
d850: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20  ite3_shutdown() 
d860: 64 6f 65 73 20 61 6e 79 20 64 65 69 6e 69 74 69  does any deiniti
d870: 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 20 41 6c  alization..** Al
d880: 6c 20 6f 74 68 65 72 20 76 61 6c 69 64 20 63 61  l other valid ca
d890: 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  lls to sqlite3_s
d8a0: 68 75 74 64 6f 77 6e 28 29 20 61 72 65 20 68 61  hutdown() are ha
d8b0: 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e  rmless no-ops.)^
d8c0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
d8d0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
d8e0: 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 68 72  interface is thr
d8f0: 65 61 64 73 61 66 65 2c 20 62 75 74 20 73 71 6c  eadsafe, but sql
d900: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a  ite3_shutdown().
d910: 2a 2a 20 69 73 20 6e 6f 74 2e 20 20 54 68 65 20  ** is not.  The 
d920: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
d930: 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d 75 73  () interface mus
d940: 74 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64  t only be called
d950: 20 66 72 6f 6d 20 61 0a 2a 2a 20 73 69 6e 67 6c   from a.** singl
d960: 65 20 74 68 72 65 61 64 2e 20 20 41 6c 6c 20 6f  e thread.  All o
d970: 70 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f  pen [database co
d980: 6e 6e 65 63 74 69 6f 6e 73 5d 20 6d 75 73 74 20  nnections] must 
d990: 62 65 20 63 6c 6f 73 65 64 20 61 6e 64 20 61 6c  be closed and al
d9a0: 6c 0a 2a 2a 20 6f 74 68 65 72 20 53 51 4c 69 74  l.** other SQLit
d9b0: 65 20 72 65 73 6f 75 72 63 65 73 20 6d 75 73 74  e resources must
d9c0: 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20   be deallocated 
d9d0: 70 72 69 6f 72 20 74 6f 20 69 6e 76 6f 6b 69 6e  prior to invokin
d9e0: 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 68 75  g.** sqlite3_shu
d9f0: 74 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 41  tdown()..**.** A
da00: 6d 6f 6e 67 20 6f 74 68 65 72 20 74 68 69 6e 67  mong other thing
da10: 73 2c 20 5e 73 71 6c 69 74 65 33 5f 69 6e 69 74  s, ^sqlite3_init
da20: 69 61 6c 69 7a 65 28 29 20 77 69 6c 6c 20 69 6e  ialize() will in
da30: 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  voke.** sqlite3_
da40: 6f 73 5f 69 6e 69 74 28 29 2e 20 20 53 69 6d 69  os_init().  Simi
da50: 6c 61 72 6c 79 2c 20 5e 73 71 6c 69 74 65 33 5f  larly, ^sqlite3_
da60: 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 77 69  shutdown().** wi
da70: 6c 6c 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65  ll invoke sqlite
da80: 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a 0a 2a  3_os_end()..**.*
da90: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69  * ^The sqlite3_i
daa0: 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74  nitialize() rout
dab0: 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ine returns [SQL
dac0: 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65  ITE_OK] on succe
dad0: 73 73 2e 0a 2a 2a 20 5e 49 66 20 66 6f 72 20 73  ss..** ^If for s
dae0: 6f 6d 65 20 72 65 61 73 6f 6e 2c 20 73 71 6c 69  ome reason, sqli
daf0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
db00: 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 69 6e   is unable to in
db10: 69 74 69 61 6c 69 7a 65 0a 2a 2a 20 74 68 65 20  itialize.** the 
db20: 6c 69 62 72 61 72 79 20 28 70 65 72 68 61 70 73  library (perhaps
db30: 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f   it is unable to
db40: 20 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65 65 64   allocate a need
db50: 65 64 20 72 65 73 6f 75 72 63 65 20 73 75 63 68  ed resource such
db60: 0a 2a 2a 20 61 73 20 61 20 6d 75 74 65 78 29 20  .** as a mutex) 
db70: 69 74 20 72 65 74 75 72 6e 73 20 61 6e 20 5b 65  it returns an [e
db80: 72 72 6f 72 20 63 6f 64 65 5d 20 6f 74 68 65 72  rror code] other
db90: 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b   than [SQLITE_OK
dba0: 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ]..**.** ^The sq
dbb0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
dbc0: 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61  () routine is ca
dbd0: 6c 6c 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20  lled internally 
dbe0: 62 79 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a  by many other.**
dbf0: 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
dc00: 65 73 20 73 6f 20 74 68 61 74 20 61 6e 20 61 70  es so that an ap
dc10: 70 6c 69 63 61 74 69 6f 6e 20 75 73 75 61 6c 6c  plication usuall
dc20: 79 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20  y does not need 
dc30: 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c  to.** invoke sql
dc40: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
dc50: 29 20 64 69 72 65 63 74 6c 79 2e 20 20 46 6f 72  ) directly.  For
dc60: 20 65 78 61 6d 70 6c 65 2c 20 5b 73 71 6c 69 74   example, [sqlit
dc70: 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 63 61  e3_open()].** ca
dc80: 6c 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  lls sqlite3_init
dc90: 69 61 6c 69 7a 65 28 29 20 73 6f 20 74 68 65 20  ialize() so the 
dca0: 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77  SQLite library w
dcb0: 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63  ill be automatic
dcc0: 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69 61 6c 69  ally.** initiali
dcd0: 7a 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65  zed when [sqlite
dce0: 33 5f 6f 70 65 6e 28 29 5d 20 69 73 20 63 61 6c  3_open()] is cal
dcf0: 6c 65 64 20 69 66 20 69 74 20 68 61 73 20 6e 6f  led if it has no
dd00: 74 20 62 65 20 69 6e 69 74 69 61 6c 69 7a 65 64  t be initialized
dd10: 0a 2a 2a 20 61 6c 72 65 61 64 79 2e 20 20 5e 48  .** already.  ^H
dd20: 6f 77 65 76 65 72 2c 20 69 66 20 53 51 4c 69 74  owever, if SQLit
dd30: 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
dd40: 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  th the [SQLITE_O
dd50: 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 0a 2a 2a  MIT_AUTOINIT].**
dd60: 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
dd70: 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 61  tion, then the a
dd80: 75 74 6f 6d 61 74 69 63 20 63 61 6c 6c 73 20 74  utomatic calls t
dd90: 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  o sqlite3_initia
dda0: 6c 69 7a 65 28 29 0a 2a 2a 20 61 72 65 20 6f 6d  lize().** are om
ddb0: 69 74 74 65 64 20 61 6e 64 20 74 68 65 20 61 70  itted and the ap
ddc0: 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 63  plication must c
ddd0: 61 6c 6c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  all sqlite3_init
dde0: 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c  ialize() directl
ddf0: 79 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 75 73  y.** prior to us
de00: 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51  ing any other SQ
de10: 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20  Lite interface. 
de20: 20 46 6f 72 20 6d 61 78 69 6d 75 6d 20 70 6f 72   For maximum por
de30: 74 61 62 69 6c 69 74 79 2c 0a 2a 2a 20 69 74 20  tability,.** it 
de40: 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74  is recommended t
de50: 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  hat applications
de60: 20 61 6c 77 61 79 73 20 69 6e 76 6f 6b 65 20 73   always invoke s
de70: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
de80: 65 28 29 0a 2a 2a 20 64 69 72 65 63 74 6c 79 20  e().** directly 
de90: 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61  prior to using a
dea0: 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20  ny other SQLite 
deb0: 69 6e 74 65 72 66 61 63 65 2e 20 20 46 75 74 75  interface.  Futu
dec0: 72 65 20 72 65 6c 65 61 73 65 73 0a 2a 2a 20 6f  re releases.** o
ded0: 66 20 53 51 4c 69 74 65 20 6d 61 79 20 72 65 71  f SQLite may req
dee0: 75 69 72 65 20 74 68 69 73 2e 20 20 49 6e 20 6f  uire this.  In o
def0: 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20  ther words, the 
df00: 62 65 68 61 76 69 6f 72 20 65 78 68 69 62 69 74  behavior exhibit
df10: 65 64 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74  ed.** when SQLit
df20: 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
df30: 74 68 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  th [SQLITE_OMIT_
df40: 41 55 54 4f 49 4e 49 54 5d 20 6d 69 67 68 74 20  AUTOINIT] might 
df50: 62 65 63 6f 6d 65 20 74 68 65 0a 2a 2a 20 64 65  become the.** de
df60: 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20 69  fault behavior i
df70: 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20 72 65  n some future re
df80: 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e  lease of SQLite.
df90: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
dfa0: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 72 6f 75  e3_os_init() rou
dfb0: 74 69 6e 65 20 64 6f 65 73 20 6f 70 65 72 61 74  tine does operat
dfc0: 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69  ing-system speci
dfd0: 66 69 63 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a  fic.** initializ
dfe0: 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 53 51 4c  ation of the SQL
dff0: 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 54 68  ite library.  Th
e000: 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  e sqlite3_os_end
e010: 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 75 6e  ().** routine un
e020: 64 6f 65 73 20 74 68 65 20 65 66 66 65 63 74 20  does the effect 
e030: 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  of sqlite3_os_in
e040: 69 74 28 29 2e 20 20 54 79 70 69 63 61 6c 20 74  it().  Typical t
e050: 61 73 6b 73 0a 2a 2a 20 70 65 72 66 6f 72 6d 65  asks.** performe
e060: 64 20 62 79 20 74 68 65 73 65 20 72 6f 75 74 69  d by these routi
e070: 6e 65 73 20 69 6e 63 6c 75 64 65 20 61 6c 6c 6f  nes include allo
e080: 63 61 74 69 6f 6e 20 6f 72 20 64 65 61 6c 6c 6f  cation or deallo
e090: 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73 74 61  cation.** of sta
e0a0: 74 69 63 20 72 65 73 6f 75 72 63 65 73 2c 20 69  tic resources, i
e0b0: 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66  nitialization of
e0c0: 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65   global variable
e0d0: 73 2c 0a 2a 2a 20 73 65 74 74 69 6e 67 20 75 70  s,.** setting up
e0e0: 20 61 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69   a default [sqli
e0f0: 74 65 33 5f 76 66 73 5d 20 6d 6f 64 75 6c 65 2c  te3_vfs] module,
e100: 20 6f 72 20 73 65 74 74 69 6e 67 20 75 70 0a 2a   or setting up.*
e110: 2a 20 61 20 64 65 66 61 75 6c 74 20 63 6f 6e 66  * a default conf
e120: 69 67 75 72 61 74 69 6f 6e 20 75 73 69 6e 67 20  iguration using 
e130: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
e140: 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70  )]..**.** The ap
e150: 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64  plication should
e160: 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 65 69   never invoke ei
e170: 74 68 65 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f  ther sqlite3_os_
e180: 69 6e 69 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c  init().** or sql
e190: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 64 69  ite3_os_end() di
e1a0: 72 65 63 74 6c 79 2e 20 20 54 68 65 20 61 70 70  rectly.  The app
e1b0: 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  lication should 
e1c0: 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73  only invoke.** s
e1d0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
e1e0: 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  e() and sqlite3_
e1f0: 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 54 68 65  shutdown().  The
e200: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
e210: 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  ().** interface 
e220: 69 73 20 63 61 6c 6c 65 64 20 61 75 74 6f 6d 61  is called automa
e230: 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74  tically by sqlit
e240: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
e250: 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  and.** sqlite3_o
e260: 73 5f 65 6e 64 28 29 20 69 73 20 63 61 6c 6c 65  s_end() is calle
e270: 64 20 62 79 20 73 71 6c 69 74 65 33 5f 73 68 75  d by sqlite3_shu
e280: 74 64 6f 77 6e 28 29 2e 20 20 41 70 70 72 6f 70  tdown().  Approp
e290: 72 69 61 74 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65  riate.** impleme
e2a0: 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20 73 71 6c  ntations for sql
e2b0: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61  ite3_os_init() a
e2c0: 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  nd sqlite3_os_en
e2d0: 64 28 29 0a 2a 2a 20 61 72 65 20 62 75 69 6c 74  d().** are built
e2e0: 20 69 6e 74 6f 20 53 51 4c 69 74 65 20 77 68 65   into SQLite whe
e2f0: 6e 20 69 74 20 69 73 20 63 6f 6d 70 69 6c 65 64  n it is compiled
e300: 20 66 6f 72 20 55 6e 69 78 2c 20 57 69 6e 64 6f   for Unix, Windo
e310: 77 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a 2a 2a 20  ws, or OS/2..** 
e320: 57 68 65 6e 20 5b 63 75 73 74 6f 6d 20 62 75 69  When [custom bui
e330: 6c 64 73 20 7c 20 62 75 69 6c 74 20 66 6f 72 20  lds | built for 
e340: 6f 74 68 65 72 20 70 6c 61 74 66 6f 72 6d 73 5d  other platforms]
e350: 0a 2a 2a 20 28 75 73 69 6e 67 20 74 68 65 20 5b  .** (using the [
e360: 53 51 4c 49 54 45 5f 4f 53 5f 4f 54 48 45 52 3d  SQLITE_OS_OTHER=
e370: 31 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a  1] compile-time.
e380: 2a 2a 20 6f 70 74 69 6f 6e 29 20 74 68 65 20 61  ** option) the a
e390: 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
e3a0: 73 75 70 70 6c 79 20 61 20 73 75 69 74 61 62 6c  supply a suitabl
e3b0: 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
e3c0: 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   for.** sqlite3_
e3d0: 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71  os_init() and sq
e3e0: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 20  lite3_os_end(). 
e3f0: 20 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   An application-
e400: 73 75 70 70 6c 69 65 64 0a 2a 2a 20 69 6d 70 6c  supplied.** impl
e410: 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71  ementation of sq
e420: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20  lite3_os_init() 
e430: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  or sqlite3_os_en
e440: 64 28 29 0a 2a 2a 20 6d 75 73 74 20 72 65 74 75  d().** must retu
e450: 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f  rn [SQLITE_OK] o
e460: 6e 20 73 75 63 63 65 73 73 20 61 6e 64 20 73 6f  n success and so
e470: 6d 65 20 6f 74 68 65 72 20 5b 65 72 72 6f 72 20  me other [error 
e480: 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20 66 61  code] upon.** fa
e490: 69 6c 75 72 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ilure..*/.int sq
e4a0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
e4b0: 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69  (void);.int sqli
e4c0: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 76 6f 69  te3_shutdown(voi
e4d0: 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  d);.int sqlite3_
e4e0: 6f 73 5f 69 6e 69 74 28 76 6f 69 64 29 3b 0a 69  os_init(void);.i
e4f0: 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  nt sqlite3_os_en
e500: 64 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20  d(void);../*.** 
e510: 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67  CAPI3REF: Config
e520: 75 72 69 6e 67 20 54 68 65 20 53 51 4c 69 74 65  uring The SQLite
e530: 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 54   Library.**.** T
e540: 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  he sqlite3_confi
e550: 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  g() interface is
e560: 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 67 6c   used to make gl
e570: 6f 62 61 6c 20 63 6f 6e 66 69 67 75 72 61 74 69  obal configurati
e580: 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f  on.** changes to
e590: 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72   SQLite in order
e5a0: 20 74 6f 20 74 75 6e 65 20 53 51 4c 69 74 65 20   to tune SQLite 
e5b0: 74 6f 20 74 68 65 20 73 70 65 63 69 66 69 63 20  to the specific 
e5c0: 6e 65 65 64 73 20 6f 66 0a 2a 2a 20 74 68 65 20  needs of.** the 
e5d0: 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 54 68  application.  Th
e5e0: 65 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67  e default config
e5f0: 75 72 61 74 69 6f 6e 20 69 73 20 72 65 63 6f 6d  uration is recom
e600: 6d 65 6e 64 65 64 20 66 6f 72 20 6d 6f 73 74 0a  mended for most.
e610: 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  ** applications 
e620: 61 6e 64 20 73 6f 20 74 68 69 73 20 72 6f 75 74  and so this rout
e630: 69 6e 65 20 69 73 20 75 73 75 61 6c 6c 79 20 6e  ine is usually n
e640: 6f 74 20 6e 65 63 65 73 73 61 72 79 2e 20 20 49  ot necessary.  I
e650: 74 20 69 73 0a 2a 2a 20 70 72 6f 76 69 64 65 64  t is.** provided
e660: 20 74 6f 20 73 75 70 70 6f 72 74 20 72 61 72 65   to support rare
e670: 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 77 69   applications wi
e680: 74 68 20 75 6e 75 73 75 61 6c 20 6e 65 65 64 73  th unusual needs
e690: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
e6a0: 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74  te3_config() int
e6b0: 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20 74 68  erface is not th
e6c0: 72 65 61 64 73 61 66 65 2e 20 20 54 68 65 20 61  readsafe.  The a
e6d0: 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75  pplication.** mu
e6e0: 73 74 20 69 6e 73 75 72 65 20 74 68 61 74 20 6e  st insure that n
e6f0: 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69  o other SQLite i
e700: 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 69 6e  nterfaces are in
e710: 76 6f 6b 65 64 20 62 79 20 6f 74 68 65 72 0a 2a  voked by other.*
e720: 2a 20 74 68 72 65 61 64 73 20 77 68 69 6c 65 20  * threads while 
e730: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
e740: 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20 20 46 75   is running.  Fu
e750: 72 74 68 65 72 6d 6f 72 65 2c 20 73 71 6c 69 74  rthermore, sqlit
e760: 65 33 5f 63 6f 6e 66 69 67 28 29 0a 2a 2a 20 6d  e3_config().** m
e770: 61 79 20 6f 6e 6c 79 20 62 65 20 69 6e 76 6f 6b  ay only be invok
e780: 65 64 20 70 72 69 6f 72 20 74 6f 20 6c 69 62 72  ed prior to libr
e790: 61 72 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  ary initializati
e7a0: 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c  on using.** [sql
e7b0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
e7c0: 29 5d 20 6f 72 20 61 66 74 65 72 20 73 68 75 74  )] or after shut
e7d0: 64 6f 77 6e 20 62 79 20 5b 73 71 6c 69 74 65 33  down by [sqlite3
e7e0: 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a  _shutdown()]..**
e7f0: 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6f 6e   ^If sqlite3_con
e800: 66 69 67 28 29 20 69 73 20 63 61 6c 6c 65 64 20  fig() is called 
e810: 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 69  after [sqlite3_i
e820: 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 61 6e 64  nitialize()] and
e830: 20 62 65 66 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69   before.** [sqli
e840: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20  te3_shutdown()] 
e850: 74 68 65 6e 20 69 74 20 77 69 6c 6c 20 72 65 74  then it will ret
e860: 75 72 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53  urn SQLITE_MISUS
e870: 45 2e 0a 2a 2a 20 4e 6f 74 65 2c 20 68 6f 77 65  E..** Note, howe
e880: 76 65 72 2c 20 74 68 61 74 20 5e 73 71 6c 69 74  ver, that ^sqlit
e890: 65 33 5f 63 6f 6e 66 69 67 28 29 20 63 61 6e 20  e3_config() can 
e8a0: 62 65 20 63 61 6c 6c 65 64 20 61 73 20 70 61 72  be called as par
e8b0: 74 20 6f 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c  t of the.** impl
e8c0: 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e  ementation of an
e8d0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
e8e0: 69 6e 65 64 20 5b 73 71 6c 69 74 65 33 5f 6f 73  ined [sqlite3_os
e8f0: 5f 69 6e 69 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  _init()]..**.** 
e900: 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
e910: 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  nt to sqlite3_co
e920: 6e 66 69 67 28 29 20 69 73 20 61 6e 20 69 6e 74  nfig() is an int
e930: 65 67 65 72 0a 2a 2a 20 5b 63 6f 6e 66 69 67 75  eger.** [configu
e940: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 20 74  ration option] t
e950: 68 61 74 20 64 65 74 65 72 6d 69 6e 65 73 0a 2a  hat determines.*
e960: 2a 20 77 68 61 74 20 70 72 6f 70 65 72 74 79 20  * what property 
e970: 6f 66 20 53 51 4c 69 74 65 20 69 73 20 74 6f 20  of SQLite is to 
e980: 62 65 20 63 6f 6e 66 69 67 75 72 65 64 2e 20 20  be configured.  
e990: 53 75 62 73 65 71 75 65 6e 74 20 61 72 67 75 6d  Subsequent argum
e9a0: 65 6e 74 73 0a 2a 2a 20 76 61 72 79 20 64 65 70  ents.** vary dep
e9b0: 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 5b 63  ending on the [c
e9c0: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
e9d0: 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66  ion].** in the f
e9e0: 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  irst argument..*
e9f0: 2a 0a 2a 2a 20 5e 57 68 65 6e 20 61 20 63 6f 6e  *.** ^When a con
ea00: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
ea10: 6e 20 69 73 20 73 65 74 2c 20 73 71 6c 69 74 65  n is set, sqlite
ea20: 33 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 75 72  3_config() retur
ea30: 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a  ns [SQLITE_OK]..
ea40: 2a 2a 20 5e 49 66 20 74 68 65 20 6f 70 74 69 6f  ** ^If the optio
ea50: 6e 20 69 73 20 75 6e 6b 6e 6f 77 6e 20 6f 72 20  n is unknown or 
ea60: 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65  SQLite is unable
ea70: 20 74 6f 20 73 65 74 20 74 68 65 20 6f 70 74 69   to set the opti
ea80: 6f 6e 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 20  on.** then this 
ea90: 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
eaa0: 61 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f  a non-zero [erro
eab0: 72 20 63 6f 64 65 5d 2e 0a 2a 2f 0a 69 6e 74 20  r code]..*/.int 
eac0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 69  sqlite3_config(i
ead0: 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a  nt, ...);../*.**
eae0: 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69   CAPI3REF: Confi
eaf0: 67 75 72 65 20 64 61 74 61 62 61 73 65 20 63 6f  gure database co
eb00: 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20  nnections.**.** 
eb10: 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 63  The sqlite3_db_c
eb20: 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63  onfig() interfac
eb30: 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b  e is used to mak
eb40: 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a  e configuration.
eb50: 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 61 20  ** changes to a 
eb60: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
eb70: 74 69 6f 6e 5d 2e 20 20 54 68 65 20 69 6e 74 65  tion].  The inte
eb80: 72 66 61 63 65 20 69 73 20 73 69 6d 69 6c 61 72  rface is similar
eb90: 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
eba0: 63 6f 6e 66 69 67 28 29 5d 20 65 78 63 65 70 74  config()] except
ebb0: 20 74 68 61 74 20 74 68 65 20 63 68 61 6e 67 65   that the change
ebc0: 73 20 61 70 70 6c 79 20 74 6f 20 61 20 73 69 6e  s apply to a sin
ebd0: 67 6c 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  gle.** [database
ebe0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 73 70   connection] (sp
ebf0: 65 63 69 66 69 65 64 20 69 6e 20 74 68 65 20 66  ecified in the f
ec00: 69 72 73 74 20 61 72 67 75 6d 65 6e 74 29 2e 0a  irst argument)..
ec10: 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  **.** The second
ec20: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
ec30: 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 44  ite3_db_config(D
ec40: 2c 56 2c 2e 2e 2e 29 20 20 69 73 20 74 68 65 0a  ,V,...)  is the.
ec50: 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e  ** [SQLITE_DBCON
ec60: 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 7c 20  FIG_LOOKASIDE | 
ec70: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65  configuration ve
ec80: 72 62 5d 20 2d 20 61 6e 20 69 6e 74 65 67 65 72  rb] - an integer
ec90: 20 63 6f 64 65 20 0a 2a 2a 20 74 68 61 74 20 69   code .** that i
eca0: 6e 64 69 63 61 74 65 73 20 77 68 61 74 20 61 73  ndicates what as
ecb0: 70 65 63 74 20 6f 66 20 74 68 65 20 5b 64 61 74  pect of the [dat
ecc0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
ecd0: 5d 20 69 73 20 62 65 69 6e 67 20 63 6f 6e 66 69  ] is being confi
ece0: 67 75 72 65 64 2e 0a 2a 2a 20 53 75 62 73 65 71  gured..** Subseq
ecf0: 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 20 76  uent arguments v
ed00: 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  ary depending on
ed10: 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69   the configurati
ed20: 6f 6e 20 76 65 72 62 2e 0a 2a 2a 0a 2a 2a 20 5e  on verb..**.** ^
ed30: 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  Calls to sqlite3
ed40: 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 72 65 74  _db_config() ret
ed50: 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66  urn SQLITE_OK if
ed60: 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20   and only if.** 
ed70: 74 68 65 20 63 61 6c 6c 20 69 73 20 63 6f 6e 73  the call is cons
ed80: 69 64 65 72 65 64 20 73 75 63 63 65 73 73 66 75  idered successfu
ed90: 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  l..*/.int sqlite
eda0: 33 5f 64 62 5f 63 6f 6e 66 69 67 28 73 71 6c 69  3_db_config(sqli
edb0: 74 65 33 2a 2c 20 69 6e 74 20 6f 70 2c 20 2e 2e  te3*, int op, ..
edc0: 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
edd0: 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f  REF: Memory Allo
ede0: 63 61 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73 0a  cation Routines.
edf0: 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63  **.** An instanc
ee00: 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
ee10: 20 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74   defines the int
ee20: 65 72 66 61 63 65 20 62 65 74 77 65 65 6e 20 53  erface between S
ee30: 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 6c 6f 77  QLite.** and low
ee40: 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c  -level memory al
ee50: 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  location routine
ee60: 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 6f 62  s..**.** This ob
ee70: 6a 65 63 74 20 69 73 20 75 73 65 64 20 69 6e 20  ject is used in 
ee80: 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61 63 65 20 69  only one place i
ee90: 6e 20 74 68 65 20 53 51 4c 69 74 65 20 69 6e 74  n the SQLite int
eea0: 65 72 66 61 63 65 2e 0a 2a 2a 20 41 20 70 6f 69  erface..** A poi
eeb0: 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61  nter to an insta
eec0: 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65  nce of this obje
eed0: 63 74 20 69 73 20 74 68 65 20 61 72 67 75 6d 65  ct is the argume
eee0: 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  nt to.** [sqlite
eef0: 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 68 65 6e  3_config()] when
ef00: 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69   the configurati
ef10: 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20  on option is.** 
ef20: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
ef30: 41 4c 4c 4f 43 5d 20 6f 72 20 5b 53 51 4c 49 54  ALLOC] or [SQLIT
ef40: 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c  E_CONFIG_GETMALL
ef50: 4f 43 5d 2e 20 20 0a 2a 2a 20 42 79 20 63 72 65  OC].  .** By cre
ef60: 61 74 69 6e 67 20 61 6e 20 69 6e 73 74 61 6e 63  ating an instanc
ef70: 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
ef80: 0a 2a 2a 20 61 6e 64 20 70 61 73 73 69 6e 67 20  .** and passing 
ef90: 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  it to [sqlite3_c
efa0: 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43  onfig]([SQLITE_C
efb0: 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 29 0a 2a  ONFIG_MALLOC]).*
efc0: 2a 20 64 75 72 69 6e 67 20 63 6f 6e 66 69 67 75  * during configu
efd0: 72 61 74 69 6f 6e 2c 20 61 6e 20 61 70 70 6c 69  ration, an appli
efe0: 63 61 74 69 6f 6e 20 63 61 6e 20 73 70 65 63 69  cation can speci
eff0: 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76  fy an alternativ
f000: 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  e.** memory allo
f010: 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d  cation subsystem
f020: 20 66 6f 72 20 53 51 4c 69 74 65 20 74 6f 20 75   for SQLite to u
f030: 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74  se for all of it
f040: 73 0a 2a 2a 20 64 79 6e 61 6d 69 63 20 6d 65 6d  s.** dynamic mem
f050: 6f 72 79 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a  ory needs..**.**
f060: 20 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 69 74   Note that SQLit
f070: 65 20 63 6f 6d 65 73 20 77 69 74 68 20 73 65 76  e comes with sev
f080: 65 72 61 6c 20 5b 62 75 69 6c 74 2d 69 6e 20 6d  eral [built-in m
f090: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73  emory allocators
f0a0: 5d 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 70 65  ].** that are pe
f0b0: 72 66 65 63 74 6c 79 20 61 64 65 71 75 61 74 65  rfectly adequate
f0c0: 20 66 6f 72 20 74 68 65 20 6f 76 65 72 77 68 65   for the overwhe
f0d0: 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69 74 79 20 6f  lming majority o
f0e0: 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a  f applications.*
f0f0: 2a 20 61 6e 64 20 74 68 61 74 20 74 68 69 73 20  * and that this 
f100: 6f 62 6a 65 63 74 20 69 73 20 6f 6e 6c 79 20 75  object is only u
f110: 73 65 66 75 6c 20 74 6f 20 61 20 74 69 6e 79 20  seful to a tiny 
f120: 6d 69 6e 6f 72 69 74 79 20 6f 66 20 61 70 70 6c  minority of appl
f130: 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68  ications.** with
f140: 20 73 70 65 63 69 61 6c 69 7a 65 64 20 6d 65 6d   specialized mem
f150: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ory allocation r
f160: 65 71 75 69 72 65 6d 65 6e 74 73 2e 20 20 54 68  equirements.  Th
f170: 69 73 20 6f 62 6a 65 63 74 20 69 73 0a 2a 2a 20  is object is.** 
f180: 61 6c 73 6f 20 75 73 65 64 20 64 75 72 69 6e 67  also used during
f190: 20 74 65 73 74 69 6e 67 20 6f 66 20 53 51 4c 69   testing of SQLi
f1a0: 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 73  te in order to s
f1b0: 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e  pecify an altern
f1c0: 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20  ative.** memory 
f1d0: 61 6c 6c 6f 63 61 74 6f 72 20 74 68 61 74 20 73  allocator that s
f1e0: 69 6d 75 6c 61 74 65 73 20 6d 65 6d 6f 72 79 20  imulates memory 
f1f0: 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20 63 6f  out-of-memory co
f200: 6e 64 69 74 69 6f 6e 73 20 69 6e 0a 2a 2a 20 6f  nditions in.** o
f210: 72 64 65 72 20 74 6f 20 76 65 72 69 66 79 20 74  rder to verify t
f220: 68 61 74 20 53 51 4c 69 74 65 20 72 65 63 6f 76  hat SQLite recov
f230: 65 72 73 20 67 72 61 63 65 66 75 6c 6c 79 20 66  ers gracefully f
f240: 72 6f 6d 20 73 75 63 68 0a 2a 2a 20 63 6f 6e 64  rom such.** cond
f250: 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  itions..**.** Th
f260: 65 20 78 4d 61 6c 6c 6f 63 2c 20 78 52 65 61 6c  e xMalloc, xReal
f270: 6c 6f 63 2c 20 61 6e 64 20 78 46 72 65 65 20 6d  loc, and xFree m
f280: 65 74 68 6f 64 73 20 6d 75 73 74 20 77 6f 72 6b  ethods must work
f290: 20 6c 69 6b 65 20 74 68 65 0a 2a 2a 20 6d 61 6c   like the.** mal
f2a0: 6c 6f 63 28 29 2c 20 72 65 61 6c 6c 6f 63 28 29  loc(), realloc()
f2b0: 20 61 6e 64 20 66 72 65 65 28 29 20 66 75 6e 63   and free() func
f2c0: 74 69 6f 6e 73 20 66 72 6f 6d 20 74 68 65 20 73  tions from the s
f2d0: 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72  tandard C librar
f2e0: 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75  y..** ^SQLite gu
f2f0: 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 68  arantees that th
f300: 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
f310: 74 20 74 6f 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63  t to.** xRealloc
f320: 20 69 73 20 61 6c 77 61 79 73 20 61 20 76 61 6c   is always a val
f330: 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 61  ue returned by a
f340: 20 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f 20 78   prior call to x
f350: 52 6f 75 6e 64 75 70 2e 0a 2a 2a 0a 2a 2a 20 78  Roundup..**.** x
f360: 53 69 7a 65 20 73 68 6f 75 6c 64 20 72 65 74 75  Size should retu
f370: 72 6e 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64  rn the allocated
f380: 20 73 69 7a 65 20 6f 66 20 61 20 6d 65 6d 6f 72   size of a memor
f390: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  y allocation.** 
f3a0: 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69  previously obtai
f3b0: 6e 65 64 20 66 72 6f 6d 20 78 4d 61 6c 6c 6f 63  ned from xMalloc
f3c0: 20 6f 72 20 78 52 65 61 6c 6c 6f 63 2e 20 20 54   or xRealloc.  T
f3d0: 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a  he allocated siz
f3e0: 65 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61  e.** is always a
f3f0: 74 20 6c 65 61 73 74 20 61 73 20 62 69 67 20 61  t least as big a
f400: 73 20 74 68 65 20 72 65 71 75 65 73 74 65 64 20  s the requested 
f410: 73 69 7a 65 20 62 75 74 20 6d 61 79 20 62 65 20  size but may be 
f420: 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  larger..**.** Th
f430: 65 20 78 52 6f 75 6e 64 75 70 20 6d 65 74 68 6f  e xRoundup metho
f440: 64 20 72 65 74 75 72 6e 73 20 77 68 61 74 20 77  d returns what w
f450: 6f 75 6c 64 20 62 65 20 74 68 65 20 61 6c 6c 6f  ould be the allo
f460: 63 61 74 65 64 20 73 69 7a 65 20 6f 66 0a 2a 2a  cated size of.**
f470: 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
f480: 74 69 6f 6e 20 67 69 76 65 6e 20 61 20 70 61 72  tion given a par
f490: 74 69 63 75 6c 61 72 20 72 65 71 75 65 73 74 65  ticular requeste
f4a0: 64 20 73 69 7a 65 2e 20 20 4d 6f 73 74 20 6d 65  d size.  Most me
f4b0: 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f  mory.** allocato
f4c0: 72 73 20 72 6f 75 6e 64 20 75 70 20 6d 65 6d 6f  rs round up memo
f4d0: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 61  ry allocations a
f4e0: 74 20 6c 65 61 73 74 20 74 6f 20 74 68 65 20 6e  t least to the n
f4f0: 65 78 74 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20  ext multiple.** 
f500: 6f 66 20 38 2e 20 20 53 6f 6d 65 20 61 6c 6c 6f  of 8.  Some allo
f510: 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20  cators round up 
f520: 74 6f 20 61 20 6c 61 72 67 65 72 20 6d 75 6c 74  to a larger mult
f530: 69 70 6c 65 20 6f 72 20 74 6f 20 61 20 70 6f 77  iple or to a pow
f540: 65 72 20 6f 66 20 32 2e 0a 2a 2a 20 45 76 65 72  er of 2..** Ever
f550: 79 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  y memory allocat
f560: 69 6f 6e 20 72 65 71 75 65 73 74 20 63 6f 6d 69  ion request comi
f570: 6e 67 20 69 6e 20 74 68 72 6f 75 67 68 20 5b 73  ng in through [s
f580: 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
f590: 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  .** or [sqlite3_
f5a0: 72 65 61 6c 6c 6f 63 28 29 5d 20 66 69 72 73 74  realloc()] first
f5b0: 20 63 61 6c 6c 73 20 78 52 6f 75 6e 64 75 70 2e   calls xRoundup.
f5c0: 20 20 49 66 20 78 52 6f 75 6e 64 75 70 20 72 65    If xRoundup re
f5d0: 74 75 72 6e 73 20 30 2c 20 0a 2a 2a 20 74 68 61  turns 0, .** tha
f5e0: 74 20 63 61 75 73 65 73 20 74 68 65 20 63 6f 72  t causes the cor
f5f0: 72 65 73 70 6f 6e 64 69 6e 67 20 6d 65 6d 6f 72  responding memor
f600: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20  y allocation to 
f610: 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  fail..**.** The 
f620: 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 69 6e 69  xInit method ini
f630: 74 69 61 6c 69 7a 65 73 20 74 68 65 20 6d 65 6d  tializes the mem
f640: 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 2e 20 20  ory allocator.  
f650: 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a  (For example,.**
f660: 20 69 74 20 6d 69 67 68 74 20 61 6c 6c 6f 63 61   it might alloca
f670: 74 65 20 61 6e 79 20 72 65 71 75 69 72 65 20 6d  te any require m
f680: 75 74 65 78 65 73 20 6f 72 20 69 6e 69 74 69 61  utexes or initia
f690: 6c 69 7a 65 20 69 6e 74 65 72 6e 61 6c 20 64 61  lize internal da
f6a0: 74 61 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 73  ta.** structures
f6b0: 2e 20 20 54 68 65 20 78 53 68 75 74 64 6f 77 6e  .  The xShutdown
f6c0: 20 6d 65 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b   method is invok
f6d0: 65 64 20 28 69 6e 64 69 72 65 63 74 6c 79 29 20  ed (indirectly) 
f6e0: 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  by.** [sqlite3_s
f6f0: 68 75 74 64 6f 77 6e 28 29 5d 20 61 6e 64 20 73  hutdown()] and s
f700: 68 6f 75 6c 64 20 64 65 61 6c 6c 6f 63 61 74 65  hould deallocate
f710: 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20 61   any resources a
f720: 63 71 75 69 72 65 64 0a 2a 2a 20 62 79 20 78 49  cquired.** by xI
f730: 6e 69 74 2e 20 20 54 68 65 20 70 41 70 70 44 61  nit.  The pAppDa
f740: 74 61 20 70 6f 69 6e 74 65 72 20 69 73 20 75 73  ta pointer is us
f750: 65 64 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70  ed as the only p
f760: 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 78  arameter to.** x
f770: 49 6e 69 74 20 61 6e 64 20 78 53 68 75 74 64 6f  Init and xShutdo
f780: 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  wn..**.** SQLite
f790: 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49   holds the [SQLI
f7a0: 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f  TE_MUTEX_STATIC_
f7b0: 4d 41 53 54 45 52 5d 20 6d 75 74 65 78 20 77 68  MASTER] mutex wh
f7c0: 65 6e 20 69 74 20 69 6e 76 6f 6b 65 73 0a 2a 2a  en it invokes.**
f7d0: 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f   the xInit metho
f7e0: 64 2c 20 73 6f 20 74 68 65 20 78 49 6e 69 74 20  d, so the xInit 
f7f0: 6d 65 74 68 6f 64 20 6e 65 65 64 20 6e 6f 74 20  method need not 
f800: 62 65 20 74 68 72 65 61 64 73 61 66 65 2e 20 20  be threadsafe.  
f810: 54 68 65 0a 2a 2a 20 78 53 68 75 74 64 6f 77 6e  The.** xShutdown
f820: 20 6d 65 74 68 6f 64 20 69 73 20 6f 6e 6c 79 20   method is only 
f830: 63 61 6c 6c 65 64 20 66 72 6f 6d 20 5b 73 71 6c  called from [sql
f840: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d  ite3_shutdown()]
f850: 20 73 6f 20 69 74 20 64 6f 65 73 0a 2a 2a 20 6e   so it does.** n
f860: 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 74 68  ot need to be th
f870: 72 65 61 64 73 61 66 65 20 65 69 74 68 65 72 2e  readsafe either.
f880: 20 20 46 6f 72 20 61 6c 6c 20 6f 74 68 65 72 20    For all other 
f890: 6d 65 74 68 6f 64 73 2c 20 53 51 4c 69 74 65 0a  methods, SQLite.
f8a0: 2a 2a 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51  ** holds the [SQ
f8b0: 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49  LITE_MUTEX_STATI
f8c0: 43 5f 4d 45 4d 5d 20 6d 75 74 65 78 20 61 73 20  C_MEM] mutex as 
f8d0: 6c 6f 6e 67 20 61 73 20 74 68 65 0a 2a 2a 20 5b  long as the.** [
f8e0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
f8f0: 4d 53 54 41 54 55 53 5d 20 63 6f 6e 66 69 67 75  MSTATUS] configu
f900: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73  ration option is
f910: 20 74 75 72 6e 65 64 20 6f 6e 20 28 77 68 69 63   turned on (whic
f920: 68 0a 2a 2a 20 69 74 20 69 73 20 62 79 20 64 65  h.** it is by de
f930: 66 61 75 6c 74 29 20 61 6e 64 20 73 6f 20 74 68  fault) and so th
f940: 65 20 6d 65 74 68 6f 64 73 20 61 72 65 20 61 75  e methods are au
f950: 74 6f 6d 61 74 69 63 61 6c 6c 79 20 73 65 72 69  tomatically seri
f960: 61 6c 69 7a 65 64 2e 0a 2a 2a 20 48 6f 77 65 76  alized..** Howev
f970: 65 72 2c 20 69 66 20 5b 53 51 4c 49 54 45 5f 43  er, if [SQLITE_C
f980: 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d  ONFIG_MEMSTATUS]
f990: 20 69 73 20 64 69 73 61 62 6c 65 64 2c 20 74 68   is disabled, th
f9a0: 65 6e 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20  en the other.** 
f9b0: 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 62 65 20  methods must be 
f9c0: 74 68 72 65 61 64 73 61 66 65 20 6f 72 20 65 6c  threadsafe or el
f9d0: 73 65 20 6d 61 6b 65 20 74 68 65 69 72 20 6f 77  se make their ow
f9e0: 6e 20 61 72 72 61 6e 67 65 6d 65 6e 74 73 20 66  n arrangements f
f9f0: 6f 72 0a 2a 2a 20 73 65 72 69 61 6c 69 7a 61 74  or.** serializat
fa00: 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  ion..**.** SQLit
fa10: 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 69 6e 76  e will never inv
fa20: 6f 6b 65 20 78 49 6e 69 74 28 29 20 6d 6f 72 65  oke xInit() more
fa30: 20 74 68 61 6e 20 6f 6e 63 65 20 77 69 74 68 6f   than once witho
fa40: 75 74 20 61 6e 20 69 6e 74 65 72 76 65 6e 69 6e  ut an intervenin
fa50: 67 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 78 53 68  g.** call to xSh
fa60: 75 74 64 6f 77 6e 28 29 2e 0a 2a 2f 0a 74 79 70  utdown()..*/.typ
fa70: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
fa80: 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20  te3_mem_methods 
fa90: 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
faa0: 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69  ods;.struct sqli
fab0: 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20  te3_mem_methods 
fac0: 7b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 4d 61 6c  {.  void *(*xMal
fad0: 6c 6f 63 29 28 69 6e 74 29 3b 20 20 20 20 20 20  loc)(int);      
fae0: 20 20 20 2f 2a 20 4d 65 6d 6f 72 79 20 61 6c 6c     /* Memory all
faf0: 6f 63 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e  ocation function
fb00: 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 46 72   */.  void (*xFr
fb10: 65 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20  ee)(void*);     
fb20: 20 20 20 20 20 2f 2a 20 46 72 65 65 20 61 20 70       /* Free a p
fb30: 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  rior allocation 
fb40: 2a 2f 0a 20 20 76 6f 69 64 20 2a 28 2a 78 52 65  */.  void *(*xRe
fb50: 61 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c 69 6e 74  alloc)(void*,int
fb60: 29 3b 20 20 2f 2a 20 52 65 73 69 7a 65 20 61 6e  );  /* Resize an
fb70: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20   allocation */. 
fb80: 20 69 6e 74 20 28 2a 78 53 69 7a 65 29 28 76 6f   int (*xSize)(vo
fb90: 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20  id*);           
fba0: 2f 2a 20 52 65 74 75 72 6e 20 74 68 65 20 73 69  /* Return the si
fbb0: 7a 65 20 6f 66 20 61 6e 20 61 6c 6c 6f 63 61 74  ze of an allocat
fbc0: 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  ion */.  int (*x
fbd0: 52 6f 75 6e 64 75 70 29 28 69 6e 74 29 3b 20 20  Roundup)(int);  
fbe0: 20 20 20 20 20 20 20 20 2f 2a 20 52 6f 75 6e 64          /* Round
fbf0: 20 75 70 20 72 65 71 75 65 73 74 20 73 69 7a 65   up request size
fc00: 20 74 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73   to allocation s
fc10: 69 7a 65 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  ize */.  int (*x
fc20: 49 6e 69 74 29 28 76 6f 69 64 2a 29 3b 20 20 20  Init)(void*);   
fc30: 20 20 20 20 20 20 20 20 2f 2a 20 49 6e 69 74 69          /* Initi
fc40: 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79  alize the memory
fc50: 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20   allocator */.  
fc60: 76 6f 69 64 20 28 2a 78 53 68 75 74 64 6f 77 6e  void (*xShutdown
fc70: 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 2f  )(void*);      /
fc80: 2a 20 44 65 69 6e 69 74 69 61 6c 69 7a 65 20 74  * Deinitialize t
fc90: 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
fca0: 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70  tor */.  void *p
fcb0: 41 70 70 44 61 74 61 3b 20 20 20 20 20 20 20 20  AppData;        
fcc0: 20 20 20 20 20 20 20 20 2f 2a 20 41 72 67 75 6d          /* Argum
fcd0: 65 6e 74 20 74 6f 20 78 49 6e 69 74 28 29 20 61  ent to xInit() a
fce0: 6e 64 20 78 53 68 75 74 64 6f 77 6e 28 29 20 2a  nd xShutdown() *
fcf0: 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.};../*.** CAPI
fd00: 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 61 74  3REF: Configurat
fd10: 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 20 4b  ion Options.** K
fd20: 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6e 66 69 67  EYWORDS: {config
fd30: 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 7d 0a  uration option}.
fd40: 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
fd50: 74 61 6e 74 73 20 61 72 65 20 74 68 65 20 61 76  tants are the av
fd60: 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20  ailable integer 
fd70: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
fd80: 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61  tions that.** ca
fd90: 6e 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74  n be passed as t
fda0: 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
fdb0: 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  t to the [sqlite
fdc0: 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65  3_config()] inte
fdd0: 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77  rface..**.** New
fde0: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
fdf0: 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64  ptions may be ad
fe00: 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65  ded in future re
fe10: 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65  leases of SQLite
fe20: 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f  ..** Existing co
fe30: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
fe40: 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69 73  ons might be dis
fe50: 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c  continued.  Appl
fe60: 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75  ications.** shou
fe70: 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72 65 74  ld check the ret
fe80: 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73  urn code from [s
fe90: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
fea0: 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68   to make sure th
feb0: 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77  at.** the call w
fec0: 6f 72 6b 65 64 2e 20 20 54 68 65 20 5b 73 71 6c  orked.  The [sql
fed0: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69  ite3_config()] i
fee0: 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65  nterface will re
fef0: 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65  turn a.** non-ze
ff00: 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  ro [error code] 
ff10: 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65  if a discontinue
ff20: 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64  d or unsupported
ff30: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
ff40: 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f  ption.** is invo
ff50: 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a  ked..**.** <dl>.
ff60: 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
ff70: 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d  IG_SINGLETHREAD]
ff80: 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
ff90: 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44  FIG_SINGLETHREAD
ffa0: 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
ffb0: 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65  re are no argume
ffc0: 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69  nts to this opti
ffd0: 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f  on.  ^This optio
ffe0: 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74  n sets the.** [t
fff0: 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74  hreading mode] t
10000 6f 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 2e  o Single-thread.
10010 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73    In other words
10020 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a  , it disables.**
10030 20 61 6c 6c 20 6d 75 74 65 78 69 6e 67 20 61 6e   all mutexing an
10040 64 20 70 75 74 73 20 53 51 4c 69 74 65 20 69 6e  d puts SQLite in
10050 74 6f 20 61 20 6d 6f 64 65 20 77 68 65 72 65 20  to a mode where 
10060 69 74 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 75  it can only be u
10070 73 65 64 0a 2a 2a 20 62 79 20 61 20 73 69 6e 67  sed.** by a sing
10080 6c 65 20 74 68 72 65 61 64 2e 20 20 20 5e 49 66  le thread.   ^If
10090 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
100a0 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20  led with.** the 
100b0 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
100c0 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45  FE | SQLITE_THRE
100d0 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c  ADSAFE=0] compil
100e0 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68  e-time option th
100f0 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20  en.** it is not 
10100 70 6f 73 73 69 62 6c 65 20 74 6f 20 63 68 61 6e  possible to chan
10110 67 65 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e  ge the [threadin
10120 67 20 6d 6f 64 65 5d 20 66 72 6f 6d 20 69 74 73  g mode] from its
10130 20 64 65 66 61 75 6c 74 0a 2a 2a 20 76 61 6c 75   default.** valu
10140 65 20 6f 66 20 53 69 6e 67 6c 65 2d 74 68 72 65  e of Single-thre
10150 61 64 20 61 6e 64 20 73 6f 20 5b 73 71 6c 69 74  ad and so [sqlit
10160 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c  e3_config()] wil
10170 6c 20 72 65 74 75 72 6e 20 0a 2a 2a 20 5b 53 51  l return .** [SQ
10180 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63  LITE_ERROR] if c
10190 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 53  alled with the S
101a0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e  QLITE_CONFIG_SIN
101b0 47 4c 45 54 48 52 45 41 44 0a 2a 2a 20 63 6f 6e  GLETHREAD.** con
101c0 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
101d0 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  n.</dd>.**.** [[
101e0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
101f0 4c 54 49 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e  LTITHREAD]] <dt>
10200 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
10210 4c 54 49 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a  LTITHREAD</dt>.*
10220 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20  * <dd>There are 
10230 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  no arguments to 
10240 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54  this option.  ^T
10250 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20  his option sets 
10260 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e  the.** [threadin
10270 67 20 6d 6f 64 65 5d 20 74 6f 20 4d 75 6c 74 69  g mode] to Multi
10280 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68  -thread.  In oth
10290 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73  er words, it dis
102a0 61 62 6c 65 73 0a 2a 2a 20 6d 75 74 65 78 69 6e  ables.** mutexin
102b0 67 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63  g on [database c
102c0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b  onnection] and [
102d0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
102e0 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20  nt] objects..** 
102f0 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
10300 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66  is responsible f
10310 6f 72 20 73 65 72 69 61 6c 69 7a 69 6e 67 20 61  or serializing a
10320 63 63 65 73 73 20 74 6f 0a 2a 2a 20 5b 64 61 74  ccess to.** [dat
10330 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
10340 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64  s] and [prepared
10350 20 73 74 61 74 65 6d 65 6e 74 73 5d 2e 20 20 42   statements].  B
10360 75 74 20 6f 74 68 65 72 20 6d 75 74 65 78 65 73  ut other mutexes
10370 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20  .** are enabled 
10380 73 6f 20 74 68 61 74 20 53 51 4c 69 74 65 20 77  so that SQLite w
10390 69 6c 6c 20 62 65 20 73 61 66 65 20 74 6f 20 75  ill be safe to u
103a0 73 65 20 69 6e 20 61 20 6d 75 6c 74 69 2d 74 68  se in a multi-th
103b0 72 65 61 64 65 64 0a 2a 2a 20 65 6e 76 69 72 6f  readed.** enviro
103c0 6e 6d 65 6e 74 20 61 73 20 6c 6f 6e 67 20 61 73  nment as long as
103d0 20 6e 6f 20 74 77 6f 20 74 68 72 65 61 64 73 20   no two threads 
103e0 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74  attempt to use t
103f0 68 65 20 73 61 6d 65 0a 2a 2a 20 5b 64 61 74 61  he same.** [data
10400 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
10410 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d   at the same tim
10420 65 2e 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69  e.  ^If SQLite i
10430 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a  s compiled with.
10440 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  ** the [SQLITE_T
10450 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49  HREADSAFE | SQLI
10460 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d  TE_THREADSAFE=0]
10470 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
10480 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20  tion then.** it 
10490 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20  is not possible 
104a0 74 6f 20 73 65 74 20 74 68 65 20 4d 75 6c 74 69  to set the Multi
104b0 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61 64 69  -thread [threadi
104c0 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20  ng mode] and.** 
104d0 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
104e0 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b  )] will return [
104f0 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66  SQLITE_ERROR] if
10500 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65   called with the
10510 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  .** SQLITE_CONFI
10520 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 63 6f  G_MULTITHREAD co
10530 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
10540 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  on.</dd>.**.** [
10550 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
10560 45 52 49 41 4c 49 5a 45 44 5d 5d 20 3c 64 74 3e  ERIALIZED]] <dt>
10570 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45  SQLITE_CONFIG_SE
10580 52 49 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a 2a 2a  RIALIZED</dt>.**
10590 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e   <dd>There are n
105a0 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74  o arguments to t
105b0 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68  his option.  ^Th
105c0 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74  is option sets t
105d0 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67  he.** [threading
105e0 20 6d 6f 64 65 5d 20 74 6f 20 53 65 72 69 61 6c   mode] to Serial
105f0 69 7a 65 64 2e 20 49 6e 20 6f 74 68 65 72 20 77  ized. In other w
10600 6f 72 64 73 2c 20 74 68 69 73 20 6f 70 74 69 6f  ords, this optio
10610 6e 20 65 6e 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c  n enables.** all
10620 20 6d 75 74 65 78 65 73 20 69 6e 63 6c 75 64 69   mutexes includi
10630 6e 67 20 74 68 65 20 72 65 63 75 72 73 69 76 65  ng the recursive
10640 0a 2a 2a 20 6d 75 74 65 78 65 73 20 6f 6e 20 5b  .** mutexes on [
10650 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
10660 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72  ion] and [prepar
10670 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62  ed statement] ob
10680 6a 65 63 74 73 2e 0a 2a 2a 20 49 6e 20 74 68 69  jects..** In thi
10690 73 20 6d 6f 64 65 20 28 77 68 69 63 68 20 69 73  s mode (which is
106a0 20 74 68 65 20 64 65 66 61 75 6c 74 20 77 68 65   the default whe
106b0 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  n SQLite is comp
106c0 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 5b 53 51  iled with.** [SQ
106d0 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
106e0 31 5d 29 20 74 68 65 20 53 51 4c 69 74 65 20 6c  1]) the SQLite l
106f0 69 62 72 61 72 79 20 77 69 6c 6c 20 69 74 73 65  ibrary will itse
10700 6c 66 20 73 65 72 69 61 6c 69 7a 65 20 61 63 63  lf serialize acc
10710 65 73 73 0a 2a 2a 20 74 6f 20 5b 64 61 74 61 62  ess.** to [datab
10720 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d  ase connections]
10730 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73   and [prepared s
10740 74 61 74 65 6d 65 6e 74 73 5d 20 73 6f 20 74 68  tatements] so th
10750 61 74 20 74 68 65 0a 2a 2a 20 61 70 70 6c 69 63  at the.** applic
10760 61 74 69 6f 6e 20 69 73 20 66 72 65 65 20 74 6f  ation is free to
10770 20 75 73 65 20 74 68 65 20 73 61 6d 65 20 5b 64   use the same [d
10780 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
10790 6f 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a 20 73 61  on] or the.** sa
107a0 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  me [prepared sta
107b0 74 65 6d 65 6e 74 5d 20 69 6e 20 64 69 66 66 65  tement] in diffe
107c0 72 65 6e 74 20 74 68 72 65 61 64 73 20 61 74 20  rent threads at 
107d0 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 0a 2a  the same time..*
107e0 2a 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20  * ^If SQLite is 
107f0 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
10800 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
10810 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45  EADSAFE | SQLITE
10820 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63  _THREADSAFE=0] c
10830 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
10840 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73  on then.** it is
10850 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f   not possible to
10860 20 73 65 74 20 74 68 65 20 53 65 72 69 61 6c 69   set the Seriali
10870 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  zed [threading m
10880 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ode] and.** [sql
10890 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77  ite3_config()] w
108a0 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  ill return [SQLI
108b0 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c  TE_ERROR] if cal
108c0 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  led with the.** 
108d0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45  SQLITE_CONFIG_SE
108e0 52 49 41 4c 49 5a 45 44 20 63 6f 6e 66 69 67 75  RIALIZED configu
108f0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f  ration option.</
10900 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
10910 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
10920 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
10930 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e  NFIG_MALLOC</dt>
10940 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20  .** <dd> ^(This 
10950 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
10960 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77  ingle argument w
10970 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65  hich is a pointe
10980 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61  r to an.** insta
10990 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  nce of the [sqli
109a0 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d  te3_mem_methods]
109b0 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65   structure.  The
109c0 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66   argument specif
109d0 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69  ies.** alternati
109e0 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d  ve low-level mem
109f0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ory allocation r
10a00 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73  outines to be us
10a10 65 64 20 69 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  ed in place of.*
10a20 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  * the memory all
10a30 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  ocation routines
10a40 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69   built into SQLi
10a50 74 65 2e 29 5e 20 5e 53 51 4c 69 74 65 20 6d 61  te.)^ ^SQLite ma
10a60 6b 65 73 0a 2a 2a 20 69 74 73 20 6f 77 6e 20 70  kes.** its own p
10a70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74  rivate copy of t
10a80 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68  he content of th
10a90 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  e [sqlite3_mem_m
10aa0 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72  ethods] structur
10ab0 65 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68 65 20  e.** before the 
10ac0 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
10ad0 29 5d 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e  )] call returns.
10ae0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
10af0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
10b00 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49  ALLOC]] <dt>SQLI
10b10 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c  TE_CONFIG_GETMAL
10b20 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  LOC</dt>.** <dd>
10b30 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74   ^(This option t
10b40 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
10b50 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20  gument which is 
10b60 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a  a pointer to an.
10b70 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  ** instance of t
10b80 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  he [sqlite3_mem_
10b90 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75  methods] structu
10ba0 72 65 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65  re.  The [sqlite
10bb0 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a  3_mem_methods].*
10bc0 2a 20 73 74 72 75 63 74 75 72 65 20 69 73 20 66  * structure is f
10bd0 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 63  illed with the c
10be0 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64  urrently defined
10bf0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
10c00 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a  on routines.)^.*
10c10 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61  * This option ca
10c20 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65  n be used to ove
10c30 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c  rload the defaul
10c40 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  t memory allocat
10c50 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20  ion.** routines 
10c60 77 69 74 68 20 61 20 77 72 61 70 70 65 72 20 74  with a wrapper t
10c70 68 61 74 20 73 69 6d 75 6c 61 74 69 6f 6e 73 20  hat simulations 
10c80 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
10c90 6e 20 66 61 69 6c 75 72 65 20 6f 72 0a 2a 2a 20  n failure or.** 
10ca0 74 72 61 63 6b 73 20 6d 65 6d 6f 72 79 20 75 73  tracks memory us
10cb0 61 67 65 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65  age, for example
10cc0 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  . </dd>.**.** [[
10cd0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
10ce0 4d 53 54 41 54 55 53 5d 5d 20 3c 64 74 3e 53 51  MSTATUS]] <dt>SQ
10cf0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53  LITE_CONFIG_MEMS
10d00 54 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  TATUS</dt>.** <d
10d10 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  d> ^This option 
10d20 74 61 6b 65 73 20 73 69 6e 67 6c 65 20 61 72 67  takes single arg
10d30 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e  ument of type in
10d40 74 2c 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  t, interpreted a
10d50 73 20 61 20 0a 2a 2a 20 62 6f 6f 6c 65 61 6e 2c  s a .** boolean,
10d60 20 77 68 69 63 68 20 65 6e 61 62 6c 65 73 20 6f   which enables o
10d70 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 63  r disables the c
10d80 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66 20 6d 65 6d  ollection of mem
10d90 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 0a  ory allocation .
10da0 2a 2a 20 73 74 61 74 69 73 74 69 63 73 2e 20 5e  ** statistics. ^
10db0 28 57 68 65 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c  (When memory all
10dc0 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69  ocation statisti
10dd0 63 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 2c  cs are disabled,
10de0 20 74 68 65 20 0a 2a 2a 20 66 6f 6c 6c 6f 77 69   the .** followi
10df0 6e 67 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  ng SQLite interf
10e00 61 63 65 73 20 62 65 63 6f 6d 65 20 6e 6f 6e 2d  aces become non-
10e10 6f 70 65 72 61 74 69 6f 6e 61 6c 3a 0a 2a 2a 20  operational:.** 
10e20 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e    <ul>.**   <li>
10e30 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
10e40 5f 75 73 65 64 28 29 5d 0a 2a 2a 20 20 20 3c 6c  _used()].**   <l
10e50 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  i> [sqlite3_memo
10e60 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 0a  ry_highwater()].
10e70 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74  **   <li> [sqlit
10e80 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d  e3_soft_heap_lim
10e90 69 74 36 34 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69  it64()].**   <li
10ea0 3e 20 5b 73 71 6c 69 74 65 33 5f 73 74 61 74 75  > [sqlite3_statu
10eb0 73 28 29 5d 0a 2a 2a 20 20 20 3c 2f 75 6c 3e 29  s()].**   </ul>)
10ec0 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72 79 20 61 6c 6c  ^.** ^Memory all
10ed0 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69  ocation statisti
10ee0 63 73 20 61 72 65 20 65 6e 61 62 6c 65 64 20 62  cs are enabled b
10ef0 79 20 64 65 66 61 75 6c 74 20 75 6e 6c 65 73 73  y default unless
10f00 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 63 6f   SQLite is.** co
10f10 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c  mpiled with [SQL
10f20 49 54 45 5f 44 45 46 41 55 4c 54 5f 4d 45 4d 53  ITE_DEFAULT_MEMS
10f30 54 41 54 55 53 5d 3d 30 20 69 6e 20 77 68 69 63  TATUS]=0 in whic
10f40 68 20 63 61 73 65 20 6d 65 6d 6f 72 79 0a 2a 2a  h case memory.**
10f50 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74   allocation stat
10f60 69 73 74 69 63 73 20 61 72 65 20 64 69 73 61 62  istics are disab
10f70 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a  led by default..
10f80 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  ** </dd>.**.** [
10f90 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
10fa0 43 52 41 54 43 48 5d 5d 20 3c 64 74 3e 53 51 4c  CRATCH]] <dt>SQL
10fb0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54  ITE_CONFIG_SCRAT
10fc0 43 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  CH</dt>.** <dd> 
10fd0 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65  ^This option spe
10fe0 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20  cifies a static 
10ff0 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68  memory buffer th
11000 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73  at SQLite can us
11010 65 20 66 6f 72 0a 2a 2a 20 73 63 72 61 74 63 68  e for.** scratch
11020 20 6d 65 6d 6f 72 79 2e 20 20 54 68 65 72 65 20   memory.  There 
11030 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65  are three argume
11040 6e 74 73 3a 20 20 41 20 70 6f 69 6e 74 65 72 20  nts:  A pointer 
11050 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 61 6c 69  an 8-byte.** ali
11060 67 6e 65 64 20 6d 65 6d 6f 72 79 20 62 75 66 66  gned memory buff
11070 65 72 20 66 72 6f 6d 20 77 68 69 63 68 20 74 68  er from which th
11080 65 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61  e scratch alloca
11090 74 69 6f 6e 73 20 77 69 6c 6c 20 62 65 0a 2a 2a  tions will be.**
110a0 20 64 72 61 77 6e 2c 20 74 68 65 20 73 69 7a 65   drawn, the size
110b0 20 6f 66 20 65 61 63 68 20 73 63 72 61 74 63 68   of each scratch
110c0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 28 73 7a 29   allocation (sz)
110d0 2c 0a 2a 2a 20 61 6e 64 20 74 68 65 20 6d 61 78  ,.** and the max
110e0 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 73  imum number of s
110f0 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f  cratch allocatio
11100 6e 73 20 28 4e 29 2e 20 20 54 68 65 20 73 7a 0a  ns (N).  The sz.
11110 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74  ** argument must
11120 20 62 65 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f   be a multiple o
11130 66 20 31 36 2e 0a 2a 2a 20 54 68 65 20 66 69 72  f 16..** The fir
11140 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74  st argument must
11150 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   be a pointer to
11160 20 61 6e 20 38 2d 62 79 74 65 20 61 6c 69 67 6e   an 8-byte align
11170 65 64 20 62 75 66 66 65 72 0a 2a 2a 20 6f 66 20  ed buffer.** of 
11180 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79  at least sz*N by
11190 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a  tes of memory..*
111a0 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75  * ^SQLite will u
111b0 73 65 20 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 20  se no more than 
111c0 74 77 6f 20 73 63 72 61 74 63 68 20 62 75 66 66  two scratch buff
111d0 65 72 73 20 70 65 72 20 74 68 72 65 61 64 2e 20  ers per thread. 
111e0 20 53 6f 0a 2a 2a 20 4e 20 73 68 6f 75 6c 64 20   So.** N should 
111f0 62 65 20 73 65 74 20 74 6f 20 74 77 69 63 65 20  be set to twice 
11200 74 68 65 20 65 78 70 65 63 74 65 64 20 6d 61 78  the expected max
11210 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74  imum number of t
11220 68 72 65 61 64 73 2e 0a 2a 2a 20 5e 53 51 4c 69  hreads..** ^SQLi
11230 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 72 65  te will never re
11240 71 75 69 72 65 20 61 20 73 63 72 61 74 63 68 20  quire a scratch 
11250 62 75 66 66 65 72 20 74 68 61 74 20 69 73 20 6d  buffer that is m
11260 6f 72 65 20 74 68 61 6e 20 36 0a 2a 2a 20 74 69  ore than 6.** ti
11270 6d 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65  mes the database
11280 20 70 61 67 65 20 73 69 7a 65 2e 20 5e 49 66 20   page size. ^If 
11290 53 51 4c 69 74 65 20 6e 65 65 64 73 20 6e 65 65  SQLite needs nee
112a0 64 73 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a  ds additional.**
112b0 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 20   scratch memory 
112c0 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70  beyond what is p
112d0 72 6f 76 69 64 65 64 20 62 79 20 74 68 69 73 20  rovided by this 
112e0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
112f0 74 69 6f 6e 2c 20 74 68 65 6e 20 0a 2a 2a 20 5b  tion, then .** [
11300 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
11310 5d 20 77 69 6c 6c 20 62 65 20 75 73 65 64 20 74  ] will be used t
11320 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 6d 65 6d  o obtain the mem
11330 6f 72 79 20 6e 65 65 64 65 64 2e 3c 2f 64 64 3e  ory needed.</dd>
11340 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
11350 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45  CONFIG_PAGECACHE
11360 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
11370 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 3c 2f  NFIG_PAGECACHE</
11380 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69  dt>.** <dd> ^Thi
11390 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69  s option specifi
113a0 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f  es a static memo
113b0 72 79 20 62 75 66 66 65 72 20 74 68 61 74 20 53  ry buffer that S
113c0 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f  QLite can use fo
113d0 72 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73  r.** the databas
113e0 65 20 70 61 67 65 20 63 61 63 68 65 20 77 69 74  e page cache wit
113f0 68 20 74 68 65 20 64 65 66 61 75 6c 74 20 70 61  h the default pa
11400 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65  ge cache impleme
11410 6e 74 61 74 69 6f 6e 2e 20 20 0a 2a 2a 20 54 68  ntation.  .** Th
11420 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  is configuration
11430 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75   should not be u
11440 73 65 64 20 69 66 20 61 6e 20 61 70 70 6c 69 63  sed if an applic
11450 61 74 69 6f 6e 2d 64 65 66 69 6e 65 20 70 61 67  ation-define pag
11460 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70 6c 65  e.** cache imple
11470 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6c 6f 61  mentation is loa
11480 64 65 64 20 75 73 69 6e 67 20 74 68 65 20 53 51  ded using the SQ
11490 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
114a0 48 45 32 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 54  HE2 option..** T
114b0 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61  here are three a
114c0 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73  rguments to this
114d0 20 6f 70 74 69 6f 6e 3a 20 41 20 70 6f 69 6e 74   option: A point
114e0 65 72 20 74 6f 20 38 2d 62 79 74 65 20 61 6c 69  er to 8-byte ali
114f0 67 6e 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20  gned.** memory, 
11500 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68  the size of each
11510 20 70 61 67 65 20 62 75 66 66 65 72 20 28 73 7a   page buffer (sz
11520 29 2c 20 61 6e 64 20 74 68 65 20 6e 75 6d 62 65  ), and the numbe
11530 72 20 6f 66 20 70 61 67 65 73 20 28 4e 29 2e 0a  r of pages (N)..
11540 2a 2a 20 54 68 65 20 73 7a 20 61 72 67 75 6d 65  ** The sz argume
11550 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 74 68 65  nt should be the
11560 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6c 61 72   size of the lar
11570 67 65 73 74 20 64 61 74 61 62 61 73 65 20 70 61  gest database pa
11580 67 65 0a 2a 2a 20 28 61 20 70 6f 77 65 72 20 6f  ge.** (a power o
11590 66 20 74 77 6f 20 62 65 74 77 65 65 6e 20 35 31  f two between 51
115a0 32 20 61 6e 64 20 33 32 37 36 38 29 20 70 6c 75  2 and 32768) plu
115b0 73 20 61 20 6c 69 74 74 6c 65 20 65 78 74 72 61  s a little extra
115c0 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 70 61 67   for each.** pag
115d0 65 20 68 65 61 64 65 72 2e 20 20 5e 54 68 65 20  e header.  ^The 
115e0 70 61 67 65 20 68 65 61 64 65 72 20 73 69 7a 65  page header size
115f0 20 69 73 20 32 30 20 74 6f 20 34 30 20 62 79 74   is 20 to 40 byt
11600 65 73 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 0a  es depending on.
11610 2a 2a 20 74 68 65 20 68 6f 73 74 20 61 72 63 68  ** the host arch
11620 69 74 65 63 74 75 72 65 2e 20 20 5e 49 74 20 69  itecture.  ^It i
11630 73 20 68 61 72 6d 6c 65 73 73 2c 20 61 70 61 72  s harmless, apar
11640 74 20 66 72 6f 6d 20 74 68 65 20 77 61 73 74 65  t from the waste
11650 64 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74 6f 20  d memory,.** to 
11660 6d 61 6b 65 20 73 7a 20 61 20 6c 69 74 74 6c 65  make sz a little
11670 20 74 6f 6f 20 6c 61 72 67 65 2e 20 20 54 68 65   too large.  The
11680 20 66 69 72 73 74 0a 2a 2a 20 61 72 67 75 6d 65   first.** argume
11690 6e 74 20 73 68 6f 75 6c 64 20 70 6f 69 6e 74 20  nt should point 
116a0 74 6f 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e  to an allocation
116b0 20 6f 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a   of at least sz*
116c0 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72  N bytes of memor
116d0 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69  y..** ^SQLite wi
116e0 6c 6c 20 75 73 65 20 74 68 65 20 6d 65 6d 6f 72  ll use the memor
116f0 79 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68  y provided by th
11700 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
11710 20 74 6f 20 73 61 74 69 73 66 79 20 69 74 73 0a   to satisfy its.
11720 2a 2a 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 20  ** memory needs 
11730 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 4e 20  for the first N 
11740 70 61 67 65 73 20 74 68 61 74 20 69 74 20 61 64  pages that it ad
11750 64 73 20 74 6f 20 63 61 63 68 65 2e 20 20 5e 49  ds to cache.  ^I
11760 66 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  f additional.** 
11770 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72  page cache memor
11780 79 20 69 73 20 6e 65 65 64 65 64 20 62 65 79 6f  y is needed beyo
11790 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f 76 69  nd what is provi
117a0 64 65 64 20 62 79 20 74 68 69 73 20 6f 70 74 69  ded by this opti
117b0 6f 6e 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69  on, then.** SQLi
117c0 74 65 20 67 6f 65 73 20 74 6f 20 5b 73 71 6c 69  te goes to [sqli
117d0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 66 6f  te3_malloc()] fo
117e0 72 20 74 68 65 20 61 64 64 69 74 69 6f 6e 61 6c  r the additional
117f0 20 73 74 6f 72 61 67 65 20 73 70 61 63 65 2e 0a   storage space..
11800 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65 72 20 69  ** The pointer i
11810 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  n the first argu
11820 6d 65 6e 74 20 6d 75 73 74 0a 2a 2a 20 62 65 20  ment must.** be 
11830 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d  aligned to an 8-
11840 62 79 74 65 20 62 6f 75 6e 64 61 72 79 20 6f 72  byte boundary or
11850 20 73 75 62 73 65 71 75 65 6e 74 20 62 65 68 61   subsequent beha
11860 76 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 0a 2a  vior of SQLite.*
11870 2a 20 77 69 6c 6c 20 62 65 20 75 6e 64 65 66 69  * will be undefi
11880 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ned.</dd>.**.** 
11890 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
118a0 48 45 41 50 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  HEAP]] <dt>SQLIT
118b0 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3c 2f 64  E_CONFIG_HEAP</d
118c0 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73  t>.** <dd> ^This
118d0 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65   option specifie
118e0 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72  s a static memor
118f0 79 20 62 75 66 66 65 72 20 74 68 61 74 20 53 51  y buffer that SQ
11900 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a  Lite will use.**
11910 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20   for all of its 
11920 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 61  dynamic memory a
11930 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 20  llocation needs 
11940 62 65 79 6f 6e 64 20 74 68 6f 73 65 20 70 72 6f  beyond those pro
11950 76 69 64 65 64 0a 2a 2a 20 66 6f 72 20 62 79 20  vided.** for by 
11960 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
11970 43 52 41 54 43 48 5d 20 61 6e 64 20 5b 53 51 4c  CRATCH] and [SQL
11980 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43  ITE_CONFIG_PAGEC
11990 41 43 48 45 5d 2e 0a 2a 2a 20 54 68 65 72 65 20  ACHE]..** There 
119a0 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65  are three argume
119b0 6e 74 73 3a 20 41 6e 20 38 2d 62 79 74 65 20 61  nts: An 8-byte a
119c0 6c 69 67 6e 65 64 20 70 6f 69 6e 74 65 72 20 74  ligned pointer t
119d0 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c 0a 2a 2a  o the memory,.**
119e0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
119f0 79 74 65 73 20 69 6e 20 74 68 65 20 6d 65 6d 6f  ytes in the memo
11a00 72 79 20 62 75 66 66 65 72 2c 20 61 6e 64 20 74  ry buffer, and t
11a10 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63  he minimum alloc
11a20 61 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a 2a 20 5e  ation size..** ^
11a30 49 66 20 74 68 65 20 66 69 72 73 74 20 70 6f 69  If the first poi
11a40 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79  nter (the memory
11a50 20 70 6f 69 6e 74 65 72 29 20 69 73 20 4e 55 4c   pointer) is NUL
11a60 4c 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 72  L, then SQLite r
11a70 65 76 65 72 74 73 0a 2a 2a 20 74 6f 20 75 73 69  everts.** to usi
11a80 6e 67 20 69 74 73 20 64 65 66 61 75 6c 74 20 6d  ng its default m
11a90 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20  emory allocator 
11aa0 28 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c  (the system mall
11ab0 6f 63 28 29 20 69 6d 70 6c 65 6d 65 6e 74 61 74  oc() implementat
11ac0 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f 69 6e 67  ion),.** undoing
11ad0 20 61 6e 79 20 70 72 69 6f 72 20 69 6e 76 6f 63   any prior invoc
11ae0 61 74 69 6f 6e 20 6f 66 20 5b 53 51 4c 49 54 45  ation of [SQLITE
11af0 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 2e  _CONFIG_MALLOC].
11b00 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 6d 65 6d    ^If the.** mem
11b10 6f 72 79 20 70 6f 69 6e 74 65 72 20 69 73 20 6e  ory pointer is n
11b20 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 65 69 74 68  ot NULL and eith
11b30 65 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c  er [SQLITE_ENABL
11b40 45 5f 4d 45 4d 53 59 53 33 5d 20 6f 72 0a 2a 2a  E_MEMSYS3] or.**
11b50 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f   [SQLITE_ENABLE_
11b60 4d 45 4d 53 59 53 35 5d 20 61 72 65 20 64 65 66  MEMSYS5] are def
11b70 69 6e 65 64 2c 20 74 68 65 6e 20 74 68 65 20 61  ined, then the a
11b80 6c 74 65 72 6e 61 74 69 76 65 20 6d 65 6d 6f 72  lternative memor
11b90 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 20 69  y.** allocator i
11ba0 73 20 65 6e 67 61 67 65 64 20 74 6f 20 68 61 6e  s engaged to han
11bb0 64 6c 65 20 61 6c 6c 20 6f 66 20 53 51 4c 69 74  dle all of SQLit
11bc0 65 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  es memory alloca
11bd0 74 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a 2a 20 54  tion needs..** T
11be0 68 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65 72  he first pointer
11bf0 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69   (the memory poi
11c00 6e 74 65 72 29 20 6d 75 73 74 20 62 65 20 61 6c  nter) must be al
11c10 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79  igned to an 8-by
11c20 74 65 0a 2a 2a 20 62 6f 75 6e 64 61 72 79 20 6f  te.** boundary o
11c30 72 20 73 75 62 73 65 71 75 65 6e 74 20 62 65 68  r subsequent beh
11c40 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 20  avior of SQLite 
11c50 77 69 6c 6c 20 62 65 20 75 6e 64 65 66 69 6e 65  will be undefine
11c60 64 2e 0a 2a 2a 20 54 68 65 20 6d 69 6e 69 6d 75  d..** The minimu
11c70 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a  m allocation siz
11c80 65 20 69 73 20 63 61 70 70 65 64 20 61 74 20 32  e is capped at 2
11c90 2a 2a 31 32 2e 20 52 65 61 73 6f 6e 61 62 6c 65  **12. Reasonable
11ca0 20 76 61 6c 75 65 73 0a 2a 2a 20 66 6f 72 20 74   values.** for t
11cb0 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63  he minimum alloc
11cc0 61 74 69 6f 6e 20 73 69 7a 65 20 61 72 65 20 32  ation size are 2
11cd0 2a 2a 35 20 74 68 72 6f 75 67 68 20 32 2a 2a 38  **5 through 2**8
11ce0 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  .</dd>.**.** [[S
11cf0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54  QLITE_CONFIG_MUT
11d00 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  EX]] <dt>SQLITE_
11d10 43 4f 4e 46 49 47 5f 4d 55 54 45 58 3c 2f 64 74  CONFIG_MUTEX</dt
11d20 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73  >.** <dd> ^(This
11d30 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
11d40 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
11d50 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74  which is a point
11d60 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74  er to an.** inst
11d70 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c  ance of the [sql
11d80 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
11d90 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20  ds] structure.  
11da0 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65  The argument spe
11db0 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e  cifies.** altern
11dc0 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20  ative low-level 
11dd0 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20 74  mutex routines t
11de0 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61  o be used in pla
11df0 63 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 20  ce.** the mutex 
11e00 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69  routines built i
11e10 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 20 5e  nto SQLite.)^  ^
11e20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63  SQLite makes a c
11e30 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f  opy of the.** co
11e40 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71  ntent of the [sq
11e50 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68  lite3_mutex_meth
11e60 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 20 62  ods] structure b
11e70 65 66 6f 72 65 20 74 68 65 20 63 61 6c 6c 20 74  efore the call t
11e80 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  o.** [sqlite3_co
11e90 6e 66 69 67 28 29 5d 20 72 65 74 75 72 6e 73 2e  nfig()] returns.
11ea0 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63   ^If SQLite is c
11eb0 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
11ec0 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
11ed0 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f  ADSAFE | SQLITE_
11ee0 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f  THREADSAFE=0] co
11ef0 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
11f00 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e  n then.** the en
11f10 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75  tire mutexing su
11f20 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74  bsystem is omitt
11f30 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c  ed from the buil
11f40 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c  d and hence call
11f50 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  s to.** [sqlite3
11f60 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20  _config()] with 
11f70 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  the SQLITE_CONFI
11f80 47 5f 4d 55 54 45 58 20 63 6f 6e 66 69 67 75 72  G_MUTEX configur
11f90 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c  ation option wil
11fa0 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c  l.** return [SQL
11fb0 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e  ITE_ERROR].</dd>
11fc0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
11fd0 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 5d  CONFIG_GETMUTEX]
11fe0 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
11ff0 46 49 47 5f 47 45 54 4d 55 54 45 58 3c 2f 64 74  FIG_GETMUTEX</dt
12000 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73  >.** <dd> ^(This
12010 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
12020 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
12030 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74  which is a point
12040 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74  er to an.** inst
12050 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c  ance of the [sql
12060 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
12070 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20  ds] structure.  
12080 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  The.** [sqlite3_
12090 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a  mutex_methods].*
120a0 2a 20 73 74 72 75 63 74 75 72 65 20 69 73 20 66  * structure is f
120b0 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 63  illed with the c
120c0 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64  urrently defined
120d0 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 2e   mutex routines.
120e0 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f  )^.** This optio
120f0 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  n can be used to
12100 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65   overload the de
12110 66 61 75 6c 74 20 6d 75 74 65 78 20 61 6c 6c 6f  fault mutex allo
12120 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e  cation.** routin
12130 65 73 20 77 69 74 68 20 61 20 77 72 61 70 70 65  es with a wrappe
12140 72 20 75 73 65 64 20 74 6f 20 74 72 61 63 6b 20  r used to track 
12150 6d 75 74 65 78 20 75 73 61 67 65 20 66 6f 72 20  mutex usage for 
12160 70 65 72 66 6f 72 6d 61 6e 63 65 0a 2a 2a 20 70  performance.** p
12170 72 6f 66 69 6c 69 6e 67 20 6f 72 20 74 65 73 74  rofiling or test
12180 69 6e 67 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65  ing, for example
12190 2e 20 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69  .   ^If SQLite i
121a0 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a  s compiled with.
121b0 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  ** the [SQLITE_T
121c0 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49  HREADSAFE | SQLI
121d0 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d  TE_THREADSAFE=0]
121e0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
121f0 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65  tion then.** the
12200 20 65 6e 74 69 72 65 20 6d 75 74 65 78 69 6e 67   entire mutexing
12210 20 73 75 62 73 79 73 74 65 6d 20 69 73 20 6f 6d   subsystem is om
12220 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 62  itted from the b
12230 75 69 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 63  uild and hence c
12240 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  alls to.** [sqli
12250 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69  te3_config()] wi
12260 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f  th the SQLITE_CO
12270 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20 63 6f  NFIG_GETMUTEX co
12280 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
12290 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72  on will.** retur
122a0 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  n [SQLITE_ERROR]
122b0 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  .</dd>.**.** [[S
122c0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f  QLITE_CONFIG_LOO
122d0 4b 41 53 49 44 45 5d 5d 20 3c 64 74 3e 53 51 4c  KASIDE]] <dt>SQL
122e0 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  ITE_CONFIG_LOOKA
122f0 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  SIDE</dt>.** <dd
12300 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20  > ^(This option 
12310 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65  takes two argume
12320 6e 74 73 20 74 68 61 74 20 64 65 74 65 72 6d 69  nts that determi
12330 6e 65 20 74 68 65 20 64 65 66 61 75 6c 74 0a 2a  ne the default.*
12340 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  * memory allocat
12350 69 6f 6e 20 66 6f 72 20 74 68 65 20 6c 6f 6f 6b  ion for the look
12360 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  aside memory all
12370 6f 63 61 74 6f 72 20 6f 6e 20 65 61 63 68 0a 2a  ocator on each.*
12380 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
12390 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20 66 69  ection].  The fi
123a0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20  rst argument is 
123b0 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65  the.** size of e
123c0 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75  ach lookaside bu
123d0 66 66 65 72 20 73 6c 6f 74 20 61 6e 64 20 74 68  ffer slot and th
123e0 65 20 73 65 63 6f 6e 64 20 69 73 20 74 68 65 20  e second is the 
123f0 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f  number of.** slo
12400 74 73 20 61 6c 6c 6f 63 61 74 65 64 20 74 6f 20  ts allocated to 
12410 65 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f  each database co
12420 6e 6e 65 63 74 69 6f 6e 2e 29 5e 20 20 5e 28 54  nnection.)^  ^(T
12430 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20  his option sets 
12440 74 68 65 0a 2a 2a 20 3c 69 3e 64 65 66 61 75 6c  the.** <i>defaul
12450 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 73 69 64 65 20  t</i> lookaside 
12460 73 69 7a 65 2e 20 54 68 65 20 5b 53 51 4c 49 54  size. The [SQLIT
12470 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  E_DBCONFIG_LOOKA
12480 53 49 44 45 5d 0a 2a 2a 20 76 65 72 62 20 74 6f  SIDE].** verb to
12490 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e   [sqlite3_db_con
124a0 66 69 67 28 29 5d 20 63 61 6e 20 62 65 20 75 73  fig()] can be us
124b0 65 64 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65  ed to change the
124c0 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 63 6f   lookaside.** co
124d0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 6e 20 69  nfiguration on i
124e0 6e 64 69 76 69 64 75 61 6c 20 63 6f 6e 6e 65 63  ndividual connec
124f0 74 69 6f 6e 73 2e 29 5e 20 3c 2f 64 64 3e 0a 2a  tions.)^ </dd>.*
12500 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
12510 4e 46 49 47 5f 50 43 41 43 48 45 32 5d 5d 20 3c  NFIG_PCACHE2]] <
12520 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
12530 5f 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a  _PCACHE2</dt>.**
12540 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74   <dd> ^(This opt
12550 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
12560 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  le argument whic
12570 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  h is a pointer t
12580 6f 0a 2a 2a 20 61 6e 20 5b 73 71 6c 69 74 65 33  o.** an [sqlite3
12590 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32  _pcache_methods2
125a0 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 69 73 20  ] object.  This 
125b0 6f 62 6a 65 63 74 20 73 70 65 63 69 66 69 65 73  object specifies
125c0 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 0a 2a   the interface.*
125d0 2a 20 74 6f 20 61 20 63 75 73 74 6f 6d 20 70 61  * to a custom pa
125e0 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65  ge cache impleme
125f0 6e 74 61 74 69 6f 6e 2e 29 5e 20 20 5e 53 51 4c  ntation.)^  ^SQL
12600 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79  ite makes a copy
12610 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 62 6a 65 63   of the.** objec
12620 74 20 61 6e 64 20 75 73 65 73 20 69 74 20 66 6f  t and uses it fo
12630 72 20 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d  r page cache mem
12640 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e  ory allocations.
12650 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
12660 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50  LITE_CONFIG_GETP
12670 43 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53 51 4c  CACHE2]] <dt>SQL
12680 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43  ITE_CONFIG_GETPC
12690 41 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ACHE2</dt>.** <d
126a0 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e  d> ^(This option
126b0 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
126c0 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
126d0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
126e0 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 63  n.** [sqlite3_pc
126f0 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f  ache_methods2] o
12700 62 6a 65 63 74 2e 20 20 53 51 4c 69 74 65 20 63  bject.  SQLite c
12710 6f 70 69 65 73 20 6f 66 20 74 68 65 20 63 75 72  opies of the cur
12720 72 65 6e 74 0a 2a 2a 20 70 61 67 65 20 63 61 63  rent.** page cac
12730 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
12740 6e 20 69 6e 74 6f 20 74 68 61 74 20 6f 62 6a 65  n into that obje
12750 63 74 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ct.)^ </dd>.**.*
12760 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
12770 47 5f 4c 4f 47 5d 5d 20 3c 64 74 3e 53 51 4c 49  G_LOG]] <dt>SQLI
12780 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 3c 2f 64  TE_CONFIG_LOG</d
12790 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20  t>.** <dd> ^The 
127a0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
127b0 47 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74  G option takes t
127c0 77 6f 20 61 72 67 75 6d 65 6e 74 73 3a 20 61 20  wo arguments: a 
127d0 70 6f 69 6e 74 65 72 20 74 6f 20 61 0a 2a 2a 20  pointer to a.** 
127e0 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20  function with a 
127f0 63 61 6c 6c 20 73 69 67 6e 61 74 75 72 65 20 6f  call signature o
12800 66 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c  f void(*)(void*,
12810 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29  int,const char*)
12820 2c 20 0a 2a 2a 20 61 6e 64 20 61 20 70 6f 69 6e  , .** and a poin
12830 74 65 72 20 74 6f 20 76 6f 69 64 2e 20 5e 49 66  ter to void. ^If
12840 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 70 6f   the function po
12850 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c  inter is not NUL
12860 4c 2c 20 69 74 20 69 73 0a 2a 2a 20 69 6e 76 6f  L, it is.** invo
12870 6b 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ked by [sqlite3_
12880 6c 6f 67 28 29 5d 20 74 6f 20 70 72 6f 63 65 73  log()] to proces
12890 73 20 65 61 63 68 20 6c 6f 67 67 69 6e 67 20 65  s each logging e
128a0 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a  vent.  ^If the.*
128b0 2a 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74  * function point
128c0 65 72 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 20  er is NULL, the 
128d0 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20  [sqlite3_log()] 
128e0 69 6e 74 65 72 66 61 63 65 20 62 65 63 6f 6d 65  interface become
128f0 73 20 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a 20 5e 54  s a no-op..** ^T
12900 68 65 20 76 6f 69 64 20 70 6f 69 6e 74 65 72 20  he void pointer 
12910 74 68 61 74 20 69 73 20 74 68 65 20 73 65 63 6f  that is the seco
12920 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 53  nd argument to S
12930 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47  QLITE_CONFIG_LOG
12940 20 69 73 0a 2a 2a 20 70 61 73 73 65 64 20 74 68   is.** passed th
12950 72 6f 75 67 68 20 61 73 20 74 68 65 20 66 69 72  rough as the fir
12960 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
12970 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
12980 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a  defined logger.*
12990 2a 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 6e 65  * function whene
129a0 76 65 72 20 74 68 61 74 20 66 75 6e 63 74 69 6f  ver that functio
129b0 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e  n is invoked.  ^
129c0 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
129d0 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 6c  eter to.** the l
129e0 6f 67 67 65 72 20 66 75 6e 63 74 69 6f 6e 20 69  ogger function i
129f0 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
12a00 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
12a10 74 6f 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  to the correspon
12a20 64 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ding.** [sqlite3
12a30 5f 6c 6f 67 28 29 5d 20 63 61 6c 6c 20 61 6e 64  _log()] call and
12a40 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74 6f 20   is intended to 
12a50 62 65 20 61 20 5b 72 65 73 75 6c 74 20 63 6f 64  be a [result cod
12a60 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 78 74  e] or an.** [ext
12a70 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
12a80 65 5d 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20  e].  ^The third 
12a90 70 61 72 61 6d 65 74 65 72 20 70 61 73 73 65 64  parameter passed
12aa0 20 74 6f 20 74 68 65 20 6c 6f 67 67 65 72 20 69   to the logger i
12ab0 73 0a 2a 2a 20 6c 6f 67 20 6d 65 73 73 61 67 65  s.** log message
12ac0 20 61 66 74 65 72 20 66 6f 72 6d 61 74 74 69 6e   after formattin
12ad0 67 20 76 69 61 20 5b 73 71 6c 69 74 65 33 5f 73  g via [sqlite3_s
12ae0 6e 70 72 69 6e 74 66 28 29 5d 2e 0a 2a 2a 20 54  nprintf()]..** T
12af0 68 65 20 53 51 4c 69 74 65 20 6c 6f 67 67 69 6e  he SQLite loggin
12b00 67 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e  g interface is n
12b10 6f 74 20 72 65 65 6e 74 72 61 6e 74 3b 20 74 68  ot reentrant; th
12b20 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f  e logger functio
12b30 6e 0a 2a 2a 20 73 75 70 70 6c 69 65 64 20 62 79  n.** supplied by
12b40 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
12b50 20 6d 75 73 74 20 6e 6f 74 20 69 6e 76 6f 6b 65   must not invoke
12b60 20 61 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 65   any SQLite inte
12b70 72 66 61 63 65 2e 0a 2a 2a 20 49 6e 20 61 20 6d  rface..** In a m
12b80 75 6c 74 69 2d 74 68 72 65 61 64 65 64 20 61 70  ulti-threaded ap
12b90 70 6c 69 63 61 74 69 6f 6e 2c 20 74 68 65 20 61  plication, the a
12ba0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
12bb0 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e  ed logger.** fun
12bc0 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 74 68  ction must be th
12bd0 72 65 61 64 73 61 66 65 2e 20 3c 2f 64 64 3e 0a  readsafe. </dd>.
12be0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
12bf0 4f 4e 46 49 47 5f 55 52 49 5d 5d 20 3c 64 74 3e  ONFIG_URI]] <dt>
12c00 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52  SQLITE_CONFIG_UR
12c10 49 0a 2a 2a 20 3c 64 64 3e 20 54 68 69 73 20 6f  I.** <dd> This o
12c20 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
12c30 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66  ngle argument of
12c40 20 74 79 70 65 20 69 6e 74 2e 20 49 66 20 6e 6f   type int. If no
12c50 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 0a 2a 2a 20  n-zero, then.** 
12c60 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20  URI handling is 
12c70 67 6c 6f 62 61 6c 6c 79 20 65 6e 61 62 6c 65 64  globally enabled
12c80 2e 20 49 66 20 74 68 65 20 70 61 72 61 6d 65 74  . If the paramet
12c90 65 72 20 69 73 20 7a 65 72 6f 2c 20 74 68 65 6e  er is zero, then
12ca0 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 0a 2a 2a   URI handling.**
12cb0 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64 69 73   is globally dis
12cc0 61 62 6c 65 64 2e 20 49 66 20 55 52 49 20 68 61  abled. If URI ha
12cd0 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c  ndling is global
12ce0 6c 79 20 65 6e 61 62 6c 65 64 2c 20 61 6c 6c 20  ly enabled, all 
12cf0 66 69 6c 65 6e 61 6d 65 73 0a 2a 2a 20 70 61 73  filenames.** pas
12d00 73 65 64 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  sed to [sqlite3_
12d10 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65  open()], [sqlite
12d20 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 5b 73  3_open_v2()], [s
12d30 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d  qlite3_open16()]
12d40 20 6f 72 0a 2a 2a 20 73 70 65 63 69 66 69 65 64   or.** specified
12d50 20 61 73 20 70 61 72 74 20 6f 66 20 5b 41 54 54   as part of [ATT
12d60 41 43 48 5d 20 63 6f 6d 6d 61 6e 64 73 20 61 72  ACH] commands ar
12d70 65 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  e interpreted as
12d80 20 55 52 49 73 2c 20 72 65 67 61 72 64 6c 65 73   URIs, regardles
12d90 73 0a 2a 2a 20 6f 66 20 77 68 65 74 68 65 72 20  s.** of whether 
12da0 6f 72 20 6e 6f 74 20 74 68 65 20 5b 53 51 4c 49  or not the [SQLI
12db0 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61  TE_OPEN_URI] fla
12dc0 67 20 69 73 20 73 65 74 20 77 68 65 6e 20 74 68  g is set when th
12dd0 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f  e database.** co
12de0 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e  nnection is open
12df0 65 64 2e 20 49 66 20 69 74 20 69 73 20 67 6c 6f  ed. If it is glo
12e00 62 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 2c 20  bally disabled, 
12e10 66 69 6c 65 6e 61 6d 65 73 20 61 72 65 0a 2a 2a  filenames are.**
12e20 20 6f 6e 6c 79 20 69 6e 74 65 72 70 72 65 74 65   only interprete
12e30 64 20 61 73 20 55 52 49 73 20 69 66 20 74 68 65  d as URIs if the
12e40 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49   SQLITE_OPEN_URI
12e50 20 66 6c 61 67 20 69 73 20 73 65 74 20 77 68 65   flag is set whe
12e60 6e 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  n the.** databas
12e70 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
12e80 6f 70 65 6e 65 64 2e 20 42 79 20 64 65 66 61 75  opened. By defau
12e90 6c 74 2c 20 55 52 49 20 68 61 6e 64 6c 69 6e 67  lt, URI handling
12ea0 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20   is globally.** 
12eb0 64 69 73 61 62 6c 65 64 2e 20 54 68 65 20 64 65  disabled. The de
12ec0 66 61 75 6c 74 20 76 61 6c 75 65 20 6d 61 79 20  fault value may 
12ed0 62 65 20 63 68 61 6e 67 65 64 20 62 79 20 63 6f  be changed by co
12ee0 6d 70 69 6c 69 6e 67 20 77 69 74 68 20 74 68 65  mpiling with the
12ef0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f  .** [SQLITE_USE_
12f00 55 52 49 5d 20 73 79 6d 62 6f 6c 20 64 65 66 69  URI] symbol defi
12f10 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  ned..**.** [[SQL
12f20 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48  ITE_CONFIG_PCACH
12f30 45 5d 5d 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  E]] [[SQLITE_CON
12f40 46 49 47 5f 47 45 54 50 43 41 43 48 45 5d 5d 0a  FIG_GETPCACHE]].
12f50 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
12f60 4e 46 49 47 5f 50 43 41 43 48 45 20 61 6e 64 20  NFIG_PCACHE and 
12f70 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
12f80 54 50 43 41 43 48 45 0a 2a 2a 20 3c 64 64 3e 20  TPCACHE.** <dd> 
12f90 54 68 65 73 65 20 6f 70 74 69 6f 6e 73 20 61 72  These options ar
12fa0 65 20 6f 62 73 6f 6c 65 74 65 20 61 6e 64 20 73  e obsolete and s
12fb0 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75 73 65  hould not be use
12fc0 64 20 62 79 20 6e 65 77 20 63 6f 64 65 2e 0a 2a  d by new code..*
12fd0 2a 20 54 68 65 79 20 61 72 65 20 72 65 74 61 69  * They are retai
12fe0 6e 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64  ned for backward
12ff0 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20  s compatibility 
13000 62 75 74 20 61 72 65 20 6e 6f 77 20 6e 6f 2d 6f  but are now no-o
13010 70 73 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a  ps..** </dl>.*/.
13020 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
13030 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
13040 41 44 20 20 31 20 20 2f 2a 20 6e 69 6c 20 2a 2f  AD  1  /* nil */
13050 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
13060 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45  CONFIG_MULTITHRE
13070 41 44 20 20 20 32 20 20 2f 2a 20 6e 69 6c 20 2a  AD   2  /* nil *
13080 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
13090 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a  _CONFIG_SERIALIZ
130a0 45 44 20 20 20 20 33 20 20 2f 2a 20 6e 69 6c 20  ED    3  /* nil 
130b0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
130c0 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20  E_CONFIG_MALLOC 
130d0 20 20 20 20 20 20 20 34 20 20 2f 2a 20 73 71 6c         4  /* sql
130e0 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
130f0 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
13100 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41  ITE_CONFIG_GETMA
13110 4c 4c 4f 43 20 20 20 20 20 35 20 20 2f 2a 20 73  LLOC     5  /* s
13120 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
13130 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ds* */.#define S
13140 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52  QLITE_CONFIG_SCR
13150 41 54 43 48 20 20 20 20 20 20 20 36 20 20 2f 2a  ATCH       6  /*
13160 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20   void*, int sz, 
13170 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65  int N */.#define
13180 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
13190 41 47 45 43 41 43 48 45 20 20 20 20 20 37 20 20  AGECACHE     7  
131a0 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a  /* void*, int sz
131b0 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69  , int N */.#defi
131c0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
131d0 5f 48 45 41 50 20 20 20 20 20 20 20 20 20 20 38  _HEAP          8
131e0 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20    /* void*, int 
131f0 6e 42 79 74 65 2c 20 69 6e 74 20 6d 69 6e 20 2a  nByte, int min *
13200 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
13210 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55  _CONFIG_MEMSTATU
13220 53 20 20 20 20 20 39 20 20 2f 2a 20 62 6f 6f 6c  S     9  /* bool
13230 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ean */.#define S
13240 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54  QLITE_CONFIG_MUT
13250 45 58 20 20 20 20 20 20 20 20 31 30 20 20 2f 2a  EX        10  /*
13260 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d   sqlite3_mutex_m
13270 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69  ethods* */.#defi
13280 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
13290 5f 47 45 54 4d 55 54 45 58 20 20 20 20 20 31 31  _GETMUTEX     11
132a0 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74    /* sqlite3_mut
132b0 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 2f  ex_methods* */./
132c0 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 53 51 4c  * previously SQL
132d0 49 54 45 5f 43 4f 4e 46 49 47 5f 43 48 55 4e 4b  ITE_CONFIG_CHUNK
132e0 41 4c 4c 4f 43 20 31 32 20 77 68 69 63 68 20 69  ALLOC 12 which i
132f0 73 20 6e 6f 77 20 75 6e 75 73 65 64 2e 20 2a 2f  s now unused. */
13300 20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45   .#define SQLITE
13310 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  _CONFIG_LOOKASID
13320 45 20 20 20 20 31 33 20 20 2f 2a 20 69 6e 74 20  E    13  /* int 
13330 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  int */.#define S
13340 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
13350 43 48 45 20 20 20 20 20 20 20 31 34 20 20 2f 2a  CHE       14  /*
13360 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 6e   no-op */.#defin
13370 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
13380 47 45 54 50 43 41 43 48 45 20 20 20 20 31 35 20  GETPCACHE    15 
13390 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65   /* no-op */.#de
133a0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
133b0 49 47 5f 4c 4f 47 20 20 20 20 20 20 20 20 20 20  IG_LOG          
133c0 31 36 20 20 2f 2a 20 78 46 75 6e 63 2c 20 76 6f  16  /* xFunc, vo
133d0 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  id* */.#define S
133e0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49  QLITE_CONFIG_URI
133f0 20 20 20 20 20 20 20 20 20 20 31 37 20 20 2f 2a            17  /*
13400 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20   int */.#define 
13410 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
13420 41 43 48 45 32 20 20 20 20 20 20 31 38 20 20 2f  ACHE2      18  /
13430 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65  * sqlite3_pcache
13440 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23 64  _methods2* */.#d
13450 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
13460 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 20 20  FIG_GETPCACHE2  
13470 20 31 39 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f   19  /* sqlite3_
13480 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 2a  pcache_methods2*
13490 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
134a0 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f  REF: Database Co
134b0 6e 6e 65 63 74 69 6f 6e 20 43 6f 6e 66 69 67 75  nnection Configu
134c0 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a  ration Options.*
134d0 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74  *.** These const
134e0 61 6e 74 73 20 61 72 65 20 74 68 65 20 61 76 61  ants are the ava
134f0 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63  ilable integer c
13500 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
13510 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e  ions that.** can
13520 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68   be passed as th
13530 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
13540 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  t to the [sqlite
13550 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69  3_db_config()] i
13560 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
13570 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  New configuratio
13580 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65  n options may be
13590 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65   added in future
135a0 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c   releases of SQL
135b0 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67  ite..** Existing
135c0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
135d0 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20  ptions might be 
135e0 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41  discontinued.  A
135f0 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73  pplications.** s
13600 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20  hould check the 
13610 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d  return code from
13620 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e   [sqlite3_db_con
13630 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73  fig()] to make s
13640 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  ure that.** the 
13650 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 5e 54  call worked.  ^T
13660 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63  he [sqlite3_db_c
13670 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61  onfig()] interfa
13680 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61  ce will return a
13690 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72  .** non-zero [er
136a0 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64  ror code] if a d
136b0 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75  iscontinued or u
136c0 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69  nsupported confi
136d0 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a  guration option.
136e0 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a  ** is invoked..*
136f0 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74  *.** <dl>.** <dt
13700 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47  >SQLITE_DBCONFIG
13710 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a  _LOOKASIDE</dt>.
13720 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70  ** <dd> ^This op
13730 74 69 6f 6e 20 74 61 6b 65 73 20 74 68 72 65 65  tion takes three
13740 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75   additional argu
13750 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 65 72  ments that deter
13760 6d 69 6e 65 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f  mine the .** [lo
13770 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61  okaside memory a
13780 6c 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e 66 69 67  llocator] config
13790 75 72 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 20  uration for the 
137a0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
137b0 74 69 6f 6e 5d 2e 0a 2a 2a 20 5e 54 68 65 20 66  tion]..** ^The f
137c0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 28 74  irst argument (t
137d0 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
137e0 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64  er to [sqlite3_d
137f0 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 73 20 61  b_config()] is a
13800 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  .** pointer to a
13810 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74   memory buffer t
13820 6f 20 75 73 65 20 66 6f 72 20 6c 6f 6f 6b 61 73  o use for lookas
13830 69 64 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e  ide memory..** ^
13840 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
13850 6e 74 20 61 66 74 65 72 20 74 68 65 20 53 51 4c  nt after the SQL
13860 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
13870 4b 41 53 49 44 45 20 76 65 72 62 0a 2a 2a 20 6d  KASIDE verb.** m
13880 61 79 20 62 65 20 4e 55 4c 4c 20 69 6e 20 77 68  ay be NULL in wh
13890 69 63 68 20 63 61 73 65 20 53 51 4c 69 74 65 20  ich case SQLite 
138a0 77 69 6c 6c 20 61 6c 6c 6f 63 61 74 65 20 74 68  will allocate th
138b0 65 0a 2a 2a 20 6c 6f 6f 6b 61 73 69 64 65 20 62  e.** lookaside b
138c0 75 66 66 65 72 20 69 74 73 65 6c 66 20 75 73 69  uffer itself usi
138d0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ng [sqlite3_mall
138e0 6f 63 28 29 5d 2e 20 5e 54 68 65 20 73 65 63 6f  oc()]. ^The seco
138f0 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  nd argument is t
13900 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61  he.** size of ea
13910 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66  ch lookaside buf
13920 66 65 72 20 73 6c 6f 74 2e 20 20 5e 54 68 65 20  fer slot.  ^The 
13930 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69  third argument i
13940 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a  s the number of.
13950 2a 2a 20 73 6c 6f 74 73 2e 20 20 54 68 65 20 73  ** slots.  The s
13960 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66 65  ize of the buffe
13970 72 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61  r in the first a
13980 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20  rgument must be 
13990 67 72 65 61 74 65 72 20 74 68 61 6e 0a 2a 2a 20  greater than.** 
139a0 6f 72 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20  or equal to the 
139b0 70 72 6f 64 75 63 74 20 6f 66 20 74 68 65 20 73  product of the s
139c0 65 63 6f 6e 64 20 61 6e 64 20 74 68 69 72 64 20  econd and third 
139d0 61 72 67 75 6d 65 6e 74 73 2e 20 20 54 68 65 20  arguments.  The 
139e0 62 75 66 66 65 72 0a 2a 2a 20 6d 75 73 74 20 62  buffer.** must b
139f0 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20  e aligned to an 
13a00 38 2d 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2e  8-byte boundary.
13a10 20 20 5e 49 66 20 74 68 65 20 73 65 63 6f 6e 64    ^If the second
13a20 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
13a30 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
13a40 4c 4f 4f 4b 41 53 49 44 45 20 69 73 20 6e 6f 74  LOOKASIDE is not
13a50 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38   a multiple of 8
13a60 2c 20 69 74 20 69 73 20 69 6e 74 65 72 6e 61 6c  , it is internal
13a70 6c 79 0a 2a 2a 20 72 6f 75 6e 64 65 64 20 64 6f  ly.** rounded do
13a80 77 6e 20 74 6f 20 74 68 65 20 6e 65 78 74 20 73  wn to the next s
13a90 6d 61 6c 6c 65 72 20 6d 75 6c 74 69 70 6c 65 20  maller multiple 
13aa0 6f 66 20 38 2e 20 20 5e 28 54 68 65 20 6c 6f 6f  of 8.  ^(The loo
13ab0 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 0a 2a 2a  kaside memory.**
13ac0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66   configuration f
13ad0 6f 72 20 61 20 64 61 74 61 62 61 73 65 20 63 6f  or a database co
13ae0 6e 6e 65 63 74 69 6f 6e 20 63 61 6e 20 6f 6e 6c  nnection can onl
13af0 79 20 62 65 20 63 68 61 6e 67 65 64 20 77 68 65  y be changed whe
13b00 6e 20 74 68 61 74 0a 2a 2a 20 63 6f 6e 6e 65 63  n that.** connec
13b10 74 69 6f 6e 20 69 73 20 6e 6f 74 20 63 75 72 72  tion is not curr
13b20 65 6e 74 6c 79 20 75 73 69 6e 67 20 6c 6f 6f 6b  ently using look
13b30 61 73 69 64 65 20 6d 65 6d 6f 72 79 2c 20 6f 72  aside memory, or
13b40 20 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 0a   in other words.
13b50 2a 2a 20 77 68 65 6e 20 74 68 65 20 22 63 75 72  ** when the "cur
13b60 72 65 6e 74 20 76 61 6c 75 65 22 20 72 65 74 75  rent value" retu
13b70 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69  rned by.** [sqli
13b80 74 65 33 5f 64 62 5f 73 74 61 74 75 73 5d 28 44  te3_db_status](D
13b90 2c 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  ,[SQLITE_CONFIG_
13ba0 4c 4f 4f 4b 41 53 49 44 45 5d 2c 2e 2e 2e 29 20  LOOKASIDE],...) 
13bb0 69 73 20 7a 65 72 6f 2e 0a 2a 2a 20 41 6e 79 20  is zero..** Any 
13bc0 61 74 74 65 6d 70 74 20 74 6f 20 63 68 61 6e 67  attempt to chang
13bd0 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20  e the lookaside 
13be0 6d 65 6d 6f 72 79 20 63 6f 6e 66 69 67 75 72 61  memory configura
13bf0 74 69 6f 6e 20 77 68 65 6e 20 6c 6f 6f 6b 61 73  tion when lookas
13c00 69 64 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 69 73  ide.** memory is
13c10 20 69 6e 20 75 73 65 20 6c 65 61 76 65 73 20 74   in use leaves t
13c20 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  he configuration
13c30 20 75 6e 63 68 61 6e 67 65 64 20 61 6e 64 20 72   unchanged and r
13c40 65 74 75 72 6e 73 20 0a 2a 2a 20 5b 53 51 4c 49  eturns .** [SQLI
13c50 54 45 5f 42 55 53 59 5d 2e 29 5e 3c 2f 64 64 3e  TE_BUSY].)^</dd>
13c60 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
13c70 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c  E_DBCONFIG_ENABL
13c80 45 5f 46 4b 45 59 3c 2f 64 74 3e 0a 2a 2a 20 3c  E_FKEY</dt>.** <
13c90 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  dd> ^This option
13ca0 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62   is used to enab
13cb0 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 74 68  le or disable th
13cc0 65 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 66  e enforcement of
13cd0 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79  .** [foreign key
13ce0 20 63 6f 6e 73 74 72 61 69 6e 74 73 5d 2e 20 20   constraints].  
13cf0 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20  There should be 
13d00 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61  two additional a
13d10 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65  rguments..** The
13d20 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
13d30 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68  is an integer wh
13d40 69 63 68 20 69 73 20 30 20 74 6f 20 64 69 73 61  ich is 0 to disa
13d50 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65  ble FK enforceme
13d60 6e 74 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20  nt,.** positive 
13d70 74 6f 20 65 6e 61 62 6c 65 20 46 4b 20 65 6e 66  to enable FK enf
13d80 6f 72 63 65 6d 65 6e 74 20 6f 72 20 6e 65 67 61  orcement or nega
13d90 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20 46 4b  tive to leave FK
13da0 20 65 6e 66 6f 72 63 65 6d 65 6e 74 0a 2a 2a 20   enforcement.** 
13db0 75 6e 63 68 61 6e 67 65 64 2e 20 20 54 68 65 20  unchanged.  The 
13dc0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
13dd0 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
13de0 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f   an integer into
13df0 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69   which.** is wri
13e00 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69  tten 0 or 1 to i
13e10 6e 64 69 63 61 74 65 20 77 68 65 74 68 65 72 20  ndicate whether 
13e20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 69  FK enforcement i
13e30 73 20 6f 66 66 20 6f 72 20 6f 6e 0a 2a 2a 20 66  s off or on.** f
13e40 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61  ollowing this ca
13e50 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20  ll.  The second 
13e60 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65  parameter may be
13e70 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c   a NULL pointer,
13e80 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73   in.** which cas
13e90 65 20 74 68 65 20 46 4b 20 65 6e 66 6f 72 63 65  e the FK enforce
13ea0 6d 65 6e 74 20 73 65 74 74 69 6e 67 20 69 73 20  ment setting is 
13eb0 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61 63  not reported bac
13ec0 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  k. </dd>.**.** <
13ed0 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  dt>SQLITE_DBCONF
13ee0 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 45  IG_ENABLE_TRIGGE
13ef0 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  R</dt>.** <dd> ^
13f00 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75  This option is u
13f10 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72  sed to enable or
13f20 20 64 69 73 61 62 6c 65 20 5b 43 52 45 41 54 45   disable [CREATE
13f30 20 54 52 49 47 47 45 52 20 7c 20 74 72 69 67 67   TRIGGER | trigg
13f40 65 72 73 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 73  ers]..** There s
13f50 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64  hould be two add
13f60 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74  itional argument
13f70 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  s..** The first 
13f80 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69  argument is an i
13f90 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20  nteger which is 
13fa0 30 20 74 6f 20 64 69 73 61 62 6c 65 20 74 72 69  0 to disable tri
13fb0 67 67 65 72 73 2c 0a 2a 2a 20 70 6f 73 69 74 69  ggers,.** positi
13fc0 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 74 72 69  ve to enable tri
13fd0 67 67 65 72 73 20 6f 72 20 6e 65 67 61 74 69 76  ggers or negativ
13fe0 65 20 74 6f 20 6c 65 61 76 65 20 74 68 65 20 73  e to leave the s
13ff0 65 74 74 69 6e 67 20 75 6e 63 68 61 6e 67 65 64  etting unchanged
14000 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  ..** The second 
14010 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70  parameter is a p
14020 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74  ointer to an int
14030 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a  eger into which.
14040 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30 20  ** is written 0 
14050 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65  or 1 to indicate
14060 20 77 68 65 74 68 65 72 20 74 72 69 67 67 65 72   whether trigger
14070 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 6f  s are disabled o
14080 72 20 65 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c  r enabled.** fol
14090 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c  lowing this call
140a0 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  .  The second pa
140b0 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61  rameter may be a
140c0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69   NULL pointer, i
140d0 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20  n.** which case 
140e0 74 68 65 20 74 72 69 67 67 65 72 20 73 65 74 74  the trigger sett
140f0 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72  ing is not repor
14100 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a  ted back. </dd>.
14110 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23  **.** </dl>.*/.#
14120 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42  define SQLITE_DB
14130 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
14140 20 20 20 20 20 20 20 31 30 30 31 20 20 2f 2a 20         1001  /* 
14150 76 6f 69 64 2a 20 69 6e 74 20 69 6e 74 20 2a 2f  void* int int */
14160 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
14170 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f  DBCONFIG_ENABLE_
14180 46 4b 45 59 20 20 20 20 20 31 30 30 32 20 20 2f  FKEY     1002  /
14190 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64  * int int* */.#d
141a0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43  efine SQLITE_DBC
141b0 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49  ONFIG_ENABLE_TRI
141c0 47 47 45 52 20 20 31 30 30 33 20 20 2f 2a 20 69  GGER  1003  /* i
141d0 6e 74 20 69 6e 74 2a 20 2a 2f 0a 0a 0a 2f 2a 0a  nt int* */.../*.
141e0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61  ** CAPI3REF: Ena
141f0 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45  ble Or Disable E
14200 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43  xtended Result C
14210 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  odes.**.** ^The 
14220 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64  sqlite3_extended
14230 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 20  _result_codes() 
14240 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65 73 20  routine enables 
14250 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 0a  or disables the.
14260 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  ** [extended res
14270 75 6c 74 20 63 6f 64 65 73 5d 20 66 65 61 74 75  ult codes] featu
14280 72 65 20 6f 66 20 53 51 4c 69 74 65 2e 20 5e 54  re of SQLite. ^T
14290 68 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 75  he extended resu
142a0 6c 74 0a 2a 2a 20 63 6f 64 65 73 20 61 72 65 20  lt.** codes are 
142b0 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61  disabled by defa
142c0 75 6c 74 20 66 6f 72 20 68 69 73 74 6f 72 69 63  ult for historic
142d0 61 6c 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  al compatibility
142e0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
142f0 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74  _extended_result
14300 5f 63 6f 64 65 73 28 73 71 6c 69 74 65 33 2a 2c  _codes(sqlite3*,
14310 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a   int onoff);../*
14320 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 61  .** CAPI3REF: La
14330 73 74 20 49 6e 73 65 72 74 20 52 6f 77 69 64 0a  st Insert Rowid.
14340 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20 65 6e 74 72  **.** ^Each entr
14350 79 20 69 6e 20 61 6e 20 53 51 4c 69 74 65 20 74  y in an SQLite t
14360 61 62 6c 65 20 68 61 73 20 61 20 75 6e 69 71 75  able has a uniqu
14370 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 0a  e 64-bit signed.
14380 2a 2a 20 69 6e 74 65 67 65 72 20 6b 65 79 20 63  ** integer key c
14390 61 6c 6c 65 64 20 74 68 65 20 5b 52 4f 57 49 44  alled the [ROWID
143a0 20 7c 20 22 72 6f 77 69 64 22 5d 2e 20 5e 54 68   | "rowid"]. ^Th
143b0 65 20 72 6f 77 69 64 20 69 73 20 61 6c 77 61 79  e rowid is alway
143c0 73 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 61  s available.** a
143d0 73 20 61 6e 20 75 6e 64 65 63 6c 61 72 65 64 20  s an undeclared 
143e0 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f 57  column named ROW
143f0 49 44 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f 57  ID, OID, or _ROW
14400 49 44 5f 20 61 73 20 6c 6f 6e 67 20 61 73 20 74  ID_ as long as t
14410 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 61 72  hose.** names ar
14420 65 20 6e 6f 74 20 61 6c 73 6f 20 75 73 65 64 20  e not also used 
14430 62 79 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65  by explicitly de
14440 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 73 2e 20  clared columns. 
14450 5e 49 66 0a 2a 2a 20 74 68 65 20 74 61 62 6c 65  ^If.** the table
14460 20 68 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66   has a column of
14470 20 74 79 70 65 20 5b 49 4e 54 45 47 45 52 20 50   type [INTEGER P
14480 52 49 4d 41 52 59 20 4b 45 59 5d 20 74 68 65 6e  RIMARY KEY] then
14490 20 74 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20   that column.** 
144a0 69 73 20 61 6e 6f 74 68 65 72 20 61 6c 69 61 73  is another alias
144b0 20 66 6f 72 20 74 68 65 20 72 6f 77 69 64 2e 0a   for the rowid..
144c0 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74  **.** ^This rout
144d0 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ine returns the 
144e0 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 6d  [rowid] of the m
144f0 6f 73 74 20 72 65 63 65 6e 74 0a 2a 2a 20 73 75  ost recent.** su
14500 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54  ccessful [INSERT
14510 5d 20 69 6e 74 6f 20 74 68 65 20 64 61 74 61 62  ] into the datab
14520 61 73 65 20 66 72 6f 6d 20 74 68 65 20 5b 64 61  ase from the [da
14530 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
14540 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69 72  n].** in the fir
14550 73 74 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e 41  st argument.  ^A
14560 73 20 6f 66 20 53 51 4c 69 74 65 20 76 65 72 73  s of SQLite vers
14570 69 6f 6e 20 33 2e 37 2e 37 2c 20 74 68 69 73 20  ion 3.7.7, this 
14580 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 72 65 63 6f  routines.** reco
14590 72 64 73 20 74 68 65 20 6c 61 73 74 20 69 6e 73  rds the last ins
145a0 65 72 74 20 72 6f 77 69 64 20 6f 66 20 62 6f 74  ert rowid of bot
145b0 68 20 6f 72 64 69 6e 61 72 79 20 74 61 62 6c 65  h ordinary table
145c0 73 20 61 6e 64 20 5b 76 69 72 74 75 61 6c 20 74  s and [virtual t
145d0 61 62 6c 65 73 5d 2e 0a 2a 2a 20 5e 49 66 20 6e  ables]..** ^If n
145e0 6f 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e  o successful [IN
145f0 53 45 52 54 5d 73 0a 2a 2a 20 68 61 76 65 20 65  SERT]s.** have e
14600 76 65 72 20 6f 63 63 75 72 72 65 64 20 6f 6e 20  ver occurred on 
14610 74 68 61 74 20 64 61 74 61 62 61 73 65 20 63 6f  that database co
14620 6e 6e 65 63 74 69 6f 6e 2c 20 7a 65 72 6f 20 69  nnection, zero i
14630 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
14640 2a 20 5e 28 49 66 20 61 6e 20 5b 49 4e 53 45 52  * ^(If an [INSER
14650 54 5d 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e  T] occurs within
14660 20 61 20 74 72 69 67 67 65 72 20 6f 72 20 77 69   a trigger or wi
14670 74 68 69 6e 20 61 20 5b 76 69 72 74 75 61 6c 20  thin a [virtual 
14680 74 61 62 6c 65 5d 0a 2a 2a 20 6d 65 74 68 6f 64  table].** method
14690 2c 20 74 68 65 6e 20 74 68 69 73 20 72 6f 75 74  , then this rout
146a0 69 6e 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ine will return 
146b0 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74  the [rowid] of t
146c0 68 65 20 69 6e 73 65 72 74 65 64 0a 2a 2a 20 72  he inserted.** r
146d0 6f 77 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68  ow as long as th
146e0 65 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 72  e trigger or vir
146f0 74 75 61 6c 20 74 61 62 6c 65 20 6d 65 74 68 6f  tual table metho
14700 64 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a  d is running..**
14710 20 42 75 74 20 6f 6e 63 65 20 74 68 65 20 74 72   But once the tr
14720 69 67 67 65 72 20 6f 72 20 76 69 72 74 75 61 6c  igger or virtual
14730 20 74 61 62 6c 65 20 6d 65 74 68 6f 64 20 65 6e   table method en
14740 64 73 2c 20 74 68 65 20 76 61 6c 75 65 20 72 65  ds, the value re
14750 74 75 72 6e 65 64 20 0a 2a 2a 20 62 79 20 74 68  turned .** by th
14760 69 73 20 72 6f 75 74 69 6e 65 20 72 65 76 65 72  is routine rever
14770 74 73 20 74 6f 20 77 68 61 74 20 69 74 20 77 61  ts to what it wa
14780 73 20 62 65 66 6f 72 65 20 74 68 65 20 74 72 69  s before the tri
14790 67 67 65 72 20 6f 72 20 76 69 72 74 75 61 6c 0a  gger or virtual.
147a0 2a 2a 20 74 61 62 6c 65 20 6d 65 74 68 6f 64 20  ** table method 
147b0 62 65 67 61 6e 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  began.)^.**.** ^
147c0 41 6e 20 5b 49 4e 53 45 52 54 5d 20 74 68 61 74  An [INSERT] that
147d0 20 66 61 69 6c 73 20 64 75 65 20 74 6f 20 61 20   fails due to a 
147e0 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61  constraint viola
147f0 74 69 6f 6e 20 69 73 20 6e 6f 74 20 61 0a 2a 2a  tion is not a.**
14800 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53   successful [INS
14810 45 52 54 5d 20 61 6e 64 20 64 6f 65 73 20 6e 6f  ERT] and does no
14820 74 20 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c  t change the val
14830 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  ue returned by t
14840 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 2e 20  his.** routine. 
14850 20 5e 54 68 75 73 20 49 4e 53 45 52 54 20 4f 52   ^Thus INSERT OR
14860 20 46 41 49 4c 2c 20 49 4e 53 45 52 54 20 4f 52   FAIL, INSERT OR
14870 20 49 47 4e 4f 52 45 2c 20 49 4e 53 45 52 54 20   IGNORE, INSERT 
14880 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a 20  OR ROLLBACK,.** 
14890 61 6e 64 20 49 4e 53 45 52 54 20 4f 52 20 41 42  and INSERT OR AB
148a0 4f 52 54 20 6d 61 6b 65 20 6e 6f 20 63 68 61 6e  ORT make no chan
148b0 67 65 73 20 74 6f 20 74 68 65 20 72 65 74 75 72  ges to the retur
148c0 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 0a  n value of this.
148d0 2a 2a 20 72 6f 75 74 69 6e 65 20 77 68 65 6e 20  ** routine when 
148e0 74 68 65 69 72 20 69 6e 73 65 72 74 69 6f 6e 20  their insertion 
148f0 66 61 69 6c 73 2e 20 20 5e 28 57 68 65 6e 20 49  fails.  ^(When I
14900 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45  NSERT OR REPLACE
14910 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 73 20 61  .** encounters a
14920 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c   constraint viol
14930 61 74 69 6f 6e 2c 20 69 74 20 64 6f 65 73 20 6e  ation, it does n
14940 6f 74 20 66 61 69 6c 2e 20 20 54 68 65 0a 2a 2a  ot fail.  The.**
14950 20 49 4e 53 45 52 54 20 63 6f 6e 74 69 6e 75 65   INSERT continue
14960 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20  s to completion 
14970 61 66 74 65 72 20 64 65 6c 65 74 69 6e 67 20 72  after deleting r
14980 6f 77 73 20 74 68 61 74 20 63 61 75 73 65 64 0a  ows that caused.
14990 2a 2a 20 74 68 65 20 63 6f 6e 73 74 72 61 69 6e  ** the constrain
149a0 74 20 70 72 6f 62 6c 65 6d 20 73 6f 20 49 4e 53  t problem so INS
149b0 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45 20 77  ERT OR REPLACE w
149c0 69 6c 6c 20 61 6c 77 61 79 73 20 63 68 61 6e 67  ill always chang
149d0 65 0a 2a 2a 20 74 68 65 20 72 65 74 75 72 6e 20  e.** the return 
149e0 76 61 6c 75 65 20 6f 66 20 74 68 69 73 20 69 6e  value of this in
149f0 74 65 72 66 61 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a  terface.)^.**.**
14a00 20 5e 46 6f 72 20 74 68 65 20 70 75 72 70 6f 73   ^For the purpos
14a10 65 73 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69  es of this routi
14a20 6e 65 2c 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20  ne, an [INSERT] 
14a30 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 74 6f  is considered to
14a40 0a 2a 2a 20 62 65 20 73 75 63 63 65 73 73 66 75  .** be successfu
14a50 6c 20 65 76 65 6e 20 69 66 20 69 74 20 69 73 20  l even if it is 
14a60 73 75 62 73 65 71 75 65 6e 74 6c 79 20 72 6f 6c  subsequently rol
14a70 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20  led back..**.** 
14a80 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73  This function is
14a90 20 61 63 63 65 73 73 69 62 6c 65 20 74 6f 20 53   accessible to S
14aa0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 76 69  QL statements vi
14ab0 61 20 74 68 65 0a 2a 2a 20 5b 6c 61 73 74 5f 69  a the.** [last_i
14ac0 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 20 53 51  nsert_rowid() SQ
14ad0 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a  L function]..**.
14ae0 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65  ** If a separate
14af0 20 74 68 72 65 61 64 20 70 65 72 66 6f 72 6d 73   thread performs
14b00 20 61 20 6e 65 77 20 5b 49 4e 53 45 52 54 5d 20   a new [INSERT] 
14b10 6f 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 64  on the same.** d
14b20 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
14b30 6f 6e 20 77 68 69 6c 65 20 74 68 65 20 5b 73 71  on while the [sq
14b40 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72  lite3_last_inser
14b50 74 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a 20 66 75  t_rowid()].** fu
14b60 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e  nction is runnin
14b70 67 20 61 6e 64 20 74 68 75 73 20 63 68 61 6e 67  g and thus chang
14b80 65 73 20 74 68 65 20 6c 61 73 74 20 69 6e 73 65  es the last inse
14b90 72 74 20 5b 72 6f 77 69 64 5d 2c 0a 2a 2a 20 74  rt [rowid],.** t
14ba0 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65  hen the value re
14bb0 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74  turned by [sqlit
14bc0 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72  e3_last_insert_r
14bd0 6f 77 69 64 28 29 5d 20 69 73 0a 2a 2a 20 75 6e  owid()] is.** un
14be0 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20  predictable and 
14bf0 6d 69 67 68 74 20 6e 6f 74 20 65 71 75 61 6c 20  might not equal 
14c00 65 69 74 68 65 72 20 74 68 65 20 6f 6c 64 20 6f  either the old o
14c10 72 20 74 68 65 20 6e 65 77 0a 2a 2a 20 6c 61 73  r the new.** las
14c20 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d  t insert [rowid]
14c30 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74  ..*/.sqlite3_int
14c40 36 34 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f  64 sqlite3_last_
14c50 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 73 71 6c  insert_rowid(sql
14c60 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
14c70 41 50 49 33 52 45 46 3a 20 43 6f 75 6e 74 20 54  API3REF: Count T
14c80 68 65 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77  he Number Of Row
14c90 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a 2a 2a  s Modified.**.**
14ca0 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20   ^This function 
14cb0 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
14cc0 65 72 20 6f 66 20 64 61 74 61 62 61 73 65 20 72  er of database r
14cd0 6f 77 73 20 74 68 61 74 20 77 65 72 65 20 63 68  ows that were ch
14ce0 61 6e 67 65 64 0a 2a 2a 20 6f 72 20 69 6e 73 65  anged.** or inse
14cf0 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64 20  rted or deleted 
14d00 62 79 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  by the most rece
14d10 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 53  ntly completed S
14d20 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  QL statement.** 
14d30 6f 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  on the [database
14d40 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65   connection] spe
14d50 63 69 66 69 65 64 20 62 79 20 74 68 65 20 66 69  cified by the fi
14d60 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  rst parameter..*
14d70 2a 20 5e 28 4f 6e 6c 79 20 63 68 61 6e 67 65 73  * ^(Only changes
14d80 20 74 68 61 74 20 61 72 65 20 64 69 72 65 63 74   that are direct
14d90 6c 79 20 73 70 65 63 69 66 69 65 64 20 62 79 20  ly specified by 
14da0 74 68 65 20 5b 49 4e 53 45 52 54 5d 2c 20 5b 55  the [INSERT], [U
14db0 50 44 41 54 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 44  PDATE],.** or [D
14dc0 45 4c 45 54 45 5d 20 73 74 61 74 65 6d 65 6e 74  ELETE] statement
14dd0 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 20 20 41   are counted.  A
14de0 75 78 69 6c 69 61 72 79 20 63 68 61 6e 67 65 73  uxiliary changes
14df0 20 63 61 75 73 65 64 20 62 79 0a 2a 2a 20 74 72   caused by.** tr
14e00 69 67 67 65 72 73 20 6f 72 20 5b 66 6f 72 65 69  iggers or [forei
14e10 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d 20  gn key actions] 
14e20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e  are not counted.
14e30 29 5e 20 55 73 65 20 74 68 65 0a 2a 2a 20 5b 73  )^ Use the.** [s
14e40 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61  qlite3_total_cha
14e50 6e 67 65 73 28 29 5d 20 66 75 6e 63 74 69 6f 6e  nges()] function
14e60 20 74 6f 20 66 69 6e 64 20 74 68 65 20 74 6f 74   to find the tot
14e70 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61  al number of cha
14e80 6e 67 65 73 0a 2a 2a 20 69 6e 63 6c 75 64 69 6e  nges.** includin
14e90 67 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 64  g changes caused
14ea0 20 62 79 20 74 72 69 67 67 65 72 73 20 61 6e 64   by triggers and
14eb0 20 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74   foreign key act
14ec0 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 43 68 61  ions..**.** ^Cha
14ed0 6e 67 65 73 20 74 6f 20 61 20 76 69 65 77 20 74  nges to a view t
14ee0 68 61 74 20 61 72 65 20 73 69 6d 75 6c 61 74 65  hat are simulate
14ef0 64 20 62 79 20 61 6e 20 5b 49 4e 53 54 45 41 44  d by an [INSTEAD
14f00 20 4f 46 20 74 72 69 67 67 65 72 5d 0a 2a 2a 20   OF trigger].** 
14f10 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e  are not counted.
14f20 20 20 4f 6e 6c 79 20 72 65 61 6c 20 74 61 62 6c    Only real tabl
14f30 65 20 63 68 61 6e 67 65 73 20 61 72 65 20 63 6f  e changes are co
14f40 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41  unted..**.** ^(A
14f50 20 22 72 6f 77 20 63 68 61 6e 67 65 22 20 69 73   "row change" is
14f60 20 61 20 63 68 61 6e 67 65 20 74 6f 20 61 20 73   a change to a s
14f70 69 6e 67 6c 65 20 72 6f 77 20 6f 66 20 61 20 73  ingle row of a s
14f80 69 6e 67 6c 65 20 74 61 62 6c 65 0a 2a 2a 20 63  ingle table.** c
14f90 61 75 73 65 64 20 62 79 20 61 6e 20 49 4e 53 45  aused by an INSE
14fa0 52 54 2c 20 44 45 4c 45 54 45 2c 20 6f 72 20 55  RT, DELETE, or U
14fb0 50 44 41 54 45 20 73 74 61 74 65 6d 65 6e 74 2e  PDATE statement.
14fc0 20 20 52 6f 77 73 20 74 68 61 74 0a 2a 2a 20 61    Rows that.** a
14fd0 72 65 20 63 68 61 6e 67 65 64 20 61 73 20 73 69  re changed as si
14fe0 64 65 20 65 66 66 65 63 74 73 20 6f 66 20 5b 52  de effects of [R
14ff0 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61 69  EPLACE] constrai
15000 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e 2c 0a 2a  nt resolution,.*
15010 2a 20 72 6f 6c 6c 62 61 63 6b 2c 20 41 42 4f 52  * rollback, ABOR
15020 54 20 70 72 6f 63 65 73 73 69 6e 67 2c 20 5b 44  T processing, [D
15030 52 4f 50 20 54 41 42 4c 45 5d 2c 20 6f 72 20 62  ROP TABLE], or b
15040 79 20 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 6d  y any other.** m
15050 65 63 68 61 6e 69 73 6d 73 20 64 6f 20 6e 6f 74  echanisms do not
15060 20 63 6f 75 6e 74 20 61 73 20 64 69 72 65 63 74   count as direct
15070 20 72 6f 77 20 63 68 61 6e 67 65 73 2e 29 5e 0a   row changes.)^.
15080 2a 2a 0a 2a 2a 20 41 20 22 74 72 69 67 67 65 72  **.** A "trigger
15090 20 63 6f 6e 74 65 78 74 22 20 69 73 20 61 20 73   context" is a s
150a0 63 6f 70 65 20 6f 66 20 65 78 65 63 75 74 69 6f  cope of executio
150b0 6e 20 74 68 61 74 20 62 65 67 69 6e 73 20 61 6e  n that begins an
150c0 64 0a 2a 2a 20 65 6e 64 73 20 77 69 74 68 20 74  d.** ends with t
150d0 68 65 20 73 63 72 69 70 74 20 6f 66 20 61 20 5b  he script of a [
150e0 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20 7c  CREATE TRIGGER |
150f0 20 74 72 69 67 67 65 72 5d 2e 20 0a 2a 2a 20 4d   trigger]. .** M
15100 6f 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ost SQL statemen
15110 74 73 20 61 72 65 0a 2a 2a 20 65 76 61 6c 75 61  ts are.** evalua
15120 74 65 64 20 6f 75 74 73 69 64 65 20 6f 66 20 61  ted outside of a
15130 6e 79 20 74 72 69 67 67 65 72 2e 20 20 54 68 69  ny trigger.  Thi
15140 73 20 69 73 20 74 68 65 20 22 74 6f 70 20 6c 65  s is the "top le
15150 76 65 6c 22 0a 2a 2a 20 74 72 69 67 67 65 72 20  vel".** trigger 
15160 63 6f 6e 74 65 78 74 2e 20 20 49 66 20 61 20 74  context.  If a t
15170 72 69 67 67 65 72 20 66 69 72 65 73 20 66 72 6f  rigger fires fro
15180 6d 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2c  m the top level,
15190 20 61 0a 2a 2a 20 6e 65 77 20 74 72 69 67 67 65   a.** new trigge
151a0 72 20 63 6f 6e 74 65 78 74 20 69 73 20 65 6e 74  r context is ent
151b0 65 72 65 64 20 66 6f 72 20 74 68 65 20 64 75 72  ered for the dur
151c0 61 74 69 6f 6e 20 6f 66 20 74 68 61 74 20 6f 6e  ation of that on
151d0 65 0a 2a 2a 20 74 72 69 67 67 65 72 2e 20 20 53  e.** trigger.  S
151e0 75 62 74 72 69 67 67 65 72 73 20 63 72 65 61 74  ubtriggers creat
151f0 65 20 73 75 62 63 6f 6e 74 65 78 74 73 20 66 6f  e subcontexts fo
15200 72 20 74 68 65 69 72 20 64 75 72 61 74 69 6f 6e  r their duration
15210 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67  ..**.** ^Calling
15220 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
15230 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 74  ] or [sqlite3_st
15240 65 70 28 29 5d 20 72 65 63 75 72 73 69 76 65 6c  ep()] recursivel
15250 79 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 63 72  y does.** not cr
15260 65 61 74 65 20 61 20 6e 65 77 20 74 72 69 67 67  eate a new trigg
15270 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a  er context..**.*
15280 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  * ^This function
15290 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
152a0 62 65 72 20 6f 66 20 64 69 72 65 63 74 20 72 6f  ber of direct ro
152b0 77 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65  w changes in the
152c0 0a 2a 2a 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  .** most recent 
152d0 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20  INSERT, UPDATE, 
152e0 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d  or DELETE statem
152f0 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65 20 73  ent within the s
15300 61 6d 65 0a 2a 2a 20 74 72 69 67 67 65 72 20 63  ame.** trigger c
15310 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ontext..**.** ^T
15320 68 75 73 2c 20 77 68 65 6e 20 63 61 6c 6c 65 64  hus, when called
15330 20 66 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65   from the top le
15340 76 65 6c 2c 20 74 68 69 73 20 66 75 6e 63 74 69  vel, this functi
15350 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a  on returns the.*
15360 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 6e  * number of chan
15370 67 65 73 20 69 6e 20 74 68 65 20 6d 6f 73 74 20  ges in the most 
15380 72 65 63 65 6e 74 20 49 4e 53 45 52 54 2c 20 55  recent INSERT, U
15390 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45  PDATE, or DELETE
153a0 0a 2a 2a 20 74 68 61 74 20 61 6c 73 6f 20 6f 63  .** that also oc
153b0 63 75 72 72 65 64 20 61 74 20 74 68 65 20 74 6f  curred at the to
153c0 70 20 6c 65 76 65 6c 2e 20 20 5e 28 57 69 74 68  p level.  ^(With
153d0 69 6e 20 74 68 65 20 62 6f 64 79 20 6f 66 20 61  in the body of a
153e0 20 74 72 69 67 67 65 72 2c 0a 2a 2a 20 74 68 65   trigger,.** the
153f0 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73   sqlite3_changes
15400 28 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e  () interface can
15410 20 62 65 20 63 61 6c 6c 65 64 20 74 6f 20 66 69   be called to fi
15420 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  nd the number of
15430 0a 2a 2a 20 63 68 61 6e 67 65 73 20 69 6e 20 74  .** changes in t
15440 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79  he most recently
15450 20 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53 45 52   completed INSER
15460 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45  T, UPDATE, or DE
15470 4c 45 54 45 0a 2a 2a 20 73 74 61 74 65 6d 65 6e  LETE.** statemen
15480 74 20 77 69 74 68 69 6e 20 74 68 65 20 62 6f 64  t within the bod
15490 79 20 6f 66 20 74 68 65 20 73 61 6d 65 20 74 72  y of the same tr
154a0 69 67 67 65 72 2e 0a 2a 2a 20 48 6f 77 65 76 65  igger..** Howeve
154b0 72 2c 20 74 68 65 20 6e 75 6d 62 65 72 20 72 65  r, the number re
154c0 74 75 72 6e 65 64 20 64 6f 65 73 20 6e 6f 74 20  turned does not 
154d0 69 6e 63 6c 75 64 65 20 63 68 61 6e 67 65 73 0a  include changes.
154e0 2a 2a 20 63 61 75 73 65 64 20 62 79 20 73 75 62  ** caused by sub
154f0 74 72 69 67 67 65 72 73 20 73 69 6e 63 65 20 74  triggers since t
15500 68 6f 73 65 20 68 61 76 65 20 74 68 65 69 72 20  hose have their 
15510 6f 77 6e 20 63 6f 6e 74 65 78 74 2e 29 5e 0a 2a  own context.)^.*
15520 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68  *.** See also th
15530 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c  e [sqlite3_total
15540 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 65  _changes()] inte
15550 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63  rface, the.** [c
15560 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 61  ount_changes pra
15570 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b 63  gma], and the [c
15580 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e  hanges() SQL fun
15590 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66  ction]..**.** If
155a0 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65   a separate thre
155b0 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73  ad makes changes
155c0 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74   on the same dat
155d0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
155e0 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69 74  .** while [sqlit
155f0 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73  e3_changes()] is
15600 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68   running then th
15610 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
15620 0a 2a 2a 20 69 73 20 75 6e 70 72 65 64 69 63 74  .** is unpredict
15630 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61  able and not mea
15640 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20  ningful..*/.int 
15650 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
15660 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a  sqlite3*);../*.*
15670 2a 20 43 41 50 49 33 52 45 46 3a 20 54 6f 74 61  * CAPI3REF: Tota
15680 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73  l Number Of Rows
15690 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a 2a 2a 20   Modified.**.** 
156a0 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72  ^This function r
156b0 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
156c0 72 20 6f 66 20 72 6f 77 20 63 68 61 6e 67 65 73  r of row changes
156d0 20 63 61 75 73 65 64 20 62 79 20 5b 49 4e 53 45   caused by [INSE
156e0 52 54 5d 2c 0a 2a 2a 20 5b 55 50 44 41 54 45 5d  RT],.** [UPDATE]
156f0 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73 74 61   or [DELETE] sta
15700 74 65 6d 65 6e 74 73 20 73 69 6e 63 65 20 74 68  tements since th
15710 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
15720 65 63 74 69 6f 6e 5d 20 77 61 73 20 6f 70 65 6e  ection] was open
15730 65 64 2e 0a 2a 2a 20 5e 28 54 68 65 20 63 6f 75  ed..** ^(The cou
15740 6e 74 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  nt returned by s
15750 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61  qlite3_total_cha
15760 6e 67 65 73 28 29 20 69 6e 63 6c 75 64 65 73 20  nges() includes 
15770 61 6c 6c 20 63 68 61 6e 67 65 73 0a 2a 2a 20 66  all changes.** f
15780 72 6f 6d 20 61 6c 6c 20 5b 43 52 45 41 54 45 20  rom all [CREATE 
15790 54 52 49 47 47 45 52 20 7c 20 74 72 69 67 67 65  TRIGGER | trigge
157a0 72 5d 20 63 6f 6e 74 65 78 74 73 20 61 6e 64 20  r] contexts and 
157b0 63 68 61 6e 67 65 73 20 6d 61 64 65 20 62 79 0a  changes made by.
157c0 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20  ** [foreign key 
157d0 61 63 74 69 6f 6e 73 5d 2e 20 48 6f 77 65 76 65  actions]. Howeve
157e0 72 2c 0a 2a 2a 20 74 68 65 20 63 6f 75 6e 74 20  r,.** the count 
157f0 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65  does not include
15800 20 63 68 61 6e 67 65 73 20 75 73 65 64 20 74 6f   changes used to
15810 20 69 6d 70 6c 65 6d 65 6e 74 20 5b 52 45 50 4c   implement [REPL
15820 41 43 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74 73  ACE] constraints
15830 2c 0a 2a 2a 20 64 6f 20 72 6f 6c 6c 62 61 63 6b  ,.** do rollback
15840 73 20 6f 72 20 41 42 4f 52 54 20 70 72 6f 63 65  s or ABORT proce
15850 73 73 69 6e 67 2c 20 6f 72 20 5b 44 52 4f 50 20  ssing, or [DROP 
15860 54 41 42 4c 45 5d 20 70 72 6f 63 65 73 73 69 6e  TABLE] processin
15870 67 2e 20 20 54 68 65 0a 2a 2a 20 63 6f 75 6e 74  g.  The.** count
15880 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64   does not includ
15890 65 20 72 6f 77 73 20 6f 66 20 76 69 65 77 73 20  e rows of views 
158a0 74 68 61 74 20 66 69 72 65 20 61 6e 20 5b 49 4e  that fire an [IN
158b0 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 72  STEAD OF trigger
158c0 5d 2c 0a 2a 2a 20 74 68 6f 75 67 68 20 69 66 20  ],.** though if 
158d0 74 68 65 20 49 4e 53 54 45 41 44 20 4f 46 20 74  the INSTEAD OF t
158e0 72 69 67 67 65 72 20 6d 61 6b 65 73 20 63 68 61  rigger makes cha
158f0 6e 67 65 73 20 6f 66 20 69 74 73 20 6f 77 6e 2c  nges of its own,
15900 20 74 68 6f 73 65 20 63 68 61 6e 67 65 73 20 0a   those changes .
15910 2a 2a 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 29  ** are counted.)
15920 5e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ^.** ^The sqlite
15930 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
15940 29 20 66 75 6e 63 74 69 6f 6e 20 63 6f 75 6e 74  ) function count
15950 73 20 74 68 65 20 63 68 61 6e 67 65 73 20 61 73  s the changes as
15960 20 73 6f 6f 6e 20 61 73 0a 2a 2a 20 74 68 65 20   soon as.** the 
15970 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 6d  statement that m
15980 61 6b 65 73 20 74 68 65 6d 20 69 73 20 63 6f 6d  akes them is com
15990 70 6c 65 74 65 64 20 28 77 68 65 6e 20 74 68 65  pleted (when the
159a0 20 73 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c   statement handl
159b0 65 0a 2a 2a 20 69 73 20 70 61 73 73 65 64 20 74  e.** is passed t
159c0 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  o [sqlite3_reset
159d0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
159e0 66 69 6e 61 6c 69 7a 65 28 29 5d 29 2e 0a 2a 2a  finalize()])..**
159f0 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65  .** See also the
15a00 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65   [sqlite3_change
15a10 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2c 20  s()] interface, 
15a20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68  the.** [count_ch
15a30 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c 20 61  anges pragma], a
15a40 6e 64 20 74 68 65 20 5b 74 6f 74 61 6c 5f 63 68  nd the [total_ch
15a50 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63  anges() SQL func
15a60 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  tion]..**.** If 
15a70 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61  a separate threa
15a80 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20  d makes changes 
15a90 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  on the same data
15aa0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
15ab0 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65  ** while [sqlite
15ac0 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
15ad0 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68  )] is running th
15ae0 65 6e 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20  en the value.** 
15af0 72 65 74 75 72 6e 65 64 20 69 73 20 75 6e 70 72  returned is unpr
15b00 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f  edictable and no
15b10 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f  t meaningful..*/
15b20 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 6f 74  .int sqlite3_tot
15b30 61 6c 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74  al_changes(sqlit
15b40 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e3*);../*.** CAP
15b50 49 33 52 45 46 3a 20 49 6e 74 65 72 72 75 70 74  I3REF: Interrupt
15b60 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e 67 20   A Long-Running 
15b70 51 75 65 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  Query.**.** ^Thi
15b80 73 20 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 65  s function cause
15b90 73 20 61 6e 79 20 70 65 6e 64 69 6e 67 20 64 61  s any pending da
15ba0 74 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e  tabase operation
15bb0 20 74 6f 20 61 62 6f 72 74 20 61 6e 64 0a 2a 2a   to abort and.**
15bc0 20 72 65 74 75 72 6e 20 61 74 20 69 74 73 20 65   return at its e
15bd0 61 72 6c 69 65 73 74 20 6f 70 70 6f 72 74 75 6e  arliest opportun
15be0 69 74 79 2e 20 54 68 69 73 20 72 6f 75 74 69 6e  ity. This routin
15bf0 65 20 69 73 20 74 79 70 69 63 61 6c 6c 79 0a 2a  e is typically.*
15c00 2a 20 63 61 6c 6c 65 64 20 69 6e 20 72 65 73 70  * called in resp
15c10 6f 6e 73 65 20 74 6f 20 61 20 75 73 65 72 20 61  onse to a user a
15c20 63 74 69 6f 6e 20 73 75 63 68 20 61 73 20 70 72  ction such as pr
15c30 65 73 73 69 6e 67 20 22 43 61 6e 63 65 6c 22 0a  essing "Cancel".
15c40 2a 2a 20 6f 72 20 43 74 72 6c 2d 43 20 77 68 65  ** or Ctrl-C whe
15c50 72 65 20 74 68 65 20 75 73 65 72 20 77 61 6e 74  re the user want
15c60 73 20 61 20 6c 6f 6e 67 20 71 75 65 72 79 20 6f  s a long query o
15c70 70 65 72 61 74 69 6f 6e 20 74 6f 20 68 61 6c 74  peration to halt
15c80 0a 2a 2a 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e  .** immediately.
15c90 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 73 61  .**.** ^It is sa
15ca0 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20  fe to call this 
15cb0 72 6f 75 74 69 6e 65 20 66 72 6f 6d 20 61 20 74  routine from a t
15cc0 68 72 65 61 64 20 64 69 66 66 65 72 65 6e 74 20  hread different 
15cd0 66 72 6f 6d 20 74 68 65 0a 2a 2a 20 74 68 72 65  from the.** thre
15ce0 61 64 20 74 68 61 74 20 69 73 20 63 75 72 72 65  ad that is curre
15cf0 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 20 74 68 65  ntly running the
15d00 20 64 61 74 61 62 61 73 65 20 6f 70 65 72 61 74   database operat
15d10 69 6f 6e 2e 20 20 42 75 74 20 69 74 0a 2a 2a 20  ion.  But it.** 
15d20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 63  is not safe to c
15d30 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65  all this routine
15d40 20 77 69 74 68 20 61 20 5b 64 61 74 61 62 61 73   with a [databas
15d50 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68  e connection] th
15d60 61 74 0a 2a 2a 20 69 73 20 63 6c 6f 73 65 64 20  at.** is closed 
15d70 6f 72 20 6d 69 67 68 74 20 63 6c 6f 73 65 20 62  or might close b
15d80 65 66 6f 72 65 20 73 71 6c 69 74 65 33 5f 69 6e  efore sqlite3_in
15d90 74 65 72 72 75 70 74 28 29 20 72 65 74 75 72 6e  terrupt() return
15da0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20  s..**.** ^If an 
15db0 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73  SQL operation is
15dc0 20 76 65 72 79 20 6e 65 61 72 6c 79 20 66 69 6e   very nearly fin
15dd0 69 73 68 65 64 20 61 74 20 74 68 65 20 74 69 6d  ished at the tim
15de0 65 20 77 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65  e when.** sqlite
15df0 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 69 73  3_interrupt() is
15e00 20 63 61 6c 6c 65 64 2c 20 74 68 65 6e 20 69 74   called, then it
15e10 20 6d 69 67 68 74 20 6e 6f 74 20 68 61 76 65 20   might not have 
15e20 61 6e 20 6f 70 70 6f 72 74 75 6e 69 74 79 0a 2a  an opportunity.*
15e30 2a 20 74 6f 20 62 65 20 69 6e 74 65 72 72 75 70  * to be interrup
15e40 74 65 64 20 61 6e 64 20 6d 69 67 68 74 20 63 6f  ted and might co
15e50 6e 74 69 6e 75 65 20 74 6f 20 63 6f 6d 70 6c 65  ntinue to comple
15e60 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20  tion..**.** ^An 
15e70 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 74 68  SQL operation th
15e80 61 74 20 69 73 20 69 6e 74 65 72 72 75 70 74 65  at is interrupte
15e90 64 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53  d will return [S
15ea0 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d  QLITE_INTERRUPT]
15eb0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 69 6e 74  ..** ^If the int
15ec0 65 72 72 75 70 74 65 64 20 53 51 4c 20 6f 70 65  errupted SQL ope
15ed0 72 61 74 69 6f 6e 20 69 73 20 61 6e 20 49 4e 53  ration is an INS
15ee0 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20  ERT, UPDATE, or 
15ef0 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 69  DELETE.** that i
15f00 73 20 69 6e 73 69 64 65 20 61 6e 20 65 78 70 6c  s inside an expl
15f10 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e  icit transaction
15f20 2c 20 74 68 65 6e 20 74 68 65 20 65 6e 74 69 72  , then the entir
15f30 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 0a 2a 2a  e transaction.**
15f40 20 77 69 6c 6c 20 62 65 20 72 6f 6c 6c 65 64 20   will be rolled 
15f50 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c  back automatical
15f60 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ly..**.** ^The s
15f70 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
15f80 28 44 29 20 63 61 6c 6c 20 69 73 20 69 6e 20 65  (D) call is in e
15f90 66 66 65 63 74 20 75 6e 74 69 6c 20 61 6c 6c 20  ffect until all 
15fa0 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e  currently runnin
15fb0 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65  g.** SQL stateme
15fc0 6e 74 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65  nts on [database
15fd0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 63   connection] D c
15fe0 6f 6d 70 6c 65 74 65 2e 20 20 5e 41 6e 79 20 6e  omplete.  ^Any n
15ff0 65 77 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ew SQL statement
16000 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74  s.** that are st
16010 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65 20  arted after the 
16020 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
16030 74 28 29 20 63 61 6c 6c 20 61 6e 64 20 62 65 66  t() call and bef
16040 6f 72 65 20 74 68 65 20 0a 2a 2a 20 72 75 6e 6e  ore the .** runn
16050 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 73 20 72  ing statements r
16060 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65 20  eaches zero are 
16070 69 6e 74 65 72 72 75 70 74 65 64 20 61 73 20 69  interrupted as i
16080 66 20 74 68 65 79 20 68 61 64 20 62 65 65 6e 0a  f they had been.
16090 2a 2a 20 72 75 6e 6e 69 6e 67 20 70 72 69 6f 72  ** running prior
160a0 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
160b0 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c  interrupt() call
160c0 2e 20 20 5e 4e 65 77 20 53 51 4c 20 73 74 61 74  .  ^New SQL stat
160d0 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61  ements.** that a
160e0 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72  re started after
160f0 20 74 68 65 20 72 75 6e 6e 69 6e 67 20 73 74 61   the running sta
16100 74 65 6d 65 6e 74 20 63 6f 75 6e 74 20 72 65 61  tement count rea
16110 63 68 65 73 20 7a 65 72 6f 20 61 72 65 0a 2a 2a  ches zero are.**
16120 20 6e 6f 74 20 65 66 66 65 63 74 65 64 20 62 79   not effected by
16130 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74   the sqlite3_int
16140 65 72 72 75 70 74 28 29 2e 0a 2a 2a 20 5e 41 20  errupt()..** ^A 
16150 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
16160 69 6e 74 65 72 72 75 70 74 28 44 29 20 74 68 61  interrupt(D) tha
16170 74 20 6f 63 63 75 72 73 20 77 68 65 6e 20 74 68  t occurs when th
16180 65 72 65 20 61 72 65 20 6e 6f 20 72 75 6e 6e 69  ere are no runni
16190 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d  ng.** SQL statem
161a0 65 6e 74 73 20 69 73 20 61 20 6e 6f 2d 6f 70 20  ents is a no-op 
161b0 61 6e 64 20 68 61 73 20 6e 6f 20 65 66 66 65 63  and has no effec
161c0 74 20 6f 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  t on SQL stateme
161d0 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20  nts.** that are 
161e0 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68  started after th
161f0 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  e sqlite3_interr
16200 75 70 74 28 29 20 63 61 6c 6c 20 72 65 74 75 72  upt() call retur
16210 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  ns..**.** If the
16220 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
16230 74 69 6f 6e 20 63 6c 6f 73 65 73 20 77 68 69 6c  tion closes whil
16240 65 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  e [sqlite3_inter
16250 72 75 70 74 28 29 5d 0a 2a 2a 20 69 73 20 72 75  rupt()].** is ru
16260 6e 6e 69 6e 67 20 74 68 65 6e 20 62 61 64 20 74  nning then bad t
16270 68 69 6e 67 73 20 77 69 6c 6c 20 6c 69 6b 65 6c  hings will likel
16280 79 20 68 61 70 70 65 6e 2e 0a 2a 2f 0a 76 6f 69  y happen..*/.voi
16290 64 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  d sqlite3_interr
162a0 75 70 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  upt(sqlite3*);..
162b0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
162c0 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 6e 20  Determine If An 
162d0 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 49 73  SQL Statement Is
162e0 20 43 6f 6d 70 6c 65 74 65 0a 2a 2a 0a 2a 2a 20   Complete.**.** 
162f0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
16300 72 65 20 75 73 65 66 75 6c 20 64 75 72 69 6e 67  re useful during
16310 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69 6e   command-line in
16320 70 75 74 20 74 6f 20 64 65 74 65 72 6d 69 6e 65  put to determine
16330 20 69 66 20 74 68 65 0a 2a 2a 20 63 75 72 72 65   if the.** curre
16340 6e 74 6c 79 20 65 6e 74 65 72 65 64 20 74 65 78  ntly entered tex
16350 74 20 73 65 65 6d 73 20 74 6f 20 66 6f 72 6d 20  t seems to form 
16360 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73  a complete SQL s
16370 74 61 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a 20 69  tatement or.** i
16380 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 70  f additional inp
16390 75 74 20 69 73 20 6e 65 65 64 65 64 20 62 65 66  ut is needed bef
163a0 6f 72 65 20 73 65 6e 64 69 6e 67 20 74 68 65 20  ore sending the 
163b0 74 65 78 74 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c  text into.** SQL
163c0 69 74 65 20 66 6f 72 20 70 61 72 73 69 6e 67 2e  ite for parsing.
163d0 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65    ^These routine
163e0 73 20 72 65 74 75 72 6e 20 31 20 69 66 20 74 68  s return 1 if th
163f0 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 0a 2a  e input string.*
16400 2a 20 61 70 70 65 61 72 73 20 74 6f 20 62 65 20  * appears to be 
16410 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73  a complete SQL s
16420 74 61 74 65 6d 65 6e 74 2e 20 20 5e 41 20 73 74  tatement.  ^A st
16430 61 74 65 6d 65 6e 74 20 69 73 20 6a 75 64 67 65  atement is judge
16440 64 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 6c  d to be.** compl
16450 65 74 65 20 69 66 20 69 74 20 65 6e 64 73 20 77  ete if it ends w
16460 69 74 68 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 20  ith a semicolon 
16470 74 6f 6b 65 6e 20 61 6e 64 20 69 73 20 6e 6f 74  token and is not
16480 20 61 20 70 72 65 66 69 78 20 6f 66 20 61 0a 2a   a prefix of a.*
16490 2a 20 77 65 6c 6c 2d 66 6f 72 6d 65 64 20 43 52  * well-formed CR
164a0 45 41 54 45 20 54 52 49 47 47 45 52 20 73 74 61  EATE TRIGGER sta
164b0 74 65 6d 65 6e 74 2e 20 20 5e 53 65 6d 69 63 6f  tement.  ^Semico
164c0 6c 6f 6e 73 20 74 68 61 74 20 61 72 65 20 65 6d  lons that are em
164d0 62 65 64 64 65 64 20 77 69 74 68 69 6e 0a 2a 2a  bedded within.**
164e0 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 73   string literals
164f0 20 6f 72 20 71 75 6f 74 65 64 20 69 64 65 6e 74   or quoted ident
16500 69 66 69 65 72 20 6e 61 6d 65 73 20 6f 72 20 63  ifier names or c
16510 6f 6d 6d 65 6e 74 73 20 61 72 65 20 6e 6f 74 0a  omments are not.
16520 2a 2a 20 69 6e 64 65 70 65 6e 64 65 6e 74 20 74  ** independent t
16530 6f 6b 65 6e 73 20 28 74 68 65 79 20 61 72 65 20  okens (they are 
16540 70 61 72 74 20 6f 66 20 74 68 65 20 74 6f 6b 65  part of the toke
16550 6e 20 69 6e 20 77 68 69 63 68 20 74 68 65 79 20  n in which they 
16560 61 72 65 0a 2a 2a 20 65 6d 62 65 64 64 65 64 29  are.** embedded)
16570 20 61 6e 64 20 74 68 75 73 20 64 6f 20 6e 6f 74   and thus do not
16580 20 63 6f 75 6e 74 20 61 73 20 61 20 73 74 61 74   count as a stat
16590 65 6d 65 6e 74 20 74 65 72 6d 69 6e 61 74 6f 72  ement terminator
165a0 2e 20 20 5e 57 68 69 74 65 73 70 61 63 65 0a 2a  .  ^Whitespace.*
165b0 2a 20 61 6e 64 20 63 6f 6d 6d 65 6e 74 73 20 74  * and comments t
165c0 68 61 74 20 66 6f 6c 6c 6f 77 20 74 68 65 20 66  hat follow the f
165d0 69 6e 61 6c 20 73 65 6d 69 63 6f 6c 6f 6e 20 61  inal semicolon a
165e0 72 65 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a  re ignored..**.*
165f0 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65  * ^These routine
16600 73 20 72 65 74 75 72 6e 20 30 20 69 66 20 74 68  s return 0 if th
16610 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 69  e statement is i
16620 6e 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 49 66 20  ncomplete.  ^If 
16630 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  a.** memory allo
16640 63 61 74 69 6f 6e 20 66 61 69 6c 73 2c 20 74 68  cation fails, th
16650 65 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20  en SQLITE_NOMEM 
16660 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  is returned..**.
16670 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
16680 65 73 20 64 6f 20 6e 6f 74 20 70 61 72 73 65 20  es do not parse 
16690 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
166a0 74 73 20 74 68 75 73 0a 2a 2a 20 77 69 6c 6c 20  ts thus.** will 
166b0 6e 6f 74 20 64 65 74 65 63 74 20 73 79 6e 74 61  not detect synta
166c0 63 74 69 63 61 6c 6c 79 20 69 6e 63 6f 72 72 65  ctically incorre
166d0 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ct SQL..**.** ^(
166e0 49 66 20 53 51 4c 69 74 65 20 68 61 73 20 6e 6f  If SQLite has no
166f0 74 20 62 65 65 6e 20 69 6e 69 74 69 61 6c 69 7a  t been initializ
16700 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
16710 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20  3_initialize()] 
16720 70 72 69 6f 72 20 0a 2a 2a 20 74 6f 20 69 6e 76  prior .** to inv
16730 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 63 6f  oking sqlite3_co
16740 6d 70 6c 65 74 65 31 36 28 29 20 74 68 65 6e 20  mplete16() then 
16750 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
16760 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a  ze() is invoked.
16770 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ** automatically
16780 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70   by sqlite3_comp
16790 6c 65 74 65 31 36 28 29 2e 20 20 49 66 20 74 68  lete16().  If th
167a0 61 74 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f  at initializatio
167b0 6e 20 66 61 69 6c 73 2c 0a 2a 2a 20 74 68 65 6e  n fails,.** then
167c0 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
167d0 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63  e from sqlite3_c
167e0 6f 6d 70 6c 65 74 65 31 36 28 29 20 77 69 6c 6c  omplete16() will
167f0 20 62 65 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a 20   be non-zero.** 
16800 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68  regardless of wh
16810 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65  ether or not the
16820 20 69 6e 70 75 74 20 53 51 4c 20 69 73 20 63 6f   input SQL is co
16830 6d 70 6c 65 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20  mplete.)^.**.** 
16840 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 71  The input to [sq
16850 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 29  lite3_complete()
16860 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f  ] must be a zero
16870 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55  -terminated.** U
16880 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a  TF-8 string..**.
16890 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20  ** The input to 
168a0 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74  [sqlite3_complet
168b0 65 31 36 28 29 5d 20 6d 75 73 74 20 62 65 20 61  e16()] must be a
168c0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
168d0 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69 6e  .** UTF-16 strin
168e0 67 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65  g in native byte
168f0 20 6f 72 64 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73   order..*/.int s
16900 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28  qlite3_complete(
16910 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 29  const char *sql)
16920 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  ;.int sqlite3_co
16930 6d 70 6c 65 74 65 31 36 28 63 6f 6e 73 74 20 76  mplete16(const v
16940 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a  oid *sql);../*.*
16950 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 67 69  * CAPI3REF: Regi
16960 73 74 65 72 20 41 20 43 61 6c 6c 62 61 63 6b 20  ster A Callback 
16970 54 6f 20 48 61 6e 64 6c 65 20 53 51 4c 49 54 45  To Handle SQLITE
16980 5f 42 55 53 59 20 45 72 72 6f 72 73 0a 2a 2a 0a  _BUSY Errors.**.
16990 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65  ** ^This routine
169a0 20 73 65 74 73 20 61 20 63 61 6c 6c 62 61 63 6b   sets a callback
169b0 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 6d   function that m
169c0 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20  ight be invoked 
169d0 77 68 65 6e 65 76 65 72 0a 2a 2a 20 61 6e 20 61  whenever.** an a
169e0 74 74 65 6d 70 74 20 69 73 20 6d 61 64 65 20 74  ttempt is made t
169f0 6f 20 6f 70 65 6e 20 61 20 64 61 74 61 62 61 73  o open a databas
16a00 65 20 74 61 62 6c 65 20 74 68 61 74 20 61 6e 6f  e table that ano
16a10 74 68 65 72 20 74 68 72 65 61 64 0a 2a 2a 20 6f  ther thread.** o
16a20 72 20 70 72 6f 63 65 73 73 20 68 61 73 20 6c 6f  r process has lo
16a30 63 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  cked..**.** ^If 
16a40 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63  the busy callbac
16a50 6b 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20  k is NULL, then 
16a60 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72  [SQLITE_BUSY] or
16a70 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42   [SQLITE_IOERR_B
16a80 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 69 73 20 72 65  LOCKED].** is re
16a90 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65  turned immediate
16aa0 6c 79 20 75 70 6f 6e 20 65 6e 63 6f 75 6e 74 65  ly upon encounte
16ab0 72 69 6e 67 20 74 68 65 20 6c 6f 63 6b 2e 20 20  ring the lock.  
16ac0 5e 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c  ^If the busy cal
16ad0 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20  lback.** is not 
16ae0 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20 63  NULL, then the c
16af0 61 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 62 65  allback might be
16b00 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74 77   invoked with tw
16b10 6f 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a  o arguments..**.
16b20 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72  ** ^The first ar
16b30 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 62 75  gument to the bu
16b40 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20 61 20  sy handler is a 
16b50 63 6f 70 79 20 6f 66 20 74 68 65 20 76 6f 69 64  copy of the void
16b60 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68 0a  * pointer which.
16b70 2a 2a 20 69 73 20 74 68 65 20 74 68 69 72 64 20  ** is the third 
16b80 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
16b90 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72  te3_busy_handler
16ba0 28 29 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64  ().  ^The second
16bb0 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
16bc0 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
16bd0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65   callback is the
16be0 20 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d 65 73   number of times
16bf0 20 74 68 61 74 20 74 68 65 20 62 75 73 79 20 68   that the busy h
16c00 61 6e 64 6c 65 72 20 68 61 73 0a 2a 2a 20 62 65  andler has.** be
16c10 65 6e 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 74  en invoked for t
16c20 68 69 73 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e  his locking even
16c30 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 62  t.  ^If the.** b
16c40 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  usy callback ret
16c50 75 72 6e 73 20 30 2c 20 74 68 65 6e 20 6e 6f 20  urns 0, then no 
16c60 61 64 64 69 74 69 6f 6e 61 6c 20 61 74 74 65 6d  additional attem
16c70 70 74 73 20 61 72 65 20 6d 61 64 65 20 74 6f 0a  pts are made to.
16c80 2a 2a 20 61 63 63 65 73 73 20 74 68 65 20 64 61  ** access the da
16c90 74 61 62 61 73 65 20 61 6e 64 20 5b 53 51 4c 49  tabase and [SQLI
16ca0 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c  TE_BUSY] or [SQL
16cb0 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45  ITE_IOERR_BLOCKE
16cc0 44 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  D] is returned..
16cd0 2a 2a 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62  ** ^If the callb
16ce0 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d  ack returns non-
16cf0 7a 65 72 6f 2c 20 74 68 65 6e 20 61 6e 6f 74 68  zero, then anoth
16d00 65 72 20 61 74 74 65 6d 70 74 0a 2a 2a 20 69 73  er attempt.** is
16d10 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20 74 68   made to open th
16d20 65 20 64 61 74 61 62 61 73 65 20 66 6f 72 20 72  e database for r
16d30 65 61 64 69 6e 67 20 61 6e 64 20 74 68 65 20 63  eading and the c
16d40 79 63 6c 65 20 72 65 70 65 61 74 73 2e 0a 2a 2a  ycle repeats..**
16d50 0a 2a 2a 20 54 68 65 20 70 72 65 73 65 6e 63 65  .** The presence
16d60 20 6f 66 20 61 20 62 75 73 79 20 68 61 6e 64 6c   of a busy handl
16d70 65 72 20 64 6f 65 73 20 6e 6f 74 20 67 75 61 72  er does not guar
16d80 61 6e 74 65 65 20 74 68 61 74 20 69 74 20 77 69  antee that it wi
16d90 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a  ll be invoked.**
16da0 20 77 68 65 6e 20 74 68 65 72 65 20 69 73 20 6c   when there is l
16db0 6f 63 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e 20  ock contention. 
16dc0 5e 49 66 20 53 51 4c 69 74 65 20 64 65 74 65 72  ^If SQLite deter
16dd0 6d 69 6e 65 73 20 74 68 61 74 20 69 6e 76 6f 6b  mines that invok
16de0 69 6e 67 20 74 68 65 20 62 75 73 79 0a 2a 2a 20  ing the busy.** 
16df0 68 61 6e 64 6c 65 72 20 63 6f 75 6c 64 20 72 65  handler could re
16e00 73 75 6c 74 20 69 6e 20 61 20 64 65 61 64 6c 6f  sult in a deadlo
16e10 63 6b 2c 20 69 74 20 77 69 6c 6c 20 67 6f 20 61  ck, it will go a
16e20 68 65 61 64 20 61 6e 64 20 72 65 74 75 72 6e 20  head and return 
16e30 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a  [SQLITE_BUSY].**
16e40 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52   or [SQLITE_IOER
16e50 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 6e 73 74 65  R_BLOCKED] inste
16e60 61 64 20 6f 66 20 69 6e 76 6f 6b 69 6e 67 20 74  ad of invoking t
16e70 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e  he busy handler.
16e80 0a 2a 2a 20 43 6f 6e 73 69 64 65 72 20 61 20 73  .** Consider a s
16e90 63 65 6e 61 72 69 6f 20 77 68 65 72 65 20 6f 6e  cenario where on
16ea0 65 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c  e process is hol
16eb0 64 69 6e 67 20 61 20 72 65 61 64 20 6c 6f 63 6b  ding a read lock
16ec0 20 74 68 61 74 0a 2a 2a 20 69 74 20 69 73 20 74   that.** it is t
16ed0 72 79 69 6e 67 20 74 6f 20 70 72 6f 6d 6f 74 65  rying to promote
16ee0 20 74 6f 20 61 20 72 65 73 65 72 76 65 64 20 6c   to a reserved l
16ef0 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61 20 73 65 63  ock and.** a sec
16f00 6f 6e 64 20 70 72 6f 63 65 73 73 20 69 73 20 68  ond process is h
16f10 6f 6c 64 69 6e 67 20 61 20 72 65 73 65 72 76 65  olding a reserve
16f20 64 20 6c 6f 63 6b 20 74 68 61 74 20 69 74 20 69  d lock that it i
16f30 73 20 74 72 79 69 6e 67 0a 2a 2a 20 74 6f 20 70  s trying.** to p
16f40 72 6f 6d 6f 74 65 20 74 6f 20 61 6e 20 65 78 63  romote to an exc
16f50 6c 75 73 69 76 65 20 6c 6f 63 6b 2e 20 20 54 68  lusive lock.  Th
16f60 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 20  e first process 
16f70 63 61 6e 6e 6f 74 20 70 72 6f 63 65 65 64 0a 2a  cannot proceed.*
16f80 2a 20 62 65 63 61 75 73 65 20 69 74 20 69 73 20  * because it is 
16f90 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20 73  blocked by the s
16fa0 65 63 6f 6e 64 20 61 6e 64 20 74 68 65 20 73 65  econd and the se
16fb0 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 63 61 6e  cond process can
16fc0 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65 65 64 20 62  not.** proceed b
16fd0 65 63 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f  ecause it is blo
16fe0 63 6b 65 64 20 62 79 20 74 68 65 20 66 69 72 73  cked by the firs
16ff0 74 2e 20 20 49 66 20 62 6f 74 68 20 70 72 6f 63  t.  If both proc
17000 65 73 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20  esses.** invoke 
17010 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
17020 73 2c 20 6e 65 69 74 68 65 72 20 77 69 6c 6c 20  s, neither will 
17030 6d 61 6b 65 20 61 6e 79 20 70 72 6f 67 72 65 73  make any progres
17040 73 2e 20 20 54 68 65 72 65 66 6f 72 65 2c 0a 2a  s.  Therefore,.*
17050 2a 20 53 51 4c 69 74 65 20 72 65 74 75 72 6e 73  * SQLite returns
17060 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 66   [SQLITE_BUSY] f
17070 6f 72 20 74 68 65 20 66 69 72 73 74 20 70 72 6f  or the first pro
17080 63 65 73 73 2c 20 68 6f 70 69 6e 67 20 74 68 61  cess, hoping tha
17090 74 20 74 68 69 73 0a 2a 2a 20 77 69 6c 6c 20 69  t this.** will i
170a0 6e 64 75 63 65 20 74 68 65 20 66 69 72 73 74 20  nduce the first 
170b0 70 72 6f 63 65 73 73 20 74 6f 20 72 65 6c 65 61  process to relea
170c0 73 65 20 69 74 73 20 72 65 61 64 20 6c 6f 63 6b  se its read lock
170d0 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68   and allow.** th
170e0 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73  e second process
170f0 20 74 6f 20 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a   to proceed..**.
17100 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20  ** ^The default 
17110 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73  busy callback is
17120 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68   NULL..**.** ^Th
17130 65 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  e [SQLITE_BUSY] 
17140 65 72 72 6f 72 20 69 73 20 63 6f 6e 76 65 72 74  error is convert
17150 65 64 20 74 6f 20 5b 53 51 4c 49 54 45 5f 49 4f  ed to [SQLITE_IO
17160 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20  ERR_BLOCKED].** 
17170 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 69  when SQLite is i
17180 6e 20 74 68 65 20 6d 69 64 64 6c 65 20 6f 66 20  n the middle of 
17190 61 20 6c 61 72 67 65 20 74 72 61 6e 73 61 63 74  a large transact
171a0 69 6f 6e 20 77 68 65 72 65 20 61 6c 6c 20 74 68  ion where all th
171b0 65 0a 2a 2a 20 63 68 61 6e 67 65 73 20 77 69 6c  e.** changes wil
171c0 6c 20 6e 6f 74 20 66 69 74 20 69 6e 74 6f 20 74  l not fit into t
171d0 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 20 63 61 63  he in-memory cac
171e0 68 65 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c  he.  SQLite will
171f0 0a 2a 2a 20 61 6c 72 65 61 64 79 20 68 6f 6c 64  .** already hold
17200 20 61 20 52 45 53 45 52 56 45 44 20 6c 6f 63 6b   a RESERVED lock
17210 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73 65   on the database
17220 20 66 69 6c 65 2c 20 62 75 74 20 69 74 20 6e 65   file, but it ne
17230 65 64 73 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74  eds.** to promot
17240 65 20 74 68 69 73 20 6c 6f 63 6b 20 74 6f 20 45  e this lock to E
17250 58 43 4c 55 53 49 56 45 20 73 6f 20 74 68 61 74  XCLUSIVE so that
17260 20 69 74 20 63 61 6e 20 73 70 69 6c 6c 20 63 61   it can spill ca
17270 63 68 65 0a 2a 2a 20 70 61 67 65 73 20 69 6e 74  che.** pages int
17280 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  o the database f
17290 69 6c 65 20 77 69 74 68 6f 75 74 20 68 61 72 6d  ile without harm
172a0 20 74 6f 20 63 6f 6e 63 75 72 72 65 6e 74 0a 2a   to concurrent.*
172b0 2a 20 72 65 61 64 65 72 73 2e 20 20 5e 49 66 20  * readers.  ^If 
172c0 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  it is unable to 
172d0 70 72 6f 6d 6f 74 65 20 74 68 65 20 6c 6f 63 6b  promote the lock
172e0 2c 20 74 68 65 6e 20 74 68 65 20 69 6e 2d 6d 65  , then the in-me
172f0 6d 6f 72 79 0a 2a 2a 20 63 61 63 68 65 20 77 69  mory.** cache wi
17300 6c 6c 20 62 65 20 6c 65 66 74 20 69 6e 20 61 6e  ll be left in an
17310 20 69 6e 63 6f 6e 73 69 73 74 65 6e 74 20 73 74   inconsistent st
17320 61 74 65 20 61 6e 64 20 73 6f 20 74 68 65 20 65  ate and so the e
17330 72 72 6f 72 0a 2a 2a 20 63 6f 64 65 20 69 73 20  rror.** code is 
17340 70 72 6f 6d 6f 74 65 64 20 66 72 6f 6d 20 74 68  promoted from th
17350 65 20 72 65 6c 61 74 69 76 65 6c 79 20 62 65 6e  e relatively ben
17360 69 67 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  ign [SQLITE_BUSY
17370 5d 20 74 6f 0a 2a 2a 20 74 68 65 20 6d 6f 72 65  ] to.** the more
17380 20 73 65 76 65 72 65 20 5b 53 51 4c 49 54 45 5f   severe [SQLITE_
17390 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e 20  IOERR_BLOCKED]. 
173a0 20 5e 54 68 69 73 20 65 72 72 6f 72 20 63 6f 64   ^This error cod
173b0 65 20 70 72 6f 6d 6f 74 69 6f 6e 0a 2a 2a 20 66  e promotion.** f
173c0 6f 72 63 65 73 20 61 6e 20 61 75 74 6f 6d 61 74  orces an automat
173d0 69 63 20 72 6f 6c 6c 62 61 63 6b 20 6f 66 20 74  ic rollback of t
173e0 68 65 20 63 68 61 6e 67 65 73 2e 20 20 53 65 65  he changes.  See
173f0 20 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66 3d   the.** <a href=
17400 22 2f 63 76 73 74 72 61 63 2f 77 69 6b 69 3f 70  "/cvstrac/wiki?p
17410 3d 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f  =CorruptionFollo
17420 77 69 6e 67 42 75 73 79 45 72 72 6f 72 22 3e 0a  wingBusyError">.
17430 2a 2a 20 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c  ** CorruptionFol
17440 6c 6f 77 69 6e 67 42 75 73 79 45 72 72 6f 72 3c  lowingBusyError<
17450 2f 61 3e 20 77 69 6b 69 20 70 61 67 65 20 66 6f  /a> wiki page fo
17460 72 20 61 20 64 69 73 63 75 73 73 69 6f 6e 20 6f  r a discussion o
17470 66 20 77 68 79 0a 2a 2a 20 74 68 69 73 20 69 73  f why.** this is
17480 20 69 6d 70 6f 72 74 61 6e 74 2e 0a 2a 2a 0a 2a   important..**.*
17490 2a 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e  * ^(There can on
174a0 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62  ly be a single b
174b0 75 73 79 20 68 61 6e 64 6c 65 72 20 64 65 66 69  usy handler defi
174c0 6e 65 64 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20  ned for each.** 
174d0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
174e0 74 69 6f 6e 5d 2e 20 20 53 65 74 74 69 6e 67 20  tion].  Setting 
174f0 61 20 6e 65 77 20 62 75 73 79 20 68 61 6e 64 6c  a new busy handl
17500 65 72 20 63 6c 65 61 72 73 20 61 6e 79 0a 2a 2a  er clears any.**
17510 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 74 20   previously set 
17520 68 61 6e 64 6c 65 72 2e 29 5e 20 20 5e 4e 6f 74  handler.)^  ^Not
17530 65 20 74 68 61 74 20 63 61 6c 6c 69 6e 67 20 5b  e that calling [
17540 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d  sqlite3_busy_tim
17550 65 6f 75 74 28 29 5d 0a 2a 2a 20 77 69 6c 6c 20  eout()].** will 
17560 61 6c 73 6f 20 73 65 74 20 6f 72 20 63 6c 65 61  also set or clea
17570 72 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  r the busy handl
17580 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 62 75  er..**.** The bu
17590 73 79 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75  sy callback shou
175a0 6c 64 20 6e 6f 74 20 74 61 6b 65 20 61 6e 79 20  ld not take any 
175b0 61 63 74 69 6f 6e 73 20 77 68 69 63 68 20 6d 6f  actions which mo
175c0 64 69 66 79 20 74 68 65 0a 2a 2a 20 64 61 74 61  dify the.** data
175d0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
175e0 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65  that invoked the
175f0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 20 20   busy handler.  
17600 41 6e 79 20 73 75 63 68 20 61 63 74 69 6f 6e 73  Any such actions
17610 0a 2a 2a 20 72 65 73 75 6c 74 20 69 6e 20 75 6e  .** result in un
17620 64 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72  defined behavior
17630 2e 0a 2a 2a 20 0a 2a 2a 20 41 20 62 75 73 79 20  ..** .** A busy 
17640 68 61 6e 64 6c 65 72 20 6d 75 73 74 20 6e 6f 74  handler must not
17650 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62   close the datab
17660 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase connection.*
17670 2a 20 6f 72 20 5b 70 72 65 70 61 72 65 64 20 73  * or [prepared s
17680 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69  tatement] that i
17690 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20  nvoked the busy 
176a0 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 69 6e 74 20  handler..*/.int 
176b0 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e  sqlite3_busy_han
176c0 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69  dler(sqlite3*, i
176d0 6e 74 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 29  nt(*)(void*,int)
176e0 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  , void*);../*.**
176f0 20 43 41 50 49 33 52 45 46 3a 20 53 65 74 20 41   CAPI3REF: Set A
17700 20 42 75 73 79 20 54 69 6d 65 6f 75 74 0a 2a 2a   Busy Timeout.**
17710 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e  .** ^This routin
17720 65 20 73 65 74 73 20 61 20 5b 73 71 6c 69 74 65  e sets a [sqlite
17730 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 20 7c  3_busy_handler |
17740 20 62 75 73 79 20 68 61 6e 64 6c 65 72 5d 20 74   busy handler] t
17750 68 61 74 20 73 6c 65 65 70 73 0a 2a 2a 20 66 6f  hat sleeps.** fo
17760 72 20 61 20 73 70 65 63 69 66 69 65 64 20 61 6d  r a specified am
17770 6f 75 6e 74 20 6f 66 20 74 69 6d 65 20 77 68 65  ount of time whe
17780 6e 20 61 20 74 61 62 6c 65 20 69 73 20 6c 6f 63  n a table is loc
17790 6b 65 64 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c  ked.  ^The handl
177a0 65 72 0a 2a 2a 20 77 69 6c 6c 20 73 6c 65 65 70  er.** will sleep
177b0 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20   multiple times 
177c0 75 6e 74 69 6c 20 61 74 20 6c 65 61 73 74 20 22  until at least "
177d0 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73  ms" milliseconds
177e0 20 6f 66 20 73 6c 65 65 70 69 6e 67 0a 2a 2a 20   of sleeping.** 
177f0 68 61 76 65 20 61 63 63 75 6d 75 6c 61 74 65 64  have accumulated
17800 2e 20 20 5e 41 66 74 65 72 20 61 74 20 6c 65 61  .  ^After at lea
17810 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63  st "ms" millisec
17820 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67  onds of sleeping
17830 2c 0a 2a 2a 20 74 68 65 20 68 61 6e 64 6c 65 72  ,.** the handler
17840 20 72 65 74 75 72 6e 73 20 30 20 77 68 69 63 68   returns 0 which
17850 20 63 61 75 73 65 73 20 5b 73 71 6c 69 74 65 33   causes [sqlite3
17860 5f 73 74 65 70 28 29 5d 20 74 6f 20 72 65 74 75  _step()] to retu
17870 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55  rn.** [SQLITE_BU
17880 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49  SY] or [SQLITE_I
17890 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e 0a 2a  OERR_BLOCKED]..*
178a0 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 74 68  *.** ^Calling th
178b0 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20  is routine with 
178c0 61 6e 20 61 72 67 75 6d 65 6e 74 20 6c 65 73 73  an argument less
178d0 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74   than or equal t
178e0 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e 73 20  o zero.** turns 
178f0 6f 66 66 20 61 6c 6c 20 62 75 73 79 20 68 61 6e  off all busy han
17900 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  dlers..**.** ^(T
17910 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65  here can only be
17920 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68   a single busy h
17930 61 6e 64 6c 65 72 20 66 6f 72 20 61 20 70 61 72  andler for a par
17940 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61  ticular.** [data
17950 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
17960 20 61 6e 79 20 61 6e 79 20 67 69 76 65 6e 20 6d   any any given m
17970 6f 6d 65 6e 74 2e 20 20 49 66 20 61 6e 6f 74 68  oment.  If anoth
17980 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72 0a  er busy handler.
17990 2a 2a 20 77 61 73 20 64 65 66 69 6e 65 64 20 20  ** was defined  
179a0 28 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  (using [sqlite3_
179b0 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d 29  busy_handler()])
179c0 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e   prior to callin
179d0 67 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e  g.** this routin
179e0 65 2c 20 74 68 61 74 20 6f 74 68 65 72 20 62 75  e, that other bu
179f0 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20 63 6c  sy handler is cl
17a00 65 61 72 65 64 2e 29 5e 0a 2a 2f 0a 69 6e 74 20  eared.)^.*/.int 
17a10 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d  sqlite3_busy_tim
17a20 65 6f 75 74 28 73 71 6c 69 74 65 33 2a 2c 20 69  eout(sqlite3*, i
17a30 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  nt ms);../*.** C
17a40 41 50 49 33 52 45 46 3a 20 43 6f 6e 76 65 6e 69  API3REF: Conveni
17a50 65 6e 63 65 20 52 6f 75 74 69 6e 65 73 20 46 6f  ence Routines Fo
17a60 72 20 52 75 6e 6e 69 6e 67 20 51 75 65 72 69 65  r Running Querie
17a70 73 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20  s.**.** This is 
17a80 61 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61  a legacy interfa
17a90 63 65 20 74 68 61 74 20 69 73 20 70 72 65 73 65  ce that is prese
17aa0 72 76 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72  rved for backwar
17ab0 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ds compatibility
17ac0 2e 0a 2a 2a 20 55 73 65 20 6f 66 20 74 68 69 73  ..** Use of this
17ad0 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f   interface is no
17ae0 74 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a  t recommended..*
17af0 2a 0a 2a 2a 20 44 65 66 69 6e 69 74 69 6f 6e 3a  *.** Definition:
17b00 20 41 20 3c 62 3e 72 65 73 75 6c 74 20 74 61 62   A <b>result tab
17b10 6c 65 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f 72 79  le</b> is memory
17b20 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65 20   data structure 
17b30 63 72 65 61 74 65 64 20 62 79 20 74 68 65 0a 2a  created by the.*
17b40 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  * [sqlite3_get_t
17b50 61 62 6c 65 28 29 5d 20 69 6e 74 65 72 66 61 63  able()] interfac
17b60 65 2e 20 20 41 20 72 65 73 75 6c 74 20 74 61 62  e.  A result tab
17b70 6c 65 20 72 65 63 6f 72 64 73 20 74 68 65 0a 2a  le records the.*
17b80 2a 20 63 6f 6d 70 6c 65 74 65 20 71 75 65 72 79  * complete query
17b90 20 72 65 73 75 6c 74 73 20 66 72 6f 6d 20 6f 6e   results from on
17ba0 65 20 6f 72 20 6d 6f 72 65 20 71 75 65 72 69 65  e or more querie
17bb0 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62  s..**.** The tab
17bc0 6c 65 20 63 6f 6e 63 65 70 74 75 61 6c 6c 79 20  le conceptually 
17bd0 68 61 73 20 61 20 6e 75 6d 62 65 72 20 6f 66 20  has a number of 
17be0 72 6f 77 73 20 61 6e 64 20 63 6f 6c 75 6d 6e 73  rows and columns
17bf0 2e 20 20 42 75 74 0a 2a 2a 20 74 68 65 73 65 20  .  But.** these 
17c00 6e 75 6d 62 65 72 73 20 61 72 65 20 6e 6f 74 20  numbers are not 
17c10 70 61 72 74 20 6f 66 20 74 68 65 20 72 65 73 75  part of the resu
17c20 6c 74 20 74 61 62 6c 65 20 69 74 73 65 6c 66 2e  lt table itself.
17c30 20 20 54 68 65 73 65 0a 2a 2a 20 6e 75 6d 62 65    These.** numbe
17c40 72 73 20 61 72 65 20 6f 62 74 61 69 6e 65 64 20  rs are obtained 
17c50 73 65 70 61 72 61 74 65 6c 79 2e 20 20 4c 65 74  separately.  Let
17c60 20 4e 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72   N be the number
17c70 20 6f 66 20 72 6f 77 73 0a 2a 2a 20 61 6e 64 20   of rows.** and 
17c80 4d 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20  M be the number 
17c90 6f 66 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a  of columns..**.*
17ca0 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65  * A result table
17cb0 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20   is an array of 
17cc0 70 6f 69 6e 74 65 72 73 20 74 6f 20 7a 65 72 6f  pointers to zero
17cd0 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d  -terminated UTF-
17ce0 38 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68  8 strings..** Th
17cf0 65 72 65 20 61 72 65 20 28 4e 2b 31 29 2a 4d 20  ere are (N+1)*M 
17d00 65 6c 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20  elements in the 
17d10 61 72 72 61 79 2e 20 20 54 68 65 20 66 69 72 73  array.  The firs
17d20 74 20 4d 20 70 6f 69 6e 74 65 72 73 20 70 6f 69  t M pointers poi
17d30 6e 74 0a 2a 2a 20 74 6f 20 7a 65 72 6f 2d 74 65  nt.** to zero-te
17d40 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73  rminated strings
17d50 20 74 68 61 74 20 20 63 6f 6e 74 61 69 6e 20 74   that  contain t
17d60 68 65 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 20  he names of the 
17d70 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20  columns..** The 
17d80 72 65 6d 61 69 6e 69 6e 67 20 65 6e 74 72 69 65  remaining entrie
17d90 73 20 61 6c 6c 20 70 6f 69 6e 74 20 74 6f 20 71  s all point to q
17da0 75 65 72 79 20 72 65 73 75 6c 74 73 2e 20 20 4e  uery results.  N
17db0 55 4c 4c 20 76 61 6c 75 65 73 20 72 65 73 75 6c  ULL values resul
17dc0 74 0a 2a 2a 20 69 6e 20 4e 55 4c 4c 20 70 6f 69  t.** in NULL poi
17dd0 6e 74 65 72 73 2e 20 20 41 6c 6c 20 6f 74 68 65  nters.  All othe
17de0 72 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e 20  r values are in 
17df0 74 68 65 69 72 20 55 54 46 2d 38 20 7a 65 72 6f  their UTF-8 zero
17e00 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73  -terminated.** s
17e10 74 72 69 6e 67 20 72 65 70 72 65 73 65 6e 74 61  tring representa
17e20 74 69 6f 6e 20 61 73 20 72 65 74 75 72 6e 65 64  tion as returned
17e30 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c   by [sqlite3_col
17e40 75 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a  umn_text()]..**.
17e50 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c  ** A result tabl
17e60 65 20 6d 69 67 68 74 20 63 6f 6e 73 69 73 74 20  e might consist 
17e70 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6d  of one or more m
17e80 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
17e90 73 2e 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20  s..** It is not 
17ea0 73 61 66 65 20 74 6f 20 70 61 73 73 20 61 20 72  safe to pass a r
17eb0 65 73 75 6c 74 20 74 61 62 6c 65 20 64 69 72 65  esult table dire
17ec0 63 74 6c 79 20 74 6f 20 5b 73 71 6c 69 74 65 33  ctly to [sqlite3
17ed0 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 20 41 20 72  _free()]..** A r
17ee0 65 73 75 6c 74 20 74 61 62 6c 65 20 73 68 6f 75  esult table shou
17ef0 6c 64 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65  ld be deallocate
17f00 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
17f10 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 2e 0a  _free_table()]..
17f20 2a 2a 0a 2a 2a 20 5e 28 41 73 20 61 6e 20 65 78  **.** ^(As an ex
17f30 61 6d 70 6c 65 20 6f 66 20 74 68 65 20 72 65 73  ample of the res
17f40 75 6c 74 20 74 61 62 6c 65 20 66 6f 72 6d 61 74  ult table format
17f50 2c 20 73 75 70 70 6f 73 65 20 61 20 71 75 65 72  , suppose a quer
17f60 79 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 61  y result.** is a
17f70 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a  s follows:.**.**
17f80 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
17f90 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 4e 61 6d  e>.**        Nam
17fa0 65 20 20 20 20 20 20 20 20 7c 20 41 67 65 0a 2a  e        | Age.*
17fb0 2a 20 20 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d  *        -------
17fc0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
17fd0 0a 2a 2a 20 20 20 20 20 20 20 20 41 6c 69 63 65  .**        Alice
17fe0 20 20 20 20 20 20 20 7c 20 34 33 0a 2a 2a 20 20         | 43.**  
17ff0 20 20 20 20 20 20 42 6f 62 20 20 20 20 20 20 20        Bob       
18000 20 20 7c 20 32 38 0a 2a 2a 20 20 20 20 20 20 20    | 28.**       
18010 20 43 69 6e 64 79 20 20 20 20 20 20 20 7c 20 32   Cindy       | 2
18020 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  1.** </pre></blo
18030 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54  ckquote>.**.** T
18040 68 65 72 65 20 61 72 65 20 74 77 6f 20 63 6f 6c  here are two col
18050 75 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e 64 20 74  umn (M==2) and t
18060 68 72 65 65 20 72 6f 77 73 20 28 4e 3d 3d 33 29  hree rows (N==3)
18070 2e 20 20 54 68 75 73 20 74 68 65 0a 2a 2a 20 72  .  Thus the.** r
18080 65 73 75 6c 74 20 74 61 62 6c 65 20 68 61 73 20  esult table has 
18090 38 20 65 6e 74 72 69 65 73 2e 20 20 53 75 70 70  8 entries.  Supp
180a0 6f 73 65 20 74 68 65 20 72 65 73 75 6c 74 20 74  ose the result t
180b0 61 62 6c 65 20 69 73 20 73 74 6f 72 65 64 0a 2a  able is stored.*
180c0 2a 20 69 6e 20 61 6e 20 61 72 72 61 79 20 6e 61  * in an array na
180d0 6d 65 73 20 61 7a 52 65 73 75 6c 74 2e 20 20 54  mes azResult.  T
180e0 68 65 6e 20 61 7a 52 65 73 75 6c 74 20 68 6f 6c  hen azResult hol
180f0 64 73 20 74 68 69 73 20 63 6f 6e 74 65 6e 74 3a  ds this content:
18100 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
18110 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20  te><pre>.**     
18120 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
18130 30 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20  0] = "Name";.** 
18140 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
18150 23 39 31 3b 31 5d 20 3d 20 22 41 67 65 22 3b 0a  #91;1] = "Age";.
18160 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
18170 6c 74 26 23 39 31 3b 32 5d 20 3d 20 22 41 6c 69  lt&#91;2] = "Ali
18180 63 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  ce";.**        a
18190 7a 52 65 73 75 6c 74 26 23 39 31 3b 33 5d 20 3d  zResult&#91;3] =
181a0 20 22 34 33 22 3b 0a 2a 2a 20 20 20 20 20 20 20   "43";.**       
181b0 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 34 5d   azResult&#91;4]
181c0 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20 20 20 20   = "Bob";.**    
181d0 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
181e0 3b 35 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a 20 20  ;5] = "28";.**  
181f0 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
18200 39 31 3b 36 5d 20 3d 20 22 43 69 6e 64 79 22 3b  91;6] = "Cindy";
18210 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
18220 75 6c 74 26 23 39 31 3b 37 5d 20 3d 20 22 32 31  ult&#91;7] = "21
18230 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  ";.** </pre></bl
18240 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a  ockquote>)^.**.*
18250 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67  * ^The sqlite3_g
18260 65 74 5f 74 61 62 6c 65 28 29 20 66 75 6e 63 74  et_table() funct
18270 69 6f 6e 20 65 76 61 6c 75 61 74 65 73 20 6f 6e  ion evaluates on
18280 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d  e or more.** sem
18290 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65 64  icolon-separated
182a0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
182b0 69 6e 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d  in the zero-term
182c0 69 6e 61 74 65 64 20 55 54 46 2d 38 0a 2a 2a 20  inated UTF-8.** 
182d0 73 74 72 69 6e 67 20 6f 66 20 69 74 73 20 32 6e  string of its 2n
182e0 64 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20  d parameter and 
182f0 72 65 74 75 72 6e 73 20 61 20 72 65 73 75 6c 74  returns a result
18300 20 74 61 62 6c 65 20 74 6f 20 74 68 65 0a 2a 2a   table to the.**
18310 20 70 6f 69 6e 74 65 72 20 67 69 76 65 6e 20 69   pointer given i
18320 6e 20 69 74 73 20 33 72 64 20 70 61 72 61 6d 65  n its 3rd parame
18330 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72  ter..**.** After
18340 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
18350 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69   has finished wi
18360 74 68 20 74 68 65 20 72 65 73 75 6c 74 20 66 72  th the result fr
18370 6f 6d 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  om sqlite3_get_t
18380 61 62 6c 65 28 29 2c 0a 2a 2a 20 69 74 20 6d 75  able(),.** it mu
18390 73 74 20 70 61 73 73 20 74 68 65 20 72 65 73 75  st pass the resu
183a0 6c 74 20 74 61 62 6c 65 20 70 6f 69 6e 74 65 72  lt table pointer
183b0 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65   to sqlite3_free
183c0 5f 74 61 62 6c 65 28 29 20 69 6e 20 6f 72 64 65  _table() in orde
183d0 72 20 74 6f 0a 2a 2a 20 72 65 6c 65 61 73 65 20  r to.** release 
183e0 74 68 65 20 6d 65 6d 6f 72 79 20 74 68 61 74 20  the memory that 
183f0 77 61 73 20 6d 61 6c 6c 6f 63 65 64 2e 20 20 42  was malloced.  B
18400 65 63 61 75 73 65 20 6f 66 20 74 68 65 20 77 61  ecause of the wa
18410 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  y the.** [sqlite
18420 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68 61 70 70  3_malloc()] happ
18430 65 6e 73 20 77 69 74 68 69 6e 20 73 71 6c 69 74  ens within sqlit
18440 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 20  e3_get_table(), 
18450 74 68 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66  the calling.** f
18460 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  unction must not
18470 20 74 72 79 20 74 6f 20 63 61 6c 6c 20 5b 73 71   try to call [sq
18480 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 64 69  lite3_free()] di
18490 72 65 63 74 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a  rectly.  Only.**
184a0 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74   [sqlite3_free_t
184b0 61 62 6c 65 28 29 5d 20 69 73 20 61 62 6c 65 20  able()] is able 
184c0 74 6f 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d  to release the m
184d0 65 6d 6f 72 79 20 70 72 6f 70 65 72 6c 79 20 61  emory properly a
184e0 6e 64 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a  nd safely..**.**
184f0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74   The sqlite3_get
18500 5f 74 61 62 6c 65 28 29 20 69 6e 74 65 72 66 61  _table() interfa
18510 63 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65  ce is implemente
18520 64 20 61 73 20 61 20 77 72 61 70 70 65 72 20 61  d as a wrapper a
18530 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  round.** [sqlite
18540 33 5f 65 78 65 63 28 29 5d 2e 20 20 54 68 65 20  3_exec()].  The 
18550 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
18560 65 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73  e() routine does
18570 20 6e 6f 74 20 68 61 76 65 20 61 63 63 65 73 73   not have access
18580 0a 2a 2a 20 74 6f 20 61 6e 79 20 69 6e 74 65 72  .** to any inter
18590 6e 61 6c 20 64 61 74 61 20 73 74 72 75 63 74 75  nal data structu
185a0 72 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20  res of SQLite.  
185b0 49 74 20 75 73 65 73 20 6f 6e 6c 79 20 74 68 65  It uses only the
185c0 20 70 75 62 6c 69 63 0a 2a 2a 20 69 6e 74 65 72   public.** inter
185d0 66 61 63 65 20 64 65 66 69 6e 65 64 20 68 65 72  face defined her
185e0 65 2e 20 20 41 73 20 61 20 63 6f 6e 73 65 71 75  e.  As a consequ
185f0 65 6e 63 65 2c 20 65 72 72 6f 72 73 20 74 68 61  ence, errors tha
18600 74 20 6f 63 63 75 72 20 69 6e 20 74 68 65 0a 2a  t occur in the.*
18610 2a 20 77 72 61 70 70 65 72 20 6c 61 79 65 72 20  * wrapper layer 
18620 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65 20 69  outside of the i
18630 6e 74 65 72 6e 61 6c 20 5b 73 71 6c 69 74 65 33  nternal [sqlite3
18640 5f 65 78 65 63 28 29 5d 20 63 61 6c 6c 20 61 72  _exec()] call ar
18650 65 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c 65 63 74  e not.** reflect
18660 65 64 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74  ed in subsequent
18670 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   calls to [sqlit
18680 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 6f 72  e3_errcode()] or
18690 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72  .** [sqlite3_err
186a0 6d 73 67 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73  msg()]..*/.int s
186b0 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
186c0 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
186d0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 6e 20            /* An 
186e0 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f  open database */
186f0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
18700 53 71 6c 2c 20 20 20 20 20 2f 2a 20 53 51 4c 20  Sql,     /* SQL 
18710 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64 20  to be evaluated 
18720 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 2a 70 61 7a  */.  char ***paz
18730 52 65 73 75 6c 74 2c 20 20 20 20 2f 2a 20 52 65  Result,    /* Re
18740 73 75 6c 74 73 20 6f 66 20 74 68 65 20 71 75 65  sults of the que
18750 72 79 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 52  ry */.  int *pnR
18760 6f 77 2c 20 20 20 20 20 20 20 20 20 20 20 2f 2a  ow,           /*
18770 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c   Number of resul
18780 74 20 72 6f 77 73 20 77 72 69 74 74 65 6e 20 68  t rows written h
18790 65 72 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e  ere */.  int *pn
187a0 43 6f 6c 75 6d 6e 2c 20 20 20 20 20 20 20 20 2f  Column,        /
187b0 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75  * Number of resu
187c0 6c 74 20 63 6f 6c 75 6d 6e 73 20 77 72 69 74 74  lt columns writt
187d0 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 63 68 61  en here */.  cha
187e0 72 20 2a 2a 70 7a 45 72 72 6d 73 67 20 20 20 20  r **pzErrmsg    
187f0 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20     /* Error msg 
18800 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a  written here */.
18810 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
18820 66 72 65 65 5f 74 61 62 6c 65 28 63 68 61 72 20  free_table(char 
18830 2a 2a 72 65 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a  **result);../*.*
18840 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6f 72 6d  * CAPI3REF: Form
18850 61 74 74 65 64 20 53 74 72 69 6e 67 20 50 72 69  atted String Pri
18860 6e 74 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a  nting Functions.
18870 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
18880 69 6e 65 73 20 61 72 65 20 77 6f 72 6b 2d 61 6c  ines are work-al
18890 69 6b 65 73 20 6f 66 20 74 68 65 20 22 70 72 69  ikes of the "pri
188a0 6e 74 66 28 29 22 20 66 61 6d 69 6c 79 20 6f 66  ntf()" family of
188b0 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 66 72   functions.** fr
188c0 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64 20  om the standard 
188d0 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 0a 2a 2a  C library..**.**
188e0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 70   ^The sqlite3_mp
188f0 72 69 6e 74 66 28 29 20 61 6e 64 20 73 71 6c 69  rintf() and sqli
18900 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 29 20 72  te3_vmprintf() r
18910 6f 75 74 69 6e 65 73 20 77 72 69 74 65 20 74 68  outines write th
18920 65 69 72 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69  eir.** results i
18930 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69  nto memory obtai
18940 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ned from [sqlite
18950 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 20  3_malloc()]..** 
18960 54 68 65 20 73 74 72 69 6e 67 73 20 72 65 74 75  The strings retu
18970 72 6e 65 64 20 62 79 20 74 68 65 73 65 20 74 77  rned by these tw
18980 6f 20 72 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c  o routines shoul
18990 64 20 62 65 0a 2a 2a 20 72 65 6c 65 61 73 65 64  d be.** released
189a0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 72 65   by [sqlite3_fre
189b0 65 28 29 5d 2e 20 20 5e 42 6f 74 68 20 72 6f 75  e()].  ^Both rou
189c0 74 69 6e 65 73 20 72 65 74 75 72 6e 20 61 0a 2a  tines return a.*
189d0 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69  * NULL pointer i
189e0 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  f [sqlite3_mallo
189f0 63 28 29 5d 20 69 73 20 75 6e 61 62 6c 65 20 74  c()] is unable t
18a00 6f 20 61 6c 6c 6f 63 61 74 65 20 65 6e 6f 75 67  o allocate enoug
18a10 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f 20 68  h.** memory to h
18a20 6f 6c 64 20 74 68 65 20 72 65 73 75 6c 74 69 6e  old the resultin
18a30 67 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  g string..**.** 
18a40 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6e  ^(The sqlite3_sn
18a50 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65  printf() routine
18a60 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 20 22   is similar to "
18a70 73 6e 70 72 69 6e 74 66 28 29 22 20 66 72 6f 6d  snprintf()" from
18a80 0a 2a 2a 20 74 68 65 20 73 74 61 6e 64 61 72 64  .** the standard
18a90 20 43 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65   C library.  The
18aa0 20 72 65 73 75 6c 74 20 69 73 20 77 72 69 74 74   result is writt
18ab0 65 6e 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 62  en into the.** b
18ac0 75 66 66 65 72 20 73 75 70 70 6c 69 65 64 20 61  uffer supplied a
18ad0 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  s the second par
18ae0 61 6d 65 74 65 72 20 77 68 6f 73 65 20 73 69 7a  ameter whose siz
18af0 65 20 69 73 20 67 69 76 65 6e 20 62 79 0a 2a 2a  e is given by.**
18b00 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
18b10 65 74 65 72 2e 20 4e 6f 74 65 20 74 68 61 74 20  eter. Note that 
18b20 74 68 65 20 6f 72 64 65 72 20 6f 66 20 74 68 65  the order of the
18b30 0a 2a 2a 20 66 69 72 73 74 20 74 77 6f 20 70 61  .** first two pa
18b40 72 61 6d 65 74 65 72 73 20 69 73 20 72 65 76 65  rameters is reve
18b50 72 73 65 64 20 66 72 6f 6d 20 73 6e 70 72 69 6e  rsed from snprin
18b60 74 66 28 29 2e 29 5e 20 20 54 68 69 73 20 69 73  tf().)^  This is
18b70 20 61 6e 0a 2a 2a 20 68 69 73 74 6f 72 69 63 61   an.** historica
18b80 6c 20 61 63 63 69 64 65 6e 74 20 74 68 61 74 20  l accident that 
18b90 63 61 6e 6e 6f 74 20 62 65 20 66 69 78 65 64 20  cannot be fixed 
18ba0 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67  without breaking
18bb0 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f  .** backwards co
18bc0 6d 70 61 74 69 62 69 6c 69 74 79 2e 20 20 5e 28  mpatibility.  ^(
18bd0 4e 6f 74 65 20 61 6c 73 6f 20 74 68 61 74 20 73  Note also that s
18be0 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
18bf0 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 20 70  ).** returns a p
18c00 6f 69 6e 74 65 72 20 74 6f 20 69 74 73 20 62 75  ointer to its bu
18c10 66 66 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20  ffer instead of 
18c20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a  the number of.**
18c30 20 63 68 61 72 61 63 74 65 72 73 20 61 63 74 75   characters actu
18c40 61 6c 6c 79 20 77 72 69 74 74 65 6e 20 69 6e 74  ally written int
18c50 6f 20 74 68 65 20 62 75 66 66 65 72 2e 29 5e 20  o the buffer.)^ 
18c60 20 57 65 20 61 64 6d 69 74 20 74 68 61 74 0a 2a   We admit that.*
18c70 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  * the number of 
18c80 63 68 61 72 61 63 74 65 72 73 20 77 72 69 74 74  characters writt
18c90 65 6e 20 77 6f 75 6c 64 20 62 65 20 61 20 6d 6f  en would be a mo
18ca0 72 65 20 75 73 65 66 75 6c 20 72 65 74 75 72 6e  re useful return
18cb0 0a 2a 2a 20 76 61 6c 75 65 20 62 75 74 20 77 65  .** value but we
18cc0 20 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65 20 74   cannot change t
18cd0 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
18ce0 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e 70  n of sqlite3_snp
18cf0 72 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77 20 77  rintf().** now w
18d00 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 20  ithout breaking 
18d10 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a  compatibility..*
18d20 2a 0a 2a 2a 20 5e 41 73 20 6c 6f 6e 67 20 61 73  *.** ^As long as
18d30 20 74 68 65 20 62 75 66 66 65 72 20 73 69 7a 65   the buffer size
18d40 20 69 73 20 67 72 65 61 74 65 72 20 74 68 61 6e   is greater than
18d50 20 7a 65 72 6f 2c 20 73 71 6c 69 74 65 33 5f 73   zero, sqlite3_s
18d60 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 67 75 61  nprintf().** gua
18d70 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 68 65  rantees that the
18d80 20 62 75 66 66 65 72 20 69 73 20 61 6c 77 61 79   buffer is alway
18d90 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  s zero-terminate
18da0 64 2e 20 20 5e 54 68 65 20 66 69 72 73 74 0a 2a  d.  ^The first.*
18db0 2a 20 70 61 72 61 6d 65 74 65 72 20 22 6e 22 20  * parameter "n" 
18dc0 69 73 20 74 68 65 20 74 6f 74 61 6c 20 73 69 7a  is the total siz
18dd0 65 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 2c  e of the buffer,
18de0 20 69 6e 63 6c 75 64 69 6e 67 20 73 70 61 63 65   including space
18df0 20 66 6f 72 0a 2a 2a 20 74 68 65 20 7a 65 72 6f   for.** the zero
18e00 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 53 6f   terminator.  So
18e10 20 74 68 65 20 6c 6f 6e 67 65 73 74 20 73 74 72   the longest str
18e20 69 6e 67 20 74 68 61 74 20 63 61 6e 20 62 65 20  ing that can be 
18e30 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a 20 77 72  completely.** wr
18e40 69 74 74 65 6e 20 77 69 6c 6c 20 62 65 20 6e 2d  itten will be n-
18e50 31 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a  1 characters..**
18e60 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
18e70 5f 76 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75  _vsnprintf() rou
18e80 74 69 6e 65 20 69 73 20 61 20 76 61 72 61 72 67  tine is a vararg
18e90 73 20 76 65 72 73 69 6f 6e 20 6f 66 20 73 71 6c  s version of sql
18ea0 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 2e  ite3_snprintf().
18eb0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
18ec0 74 69 6e 65 73 20 61 6c 6c 20 69 6d 70 6c 65 6d  tines all implem
18ed0 65 6e 74 20 73 6f 6d 65 20 61 64 64 69 74 69 6f  ent some additio
18ee0 6e 61 6c 20 66 6f 72 6d 61 74 74 69 6e 67 0a 2a  nal formatting.*
18ef0 2a 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 20 61  * options that a
18f00 72 65 20 75 73 65 66 75 6c 20 66 6f 72 20 63 6f  re useful for co
18f10 6e 73 74 72 75 63 74 69 6e 67 20 53 51 4c 20 73  nstructing SQL s
18f20 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 41 6c  tatements..** Al
18f30 6c 20 6f 66 20 74 68 65 20 75 73 75 61 6c 20 70  l of the usual p
18f40 72 69 6e 74 66 28 29 20 66 6f 72 6d 61 74 74 69  rintf() formatti
18f50 6e 67 20 6f 70 74 69 6f 6e 73 20 61 70 70 6c 79  ng options apply
18f60 2e 20 20 49 6e 20 61 64 64 69 74 69 6f 6e 2c 20  .  In addition, 
18f70 74 68 65 72 65 0a 2a 2a 20 69 73 20 61 72 65 20  there.** is are 
18f80 22 25 71 22 2c 20 22 25 51 22 2c 20 61 6e 64 20  "%q", "%Q", and 
18f90 22 25 7a 22 20 6f 70 74 69 6f 6e 73 2e 0a 2a 2a  "%z" options..**
18fa0 0a 2a 2a 20 5e 28 54 68 65 20 25 71 20 6f 70 74  .** ^(The %q opt
18fb0 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25  ion works like %
18fc0 73 20 69 6e 20 74 68 61 74 20 69 74 20 73 75 62  s in that it sub
18fd0 73 74 69 74 75 74 65 73 20 61 20 6e 75 6c 2d 74  stitutes a nul-t
18fe0 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72  erminated.** str
18ff0 69 6e 67 20 66 72 6f 6d 20 74 68 65 20 61 72 67  ing from the arg
19000 75 6d 65 6e 74 20 6c 69 73 74 2e 20 20 42 75 74  ument list.  But
19010 20 25 71 20 61 6c 73 6f 20 64 6f 75 62 6c 65 73   %q also doubles
19020 20 65 76 65 72 79 20 27 5c 27 27 20 63 68 61 72   every '\'' char
19030 61 63 74 65 72 2e 0a 2a 2a 20 25 71 20 69 73 20  acter..** %q is 
19040 64 65 73 69 67 6e 65 64 20 66 6f 72 20 75 73 65  designed for use
19050 20 69 6e 73 69 64 65 20 61 20 73 74 72 69 6e 67   inside a string
19060 20 6c 69 74 65 72 61 6c 2e 29 5e 20 20 42 79 20   literal.)^  By 
19070 64 6f 75 62 6c 69 6e 67 20 65 61 63 68 20 27 5c  doubling each '\
19080 27 27 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 20  ''.** character 
19090 69 74 20 65 73 63 61 70 65 73 20 74 68 61 74 20  it escapes that 
190a0 63 68 61 72 61 63 74 65 72 20 61 6e 64 20 61 6c  character and al
190b0 6c 6f 77 73 20 69 74 20 74 6f 20 62 65 20 69 6e  lows it to be in
190c0 73 65 72 74 65 64 20 69 6e 74 6f 0a 2a 2a 20 74  serted into.** t
190d0 68 65 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a  he string..**.**
190e0 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 73   For example, as
190f0 73 75 6d 65 20 74 68 65 20 73 74 72 69 6e 67 20  sume the string 
19100 76 61 72 69 61 62 6c 65 20 7a 54 65 78 74 20 63  variable zText c
19110 6f 6e 74 61 69 6e 73 20 74 65 78 74 20 61 73 20  ontains text as 
19120 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c  follows:.**.** <
19130 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
19140 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 54 65 78 74  .**  char *zText
19150 20 3d 20 22 49 74 27 73 20 61 20 68 61 70 70 79   = "It's a happy
19160 20 64 61 79 21 22 3b 0a 2a 2a 20 3c 2f 70 72 65   day!";.** </pre
19170 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
19180 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e 20 75 73 65  *.** One can use
19190 20 74 68 69 73 20 74 65 78 74 20 69 6e 20 61 6e   this text in an
191a0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61   SQL statement a
191b0 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a  s follows:.**.**
191c0 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
191d0 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51  e>.**  char *zSQ
191e0 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69  L = sqlite3_mpri
191f0 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f  ntf("INSERT INTO
19200 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28 27 25   table VALUES('%
19210 71 27 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a  q')", zText);.**
19220 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64    sqlite3_exec(d
19230 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30  b, zSQL, 0, 0, 0
19240 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66  );.**  sqlite3_f
19250 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f  ree(zSQL);.** </
19260 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
19270 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20  >.**.** Because 
19280 74 68 65 20 25 71 20 66 6f 72 6d 61 74 20 73 74  the %q format st
19290 72 69 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68  ring is used, th
192a0 65 20 27 5c 27 27 20 63 68 61 72 61 63 74 65 72  e '\'' character
192b0 20 69 6e 20 7a 54 65 78 74 0a 2a 2a 20 69 73 20   in zText.** is 
192c0 65 73 63 61 70 65 64 20 61 6e 64 20 74 68 65 20  escaped and the 
192d0 53 51 4c 20 67 65 6e 65 72 61 74 65 64 20 69 73  SQL generated is
192e0 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a   as follows:.**.
192f0 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
19300 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20  pre>.**  INSERT 
19310 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55  INTO table1 VALU
19320 45 53 28 27 49 74 27 27 73 20 61 20 68 61 70 70  ES('It''s a happ
19330 79 20 64 61 79 21 27 29 0a 2a 2a 20 3c 2f 70 72  y day!').** </pr
19340 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
19350 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 63 6f  **.** This is co
19360 72 72 65 63 74 2e 20 20 48 61 64 20 77 65 20 75  rrect.  Had we u
19370 73 65 64 20 25 73 20 69 6e 73 74 65 61 64 20 6f  sed %s instead o
19380 66 20 25 71 2c 20 74 68 65 20 67 65 6e 65 72 61  f %q, the genera
19390 74 65 64 20 53 51 4c 0a 2a 2a 20 77 6f 75 6c 64  ted SQL.** would
193a0 20 68 61 76 65 20 6c 6f 6f 6b 65 64 20 6c 69 6b   have looked lik
193b0 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62  e this:.**.** <b
193c0 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
193d0 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20  **  INSERT INTO 
193e0 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49  table1 VALUES('I
193f0 74 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21  t's a happy day!
19400 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  ');.** </pre></b
19410 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
19420 20 54 68 69 73 20 73 65 63 6f 6e 64 20 65 78 61   This second exa
19430 6d 70 6c 65 20 69 73 20 61 6e 20 53 51 4c 20 73  mple is an SQL s
19440 79 6e 74 61 78 20 65 72 72 6f 72 2e 20 20 41 73  yntax error.  As
19450 20 61 20 67 65 6e 65 72 61 6c 20 72 75 6c 65 20   a general rule 
19460 79 6f 75 20 73 68 6f 75 6c 64 0a 2a 2a 20 61 6c  you should.** al
19470 77 61 79 73 20 75 73 65 20 25 71 20 69 6e 73 74  ways use %q inst
19480 65 61 64 20 6f 66 20 25 73 20 77 68 65 6e 20 69  ead of %s when i
19490 6e 73 65 72 74 69 6e 67 20 74 65 78 74 20 69 6e  nserting text in
194a0 74 6f 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65  to a string lite
194b0 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ral..**.** ^(The
194c0 20 25 51 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73   %Q option works
194d0 20 6c 69 6b 65 20 25 71 20 65 78 63 65 70 74 20   like %q except 
194e0 69 74 20 61 6c 73 6f 20 61 64 64 73 20 73 69 6e  it also adds sin
194f0 67 6c 65 20 71 75 6f 74 65 73 20 61 72 6f 75 6e  gle quotes aroun
19500 64 0a 2a 2a 20 74 68 65 20 6f 75 74 73 69 64 65  d.** the outside
19510 20 6f 66 20 74 68 65 20 74 6f 74 61 6c 20 73 74   of the total st
19520 72 69 6e 67 2e 20 20 41 64 64 69 74 69 6f 6e 61  ring.  Additiona
19530 6c 6c 79 2c 20 69 66 20 74 68 65 20 70 61 72 61  lly, if the para
19540 6d 65 74 65 72 20 69 6e 20 74 68 65 0a 2a 2a 20  meter in the.** 
19550 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 20 69 73  argument list is
19560 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c   a NULL pointer,
19570 20 25 51 20 73 75 62 73 74 69 74 75 74 65 73 20   %Q substitutes 
19580 74 68 65 20 74 65 78 74 20 22 4e 55 4c 4c 22 20  the text "NULL" 
19590 28 77 69 74 68 6f 75 74 0a 2a 2a 20 73 69 6e 67  (without.** sing
195a0 6c 65 20 71 75 6f 74 65 73 29 2e 29 5e 20 20 53  le quotes).)^  S
195b0 6f 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20  o, for example, 
195c0 6f 6e 65 20 63 6f 75 6c 64 20 73 61 79 3a 0a 2a  one could say:.*
195d0 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
195e0 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20  ><pre>.**  char 
195f0 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f  *zSQL = sqlite3_
19600 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20  mprintf("INSERT 
19610 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45  INTO table VALUE
19620 53 28 25 51 29 22 2c 20 7a 54 65 78 74 29 3b 0a  S(%Q)", zText);.
19630 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63  **  sqlite3_exec
19640 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c  (db, zSQL, 0, 0,
19650 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33   0);.**  sqlite3
19660 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20  _free(zSQL);.** 
19670 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
19680 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f  te>.**.** The co
19690 64 65 20 61 62 6f 76 65 20 77 69 6c 6c 20 72 65  de above will re
196a0 6e 64 65 72 20 61 20 63 6f 72 72 65 63 74 20 53  nder a correct S
196b0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20  QL statement in 
196c0 74 68 65 20 7a 53 51 4c 0a 2a 2a 20 76 61 72 69  the zSQL.** vari
196d0 61 62 6c 65 20 65 76 65 6e 20 69 66 20 74 68 65  able even if the
196e0 20 7a 54 65 78 74 20 76 61 72 69 61 62 6c 65 20   zText variable 
196f0 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
19700 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 22  r..**.** ^(The "
19710 25 7a 22 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f  %z" formatting o
19720 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65  ption works like
19730 20 22 25 73 22 20 62 75 74 20 77 69 74 68 20 74   "%s" but with t
19740 68 65 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 20 74  he.** addition t
19750 68 61 74 20 61 66 74 65 72 20 74 68 65 20 73 74  hat after the st
19760 72 69 6e 67 20 68 61 73 20 62 65 65 6e 20 72 65  ring has been re
19770 61 64 20 61 6e 64 20 63 6f 70 69 65 64 20 69 6e  ad and copied in
19780 74 6f 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74  to.** the result
19790 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  , [sqlite3_free(
197a0 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20  )] is called on 
197b0 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67  the input string
197c0 2e 29 5e 0a 2a 2f 0a 63 68 61 72 20 2a 73 71 6c  .)^.*/.char *sql
197d0 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 63 6f 6e  ite3_mprintf(con
197e0 73 74 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 63  st char*,...);.c
197f0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 6d 70  har *sqlite3_vmp
19800 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72  rintf(const char
19810 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 63 68 61  *, va_list);.cha
19820 72 20 2a 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  r *sqlite3_snpri
19830 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f  ntf(int,char*,co
19840 6e 73 74 20 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b  nst char*, ...);
19850 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76  .char *sqlite3_v
19860 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61  snprintf(int,cha
19870 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  r*,const char*, 
19880 76 61 5f 6c 69 73 74 29 3b 0a 0a 2f 2a 0a 2a 2a  va_list);../*.**
19890 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72   CAPI3REF: Memor
198a0 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 53 75 62  y Allocation Sub
198b0 73 79 73 74 65 6d 0a 2a 2a 0a 2a 2a 20 54 68 65  system.**.** The
198c0 20 53 51 4c 69 74 65 20 63 6f 72 65 20 75 73 65   SQLite core use
198d0 73 20 74 68 65 73 65 20 74 68 72 65 65 20 72 6f  s these three ro
198e0 75 74 69 6e 65 73 20 66 6f 72 20 61 6c 6c 20 6f  utines for all o
198f0 66 20 69 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74  f its own.** int
19900 65 72 6e 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c  ernal memory all
19910 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 20 22  ocation needs. "
19920 43 6f 72 65 22 20 69 6e 20 74 68 65 20 70 72 65  Core" in the pre
19930 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 0a 2a  vious sentence.*
19940 2a 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75  * does not inclu
19950 64 65 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73  de operating-sys
19960 74 65 6d 20 73 70 65 63 69 66 69 63 20 56 46 53  tem specific VFS
19970 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e   implementation.
19980 20 20 54 68 65 0a 2a 2a 20 57 69 6e 64 6f 77 73    The.** Windows
19990 20 56 46 53 20 75 73 65 73 20 6e 61 74 69 76 65   VFS uses native
199a0 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72   malloc() and fr
199b0 65 65 28 29 20 66 6f 72 20 73 6f 6d 65 20 6f 70  ee() for some op
199c0 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20  erations..**.** 
199d0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c  ^The sqlite3_mal
199e0 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65 20 72 65  loc() routine re
199f0 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
19a00 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66  to a block.** of
19a10 20 6d 65 6d 6f 72 79 20 61 74 20 6c 65 61 73 74   memory at least
19a20 20 4e 20 62 79 74 65 73 20 69 6e 20 6c 65 6e 67   N bytes in leng
19a30 74 68 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74  th, where N is t
19a40 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  he parameter..**
19a50 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c   ^If sqlite3_mal
19a60 6c 6f 63 28 29 20 69 73 20 75 6e 61 62 6c 65 20  loc() is unable 
19a70 74 6f 20 6f 62 74 61 69 6e 20 73 75 66 66 69 63  to obtain suffic
19a80 69 65 6e 74 20 66 72 65 65 0a 2a 2a 20 6d 65 6d  ient free.** mem
19a90 6f 72 79 2c 20 69 74 20 72 65 74 75 72 6e 73 20  ory, it returns 
19aa0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20  a NULL pointer. 
19ab0 20 5e 49 66 20 74 68 65 20 70 61 72 61 6d 65 74   ^If the paramet
19ac0 65 72 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  er N to.** sqlit
19ad0 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 7a  e3_malloc() is z
19ae0 65 72 6f 20 6f 72 20 6e 65 67 61 74 69 76 65 20  ero or negative 
19af0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 6d 61 6c  then sqlite3_mal
19b00 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a  loc() returns.**
19b10 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
19b20 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20  .**.** ^Calling 
19b30 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 77  sqlite3_free() w
19b40 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20 70 72  ith a pointer pr
19b50 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65  eviously returne
19b60 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f  d.** by sqlite3_
19b70 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69  malloc() or sqli
19b80 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65  te3_realloc() re
19b90 6c 65 61 73 65 73 20 74 68 61 74 20 6d 65 6d 6f  leases that memo
19ba0 72 79 20 73 6f 0a 2a 2a 20 74 68 61 74 20 69 74  ry so.** that it
19bb0 20 6d 69 67 68 74 20 62 65 20 72 65 75 73 65 64   might be reused
19bc0 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
19bd0 66 72 65 65 28 29 20 72 6f 75 74 69 6e 65 20 69  free() routine i
19be0 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69 66 20  s.** a no-op if 
19bf0 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61  is called with a
19c00 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20   NULL pointer.  
19c10 50 61 73 73 69 6e 67 20 61 20 4e 55 4c 4c 20 70  Passing a NULL p
19c20 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 73 71 6c  ointer.** to sql
19c30 69 74 65 33 5f 66 72 65 65 28 29 20 69 73 20 68  ite3_free() is h
19c40 61 72 6d 6c 65 73 73 2e 20 20 41 66 74 65 72 20  armless.  After 
19c50 62 65 69 6e 67 20 66 72 65 65 64 2c 20 6d 65 6d  being freed, mem
19c60 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 65  ory.** should ne
19c70 69 74 68 65 72 20 62 65 20 72 65 61 64 20 6e 6f  ither be read no
19c80 72 20 77 72 69 74 74 65 6e 2e 20 20 45 76 65 6e  r written.  Even
19c90 20 72 65 61 64 69 6e 67 20 70 72 65 76 69 6f 75   reading previou
19ca0 73 6c 79 20 66 72 65 65 64 0a 2a 2a 20 6d 65 6d  sly freed.** mem
19cb0 6f 72 79 20 6d 69 67 68 74 20 72 65 73 75 6c 74  ory might result
19cc0 20 69 6e 20 61 20 73 65 67 6d 65 6e 74 61 74 69   in a segmentati
19cd0 6f 6e 20 66 61 75 6c 74 20 6f 72 20 6f 74 68 65  on fault or othe
19ce0 72 20 73 65 76 65 72 65 20 65 72 72 6f 72 2e 0a  r severe error..
19cf0 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f 72 72 75 70  ** Memory corrup
19d00 74 69 6f 6e 2c 20 61 20 73 65 67 6d 65 6e 74 61  tion, a segmenta
19d10 74 69 6f 6e 20 66 61 75 6c 74 2c 20 6f 72 20 6f  tion fault, or o
19d20 74 68 65 72 20 73 65 76 65 72 65 20 65 72 72 6f  ther severe erro
19d30 72 0a 2a 2a 20 6d 69 67 68 74 20 72 65 73 75 6c  r.** might resul
19d40 74 20 69 66 20 73 71 6c 69 74 65 33 5f 66 72 65  t if sqlite3_fre
19d50 65 28 29 20 69 73 20 63 61 6c 6c 65 64 20 77 69  e() is called wi
19d60 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f  th a non-NULL po
19d70 69 6e 74 65 72 20 74 68 61 74 0a 2a 2a 20 77 61  inter that.** wa
19d80 73 20 6e 6f 74 20 6f 62 74 61 69 6e 65 64 20 66  s not obtained f
19d90 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  rom sqlite3_mall
19da0 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  oc() or sqlite3_
19db0 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a  realloc()..**.**
19dc0 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f 72   ^(The sqlite3_r
19dd0 65 61 6c 6c 6f 63 28 29 20 69 6e 74 65 72 66 61  ealloc() interfa
19de0 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72  ce attempts to r
19df0 65 73 69 7a 65 20 61 0a 2a 2a 20 70 72 69 6f 72  esize a.** prior
19e00 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
19e10 6f 6e 20 74 6f 20 62 65 20 61 74 20 6c 65 61 73  on to be at leas
19e20 74 20 4e 20 62 79 74 65 73 2c 20 77 68 65 72 65  t N bytes, where
19e30 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20 73 65 63   N is the.** sec
19e40 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20  ond parameter.  
19e50 54 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  The memory alloc
19e60 61 74 69 6f 6e 20 74 6f 20 62 65 20 72 65 73 69  ation to be resi
19e70 7a 65 64 20 69 73 20 74 68 65 20 66 69 72 73 74  zed is the first
19e80 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 29 5e  .** parameter.)^
19e90 20 5e 20 49 66 20 74 68 65 20 66 69 72 73 74 20   ^ If the first 
19ea0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
19eb0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a  ite3_realloc().*
19ec0 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  * is a NULL poin
19ed0 74 65 72 20 74 68 65 6e 20 69 74 73 20 62 65 68  ter then its beh
19ee0 61 76 69 6f 72 20 69 73 20 69 64 65 6e 74 69 63  avior is identic
19ef0 61 6c 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a  al to calling.**
19f00 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
19f10 4e 29 20 77 68 65 72 65 20 4e 20 69 73 20 74 68  N) where N is th
19f20 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
19f30 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65  er to sqlite3_re
19f40 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 5e 49 66 20  alloc()..** ^If 
19f50 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
19f60 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
19f70 72 65 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72  realloc() is zer
19f80 6f 20 6f 72 0a 2a 2a 20 6e 65 67 61 74 69 76 65  o or.** negative
19f90 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
19fa0 6f 72 20 69 73 20 65 78 61 63 74 6c 79 20 74 68  or is exactly th
19fb0 65 20 73 61 6d 65 20 61 73 20 63 61 6c 6c 69 6e  e same as callin
19fc0 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 72 65  g.** sqlite3_fre
19fd0 65 28 50 29 20 77 68 65 72 65 20 50 20 69 73 20  e(P) where P is 
19fe0 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
19ff0 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72  ter to sqlite3_r
1a000 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 5e 73 71  ealloc()..** ^sq
1a010 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20  lite3_realloc() 
1a020 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
1a030 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20 61 6c  r to a memory al
1a040 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 61  location.** of a
1a050 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20  t least N bytes 
1a060 69 6e 20 73 69 7a 65 20 6f 72 20 4e 55 4c 4c 20  in size or NULL 
1a070 69 66 20 73 75 66 66 69 63 69 65 6e 74 20 6d 65  if sufficient me
1a080 6d 6f 72 79 20 69 73 20 75 6e 61 76 61 69 6c 61  mory is unavaila
1a090 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 4d 20 69 73  ble..** ^If M is
1a0a0 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
1a0b0 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f   prior allocatio
1a0c0 6e 2c 20 74 68 65 6e 20 6d 69 6e 28 4e 2c 4d 29  n, then min(N,M)
1a0d0 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 74 68 65   bytes.** of the
1a0e0 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f   prior allocatio
1a0f0 6e 20 61 72 65 20 63 6f 70 69 65 64 20 69 6e 74  n are copied int
1a100 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20  o the beginning 
1a110 6f 66 20 62 75 66 66 65 72 20 72 65 74 75 72 6e  of buffer return
1a120 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33  ed.** by sqlite3
1a130 5f 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20 74  _realloc() and t
1a140 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74  he prior allocat
1a150 69 6f 6e 20 69 73 20 66 72 65 65 64 2e 0a 2a 2a  ion is freed..**
1a160 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 72 65 61   ^If sqlite3_rea
1a170 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 20 4e  lloc() returns N
1a180 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20 70 72  ULL, then the pr
1a190 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a  ior allocation.*
1a1a0 2a 20 69 73 20 6e 6f 74 20 66 72 65 65 64 2e 0a  * is not freed..
1a1b0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72  **.** ^The memor
1a1c0 79 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  y returned by sq
1a1d0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 61  lite3_malloc() a
1a1e0 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  nd sqlite3_reall
1a1f0 6f 63 28 29 0a 2a 2a 20 69 73 20 61 6c 77 61 79  oc().** is alway
1a200 73 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 74 20  s aligned to at 
1a210 6c 65 61 73 74 20 61 6e 20 38 20 62 79 74 65 20  least an 8 byte 
1a220 62 6f 75 6e 64 61 72 79 2c 20 6f 72 20 74 6f 20  boundary, or to 
1a230 61 0a 2a 2a 20 34 20 62 79 74 65 20 62 6f 75 6e  a.** 4 byte boun
1a240 64 61 72 79 20 69 66 20 74 68 65 20 5b 53 51 4c  dary if the [SQL
1a250 49 54 45 5f 34 5f 42 59 54 45 5f 41 4c 49 47 4e  ITE_4_BYTE_ALIGN
1a260 45 44 5f 4d 41 4c 4c 4f 43 5d 20 63 6f 6d 70 69  ED_MALLOC] compi
1a270 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f  le-time.** optio
1a280 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a  n is used..**.**
1a290 20 49 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69   In SQLite versi
1a2a0 6f 6e 20 33 2e 35 2e 30 20 61 6e 64 20 33 2e 35  on 3.5.0 and 3.5
1a2b0 2e 31 2c 20 69 74 20 77 61 73 20 70 6f 73 73 69  .1, it was possi
1a2c0 62 6c 65 20 74 6f 20 64 65 66 69 6e 65 0a 2a 2a  ble to define.**
1a2d0 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 4d 49 54   the SQLITE_OMIT
1a2e0 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54 49  _MEMORY_ALLOCATI
1a2f0 4f 4e 20 77 68 69 63 68 20 77 6f 75 6c 64 20 63  ON which would c
1a300 61 75 73 65 20 74 68 65 20 62 75 69 6c 74 2d 69  ause the built-i
1a310 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  n.** implementat
1a320 69 6f 6e 20 6f 66 20 74 68 65 73 65 20 72 6f 75  ion of these rou
1a330 74 69 6e 65 73 20 74 6f 20 62 65 20 6f 6d 69 74  tines to be omit
1a340 74 65 64 2e 20 20 54 68 61 74 20 63 61 70 61 62  ted.  That capab
1a350 69 6c 69 74 79 0a 2a 2a 20 69 73 20 6e 6f 20 6c  ility.** is no l
1a360 6f 6e 67 65 72 20 70 72 6f 76 69 64 65 64 2e 20  onger provided. 
1a370 20 4f 6e 6c 79 20 62 75 69 6c 74 2d 69 6e 20 6d   Only built-in m
1a380 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73  emory allocators
1a390 20 63 61 6e 20 62 65 20 75 73 65 64 2e 0a 2a 2a   can be used..**
1a3a0 0a 2a 2a 20 50 72 69 6f 72 20 74 6f 20 53 51 4c  .** Prior to SQL
1a3b0 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e  ite version 3.7.
1a3c0 31 30 2c 20 74 68 65 20 57 69 6e 64 6f 77 73 20  10, the Windows 
1a3d0 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79  OS interface lay
1a3e0 65 72 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 68 65  er called.** the
1a3f0 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29   system malloc()
1a400 20 61 6e 64 20 66 72 65 65 28 29 20 64 69 72 65   and free() dire
1a410 63 74 6c 79 20 77 68 65 6e 20 63 6f 6e 76 65 72  ctly when conver
1a420 74 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65  ting.** filename
1a430 73 20 62 65 74 77 65 65 6e 20 74 68 65 20 55 54  s between the UT
1a440 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 75 73 65  F-8 encoding use
1a450 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61  d by SQLite.** a
1a460 6e 64 20 77 68 61 74 65 76 65 72 20 66 69 6c 65  nd whatever file
1a470 6e 61 6d 65 20 65 6e 63 6f 64 69 6e 67 20 69 73  name encoding is
1a480 20 75 73 65 64 20 62 79 20 74 68 65 20 70 61 72   used by the par
1a490 74 69 63 75 6c 61 72 20 57 69 6e 64 6f 77 73 0a  ticular Windows.
1a4a0 2a 2a 20 69 6e 73 74 61 6c 6c 61 74 69 6f 6e 2e  ** installation.
1a4b0 20 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74    Memory allocat
1a4c0 69 6f 6e 20 65 72 72 6f 72 73 20 77 65 72 65 20  ion errors were 
1a4d0 64 65 74 65 63 74 65 64 2c 20 62 75 74 0a 2a 2a  detected, but.**
1a4e0 20 74 68 65 79 20 77 65 72 65 20 72 65 70 6f 72   they were repor
1a4f0 74 65 64 20 62 61 63 6b 20 61 73 20 5b 53 51 4c  ted back as [SQL
1a500 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f 72  ITE_CANTOPEN] or
1a510 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52  .** [SQLITE_IOER
1a520 52 5d 20 72 61 74 68 65 72 20 74 68 61 6e 20 5b  R] rather than [
1a530 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a  SQLITE_NOMEM]..*
1a540 2a 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65 72  *.** The pointer
1a550 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 5b 73   arguments to [s
1a560 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 61  qlite3_free()] a
1a570 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  nd [sqlite3_real
1a580 6c 6f 63 28 29 5d 0a 2a 2a 20 6d 75 73 74 20 62  loc()].** must b
1a590 65 20 65 69 74 68 65 72 20 4e 55 4c 4c 20 6f 72  e either NULL or
1a5a0 20 65 6c 73 65 20 70 6f 69 6e 74 65 72 73 20 6f   else pointers o
1a5b0 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 20 70  btained from a p
1a5c0 72 69 6f 72 0a 2a 2a 20 69 6e 76 6f 63 61 74 69  rior.** invocati
1a5d0 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d  on of [sqlite3_m
1a5e0 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71 6c  alloc()] or [sql
1a5f0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20  ite3_realloc()] 
1a600 74 68 61 74 20 68 61 76 65 0a 2a 2a 20 6e 6f 74  that have.** not
1a610 20 79 65 74 20 62 65 65 6e 20 72 65 6c 65 61 73   yet been releas
1a620 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70  ed..**.** The ap
1a630 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e  plication must n
1a640 6f 74 20 72 65 61 64 20 6f 72 20 77 72 69 74 65  ot read or write
1a650 20 61 6e 79 20 70 61 72 74 20 6f 66 0a 2a 2a 20   any part of.** 
1a660 61 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72  a block of memor
1a670 79 20 61 66 74 65 72 20 69 74 20 68 61 73 20 62  y after it has b
1a680 65 65 6e 20 72 65 6c 65 61 73 65 64 20 75 73 69  een released usi
1a690 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  ng.** [sqlite3_f
1a6a0 72 65 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  ree()] or [sqlit
1a6b0 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e 0a 2a  e3_realloc()]..*
1a6c0 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  /.void *sqlite3_
1a6d0 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76 6f 69  malloc(int);.voi
1a6e0 64 20 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  d *sqlite3_reall
1a6f0 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a  oc(void*, int);.
1a700 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65  void sqlite3_fre
1a710 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  e(void*);../*.**
1a720 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72   CAPI3REF: Memor
1a730 79 20 41 6c 6c 6f 63 61 74 6f 72 20 53 74 61 74  y Allocator Stat
1a740 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 53 51 4c  istics.**.** SQL
1a750 69 74 65 20 70 72 6f 76 69 64 65 73 20 74 68 65  ite provides the
1a760 73 65 20 74 77 6f 20 69 6e 74 65 72 66 61 63 65  se two interface
1a770 73 20 66 6f 72 20 72 65 70 6f 72 74 69 6e 67 20  s for reporting 
1a780 6f 6e 20 74 68 65 20 73 74 61 74 75 73 0a 2a 2a  on the status.**
1a790 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
1a7a0 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c  _malloc()], [sql
1a7b0 69 74 65 33 5f 66 72 65 65 28 29 5d 2c 20 61 6e  ite3_free()], an
1a7c0 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  d [sqlite3_reall
1a7d0 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65  oc()].** routine
1a7e0 73 2c 20 77 68 69 63 68 20 66 6f 72 6d 20 74 68  s, which form th
1a7f0 65 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72  e built-in memor
1a800 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62  y allocation sub
1a810 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 54  system..**.** ^T
1a820 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  he [sqlite3_memo
1a830 72 79 5f 75 73 65 64 28 29 5d 20 72 6f 75 74 69  ry_used()] routi
1a840 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  ne returns the n
1a850 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 0a 2a  umber of bytes.*
1a860 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 63 75 72 72  * of memory curr
1a870 65 6e 74 6c 79 20 6f 75 74 73 74 61 6e 64 69 6e  ently outstandin
1a880 67 20 28 6d 61 6c 6c 6f 63 65 64 20 62 75 74 20  g (malloced but 
1a890 6e 6f 74 20 66 72 65 65 64 29 2e 0a 2a 2a 20 5e  not freed)..** ^
1a8a0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  The [sqlite3_mem
1a8b0 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d  ory_highwater()]
1a8c0 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
1a8d0 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20   the maximum.** 
1a8e0 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74 65  value of [sqlite
1a8f0 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d  3_memory_used()]
1a900 20 73 69 6e 63 65 20 74 68 65 20 68 69 67 68 2d   since the high-
1a910 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 77 61  water mark.** wa
1a920 73 20 6c 61 73 74 20 72 65 73 65 74 2e 20 20 5e  s last reset.  ^
1a930 54 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72  The values retur
1a940 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ned by [sqlite3_
1a950 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 61  memory_used()] a
1a960 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  nd.** [sqlite3_m
1a970 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
1a980 29 5d 20 69 6e 63 6c 75 64 65 20 61 6e 79 20 6f  )] include any o
1a990 76 65 72 68 65 61 64 0a 2a 2a 20 61 64 64 65 64  verhead.** added
1a9a0 20 62 79 20 53 51 4c 69 74 65 20 69 6e 20 69 74   by SQLite in it
1a9b0 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  s implementation
1a9c0 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c   of [sqlite3_mal
1a9d0 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 62 75 74 20 6e  loc()],.** but n
1a9e0 6f 74 20 6f 76 65 72 68 65 61 64 20 61 64 64 65  ot overhead adde
1a9f0 64 20 62 79 20 74 68 65 20 61 6e 79 20 75 6e 64  d by the any und
1aa00 65 72 6c 79 69 6e 67 20 73 79 73 74 65 6d 20 6c  erlying system l
1aa10 69 62 72 61 72 79 0a 2a 2a 20 72 6f 75 74 69 6e  ibrary.** routin
1aa20 65 73 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33  es that [sqlite3
1aa30 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61 79 20 63  _malloc()] may c
1aa40 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  all..**.** ^The 
1aa50 6d 65 6d 6f 72 79 20 68 69 67 68 2d 77 61 74 65  memory high-wate
1aa60 72 20 6d 61 72 6b 20 69 73 20 72 65 73 65 74 20  r mark is reset 
1aa70 74 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20 76  to the current v
1aa80 61 6c 75 65 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69  alue of.** [sqli
1aa90 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28  te3_memory_used(
1aaa0 29 5d 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69  )] if and only i
1aab0 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
1aac0 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  to.** [sqlite3_m
1aad0 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
1aae0 29 5d 20 69 73 20 74 72 75 65 2e 20 20 5e 54 68  )] is true.  ^Th
1aaf0 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
1ab00 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  .** by [sqlite3_
1ab10 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
1ab20 28 31 29 5d 20 69 73 20 74 68 65 20 68 69 67 68  (1)] is the high
1ab30 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 70  -water mark.** p
1ab40 72 69 6f 72 20 74 6f 20 74 68 65 20 72 65 73 65  rior to the rese
1ab50 74 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e  t..*/.sqlite3_in
1ab60 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  t64 sqlite3_memo
1ab70 72 79 5f 75 73 65 64 28 76 6f 69 64 29 3b 0a 73  ry_used(void);.s
1ab80 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
1ab90 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
1aba0 77 61 74 65 72 28 69 6e 74 20 72 65 73 65 74 46  water(int resetF
1abb0 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  lag);../*.** CAP
1abc0 49 33 52 45 46 3a 20 50 73 65 75 64 6f 2d 52 61  I3REF: Pseudo-Ra
1abd0 6e 64 6f 6d 20 4e 75 6d 62 65 72 20 47 65 6e 65  ndom Number Gene
1abe0 72 61 74 6f 72 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  rator.**.** SQLi
1abf0 74 65 20 63 6f 6e 74 61 69 6e 73 20 61 20 68 69  te contains a hi
1ac00 67 68 2d 71 75 61 6c 69 74 79 20 70 73 65 75 64  gh-quality pseud
1ac10 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62 65 72 20  o-random number 
1ac20 67 65 6e 65 72 61 74 6f 72 20 28 50 52 4e 47 29  generator (PRNG)
1ac30 20 75 73 65 64 20 74 6f 0a 2a 2a 20 73 65 6c 65   used to.** sele
1ac40 63 74 20 72 61 6e 64 6f 6d 20 5b 52 4f 57 49 44  ct random [ROWID
1ac50 20 7c 20 52 4f 57 49 44 73 5d 20 77 68 65 6e 20   | ROWIDs] when 
1ac60 69 6e 73 65 72 74 69 6e 67 20 6e 65 77 20 72 65  inserting new re
1ac70 63 6f 72 64 73 20 69 6e 74 6f 20 61 20 74 61 62  cords into a tab
1ac80 6c 65 20 74 68 61 74 0a 2a 2a 20 61 6c 72 65 61  le that.** alrea
1ac90 64 79 20 75 73 65 73 20 74 68 65 20 6c 61 72 67  dy uses the larg
1aca0 65 73 74 20 70 6f 73 73 69 62 6c 65 20 5b 52 4f  est possible [RO
1acb0 57 49 44 5d 2e 20 20 54 68 65 20 50 52 4e 47 20  WID].  The PRNG 
1acc0 69 73 20 61 6c 73 6f 20 75 73 65 64 20 66 6f 72  is also used for
1acd0 0a 2a 2a 20 74 68 65 20 62 75 69 6c 64 2d 69 6e  .** the build-in
1ace0 20 72 61 6e 64 6f 6d 28 29 20 61 6e 64 20 72 61   random() and ra
1acf0 6e 64 6f 6d 62 6c 6f 62 28 29 20 53 51 4c 20 66  ndomblob() SQL f
1ad00 75 6e 63 74 69 6f 6e 73 2e 20 20 54 68 69 73 20  unctions.  This 
1ad10 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73  interface allows
1ad20 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  .** applications
1ad30 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 73   to access the s
1ad40 61 6d 65 20 50 52 4e 47 20 66 6f 72 20 6f 74 68  ame PRNG for oth
1ad50 65 72 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a  er purposes..**.
1ad60 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 74 68  ** ^A call to th
1ad70 69 73 20 72 6f 75 74 69 6e 65 20 73 74 6f 72 65  is routine store
1ad80 73 20 4e 20 62 79 74 65 73 20 6f 66 20 72 61 6e  s N bytes of ran
1ad90 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 62 75 66  domness into buf
1ada0 66 65 72 20 50 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  fer P..**.** ^Th
1adb0 65 20 66 69 72 73 74 20 74 69 6d 65 20 74 68 69  e first time thi
1adc0 73 20 72 6f 75 74 69 6e 65 20 69 73 20 69 6e 76  s routine is inv
1add0 6f 6b 65 64 20 28 65 69 74 68 65 72 20 69 6e 74  oked (either int
1ade0 65 72 6e 61 6c 6c 79 20 6f 72 20 62 79 0a 2a 2a  ernally or by.**
1adf0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
1ae00 29 20 74 68 65 20 50 52 4e 47 20 69 73 20 73 65  ) the PRNG is se
1ae10 65 64 65 64 20 75 73 69 6e 67 20 72 61 6e 64 6f  eded using rando
1ae20 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 0a 2a  mness obtained.*
1ae30 2a 20 66 72 6f 6d 20 74 68 65 20 78 52 61 6e 64  * from the xRand
1ae40 6f 6d 6e 65 73 73 20 6d 65 74 68 6f 64 20 6f 66  omness method of
1ae50 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71   the default [sq
1ae60 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
1ae70 74 2e 0a 2a 2a 20 5e 4f 6e 20 61 6c 6c 20 73 75  t..** ^On all su
1ae80 62 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74  bsequent invocat
1ae90 69 6f 6e 73 2c 20 74 68 65 20 70 73 65 75 64 6f  ions, the pseudo
1aea0 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69 73 20 67  -randomness is g
1aeb0 65 6e 65 72 61 74 65 64 0a 2a 2a 20 69 6e 74 65  enerated.** inte
1aec0 72 6e 61 6c 6c 79 20 61 6e 64 20 77 69 74 68 6f  rnally and witho
1aed0 75 74 20 72 65 63 6f 75 72 73 65 20 74 6f 20 74  ut recourse to t
1aee0 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  he [sqlite3_vfs]
1aef0 20 78 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20   xRandomness.** 
1af00 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 76 6f 69 64 20  method..*/.void 
1af10 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 6e 65  sqlite3_randomne
1af20 73 73 28 69 6e 74 20 4e 2c 20 76 6f 69 64 20 2a  ss(int N, void *
1af30 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  P);../*.** CAPI3
1af40 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d  REF: Compile-Tim
1af50 65 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20  e Authorization 
1af60 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20  Callbacks.**.** 
1af70 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65  ^This routine re
1af80 67 69 73 74 65 72 73 20 61 6e 20 61 75 74 68 6f  gisters an autho
1af90 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 77  rizer callback w
1afa0 69 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72  ith a particular
1afb0 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
1afc0 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73 75 70 70 6c  nnection], suppl
1afd0 69 65 64 20 69 6e 20 74 68 65 20 66 69 72 73 74  ied in the first
1afe0 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54   argument..** ^T
1aff0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
1b000 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
1b010 64 20 61 73 20 53 51 4c 20 73 74 61 74 65 6d 65  d as SQL stateme
1b020 6e 74 73 20 61 72 65 20 62 65 69 6e 67 20 63 6f  nts are being co
1b030 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73 71  mpiled.** by [sq
1b040 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d  lite3_prepare()]
1b050 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73   or its variants
1b060 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1b070 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  e_v2()],.** [sql
1b080 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
1b090 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70  ] and [sqlite3_p
1b0a0 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 20  repare16_v2()]. 
1b0b0 20 5e 41 74 20 76 61 72 69 6f 75 73 0a 2a 2a 20   ^At various.** 
1b0c0 70 6f 69 6e 74 73 20 64 75 72 69 6e 67 20 74 68  points during th
1b0d0 65 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 70 72  e compilation pr
1b0e0 6f 63 65 73 73 2c 20 61 73 20 6c 6f 67 69 63 20  ocess, as logic 
1b0f0 69 73 20 62 65 69 6e 67 20 63 72 65 61 74 65 64  is being created
1b100 0a 2a 2a 20 74 6f 20 70 65 72 66 6f 72 6d 20 76  .** to perform v
1b110 61 72 69 6f 75 73 20 61 63 74 69 6f 6e 73 2c 20  arious actions, 
1b120 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
1b130 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
1b140 65 64 20 74 6f 0a 2a 2a 20 73 65 65 20 69 66 20  ed to.** see if 
1b150 74 68 6f 73 65 20 61 63 74 69 6f 6e 73 20 61 72  those actions ar
1b160 65 20 61 6c 6c 6f 77 65 64 2e 20 20 5e 54 68 65  e allowed.  ^The
1b170 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
1b180 62 61 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20 72  back should.** r
1b190 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b  eturn [SQLITE_OK
1b1a0 5d 20 74 6f 20 61 6c 6c 6f 77 20 74 68 65 20 61  ] to allow the a
1b1b0 63 74 69 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f 49  ction, [SQLITE_I
1b1c0 47 4e 4f 52 45 5d 20 74 6f 20 64 69 73 61 6c 6c  GNORE] to disall
1b1d0 6f 77 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66  ow the.** specif
1b1e0 69 63 20 61 63 74 69 6f 6e 20 62 75 74 20 61 6c  ic action but al
1b1f0 6c 6f 77 20 74 68 65 20 53 51 4c 20 73 74 61 74  low the SQL stat
1b200 65 6d 65 6e 74 20 74 6f 20 63 6f 6e 74 69 6e 75  ement to continu
1b210 65 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 69  e to be.** compi
1b220 6c 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  led, or [SQLITE_
1b230 44 45 4e 59 5d 20 74 6f 20 63 61 75 73 65 20 74  DENY] to cause t
1b240 68 65 20 65 6e 74 69 72 65 20 53 51 4c 20 73 74  he entire SQL st
1b250 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 0a 2a 2a  atement to be.**
1b260 20 72 65 6a 65 63 74 65 64 20 77 69 74 68 20 61   rejected with a
1b270 6e 20 65 72 72 6f 72 2e 20 20 5e 49 66 20 74 68  n error.  ^If th
1b280 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
1b290 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a  lback returns.**
1b2a0 20 61 6e 79 20 76 61 6c 75 65 20 6f 74 68 65 72   any value other
1b2b0 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 49 47   than [SQLITE_IG
1b2c0 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f  NORE], [SQLITE_O
1b2d0 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44  K], or [SQLITE_D
1b2e0 45 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ENY].** then the
1b2f0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1b300 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76  e_v2()] or equiv
1b310 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20  alent call that 
1b320 74 72 69 67 67 65 72 65 64 0a 2a 2a 20 74 68 65  triggered.** the
1b330 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c   authorizer will
1b340 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72   fail with an er
1b350 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a  ror message..**.
1b360 2a 2a 20 57 68 65 6e 20 74 68 65 20 63 61 6c 6c  ** When the call
1b370 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51  back returns [SQ
1b380 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d  LITE_OK], that m
1b390 65 61 6e 73 20 74 68 65 20 6f 70 65 72 61 74 69  eans the operati
1b3a0 6f 6e 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20  on.** requested 
1b3b0 69 73 20 6f 6b 2e 20 20 5e 57 68 65 6e 20 74 68  is ok.  ^When th
1b3c0 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  e callback retur
1b3d0 6e 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d  ns [SQLITE_DENY]
1b3e0 2c 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  , the.** [sqlite
1b3f0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
1b400 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61  or equivalent ca
1b410 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65  ll that triggere
1b420 64 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69  d the.** authori
1b430 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69  zer will fail wi
1b440 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73  th an error mess
1b450 61 67 65 20 65 78 70 6c 61 69 6e 69 6e 67 20 74  age explaining t
1b460 68 61 74 0a 2a 2a 20 61 63 63 65 73 73 20 69 73  hat.** access is
1b470 20 64 65 6e 69 65 64 2e 20 0a 2a 2a 0a 2a 2a 20   denied. .**.** 
1b480 5e 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d  ^The first param
1b490 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68  eter to the auth
1b4a0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
1b4b0 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  is a copy of the
1b4c0 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65   third.** parame
1b4d0 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ter to the sqlit
1b4e0 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
1b4f0 72 28 29 20 69 6e 74 65 72 66 61 63 65 2e 20 5e  r() interface. ^
1b500 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
1b510 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 63  eter.** to the c
1b520 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e  allback is an in
1b530 74 65 67 65 72 20 5b 53 51 4c 49 54 45 5f 43 4f  teger [SQLITE_CO
1b540 50 59 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64 65  PY | action code
1b550 5d 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73  ] that specifies
1b560 0a 2a 2a 20 74 68 65 20 70 61 72 74 69 63 75 6c  .** the particul
1b570 61 72 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20  ar action to be 
1b580 61 75 74 68 6f 72 69 7a 65 64 2e 20 5e 54 68 65  authorized. ^The
1b590 20 74 68 69 72 64 20 74 68 72 6f 75 67 68 20 73   third through s
1b5a0 69 78 74 68 20 70 61 72 61 6d 65 74 65 72 73 0a  ixth parameters.
1b5b0 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  ** to the callba
1b5c0 63 6b 20 61 72 65 20 7a 65 72 6f 2d 74 65 72 6d  ck are zero-term
1b5d0 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20 74  inated strings t
1b5e0 68 61 74 20 63 6f 6e 74 61 69 6e 20 61 64 64 69  hat contain addi
1b5f0 74 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74 61 69 6c  tional.** detail
1b600 73 20 61 62 6f 75 74 20 74 68 65 20 61 63 74 69  s about the acti
1b610 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69  on to be authori
1b620 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  zed..**.** ^If t
1b630 68 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69  he action code i
1b640 73 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d 0a  s [SQLITE_READ].
1b650 2a 2a 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62  ** and the callb
1b660 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ack returns [SQL
1b670 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e  ITE_IGNORE] then
1b680 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
1b690 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 73 74 61  d statement] sta
1b6a0 74 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73 74 72  tement is constr
1b6b0 75 63 74 65 64 20 74 6f 20 73 75 62 73 74 69 74  ucted to substit
1b6c0 75 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76 61  ute.** a NULL va
1b6d0 6c 75 65 20 69 6e 20 70 6c 61 63 65 20 6f 66 20  lue in place of 
1b6e0 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e  the table column
1b6f0 20 74 68 61 74 20 77 6f 75 6c 64 20 68 61 76 65   that would have
1b700 0a 2a 2a 20 62 65 65 6e 20 72 65 61 64 20 69 66  .** been read if
1b710 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 64   [SQLITE_OK] had
1b720 20 62 65 65 6e 20 72 65 74 75 72 6e 65 64 2e 20   been returned. 
1b730 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 47 4e   The [SQLITE_IGN
1b740 4f 52 45 5d 0a 2a 2a 20 72 65 74 75 72 6e 20 63  ORE].** return c
1b750 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 64 65  an be used to de
1b760 6e 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20  ny an untrusted 
1b770 75 73 65 72 20 61 63 63 65 73 73 20 74 6f 20 69  user access to i
1b780 6e 64 69 76 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c  ndividual.** col
1b790 75 6d 6e 73 20 6f 66 20 61 20 74 61 62 6c 65 2e  umns of a table.
1b7a0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74 69  .** ^If the acti
1b7b0 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49  on code is [SQLI
1b7c0 54 45 5f 44 45 4c 45 54 45 5d 20 61 6e 64 20 74  TE_DELETE] and t
1b7d0 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  he callback retu
1b7e0 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49  rns.** [SQLITE_I
1b7f0 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 20  GNORE] then the 
1b800 5b 44 45 4c 45 54 45 5d 20 6f 70 65 72 61 74 69  [DELETE] operati
1b810 6f 6e 20 70 72 6f 63 65 65 64 73 20 62 75 74 20  on proceeds but 
1b820 74 68 65 0a 2a 2a 20 5b 74 72 75 6e 63 61 74 65  the.** [truncate
1b830 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 20 69   optimization] i
1b840 73 20 64 69 73 61 62 6c 65 64 20 61 6e 64 20 61  s disabled and a
1b850 6c 6c 20 72 6f 77 73 20 61 72 65 20 64 65 6c 65  ll rows are dele
1b860 74 65 64 20 69 6e 64 69 76 69 64 75 61 6c 6c 79  ted individually
1b870 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68 6f  ..**.** An autho
1b880 72 69 7a 65 72 20 69 73 20 75 73 65 64 20 77 68  rizer is used wh
1b890 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  en [sqlite3_prep
1b8a0 61 72 65 20 7c 20 70 72 65 70 61 72 69 6e 67 5d  are | preparing]
1b8b0 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  .** SQL statemen
1b8c0 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72 75  ts from an untru
1b8d0 73 74 65 64 20 73 6f 75 72 63 65 2c 20 74 6f 20  sted source, to 
1b8e0 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20  ensure that the 
1b8f0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a  SQL statements.*
1b900 2a 20 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f 20  * do not try to 
1b910 61 63 63 65 73 73 20 64 61 74 61 20 74 68 65 79  access data they
1b920 20 61 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65 64   are not allowed
1b930 20 74 6f 20 73 65 65 2c 20 6f 72 20 74 68 61 74   to see, or that
1b940 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20   they do not.** 
1b950 74 72 79 20 74 6f 20 65 78 65 63 75 74 65 20 6d  try to execute m
1b960 61 6c 69 63 69 6f 75 73 20 73 74 61 74 65 6d 65  alicious stateme
1b970 6e 74 73 20 74 68 61 74 20 64 61 6d 61 67 65 20  nts that damage 
1b980 74 68 65 20 64 61 74 61 62 61 73 65 2e 20 20 46  the database.  F
1b990 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 61  or.** example, a
1b9a0 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61  n application ma
1b9b0 79 20 61 6c 6c 6f 77 20 61 20 75 73 65 72 20 74  y allow a user t
1b9c0 6f 20 65 6e 74 65 72 20 61 72 62 69 74 72 61 72  o enter arbitrar
1b9d0 79 0a 2a 2a 20 53 51 4c 20 71 75 65 72 69 65 73  y.** SQL queries
1b9e0 20 66 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e 20   for evaluation 
1b9f0 62 79 20 61 20 64 61 74 61 62 61 73 65 2e 20 20  by a database.  
1ba00 42 75 74 20 74 68 65 20 61 70 70 6c 69 63 61 74  But the applicat
1ba10 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20  ion does.** not 
1ba20 77 61 6e 74 20 74 68 65 20 75 73 65 72 20 74 6f  want the user to
1ba30 20 62 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b 65   be able to make
1ba40 20 61 72 62 69 74 72 61 72 79 20 63 68 61 6e 67   arbitrary chang
1ba50 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74  es to the.** dat
1ba60 61 62 61 73 65 2e 20 20 41 6e 20 61 75 74 68 6f  abase.  An autho
1ba70 72 69 7a 65 72 20 63 6f 75 6c 64 20 74 68 65 6e  rizer could then
1ba80 20 62 65 20 70 75 74 20 69 6e 20 70 6c 61 63 65   be put in place
1ba90 20 77 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75 73   while the.** us
1baa0 65 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 20 69  er-entered SQL i
1bab0 73 20 62 65 69 6e 67 20 5b 73 71 6c 69 74 65 33  s being [sqlite3
1bac0 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70 61  _prepare | prepa
1bad0 72 65 64 5d 20 74 68 61 74 0a 2a 2a 20 64 69 73  red] that.** dis
1bae0 61 6c 6c 6f 77 73 20 65 76 65 72 79 74 68 69 6e  allows everythin
1baf0 67 20 65 78 63 65 70 74 20 5b 53 45 4c 45 43 54  g except [SELECT
1bb00 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  ] statements..**
1bb10 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  .** Applications
1bb20 20 74 68 61 74 20 6e 65 65 64 20 74 6f 20 70 72   that need to pr
1bb30 6f 63 65 73 73 20 53 51 4c 20 66 72 6f 6d 20 75  ocess SQL from u
1bb40 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63 65 73  ntrusted sources
1bb50 0a 2a 2a 20 6d 69 67 68 74 20 61 6c 73 6f 20 63  .** might also c
1bb60 6f 6e 73 69 64 65 72 20 6c 6f 77 65 72 69 6e 67  onsider lowering
1bb70 20 72 65 73 6f 75 72 63 65 20 6c 69 6d 69 74 73   resource limits
1bb80 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
1bb90 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 64 20  limit()].** and 
1bba0 6c 69 6d 69 74 69 6e 67 20 64 61 74 61 62 61 73  limiting databas
1bbb0 65 20 73 69 7a 65 20 75 73 69 6e 67 20 74 68 65  e size using the
1bbc0 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74   [max_page_count
1bbd0 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e  ] [PRAGMA].** in
1bbe0 20 61 64 64 69 74 69 6f 6e 20 74 6f 20 75 73 69   addition to usi
1bbf0 6e 67 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72  ng an authorizer
1bc00 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 61  ..**.** ^(Only a
1bc10 20 73 69 6e 67 6c 65 20 61 75 74 68 6f 72 69 7a   single authoriz
1bc20 65 72 20 63 61 6e 20 62 65 20 69 6e 20 70 6c 61  er can be in pla
1bc30 63 65 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65  ce on a database
1bc40 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61   connection.** a
1bc50 74 20 61 20 74 69 6d 65 2e 20 20 45 61 63 68 20  t a time.  Each 
1bc60 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
1bc70 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 6f  set_authorizer o
1bc80 76 65 72 72 69 64 65 73 20 74 68 65 0a 2a 2a 20  verrides the.** 
1bc90 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e 29 5e  previous call.)^
1bca0 20 20 5e 44 69 73 61 62 6c 65 20 74 68 65 20 61    ^Disable the a
1bcb0 75 74 68 6f 72 69 7a 65 72 20 62 79 20 69 6e 73  uthorizer by ins
1bcc0 74 61 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c 20 63  talling a NULL c
1bcd0 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20  allback..** The 
1bce0 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 64 69  authorizer is di
1bcf0 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  sabled by defaul
1bd00 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74  t..**.** The aut
1bd10 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1bd20 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79   must not do any
1bd30 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20  thing that will 
1bd40 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61  modify.** the da
1bd50 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1bd60 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74  n that invoked t
1bd70 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
1bd80 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20  llback..** Note 
1bd90 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72  that [sqlite3_pr
1bda0 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20  epare_v2()] and 
1bdb0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
1bdc0 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65   both modify the
1bdd0 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  ir.** database c
1bde0 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74  onnections for t
1bdf0 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d  he meaning of "m
1be00 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 70  odify" in this p
1be10 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20  aragraph..**.** 
1be20 5e 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70  ^When [sqlite3_p
1be30 72 65 70 61 72 65 5f 76 32 28 29 5d 20 69 73 20  repare_v2()] is 
1be40 75 73 65 64 20 74 6f 20 70 72 65 70 61 72 65 20  used to prepare 
1be50 61 20 73 74 61 74 65 6d 65 6e 74 2c 20 74 68 65  a statement, the
1be60 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 6d 69  .** statement mi
1be70 67 68 74 20 62 65 20 72 65 2d 70 72 65 70 61 72  ght be re-prepar
1be80 65 64 20 64 75 72 69 6e 67 20 5b 73 71 6c 69 74  ed during [sqlit
1be90 65 33 5f 73 74 65 70 28 29 5d 20 64 75 65 20 74  e3_step()] due t
1bea0 6f 20 61 20 0a 2a 2a 20 73 63 68 65 6d 61 20 63  o a .** schema c
1beb0 68 61 6e 67 65 2e 20 20 48 65 6e 63 65 2c 20 74  hange.  Hence, t
1bec0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73  he application s
1bed0 68 6f 75 6c 64 20 65 6e 73 75 72 65 20 74 68 61  hould ensure tha
1bee0 74 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 63 74  t the.** correct
1bef0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
1bf00 62 61 63 6b 20 72 65 6d 61 69 6e 73 20 69 6e 20  back remains in 
1bf10 70 6c 61 63 65 20 64 75 72 69 6e 67 20 74 68 65  place during the
1bf20 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
1bf30 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74  ]..**.** ^Note t
1bf40 68 61 74 20 74 68 65 20 61 75 74 68 6f 72 69 7a  hat the authoriz
1bf50 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  er callback is i
1bf60 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72 69  nvoked only duri
1bf70 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  ng.** [sqlite3_p
1bf80 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73  repare()] or its
1bf90 20 76 61 72 69 61 6e 74 73 2e 20 20 41 75 74 68   variants.  Auth
1bfa0 6f 72 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f 74  orization is not
1bfb0 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 64 75  .** performed du
1bfc0 72 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 65  ring statement e
1bfd0 76 61 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73 71  valuation in [sq
1bfe0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 75  lite3_step()], u
1bff0 6e 6c 65 73 73 0a 2a 2a 20 61 73 20 73 74 61 74  nless.** as stat
1c000 65 64 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f  ed in the previo
1c010 75 73 20 70 61 72 61 67 72 61 70 68 2c 20 73 71  us paragraph, sq
1c020 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e 76  lite3_step() inv
1c030 6f 6b 65 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  okes.** sqlite3_
1c040 70 72 65 70 61 72 65 5f 76 32 28 29 20 74 6f 20  prepare_v2() to 
1c050 72 65 70 72 65 70 61 72 65 20 61 20 73 74 61 74  reprepare a stat
1c060 65 6d 65 6e 74 20 61 66 74 65 72 20 61 20 73 63  ement after a sc
1c070 68 65 6d 61 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a  hema change..*/.
1c080 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  int sqlite3_set_
1c090 61 75 74 68 6f 72 69 7a 65 72 28 0a 20 20 73 71  authorizer(.  sq
1c0a0 6c 69 74 65 33 2a 2c 0a 20 20 69 6e 74 20 28 2a  lite3*,.  int (*
1c0b0 78 41 75 74 68 29 28 76 6f 69 64 2a 2c 69 6e 74  xAuth)(void*,int
1c0c0 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e  ,const char*,con
1c0d0 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63  st char*,const c
1c0e0 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  har*,const char*
1c0f0 29 2c 0a 20 20 76 6f 69 64 20 2a 70 55 73 65 72  ),.  void *pUser
1c100 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  Data.);../*.** C
1c110 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69  API3REF: Authori
1c120 7a 65 72 20 52 65 74 75 72 6e 20 43 6f 64 65 73  zer Return Codes
1c130 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69  .**.** The [sqli
1c140 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
1c150 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20  er | authorizer 
1c160 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
1c170 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72 65 74 75 72  n] must.** retur
1c180 6e 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45  n either [SQLITE
1c190 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74  _OK] or one of t
1c1a0 68 65 73 65 20 74 77 6f 20 63 6f 6e 73 74 61 6e  hese two constan
1c1b0 74 73 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 74  ts in order.** t
1c1c0 6f 20 73 69 67 6e 61 6c 20 53 51 4c 69 74 65 20  o signal SQLite 
1c1d0 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74  whether or not t
1c1e0 68 65 20 61 63 74 69 6f 6e 20 69 73 20 70 65 72  he action is per
1c1f0 6d 69 74 74 65 64 2e 20 20 53 65 65 20 74 68 65  mitted.  See the
1c200 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  .** [sqlite3_set
1c210 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75  _authorizer | au
1c220 74 68 6f 72 69 7a 65 72 20 64 6f 63 75 6d 65 6e  thorizer documen
1c230 74 61 74 69 6f 6e 5d 20 66 6f 72 20 61 64 64 69  tation] for addi
1c240 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d  tional.** inform
1c250 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74  ation..**.** Not
1c260 65 20 74 68 61 74 20 53 51 4c 49 54 45 5f 49 47  e that SQLITE_IG
1c270 4e 4f 52 45 20 69 73 20 61 6c 73 6f 20 75 73 65  NORE is also use
1c280 64 20 61 73 20 61 20 5b 53 51 4c 49 54 45 5f 52  d as a [SQLITE_R
1c290 4f 4c 4c 42 41 43 4b 20 7c 20 72 65 74 75 72 6e  OLLBACK | return
1c2a0 20 63 6f 64 65 5d 0a 2a 2a 20 66 72 6f 6d 20 74   code].** from t
1c2b0 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 74 61 62  he [sqlite3_vtab
1c2c0 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28 29 5d 20  _on_conflict()] 
1c2d0 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 23 64  interface..*/.#d
1c2e0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4e  efine SQLITE_DEN
1c2f0 59 20 20 20 31 20 20 20 2f 2a 20 41 62 6f 72 74  Y   1   /* Abort
1c300 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
1c310 6e 74 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72  nt with an error
1c320 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1c330 54 45 5f 49 47 4e 4f 52 45 20 32 20 20 20 2f 2a  TE_IGNORE 2   /*
1c340 20 44 6f 6e 27 74 20 61 6c 6c 6f 77 20 61 63 63   Don't allow acc
1c350 65 73 73 2c 20 62 75 74 20 64 6f 6e 27 74 20 67  ess, but don't g
1c360 65 6e 65 72 61 74 65 20 61 6e 20 65 72 72 6f 72  enerate an error
1c370 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
1c380 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20  REF: Authorizer 
1c390 41 63 74 69 6f 6e 20 43 6f 64 65 73 0a 2a 2a 0a  Action Codes.**.
1c3a0 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** The [sqlite3_
1c3b0 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29  set_authorizer()
1c3c0 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69  ] interface regi
1c3d0 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b  sters a callback
1c3e0 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68 61   function.** tha
1c3f0 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 20  t is invoked to 
1c400 61 75 74 68 6f 72 69 7a 65 20 63 65 72 74 61 69  authorize certai
1c410 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  n SQL statement 
1c420 61 63 74 69 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a  actions.  The.**
1c430 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
1c440 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63  r to the callbac
1c450 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  k is an integer 
1c460 63 6f 64 65 20 74 68 61 74 20 73 70 65 63 69 66  code that specif
1c470 69 65 73 0a 2a 2a 20 77 68 61 74 20 61 63 74 69  ies.** what acti
1c480 6f 6e 20 69 73 20 62 65 69 6e 67 20 61 75 74 68  on is being auth
1c490 6f 72 69 7a 65 64 2e 20 20 54 68 65 73 65 20 61  orized.  These a
1c4a0 72 65 20 74 68 65 20 69 6e 74 65 67 65 72 20 61  re the integer a
1c4b0 63 74 69 6f 6e 20 63 6f 64 65 73 20 74 68 61 74  ction codes that
1c4c0 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a  .** the authoriz
1c4d0 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 61 79 20  er callback may 
1c4e0 62 65 20 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a  be passed..**.**
1c4f0 20 54 68 65 73 65 20 61 63 74 69 6f 6e 20 63 6f   These action co
1c500 64 65 20 76 61 6c 75 65 73 20 73 69 67 6e 69 66  de values signif
1c510 79 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 6f  y what kind of o
1c520 70 65 72 61 74 69 6f 6e 20 69 73 20 74 6f 20 62  peration is to b
1c530 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 64 2e  e.** authorized.
1c540 20 20 54 68 65 20 33 72 64 20 61 6e 64 20 34 74    The 3rd and 4t
1c550 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20  h parameters to 
1c560 74 68 65 20 61 75 74 68 6f 72 69 7a 61 74 69 6f  the authorizatio
1c570 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75  n.** callback fu
1c580 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20 70  nction will be p
1c590 61 72 61 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c  arameters or NUL
1c5a0 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77  L depending on w
1c5b0 68 69 63 68 20 6f 66 20 74 68 65 73 65 0a 2a 2a  hich of these.**
1c5c0 20 63 6f 64 65 73 20 69 73 20 75 73 65 64 20 61   codes is used a
1c5d0 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  s the second par
1c5e0 61 6d 65 74 65 72 2e 20 20 5e 28 54 68 65 20 35  ameter.  ^(The 5
1c5f0 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
1c600 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65  the.** authorize
1c610 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68  r callback is th
1c620 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61  e name of the da
1c630 74 61 62 61 73 65 20 28 22 6d 61 69 6e 22 2c 20  tabase ("main", 
1c640 22 74 65 6d 70 22 2c 0a 2a 2a 20 65 74 63 2e 29  "temp",.** etc.)
1c650 20 69 66 20 61 70 70 6c 69 63 61 62 6c 65 2e 29   if applicable.)
1c660 5e 20 20 5e 54 68 65 20 36 74 68 20 70 61 72 61  ^  ^The 6th para
1c670 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74  meter to the aut
1c680 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1c690 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20  .** is the name 
1c6a0 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f 73  of the inner-mos
1c6b0 74 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 65  t trigger or vie
1c6c0 77 20 74 68 61 74 20 69 73 20 72 65 73 70 6f 6e  w that is respon
1c6d0 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 74 68 65  sible for.** the
1c6e0 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20   access attempt 
1c6f0 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 69 73 20  or NULL if this 
1c700 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 69  access attempt i
1c710 73 20 64 69 72 65 63 74 6c 79 20 66 72 6f 6d 0a  s directly from.
1c720 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51 4c  ** top-level SQL
1c730 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a   code..*/./*****
1c740 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1c750 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1c760 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a  ****** 3rd *****
1c770 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a  ******* 4th ****
1c780 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65  *******/.#define
1c790 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 49   SQLITE_CREATE_I
1c7a0 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 31 20  NDEX          1 
1c7b0 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20    /* Index Name 
1c7c0 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20       Table Name 
1c7d0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1c7e0 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 41  SQLITE_CREATE_TA
1c7f0 42 4c 45 20 20 20 20 20 20 20 20 20 20 32 20 20  BLE          2  
1c800 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
1c810 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
1c820 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1c830 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d  QLITE_CREATE_TEM
1c840 50 5f 49 4e 44 45 58 20 20 20 20 20 33 20 20 20  P_INDEX     3   
1c850 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20  /* Index Name   
1c860 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
1c870 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1c880 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50  LITE_CREATE_TEMP
1c890 5f 54 41 42 4c 45 20 20 20 20 20 34 20 20 20 2f  _TABLE     4   /
1c8a0 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
1c8b0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1c8c0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1c8d0 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f  ITE_CREATE_TEMP_
1c8e0 54 52 49 47 47 45 52 20 20 20 35 20 20 20 2f 2a  TRIGGER   5   /*
1c8f0 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20   Trigger Name   
1c900 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1c910 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1c920 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 56  TE_CREATE_TEMP_V
1c930 49 45 57 20 20 20 20 20 20 36 20 20 20 2f 2a 20  IEW      6   /* 
1c940 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20  View Name       
1c950 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1c960 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1c970 45 5f 43 52 45 41 54 45 5f 54 52 49 47 47 45 52  E_CREATE_TRIGGER
1c980 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 54          7   /* T
1c990 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54  rigger Name    T
1c9a0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
1c9b0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1c9c0 5f 43 52 45 41 54 45 5f 56 49 45 57 20 20 20 20  _CREATE_VIEW    
1c9d0 20 20 20 20 20 20 20 38 20 20 20 2f 2a 20 56 69         8   /* Vi
1c9e0 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55  ew Name       NU
1c9f0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
1ca00 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1ca10 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20 20  DELETE          
1ca20 20 20 20 20 20 20 39 20 20 20 2f 2a 20 54 61 62        9   /* Tab
1ca30 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
1ca40 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
1ca50 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1ca60 52 4f 50 5f 49 4e 44 45 58 20 20 20 20 20 20 20  ROP_INDEX       
1ca70 20 20 20 20 31 30 20 20 20 2f 2a 20 49 6e 64 65      10   /* Inde
1ca80 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c  x Name      Tabl
1ca90 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
1caa0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
1cab0 4f 50 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20  OP_TABLE        
1cac0 20 20 20 31 31 20 20 20 2f 2a 20 54 61 62 6c 65     11   /* Table
1cad0 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
1cae0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
1caf0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
1cb00 50 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20  P_TEMP_INDEX    
1cb10 20 20 31 32 20 20 20 2f 2a 20 49 6e 64 65 78 20    12   /* Index 
1cb20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20  Name      Table 
1cb30 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
1cb40 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
1cb50 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20  _TEMP_TABLE     
1cb60 20 31 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   13   /* Table N
1cb70 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
1cb80 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1cb90 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
1cba0 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 20  TEMP_TRIGGER    
1cbb0 31 34 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20  14   /* Trigger 
1cbc0 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61  Name    Table Na
1cbd0 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
1cbe0 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
1cbf0 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20 20 31  EMP_VIEW       1
1cc00 35 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65  5   /* View Name
1cc10 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
1cc20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
1cc30 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 52  e SQLITE_DROP_TR
1cc40 49 47 47 45 52 20 20 20 20 20 20 20 20 20 31 36  IGGER         16
1cc50 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61     /* Trigger Na
1cc60 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65  me    Table Name
1cc70 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1cc80 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 49 45   SQLITE_DROP_VIE
1cc90 57 20 20 20 20 20 20 20 20 20 20 20 20 31 37 20  W            17 
1cca0 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20    /* View Name  
1ccb0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
1ccc0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1ccd0 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 20 20 20  SQLITE_INSERT   
1cce0 20 20 20 20 20 20 20 20 20 20 20 20 31 38 20 20              18  
1ccf0 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
1cd00 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
1cd10 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1cd20 51 4c 49 54 45 5f 50 52 41 47 4d 41 20 20 20 20  QLITE_PRAGMA    
1cd30 20 20 20 20 20 20 20 20 20 20 20 31 39 20 20 20             19   
1cd40 2f 2a 20 50 72 61 67 6d 61 20 4e 61 6d 65 20 20  /* Pragma Name  
1cd50 20 20 20 31 73 74 20 61 72 67 20 6f 72 20 4e 55     1st arg or NU
1cd60 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  LL */.#define SQ
1cd70 4c 49 54 45 5f 52 45 41 44 20 20 20 20 20 20 20  LITE_READ       
1cd80 20 20 20 20 20 20 20 20 20 20 32 30 20 20 20 2f            20   /
1cd90 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
1cda0 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20    Column Name   
1cdb0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1cdc0 49 54 45 5f 53 45 4c 45 43 54 20 20 20 20 20 20  ITE_SELECT      
1cdd0 20 20 20 20 20 20 20 20 20 32 31 20 20 20 2f 2a           21   /*
1cde0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1cdf0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1ce00 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1ce10 54 45 5f 54 52 41 4e 53 41 43 54 49 4f 4e 20 20  TE_TRANSACTION  
1ce20 20 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20          22   /* 
1ce30 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20  Operation       
1ce40 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1ce50 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1ce60 45 5f 55 50 44 41 54 45 20 20 20 20 20 20 20 20  E_UPDATE        
1ce70 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20 54         23   /* T
1ce80 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43  able Name      C
1ce90 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a  olumn Name     *
1cea0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1ceb0 5f 41 54 54 41 43 48 20 20 20 20 20 20 20 20 20  _ATTACH         
1cec0 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20 46 69        24   /* Fi
1ced0 6c 65 6e 61 6d 65 20 20 20 20 20 20 20 20 4e 55  lename        NU
1cee0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
1cef0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1cf00 44 45 54 41 43 48 20 20 20 20 20 20 20 20 20 20  DETACH          
1cf10 20 20 20 20 20 32 35 20 20 20 2f 2a 20 44 61 74       25   /* Dat
1cf20 61 62 61 73 65 20 4e 61 6d 65 20 20 20 4e 55 4c  abase Name   NUL
1cf30 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
1cf40 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
1cf50 4c 54 45 52 5f 54 41 42 4c 45 20 20 20 20 20 20  LTER_TABLE      
1cf60 20 20 20 20 32 36 20 20 20 2f 2a 20 44 61 74 61      26   /* Data
1cf70 62 61 73 65 20 4e 61 6d 65 20 20 20 54 61 62 6c  base Name   Tabl
1cf80 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
1cf90 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45  define SQLITE_RE
1cfa0 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 20  INDEX           
1cfb0 20 20 20 32 37 20 20 20 2f 2a 20 49 6e 64 65 78     27   /* Index
1cfc0 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
1cfd0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
1cfe0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 41  efine SQLITE_ANA
1cff0 4c 59 5a 45 20 20 20 20 20 20 20 20 20 20 20 20  LYZE            
1d000 20 20 32 38 20 20 20 2f 2a 20 54 61 62 6c 65 20    28   /* Table 
1d010 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
1d020 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
1d030 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
1d040 54 45 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20  TE_VTABLE       
1d050 20 32 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   29   /* Table N
1d060 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20  ame      Module 
1d070 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66  Name     */.#def
1d080 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
1d090 56 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20  VTABLE          
1d0a0 33 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  30   /* Table Na
1d0b0 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e  me      Module N
1d0c0 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  ame     */.#defi
1d0d0 6e 65 20 53 51 4c 49 54 45 5f 46 55 4e 43 54 49  ne SQLITE_FUNCTI
1d0e0 4f 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 33  ON             3
1d0f0 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20  1   /* NULL     
1d100 20 20 20 20 20 20 20 46 75 6e 63 74 69 6f 6e 20         Function 
1d110 4e 61 6d 65 20 20 20 2a 2f 0a 23 64 65 66 69 6e  Name   */.#defin
1d120 65 20 53 51 4c 49 54 45 5f 53 41 56 45 50 4f 49  e SQLITE_SAVEPOI
1d130 4e 54 20 20 20 20 20 20 20 20 20 20 20 20 33 32  NT            32
1d140 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20     /* Operation 
1d150 20 20 20 20 20 20 53 61 76 65 70 6f 69 6e 74 20        Savepoint 
1d160 4e 61 6d 65 20 20 2a 2f 0a 23 64 65 66 69 6e 65  Name  */.#define
1d170 20 53 51 4c 49 54 45 5f 43 4f 50 59 20 20 20 20   SQLITE_COPY    
1d180 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 20                0 
1d190 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 75    /* No longer u
1d1a0 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  sed */../*.** CA
1d1b0 50 49 33 52 45 46 3a 20 54 72 61 63 69 6e 67 20  PI3REF: Tracing 
1d1c0 41 6e 64 20 50 72 6f 66 69 6c 69 6e 67 20 46 75  And Profiling Fu
1d1d0 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68  nctions.**.** Th
1d1e0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 67  ese routines reg
1d1f0 69 73 74 65 72 20 63 61 6c 6c 62 61 63 6b 20 66  ister callback f
1d200 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 63 61  unctions that ca
1d210 6e 20 62 65 20 75 73 65 64 20 66 6f 72 0a 2a 2a  n be used for.**
1d220 20 74 72 61 63 69 6e 67 20 61 6e 64 20 70 72 6f   tracing and pro
1d230 66 69 6c 69 6e 67 20 74 68 65 20 65 78 65 63 75  filing the execu
1d240 74 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61 74  tion of SQL stat
1d250 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ements..**.** ^T
1d260 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  he callback func
1d270 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20  tion registered 
1d280 62 79 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65  by sqlite3_trace
1d290 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 74  () is invoked at
1d2a0 0a 2a 2a 20 76 61 72 69 6f 75 73 20 74 69 6d 65  .** various time
1d2b0 73 20 77 68 65 6e 20 61 6e 20 53 51 4c 20 73 74  s when an SQL st
1d2c0 61 74 65 6d 65 6e 74 20 69 73 20 62 65 69 6e 67  atement is being
1d2d0 20 72 75 6e 20 62 79 20 5b 73 71 6c 69 74 65 33   run by [sqlite3
1d2e0 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 5e 54 68  _step()]..** ^Th
1d2f0 65 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28  e sqlite3_trace(
1d300 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  ) callback is in
1d310 76 6f 6b 65 64 20 77 69 74 68 20 61 20 55 54 46  voked with a UTF
1d320 2d 38 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20  -8 rendering of 
1d330 74 68 65 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65  the.** SQL state
1d340 6d 65 6e 74 20 74 65 78 74 20 61 73 20 74 68 65  ment text as the
1d350 20 73 74 61 74 65 6d 65 6e 74 20 66 69 72 73 74   statement first
1d360 20 62 65 67 69 6e 73 20 65 78 65 63 75 74 69 6e   begins executin
1d370 67 2e 0a 2a 2a 20 5e 28 41 64 64 69 74 69 6f 6e  g..** ^(Addition
1d380 61 6c 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65  al sqlite3_trace
1d390 28 29 20 63 61 6c 6c 62 61 63 6b 73 20 6d 69 67  () callbacks mig
1d3a0 68 74 20 6f 63 63 75 72 0a 2a 2a 20 61 73 20 65  ht occur.** as e
1d3b0 61 63 68 20 74 72 69 67 67 65 72 65 64 20 73 75  ach triggered su
1d3c0 62 70 72 6f 67 72 61 6d 20 69 73 20 65 6e 74 65  bprogram is ente
1d3d0 72 65 64 2e 20 20 54 68 65 20 63 61 6c 6c 62 61  red.  The callba
1d3e0 63 6b 73 20 66 6f 72 20 74 72 69 67 67 65 72 73  cks for triggers
1d3f0 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 61 20 55 54  .** contain a UT
1d400 46 2d 38 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20  F-8 SQL comment 
1d410 74 68 61 74 20 69 64 65 6e 74 69 66 69 65 73 20  that identifies 
1d420 74 68 65 20 74 72 69 67 67 65 72 2e 29 5e 0a 2a  the trigger.)^.*
1d430 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61  *.** ^The callba
1d440 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69  ck function regi
1d450 73 74 65 72 65 64 20 62 79 20 73 71 6c 69 74 65  stered by sqlite
1d460 33 5f 70 72 6f 66 69 6c 65 28 29 20 69 73 20 69  3_profile() is i
1d470 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73 20 65 61 63  nvoked.** as eac
1d480 68 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  h SQL statement 
1d490 66 69 6e 69 73 68 65 73 2e 20 20 5e 54 68 65 20  finishes.  ^The 
1d4a0 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b  profile callback
1d4b0 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74 68 65   contains.** the
1d4c0 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d   original statem
1d4d0 65 6e 74 20 74 65 78 74 20 61 6e 64 20 61 6e 20  ent text and an 
1d4e0 65 73 74 69 6d 61 74 65 20 6f 66 20 77 61 6c 6c  estimate of wall
1d4f0 2d 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a 20 6f  -clock time.** o
1d500 66 20 68 6f 77 20 6c 6f 6e 67 20 74 68 61 74 20  f how long that 
1d510 73 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b 20 74  statement took t
1d520 6f 20 72 75 6e 2e 20 20 5e 54 68 65 20 70 72 6f  o run.  ^The pro
1d530 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a  file callback.**
1d540 20 74 69 6d 65 20 69 73 20 69 6e 20 75 6e 69 74   time is in unit
1d550 73 20 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e 64 73  s of nanoseconds
1d560 2c 20 68 6f 77 65 76 65 72 20 74 68 65 20 63 75  , however the cu
1d570 72 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61  rrent implementa
1d580 74 69 6f 6e 0a 2a 2a 20 69 73 20 6f 6e 6c 79 20  tion.** is only 
1d590 63 61 70 61 62 6c 65 20 6f 66 20 6d 69 6c 6c 69  capable of milli
1d5a0 73 65 63 6f 6e 64 20 72 65 73 6f 6c 75 74 69 6f  second resolutio
1d5b0 6e 20 73 6f 20 74 68 65 20 73 69 78 20 6c 65 61  n so the six lea
1d5c0 73 74 20 73 69 67 6e 69 66 69 63 61 6e 74 0a 2a  st significant.*
1d5d0 2a 20 64 69 67 69 74 73 20 69 6e 20 74 68 65 20  * digits in the 
1d5e0 74 69 6d 65 20 61 72 65 20 6d 65 61 6e 69 6e 67  time are meaning
1d5f0 6c 65 73 73 2e 20 20 46 75 74 75 72 65 20 76 65  less.  Future ve
1d600 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
1d610 0a 2a 2a 20 6d 69 67 68 74 20 70 72 6f 76 69 64  .** might provid
1d620 65 20 67 72 65 61 74 65 72 20 72 65 73 6f 6c 75  e greater resolu
1d630 74 69 6f 6e 20 6f 6e 20 74 68 65 20 70 72 6f 66  tion on the prof
1d640 69 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20 20  iler callback.  
1d650 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70  The.** sqlite3_p
1d660 72 6f 66 69 6c 65 28 29 20 66 75 6e 63 74 69 6f  rofile() functio
1d670 6e 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20  n is considered 
1d680 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64  experimental and
1d690 20 69 73 0a 2a 2a 20 73 75 62 6a 65 63 74 20 74   is.** subject t
1d6a0 6f 20 63 68 61 6e 67 65 20 69 6e 20 66 75 74 75  o change in futu
1d6b0 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  re versions of S
1d6c0 51 4c 69 74 65 2e 0a 2a 2f 0a 76 6f 69 64 20 2a  QLite..*/.void *
1d6d0 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 73 71  sqlite3_trace(sq
1d6e0 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a 78 54  lite3*, void(*xT
1d6f0 72 61 63 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73  race)(void*,cons
1d700 74 20 63 68 61 72 2a 29 2c 20 76 6f 69 64 2a 29  t char*), void*)
1d710 3b 0a 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d  ;.SQLITE_EXPERIM
1d720 45 4e 54 41 4c 20 76 6f 69 64 20 2a 73 71 6c 69  ENTAL void *sqli
1d730 74 65 33 5f 70 72 6f 66 69 6c 65 28 73 71 6c 69  te3_profile(sqli
1d740 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78  te3*,.   void(*x
1d750 50 72 6f 66 69 6c 65 29 28 76 6f 69 64 2a 2c 63  Profile)(void*,c
1d760 6f 6e 73 74 20 63 68 61 72 2a 2c 73 71 6c 69 74  onst char*,sqlit
1d770 65 33 5f 75 69 6e 74 36 34 29 2c 20 76 6f 69 64  e3_uint64), void
1d780 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
1d790 52 45 46 3a 20 51 75 65 72 79 20 50 72 6f 67 72  REF: Query Progr
1d7a0 65 73 73 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a  ess Callbacks.**
1d7b0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1d7c0 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65  _progress_handle
1d7d0 72 28 44 2c 4e 2c 58 2c 50 29 20 69 6e 74 65 72  r(D,N,X,P) inter
1d7e0 66 61 63 65 20 63 61 75 73 65 73 20 74 68 65 20  face causes the 
1d7f0 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63  callback.** func
1d800 74 69 6f 6e 20 58 20 74 6f 20 62 65 20 69 6e 76  tion X to be inv
1d810 6f 6b 65 64 20 70 65 72 69 6f 64 69 63 61 6c 6c  oked periodicall
1d820 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67 20 72 75  y during long ru
1d830 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f 0a 2a  nning calls to.*
1d840 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  * [sqlite3_exec(
1d850 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  )], [sqlite3_ste
1d860 70 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  p()] and [sqlite
1d870 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 66  3_get_table()] f
1d880 6f 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  or.** database c
1d890 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 20 41 6e  onnection D.  An
1d8a0 20 65 78 61 6d 70 6c 65 20 75 73 65 20 66 6f 72   example use for
1d8b0 20 74 68 69 73 0a 2a 2a 20 69 6e 74 65 72 66 61   this.** interfa
1d8c0 63 65 20 69 73 20 74 6f 20 6b 65 65 70 20 61 20  ce is to keep a 
1d8d0 47 55 49 20 75 70 64 61 74 65 64 20 64 75 72 69  GUI updated duri
1d8e0 6e 67 20 61 20 6c 61 72 67 65 20 71 75 65 72 79  ng a large query
1d8f0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 61 72  ..**.** ^The par
1d900 61 6d 65 74 65 72 20 50 20 69 73 20 70 61 73 73  ameter P is pass
1d910 65 64 20 74 68 72 6f 75 67 68 20 61 73 20 74 68  ed through as th
1d920 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72  e only parameter
1d930 20 74 6f 20 74 68 65 20 0a 2a 2a 20 63 61 6c 6c   to the .** call
1d940 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 58 2e  back function X.
1d950 20 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72    ^The parameter
1d960 20 4e 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72   N is the number
1d970 20 6f 66 20 0a 2a 2a 20 5b 76 69 72 74 75 61 6c   of .** [virtual
1d980 20 6d 61 63 68 69 6e 65 20 69 6e 73 74 72 75 63   machine instruc
1d990 74 69 6f 6e 73 5d 20 74 68 61 74 20 61 72 65 20  tions] that are 
1d9a0 65 76 61 6c 75 61 74 65 64 20 62 65 74 77 65 65  evaluated betwee
1d9b0 6e 20 73 75 63 63 65 73 73 69 76 65 0a 2a 2a 20  n successive.** 
1d9c0 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74  invocations of t
1d9d0 68 65 20 63 61 6c 6c 62 61 63 6b 20 58 2e 0a 2a  he callback X..*
1d9e0 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 61 20 73 69 6e  *.** ^Only a sin
1d9f0 67 6c 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e  gle progress han
1da00 64 6c 65 72 20 6d 61 79 20 62 65 20 64 65 66 69  dler may be defi
1da10 6e 65 64 20 61 74 20 6f 6e 65 20 74 69 6d 65 20  ned at one time 
1da20 70 65 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  per.** [database
1da30 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 3b 20 73 65   connection]; se
1da40 74 74 69 6e 67 20 61 20 6e 65 77 20 70 72 6f 67  tting a new prog
1da50 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61 6e  ress handler can
1da60 63 65 6c 73 20 74 68 65 0a 2a 2a 20 6f 6c 64 20  cels the.** old 
1da70 6f 6e 65 2e 20 20 5e 53 65 74 74 69 6e 67 20 70  one.  ^Setting p
1da80 61 72 61 6d 65 74 65 72 20 58 20 74 6f 20 4e 55  arameter X to NU
1da90 4c 4c 20 64 69 73 61 62 6c 65 73 20 74 68 65 20  LL disables the 
1daa0 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72  progress handler
1dab0 2e 0a 2a 2a 20 5e 54 68 65 20 70 72 6f 67 72 65  ..** ^The progre
1dac0 73 73 20 68 61 6e 64 6c 65 72 20 69 73 20 61 6c  ss handler is al
1dad0 73 6f 20 64 69 73 61 62 6c 65 64 20 62 79 20 73  so disabled by s
1dae0 65 74 74 69 6e 67 20 4e 20 74 6f 20 61 20 76 61  etting N to a va
1daf0 6c 75 65 20 6c 65 73 73 0a 2a 2a 20 74 68 61 6e  lue less.** than
1db00 20 31 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68   1..**.** ^If th
1db10 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62  e progress callb
1db20 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d  ack returns non-
1db30 7a 65 72 6f 2c 20 74 68 65 20 6f 70 65 72 61 74  zero, the operat
1db40 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74 65 72 72  ion is.** interr
1db50 75 70 74 65 64 2e 20 20 54 68 69 73 20 66 65 61  upted.  This fea
1db60 74 75 72 65 20 63 61 6e 20 62 65 20 75 73 65 64  ture can be used
1db70 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 0a   to implement a.
1db80 2a 2a 20 22 43 61 6e 63 65 6c 22 20 62 75 74 74  ** "Cancel" butt
1db90 6f 6e 20 6f 6e 20 61 20 47 55 49 20 70 72 6f 67  on on a GUI prog
1dba0 72 65 73 73 20 64 69 61 6c 6f 67 20 62 6f 78 2e  ress dialog box.
1dbb0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 6f 67 72  .**.** The progr
1dbc0 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c  ess handler call
1dbd0 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f  back must not do
1dbe0 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77   anything that w
1dbf0 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68  ill modify.** th
1dc00 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
1dc10 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b  ction that invok
1dc20 65 64 20 74 68 65 20 70 72 6f 67 72 65 73 73 20  ed the progress 
1dc30 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 4e 6f 74 65  handler..** Note
1dc40 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70   that [sqlite3_p
1dc50 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64  repare_v2()] and
1dc60 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
1dc70 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68  ] both modify th
1dc80 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  eir.** database 
1dc90 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20  connections for 
1dca0 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22  the meaning of "
1dcb0 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20  modify" in this 
1dcc0 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2f  paragraph..**.*/
1dcd0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 70 72  .void sqlite3_pr
1dce0 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 73  ogress_handler(s
1dcf0 71 6c 69 74 65 33 2a 2c 20 69 6e 74 2c 20 69 6e  qlite3*, int, in
1dd00 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69  t(*)(void*), voi
1dd10 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d*);../*.** CAPI
1dd20 33 52 45 46 3a 20 4f 70 65 6e 69 6e 67 20 41 20  3REF: Opening A 
1dd30 4e 65 77 20 44 61 74 61 62 61 73 65 20 43 6f 6e  New Database Con
1dd40 6e 65 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54  nection.**.** ^T
1dd50 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 70  hese routines op
1dd60 65 6e 20 61 6e 20 53 51 4c 69 74 65 20 64 61 74  en an SQLite dat
1dd70 61 62 61 73 65 20 66 69 6c 65 20 61 73 20 73 70  abase file as sp
1dd80 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 0a  ecified by the .
1dd90 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75  ** filename argu
1dda0 6d 65 6e 74 2e 20 5e 54 68 65 20 66 69 6c 65 6e  ment. ^The filen
1ddb0 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ame argument is 
1ddc0 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55  interpreted as U
1ddd0 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69  TF-8 for.** sqli
1dde0 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73  te3_open() and s
1ddf0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
1de00 20 61 6e 64 20 61 73 20 55 54 46 2d 31 36 20 69   and as UTF-16 i
1de10 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74  n the native byt
1de20 65 0a 2a 2a 20 6f 72 64 65 72 20 66 6f 72 20 73  e.** order for s
1de30 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e  qlite3_open16().
1de40 20 5e 28 41 20 5b 64 61 74 61 62 61 73 65 20 63   ^(A [database c
1de50 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c  onnection] handl
1de60 65 20 69 73 20 75 73 75 61 6c 6c 79 0a 2a 2a 20  e is usually.** 
1de70 72 65 74 75 72 6e 65 64 20 69 6e 20 2a 70 70 44  returned in *ppD
1de80 62 2c 20 65 76 65 6e 20 69 66 20 61 6e 20 65 72  b, even if an er
1de90 72 6f 72 20 6f 63 63 75 72 73 2e 20 20 54 68 65  ror occurs.  The
1dea0 20 6f 6e 6c 79 20 65 78 63 65 70 74 69 6f 6e 20   only exception 
1deb0 69 73 20 74 68 61 74 0a 2a 2a 20 69 66 20 53 51  is that.** if SQ
1dec0 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74  Lite is unable t
1ded0 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72  o allocate memor
1dee0 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 5b 73  y to hold the [s
1def0 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2c 0a  qlite3] object,.
1df00 2a 2a 20 61 20 4e 55 4c 4c 20 77 69 6c 6c 20 62  ** a NULL will b
1df10 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a  e written into *
1df20 70 70 44 62 20 69 6e 73 74 65 61 64 20 6f 66 20  ppDb instead of 
1df30 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
1df40 20 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62   [sqlite3].** ob
1df50 6a 65 63 74 2e 29 5e 20 5e 28 49 66 20 74 68 65  ject.)^ ^(If the
1df60 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
1df70 6e 65 64 20 28 61 6e 64 2f 6f 72 20 63 72 65 61  ned (and/or crea
1df80 74 65 64 29 20 73 75 63 63 65 73 73 66 75 6c 6c  ted) successfull
1df90 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49  y, then.** [SQLI
1dfa0 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e  TE_OK] is return
1dfb0 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 61  ed.  Otherwise a
1dfc0 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  n [error code] i
1dfd0 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 5e 54  s returned.)^ ^T
1dfe0 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  he.** [sqlite3_e
1dff0 72 72 6d 73 67 28 29 5d 20 6f 72 20 5b 73 71 6c  rrmsg()] or [sql
1e000 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d  ite3_errmsg16()]
1e010 20 72 6f 75 74 69 6e 65 73 20 63 61 6e 20 62 65   routines can be
1e020 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 0a   used to obtain.
1e030 2a 2a 20 61 6e 20 45 6e 67 6c 69 73 68 20 6c 61  ** an English la
1e040 6e 67 75 61 67 65 20 64 65 73 63 72 69 70 74 69  nguage descripti
1e050 6f 6e 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20  on of the error 
1e060 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c  following a fail
1e070 75 72 65 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66  ure of any.** of
1e080 20 74 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65   the sqlite3_ope
1e090 6e 28 29 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a  n() routines..**
1e0a0 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74  .** ^The default
1e0b0 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20 74 68   encoding for th
1e0c0 65 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20  e database will 
1e0d0 62 65 20 55 54 46 2d 38 20 69 66 0a 2a 2a 20 73  be UTF-8 if.** s
1e0e0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72  qlite3_open() or
1e0f0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
1e100 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 6e 64  () is called and
1e110 0a 2a 2a 20 55 54 46 2d 31 36 20 69 6e 20 74 68  .** UTF-16 in th
1e120 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  e native byte or
1e130 64 65 72 20 69 66 20 73 71 6c 69 74 65 33 5f 6f  der if sqlite3_o
1e140 70 65 6e 31 36 28 29 20 69 73 20 75 73 65 64 2e  pen16() is used.
1e150 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68 65 72 20 6f  .**.** Whether o
1e160 72 20 6e 6f 74 20 61 6e 20 65 72 72 6f 72 20 6f  r not an error o
1e170 63 63 75 72 73 20 77 68 65 6e 20 69 74 20 69 73  ccurs when it is
1e180 20 6f 70 65 6e 65 64 2c 20 72 65 73 6f 75 72 63   opened, resourc
1e190 65 73 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64  es.** associated
1e1a0 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62   with the [datab
1e1b0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
1e1c0 68 61 6e 64 6c 65 20 73 68 6f 75 6c 64 20 62 65  handle should be
1e1d0 20 72 65 6c 65 61 73 65 64 20 62 79 0a 2a 2a 20   released by.** 
1e1e0 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73  passing it to [s
1e1f0 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20  qlite3_close()] 
1e200 77 68 65 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f  when it is no lo
1e210 6e 67 65 72 20 72 65 71 75 69 72 65 64 2e 0a 2a  nger required..*
1e220 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
1e230 5f 6f 70 65 6e 5f 76 32 28 29 20 69 6e 74 65 72  _open_v2() inter
1e240 66 61 63 65 20 77 6f 72 6b 73 20 6c 69 6b 65 20  face works like 
1e250 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 0a 2a  sqlite3_open().*
1e260 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74  * except that it
1e270 20 61 63 63 65 70 74 73 20 74 77 6f 20 61 64 64   accepts two add
1e280 69 74 69 6f 6e 61 6c 20 70 61 72 61 6d 65 74 65  itional paramete
1e290 72 73 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  rs for additiona
1e2a0 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65  l control.** ove
1e2b0 72 20 74 68 65 20 6e 65 77 20 64 61 74 61 62 61  r the new databa
1e2c0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20  se connection.  
1e2d0 5e 28 54 68 65 20 66 6c 61 67 73 20 70 61 72 61  ^(The flags para
1e2e0 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 73 71 6c 69  meter to.** sqli
1e2f0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 63 61  te3_open_v2() ca
1e300 6e 20 74 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a  n take one of.**
1e310 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74   the following t
1e320 68 72 65 65 20 76 61 6c 75 65 73 2c 20 6f 70 74  hree values, opt
1e330 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64  ionally combined
1e340 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53   with the .** [S
1e350 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54  QLITE_OPEN_NOMUT
1e360 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45  EX], [SQLITE_OPE
1e370 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 2c 20 5b 53  N_FULLMUTEX], [S
1e380 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45  QLITE_OPEN_SHARE
1e390 44 43 41 43 48 45 5d 2c 0a 2a 2a 20 5b 53 51 4c  DCACHE],.** [SQL
1e3a0 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45  ITE_OPEN_PRIVATE
1e3b0 43 41 43 48 45 5d 2c 20 61 6e 64 2f 6f 72 20 5b  CACHE], and/or [
1e3c0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d  SQLITE_OPEN_URI]
1e3d0 20 66 6c 61 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20   flags:)^.**.** 
1e3e0 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53  <dl>.** ^(<dt>[S
1e3f0 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f  QLITE_OPEN_READO
1e400 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  NLY]</dt>.** <dd
1e410 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73  >The database is
1e420 20 6f 70 65 6e 65 64 20 69 6e 20 72 65 61 64 2d   opened in read-
1e430 6f 6e 6c 79 20 6d 6f 64 65 2e 20 20 49 66 20 74  only mode.  If t
1e440 68 65 20 64 61 74 61 62 61 73 65 20 64 6f 65 73  he database does
1e450 20 6e 6f 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20   not.** already 
1e460 65 78 69 73 74 2c 20 61 6e 20 65 72 72 6f 72 20  exist, an error 
1e470 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64  is returned.</dd
1e480 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e  >)^.**.** ^(<dt>
1e490 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
1e4a0 44 57 52 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20  DWRITE]</dt>.** 
1e4b0 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65  <dd>The database
1e4c0 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72   is opened for r
1e4d0 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69  eading and writi
1e4e0 6e 67 20 69 66 20 70 6f 73 73 69 62 6c 65 2c 20  ng if possible, 
1e4f0 6f 72 20 72 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e  or reading.** on
1e500 6c 79 20 69 66 20 74 68 65 20 66 69 6c 65 20 69  ly if the file i
1e510 73 20 77 72 69 74 65 20 70 72 6f 74 65 63 74 65  s write protecte
1e520 64 20 62 79 20 74 68 65 20 6f 70 65 72 61 74 69  d by the operati
1e530 6e 67 20 73 79 73 74 65 6d 2e 20 20 49 6e 20 65  ng system.  In e
1e540 69 74 68 65 72 0a 2a 2a 20 63 61 73 65 20 74 68  ither.** case th
1e550 65 20 64 61 74 61 62 61 73 65 20 6d 75 73 74 20  e database must 
1e560 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20 6f  already exist, o
1e570 74 68 65 72 77 69 73 65 20 61 6e 20 65 72 72 6f  therwise an erro
1e580 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f  r is returned.</
1e590 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64  dd>)^.**.** ^(<d
1e5a0 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  t>[SQLITE_OPEN_R
1e5b0 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c  EADWRITE] | [SQL
1e5c0 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d  ITE_OPEN_CREATE]
1e5d0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
1e5e0 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
1e5f0 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20  ned for reading 
1e600 61 6e 64 20 77 72 69 74 69 6e 67 2c 20 61 6e 64  and writing, and
1e610 20 69 73 20 63 72 65 61 74 65 64 20 69 66 0a 2a   is created if.*
1e620 2a 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 61 6c  * it does not al
1e630 72 65 61 64 79 20 65 78 69 73 74 2e 20 54 68 69  ready exist. Thi
1e640 73 20 69 73 20 74 68 65 20 62 65 68 61 76 69 6f  s is the behavio
1e650 72 20 74 68 61 74 20 69 73 20 61 6c 77 61 79 73  r that is always
1e660 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 73 71 6c   used for.** sql
1e670 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20  ite3_open() and 
1e680 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
1e690 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c  .</dd>)^.** </dl
1e6a0 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 33  >.**.** If the 3
1e6b0 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
1e6c0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
1e6d0 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20  ) is not one of 
1e6e0 74 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74 69  the.** combinati
1e6f0 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 20  ons shown above 
1e700 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69  optionally combi
1e710 6e 65 64 20 77 69 74 68 20 6f 74 68 65 72 0a 2a  ned with other.*
1e720 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  * [SQLITE_OPEN_R
1e730 45 41 44 4f 4e 4c 59 20 7c 20 53 51 4c 49 54 45  EADONLY | SQLITE
1e740 5f 4f 50 45 4e 5f 2a 20 62 69 74 73 5d 0a 2a 2a  _OPEN_* bits].**
1e750 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
1e760 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  or is undefined.
1e770 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b  .**.** ^If the [
1e780 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55  SQLITE_OPEN_NOMU
1e790 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74  TEX] flag is set
1e7a0 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62  , then the datab
1e7b0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase connection.*
1e7c0 2a 20 6f 70 65 6e 73 20 69 6e 20 74 68 65 20 6d  * opens in the m
1e7d0 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72  ulti-thread [thr
1e7e0 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 73 20  eading mode] as 
1e7f0 6c 6f 6e 67 20 61 73 20 74 68 65 20 73 69 6e 67  long as the sing
1e800 6c 65 2d 74 68 72 65 61 64 0a 2a 2a 20 6d 6f 64  le-thread.** mod
1e810 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 73  e has not been s
1e820 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69  et at compile-ti
1e830 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65  me or start-time
1e840 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53  .  ^If the.** [S
1e850 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d  QLITE_OPEN_FULLM
1e860 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65  UTEX] flag is se
1e870 74 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62  t then the datab
1e880 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f  ase connection o
1e890 70 65 6e 73 0a 2a 2a 20 69 6e 20 74 68 65 20 73  pens.** in the s
1e8a0 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61  erialized [threa
1e8b0 64 69 6e 67 20 6d 6f 64 65 5d 20 75 6e 6c 65 73  ding mode] unles
1e8c0 73 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 20  s single-thread 
1e8d0 77 61 73 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c  was.** previousl
1e8e0 79 20 73 65 6c 65 63 74 65 64 20 61 74 20 63 6f  y selected at co
1e8f0 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74  mpile-time or st
1e900 61 72 74 2d 74 69 6d 65 2e 0a 2a 2a 20 5e 54 68  art-time..** ^Th
1e910 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53  e [SQLITE_OPEN_S
1e920 48 41 52 45 44 43 41 43 48 45 5d 20 66 6c 61 67  HAREDCACHE] flag
1e930 20 63 61 75 73 65 73 20 74 68 65 20 64 61 74 61   causes the data
1e940 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
1e950 74 6f 20 62 65 0a 2a 2a 20 65 6c 69 67 69 62 6c  to be.** eligibl
1e960 65 20 74 6f 20 75 73 65 20 5b 73 68 61 72 65 64  e to use [shared
1e970 20 63 61 63 68 65 20 6d 6f 64 65 5d 2c 20 72 65   cache mode], re
1e980 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74  gardless of whet
1e990 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65  her or not share
1e9a0 64 0a 2a 2a 20 63 61 63 68 65 20 69 73 20 65 6e  d.** cache is en
1e9b0 61 62 6c 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  abled using [sql
1e9c0 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72  ite3_enable_shar
1e9d0 65 64 5f 63 61 63 68 65 28 29 5d 2e 20 20 5e 54  ed_cache()].  ^T
1e9e0 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50  he.** [SQLITE_OP
1e9f0 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d  EN_PRIVATECACHE]
1ea00 20 66 6c 61 67 20 63 61 75 73 65 73 20 74 68 65   flag causes the
1ea10 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1ea20 74 69 6f 6e 20 74 6f 20 6e 6f 74 0a 2a 2a 20 70  tion to not.** p
1ea30 61 72 74 69 63 69 70 61 74 65 20 69 6e 20 5b 73  articipate in [s
1ea40 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65  hared cache mode
1ea50 5d 20 65 76 65 6e 20 69 66 20 69 74 20 69 73 20  ] even if it is 
1ea60 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  enabled..**.** ^
1ea70 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  The fourth param
1ea80 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
1ea90 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 74 68 65  open_v2() is the
1eaa0 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20   name of the.** 
1eab0 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
1eac0 6a 65 63 74 20 74 68 61 74 20 64 65 66 69 6e 65  ject that define
1ead0 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20  s the operating 
1eae0 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65  system interface
1eaf0 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 65 77   that.** the new
1eb00 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1eb10 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 2e  tion should use.
1eb20 20 20 5e 49 66 20 74 68 65 20 66 6f 75 72 74 68    ^If the fourth
1eb30 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a   parameter is.**
1eb40 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
1eb50 74 68 65 6e 20 74 68 65 20 64 65 66 61 75 6c 74  then the default
1eb60 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f   [sqlite3_vfs] o
1eb70 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e 0a 2a  bject is used..*
1eb80 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 6c  *.** ^If the fil
1eb90 65 6e 61 6d 65 20 69 73 20 22 3a 6d 65 6d 6f 72  ename is ":memor
1eba0 79 3a 22 2c 20 74 68 65 6e 20 61 20 70 72 69 76  y:", then a priv
1ebb0 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 20 69  ate, temporary i
1ebc0 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73  n-memory databas
1ebd0 65 0a 2a 2a 20 69 73 20 63 72 65 61 74 65 64 20  e.** is created 
1ebe0 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63 74 69  for the connecti
1ebf0 6f 6e 2e 20 20 5e 54 68 69 73 20 69 6e 2d 6d 65  on.  ^This in-me
1ec00 6d 6f 72 79 20 64 61 74 61 62 61 73 65 20 77 69  mory database wi
1ec10 6c 6c 20 76 61 6e 69 73 68 20 77 68 65 6e 0a 2a  ll vanish when.*
1ec20 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  * the database c
1ec30 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f  onnection is clo
1ec40 73 65 64 2e 20 20 46 75 74 75 72 65 20 76 65 72  sed.  Future ver
1ec50 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20  sions of SQLite 
1ec60 6d 69 67 68 74 0a 2a 2a 20 6d 61 6b 65 20 75 73  might.** make us
1ec70 65 20 6f 66 20 61 64 64 69 74 69 6f 6e 61 6c 20  e of additional 
1ec80 73 70 65 63 69 61 6c 20 66 69 6c 65 6e 61 6d 65  special filename
1ec90 73 20 74 68 61 74 20 62 65 67 69 6e 20 77 69 74  s that begin wit
1eca0 68 20 74 68 65 20 22 3a 22 20 63 68 61 72 61 63  h the ":" charac
1ecb0 74 65 72 2e 0a 2a 2a 20 49 74 20 69 73 20 72 65  ter..** It is re
1ecc0 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 77  commended that w
1ecd0 68 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 66  hen a database f
1ece0 69 6c 65 6e 61 6d 65 20 61 63 74 75 61 6c 6c 79  ilename actually
1ecf0 20 64 6f 65 73 20 62 65 67 69 6e 20 77 69 74 68   does begin with
1ed00 0a 2a 2a 20 61 20 22 3a 22 20 63 68 61 72 61 63  .** a ":" charac
1ed10 74 65 72 20 79 6f 75 20 73 68 6f 75 6c 64 20 70  ter you should p
1ed20 72 65 66 69 78 20 74 68 65 20 66 69 6c 65 6e 61  refix the filena
1ed30 6d 65 20 77 69 74 68 20 61 20 70 61 74 68 6e 61  me with a pathna
1ed40 6d 65 20 73 75 63 68 20 61 73 0a 2a 2a 20 22 2e  me such as.** ".
1ed50 2f 22 20 74 6f 20 61 76 6f 69 64 20 61 6d 62 69  /" to avoid ambi
1ed60 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  guity..**.** ^If
1ed70 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73   the filename is
1ed80 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67   an empty string
1ed90 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 65  , then a private
1eda0 2c 20 74 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f  , temporary.** o
1edb0 6e 2d 64 69 73 6b 20 64 61 74 61 62 61 73 65 20  n-disk database 
1edc0 77 69 6c 6c 20 62 65 20 63 72 65 61 74 65 64 2e  will be created.
1edd0 20 20 5e 54 68 69 73 20 70 72 69 76 61 74 65 20    ^This private 
1ede0 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65  database will be
1edf0 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  .** automaticall
1ee00 79 20 64 65 6c 65 74 65 64 20 61 73 20 73 6f 6f  y deleted as soo
1ee10 6e 20 61 73 20 74 68 65 20 64 61 74 61 62 61 73  n as the databas
1ee20 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
1ee30 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b  closed..**.** [[
1ee40 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 69 6e  URI filenames in
1ee50 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d   sqlite3_open()]
1ee60 5d 20 3c 68 33 3e 55 52 49 20 46 69 6c 65 6e 61  ] <h3>URI Filena
1ee70 6d 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 5e  mes</h3>.**.** ^
1ee80 49 66 20 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65  If [URI filename
1ee90 5d 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e  ] interpretation
1eea0 20 69 73 20 65 6e 61 62 6c 65 64 2c 20 61 6e 64   is enabled, and
1eeb0 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72   the filename ar
1eec0 67 75 6d 65 6e 74 0a 2a 2a 20 62 65 67 69 6e 73  gument.** begins
1eed0 20 77 69 74 68 20 22 66 69 6c 65 3a 22 2c 20 74   with "file:", t
1eee0 68 65 6e 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  hen the filename
1eef0 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20   is interpreted 
1ef00 61 73 20 61 20 55 52 49 2e 20 5e 55 52 49 0a 2a  as a URI. ^URI.*
1ef10 2a 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72  * filename inter
1ef20 70 72 65 74 61 74 69 6f 6e 20 69 73 20 65 6e 61  pretation is ena
1ef30 62 6c 65 64 20 69 66 20 74 68 65 20 5b 53 51 4c  bled if the [SQL
1ef40 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c  ITE_OPEN_URI] fl
1ef50 61 67 20 69 73 0a 2a 2a 20 73 65 74 20 69 6e 20  ag is.** set in 
1ef60 74 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d  the fourth argum
1ef70 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f  ent to sqlite3_o
1ef80 70 65 6e 5f 76 32 28 29 2c 20 6f 72 20 69 66 20  pen_v2(), or if 
1ef90 69 74 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 65  it has.** been e
1efa0 6e 61 62 6c 65 64 20 67 6c 6f 62 61 6c 6c 79 20  nabled globally 
1efb0 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54  using the [SQLIT
1efc0 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 20 6f 70  E_CONFIG_URI] op
1efd0 74 69 6f 6e 20 77 69 74 68 20 74 68 65 0a 2a 2a  tion with the.**
1efe0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
1eff0 28 29 5d 20 6d 65 74 68 6f 64 20 6f 72 20 62 79  ()] method or by
1f000 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 55 53 45   the [SQLITE_USE
1f010 5f 55 52 49 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  _URI] compile-ti
1f020 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 41 73  me option..** As
1f030 20 6f 66 20 53 51 4c 69 74 65 20 76 65 72 73 69   of SQLite versi
1f040 6f 6e 20 33 2e 37 2e 37 2c 20 55 52 49 20 66 69  on 3.7.7, URI fi
1f050 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 65 74  lename interpret
1f060 61 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20  ation is turned 
1f070 6f 66 66 0a 2a 2a 20 62 79 20 64 65 66 61 75 6c  off.** by defaul
1f080 74 2c 20 62 75 74 20 66 75 74 75 72 65 20 72 65  t, but future re
1f090 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65  leases of SQLite
1f0a0 20 6d 69 67 68 74 20 65 6e 61 62 6c 65 20 55 52   might enable UR
1f0b0 49 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 69 6e  I filename.** in
1f0c0 74 65 72 70 72 65 74 61 74 69 6f 6e 20 62 79 20  terpretation by 
1f0d0 64 65 66 61 75 6c 74 2e 20 20 53 65 65 20 22 5b  default.  See "[
1f0e0 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 5d 22 20  URI filenames]" 
1f0f0 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a  for additional.*
1f100 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  * information..*
1f110 2a 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d  *.** URI filenam
1f120 65 73 20 61 72 65 20 70 61 72 73 65 64 20 61 63  es are parsed ac
1f130 63 6f 72 64 69 6e 67 20 74 6f 20 52 46 43 20 33  cording to RFC 3
1f140 39 38 36 2e 20 5e 49 66 20 74 68 65 20 55 52 49  986. ^If the URI
1f150 20 63 6f 6e 74 61 69 6e 73 20 61 6e 0a 2a 2a 20   contains an.** 
1f160 61 75 74 68 6f 72 69 74 79 2c 20 74 68 65 6e 20  authority, then 
1f170 69 74 20 6d 75 73 74 20 62 65 20 65 69 74 68 65  it must be eithe
1f180 72 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e  r an empty strin
1f190 67 20 6f 72 20 74 68 65 20 73 74 72 69 6e 67 20  g or the string 
1f1a0 0a 2a 2a 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2e  .** "localhost".
1f1b0 20 5e 49 66 20 74 68 65 20 61 75 74 68 6f 72 69   ^If the authori
1f1c0 74 79 20 69 73 20 6e 6f 74 20 61 6e 20 65 6d 70  ty is not an emp
1f1d0 74 79 20 73 74 72 69 6e 67 20 6f 72 20 22 6c 6f  ty string or "lo
1f1e0 63 61 6c 68 6f 73 74 22 2c 20 61 6e 20 0a 2a 2a  calhost", an .**
1f1f0 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e   error is return
1f200 65 64 20 74 6f 20 74 68 65 20 63 61 6c 6c 65 72  ed to the caller
1f210 2e 20 5e 54 68 65 20 66 72 61 67 6d 65 6e 74 20  . ^The fragment 
1f220 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55  component of a U
1f230 52 49 2c 20 69 66 20 0a 2a 2a 20 70 72 65 73 65  RI, if .** prese
1f240 6e 74 2c 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a  nt, is ignored..
1f250 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73  **.** ^SQLite us
1f260 65 73 20 74 68 65 20 70 61 74 68 20 63 6f 6d 70  es the path comp
1f270 6f 6e 65 6e 74 20 6f 66 20 74 68 65 20 55 52 49  onent of the URI
1f280 20 61 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   as the name of 
1f290 74 68 65 20 64 69 73 6b 20 66 69 6c 65 0a 2a 2a  the disk file.**
1f2a0 20 77 68 69 63 68 20 63 6f 6e 74 61 69 6e 73 20   which contains 
1f2b0 74 68 65 20 64 61 74 61 62 61 73 65 2e 20 5e 49  the database. ^I
1f2c0 66 20 74 68 65 20 70 61 74 68 20 62 65 67 69 6e  f the path begin
1f2d0 73 20 77 69 74 68 20 61 20 27 2f 27 20 63 68 61  s with a '/' cha
1f2e0 72 61 63 74 65 72 2c 20 0a 2a 2a 20 74 68 65 6e  racter, .** then
1f2f0 20 69 74 20 69 73 20 69 6e 74 65 72 70 72 65 74   it is interpret
1f300 65 64 20 61 73 20 61 6e 20 61 62 73 6f 6c 75 74  ed as an absolut
1f310 65 20 70 61 74 68 2e 20 5e 49 66 20 74 68 65 20  e path. ^If the 
1f320 70 61 74 68 20 64 6f 65 73 20 6e 6f 74 20 62 65  path does not be
1f330 67 69 6e 20 0a 2a 2a 20 77 69 74 68 20 61 20 27  gin .** with a '
1f340 2f 27 20 28 6d 65 61 6e 69 6e 67 20 74 68 61 74  /' (meaning that
1f350 20 74 68 65 20 61 75 74 68 6f 72 69 74 79 20 73   the authority s
1f360 65 63 74 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65  ection is omitte
1f370 64 20 66 72 6f 6d 20 74 68 65 20 55 52 49 29 0a  d from the URI).
1f380 2a 2a 20 74 68 65 6e 20 74 68 65 20 70 61 74 68  ** then the path
1f390 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20   is interpreted 
1f3a0 61 73 20 61 20 72 65 6c 61 74 69 76 65 20 70 61  as a relative pa
1f3b0 74 68 2e 20 0a 2a 2a 20 5e 4f 6e 20 77 69 6e 64  th. .** ^On wind
1f3c0 6f 77 73 2c 20 74 68 65 20 66 69 72 73 74 20 63  ows, the first c
1f3d0 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 6e 20 61  omponent of an a
1f3e0 62 73 6f 6c 75 74 65 20 70 61 74 68 20 0a 2a 2a  bsolute path .**
1f3f0 20 69 73 20 61 20 64 72 69 76 65 20 73 70 65 63   is a drive spec
1f400 69 66 69 63 61 74 69 6f 6e 20 28 65 2e 67 2e 20  ification (e.g. 
1f410 22 43 3a 22 29 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 63  "C:")..**.** [[c
1f420 6f 72 65 20 55 52 49 20 71 75 65 72 79 20 70 61  ore URI query pa
1f430 72 61 6d 65 74 65 72 73 5d 5d 0a 2a 2a 20 54 68  rameters]].** Th
1f440 65 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e  e query componen
1f450 74 20 6f 66 20 61 20 55 52 49 20 6d 61 79 20 63  t of a URI may c
1f460 6f 6e 74 61 69 6e 20 70 61 72 61 6d 65 74 65 72  ontain parameter
1f470 73 20 74 68 61 74 20 61 72 65 20 69 6e 74 65 72  s that are inter
1f480 70 72 65 74 65 64 0a 2a 2a 20 65 69 74 68 65 72  preted.** either
1f490 20 62 79 20 53 51 4c 69 74 65 20 69 74 73 65 6c   by SQLite itsel
1f4a0 66 2c 20 6f 72 20 62 79 20 61 20 5b 56 46 53 20  f, or by a [VFS 
1f4b0 7c 20 63 75 73 74 6f 6d 20 56 46 53 20 69 6d 70  | custom VFS imp
1f4c0 6c 65 6d 65 6e 74 61 74 69 6f 6e 5d 2e 0a 2a 2a  lementation]..**
1f4d0 20 53 51 4c 69 74 65 20 69 6e 74 65 72 70 72 65   SQLite interpre
1f4e0 74 73 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  ts the following
1f4f0 20 74 68 72 65 65 20 71 75 65 72 79 20 70 61 72   three query par
1f500 61 6d 65 74 65 72 73 3a 0a 2a 2a 0a 2a 2a 20 3c  ameters:.**.** <
1f510 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62  ul>.**   <li> <b
1f520 3e 76 66 73 3c 2f 62 3e 3a 20 5e 54 68 65 20 22  >vfs</b>: ^The "
1f530 76 66 73 22 20 70 61 72 61 6d 65 74 65 72 20 6d  vfs" parameter m
1f540 61 79 20 62 65 20 75 73 65 64 20 74 6f 20 73 70  ay be used to sp
1f550 65 63 69 66 79 20 74 68 65 20 6e 61 6d 65 20 6f  ecify the name o
1f560 66 0a 2a 2a 20 20 20 20 20 61 20 56 46 53 20 6f  f.**     a VFS o
1f570 62 6a 65 63 74 20 74 68 61 74 20 70 72 6f 76 69  bject that provi
1f580 64 65 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e  des the operatin
1f590 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61  g system interfa
1f5a0 63 65 20 74 68 61 74 20 73 68 6f 75 6c 64 0a 2a  ce that should.*
1f5b0 2a 20 20 20 20 20 62 65 20 75 73 65 64 20 74 6f  *     be used to
1f5c0 20 61 63 63 65 73 73 20 74 68 65 20 64 61 74 61   access the data
1f5d0 62 61 73 65 20 66 69 6c 65 20 6f 6e 20 64 69 73  base file on dis
1f5e0 6b 2e 20 5e 49 66 20 74 68 69 73 20 6f 70 74 69  k. ^If this opti
1f5f0 6f 6e 20 69 73 20 73 65 74 20 74 6f 0a 2a 2a 20  on is set to.** 
1f600 20 20 20 20 61 6e 20 65 6d 70 74 79 20 73 74 72      an empty str
1f610 69 6e 67 20 74 68 65 20 64 65 66 61 75 6c 74 20  ing the default 
1f620 56 46 53 20 6f 62 6a 65 63 74 20 69 73 20 75 73  VFS object is us
1f630 65 64 2e 20 5e 53 70 65 63 69 66 79 69 6e 67 20  ed. ^Specifying 
1f640 61 6e 20 75 6e 6b 6e 6f 77 6e 0a 2a 2a 20 20 20  an unknown.**   
1f650 20 20 56 46 53 20 69 73 20 61 6e 20 65 72 72 6f    VFS is an erro
1f660 72 2e 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f  r. ^If sqlite3_o
1f670 70 65 6e 5f 76 32 28 29 20 69 73 20 75 73 65 64  pen_v2() is used
1f680 20 61 6e 64 20 74 68 65 20 76 66 73 20 6f 70 74   and the vfs opt
1f690 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20 70 72  ion is.**     pr
1f6a0 65 73 65 6e 74 2c 20 74 68 65 6e 20 74 68 65 20  esent, then the 
1f6b0 56 46 53 20 73 70 65 63 69 66 69 65 64 20 62 79  VFS specified by
1f6c0 20 74 68 65 20 6f 70 74 69 6f 6e 20 74 61 6b 65   the option take
1f6d0 73 20 70 72 65 63 65 64 65 6e 63 65 20 6f 76 65  s precedence ove
1f6e0 72 0a 2a 2a 20 20 20 20 20 74 68 65 20 76 61 6c  r.**     the val
1f6f0 75 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  ue passed as the
1f700 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
1f710 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65  r to sqlite3_ope
1f720 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20  n_v2()..**.**   
1f730 3c 6c 69 3e 20 3c 62 3e 6d 6f 64 65 3c 2f 62 3e  <li> <b>mode</b>
1f740 3a 20 5e 28 54 68 65 20 6d 6f 64 65 20 70 61 72  : ^(The mode par
1f750 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 73 65  ameter may be se
1f760 74 20 74 6f 20 65 69 74 68 65 72 20 22 72 6f 22  t to either "ro"
1f770 2c 20 22 72 77 22 2c 0a 2a 2a 20 20 20 20 20 22  , "rw",.**     "
1f780 72 77 63 22 2c 20 6f 72 20 22 6d 65 6d 6f 72 79  rwc", or "memory
1f790 22 2e 20 41 74 74 65 6d 70 74 69 6e 67 20 74 6f  ". Attempting to
1f7a0 20 73 65 74 20 69 74 20 74 6f 20 61 6e 79 20 6f   set it to any o
1f7b0 74 68 65 72 20 76 61 6c 75 65 20 69 73 0a 2a 2a  ther value is.**
1f7c0 20 20 20 20 20 61 6e 20 65 72 72 6f 72 29 5e 2e       an error)^.
1f7d0 20 0a 2a 2a 20 20 20 20 20 5e 49 66 20 22 72 6f   .**     ^If "ro
1f7e0 22 20 69 73 20 73 70 65 63 69 66 69 65 64 2c 20  " is specified, 
1f7f0 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  then the databas
1f800 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20  e is opened for 
1f810 72 65 61 64 2d 6f 6e 6c 79 20 0a 2a 2a 20 20 20  read-only .**   
1f820 20 20 61 63 63 65 73 73 2c 20 6a 75 73 74 20 61    access, just a
1f830 73 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45  s if the [SQLITE
1f840 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 20  _OPEN_READONLY] 
1f850 66 6c 61 67 20 68 61 64 20 62 65 65 6e 20 73 65  flag had been se
1f860 74 20 69 6e 20 74 68 65 20 0a 2a 2a 20 20 20 20  t in the .**    
1f870 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
1f880 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  to sqlite3_open_
1f890 76 32 28 29 2e 20 5e 49 66 20 74 68 65 20 6d 6f  v2(). ^If the mo
1f8a0 64 65 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74  de option is set
1f8b0 20 74 6f 20 0a 2a 2a 20 20 20 20 20 22 72 77 22   to .**     "rw"
1f8c0 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62  , then the datab
1f8d0 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f  ase is opened fo
1f8e0 72 20 72 65 61 64 2d 77 72 69 74 65 20 28 62 75  r read-write (bu
1f8f0 74 20 6e 6f 74 20 63 72 65 61 74 65 29 20 0a 2a  t not create) .*
1f900 2a 20 20 20 20 20 61 63 63 65 73 73 2c 20 61 73  *     access, as
1f910 20 69 66 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f   if SQLITE_OPEN_
1f920 52 45 41 44 57 52 49 54 45 20 28 62 75 74 20 6e  READWRITE (but n
1f930 6f 74 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  ot SQLITE_OPEN_C
1f940 52 45 41 54 45 29 20 68 61 64 20 0a 2a 2a 20 20  REATE) had .**  
1f950 20 20 20 62 65 65 6e 20 73 65 74 2e 20 5e 56 61     been set. ^Va
1f960 6c 75 65 20 22 72 77 63 22 20 69 73 20 65 71 75  lue "rwc" is equ
1f970 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69  ivalent to setti
1f980 6e 67 20 62 6f 74 68 20 0a 2a 2a 20 20 20 20 20  ng both .**     
1f990 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
1f9a0 57 52 49 54 45 20 61 6e 64 20 53 51 4c 49 54 45  WRITE and SQLITE
1f9b0 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2e 20 20 5e  _OPEN_CREATE.  ^
1f9c0 49 66 20 74 68 65 20 6d 6f 64 65 20 6f 70 74 69  If the mode opti
1f9d0 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20 73 65 74  on is.**     set
1f9e0 20 74 6f 20 22 6d 65 6d 6f 72 79 22 20 74 68 65   to "memory" the
1f9f0 6e 20 61 20 70 75 72 65 20 5b 69 6e 2d 6d 65 6d  n a pure [in-mem
1fa00 6f 72 79 20 64 61 74 61 62 61 73 65 5d 20 74 68  ory database] th
1fa10 61 74 20 6e 65 76 65 72 20 72 65 61 64 73 0a 2a  at never reads.*
1fa20 2a 20 20 20 20 20 6f 72 20 77 72 69 74 65 73 20  *     or writes 
1fa30 66 72 6f 6d 20 64 69 73 6b 20 69 73 20 75 73 65  from disk is use
1fa40 64 2e 20 5e 49 74 20 69 73 20 61 6e 20 65 72 72  d. ^It is an err
1fa50 6f 72 20 74 6f 20 73 70 65 63 69 66 79 20 61 20  or to specify a 
1fa60 76 61 6c 75 65 20 66 6f 72 0a 2a 2a 20 20 20 20  value for.**    
1fa70 20 74 68 65 20 6d 6f 64 65 20 70 61 72 61 6d 65   the mode parame
1fa80 74 65 72 20 74 68 61 74 20 69 73 20 6c 65 73 73  ter that is less
1fa90 20 72 65 73 74 72 69 63 74 69 76 65 20 74 68 61   restrictive tha
1faa0 6e 20 74 68 61 74 20 73 70 65 63 69 66 69 65 64  n that specified
1fab0 20 62 79 0a 2a 2a 20 20 20 20 20 74 68 65 20 66   by.**     the f
1fac0 6c 61 67 73 20 70 61 73 73 65 64 20 69 6e 20 74  lags passed in t
1fad0 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
1fae0 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70  er to sqlite3_op
1faf0 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20  en_v2()..**.**  
1fb00 20 3c 6c 69 3e 20 3c 62 3e 63 61 63 68 65 3c 2f   <li> <b>cache</
1fb10 62 3e 3a 20 5e 54 68 65 20 63 61 63 68 65 20 70  b>: ^The cache p
1fb20 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20  arameter may be 
1fb30 73 65 74 20 74 6f 20 65 69 74 68 65 72 20 22 73  set to either "s
1fb40 68 61 72 65 64 22 20 6f 72 0a 2a 2a 20 20 20 20  hared" or.**    
1fb50 20 22 70 72 69 76 61 74 65 22 2e 20 5e 53 65 74   "private". ^Set
1fb60 74 69 6e 67 20 69 74 20 74 6f 20 22 73 68 61 72  ting it to "shar
1fb70 65 64 22 20 69 73 20 65 71 75 69 76 61 6c 65 6e  ed" is equivalen
1fb80 74 20 74 6f 20 73 65 74 74 69 6e 67 20 74 68 65  t to setting the
1fb90 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f  .**     SQLITE_O
1fba0 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20  PEN_SHAREDCACHE 
1fbb0 62 69 74 20 69 6e 20 74 68 65 20 66 6c 61 67 73  bit in the flags
1fbc0 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64   argument passed
1fbd0 20 74 6f 0a 2a 2a 20 20 20 20 20 73 71 6c 69 74   to.**     sqlit
1fbe0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 53  e3_open_v2(). ^S
1fbf0 65 74 74 69 6e 67 20 74 68 65 20 63 61 63 68 65  etting the cache
1fc00 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 22 70   parameter to "p
1fc10 72 69 76 61 74 65 22 20 69 73 20 0a 2a 2a 20 20  rivate" is .**  
1fc20 20 20 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f     equivalent to
1fc30 20 73 65 74 74 69 6e 67 20 74 68 65 20 53 51 4c   setting the SQL
1fc40 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45  ITE_OPEN_PRIVATE
1fc50 43 41 43 48 45 20 62 69 74 2e 0a 2a 2a 20 20 20  CACHE bit..**   
1fc60 20 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f 70    ^If sqlite3_op
1fc70 65 6e 5f 76 32 28 29 20 69 73 20 75 73 65 64 20  en_v2() is used 
1fc80 61 6e 64 20 74 68 65 20 22 63 61 63 68 65 22 20  and the "cache" 
1fc90 70 61 72 61 6d 65 74 65 72 20 69 73 20 70 72 65  parameter is pre
1fca0 73 65 6e 74 20 69 6e 0a 2a 2a 20 20 20 20 20 61  sent in.**     a
1fcb0 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 2c 20 69   URI filename, i
1fcc0 74 73 20 76 61 6c 75 65 20 6f 76 65 72 72 69 64  ts value overrid
1fcd0 65 73 20 61 6e 79 20 62 65 68 61 76 69 6f 75 72  es any behaviour
1fce0 20 72 65 71 75 65 73 74 65 64 20 62 79 20 73 65   requested by se
1fcf0 74 74 69 6e 67 0a 2a 2a 20 20 20 20 20 53 51 4c  tting.**     SQL
1fd00 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45  ITE_OPEN_PRIVATE
1fd10 43 41 43 48 45 20 6f 72 20 53 51 4c 49 54 45 5f  CACHE or SQLITE_
1fd20 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45  OPEN_SHAREDCACHE
1fd30 20 66 6c 61 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a   flag..** </ul>.
1fd40 2a 2a 0a 2a 2a 20 5e 53 70 65 63 69 66 79 69 6e  **.** ^Specifyin
1fd50 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 20 70 61 72  g an unknown par
1fd60 61 6d 65 74 65 72 20 69 6e 20 74 68 65 20 71 75  ameter in the qu
1fd70 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66  ery component of
1fd80 20 61 20 55 52 49 20 69 73 20 6e 6f 74 20 61 6e   a URI is not an
1fd90 0a 2a 2a 20 65 72 72 6f 72 2e 20 20 46 75 74 75  .** error.  Futu
1fda0 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  re versions of S
1fdb0 51 4c 69 74 65 20 6d 69 67 68 74 20 75 6e 64 65  QLite might unde
1fdc0 72 73 74 61 6e 64 20 61 64 64 69 74 69 6f 6e 61  rstand additiona
1fdd0 6c 20 71 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d  l query.** param
1fde0 65 74 65 72 73 2e 20 20 53 65 65 20 22 5b 71 75  eters.  See "[qu
1fdf0 65 72 79 20 70 61 72 61 6d 65 74 65 72 73 20 77  ery parameters w
1fe00 69 74 68 20 73 70 65 63 69 61 6c 20 6d 65 61 6e  ith special mean
1fe10 69 6e 67 20 74 6f 20 53 51 4c 69 74 65 5d 22 20  ing to SQLite]" 
1fe20 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61  for.** additiona
1fe30 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  l information..*
1fe40 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e  *.** [[URI filen
1fe50 61 6d 65 20 65 78 61 6d 70 6c 65 73 5d 5d 20 3c  ame examples]] <
1fe60 68 33 3e 55 52 49 20 66 69 6c 65 6e 61 6d 65 20  h3>URI filename 
1fe70 65 78 61 6d 70 6c 65 73 3c 2f 68 33 3e 0a 2a 2a  examples</h3>.**
1fe80 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65  .** <table borde
1fe90 72 3d 22 31 22 20 61 6c 69 67 6e 3d 63 65 6e 74  r="1" align=cent
1fea0 65 72 20 63 65 6c 6c 70 61 64 64 69 6e 67 3d 35  er cellpadding=5
1feb0 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 55 52  >.** <tr><th> UR
1fec0 49 20 66 69 6c 65 6e 61 6d 65 73 20 3c 74 68 3e  I filenames <th>
1fed0 20 52 65 73 75 6c 74 73 0a 2a 2a 20 3c 74 72 3e   Results.** <tr>
1fee0 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64  <td> file:data.d
1fef0 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20  b <td> .**      
1ff00 20 20 20 20 4f 70 65 6e 20 74 68 65 20 66 69 6c      Open the fil
1ff10 65 20 22 64 61 74 61 2e 64 62 22 20 69 6e 20 74  e "data.db" in t
1ff20 68 65 20 63 75 72 72 65 6e 74 20 64 69 72 65 63  he current direc
1ff30 74 6f 72 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64  tory..** <tr><td
1ff40 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65  > file:/home/fre
1ff50 64 2f 64 61 74 61 2e 64 62 3c 62 72 3e 0a 2a 2a  d/data.db<br>.**
1ff60 20 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f            file:/
1ff70 2f 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61  //home/fred/data
1ff80 2e 64 62 20 3c 62 72 3e 20 0a 2a 2a 20 20 20 20  .db <br> .**    
1ff90 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 6c 6f 63        file://loc
1ffa0 61 6c 68 6f 73 74 2f 68 6f 6d 65 2f 66 72 65 64  alhost/home/fred
1ffb0 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e 20 3c 74  /data.db <br> <t
1ffc0 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  d> .**          
1ffd0 4f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  Open the databas
1ffe0 65 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72  e file "/home/fr
1fff0 65 64 2f 64 61 74 61 2e 64 62 22 2e 0a 2a 2a 20  ed/data.db"..** 
20000 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 2f  <tr><td> file://
20010 64 61 72 6b 73 74 61 72 2f 68 6f 6d 65 2f 66 72  darkstar/home/fr
20020 65 64 2f 64 61 74 61 2e 64 62 20 3c 74 64 3e 20  ed/data.db <td> 
20030 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 41 6e 20  .**          An 
20040 65 72 72 6f 72 2e 20 22 64 61 72 6b 73 74 61 72  error. "darkstar
20050 22 20 69 73 20 6e 6f 74 20 61 20 72 65 63 6f 67  " is not a recog
20060 6e 69 7a 65 64 20 61 75 74 68 6f 72 69 74 79 2e  nized authority.
20070 0a 2a 2a 20 3c 74 72 3e 3c 74 64 20 73 74 79 6c  .** <tr><td styl
20080 65 3d 22 77 68 69 74 65 2d 73 70 61 63 65 3a 6e  e="white-space:n
20090 6f 77 72 61 70 22 3e 20 0a 2a 2a 20 20 20 20 20  owrap"> .**     
200a0 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 43 3a 2f       file:///C:/
200b0 44 6f 63 75 6d 65 6e 74 73 25 32 30 61 6e 64 25  Documents%20and%
200c0 32 30 53 65 74 74 69 6e 67 73 2f 66 72 65 64 2f  20Settings/fred/
200d0 44 65 73 6b 74 6f 70 2f 64 61 74 61 2e 64 62 0a  Desktop/data.db.
200e0 2a 2a 20 20 20 20 20 3c 74 64 3e 20 57 69 6e 64  **     <td> Wind
200f0 6f 77 73 20 6f 6e 6c 79 3a 20 4f 70 65 6e 20 74  ows only: Open t
20100 68 65 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62  he file "data.db
20110 22 20 6f 6e 20 66 72 65 64 27 73 20 64 65 73 6b  " on fred's desk
20120 74 6f 70 20 6f 6e 20 64 72 69 76 65 0a 2a 2a 20  top on drive.** 
20130 20 20 20 20 20 20 20 20 20 43 3a 2e 20 4e 6f 74           C:. Not
20140 65 20 74 68 61 74 20 74 68 65 20 25 32 30 20 65  e that the %20 e
20150 73 63 61 70 69 6e 67 20 69 6e 20 74 68 69 73 20  scaping in this 
20160 65 78 61 6d 70 6c 65 20 69 73 20 6e 6f 74 20 73  example is not s
20170 74 72 69 63 74 6c 79 20 0a 2a 2a 20 20 20 20 20  trictly .**     
20180 20 20 20 20 20 6e 65 63 65 73 73 61 72 79 20 2d       necessary -
20190 20 73 70 61 63 65 20 63 68 61 72 61 63 74 65 72   space character
201a0 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 6c 69  s can be used li
201b0 74 65 72 61 6c 6c 79 0a 2a 2a 20 20 20 20 20 20  terally.**      
201c0 20 20 20 20 69 6e 20 55 52 49 20 66 69 6c 65 6e      in URI filen
201d0 61 6d 65 73 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64  ames..** <tr><td
201e0 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d  > file:data.db?m
201f0 6f 64 65 3d 72 6f 26 63 61 63 68 65 3d 70 72 69  ode=ro&cache=pri
20200 76 61 74 65 20 3c 74 64 3e 20 0a 2a 2a 20 20 20  vate <td> .**   
20210 20 20 20 20 20 20 20 4f 70 65 6e 20 66 69 6c 65         Open file
20220 20 22 64 61 74 61 2e 64 62 22 20 69 6e 20 74 68   "data.db" in th
20230 65 20 63 75 72 72 65 6e 74 20 64 69 72 65 63 74  e current direct
20240 6f 72 79 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c  ory for read-onl
20250 79 20 61 63 63 65 73 73 2e 0a 2a 2a 20 20 20 20  y access..**    
20260 20 20 20 20 20 20 52 65 67 61 72 64 6c 65 73 73        Regardless
20270 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e   of whether or n
20280 6f 74 20 73 68 61 72 65 64 2d 63 61 63 68 65 20  ot shared-cache 
20290 6d 6f 64 65 20 69 73 20 65 6e 61 62 6c 65 64 20  mode is enabled 
202a0 62 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64  by.**          d
202b0 65 66 61 75 6c 74 2c 20 75 73 65 20 61 20 70 72  efault, use a pr
202c0 69 76 61 74 65 20 63 61 63 68 65 2e 0a 2a 2a 20  ivate cache..** 
202d0 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68  <tr><td> file:/h
202e0 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62  ome/fred/data.db
202f0 3f 76 66 73 3d 75 6e 69 78 2d 6e 6f 6c 6f 63 6b  ?vfs=unix-nolock
20300 20 3c 74 64 3e 0a 2a 2a 20 20 20 20 20 20 20 20   <td>.**        
20310 20 20 4f 70 65 6e 20 66 69 6c 65 20 22 2f 68 6f    Open file "/ho
20320 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 22  me/fred/data.db"
20330 2e 20 55 73 65 20 74 68 65 20 73 70 65 63 69 61  . Use the specia
20340 6c 20 56 46 53 20 22 75 6e 69 78 2d 6e 6f 6c 6f  l VFS "unix-nolo
20350 63 6b 22 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  ck"..** <tr><td>
20360 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f   file:data.db?mo
20370 64 65 3d 72 65 61 64 6f 6e 6c 79 20 3c 74 64 3e  de=readonly <td>
20380 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 41 6e   .**          An
20390 20 65 72 72 6f 72 2e 20 22 72 65 61 64 6f 6e 6c   error. "readonl
203a0 79 22 20 69 73 20 6e 6f 74 20 61 20 76 61 6c 69  y" is not a vali
203b0 64 20 6f 70 74 69 6f 6e 20 66 6f 72 20 74 68 65  d option for the
203c0 20 22 6d 6f 64 65 22 20 70 61 72 61 6d 65 74 65   "mode" paramete
203d0 72 2e 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a  r..** </table>.*
203e0 2a 0a 2a 2a 20 5e 55 52 49 20 68 65 78 61 64 65  *.** ^URI hexade
203f0 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71  cimal escape seq
20400 75 65 6e 63 65 73 20 28 25 48 48 29 20 61 72 65  uences (%HH) are
20410 20 73 75 70 70 6f 72 74 65 64 20 77 69 74 68 69   supported withi
20420 6e 20 74 68 65 20 70 61 74 68 20 61 6e 64 0a 2a  n the path and.*
20430 2a 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e  * query componen
20440 74 73 20 6f 66 20 61 20 55 52 49 2e 20 41 20 68  ts of a URI. A h
20450 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70  exadecimal escap
20460 65 20 73 65 71 75 65 6e 63 65 20 63 6f 6e 73 69  e sequence consi
20470 73 74 73 20 6f 66 20 61 0a 2a 2a 20 70 65 72 63  sts of a.** perc
20480 65 6e 74 20 73 69 67 6e 20 2d 20 22 25 22 20 2d  ent sign - "%" -
20490 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 65 78 61   followed by exa
204a0 63 74 6c 79 20 74 77 6f 20 68 65 78 61 64 65 63  ctly two hexadec
204b0 69 6d 61 6c 20 64 69 67 69 74 73 20 0a 2a 2a 20  imal digits .** 
204c0 73 70 65 63 69 66 79 69 6e 67 20 61 6e 20 6f 63  specifying an oc
204d0 74 65 74 20 76 61 6c 75 65 2e 20 5e 42 65 66 6f  tet value. ^Befo
204e0 72 65 20 74 68 65 20 70 61 74 68 20 6f 72 20 71  re the path or q
204f0 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20  uery components 
20500 6f 66 20 61 0a 2a 2a 20 55 52 49 20 66 69 6c 65  of a.** URI file
20510 6e 61 6d 65 20 61 72 65 20 69 6e 74 65 72 70 72  name are interpr
20520 65 74 65 64 2c 20 74 68 65 79 20 61 72 65 20 65  eted, they are e
20530 6e 63 6f 64 65 64 20 75 73 69 6e 67 20 55 54 46  ncoded using UTF
20540 2d 38 20 61 6e 64 20 61 6c 6c 20 0a 2a 2a 20 68  -8 and all .** h
20550 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70  exadecimal escap
20560 65 20 73 65 71 75 65 6e 63 65 73 20 72 65 70 6c  e sequences repl
20570 61 63 65 64 20 62 79 20 61 20 73 69 6e 67 6c 65  aced by a single
20580 20 62 79 74 65 20 63 6f 6e 74 61 69 6e 69 6e 67   byte containing
20590 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 73 70 6f   the.** correspo
205a0 6e 64 69 6e 67 20 6f 63 74 65 74 2e 20 49 66 20  nding octet. If 
205b0 74 68 69 73 20 70 72 6f 63 65 73 73 20 67 65 6e  this process gen
205c0 65 72 61 74 65 73 20 61 6e 20 69 6e 76 61 6c 69  erates an invali
205d0 64 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67  d UTF-8 encoding
205e0 2c 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 73  ,.** the results
205f0 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a   are undefined..
20600 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f  **.** <b>Note to
20610 20 57 69 6e 64 6f 77 73 20 75 73 65 72 73 3a 3c   Windows users:<
20620 2f 62 3e 20 20 54 68 65 20 65 6e 63 6f 64 69 6e  /b>  The encodin
20630 67 20 75 73 65 64 20 66 6f 72 20 74 68 65 20 66  g used for the f
20640 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74  ilename argument
20650 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f  .** of sqlite3_o
20660 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65  pen() and sqlite
20670 33 5f 6f 70 65 6e 5f 76 32 28 29 20 6d 75 73 74  3_open_v2() must
20680 20 62 65 20 55 54 46 2d 38 2c 20 6e 6f 74 20 77   be UTF-8, not w
20690 68 61 74 65 76 65 72 0a 2a 2a 20 63 6f 64 65 70  hatever.** codep
206a0 61 67 65 20 69 73 20 63 75 72 72 65 6e 74 6c 79  age is currently
206b0 20 64 65 66 69 6e 65 64 2e 20 20 46 69 6c 65 6e   defined.  Filen
206c0 61 6d 65 73 20 63 6f 6e 74 61 69 6e 69 6e 67 20  ames containing 
206d0 69 6e 74 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a  international.**
206e0 20 63 68 61 72 61 63 74 65 72 73 20 6d 75 73 74   characters must
206f0 20 62 65 20 63 6f 6e 76 65 72 74 65 64 20 74 6f   be converted to
20700 20 55 54 46 2d 38 20 70 72 69 6f 72 20 74 6f 20   UTF-8 prior to 
20710 70 61 73 73 69 6e 67 20 74 68 65 6d 20 69 6e 74  passing them int
20720 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65  o.** sqlite3_ope
20730 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f  n() or sqlite3_o
20740 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20  pen_v2()..**.** 
20750 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f  <b>Note to Windo
20760 77 73 20 52 75 6e 74 69 6d 65 20 75 73 65 72 73  ws Runtime users
20770 3a 3c 2f 62 3e 20 20 54 68 65 20 74 65 6d 70 6f  :</b>  The tempo
20780 72 61 72 79 20 64 69 72 65 63 74 6f 72 79 20 6d  rary directory m
20790 75 73 74 20 62 65 20 73 65 74 0a 2a 2a 20 70 72  ust be set.** pr
207a0 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 20 73  ior to calling s
207b0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72  qlite3_open() or
207c0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
207d0 28 29 2e 20 20 4f 74 68 65 72 77 69 73 65 2c 20  ().  Otherwise, 
207e0 76 61 72 69 6f 75 73 0a 2a 2a 20 66 65 61 74 75  various.** featu
207f0 72 65 73 20 74 68 61 74 20 72 65 71 75 69 72 65  res that require
20800 20 74 68 65 20 75 73 65 20 6f 66 20 74 65 6d 70   the use of temp
20810 6f 72 61 72 79 20 66 69 6c 65 73 20 6d 61 79 20  orary files may 
20820 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  fail..**.** See 
20830 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 74  also: [sqlite3_t
20840 65 6d 70 5f 64 69 72 65 63 74 6f 72 79 5d 0a 2a  emp_directory].*
20850 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70  /.int sqlite3_op
20860 65 6e 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  en(.  const char
20870 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a   *filename,   /*
20880 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61   Database filena
20890 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20  me (UTF-8) */.  
208a0 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20  sqlite3 **ppDb  
208b0 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20          /* OUT: 
208c0 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65  SQLite db handle
208d0 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74   */.);.int sqlit
208e0 65 33 5f 6f 70 65 6e 31 36 28 0a 20 20 63 6f 6e  e3_open16(.  con
208f0 73 74 20 76 6f 69 64 20 2a 66 69 6c 65 6e 61 6d  st void *filenam
20900 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  e,   /* Database
20910 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 31   filename (UTF-1
20920 36 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20  6) */.  sqlite3 
20930 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20 20 20  **ppDb          
20940 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64  /* OUT: SQLite d
20950 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69  b handle */.);.i
20960 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  nt sqlite3_open_
20970 76 32 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  v2(.  const char
20980 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a   *filename,   /*
20990 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61   Database filena
209a0 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20  me (UTF-8) */.  
209b0 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 2c 20  sqlite3 **ppDb, 
209c0 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20          /* OUT: 
209d0 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65  SQLite db handle
209e0 20 2a 2f 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c   */.  int flags,
209f0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
20a00 20 46 6c 61 67 73 20 2a 2f 0a 20 20 63 6f 6e 73   Flags */.  cons
20a10 74 20 63 68 61 72 20 2a 7a 56 66 73 20 20 20 20  t char *zVfs    
20a20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 56      /* Name of V
20a30 46 53 20 6d 6f 64 75 6c 65 20 74 6f 20 75 73 65  FS module to use
20a40 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.);../*.** CA
20a50 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 56  PI3REF: Obtain V
20a60 61 6c 75 65 73 20 46 6f 72 20 55 52 49 20 50 61  alues For URI Pa
20a70 72 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 54  rameters.**.** T
20a80 68 65 73 65 20 61 72 65 20 75 74 69 6c 69 74 79  hese are utility
20a90 20 72 6f 75 74 69 6e 65 73 2c 20 75 73 65 66 75   routines, usefu
20aa0 6c 20 74 6f 20 56 46 53 20 69 6d 70 6c 65 6d 65  l to VFS impleme
20ab0 6e 74 61 74 69 6f 6e 73 2c 20 74 68 61 74 20 63  ntations, that c
20ac0 68 65 63 6b 0a 2a 2a 20 74 6f 20 73 65 65 20 69  heck.** to see i
20ad0 66 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c  f a database fil
20ae0 65 20 77 61 73 20 61 20 55 52 49 20 74 68 61 74  e was a URI that
20af0 20 63 6f 6e 74 61 69 6e 65 64 20 61 20 73 70 65   contained a spe
20b00 63 69 66 69 63 20 71 75 65 72 79 20 0a 2a 2a 20  cific query .** 
20b10 70 61 72 61 6d 65 74 65 72 2c 20 61 6e 64 20 69  parameter, and i
20b20 66 20 73 6f 20 6f 62 74 61 69 6e 73 20 74 68 65  f so obtains the
20b30 20 76 61 6c 75 65 20 6f 66 20 74 68 61 74 20 71   value of that q
20b40 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 2e 0a  uery parameter..
20b50 2a 2a 0a 2a 2a 20 49 66 20 46 20 69 73 20 74 68  **.** If F is th
20b60 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e  e database filen
20b70 61 6d 65 20 70 6f 69 6e 74 65 72 20 70 61 73 73  ame pointer pass
20b80 65 64 20 69 6e 74 6f 20 74 68 65 20 78 4f 70 65  ed into the xOpe
20b90 6e 28 29 20 6d 65 74 68 6f 64 20 6f 66 20 0a 2a  n() method of .*
20ba0 2a 20 61 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e  * a VFS implemen
20bb0 74 61 74 69 6f 6e 20 77 68 65 6e 20 74 68 65 20  tation when the 
20bc0 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20  flags parameter 
20bd0 74 6f 20 78 4f 70 65 6e 28 29 20 68 61 73 20 6f  to xOpen() has o
20be0 6e 65 20 6f 72 20 0a 2a 2a 20 6d 6f 72 65 20 6f  ne or .** more o
20bf0 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  f the [SQLITE_OP
20c00 45 4e 5f 55 52 49 5d 20 6f 72 20 5b 53 51 4c 49  EN_URI] or [SQLI
20c10 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d  TE_OPEN_MAIN_DB]
20c20 20 62 69 74 73 20 73 65 74 20 61 6e 64 0a 2a 2a   bits set and.**
20c30 20 50 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f   P is the name o
20c40 66 20 74 68 65 20 71 75 65 72 79 20 70 61 72 61  f the query para
20c50 6d 65 74 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 73  meter, then.** s
20c60 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d  qlite3_uri_param
20c70 65 74 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e  eter(F,P) return
20c80 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74  s the value of t
20c90 68 65 20 50 0a 2a 2a 20 70 61 72 61 6d 65 74 65  he P.** paramete
20ca0 72 20 69 66 20 69 74 20 65 78 69 73 74 73 20 6f  r if it exists o
20cb0 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  r a NULL pointer
20cc0 20 69 66 20 50 20 64 6f 65 73 20 6e 6f 74 20 61   if P does not a
20cd0 70 70 65 61 72 20 61 73 20 61 20 0a 2a 2a 20 71  ppear as a .** q
20ce0 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 6f  uery parameter o
20cf0 6e 20 46 2e 20 20 49 66 20 50 20 69 73 20 61 20  n F.  If P is a 
20d00 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 20  query parameter 
20d10 6f 66 20 46 0a 2a 2a 20 68 61 73 20 6e 6f 20 65  of F.** has no e
20d20 78 70 6c 69 63 69 74 20 76 61 6c 75 65 2c 20 74  xplicit value, t
20d30 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  hen sqlite3_uri_
20d40 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72  parameter(F,P) r
20d50 65 74 75 72 6e 73 0a 2a 2a 20 61 20 70 6f 69 6e  eturns.** a poin
20d60 74 65 72 20 74 6f 20 61 6e 20 65 6d 70 74 79 20  ter to an empty 
20d70 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68  string..**.** Th
20d80 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f  e sqlite3_uri_bo
20d90 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75  olean(F,P,B) rou
20da0 74 69 6e 65 20 61 73 73 75 6d 65 73 20 74 68 61  tine assumes tha
20db0 74 20 50 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e  t P is a boolean
20dc0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 61 6e  .** parameter an
20dd0 64 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 28  d returns true (
20de0 31 29 20 6f 72 20 66 61 6c 73 65 20 28 30 29 20  1) or false (0) 
20df0 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 74 68 65  according to the
20e00 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 50 2e 20   value.** of P. 
20e10 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69   The sqlite3_uri
20e20 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20  _boolean(F,P,B) 
20e30 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
20e40 74 72 75 65 20 28 31 29 20 69 66 20 74 68 65 0a  true (1) if the.
20e50 2a 2a 20 76 61 6c 75 65 20 6f 66 20 71 75 65 72  ** value of quer
20e60 79 20 70 61 72 61 6d 65 74 65 72 20 50 20 69 73  y parameter P is
20e70 20 6f 6e 65 20 6f 66 20 22 79 65 73 22 2c 20 22   one of "yes", "
20e80 74 72 75 65 22 2c 20 6f 72 20 22 6f 6e 22 20 69  true", or "on" i
20e90 6e 20 61 6e 79 0a 2a 2a 20 63 61 73 65 20 6f 72  n any.** case or
20ea0 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 62 65   if the value be
20eb0 67 69 6e 73 20 77 69 74 68 20 61 20 6e 6f 6e 2d  gins with a non-
20ec0 7a 65 72 6f 20 6e 75 6d 62 65 72 2e 20 20 54 68  zero number.  Th
20ed0 65 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72  e .** sqlite3_ur
20ee0 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29  i_boolean(F,P,B)
20ef0 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
20f00 73 20 66 61 6c 73 65 20 28 30 29 20 69 66 20 74  s false (0) if t
20f10 68 65 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 71  he value of.** q
20f20 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 50  uery parameter P
20f30 20 69 73 20 6f 6e 65 20 6f 66 20 22 6e 6f 22 2c   is one of "no",
20f40 20 22 66 61 6c 73 65 22 2c 20 6f 72 20 22 6f 66   "false", or "of
20f50 66 22 20 69 6e 20 61 6e 79 20 63 61 73 65 20 6f  f" in any case o
20f60 72 0a 2a 2a 20 69 66 20 74 68 65 20 76 61 6c 75  r.** if the valu
20f70 65 20 62 65 67 69 6e 73 20 77 69 74 68 20 61 20  e begins with a 
20f80 6e 75 6d 65 72 69 63 20 7a 65 72 6f 2e 20 20 49  numeric zero.  I
20f90 66 20 50 20 69 73 20 6e 6f 74 20 61 20 71 75 65  f P is not a que
20fa0 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  ry.** parameter 
20fb0 6f 6e 20 46 20 6f 72 20 69 66 20 74 68 65 20 76  on F or if the v
20fc0 61 6c 75 65 20 6f 66 20 50 20 69 73 20 64 6f 65  alue of P is doe
20fd0 73 20 6e 6f 74 20 6d 61 74 63 68 20 61 6e 79 20  s not match any 
20fe0 6f 66 20 74 68 65 0a 2a 2a 20 61 62 6f 76 65 2c  of the.** above,
20ff0 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72   then sqlite3_ur
21000 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29  i_boolean(F,P,B)
21010 20 72 65 74 75 72 6e 73 20 28 42 21 3d 30 29 2e   returns (B!=0).
21020 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
21030 65 33 5f 75 72 69 5f 69 6e 74 36 34 28 46 2c 50  e3_uri_int64(F,P
21040 2c 44 29 20 72 6f 75 74 69 6e 65 20 63 6f 6e 76  ,D) routine conv
21050 65 72 74 73 20 74 68 65 20 76 61 6c 75 65 20 6f  erts the value o
21060 66 20 50 20 69 6e 74 6f 20 61 0a 2a 2a 20 36 34  f P into a.** 64
21070 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65  -bit signed inte
21080 67 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20  ger and returns 
21090 74 68 61 74 20 69 6e 74 65 67 65 72 2c 20 6f 72  that integer, or
210a0 20 44 20 69 66 20 50 20 64 6f 65 73 20 6e 6f 74   D if P does not
210b0 0a 2a 2a 20 65 78 69 73 74 2e 20 20 49 66 20 74  .** exist.  If t
210c0 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69 73  he value of P is
210d0 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72   something other
210e0 20 74 68 61 6e 20 61 6e 20 69 6e 74 65 67 65 72   than an integer
210f0 2c 20 74 68 65 6e 0a 2a 2a 20 7a 65 72 6f 20 69  , then.** zero i
21100 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 0a  s returned..** .
21110 2a 2a 20 49 66 20 46 20 69 73 20 61 20 4e 55 4c  ** If F is a NUL
21120 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20  L pointer, then 
21130 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61  sqlite3_uri_para
21140 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74 75 72  meter(F,P) retur
21150 6e 73 20 4e 55 4c 4c 20 61 6e 64 0a 2a 2a 20 73  ns NULL and.** s
21160 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65  qlite3_uri_boole
21170 61 6e 28 46 2c 50 2c 42 29 20 72 65 74 75 72 6e  an(F,P,B) return
21180 73 20 42 2e 20 20 49 66 20 46 20 69 73 20 6e 6f  s B.  If F is no
21190 74 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  t a NULL pointer
211a0 20 61 6e 64 0a 2a 2a 20 69 73 20 6e 6f 74 20 61   and.** is not a
211b0 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 70   database file p
211c0 61 74 68 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20  athname pointer 
211d0 74 68 61 74 20 53 51 4c 69 74 65 20 70 61 73 73  that SQLite pass
211e0 65 64 20 69 6e 74 6f 20 74 68 65 20 78 4f 70 65  ed into the xOpe
211f0 6e 0a 2a 2a 20 56 46 53 20 6d 65 74 68 6f 64 2c  n.** VFS method,
21200 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
21210 6f 72 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69  or of this routi
21220 6e 65 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20  ne is undefined 
21230 61 6e 64 20 70 72 6f 62 61 62 6c 79 0a 2a 2a 20  and probably.** 
21240 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2f 0a  undesirable..*/.
21250 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
21260 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65  te3_uri_paramete
21270 72 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46  r(const char *zF
21280 69 6c 65 6e 61 6d 65 2c 20 63 6f 6e 73 74 20 63  ilename, const c
21290 68 61 72 20 2a 7a 50 61 72 61 6d 29 3b 0a 69 6e  har *zParam);.in
212a0 74 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f  t sqlite3_uri_bo
212b0 6f 6c 65 61 6e 28 63 6f 6e 73 74 20 63 68 61 72  olean(const char
212c0 20 2a 7a 46 69 6c 65 2c 20 63 6f 6e 73 74 20 63   *zFile, const c
212d0 68 61 72 20 2a 7a 50 61 72 61 6d 2c 20 69 6e 74  har *zParam, int
212e0 20 62 44 65 66 61 75 6c 74 29 3b 0a 73 71 6c 69   bDefault);.sqli
212f0 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  te3_int64 sqlite
21300 33 5f 75 72 69 5f 69 6e 74 36 34 28 63 6f 6e 73  3_uri_int64(cons
21310 74 20 63 68 61 72 2a 2c 20 63 6f 6e 73 74 20 63  t char*, const c
21320 68 61 72 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  har*, sqlite3_in
21330 74 36 34 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41  t64);.../*.** CA
21340 50 49 33 52 45 46 3a 20 45 72 72 6f 72 20 43 6f  PI3REF: Error Co
21350 64 65 73 20 41 6e 64 20 4d 65 73 73 61 67 65 73  des And Messages
21360 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
21370 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20 69 6e  te3_errcode() in
21380 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
21390 74 68 65 20 6e 75 6d 65 72 69 63 20 5b 72 65 73  the numeric [res
213a0 75 6c 74 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20  ult code] or.** 
213b0 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  [extended result
213c0 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 6d   code] for the m
213d0 6f 73 74 20 72 65 63 65 6e 74 20 66 61 69 6c 65  ost recent faile
213e0 64 20 73 71 6c 69 74 65 33 5f 2a 20 41 50 49 20  d sqlite3_* API 
213f0 63 61 6c 6c 0a 2a 2a 20 61 73 73 6f 63 69 61 74  call.** associat
21400 65 64 20 77 69 74 68 20 61 20 5b 64 61 74 61 62  ed with a [datab
21410 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e  ase connection].
21420 20 49 66 20 61 20 70 72 69 6f 72 20 41 50 49 20   If a prior API 
21430 63 61 6c 6c 20 66 61 69 6c 65 64 0a 2a 2a 20 62  call failed.** b
21440 75 74 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  ut the most rece
21450 6e 74 20 41 50 49 20 63 61 6c 6c 20 73 75 63 63  nt API call succ
21460 65 65 64 65 64 2c 20 74 68 65 20 72 65 74 75 72  eeded, the retur
21470 6e 20 76 61 6c 75 65 20 66 72 6f 6d 0a 2a 2a 20  n value from.** 
21480 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
21490 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20  ) is undefined. 
214a0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78   ^The sqlite3_ex
214b0 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29  tended_errcode()
214c0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73  .** interface is
214d0 20 74 68 65 20 73 61 6d 65 20 65 78 63 65 70 74   the same except
214e0 20 74 68 61 74 20 69 74 20 61 6c 77 61 79 73 20   that it always 
214f0 72 65 74 75 72 6e 73 20 74 68 65 20 0a 2a 2a 20  returns the .** 
21500 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  [extended result
21510 20 63 6f 64 65 5d 20 65 76 65 6e 20 77 68 65 6e   code] even when
21520 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
21530 20 63 6f 64 65 73 20 61 72 65 0a 2a 2a 20 64 69   codes are.** di
21540 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  sabled..**.** ^T
21550 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  he sqlite3_errms
21560 67 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  g() and sqlite3_
21570 65 72 72 6d 73 67 31 36 28 29 20 72 65 74 75 72  errmsg16() retur
21580 6e 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61  n English-langua
21590 67 65 0a 2a 2a 20 74 65 78 74 20 74 68 61 74 20  ge.** text that 
215a0 64 65 73 63 72 69 62 65 73 20 74 68 65 20 65 72  describes the er
215b0 72 6f 72 2c 20 61 73 20 65 69 74 68 65 72 20 55  ror, as either U
215c0 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 72  TF-8 or UTF-16 r
215d0 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20  espectively..** 
215e0 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64  ^(Memory to hold
215f0 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61   the error messa
21600 67 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e  ge string is man
21610 61 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 2e  aged internally.
21620 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
21630 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65  ion does not nee
21640 64 20 74 6f 20 77 6f 72 72 79 20 61 62 6f 75 74  d to worry about
21650 20 66 72 65 65 69 6e 67 20 74 68 65 20 72 65 73   freeing the res
21660 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c  ult..** However,
21670 20 74 68 65 20 65 72 72 6f 72 20 73 74 72 69 6e   the error strin
21680 67 20 6d 69 67 68 74 20 62 65 20 6f 76 65 72 77  g might be overw
21690 72 69 74 74 65 6e 20 6f 72 20 64 65 61 6c 6c 6f  ritten or deallo
216a0 63 61 74 65 64 20 62 79 0a 2a 2a 20 73 75 62 73  cated by.** subs
216b0 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20  equent calls to 
216c0 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74  other SQLite int
216d0 65 72 66 61 63 65 20 66 75 6e 63 74 69 6f 6e 73  erface functions
216e0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74  .)^.**.** When t
216f0 68 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74  he serialized [t
21700 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 69  hreading mode] i
21710 73 20 69 6e 20 75 73 65 2c 20 69 74 20 6d 69 67  s in use, it mig
21720 68 74 20 62 65 20 74 68 65 0a 2a 2a 20 63 61 73  ht be the.** cas
21730 65 20 74 68 61 74 20 61 20 73 65 63 6f 6e 64 20  e that a second 
21740 65 72 72 6f 72 20 6f 63 63 75 72 73 20 6f 6e 20  error occurs on 
21750 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61  a separate threa
21760 64 20 69 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20  d in between.** 
21770 74 68 65 20 74 69 6d 65 20 6f 66 20 74 68 65 20  the time of the 
21780 66 69 72 73 74 20 65 72 72 6f 72 20 61 6e 64 20  first error and 
21790 74 68 65 20 63 61 6c 6c 20 74 6f 20 74 68 65 73  the call to thes
217a0 65 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a  e interfaces..**
217b0 20 57 68 65 6e 20 74 68 61 74 20 68 61 70 70 65   When that happe
217c0 6e 73 2c 20 74 68 65 20 73 65 63 6f 6e 64 20 65  ns, the second e
217d0 72 72 6f 72 20 77 69 6c 6c 20 62 65 20 72 65 70  rror will be rep
217e0 6f 72 74 65 64 20 73 69 6e 63 65 20 74 68 65 73  orted since thes
217f0 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  e.** interfaces 
21800 61 6c 77 61 79 73 20 72 65 70 6f 72 74 20 74 68  always report th
21810 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 72 65  e most recent re
21820 73 75 6c 74 2e 20 20 54 6f 20 61 76 6f 69 64 0a  sult.  To avoid.
21830 2a 2a 20 74 68 69 73 2c 20 65 61 63 68 20 74 68  ** this, each th
21840 72 65 61 64 20 63 61 6e 20 6f 62 74 61 69 6e 20  read can obtain 
21850 65 78 63 6c 75 73 69 76 65 20 75 73 65 20 6f 66  exclusive use of
21860 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
21870 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20  onnection] D.** 
21880 62 79 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c  by invoking [sql
21890 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72  ite3_mutex_enter
218a0 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75  ]([sqlite3_db_mu
218b0 74 65 78 5d 28 44 29 29 20 62 65 66 6f 72 65 20  tex](D)) before 
218c0 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20 74 6f 20  beginning.** to 
218d0 75 73 65 20 44 20 61 6e 64 20 69 6e 76 6f 6b 69  use D and invoki
218e0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  ng [sqlite3_mute
218f0 78 5f 6c 65 61 76 65 5d 28 5b 73 71 6c 69 74 65  x_leave]([sqlite
21900 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20  3_db_mutex](D)) 
21910 61 66 74 65 72 0a 2a 2a 20 61 6c 6c 20 63 61 6c  after.** all cal
21920 6c 73 20 74 6f 20 74 68 65 20 69 6e 74 65 72 66  ls to the interf
21930 61 63 65 73 20 6c 69 73 74 65 64 20 68 65 72 65  aces listed here
21940 20 61 72 65 20 63 6f 6d 70 6c 65 74 65 64 2e 0a   are completed..
21950 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 69 6e 74 65  **.** If an inte
21960 72 66 61 63 65 20 66 61 69 6c 73 20 77 69 74 68  rface fails with
21970 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2c 20   SQLITE_MISUSE, 
21980 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 69  that means the i
21990 6e 74 65 72 66 61 63 65 0a 2a 2a 20 77 61 73 20  nterface.** was 
219a0 69 6e 76 6f 6b 65 64 20 69 6e 63 6f 72 72 65 63  invoked incorrec
219b0 74 6c 79 20 62 79 20 74 68 65 20 61 70 70 6c 69  tly by the appli
219c0 63 61 74 69 6f 6e 2e 20 20 49 6e 20 74 68 61 74  cation.  In that
219d0 20 63 61 73 65 2c 20 74 68 65 0a 2a 2a 20 65 72   case, the.** er
219e0 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 6d 65 73  ror code and mes
219f0 73 61 67 65 20 6d 61 79 20 6f 72 20 6d 61 79 20  sage may or may 
21a00 6e 6f 74 20 62 65 20 73 65 74 2e 0a 2a 2f 0a 69  not be set..*/.i
21a10 6e 74 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  nt sqlite3_errco
21a20 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b  de(sqlite3 *db);
21a30 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74  .int sqlite3_ext
21a40 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 73 71  ended_errcode(sq
21a50 6c 69 74 65 33 20 2a 64 62 29 3b 0a 63 6f 6e 73  lite3 *db);.cons
21a60 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
21a70 65 72 72 6d 73 67 28 73 71 6c 69 74 65 33 2a 29  errmsg(sqlite3*)
21a80 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
21a90 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 73  lite3_errmsg16(s
21aa0 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
21ab0 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20 53   CAPI3REF: SQL S
21ac0 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a  tatement Object.
21ad0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72  ** KEYWORDS: {pr
21ae0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
21af0 7d 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74  } {prepared stat
21b00 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e  ements}.**.** An
21b10 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69   instance of thi
21b20 73 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65  s object represe
21b30 6e 74 73 20 61 20 73 69 6e 67 6c 65 20 53 51 4c  nts a single SQL
21b40 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 54   statement..** T
21b50 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 76 61  his object is va
21b60 72 69 6f 75 73 6c 79 20 6b 6e 6f 77 6e 20 61 73  riously known as
21b70 20 61 20 22 70 72 65 70 61 72 65 64 20 73 74 61   a "prepared sta
21b80 74 65 6d 65 6e 74 22 20 6f 72 20 61 0a 2a 2a 20  tement" or a.** 
21b90 22 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20 73 74  "compiled SQL st
21ba0 61 74 65 6d 65 6e 74 22 20 6f 72 20 73 69 6d 70  atement" or simp
21bb0 6c 79 20 61 73 20 61 20 22 73 74 61 74 65 6d 65  ly as a "stateme
21bc0 6e 74 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c  nt"..**.** The l
21bd0 69 66 65 20 6f 66 20 61 20 73 74 61 74 65 6d 65  ife of a stateme
21be0 6e 74 20 6f 62 6a 65 63 74 20 67 6f 65 73 20 73  nt object goes s
21bf0 6f 6d 65 74 68 69 6e 67 20 6c 69 6b 65 20 74 68  omething like th
21c00 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a  is:.**.** <ol>.*
21c10 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65 20 74 68  * <li> Create th
21c20 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b  e object using [
21c30 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
21c40 76 32 28 29 5d 20 6f 72 20 61 20 72 65 6c 61 74  v2()] or a relat
21c50 65 64 0a 2a 2a 20 20 20 20 20 20 66 75 6e 63 74  ed.**      funct
21c60 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e  ion..** <li> Bin
21c70 64 20 76 61 6c 75 65 73 20 74 6f 20 5b 68 6f 73  d values to [hos
21c80 74 20 70 61 72 61 6d 65 74 65 72 73 5d 20 75 73  t parameters] us
21c90 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ing the sqlite3_
21ca0 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20 20 20  bind_*().**     
21cb0 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20   interfaces..** 
21cc0 3c 6c 69 3e 20 52 75 6e 20 74 68 65 20 53 51 4c  <li> Run the SQL
21cd0 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c   by calling [sql
21ce0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 6e 65  ite3_step()] one
21cf0 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a   or more times..
21d00 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 74 20 74 68  ** <li> Reset th
21d10 65 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e  e statement usin
21d20 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  g [sqlite3_reset
21d30 28 29 5d 20 74 68 65 6e 20 67 6f 20 62 61 63 6b  ()] then go back
21d40 0a 2a 2a 20 20 20 20 20 20 74 6f 20 73 74 65 70  .**      to step
21d50 20 32 2e 20 20 44 6f 20 74 68 69 73 20 7a 65 72   2.  Do this zer
21d60 6f 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e  o or more times.
21d70 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73 74 72 6f 79  .** <li> Destroy
21d80 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e   the object usin
21d90 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  g [sqlite3_final
21da0 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e  ize()]..** </ol>
21db0 0a 2a 2a 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20  .**.** Refer to 
21dc0 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 6f 6e  documentation on
21dd0 20 69 6e 64 69 76 69 64 75 61 6c 20 6d 65 74 68   individual meth
21de0 6f 64 73 20 61 62 6f 76 65 20 66 6f 72 20 61 64  ods above for ad
21df0 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f  ditional.** info
21e00 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65  rmation..*/.type
21e10 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
21e20 65 33 5f 73 74 6d 74 20 73 71 6c 69 74 65 33 5f  e3_stmt sqlite3_
21e30 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  stmt;../*.** CAP
21e40 49 33 52 45 46 3a 20 52 75 6e 2d 74 69 6d 65 20  I3REF: Run-time 
21e50 4c 69 6d 69 74 73 0a 2a 2a 0a 2a 2a 20 5e 28 54  Limits.**.** ^(T
21e60 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c  his interface al
21e70 6c 6f 77 73 20 74 68 65 20 73 69 7a 65 20 6f 66  lows the size of
21e80 20 76 61 72 69 6f 75 73 20 63 6f 6e 73 74 72 75   various constru
21e90 63 74 73 20 74 6f 20 62 65 20 6c 69 6d 69 74 65  cts to be limite
21ea0 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e 6e 65 63  d.** on a connec
21eb0 74 69 6f 6e 20 62 79 20 63 6f 6e 6e 65 63 74 69  tion by connecti
21ec0 6f 6e 20 62 61 73 69 73 2e 20 20 54 68 65 20 66  on basis.  The f
21ed0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69  irst parameter i
21ee0 73 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61  s the.** [databa
21ef0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77  se connection] w
21f00 68 6f 73 65 20 6c 69 6d 69 74 20 69 73 20 74 6f  hose limit is to
21f10 20 62 65 20 73 65 74 20 6f 72 20 71 75 65 72 69   be set or queri
21f20 65 64 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f  ed.  The.** seco
21f30 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
21f40 6f 6e 65 20 6f 66 20 74 68 65 20 5b 6c 69 6d 69  one of the [limi
21f50 74 20 63 61 74 65 67 6f 72 69 65 73 5d 20 74 68  t categories] th
21f60 61 74 20 64 65 66 69 6e 65 20 61 0a 2a 2a 20 63  at define a.** c
21f70 6c 61 73 73 20 6f 66 20 63 6f 6e 73 74 72 75 63  lass of construc
21f80 74 73 20 74 6f 20 62 65 20 73 69 7a 65 20 6c 69  ts to be size li
21f90 6d 69 74 65 64 2e 20 20 54 68 65 20 74 68 69 72  mited.  The thir
21fa0 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  d parameter is t
21fb0 68 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d 69 74 20  he.** new limit 
21fc0 66 6f 72 20 74 68 61 74 20 63 6f 6e 73 74 72 75  for that constru
21fd0 63 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ct.)^.**.** ^If 
21fe0 74 68 65 20 6e 65 77 20 6c 69 6d 69 74 20 69 73  the new limit is
21ff0 20 61 20 6e 65 67 61 74 69 76 65 20 6e 75 6d 62   a negative numb
22000 65 72 2c 20 74 68 65 20 6c 69 6d 69 74 20 69 73  er, the limit is
22010 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 5e   unchanged..** ^
22020 28 46 6f 72 20 65 61 63 68 20 6c 69 6d 69 74 20  (For each limit 
22030 63 61 74 65 67 6f 72 79 20 53 51 4c 49 54 45 5f  category SQLITE_
22040 4c 49 4d 49 54 5f 3c 69 3e 4e 41 4d 45 3c 2f 69  LIMIT_<i>NAME</i
22050 3e 20 74 68 65 72 65 20 69 73 20 61 20 0a 2a 2a  > there is a .**
22060 20 5b 6c 69 6d 69 74 73 20 7c 20 68 61 72 64 20   [limits | hard 
22070 75 70 70 65 72 20 62 6f 75 6e 64 5d 0a 2a 2a 20  upper bound].** 
22080 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74  set at compile-t
22090 69 6d 65 20 62 79 20 61 20 43 20 70 72 65 70 72  ime by a C prepr
220a0 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 63 61  ocessor macro ca
220b0 6c 6c 65 64 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20  lled.** [limits 
220c0 7c 20 53 51 4c 49 54 45 5f 4d 41 58 5f 3c 69 3e  | SQLITE_MAX_<i>
220d0 4e 41 4d 45 3c 2f 69 3e 5d 2e 0a 2a 2a 20 28 54  NAME</i>]..** (T
220e0 68 65 20 22 5f 4c 49 4d 49 54 5f 22 20 69 6e 20  he "_LIMIT_" in 
220f0 74 68 65 20 6e 61 6d 65 20 69 73 20 63 68 61 6e  the name is chan
22100 67 65 64 20 74 6f 20 22 5f 4d 41 58 5f 22 2e 29  ged to "_MAX_".)
22110 29 5e 0a 2a 2a 20 5e 41 74 74 65 6d 70 74 73 20  )^.** ^Attempts 
22120 74 6f 20 69 6e 63 72 65 61 73 65 20 61 20 6c 69  to increase a li
22130 6d 69 74 20 61 62 6f 76 65 20 69 74 73 20 68 61  mit above its ha
22140 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 20 61  rd upper bound a
22150 72 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c 79 20 74  re.** silently t
22160 72 75 6e 63 61 74 65 64 20 74 6f 20 74 68 65 20  runcated to the 
22170 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64  hard upper bound
22180 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 61 72 64 6c  ..**.** ^Regardl
22190 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f  ess of whether o
221a0 72 20 6e 6f 74 20 74 68 65 20 6c 69 6d 69 74 20  r not the limit 
221b0 77 61 73 20 63 68 61 6e 67 65 64 2c 20 74 68 65  was changed, the
221c0 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 69   .** [sqlite3_li
221d0 6d 69 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65  mit()] interface
221e0 20 72 65 74 75 72 6e 73 20 74 68 65 20 70 72 69   returns the pri
221f0 6f 72 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  or value of the 
22200 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 48 65 6e 63 65  limit..** ^Hence
22210 2c 20 74 6f 20 66 69 6e 64 20 74 68 65 20 63 75  , to find the cu
22220 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 20 61  rrent value of a
22230 20 6c 69 6d 69 74 20 77 69 74 68 6f 75 74 20 63   limit without c
22240 68 61 6e 67 69 6e 67 20 69 74 2c 0a 2a 2a 20 73  hanging it,.** s
22250 69 6d 70 6c 79 20 69 6e 76 6f 6b 65 20 74 68 69  imply invoke thi
22260 73 20 69 6e 74 65 72 66 61 63 65 20 77 69 74 68  s interface with
22270 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   the third param
22280 65 74 65 72 20 73 65 74 20 74 6f 20 2d 31 2e 0a  eter set to -1..
22290 2a 2a 0a 2a 2a 20 52 75 6e 2d 74 69 6d 65 20 6c  **.** Run-time l
222a0 69 6d 69 74 73 20 61 72 65 20 69 6e 74 65 6e 64  imits are intend
222b0 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20 61 70  ed for use in ap
222c0 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20  plications that 
222d0 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f 74 68 20 74  manage.** both t
222e0 68 65 69 72 20 6f 77 6e 20 69 6e 74 65 72 6e 61  heir own interna
222f0 6c 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 61  l database and a
22300 6c 73 6f 20 64 61 74 61 62 61 73 65 73 20 74 68  lso databases th
22310 61 74 20 61 72 65 20 63 6f 6e 74 72 6f 6c 6c 65  at are controlle
22320 64 0a 2a 2a 20 62 79 20 75 6e 74 72 75 73 74 65  d.** by untruste
22330 64 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63  d external sourc
22340 65 73 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20  es.  An example 
22350 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 69 67 68  application migh
22360 74 20 62 65 20 61 0a 2a 2a 20 77 65 62 20 62 72  t be a.** web br
22370 6f 77 73 65 72 20 74 68 61 74 20 68 61 73 20 69  owser that has i
22380 74 73 20 6f 77 6e 20 64 61 74 61 62 61 73 65 73  ts own databases
22390 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 68 69 73   for storing his
223a0 74 6f 72 79 20 61 6e 64 0a 2a 2a 20 73 65 70 61  tory and.** sepa
223b0 72 61 74 65 20 64 61 74 61 62 61 73 65 73 20 63  rate databases c
223c0 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20 4a 61 76  ontrolled by Jav
223d0 61 53 63 72 69 70 74 20 61 70 70 6c 69 63 61 74  aScript applicat
223e0 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64 65 64 0a  ions downloaded.
223f0 2a 2a 20 6f 66 66 20 74 68 65 20 49 6e 74 65 72  ** off the Inter
22400 6e 65 74 2e 20 20 54 68 65 20 69 6e 74 65 72 6e  net.  The intern
22410 61 6c 20 64 61 74 61 62 61 73 65 73 20 63 61 6e  al databases can
22420 20 62 65 20 67 69 76 65 6e 20 74 68 65 0a 2a 2a   be given the.**
22430 20 6c 61 72 67 65 2c 20 64 65 66 61 75 6c 74 20   large, default 
22440 6c 69 6d 69 74 73 2e 20 20 44 61 74 61 62 61 73  limits.  Databas
22450 65 73 20 6d 61 6e 61 67 65 64 20 62 79 20 65 78  es managed by ex
22460 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 20 63  ternal sources c
22470 61 6e 0a 2a 2a 20 62 65 20 67 69 76 65 6e 20 6d  an.** be given m
22480 75 63 68 20 73 6d 61 6c 6c 65 72 20 6c 69 6d 69  uch smaller limi
22490 74 73 20 64 65 73 69 67 6e 65 64 20 74 6f 20 70  ts designed to p
224a0 72 65 76 65 6e 74 20 61 20 64 65 6e 69 61 6c 20  revent a denial 
224b0 6f 66 20 73 65 72 76 69 63 65 0a 2a 2a 20 61 74  of service.** at
224c0 74 61 63 6b 2e 20 20 44 65 76 65 6c 6f 70 65 72  tack.  Developer
224d0 73 20 6d 69 67 68 74 20 61 6c 73 6f 20 77 61 6e  s might also wan
224e0 74 20 74 6f 20 75 73 65 20 74 68 65 20 5b 73 71  t to use the [sq
224f0 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
22500 69 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e 74 65 72  izer()].** inter
22510 66 61 63 65 20 74 6f 20 66 75 72 74 68 65 72 20  face to further 
22520 63 6f 6e 74 72 6f 6c 20 75 6e 74 72 75 73 74 65  control untruste
22530 64 20 53 51 4c 2e 20 20 54 68 65 20 73 69 7a 65  d SQL.  The size
22540 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
22550 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20 61  .** created by a
22560 6e 20 75 6e 74 72 75 73 74 65 64 20 73 63 72 69  n untrusted scri
22570 70 74 20 63 61 6e 20 62 65 20 63 6f 6e 74 61 69  pt can be contai
22580 6e 65 64 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a  ned using the.**
22590 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74   [max_page_count
225a0 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a  ] [PRAGMA]..**.*
225b0 2a 20 4e 65 77 20 72 75 6e 2d 74 69 6d 65 20 6c  * New run-time l
225c0 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 20  imit categories 
225d0 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20  may be added in 
225e0 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e  future releases.
225f0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
22600 6c 69 6d 69 74 28 73 71 6c 69 74 65 33 2a 2c 20  limit(sqlite3*, 
22610 69 6e 74 20 69 64 2c 20 69 6e 74 20 6e 65 77 56  int id, int newV
22620 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  al);../*.** CAPI
22630 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c  3REF: Run-Time L
22640 69 6d 69 74 20 43 61 74 65 67 6f 72 69 65 73 0a  imit Categories.
22650 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 6c 69  ** KEYWORDS: {li
22660 6d 69 74 20 63 61 74 65 67 6f 72 79 7d 20 7b 2a  mit category} {*
22670 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73  limit categories
22680 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f  }.**.** These co
22690 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20 76  nstants define v
226a0 61 72 69 6f 75 73 20 70 65 72 66 6f 72 6d 61 6e  arious performan
226b0 63 65 20 6c 69 6d 69 74 73 0a 2a 2a 20 74 68 61  ce limits.** tha
226c0 74 20 63 61 6e 20 62 65 20 6c 6f 77 65 72 65 64  t can be lowered
226d0 20 61 74 20 72 75 6e 2d 74 69 6d 65 20 75 73 69   at run-time usi
226e0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69  ng [sqlite3_limi
226f0 74 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 79 6e  t()]..** The syn
22700 6f 70 73 69 73 20 6f 66 20 74 68 65 20 6d 65 61  opsis of the mea
22710 6e 69 6e 67 73 20 6f 66 20 74 68 65 20 76 61 72  nings of the var
22720 69 6f 75 73 20 6c 69 6d 69 74 73 20 69 73 20 73  ious limits is s
22730 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a 20 41  hown below..** A
22740 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d  dditional inform
22750 61 74 69 6f 6e 20 69 73 20 61 76 61 69 6c 61 62  ation is availab
22760 6c 65 20 61 74 20 5b 6c 69 6d 69 74 73 20 7c 20  le at [limits | 
22770 4c 69 6d 69 74 73 20 69 6e 20 53 51 4c 69 74 65  Limits in SQLite
22780 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a  ]..**.** <dl>.**
22790 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
227a0 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53  LENGTH]] ^(<dt>S
227b0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47  QLITE_LIMIT_LENG
227c0 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  TH</dt>.** <dd>T
227d0 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20  he maximum size 
227e0 6f 66 20 61 6e 79 20 73 74 72 69 6e 67 20 6f 72  of any string or
227f0 20 42 4c 4f 42 20 6f 72 20 74 61 62 6c 65 20 72   BLOB or table r
22800 6f 77 2c 20 69 6e 20 62 79 74 65 73 2e 3c 64 64  ow, in bytes.<dd
22810 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
22820 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e  TE_LIMIT_SQL_LEN
22830 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  GTH]] ^(<dt>SQLI
22840 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e  TE_LIMIT_SQL_LEN
22850 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  GTH</dt>.** <dd>
22860 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67  The maximum leng
22870 74 68 20 6f 66 20 61 6e 20 53 51 4c 20 73 74 61  th of an SQL sta
22880 74 65 6d 65 6e 74 2c 20 69 6e 20 62 79 74 65 73  tement, in bytes
22890 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  .</dd>)^.**.** [
228a0 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f  [SQLITE_LIMIT_CO
228b0 4c 55 4d 4e 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  LUMN]] ^(<dt>SQL
228c0 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e  ITE_LIMIT_COLUMN
228d0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
228e0 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
228f0 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20  of columns in a 
22900 74 61 62 6c 65 20 64 65 66 69 6e 69 74 69 6f 6e  table definition
22910 20 6f 72 20 69 6e 20 74 68 65 0a 2a 2a 20 72 65   or in the.** re
22920 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53  sult set of a [S
22930 45 4c 45 43 54 5d 20 6f 72 20 74 68 65 20 6d 61  ELECT] or the ma
22940 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
22950 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e 20 69 6e  columns in an in
22960 64 65 78 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e 20  dex.** or in an 
22970 4f 52 44 45 52 20 42 59 20 6f 72 20 47 52 4f 55  ORDER BY or GROU
22980 50 20 42 59 20 63 6c 61 75 73 65 2e 3c 2f 64 64  P BY clause.</dd
22990 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
229a0 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45  TE_LIMIT_EXPR_DE
229b0 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  PTH]] ^(<dt>SQLI
229c0 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45  TE_LIMIT_EXPR_DE
229d0 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  PTH</dt>.** <dd>
229e0 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74  The maximum dept
229f0 68 20 6f 66 20 74 68 65 20 70 61 72 73 65 20 74  h of the parse t
22a00 72 65 65 20 6f 6e 20 61 6e 79 20 65 78 70 72 65  ree on any expre
22a10 73 73 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  ssion.</dd>)^.**
22a20 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
22a30 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45  IT_COMPOUND_SELE
22a40 43 54 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  CT]] ^(<dt>SQLIT
22a50 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44  E_LIMIT_COMPOUND
22a60 5f 53 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20  _SELECT</dt>.** 
22a70 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
22a80 6e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20  number of terms 
22a90 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20 53 45  in a compound SE
22aa0 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e 3c  LECT statement.<
22ab0 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  /dd>)^.**.** [[S
22ac0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45  QLITE_LIMIT_VDBE
22ad0 5f 4f 50 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  _OP]] ^(<dt>SQLI
22ae0 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50  TE_LIMIT_VDBE_OP
22af0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
22b00 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
22b10 6f 66 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 20  of instructions 
22b20 69 6e 20 61 20 76 69 72 74 75 61 6c 20 6d 61 63  in a virtual mac
22b30 68 69 6e 65 20 70 72 6f 67 72 61 6d 0a 2a 2a 20  hine program.** 
22b40 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e  used to implemen
22b50 74 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  t an SQL stateme
22b60 6e 74 2e 20 20 54 68 69 73 20 6c 69 6d 69 74 20  nt.  This limit 
22b70 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79  is not currently
22b80 0a 2a 2a 20 65 6e 66 6f 72 63 65 64 2c 20 74 68  .** enforced, th
22b90 6f 75 67 68 20 74 68 61 74 20 6d 69 67 68 74 20  ough that might 
22ba0 62 65 20 61 64 64 65 64 20 69 6e 20 73 6f 6d 65  be added in some
22bb0 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20   future release 
22bc0 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 3c 2f 64  of.** SQLite.</d
22bd0 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d>)^.**.** [[SQL
22be0 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49  ITE_LIMIT_FUNCTI
22bf0 4f 4e 5f 41 52 47 5d 5d 20 5e 28 3c 64 74 3e 53  ON_ARG]] ^(<dt>S
22c00 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43  QLITE_LIMIT_FUNC
22c10 54 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a 2a 2a  TION_ARG</dt>.**
22c20 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
22c30 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d   number of argum
22c40 65 6e 74 73 20 6f 6e 20 61 20 66 75 6e 63 74 69  ents on a functi
22c50 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  on.</dd>)^.**.**
22c60 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
22c70 41 54 54 41 43 48 45 44 5d 5d 20 5e 28 3c 64 74  ATTACHED]] ^(<dt
22c80 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54  >SQLITE_LIMIT_AT
22c90 54 41 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c  TACHED</dt>.** <
22ca0 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
22cb0 75 6d 62 65 72 20 6f 66 20 5b 41 54 54 41 43 48  umber of [ATTACH
22cc0 20 7c 20 61 74 74 61 63 68 65 64 20 64 61 74 61   | attached data
22cd0 62 61 73 65 73 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a  bases].)^</dd>.*
22ce0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
22cf0 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e  MIT_LIKE_PATTERN
22d00 5f 4c 45 4e 47 54 48 5d 5d 0a 2a 2a 20 5e 28 3c  _LENGTH]].** ^(<
22d10 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
22d20 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e  LIKE_PATTERN_LEN
22d30 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  GTH</dt>.** <dd>
22d40 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67  The maximum leng
22d50 74 68 20 6f 66 20 74 68 65 20 70 61 74 74 65 72  th of the patter
22d60 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  n argument to th
22d70 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a 2a 20 5b  e [LIKE] or.** [
22d80 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 73 2e  GLOB] operators.
22d90 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  </dd>)^.**.** [[
22da0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52  SQLITE_LIMIT_VAR
22db0 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 5d 0a 2a  IABLE_NUMBER]].*
22dc0 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  * ^(<dt>SQLITE_L
22dd0 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55  IMIT_VARIABLE_NU
22de0 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  MBER</dt>.** <dd
22df0 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 69 6e 64  >The maximum ind
22e00 65 78 20 6e 75 6d 62 65 72 20 6f 66 20 61 6e 79  ex number of any
22e10 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20   [parameter] in 
22e20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  an SQL statement
22e30 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  .)^.**.** [[SQLI
22e40 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52  TE_LIMIT_TRIGGER
22e50 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53  _DEPTH]] ^(<dt>S
22e60 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47  QLITE_LIMIT_TRIG
22e70 47 45 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a  GER_DEPTH</dt>.*
22e80 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
22e90 6d 20 64 65 70 74 68 20 6f 66 20 72 65 63 75 72  m depth of recur
22ea0 73 69 6f 6e 20 66 6f 72 20 74 72 69 67 67 65 72  sion for trigger
22eb0 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64  s.</dd>)^.** </d
22ec0 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  l>.*/.#define SQ
22ed0 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54  LITE_LIMIT_LENGT
22ee0 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  H               
22ef0 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53       0.#define S
22f00 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f  QLITE_LIMIT_SQL_
22f10 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20 20 20  LENGTH          
22f20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20        1.#define 
22f30 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c  SQLITE_LIMIT_COL
22f40 55 4d 4e 20 20 20 20 20 20 20 20 20 20 20 20 20  UMN             
22f50 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65         2.#define
22f60 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58   SQLITE_LIMIT_EX
22f70 50 52 5f 44 45 50 54 48 20 20 20 20 20 20 20 20  PR_DEPTH        
22f80 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e          3.#defin
22f90 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43  e SQLITE_LIMIT_C
22fa0 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 20 20  OMPOUND_SELECT  
22fb0 20 20 20 20 20 20 20 20 20 34 0a 23 64 65 66 69           4.#defi
22fc0 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
22fd0 56 44 42 45 5f 4f 50 20 20 20 20 20 20 20 20 20  VDBE_OP         
22fe0 20 20 20 20 20 20 20 20 20 20 35 0a 23 64 65 66            5.#def
22ff0 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
23000 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 20 20 20  _FUNCTION_ARG   
23010 20 20 20 20 20 20 20 20 20 20 20 36 0a 23 64 65             6.#de
23020 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
23030 54 5f 41 54 54 41 43 48 45 44 20 20 20 20 20 20  T_ATTACHED      
23040 20 20 20 20 20 20 20 20 20 20 20 20 37 0a 23 64              7.#d
23050 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
23060 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f  IT_LIKE_PATTERN_
23070 4c 45 4e 47 54 48 20 20 20 20 20 20 20 38 0a 23  LENGTH       8.#
23080 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
23090 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d  MIT_VARIABLE_NUM
230a0 42 45 52 20 20 20 20 20 20 20 20 20 20 20 39 0a  BER           9.
230b0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
230c0 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50  IMIT_TRIGGER_DEP
230d0 54 48 20 20 20 20 20 20 20 20 20 20 20 20 31 30  TH            10
230e0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
230f0 3a 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53  : Compiling An S
23100 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  QL Statement.** 
23110 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 73  KEYWORDS: {SQL s
23120 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65  tatement compile
23130 72 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63  r}.**.** To exec
23140 75 74 65 20 61 6e 20 53 51 4c 20 71 75 65 72 79  ute an SQL query
23150 2c 20 69 74 20 6d 75 73 74 20 66 69 72 73 74 20  , it must first 
23160 62 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f  be compiled into
23170 20 61 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20   a byte-code.** 
23180 70 72 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e  program using on
23190 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  e of these routi
231a0 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  nes..**.** The f
231b0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2c 20 22  irst argument, "
231c0 64 62 22 2c 20 69 73 20 61 20 5b 64 61 74 61 62  db", is a [datab
231d0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
231e0 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 0a  obtained from a.
231f0 2a 2a 20 70 72 69 6f 72 20 73 75 63 63 65 73 73  ** prior success
23200 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ful call to [sql
23210 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73  ite3_open()], [s
23220 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
23230 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
23240 5f 6f 70 65 6e 31 36 28 29 5d 2e 20 20 54 68 65  _open16()].  The
23250 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
23260 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 68 61  tion must not ha
23270 76 65 20 62 65 65 6e 20 63 6c 6f 73 65 64 2e 0a  ve been closed..
23280 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  **.** The second
23290 20 61 72 67 75 6d 65 6e 74 2c 20 22 7a 53 71 6c   argument, "zSql
232a0 22 2c 20 69 73 20 74 68 65 20 73 74 61 74 65 6d  ", is the statem
232b0 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c  ent to be compil
232c0 65 64 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61  ed, encoded.** a
232d0 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f  s either UTF-8 o
232e0 72 20 55 54 46 2d 31 36 2e 20 20 54 68 65 20 73  r UTF-16.  The s
232f0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
23300 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65   and sqlite3_pre
23310 70 61 72 65 5f 76 32 28 29 0a 2a 2a 20 69 6e 74  pare_v2().** int
23320 65 72 66 61 63 65 73 20 75 73 65 20 55 54 46 2d  erfaces use UTF-
23330 38 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70  8, and sqlite3_p
23340 72 65 70 61 72 65 31 36 28 29 20 61 6e 64 20 73  repare16() and s
23350 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
23360 5f 76 32 28 29 0a 2a 2a 20 75 73 65 20 55 54 46  _v2().** use UTF
23370 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  -16..**.** ^If t
23380 68 65 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e  he nByte argumen
23390 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 7a  t is less than z
233a0 65 72 6f 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69  ero, then zSql i
233b0 73 20 72 65 61 64 20 75 70 20 74 6f 20 74 68 65  s read up to the
233c0 0a 2a 2a 20 66 69 72 73 74 20 7a 65 72 6f 20 74  .** first zero t
233d0 65 72 6d 69 6e 61 74 6f 72 2e 20 5e 49 66 20 6e  erminator. ^If n
233e0 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61  Byte is non-nega
233f0 74 69 76 65 2c 20 74 68 65 6e 20 69 74 20 69 73  tive, then it is
23400 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20   the maximum.** 
23410 6e 75 6d 62 65 72 20 6f 66 20 20 62 79 74 65 73  number of  bytes
23420 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e   read from zSql.
23430 20 20 5e 57 68 65 6e 20 6e 42 79 74 65 20 69 73    ^When nByte is
23440 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74   non-negative, t
23450 68 65 0a 2a 2a 20 7a 53 71 6c 20 73 74 72 69 6e  he.** zSql strin
23460 67 20 65 6e 64 73 20 61 74 20 65 69 74 68 65 72  g ends at either
23470 20 74 68 65 20 66 69 72 73 74 20 27 5c 30 30 30   the first '\000
23480 27 20 6f 72 20 27 5c 75 30 30 30 30 27 20 63 68  ' or '\u0000' ch
23490 61 72 61 63 74 65 72 20 6f 72 0a 2a 2a 20 74 68  aracter or.** th
234a0 65 20 6e 42 79 74 65 2d 74 68 20 62 79 74 65 2c  e nByte-th byte,
234b0 20 77 68 69 63 68 65 76 65 72 20 63 6f 6d 65 73   whichever comes
234c0 20 66 69 72 73 74 2e 20 49 66 20 74 68 65 20 63   first. If the c
234d0 61 6c 6c 65 72 20 6b 6e 6f 77 73 0a 2a 2a 20 74  aller knows.** t
234e0 68 61 74 20 74 68 65 20 73 75 70 70 6c 69 65 64  hat the supplied
234f0 20 73 74 72 69 6e 67 20 69 73 20 6e 75 6c 2d 74   string is nul-t
23500 65 72 6d 69 6e 61 74 65 64 2c 20 74 68 65 6e 20  erminated, then 
23510 74 68 65 72 65 20 69 73 20 61 20 73 6d 61 6c 6c  there is a small
23520 0a 2a 2a 20 70 65 72 66 6f 72 6d 61 6e 63 65 20  .** performance 
23530 61 64 76 61 6e 74 61 67 65 20 74 6f 20 62 65 20  advantage to be 
23540 67 61 69 6e 65 64 20 62 79 20 70 61 73 73 69 6e  gained by passin
23550 67 20 61 6e 20 6e 42 79 74 65 20 70 61 72 61 6d  g an nByte param
23560 65 74 65 72 20 74 68 61 74 0a 2a 2a 20 69 73 20  eter that.** is 
23570 65 71 75 61 6c 20 74 6f 20 74 68 65 20 6e 75 6d  equal to the num
23580 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
23590 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67  the input string
235a0 20 3c 69 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f 69   <i>including</i
235b0 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d 74 65 72  >.** the nul-ter
235c0 6d 69 6e 61 74 6f 72 20 62 79 74 65 73 20 61 73  minator bytes as
235d0 20 74 68 69 73 20 73 61 76 65 73 20 53 51 4c 69   this saves SQLi
235e0 74 65 20 66 72 6f 6d 20 68 61 76 69 6e 67 20 74  te from having t
235f0 6f 0a 2a 2a 20 6d 61 6b 65 20 61 20 63 6f 70 79  o.** make a copy
23600 20 6f 66 20 74 68 65 20 69 6e 70 75 74 20 73 74   of the input st
23610 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ring..**.** ^If 
23620 70 7a 54 61 69 6c 20 69 73 20 6e 6f 74 20 4e 55  pzTail is not NU
23630 4c 4c 20 74 68 65 6e 20 2a 70 7a 54 61 69 6c 20  LL then *pzTail 
23640 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74  is made to point
23650 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 62 79   to the first by
23660 74 65 0a 2a 2a 20 70 61 73 74 20 74 68 65 20 65  te.** past the e
23670 6e 64 20 6f 66 20 74 68 65 20 66 69 72 73 74 20  nd of the first 
23680 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  SQL statement in
23690 20 7a 53 71 6c 2e 20 20 54 68 65 73 65 20 72 6f   zSql.  These ro
236a0 75 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a 2a 20 63  utines only.** c
236b0 6f 6d 70 69 6c 65 20 74 68 65 20 66 69 72 73 74  ompile the first
236c0 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53   statement in zS
236d0 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c 20 69  ql, so *pzTail i
236e0 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20  s left pointing 
236f0 74 6f 0a 2a 2a 20 77 68 61 74 20 72 65 6d 61 69  to.** what remai
23700 6e 73 20 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a  ns uncompiled..*
23710 2a 0a 2a 2a 20 5e 2a 70 70 53 74 6d 74 20 69 73  *.** ^*ppStmt is
23720 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74   left pointing t
23730 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20 5b 70 72  o a compiled [pr
23740 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
23750 5d 20 74 68 61 74 20 63 61 6e 20 62 65 0a 2a 2a  ] that can be.**
23760 20 65 78 65 63 75 74 65 64 20 75 73 69 6e 67 20   executed using 
23770 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
23780 2e 20 20 5e 49 66 20 74 68 65 72 65 20 69 73 20  .  ^If there is 
23790 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70 53 74 6d  an error, *ppStm
237a0 74 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f 20 4e  t is set.** to N
237b0 55 4c 4c 2e 20 20 5e 49 66 20 74 68 65 20 69 6e  ULL.  ^If the in
237c0 70 75 74 20 74 65 78 74 20 63 6f 6e 74 61 69 6e  put text contain
237d0 73 20 6e 6f 20 53 51 4c 20 28 69 66 20 74 68 65  s no SQL (if the
237e0 20 69 6e 70 75 74 20 69 73 20 61 6e 20 65 6d 70   input is an emp
237f0 74 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 72 20  ty.** string or 
23800 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65 6e 20  a comment) then 
23810 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 20 74  *ppStmt is set t
23820 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65 20 63  o NULL..** The c
23830 61 6c 6c 69 6e 67 20 70 72 6f 63 65 64 75 72 65  alling procedure
23840 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20   is responsible 
23850 66 6f 72 20 64 65 6c 65 74 69 6e 67 20 74 68 65  for deleting the
23860 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53 51 4c   compiled.** SQL
23870 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67   statement using
23880 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
23890 7a 65 28 29 5d 20 61 66 74 65 72 20 69 74 20 68  ze()] after it h
238a0 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68  as finished with
238b0 20 69 74 2e 0a 2a 2a 20 70 70 53 74 6d 74 20 6d   it..** ppStmt m
238c0 61 79 20 6e 6f 74 20 62 65 20 4e 55 4c 4c 2e 0a  ay not be NULL..
238d0 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73 75 63 63 65 73  **.** ^On succes
238e0 73 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 70  s, the sqlite3_p
238f0 72 65 70 61 72 65 28 29 20 66 61 6d 69 6c 79 20  repare() family 
23900 6f 66 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  of routines retu
23910 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 3b 0a  rn [SQLITE_OK];.
23920 2a 2a 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20  ** otherwise an 
23930 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20  [error code] is 
23940 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
23950 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70  The sqlite3_prep
23960 61 72 65 5f 76 32 28 29 20 61 6e 64 20 73 71 6c  are_v2() and sql
23970 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
23980 32 28 29 20 69 6e 74 65 72 66 61 63 65 73 20 61  2() interfaces a
23990 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e 64 65  re.** recommende
239a0 64 20 66 6f 72 20 61 6c 6c 20 6e 65 77 20 70 72  d for all new pr
239b0 6f 67 72 61 6d 73 2e 20 54 68 65 20 74 77 6f 20  ograms. The two 
239c0 6f 6c 64 65 72 20 69 6e 74 65 72 66 61 63 65 73  older interfaces
239d0 20 61 72 65 20 72 65 74 61 69 6e 65 64 0a 2a 2a   are retained.**
239e0 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63   for backwards c
239f0 6f 6d 70 61 74 69 62 69 6c 69 74 79 2c 20 62 75  ompatibility, bu
23a00 74 20 74 68 65 69 72 20 75 73 65 20 69 73 20 64  t their use is d
23a10 69 73 63 6f 75 72 61 67 65 64 2e 0a 2a 2a 20 5e  iscouraged..** ^
23a20 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74 65  In the "v2" inte
23a30 72 66 61 63 65 73 2c 20 74 68 65 20 70 72 65 70  rfaces, the prep
23a40 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a  ared statement.*
23a50 2a 20 74 68 61 74 20 69 73 20 72 65 74 75 72 6e  * that is return
23a60 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33  ed (the [sqlite3
23a70 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 29 20 63  _stmt] object) c
23a80 6f 6e 74 61 69 6e 73 20 61 20 63 6f 70 79 20 6f  ontains a copy o
23a90 66 20 74 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61  f the.** origina
23aa0 6c 20 53 51 4c 20 74 65 78 74 2e 20 54 68 69 73  l SQL text. This
23ab0 20 63 61 75 73 65 73 20 74 68 65 20 5b 73 71 6c   causes the [sql
23ac0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 69 6e 74  ite3_step()] int
23ad0 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20 62 65 68  erface to.** beh
23ae0 61 76 65 20 64 69 66 66 65 72 65 6e 74 6c 79 20  ave differently 
23af0 69 6e 20 74 68 72 65 65 20 77 61 79 73 3a 0a 2a  in three ways:.*
23b00 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ol>.** <li
23b10 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64 61 74  >.** ^If the dat
23b20 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 61  abase schema cha
23b30 6e 67 65 73 2c 20 69 6e 73 74 65 61 64 20 6f 66  nges, instead of
23b40 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49   returning [SQLI
23b50 54 45 5f 53 43 48 45 4d 41 5d 20 61 73 20 69 74  TE_SCHEMA] as it
23b60 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 64 20  .** always used 
23b70 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 74 65 33 5f  to do, [sqlite3_
23b80 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 61 75 74  step()] will aut
23b90 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d  omatically recom
23ba0 70 69 6c 65 20 74 68 65 20 53 51 4c 0a 2a 2a 20  pile the SQL.** 
23bb0 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 72  statement and tr
23bc0 79 20 74 6f 20 72 75 6e 20 69 74 20 61 67 61 69  y to run it agai
23bd0 6e 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a  n..** </li>.**.*
23be0 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 57 68 65 6e 20  * <li>.** ^When 
23bf0 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2c  an error occurs,
23c00 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
23c10 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6f 6e  ] will return on
23c20 65 20 6f 66 20 74 68 65 20 64 65 74 61 69 6c 65  e of the detaile
23c30 64 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65  d.** [error code
23c40 73 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20  s] or [extended 
23c50 65 72 72 6f 72 20 63 6f 64 65 73 5d 2e 20 20 5e  error codes].  ^
23c60 54 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76  The legacy behav
23c70 69 6f 72 20 77 61 73 20 74 68 61 74 0a 2a 2a 20  ior was that.** 
23c80 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
23c90 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65 74 75   would only retu
23ca0 72 6e 20 61 20 67 65 6e 65 72 69 63 20 5b 53 51  rn a generic [SQ
23cb0 4c 49 54 45 5f 45 52 52 4f 52 5d 20 72 65 73 75  LITE_ERROR] resu
23cc0 6c 74 20 63 6f 64 65 0a 2a 2a 20 61 6e 64 20 74  lt code.** and t
23cd0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 77  he application w
23ce0 6f 75 6c 64 20 68 61 76 65 20 74 6f 20 6d 61 6b  ould have to mak
23cf0 65 20 61 20 73 65 63 6f 6e 64 20 63 61 6c 6c 20  e a second call 
23d00 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  to [sqlite3_rese
23d10 74 28 29 5d 0a 2a 2a 20 69 6e 20 6f 72 64 65 72  t()].** in order
23d20 20 74 6f 20 66 69 6e 64 20 74 68 65 20 75 6e 64   to find the und
23d30 65 72 6c 79 69 6e 67 20 63 61 75 73 65 20 6f 66  erlying cause of
23d40 20 74 68 65 20 70 72 6f 62 6c 65 6d 2e 20 57 69   the problem. Wi
23d50 74 68 20 74 68 65 20 22 76 32 22 20 70 72 65 70  th the "v2" prep
23d60 61 72 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  are.** interface
23d70 73 2c 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e  s, the underlyin
23d80 67 20 72 65 61 73 6f 6e 20 66 6f 72 20 74 68 65  g reason for the
23d90 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e   error is return
23da0 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a  ed immediately..
23db0 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c  ** </li>.**.** <
23dc0 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73  li>.** ^If the s
23dd0 70 65 63 69 66 69 63 20 76 61 6c 75 65 20 62 6f  pecific value bo
23de0 75 6e 64 20 74 6f 20 5b 70 61 72 61 6d 65 74 65  und to [paramete
23df0 72 20 7c 20 68 6f 73 74 20 70 61 72 61 6d 65 74  r | host paramet
23e00 65 72 5d 20 69 6e 20 74 68 65 20 0a 2a 2a 20 57  er] in the .** W
23e10 48 45 52 45 20 63 6c 61 75 73 65 20 6d 69 67 68  HERE clause migh
23e20 74 20 69 6e 66 6c 75 65 6e 63 65 20 74 68 65 20  t influence the 
23e30 63 68 6f 69 63 65 20 6f 66 20 71 75 65 72 79 20  choice of query 
23e40 70 6c 61 6e 20 66 6f 72 20 61 20 73 74 61 74 65  plan for a state
23e50 6d 65 6e 74 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  ment,.** then th
23e60 65 20 73 74 61 74 65 6d 65 6e 74 20 77 69 6c 6c  e statement will
23e70 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c   be automaticall
23e80 79 20 72 65 63 6f 6d 70 69 6c 65 64 2c 20 61 73  y recompiled, as
23e90 20 69 66 20 74 68 65 72 65 20 68 61 64 20 62 65   if there had be
23ea0 65 6e 20 0a 2a 2a 20 61 20 73 63 68 65 6d 61 20  en .** a schema 
23eb0 63 68 61 6e 67 65 2c 20 6f 6e 20 74 68 65 20 66  change, on the f
23ec0 69 72 73 74 20 20 5b 73 71 6c 69 74 65 33 5f 73  irst  [sqlite3_s
23ed0 74 65 70 28 29 5d 20 63 61 6c 6c 20 66 6f 6c 6c  tep()] call foll
23ee0 6f 77 69 6e 67 20 61 6e 79 20 63 68 61 6e 67 65  owing any change
23ef0 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  .** to the [sqli
23f00 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20  te3_bind_text | 
23f10 62 69 6e 64 69 6e 67 73 5d 20 6f 66 20 74 68 61  bindings] of tha
23f20 74 20 5b 70 61 72 61 6d 65 74 65 72 5d 2e 20 0a  t [parameter]. .
23f30 2a 2a 20 5e 54 68 65 20 73 70 65 63 69 66 69 63  ** ^The specific
23f40 20 76 61 6c 75 65 20 6f 66 20 57 48 45 52 45 2d   value of WHERE-
23f50 63 6c 61 75 73 65 20 5b 70 61 72 61 6d 65 74 65  clause [paramete
23f60 72 5d 20 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e  r] might influen
23f70 63 65 20 74 68 65 20 0a 2a 2a 20 63 68 6f 69 63  ce the .** choic
23f80 65 20 6f 66 20 71 75 65 72 79 20 70 6c 61 6e 20  e of query plan 
23f90 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  if the parameter
23fa0 20 69 73 20 74 68 65 20 6c 65 66 74 2d 68 61 6e   is the left-han
23fb0 64 20 73 69 64 65 20 6f 66 20 61 20 5b 4c 49 4b  d side of a [LIK
23fc0 45 5d 0a 2a 2a 20 6f 72 20 5b 47 4c 4f 42 5d 20  E].** or [GLOB] 
23fd0 6f 70 65 72 61 74 6f 72 20 6f 72 20 69 66 20 74  operator or if t
23fe0 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  he parameter is 
23ff0 63 6f 6d 70 61 72 65 64 20 74 6f 20 61 6e 20 69  compared to an i
24000 6e 64 65 78 65 64 20 63 6f 6c 75 6d 6e 0a 2a 2a  ndexed column.**
24010 20 61 6e 64 20 74 68 65 20 5b 53 51 4c 49 54 45   and the [SQLITE
24020 5f 45 4e 41 42 4c 45 5f 53 54 41 54 33 5d 20 63  _ENABLE_STAT3] c
24030 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
24040 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a  on is enabled..*
24050 2a 20 74 68 65 20 0a 2a 2a 20 3c 2f 6c 69 3e 0a  * the .** </li>.
24060 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 69 6e 74 20  ** </ol>.*/.int 
24070 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
24080 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
24090 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61             /* Da
240a0 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f  tabase handle */
240b0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
240c0 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51  Sql,       /* SQ
240d0 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46  L statement, UTF
240e0 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20  -8 encoded */.  
240f0 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20  int nByte,      
24100 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d          /* Maxim
24110 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71  um length of zSq
24120 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20  l in bytes. */. 
24130 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a   sqlite3_stmt **
24140 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a  ppStmt,  /* OUT:
24150 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c   Statement handl
24160 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
24170 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f  r **pzTail     /
24180 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74  * OUT: Pointer t
24190 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e  o unused portion
241a0 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69   of zSql */.);.i
241b0 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nt sqlite3_prepa
241c0 72 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33  re_v2(.  sqlite3
241d0 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
241e0 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e   /* Database han
241f0 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  dle */.  const c
24200 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20  har *zSql,      
24210 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   /* SQL statemen
24220 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64  t, UTF-8 encoded
24230 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c   */.  int nByte,
24240 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
24250 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   Maximum length 
24260 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73  of zSql in bytes
24270 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73  . */.  sqlite3_s
24280 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f  tmt **ppStmt,  /
24290 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74  * OUT: Statement
242a0 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
242b0 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c  st char **pzTail
242c0 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69       /* OUT: Poi
242d0 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70  nter to unused p
242e0 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a  ortion of zSql *
242f0 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  /.);.int sqlite3
24300 5f 70 72 65 70 61 72 65 31 36 28 0a 20 20 73 71  _prepare16(.  sq
24310 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
24320 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
24330 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  e handle */.  co
24340 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20  nst void *zSql, 
24350 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61        /* SQL sta
24360 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65  tement, UTF-16 e
24370 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20  ncoded */.  int 
24380 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20  nByte,          
24390 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c      /* Maximum l
243a0 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e  ength of zSql in
243b0 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c   bytes. */.  sql
243c0 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74  ite3_stmt **ppSt
243d0 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61  mt,  /* OUT: Sta
243e0 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f  tement handle */
243f0 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a  .  const void **
24400 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55  pzTail     /* OU
24410 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e  T: Pointer to un
24420 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20  used portion of 
24430 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73  zSql */.);.int s
24440 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
24450 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  _v2(.  sqlite3 *
24460 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f  db,            /
24470 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c  * Database handl
24480 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  e */.  const voi
24490 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f  d *zSql,       /
244a0 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  * SQL statement,
244b0 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20   UTF-16 encoded 
244c0 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20  */.  int nByte, 
244d0 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
244e0 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  Maximum length o
244f0 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e  f zSql in bytes.
24500 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74   */.  sqlite3_st
24510 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a  mt **ppStmt,  /*
24520 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20   OUT: Statement 
24530 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
24540 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20  t void **pzTail 
24550 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e      /* OUT: Poin
24560 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f  ter to unused po
24570 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f  rtion of zSql */
24580 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
24590 52 45 46 3a 20 52 65 74 72 69 65 76 69 6e 67 20  REF: Retrieving 
245a0 53 74 61 74 65 6d 65 6e 74 20 53 51 4c 0a 2a 2a  Statement SQL.**
245b0 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65 72 66  .** ^This interf
245c0 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20  ace can be used 
245d0 74 6f 20 72 65 74 72 69 65 76 65 20 61 20 73 61  to retrieve a sa
245e0 76 65 64 20 63 6f 70 79 20 6f 66 20 74 68 65 20  ved copy of the 
245f0 6f 72 69 67 69 6e 61 6c 0a 2a 2a 20 53 51 4c 20  original.** SQL 
24600 74 65 78 74 20 75 73 65 64 20 74 6f 20 63 72 65  text used to cre
24610 61 74 65 20 61 20 5b 70 72 65 70 61 72 65 64 20  ate a [prepared 
24620 73 74 61 74 65 6d 65 6e 74 5d 20 69 66 20 74 68  statement] if th
24630 61 74 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73  at statement was
24640 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 75 73 69  .** compiled usi
24650 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74  ng either [sqlit
24660 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
24670 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   or [sqlite3_pre
24680 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2f  pare16_v2()]..*/
24690 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
246a0 69 74 65 33 5f 73 71 6c 28 73 71 6c 69 74 65 33  ite3_sql(sqlite3
246b0 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a  _stmt *pStmt);..
246c0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
246d0 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 6e 20  Determine If An 
246e0 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 57 72  SQL Statement Wr
246f0 69 74 65 73 20 54 68 65 20 44 61 74 61 62 61 73  ites The Databas
24700 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  e.**.** ^The sql
24710 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e  ite3_stmt_readon
24720 6c 79 28 58 29 20 69 6e 74 65 72 66 61 63 65 20  ly(X) interface 
24730 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 6e 6f  returns true (no
24740 6e 2d 7a 65 72 6f 29 20 69 66 0a 2a 2a 20 61 6e  n-zero) if.** an
24750 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 5b 70  d only if the [p
24760 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
24770 74 5d 20 58 20 6d 61 6b 65 73 20 6e 6f 20 64 69  t] X makes no di
24780 72 65 63 74 20 63 68 61 6e 67 65 73 20 74 6f 0a  rect changes to.
24790 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f  ** the content o
247a0 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  f the database f
247b0 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20  ile..**.** Note 
247c0 74 68 61 74 20 5b 61 70 70 6c 69 63 61 74 69 6f  that [applicatio
247d0 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
247e0 6e 63 74 69 6f 6e 73 5d 20 6f 72 0a 2a 2a 20 5b  nctions] or.** [
247f0 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 5d 20  virtual tables] 
24800 6d 69 67 68 74 20 63 68 61 6e 67 65 20 74 68 65  might change the
24810 20 64 61 74 61 62 61 73 65 20 69 6e 64 69 72 65   database indire
24820 63 74 6c 79 20 61 73 20 61 20 73 69 64 65 20 65  ctly as a side e
24830 66 66 65 63 74 2e 20 20 0a 2a 2a 20 5e 28 46 6f  ffect.  .** ^(Fo
24840 72 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 61 6e  r example, if an
24850 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66   application def
24860 69 6e 65 73 20 61 20 66 75 6e 63 74 69 6f 6e 20  ines a function 
24870 22 65 76 61 6c 28 29 22 20 74 68 61 74 20 0a 2a  "eval()" that .*
24880 2a 20 63 61 6c 6c 73 20 5b 73 71 6c 69 74 65 33  * calls [sqlite3
24890 5f 65 78 65 63 28 29 5d 2c 20 74 68 65 6e 20 74  _exec()], then t
248a0 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c  he following SQL
248b0 20 73 74 61 74 65 6d 65 6e 74 20 77 6f 75 6c 64   statement would
248c0 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 64  .** change the d
248d0 61 74 61 62 61 73 65 20 66 69 6c 65 20 74 68 72  atabase file thr
248e0 6f 75 67 68 20 73 69 64 65 2d 65 66 66 65 63 74  ough side-effect
248f0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
24900 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20  uote><pre>.**   
24910 20 53 45 4c 45 43 54 20 65 76 61 6c 28 27 44 45   SELECT eval('DE
24920 4c 45 54 45 20 46 52 4f 4d 20 74 31 27 29 20 46  LETE FROM t1') F
24930 52 4f 4d 20 74 32 3b 0a 2a 2a 20 3c 2f 70 72 65  ROM t2;.** </pre
24940 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
24950 2a 0a 2a 2a 20 42 75 74 20 62 65 63 61 75 73 65  *.** But because
24960 20 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74   the [SELECT] st
24970 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74  atement does not
24980 20 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 61   change the data
24990 62 61 73 65 20 66 69 6c 65 0a 2a 2a 20 64 69 72  base file.** dir
249a0 65 63 74 6c 79 2c 20 73 71 6c 69 74 65 33 5f 73  ectly, sqlite3_s
249b0 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 77  tmt_readonly() w
249c0 6f 75 6c 64 20 73 74 69 6c 6c 20 72 65 74 75 72  ould still retur
249d0 6e 20 74 72 75 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20  n true.)^.**.** 
249e0 5e 54 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e  ^Transaction con
249f0 74 72 6f 6c 20 73 74 61 74 65 6d 65 6e 74 73 20  trol statements 
24a00 73 75 63 68 20 61 73 20 5b 42 45 47 49 4e 5d 2c  such as [BEGIN],
24a10 20 5b 43 4f 4d 4d 49 54 5d 2c 20 5b 52 4f 4c 4c   [COMMIT], [ROLL
24a20 42 41 43 4b 5d 2c 0a 2a 2a 20 5b 53 41 56 45 50  BACK],.** [SAVEP
24a30 4f 49 4e 54 5d 2c 20 61 6e 64 20 5b 52 45 4c 45  OINT], and [RELE
24a40 41 53 45 5d 20 63 61 75 73 65 20 73 71 6c 69 74  ASE] cause sqlit
24a50 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79  e3_stmt_readonly
24a60 28 29 20 74 6f 20 72 65 74 75 72 6e 20 74 72 75  () to return tru
24a70 65 2c 0a 2a 2a 20 73 69 6e 63 65 20 74 68 65 20  e,.** since the 
24a80 73 74 61 74 65 6d 65 6e 74 73 20 74 68 65 6d 73  statements thems
24a90 65 6c 76 65 73 20 64 6f 20 6e 6f 74 20 61 63 74  elves do not act
24aa0 75 61 6c 6c 79 20 6d 6f 64 69 66 79 20 74 68 65  ually modify the
24ab0 20 64 61 74 61 62 61 73 65 20 62 75 74 0a 2a 2a   database but.**
24ac0 20 72 61 74 68 65 72 20 74 68 65 79 20 63 6f 6e   rather they con
24ad0 74 72 6f 6c 20 74 68 65 20 74 69 6d 69 6e 67 20  trol the timing 
24ae0 6f 66 20 77 68 65 6e 20 6f 74 68 65 72 20 73 74  of when other st
24af0 61 74 65 6d 65 6e 74 73 20 6d 6f 64 69 66 79 20  atements modify 
24b00 74 68 65 20 0a 2a 2a 20 64 61 74 61 62 61 73 65  the .** database
24b10 2e 20 20 5e 54 68 65 20 5b 41 54 54 41 43 48 5d  .  ^The [ATTACH]
24b20 20 61 6e 64 20 5b 44 45 54 41 43 48 5d 20 73 74   and [DETACH] st
24b30 61 74 65 6d 65 6e 74 73 20 61 6c 73 6f 20 63 61  atements also ca
24b40 75 73 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73  use.** sqlite3_s
24b50 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74  tmt_readonly() t
24b60 6f 20 72 65 74 75 72 6e 20 74 72 75 65 20 73 69  o return true si
24b70 6e 63 65 2c 20 77 68 69 6c 65 20 74 68 6f 73 65  nce, while those
24b80 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 63   statements.** c
24b90 68 61 6e 67 65 20 74 68 65 20 63 6f 6e 66 69 67  hange the config
24ba0 75 72 61 74 69 6f 6e 20 6f 66 20 61 20 64 61 74  uration of a dat
24bb0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
24bc0 2c 20 74 68 65 79 20 64 6f 20 6e 6f 74 20 6d 61  , they do not ma
24bd0 6b 65 20 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74  ke .** changes t
24be0 6f 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66  o the content of
24bf0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
24c00 6c 65 73 20 6f 6e 20 64 69 73 6b 2e 0a 2a 2f 0a  les on disk..*/.
24c10 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  int sqlite3_stmt
24c20 5f 72 65 61 64 6f 6e 6c 79 28 73 71 6c 69 74 65  _readonly(sqlite
24c30 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
24c40 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
24c50 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 20   Determine If A 
24c60 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65  Prepared Stateme
24c70 6e 74 20 48 61 73 20 42 65 65 6e 20 52 65 73 65  nt Has Been Rese
24c80 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  t.**.** ^The sql
24c90 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 53  ite3_stmt_busy(S
24ca0 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
24cb0 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65  rns true (non-ze
24cc0 72 6f 29 20 69 66 20 74 68 65 0a 2a 2a 20 5b 70  ro) if the.** [p
24cd0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
24ce0 74 5d 20 53 20 68 61 73 20 62 65 65 6e 20 73 74  t] S has been st
24cf0 65 70 70 65 64 20 61 74 20 6c 65 61 73 74 20 6f  epped at least o
24d00 6e 63 65 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73  nce using .** [s
24d10 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20  qlite3_step(S)] 
24d20 62 75 74 20 68 61 73 20 6e 6f 74 20 72 75 6e 20  but has not run 
24d30 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 6e  to completion an
24d40 64 2f 6f 72 20 68 61 73 20 6e 6f 74 20 0a 2a 2a  d/or has not .**
24d50 20 62 65 65 6e 20 72 65 73 65 74 20 75 73 69 6e   been reset usin
24d60 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  g [sqlite3_reset
24d70 28 53 29 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69  (S)].  ^The sqli
24d80 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 53 29  te3_stmt_busy(S)
24d90 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65  .** interface re
24da0 74 75 72 6e 73 20 66 61 6c 73 65 20 69 66 20 53  turns false if S
24db0 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
24dc0 65 72 2e 20 20 49 66 20 53 20 69 73 20 6e 6f 74  er.  If S is not
24dd0 20 61 20 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e   a .** NULL poin
24de0 74 65 72 20 61 6e 64 20 69 73 20 6e 6f 74 20 61  ter and is not a
24df0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 76 61   pointer to a va
24e00 6c 69 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  lid [prepared st
24e10 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65  atement].** obje
24e20 63 74 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68  ct, then the beh
24e30 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e  avior is undefin
24e40 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20  ed and probably 
24e50 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2a 0a  undesirable..**.
24e60 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63  ** This interfac
24e70 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e  e can be used in
24e80 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 5b 73 71   combination [sq
24e90 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28  lite3_next_stmt(
24ea0 29 5d 0a 2a 2a 20 74 6f 20 6c 6f 63 61 74 65 20  )].** to locate 
24eb0 61 6c 6c 20 70 72 65 70 61 72 65 64 20 73 74 61  all prepared sta
24ec0 74 65 6d 65 6e 74 73 20 61 73 73 6f 63 69 61 74  tements associat
24ed0 65 64 20 77 69 74 68 20 61 20 64 61 74 61 62 61  ed with a databa
24ee0 73 65 20 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  se .** connectio
24ef0 6e 20 74 68 61 74 20 61 72 65 20 69 6e 20 6e 65  n that are in ne
24f00 65 64 20 6f 66 20 62 65 69 6e 67 20 72 65 73 65  ed of being rese
24f10 74 2e 20 20 54 68 69 73 20 63 61 6e 20 62 65 20  t.  This can be 
24f20 75 73 65 64 2c 0a 2a 2a 20 66 6f 72 20 65 78 61  used,.** for exa
24f30 6d 70 6c 65 2c 20 69 6e 20 64 69 61 67 6e 6f 73  mple, in diagnos
24f40 74 69 63 20 72 6f 75 74 69 6e 65 73 20 74 6f 20  tic routines to 
24f50 73 65 61 72 63 68 20 66 6f 72 20 70 72 65 70 61  search for prepa
24f60 72 65 64 20 0a 2a 2a 20 73 74 61 74 65 6d 65 6e  red .** statemen
24f70 74 73 20 74 68 61 74 20 61 72 65 20 68 6f 6c 64  ts that are hold
24f80 69 6e 67 20 61 20 74 72 61 6e 73 61 63 74 69 6f  ing a transactio
24f90 6e 20 6f 70 65 6e 2e 0a 2a 2f 0a 69 6e 74 20 73  n open..*/.int s
24fa0 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79  qlite3_stmt_busy
24fb0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b  (sqlite3_stmt*);
24fc0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
24fd0 3a 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54 79  : Dynamically Ty
24fe0 70 65 64 20 56 61 6c 75 65 20 4f 62 6a 65 63 74  ped Value Object
24ff0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70  .** KEYWORDS: {p
25000 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
25010 5f 76 61 6c 75 65 7d 20 7b 75 6e 70 72 6f 74 65  _value} {unprote
25020 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
25030 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  ue}.**.** SQLite
25040 20 75 73 65 73 20 74 68 65 20 73 71 6c 69 74 65   uses the sqlite
25050 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 74  3_value object t
25060 6f 20 72 65 70 72 65 73 65 6e 74 20 61 6c 6c 20  o represent all 
25070 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 63  values.** that c
25080 61 6e 20 62 65 20 73 74 6f 72 65 64 20 69 6e 20  an be stored in 
25090 61 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65  a database table
250a0 2e 20 53 51 4c 69 74 65 20 75 73 65 73 20 64 79  . SQLite uses dy
250b0 6e 61 6d 69 63 20 74 79 70 69 6e 67 0a 2a 2a 20  namic typing.** 
250c0 66 6f 72 20 74 68 65 20 76 61 6c 75 65 73 20 69  for the values i
250d0 74 20 73 74 6f 72 65 73 2e 20 20 5e 56 61 6c 75  t stores.  ^Valu
250e0 65 73 20 73 74 6f 72 65 64 20 69 6e 20 73 71 6c  es stored in sql
250f0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
25100 74 73 0a 2a 2a 20 63 61 6e 20 62 65 20 69 6e 74  ts.** can be int
25110 65 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67 20  egers, floating 
25120 70 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20 73 74  point values, st
25130 72 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f 72  rings, BLOBs, or
25140 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20   NULL..**.** An 
25150 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
25160 6a 65 63 74 20 6d 61 79 20 62 65 20 65 69 74 68  ject may be eith
25170 65 72 20 22 70 72 6f 74 65 63 74 65 64 22 20 6f  er "protected" o
25180 72 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 2e  r "unprotected".
25190 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74 65 72 66 61  .** Some interfa
251a0 63 65 73 20 72 65 71 75 69 72 65 20 61 20 70 72  ces require a pr
251b0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
251c0 76 61 6c 75 65 2e 20 20 4f 74 68 65 72 20 69 6e  value.  Other in
251d0 74 65 72 66 61 63 65 73 0a 2a 2a 20 77 69 6c 6c  terfaces.** will
251e0 20 61 63 63 65 70 74 20 65 69 74 68 65 72 20 61   accept either a
251f0 20 70 72 6f 74 65 63 74 65 64 20 6f 72 20 61 6e   protected or an
25200 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c   unprotected sql
25210 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45  ite3_value..** E
25220 76 65 72 79 20 69 6e 74 65 72 66 61 63 65 20 74  very interface t
25230 68 61 74 20 61 63 63 65 70 74 73 20 73 71 6c 69  hat accepts sqli
25240 74 65 33 5f 76 61 6c 75 65 20 61 72 67 75 6d 65  te3_value argume
25250 6e 74 73 20 73 70 65 63 69 66 69 65 73 0a 2a 2a  nts specifies.**
25260 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
25270 69 74 20 72 65 71 75 69 72 65 73 20 61 20 70 72  it requires a pr
25280 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
25290 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  value..**.** The
252a0 20 74 65 72 6d 73 20 22 70 72 6f 74 65 63 74 65   terms "protecte
252b0 64 22 20 61 6e 64 20 22 75 6e 70 72 6f 74 65 63  d" and "unprotec
252c0 74 65 64 22 20 72 65 66 65 72 20 74 6f 20 77 68  ted" refer to wh
252d0 65 74 68 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20  ether or not.** 
252e0 61 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 2e  a mutex is held.
252f0 20 20 41 6e 20 69 6e 74 65 72 6e 61 6c 20 6d 75    An internal mu
25300 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20  tex is held for 
25310 61 20 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73  a protected.** s
25320 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
25330 65 63 74 20 62 75 74 20 6e 6f 20 6d 75 74 65 78  ect but no mutex
25340 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61 6e 20   is held for an 
25350 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73  unprotected.** s
25360 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
25370 65 63 74 2e 20 20 49 66 20 53 51 4c 69 74 65 20  ect.  If SQLite 
25380 69 73 20 63 6f 6d 70 69 6c 65 64 20 74 6f 20 62  is compiled to b
25390 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 65  e single-threade
253a0 64 0a 2a 2a 20 28 77 69 74 68 20 5b 53 51 4c 49  d.** (with [SQLI
253b0 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d  TE_THREADSAFE=0]
253c0 20 61 6e 64 20 77 69 74 68 20 5b 73 71 6c 69 74   and with [sqlit
253d0 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 5d  e3_threadsafe()]
253e0 20 72 65 74 75 72 6e 69 6e 67 20 30 29 0a 2a 2a   returning 0).**
253f0 20 6f 72 20 69 66 20 53 51 4c 69 74 65 20 69 73   or if SQLite is
25400 20 72 75 6e 20 69 6e 20 6f 6e 65 20 6f 66 20 72   run in one of r
25410 65 64 75 63 65 64 20 6d 75 74 65 78 20 6d 6f 64  educed mutex mod
25420 65 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43  es .** [SQLITE_C
25430 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
25440 41 44 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43  AD] or [SQLITE_C
25450 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41  ONFIG_MULTITHREA
25460 44 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 72 65  D].** then there
25470 20 69 73 20 6e 6f 20 64 69 73 74 69 6e 63 74 69   is no distincti
25480 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65  on between prote
25490 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65  cted and unprote
254a0 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  cted.** sqlite3_
254b0 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 61 6e  value objects an
254c0 64 20 74 68 65 79 20 63 61 6e 20 62 65 20 75 73  d they can be us
254d0 65 64 20 69 6e 74 65 72 63 68 61 6e 67 65 61 62  ed interchangeab
254e0 6c 79 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a  ly.  However,.**
254f0 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 63 6f 64   for maximum cod
25500 65 20 70 6f 72 74 61 62 69 6c 69 74 79 20 69 74  e portability it
25510 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20   is recommended 
25520 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e  that application
25530 73 0a 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b 65 20  s.** still make 
25540 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 20  the distinction 
25550 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65  between protecte
25560 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65  d and unprotecte
25570 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c  d.** sqlite3_val
25580 75 65 20 6f 62 6a 65 63 74 73 20 65 76 65 6e 20  ue objects even 
25590 77 68 65 6e 20 6e 6f 74 20 73 74 72 69 63 74 6c  when not strictl
255a0 79 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a  y required..**.*
255b0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76  * ^The sqlite3_v
255c0 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 74 68 61  alue objects tha
255d0 74 20 61 72 65 20 70 61 73 73 65 64 20 61 73 20  t are passed as 
255e0 70 61 72 61 6d 65 74 65 72 73 20 69 6e 74 6f 20  parameters into 
255f0 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  the.** implement
25600 61 74 69 6f 6e 20 6f 66 20 5b 61 70 70 6c 69 63  ation of [applic
25610 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
25620 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 61 72 65  L functions] are
25630 20 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 5e   protected..** ^
25640 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  The sqlite3_valu
25650 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65  e object returne
25660 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  d by.** [sqlite3
25670 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d  _column_value()]
25680 20 69 73 20 75 6e 70 72 6f 74 65 63 74 65 64 2e   is unprotected.
25690 0a 2a 2a 20 55 6e 70 72 6f 74 65 63 74 65 64 20  .** Unprotected 
256a0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
256b0 6a 65 63 74 73 20 6d 61 79 20 6f 6e 6c 79 20 62  jects may only b
256c0 65 20 75 73 65 64 20 77 69 74 68 0a 2a 2a 20 5b  e used with.** [
256d0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
256e0 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  alue()] and [sql
256f0 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28  ite3_bind_value(
25700 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69  )]..** The [sqli
25710 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 20 7c  te3_value_blob |
25720 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
25730 79 70 65 28 29 5d 20 66 61 6d 69 6c 79 20 6f 66  ype()] family of
25740 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 72  .** interfaces r
25750 65 71 75 69 72 65 20 70 72 6f 74 65 63 74 65 64  equire protected
25760 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
25770 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74 79 70 65 64  bjects..*/.typed
25780 65 66 20 73 74 72 75 63 74 20 4d 65 6d 20 73 71  ef struct Mem sq
25790 6c 69 74 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a  lite3_value;../*
257a0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51  .** CAPI3REF: SQ
257b0 4c 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65  L Function Conte
257c0 78 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20  xt Object.**.** 
257d0 54 68 65 20 63 6f 6e 74 65 78 74 20 69 6e 20 77  The context in w
257e0 68 69 63 68 20 61 6e 20 53 51 4c 20 66 75 6e 63  hich an SQL func
257f0 74 69 6f 6e 20 65 78 65 63 75 74 65 73 20 69 73  tion executes is
25800 20 73 74 6f 72 65 64 20 69 6e 20 61 6e 0a 2a 2a   stored in an.**
25810 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
25820 20 6f 62 6a 65 63 74 2e 20 20 5e 41 20 70 6f 69   object.  ^A poi
25830 6e 74 65 72 20 74 6f 20 61 6e 20 73 71 6c 69 74  nter to an sqlit
25840 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63  e3_context objec
25850 74 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 66  t.** is always f
25860 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
25870 6f 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  o [application-d
25880 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
25890 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 70  ions]..** The ap
258a0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
258b0 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69  d SQL function i
258c0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69  mplementation wi
258d0 6c 6c 20 70 61 73 73 20 74 68 69 73 0a 2a 2a 20  ll pass this.** 
258e0 70 6f 69 6e 74 65 72 20 74 68 72 6f 75 67 68 20  pointer through 
258f0 69 6e 74 6f 20 63 61 6c 6c 73 20 74 6f 20 5b 73  into calls to [s
25900 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e  qlite3_result_in
25910 74 20 7c 20 73 71 6c 69 74 65 33 5f 72 65 73 75  t | sqlite3_resu
25920 6c 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  lt()],.** [sqlit
25930 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
25940 74 65 78 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65  text()], [sqlite
25950 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2c 0a  3_user_data()],.
25960 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ** [sqlite3_cont
25970 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 5d  ext_db_handle()]
25980 2c 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  , [sqlite3_get_a
25990 75 78 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e  uxdata()],.** an
259a0 64 2f 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 65  d/or [sqlite3_se
259b0 74 5f 61 75 78 64 61 74 61 28 29 5d 2e 0a 2a 2f  t_auxdata()]..*/
259c0 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
259d0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20  sqlite3_context 
259e0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 3b  sqlite3_context;
259f0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
25a00 3a 20 42 69 6e 64 69 6e 67 20 56 61 6c 75 65 73  : Binding Values
25a10 20 54 6f 20 50 72 65 70 61 72 65 64 20 53 74 61   To Prepared Sta
25a20 74 65 6d 65 6e 74 73 0a 2a 2a 20 4b 45 59 57 4f  tements.** KEYWO
25a30 52 44 53 3a 20 7b 68 6f 73 74 20 70 61 72 61 6d  RDS: {host param
25a40 65 74 65 72 7d 20 7b 68 6f 73 74 20 70 61 72 61  eter} {host para
25a50 6d 65 74 65 72 73 7d 20 7b 68 6f 73 74 20 70 61  meters} {host pa
25a60 72 61 6d 65 74 65 72 20 6e 61 6d 65 7d 0a 2a 2a  rameter name}.**
25a70 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20   KEYWORDS: {SQL 
25a80 70 61 72 61 6d 65 74 65 72 7d 20 7b 53 51 4c 20  parameter} {SQL 
25a90 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 70 61 72  parameters} {par
25aa0 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 7d 0a  ameter binding}.
25ab0 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 65 20 53  **.** ^(In the S
25ac0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78  QL statement tex
25ad0 74 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69  t input to [sqli
25ae0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
25af0 5d 20 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e  ] and its varian
25b00 74 73 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c 73 20  ts,.** literals 
25b10 6d 61 79 20 62 65 20 72 65 70 6c 61 63 65 64 20  may be replaced 
25b20 62 79 20 61 20 5b 70 61 72 61 6d 65 74 65 72 5d  by a [parameter]
25b30 20 74 68 61 74 20 6d 61 74 63 68 65 73 20 6f 6e   that matches on
25b40 65 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a  e of following.*
25b50 2a 20 74 65 6d 70 6c 61 74 65 73 3a 0a 2a 2a 0a  * templates:.**.
25b60 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
25b70 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e   ?.** <li>  ?NNN
25b80 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a  .** <li>  :VVV.*
25b90 2a 20 3c 6c 69 3e 20 20 40 56 56 56 0a 2a 2a 20  * <li>  @VVV.** 
25ba0 3c 6c 69 3e 20 20 24 56 56 56 0a 2a 2a 20 3c 2f  <li>  $VVV.** </
25bb0 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65  ul>.**.** In the
25bc0 20 74 65 6d 70 6c 61 74 65 73 20 61 62 6f 76 65   templates above
25bd0 2c 20 4e 4e 4e 20 72 65 70 72 65 73 65 6e 74 73  , NNN represents
25be0 20 61 6e 20 69 6e 74 65 67 65 72 20 6c 69 74 65   an integer lite
25bf0 72 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56 56 20  ral,.** and VVV 
25c00 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 61 6c  represents an al
25c10 70 68 61 6e 75 6d 65 72 69 63 20 69 64 65 6e 74  phanumeric ident
25c20 69 66 69 65 72 2e 29 5e 20 20 5e 54 68 65 20 76  ifier.)^  ^The v
25c30 61 6c 75 65 73 20 6f 66 20 74 68 65 73 65 0a 2a  alues of these.*
25c40 2a 20 70 61 72 61 6d 65 74 65 72 73 20 28 61 6c  * parameters (al
25c50 73 6f 20 63 61 6c 6c 65 64 20 22 68 6f 73 74 20  so called "host 
25c60 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 73 22  parameter names"
25c70 20 6f 72 20 22 53 51 4c 20 70 61 72 61 6d 65 74   or "SQL paramet
25c80 65 72 73 22 29 0a 2a 2a 20 63 61 6e 20 62 65 20  ers").** can be 
25c90 73 65 74 20 75 73 69 6e 67 20 74 68 65 20 73 71  set using the sq
25ca0 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72  lite3_bind_*() r
25cb0 6f 75 74 69 6e 65 73 20 64 65 66 69 6e 65 64 20  outines defined 
25cc0 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  here..**.** ^The
25cd0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
25ce0 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62  to the sqlite3_b
25cf0 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73  ind_*() routines
25d00 20 69 73 20 61 6c 77 61 79 73 0a 2a 2a 20 61 20   is always.** a 
25d10 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b  pointer to the [
25d20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62  sqlite3_stmt] ob
25d30 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 66 72  ject returned fr
25d40 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  om.** [sqlite3_p
25d50 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
25d60 69 74 73 20 76 61 72 69 61 6e 74 73 2e 0a 2a 2a  its variants..**
25d70 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  .** ^The second 
25d80 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20  argument is the 
25d90 69 6e 64 65 78 20 6f 66 20 74 68 65 20 53 51 4c  index of the SQL
25da0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62 65   parameter to be
25db0 20 73 65 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65   set..** ^The le
25dc0 66 74 6d 6f 73 74 20 53 51 4c 20 70 61 72 61 6d  ftmost SQL param
25dd0 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65  eter has an inde
25de0 78 20 6f 66 20 31 2e 20 20 5e 57 68 65 6e 20 74  x of 1.  ^When t
25df0 68 65 20 73 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a  he same named.**
25e00 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69   SQL parameter i
25e10 73 20 75 73 65 64 20 6d 6f 72 65 20 74 68 61 6e  s used more than
25e20 20 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 20 61 6e   once, second an
25e30 64 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20  d subsequent.** 
25e40 6f 63 63 75 72 72 65 6e 63 65 73 20 68 61 76 65  occurrences have
25e50 20 74 68 65 20 73 61 6d 65 20 69 6e 64 65 78 20   the same index 
25e60 61 73 20 74 68 65 20 66 69 72 73 74 20 6f 63 63  as the first occ
25e70 75 72 72 65 6e 63 65 2e 0a 2a 2a 20 5e 54 68 65  urrence..** ^The
25e80 20 69 6e 64 65 78 20 66 6f 72 20 6e 61 6d 65 64   index for named
25e90 20 70 61 72 61 6d 65 74 65 72 73 20 63 61 6e 20   parameters can 
25ea0 62 65 20 6c 6f 6f 6b 65 64 20 75 70 20 75 73 69  be looked up usi
25eb0 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ng the.** [sqlit
25ec0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
25ed0 72 5f 69 6e 64 65 78 28 29 5d 20 41 50 49 20 69  r_index()] API i
25ee0 66 20 64 65 73 69 72 65 64 2e 20 20 5e 54 68 65  f desired.  ^The
25ef0 20 69 6e 64 65 78 0a 2a 2a 20 66 6f 72 20 22 3f   index.** for "?
25f00 4e 4e 4e 22 20 70 61 72 61 6d 65 74 65 72 73 20  NNN" parameters 
25f10 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  is the value of 
25f20 4e 4e 4e 2e 0a 2a 2a 20 5e 54 68 65 20 4e 4e 4e  NNN..** ^The NNN
25f30 20 76 61 6c 75 65 20 6d 75 73 74 20 62 65 20 62   value must be b
25f40 65 74 77 65 65 6e 20 31 20 61 6e 64 20 74 68 65  etween 1 and the
25f50 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28   [sqlite3_limit(
25f60 29 5d 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  )].** parameter 
25f70 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41  [SQLITE_LIMIT_VA
25f80 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 20 28  RIABLE_NUMBER] (
25f90 64 65 66 61 75 6c 74 20 76 61 6c 75 65 3a 20 39  default value: 9
25fa0 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  99)..**.** ^The 
25fb0 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69  third argument i
25fc0 73 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 62  s the value to b
25fd0 69 6e 64 20 74 6f 20 74 68 65 20 70 61 72 61 6d  ind to the param
25fe0 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e  eter..**.** ^(In
25ff0 20 74 68 6f 73 65 20 72 6f 75 74 69 6e 65 73 20   those routines 
26000 74 68 61 74 20 68 61 76 65 20 61 20 66 6f 75 72  that have a four
26010 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 69 74 73  th argument, its
26020 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a   value is the.**
26030 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
26040 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65   in the paramete
26050 72 2e 20 20 54 6f 20 62 65 20 63 6c 65 61 72 3a  r.  To be clear:
26060 20 74 68 65 20 76 61 6c 75 65 20 69 73 20 74 68   the value is th
26070 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 3c  e.** number of <
26080 75 3e 62 79 74 65 73 3c 2f 75 3e 20 69 6e 20 74  u>bytes</u> in t
26090 68 65 20 76 61 6c 75 65 2c 20 6e 6f 74 20 74 68  he value, not th
260a0 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72  e number of char
260b0 61 63 74 65 72 73 2e 29 5e 0a 2a 2a 20 5e 49 66  acters.)^.** ^If
260c0 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
260d0 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
260e0 5f 62 69 6e 64 5f 74 65 78 74 28 29 20 6f 72 20  _bind_text() or 
260f0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
26100 74 31 36 28 29 0a 2a 2a 20 69 73 20 6e 65 67 61  t16().** is nega
26110 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65 20 6c  tive, then the l
26120 65 6e 67 74 68 20 6f 66 20 74 68 65 20 73 74 72  ength of the str
26130 69 6e 67 20 69 73 0a 2a 2a 20 74 68 65 20 6e 75  ing is.** the nu
26140 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 75 70  mber of bytes up
26150 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65   to the first ze
26160 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a  ro terminator..*
26170 2a 20 49 66 20 74 68 65 20 66 6f 75 72 74 68 20  * If the fourth 
26180 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
26190 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29  ite3_bind_blob()
261a0 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68   is negative, th
261b0 65 6e 0a 2a 2a 20 74 68 65 20 62 65 68 61 76 69  en.** the behavi
261c0 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  or is undefined.
261d0 0a 2a 2a 20 49 66 20 61 20 6e 6f 6e 2d 6e 65 67  .** If a non-neg
261e0 61 74 69 76 65 20 66 6f 75 72 74 68 20 70 61 72  ative fourth par
261f0 61 6d 65 74 65 72 20 69 73 20 70 72 6f 76 69 64  ameter is provid
26200 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69  ed to sqlite3_bi
26210 6e 64 5f 74 65 78 74 28 29 0a 2a 2a 20 6f 72 20  nd_text().** or 
26220 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
26230 74 31 36 28 29 20 74 68 65 6e 20 74 68 61 74 20  t16() then that 
26240 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74 20 62  parameter must b
26250 65 20 74 68 65 20 62 79 74 65 20 6f 66 66 73 65  e the byte offse
26260 74 0a 2a 2a 20 77 68 65 72 65 20 74 68 65 20 4e  t.** where the N
26270 55 4c 20 74 65 72 6d 69 6e 61 74 6f 72 20 77 6f  UL terminator wo
26280 75 6c 64 20 6f 63 63 75 72 20 61 73 73 75 6d 69  uld occur assumi
26290 6e 67 20 74 68 65 20 73 74 72 69 6e 67 20 77 65  ng the string we
262a0 72 65 20 4e 55 4c 0a 2a 2a 20 74 65 72 6d 69 6e  re NUL.** termin
262b0 61 74 65 64 2e 20 20 49 66 20 61 6e 79 20 4e 55  ated.  If any NU
262c0 4c 20 63 68 61 72 61 63 74 65 72 73 20 6f 63 63  L characters occ
262d0 75 72 20 61 74 20 62 79 74 65 20 6f 66 66 73 65  ur at byte offse
262e0 74 73 20 6c 65 73 73 20 74 68 61 6e 20 0a 2a 2a  ts less than .**
262f0 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68   the value of th
26300 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
26310 65 72 20 74 68 65 6e 20 74 68 65 20 72 65 73 75  er then the resu
26320 6c 74 69 6e 67 20 73 74 72 69 6e 67 20 76 61 6c  lting string val
26330 75 65 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 74 61  ue will.** conta
26340 69 6e 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73  in embedded NULs
26350 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20 6f 66  .  The result of
26360 20 65 78 70 72 65 73 73 69 6f 6e 73 20 69 6e 76   expressions inv
26370 6f 6c 76 69 6e 67 20 73 74 72 69 6e 67 73 0a 2a  olving strings.*
26380 2a 20 77 69 74 68 20 65 6d 62 65 64 64 65 64 20  * with embedded 
26390 4e 55 4c 73 20 69 73 20 75 6e 64 65 66 69 6e 65  NULs is undefine
263a0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  d..**.** ^The fi
263b0 66 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  fth argument to 
263c0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
263d0 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 62 69 6e  b(), sqlite3_bin
263e0 64 5f 74 65 78 74 28 29 2c 20 61 6e 64 0a 2a 2a  d_text(), and.**
263f0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
26400 78 74 31 36 28 29 20 69 73 20 61 20 64 65 73 74  xt16() is a dest
26410 72 75 63 74 6f 72 20 75 73 65 64 20 74 6f 20 64  ructor used to d
26420 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c  ispose of the BL
26430 4f 42 20 6f 72 0a 2a 2a 20 73 74 72 69 6e 67 20  OB or.** string 
26440 61 66 74 65 72 20 53 51 4c 69 74 65 20 68 61 73  after SQLite has
26450 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 69   finished with i
26460 74 2e 20 20 5e 54 68 65 20 64 65 73 74 72 75 63  t.  ^The destruc
26470 74 6f 72 20 69 73 20 63 61 6c 6c 65 64 0a 2a 2a  tor is called.**
26480 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74   to dispose of t
26490 68 65 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e  he BLOB or strin
264a0 67 20 65 76 65 6e 20 69 66 20 74 68 65 20 63 61  g even if the ca
264b0 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69  ll to sqlite3_bi
264c0 6e 64 5f 62 6c 6f 62 28 29 2c 0a 2a 2a 20 73 71  nd_blob(),.** sq
264d0 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28  lite3_bind_text(
264e0 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69  ), or sqlite3_bi
264f0 6e 64 5f 74 65 78 74 31 36 28 29 20 66 61 69 6c  nd_text16() fail
26500 73 2e 20 20 0a 2a 2a 20 5e 49 66 20 74 68 65 20  s.  .** ^If the 
26510 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 69  fifth argument i
26520 73 0a 2a 2a 20 74 68 65 20 73 70 65 63 69 61 6c  s.** the special
26530 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 53   value [SQLITE_S
26540 54 41 54 49 43 5d 2c 20 74 68 65 6e 20 53 51 4c  TATIC], then SQL
26550 69 74 65 20 61 73 73 75 6d 65 73 20 74 68 61 74  ite assumes that
26560 20 74 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74   the.** informat
26570 69 6f 6e 20 69 73 20 69 6e 20 73 74 61 74 69 63  ion is in static
26580 2c 20 75 6e 6d 61 6e 61 67 65 64 20 73 70 61 63  , unmanaged spac
26590 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 6e  e and does not n
265a0 65 65 64 20 74 6f 20 62 65 20 66 72 65 65 64 2e  eed to be freed.
265b0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 66 74  .** ^If the fift
265c0 68 20 61 72 67 75 6d 65 6e 74 20 68 61 73 20 74  h argument has t
265d0 68 65 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45  he value [SQLITE
265e0 5f 54 52 41 4e 53 49 45 4e 54 5d 2c 20 74 68 65  _TRANSIENT], the
265f0 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65  n.** SQLite make
26600 73 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74  s its own privat
26610 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 64 61  e copy of the da
26620 74 61 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20  ta immediately, 
26630 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 20 73 71  before.** the sq
26640 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72  lite3_bind_*() r
26650 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 2e 0a  outine returns..
26660 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
26670 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62  e3_bind_zeroblob
26680 28 29 20 72 6f 75 74 69 6e 65 20 62 69 6e 64 73  () routine binds
26690 20 61 20 42 4c 4f 42 20 6f 66 20 6c 65 6e 67 74   a BLOB of lengt
266a0 68 20 4e 20 74 68 61 74 0a 2a 2a 20 69 73 20 66  h N that.** is f
266b0 69 6c 6c 65 64 20 77 69 74 68 20 7a 65 72 6f 65  illed with zeroe
266c0 73 2e 20 20 5e 41 20 7a 65 72 6f 62 6c 6f 62 20  s.  ^A zeroblob 
266d0 75 73 65 73 20 61 20 66 69 78 65 64 20 61 6d 6f  uses a fixed amo
266e0 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a  unt of memory.**
266f0 20 28 6a 75 73 74 20 61 6e 20 69 6e 74 65 67 65   (just an intege
26700 72 20 74 6f 20 68 6f 6c 64 20 69 74 73 20 73 69  r to hold its si
26710 7a 65 29 20 77 68 69 6c 65 20 69 74 20 69 73 20  ze) while it is 
26720 62 65 69 6e 67 20 70 72 6f 63 65 73 73 65 64 2e  being processed.
26730 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73 20 61 72  .** Zeroblobs ar
26740 65 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 73 65  e intended to se
26750 72 76 65 20 61 73 20 70 6c 61 63 65 68 6f 6c 64  rve as placehold
26760 65 72 73 20 66 6f 72 20 42 4c 4f 42 73 20 77 68  ers for BLOBs wh
26770 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 69  ose.** content i
26780 73 20 6c 61 74 65 72 20 77 72 69 74 74 65 6e 20  s later written 
26790 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  using.** [sqlite
267a0 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e  3_blob_open | in
267b0 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20 49  cremental BLOB I
267c0 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a  /O] routines..**
267d0 20 5e 41 20 6e 65 67 61 74 69 76 65 20 76 61 6c   ^A negative val
267e0 75 65 20 66 6f 72 20 74 68 65 20 7a 65 72 6f 62  ue for the zerob
267f0 6c 6f 62 20 72 65 73 75 6c 74 73 20 69 6e 20 61  lob results in a
26800 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f   zero-length BLO
26810 42 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 79  B..**.** ^If any
26820 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f   of the sqlite3_
26830 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65  bind_*() routine
26840 73 20 61 72 65 20 63 61 6c 6c 65 64 20 77 69 74  s are called wit
26850 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  h a NULL pointer
26860 0a 2a 2a 20 66 6f 72 20 74 68 65 20 5b 70 72 65  .** for the [pre
26870 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
26880 20 6f 72 20 77 69 74 68 20 61 20 70 72 65 70 61   or with a prepa
26890 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 66 6f  red statement fo
268a0 72 20 77 68 69 63 68 0a 2a 2a 20 5b 73 71 6c 69  r which.** [sqli
268b0 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20  te3_step()] has 
268c0 62 65 65 6e 20 63 61 6c 6c 65 64 20 6d 6f 72 65  been called more
268d0 20 72 65 63 65 6e 74 6c 79 20 74 68 61 6e 20 5b   recently than [
268e0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
268f0 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 61  ,.** then the ca
26900 6c 6c 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b  ll will return [
26910 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20  SQLITE_MISUSE]. 
26920 20 49 66 20 61 6e 79 20 73 71 6c 69 74 65 33 5f   If any sqlite3_
26930 62 69 6e 64 5f 28 29 0a 2a 2a 20 72 6f 75 74 69  bind_().** routi
26940 6e 65 20 69 73 20 70 61 73 73 65 64 20 61 20 5b  ne is passed a [
26950 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
26960 6e 74 5d 20 74 68 61 74 20 68 61 73 20 62 65 65  nt] that has bee
26970 6e 20 66 69 6e 61 6c 69 7a 65 64 2c 20 74 68 65  n finalized, the
26980 0a 2a 2a 20 72 65 73 75 6c 74 20 69 73 20 75 6e  .** result is un
26990 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62  defined and prob
269a0 61 62 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a  ably harmful..**
269b0 0a 2a 2a 20 5e 42 69 6e 64 69 6e 67 73 20 61 72  .** ^Bindings ar
269c0 65 20 6e 6f 74 20 63 6c 65 61 72 65 64 20 62 79  e not cleared by
269d0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65   the [sqlite3_re
269e0 73 65 74 28 29 5d 20 72 6f 75 74 69 6e 65 2e 0a  set()] routine..
269f0 2a 2a 20 5e 55 6e 62 6f 75 6e 64 20 70 61 72 61  ** ^Unbound para
26a00 6d 65 74 65 72 73 20 61 72 65 20 69 6e 74 65 72  meters are inter
26a10 70 72 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e 0a  preted as NULL..
26a20 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
26a30 65 33 5f 62 69 6e 64 5f 2a 20 72 6f 75 74 69 6e  e3_bind_* routin
26a40 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  es return [SQLIT
26a50 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73  E_OK] on success
26a60 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72   or an.** [error
26a70 20 63 6f 64 65 5d 20 69 66 20 61 6e 79 74 68 69   code] if anythi
26a80 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a  ng goes wrong..*
26a90 2a 20 5e 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45  * ^[SQLITE_RANGE
26aa0 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66  ] is returned if
26ab0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a   the parameter.*
26ac0 2a 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f  * index is out o
26ad0 66 20 72 61 6e 67 65 2e 20 20 5e 5b 53 51 4c 49  f range.  ^[SQLI
26ae0 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72 65 74  TE_NOMEM] is ret
26af0 75 72 6e 65 64 20 69 66 20 6d 61 6c 6c 6f 63 28  urned if malloc(
26b00 29 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 53  ) fails..**.** S
26b10 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
26b20 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
26b30 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73  _count()],.** [s
26b40 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
26b50 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61  meter_name()], a
26b60 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  nd [sqlite3_bind
26b70 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
26b80 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ()]..*/.int sqli
26b90 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 73 71  te3_bind_blob(sq
26ba0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
26bb0 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
26bc0 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f  nt n, void(*)(vo
26bd0 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74  id*));.int sqlit
26be0 65 33 5f 62 69 6e 64 5f 64 6f 75 62 6c 65 28 73  e3_bind_double(s
26bf0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
26c00 74 2c 20 64 6f 75 62 6c 65 29 3b 0a 69 6e 74 20  t, double);.int 
26c10 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74  sqlite3_bind_int
26c20 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
26c30 69 6e 74 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73  int, int);.int s
26c40 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 36  qlite3_bind_int6
26c50 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  4(sqlite3_stmt*,
26c60 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e   int, sqlite3_in
26c70 74 36 34 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  t64);.int sqlite
26c80 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73 71 6c 69  3_bind_null(sqli
26c90 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b  te3_stmt*, int);
26ca0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
26cb0 64 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73  d_text(sqlite3_s
26cc0 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74  tmt*, int, const
26cd0 20 63 68 61 72 2a 2c 20 69 6e 74 20 6e 2c 20 76   char*, int n, v
26ce0 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
26cf0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
26d00 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f  _text16(sqlite3_
26d10 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73  stmt*, int, cons
26d20 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f  t void*, int, vo
26d30 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69  id(*)(void*));.i
26d40 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
26d50 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74  value(sqlite3_st
26d60 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20  mt*, int, const 
26d70 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
26d80 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
26d90 64 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74  d_zeroblob(sqlit
26da0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69  e3_stmt*, int, i
26db0 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  nt n);../*.** CA
26dc0 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f  PI3REF: Number O
26dd0 66 20 53 51 4c 20 50 61 72 61 6d 65 74 65 72 73  f SQL Parameters
26de0 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75  .**.** ^This rou
26df0 74 69 6e 65 20 63 61 6e 20 62 65 20 75 73 65 64  tine can be used
26e00 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d   to find the num
26e10 62 65 72 20 6f 66 20 5b 53 51 4c 20 70 61 72 61  ber of [SQL para
26e20 6d 65 74 65 72 73 5d 0a 2a 2a 20 69 6e 20 61 20  meters].** in a 
26e30 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
26e40 65 6e 74 5d 2e 20 20 53 51 4c 20 70 61 72 61 6d  ent].  SQL param
26e50 65 74 65 72 73 20 61 72 65 20 74 6f 6b 65 6e 73  eters are tokens
26e60 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 20   of the.** form 
26e70 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41  "?", "?NNN", ":A
26e80 41 41 22 2c 20 22 24 41 41 41 22 2c 20 6f 72 20  AA", "$AAA", or 
26e90 22 40 41 41 41 22 20 74 68 61 74 20 73 65 72 76  "@AAA" that serv
26ea0 65 20 61 73 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c  e as.** placehol
26eb0 64 65 72 73 20 66 6f 72 20 76 61 6c 75 65 73 20  ders for values 
26ec0 74 68 61 74 20 61 72 65 20 5b 73 71 6c 69 74 65  that are [sqlite
26ed0 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f  3_bind_blob | bo
26ee0 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 70  und].** to the p
26ef0 61 72 61 6d 65 74 65 72 73 20 61 74 20 61 20 6c  arameters at a l
26f00 61 74 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a  ater time..**.**
26f10 20 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65 20   ^(This routine 
26f20 61 63 74 75 61 6c 6c 79 20 72 65 74 75 72 6e 73  actually returns
26f30 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68   the index of th
26f40 65 20 6c 61 72 67 65 73 74 20 28 72 69 67 68 74  e largest (right
26f50 6d 6f 73 74 29 0a 2a 2a 20 70 61 72 61 6d 65 74  most).** paramet
26f60 65 72 2e 20 46 6f 72 20 61 6c 6c 20 66 6f 72 6d  er. For all form
26f70 73 20 65 78 63 65 70 74 20 3f 4e 4e 4e 2c 20 74  s except ?NNN, t
26f80 68 69 73 20 77 69 6c 6c 20 63 6f 72 72 65 73 70  his will corresp
26f90 6f 6e 64 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 75  ond to the.** nu
26fa0 6d 62 65 72 20 6f 66 20 75 6e 69 71 75 65 20 70  mber of unique p
26fb0 61 72 61 6d 65 74 65 72 73 2e 20 20 49 66 20 70  arameters.  If p
26fc0 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65  arameters of the
26fd0 20 3f 4e 4e 4e 20 66 6f 72 6d 20 61 72 65 20 75   ?NNN form are u
26fe0 73 65 64 2c 0a 2a 2a 20 74 68 65 72 65 20 6d 61  sed,.** there ma
26ff0 79 20 62 65 20 67 61 70 73 20 69 6e 20 74 68 65  y be gaps in the
27000 20 6c 69 73 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53   list.)^.**.** S
27010 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
27020 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69  3_bind_blob|sqli
27030 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20  te3_bind()],.** 
27040 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
27050 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c  rameter_name()],
27060 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
27070 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
27080 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74  index()]..*/.int
27090 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61   sqlite3_bind_pa
270a0 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 73 71  rameter_count(sq
270b0 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f  lite3_stmt*);../
270c0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e  *.** CAPI3REF: N
270d0 61 6d 65 20 4f 66 20 41 20 48 6f 73 74 20 50 61  ame Of A Host Pa
270e0 72 61 6d 65 74 65 72 0a 2a 2a 0a 2a 2a 20 5e 54  rameter.**.** ^T
270f0 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
27100 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 50  parameter_name(P
27110 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  ,N) interface re
27120 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 61 6d  turns.** the nam
27130 65 20 6f 66 20 74 68 65 20 4e 2d 74 68 20 5b 53  e of the N-th [S
27140 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e  QL parameter] in
27150 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
27160 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20  tatement] P..** 
27170 5e 28 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73  ^(SQL parameters
27180 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 4e   of the form "?N
27190 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72  NN" or ":AAA" or
271a0 20 22 40 41 41 41 22 20 6f 72 20 22 24 41 41 41   "@AAA" or "$AAA
271b0 22 0a 2a 2a 20 68 61 76 65 20 61 20 6e 61 6d 65  ".** have a name
271c0 20 77 68 69 63 68 20 69 73 20 74 68 65 20 73 74   which is the st
271d0 72 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72 20 22  ring "?NNN" or "
271e0 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41 22 20  :AAA" or "@AAA" 
271f0 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 72 65 73  or "$AAA".** res
27200 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e  pectively..** In
27210 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
27220 65 20 69 6e 69 74 69 61 6c 20 22 3a 22 20 6f 72  e initial ":" or
27230 20 22 24 22 20 6f 72 20 22 40 22 20 6f 72 20 22   "$" or "@" or "
27240 3f 22 0a 2a 2a 20 69 73 20 69 6e 63 6c 75 64 65  ?".** is include
27250 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68 65  d as part of the
27260 20 6e 61 6d 65 2e 29 5e 0a 2a 2a 20 5e 50 61 72   name.)^.** ^Par
27270 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 66  ameters of the f
27280 6f 72 6d 20 22 3f 22 20 77 69 74 68 6f 75 74 20  orm "?" without 
27290 61 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65  a following inte
272a0 67 65 72 20 68 61 76 65 20 6e 6f 20 6e 61 6d 65  ger have no name
272b0 0a 2a 2a 20 61 6e 64 20 61 72 65 20 72 65 66 65  .** and are refe
272c0 72 72 65 64 20 74 6f 20 61 73 20 22 6e 61 6d 65  rred to as "name
272d0 6c 65 73 73 22 20 6f 72 20 22 61 6e 6f 6e 79 6d  less" or "anonym
272e0 6f 75 73 20 70 61 72 61 6d 65 74 65 72 73 22 2e  ous parameters".
272f0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
27300 74 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72  t host parameter
27310 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66   has an index of
27320 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a   1, not 0..**.**
27330 20 5e 49 66 20 74 68 65 20 76 61 6c 75 65 20 4e   ^If the value N
27340 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65   is out of range
27350 20 6f 72 20 69 66 20 74 68 65 20 4e 2d 74 68 20   or if the N-th 
27360 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20  parameter is.** 
27370 6e 61 6d 65 6c 65 73 73 2c 20 74 68 65 6e 20 4e  nameless, then N
27380 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ULL is returned.
27390 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20    ^The returned 
273a0 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 61 6c 77  string is.** alw
273b0 61 79 73 20 69 6e 20 55 54 46 2d 38 20 65 6e 63  ays in UTF-8 enc
273c0 6f 64 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68  oding even if th
273d0 65 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65  e named paramete
273e0 72 20 77 61 73 0a 2a 2a 20 6f 72 69 67 69 6e 61  r was.** origina
273f0 6c 6c 79 20 73 70 65 63 69 66 69 65 64 20 61 73  lly specified as
27400 20 55 54 46 2d 31 36 20 69 6e 20 5b 73 71 6c 69   UTF-16 in [sqli
27410 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
27420 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
27430 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e  prepare16_v2()].
27440 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
27450 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
27460 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64  lob|sqlite3_bind
27470 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
27480 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
27490 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a  count()], and.**
274a0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
274b0 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29  arameter_index()
274c0 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72  ]..*/.const char
274d0 20 2a 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   *sqlite3_bind_p
274e0 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 73 71  arameter_name(sq
274f0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
27500 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
27510 45 46 3a 20 49 6e 64 65 78 20 4f 66 20 41 20 50  EF: Index Of A P
27520 61 72 61 6d 65 74 65 72 20 57 69 74 68 20 41 20  arameter With A 
27530 47 69 76 65 6e 20 4e 61 6d 65 0a 2a 2a 0a 2a 2a  Given Name.**.**
27540 20 5e 52 65 74 75 72 6e 20 74 68 65 20 69 6e 64   ^Return the ind
27550 65 78 20 6f 66 20 61 6e 20 53 51 4c 20 70 61 72  ex of an SQL par
27560 61 6d 65 74 65 72 20 67 69 76 65 6e 20 69 74 73  ameter given its
27570 20 6e 61 6d 65 2e 20 20 5e 54 68 65 0a 2a 2a 20   name.  ^The.** 
27580 69 6e 64 65 78 20 76 61 6c 75 65 20 72 65 74 75  index value retu
27590 72 6e 65 64 20 69 73 20 73 75 69 74 61 62 6c 65  rned is suitable
275a0 20 66 6f 72 20 75 73 65 20 61 73 20 74 68 65 20   for use as the 
275b0 73 65 63 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d 65  second.** parame
275c0 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ter to [sqlite3_
275d0 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65  bind_blob|sqlite
275e0 33 5f 62 69 6e 64 28 29 5d 2e 20 20 5e 41 20 7a  3_bind()].  ^A z
275f0 65 72 6f 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e  ero.** is return
27600 65 64 20 69 66 20 6e 6f 20 6d 61 74 63 68 69 6e  ed if no matchin
27610 67 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 66  g parameter is f
27620 6f 75 6e 64 2e 20 20 5e 54 68 65 20 70 61 72 61  ound.  ^The para
27630 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75  meter.** name mu
27640 73 74 20 62 65 20 67 69 76 65 6e 20 69 6e 20 55  st be given in U
27650 54 46 2d 38 20 65 76 65 6e 20 69 66 20 74 68 65  TF-8 even if the
27660 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d   original statem
27670 65 6e 74 0a 2a 2a 20 77 61 73 20 70 72 65 70 61  ent.** was prepa
27680 72 65 64 20 66 72 6f 6d 20 55 54 46 2d 31 36 20  red from UTF-16 
27690 74 65 78 74 20 75 73 69 6e 67 20 5b 73 71 6c 69  text using [sqli
276a0 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
276b0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ()]..**.** See a
276c0 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69  lso: [sqlite3_bi
276d0 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f  nd_blob|sqlite3_
276e0 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  bind()],.** [sql
276f0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
27700 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e  ter_count()], an
27710 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  d.** [sqlite3_bi
27720 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64  nd_parameter_ind
27730 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ex()]..*/.int sq
27740 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
27750 65 74 65 72 5f 69 6e 64 65 78 28 73 71 6c 69 74  eter_index(sqlit
27760 65 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73 74 20  e3_stmt*, const 
27770 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f  char *zName);../
27780 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
27790 65 73 65 74 20 41 6c 6c 20 42 69 6e 64 69 6e 67  eset All Binding
277a0 73 20 4f 6e 20 41 20 50 72 65 70 61 72 65 64 20  s On A Prepared 
277b0 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20  Statement.**.** 
277c0 5e 43 6f 6e 74 72 61 72 79 20 74 6f 20 74 68 65  ^Contrary to the
277d0 20 69 6e 74 75 69 74 69 6f 6e 20 6f 66 20 6d 61   intuition of ma
277e0 6e 79 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ny, [sqlite3_res
277f0 65 74 28 29 5d 20 64 6f 65 73 20 6e 6f 74 20 72  et()] does not r
27800 65 73 65 74 0a 2a 2a 20 74 68 65 20 5b 73 71 6c  eset.** the [sql
27810 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c  ite3_bind_blob |
27820 20 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 61 20   bindings] on a 
27830 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
27840 65 6e 74 5d 2e 0a 2a 2a 20 5e 55 73 65 20 74 68  ent]..** ^Use th
27850 69 73 20 72 6f 75 74 69 6e 65 20 74 6f 20 72 65  is routine to re
27860 73 65 74 20 61 6c 6c 20 68 6f 73 74 20 70 61 72  set all host par
27870 61 6d 65 74 65 72 73 20 74 6f 20 4e 55 4c 4c 2e  ameters to NULL.
27880 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
27890 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 73  clear_bindings(s
278a0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a  qlite3_stmt*);..
278b0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
278c0 4e 75 6d 62 65 72 20 4f 66 20 43 6f 6c 75 6d 6e  Number Of Column
278d0 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65  s In A Result Se
278e0 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20  t.**.** ^Return 
278f0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  the number of co
27900 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73  lumns in the res
27910 75 6c 74 20 73 65 74 20 72 65 74 75 72 6e 65 64  ult set returned
27920 20 62 79 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70   by the.** [prep
27930 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
27940 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72   ^This routine r
27950 65 74 75 72 6e 73 20 30 20 69 66 20 70 53 74 6d  eturns 0 if pStm
27960 74 20 69 73 20 61 6e 20 53 51 4c 0a 2a 2a 20 73  t is an SQL.** s
27970 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 64 6f  tatement that do
27980 65 73 20 6e 6f 74 20 72 65 74 75 72 6e 20 64 61  es not return da
27990 74 61 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20  ta (for example 
279a0 61 6e 20 5b 55 50 44 41 54 45 5d 29 2e 0a 2a 2a  an [UPDATE])..**
279b0 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
279c0 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e  qlite3_data_coun
279d0 74 28 29 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  t()].*/.int sqli
279e0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74  te3_column_count
279f0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
27a00 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
27a10 50 49 33 52 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e  PI3REF: Column N
27a20 61 6d 65 73 20 49 6e 20 41 20 52 65 73 75 6c 74  ames In A Result
27a30 20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73   Set.**.** ^Thes
27a40 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  e routines retur
27a50 6e 20 74 68 65 20 6e 61 6d 65 20 61 73 73 69 67  n the name assig
27a60 6e 65 64 20 74 6f 20 61 20 70 61 72 74 69 63 75  ned to a particu
27a70 6c 61 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e  lar column.** in
27a80 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
27a90 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74  of a [SELECT] st
27aa0 61 74 65 6d 65 6e 74 2e 20 20 5e 54 68 65 20 73  atement.  ^The s
27ab0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
27ac0 6d 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  me().** interfac
27ad0 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  e returns a poin
27ae0 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65  ter to a zero-te
27af0 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73  rminated UTF-8 s
27b00 74 72 69 6e 67 0a 2a 2a 20 61 6e 64 20 73 71 6c  tring.** and sql
27b10 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
27b20 31 36 28 29 20 72 65 74 75 72 6e 73 20 61 20 70  16() returns a p
27b30 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f  ointer to a zero
27b40 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55  -terminated.** U
27b50 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 5e  TF-16 string.  ^
27b60 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
27b70 74 65 72 20 69 73 20 74 68 65 20 5b 70 72 65 70  ter is the [prep
27b80 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a  ared statement].
27b90 2a 2a 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e  ** that implemen
27ba0 74 73 20 74 68 65 20 5b 53 45 4c 45 43 54 5d 20  ts the [SELECT] 
27bb0 73 74 61 74 65 6d 65 6e 74 2e 20 5e 54 68 65 20  statement. ^The 
27bc0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
27bd0 20 69 73 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d   is the.** colum
27be0 6e 20 6e 75 6d 62 65 72 2e 20 20 5e 54 68 65 20  n number.  ^The 
27bf0 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20  leftmost column 
27c00 69 73 20 6e 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a  is number 0..**.
27c10 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64  ** ^The returned
27c20 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 72 20   string pointer 
27c30 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 65  is valid until e
27c40 69 74 68 65 72 20 74 68 65 20 5b 70 72 65 70 61  ither the [prepa
27c50 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a  red statement].*
27c60 2a 20 69 73 20 64 65 73 74 72 6f 79 65 64 20 62  * is destroyed b
27c70 79 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  y [sqlite3_final
27c80 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20  ize()] or until 
27c90 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
27ca0 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a   automatically.*
27cb0 2a 20 72 65 70 72 65 70 61 72 65 64 20 62 79 20  * reprepared by 
27cc0 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c 20 74  the first call t
27cd0 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  o [sqlite3_step(
27ce0 29 5d 20 66 6f 72 20 61 20 70 61 72 74 69 63 75  )] for a particu
27cf0 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e  lar run.** or un
27d00 74 69 6c 20 74 68 65 20 6e 65 78 74 20 63 61 6c  til the next cal
27d10 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  l to.** sqlite3_
27d20 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 20 6f 72  column_name() or
27d30 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
27d40 6e 61 6d 65 31 36 28 29 20 6f 6e 20 74 68 65 20  name16() on the 
27d50 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a  same column..**.
27d60 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d  ** ^If sqlite3_m
27d70 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 20 64 75  alloc() fails du
27d80 72 69 6e 67 20 74 68 65 20 70 72 6f 63 65 73 73  ring the process
27d90 69 6e 67 20 6f 66 20 65 69 74 68 65 72 20 72 6f  ing of either ro
27da0 75 74 69 6e 65 0a 2a 2a 20 28 66 6f 72 20 65 78  utine.** (for ex
27db0 61 6d 70 6c 65 20 64 75 72 69 6e 67 20 61 20 63  ample during a c
27dc0 6f 6e 76 65 72 73 69 6f 6e 20 66 72 6f 6d 20 55  onversion from U
27dd0 54 46 2d 38 20 74 6f 20 55 54 46 2d 31 36 29 20  TF-8 to UTF-16) 
27de0 74 68 65 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70  then a.** NULL p
27df0 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e  ointer is return
27e00 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e  ed..**.** ^The n
27e10 61 6d 65 20 6f 66 20 61 20 72 65 73 75 6c 74 20  ame of a result 
27e20 63 6f 6c 75 6d 6e 20 69 73 20 74 68 65 20 76 61  column is the va
27e30 6c 75 65 20 6f 66 20 74 68 65 20 22 41 53 22 20  lue of the "AS" 
27e40 63 6c 61 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68  clause for.** th
27e50 61 74 20 63 6f 6c 75 6d 6e 2c 20 69 66 20 74 68  at column, if th
27e60 65 72 65 20 69 73 20 61 6e 20 41 53 20 63 6c 61  ere is an AS cla
27e70 75 73 65 2e 20 20 49 66 20 74 68 65 72 65 20 69  use.  If there i
27e80 73 20 6e 6f 20 41 53 20 63 6c 61 75 73 65 0a 2a  s no AS clause.*
27e90 2a 20 74 68 65 6e 20 74 68 65 20 6e 61 6d 65 20  * then the name 
27ea0 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73  of the column is
27eb0 20 75 6e 73 70 65 63 69 66 69 65 64 20 61 6e 64   unspecified and
27ec0 20 6d 61 79 20 63 68 61 6e 67 65 20 66 72 6f 6d   may change from
27ed0 0a 2a 2a 20 6f 6e 65 20 72 65 6c 65 61 73 65 20  .** one release 
27ee0 6f 66 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65  of SQLite to the
27ef0 20 6e 65 78 74 2e 0a 2a 2f 0a 63 6f 6e 73 74 20   next..*/.const 
27f00 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
27f10 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65  lumn_name(sqlite
27f20 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b  3_stmt*, int N);
27f30 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
27f40 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
27f50 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
27f60 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a  , int N);../*.**
27f70 20 43 41 50 49 33 52 45 46 3a 20 53 6f 75 72 63   CAPI3REF: Sourc
27f80 65 20 4f 66 20 44 61 74 61 20 49 6e 20 41 20 51  e Of Data In A Q
27f90 75 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a  uery Result.**.*
27fa0 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65  * ^These routine
27fb0 73 20 70 72 6f 76 69 64 65 20 61 20 6d 65 61 6e  s provide a mean
27fc0 73 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 74  s to determine t
27fd0 68 65 20 64 61 74 61 62 61 73 65 2c 20 74 61 62  he database, tab
27fe0 6c 65 2c 20 61 6e 64 0a 2a 2a 20 74 61 62 6c 65  le, and.** table
27ff0 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 69 73 20   column that is 
28000 74 68 65 20 6f 72 69 67 69 6e 20 6f 66 20 61 20  the origin of a 
28010 70 61 72 74 69 63 75 6c 61 72 20 72 65 73 75 6c  particular resul
28020 74 20 63 6f 6c 75 6d 6e 20 69 6e 0a 2a 2a 20 5b  t column in.** [
28030 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e  SELECT] statemen
28040 74 2e 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20  t..** ^The name 
28050 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  of the database 
28060 6f 72 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75  or table or colu
28070 6d 6e 20 63 61 6e 20 62 65 20 72 65 74 75 72 6e  mn can be return
28080 65 64 20 61 73 0a 2a 2a 20 65 69 74 68 65 72 20  ed as.** either 
28090 61 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31  a UTF-8 or UTF-1
280a0 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 65 20  6 string.  ^The 
280b0 5f 64 61 74 61 62 61 73 65 5f 20 72 6f 75 74 69  _database_ routi
280c0 6e 65 73 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68  nes return.** th
280d0 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65 2c  e database name,
280e0 20 74 68 65 20 5f 74 61 62 6c 65 5f 20 72 6f 75   the _table_ rou
280f0 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65  tines return the
28100 20 74 61 62 6c 65 20 6e 61 6d 65 2c 20 61 6e 64   table name, and
28110 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 5f 20  .** the origin_ 
28120 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
28130 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e  the column name.
28140 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65  .** ^The returne
28150 64 20 73 74 72 69 6e 67 20 69 73 20 76 61 6c 69  d string is vali
28160 64 20 75 6e 74 69 6c 20 74 68 65 20 5b 70 72 65  d until the [pre
28170 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
28180 20 69 73 20 64 65 73 74 72 6f 79 65 64 0a 2a 2a   is destroyed.**
28190 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
281a0 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75  finalize()] or u
281b0 6e 74 69 6c 20 74 68 65 20 73 74 61 74 65 6d 65  ntil the stateme
281c0 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61  nt is automatica
281d0 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61 72 65  lly.** reprepare
281e0 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20 63  d by the first c
281f0 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
28200 73 74 65 70 28 29 5d 20 66 6f 72 20 61 20 70 61  step()] for a pa
28210 72 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20  rticular run.** 
28220 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 61 6d  or until the sam
28230 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73  e information is
28240 20 72 65 71 75 65 73 74 65 64 0a 2a 2a 20 61 67   requested.** ag
28250 61 69 6e 20 69 6e 20 61 20 64 69 66 66 65 72 65  ain in a differe
28260 6e 74 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a  nt encoding..**.
28270 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 73 20 72 65  ** ^The names re
28280 74 75 72 6e 65 64 20 61 72 65 20 74 68 65 20 6f  turned are the o
28290 72 69 67 69 6e 61 6c 20 75 6e 2d 61 6c 69 61 73  riginal un-alias
282a0 65 64 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 0a  ed names of the.
282b0 2a 2a 20 64 61 74 61 62 61 73 65 2c 20 74 61 62  ** database, tab
282c0 6c 65 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a  le, and column..
282d0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
282e0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
282f0 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 69 73  se interfaces is
28300 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
28310 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 54 68 65  tement]..** ^The
28320 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74  se functions ret
28330 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  urn information 
28340 61 62 6f 75 74 20 74 68 65 20 4e 74 68 20 72 65  about the Nth re
28350 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 72 65 74 75  sult column retu
28360 72 6e 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 73  rned by.** the s
28370 74 61 74 65 6d 65 6e 74 2c 20 77 68 65 72 65 20  tatement, where 
28380 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20  N is the second 
28390 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e  function argumen
283a0 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74 2d  t..** ^The left-
283b0 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 63  most column is c
283c0 6f 6c 75 6d 6e 20 30 20 66 6f 72 20 74 68 65 73  olumn 0 for thes
283d0 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a  e routines..**.*
283e0 2a 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f  * ^If the Nth co
283f0 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79  lumn returned by
28400 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
28410 73 20 61 6e 20 65 78 70 72 65 73 73 69 6f 6e 20  s an expression 
28420 6f 72 0a 2a 2a 20 73 75 62 71 75 65 72 79 20 61  or.** subquery a
28430 6e 64 20 69 73 20 6e 6f 74 20 61 20 63 6f 6c 75  nd is not a colu
28440 6d 6e 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 61  mn value, then a
28450 6c 6c 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63  ll of these func
28460 74 69 6f 6e 73 20 72 65 74 75 72 6e 0a 2a 2a 20  tions return.** 
28470 4e 55 4c 4c 2e 20 20 5e 54 68 65 73 65 20 72 6f  NULL.  ^These ro
28480 75 74 69 6e 65 20 6d 69 67 68 74 20 61 6c 73 6f  utine might also
28490 20 72 65 74 75 72 6e 20 4e 55 4c 4c 20 69 66 20   return NULL if 
284a0 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
284b0 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a 20 6f 63 63  ion error.** occ
284c0 75 72 73 2e 20 20 5e 4f 74 68 65 72 77 69 73 65  urs.  ^Otherwise
284d0 2c 20 74 68 65 79 20 72 65 74 75 72 6e 20 74 68  , they return th
284e0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 61 74  e name of the at
284f0 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65 2c  tached database,
28500 20 74 61 62 6c 65 2c 0a 2a 2a 20 6f 72 20 63 6f   table,.** or co
28510 6c 75 6d 6e 20 74 68 61 74 20 71 75 65 72 79 20  lumn that query 
28520 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 77 61  result column wa
28530 73 20 65 78 74 72 61 63 74 65 64 20 66 72 6f 6d  s extracted from
28540 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 77 69 74 68  ..**.** ^As with
28550 20 61 6c 6c 20 6f 74 68 65 72 20 53 51 4c 69 74   all other SQLit
28560 65 20 41 50 49 73 2c 20 74 68 6f 73 65 20 77 68  e APIs, those wh
28570 6f 73 65 20 6e 61 6d 65 73 20 65 6e 64 20 77 69  ose names end wi
28580 74 68 20 22 31 36 22 20 72 65 74 75 72 6e 0a 2a  th "16" return.*
28590 2a 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64  * UTF-16 encoded
285a0 20 73 74 72 69 6e 67 73 20 61 6e 64 20 74 68 65   strings and the
285b0 20 6f 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 73   other functions
285c0 20 72 65 74 75 72 6e 20 55 54 46 2d 38 2e 0a 2a   return UTF-8..*
285d0 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 41 50 49 73  *.** ^These APIs
285e0 20 61 72 65 20 6f 6e 6c 79 20 61 76 61 69 6c 61   are only availa
285f0 62 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72 61  ble if the libra
28600 72 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20  ry was compiled 
28610 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  with the.** [SQL
28620 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d  ITE_ENABLE_COLUM
28630 4e 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d 70 72  N_METADATA] C-pr
28640 65 70 72 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f  eprocessor symbo
28650 6c 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20  l..**.** If two 
28660 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20  or more threads 
28670 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  call one or more
28680 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
28690 65 73 20 61 67 61 69 6e 73 74 20 74 68 65 20 73  es against the s
286a0 61 6d 65 0a 2a 2a 20 70 72 65 70 61 72 65 64 20  ame.** prepared 
286b0 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f  statement and co
286c0 6c 75 6d 6e 20 61 74 20 74 68 65 20 73 61 6d 65  lumn at the same
286d0 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72   time then the r
286e0 65 73 75 6c 74 73 20 61 72 65 0a 2a 2a 20 75 6e  esults are.** un
286f0 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49  defined..**.** I
28700 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68  f two or more th
28710 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f  reads call one o
28720 72 20 6d 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74  r more.** [sqlit
28730 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61  e3_column_databa
28740 73 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e  se_name | column
28750 20 6d 65 74 61 64 61 74 61 20 69 6e 74 65 72 66   metadata interf
28760 61 63 65 73 5d 0a 2a 2a 20 66 6f 72 20 74 68 65  aces].** for the
28770 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20   same [prepared 
28780 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20 72  statement] and r
28790 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  esult column.** 
287a0 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65  at the same time
287b0 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74   then the result
287c0 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e  s are undefined.
287d0 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  .*/.const char *
287e0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
287f0 61 74 61 62 61 73 65 5f 6e 61 6d 65 28 73 71 6c  atabase_name(sql
28800 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
28810 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
28820 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61  ite3_column_data
28830 62 61 73 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69  base_name16(sqli
28840 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
28850 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
28860 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65  te3_column_table
28870 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74  _name(sqlite3_st
28880 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20  mt*,int);.const 
28890 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
288a0 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 31  lumn_table_name1
288b0 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
288c0 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72  int);.const char
288d0 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
288e0 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 73 71 6c  _origin_name(sql
288f0 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
28900 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
28910 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67  ite3_column_orig
28920 69 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65  in_name16(sqlite
28930 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f  3_stmt*,int);../
28940 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
28950 65 63 6c 61 72 65 64 20 44 61 74 61 74 79 70 65  eclared Datatype
28960 20 4f 66 20 41 20 51 75 65 72 79 20 52 65 73 75   Of A Query Resu
28970 6c 74 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66  lt.**.** ^(The f
28980 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69  irst parameter i
28990 73 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  s a [prepared st
289a0 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20  atement]..** If 
289b0 74 68 69 73 20 73 74 61 74 65 6d 65 6e 74 20 69  this statement i
289c0 73 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61  s a [SELECT] sta
289d0 74 65 6d 65 6e 74 20 61 6e 64 20 74 68 65 20 4e  tement and the N
289e0 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65  th column of the
289f0 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 72 65 73  .** returned res
28a00 75 6c 74 20 73 65 74 20 6f 66 20 74 68 61 74 20  ult set of that 
28a10 5b 53 45 4c 45 43 54 5d 20 69 73 20 61 20 74 61  [SELECT] is a ta
28a20 62 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20  ble column (not 
28a30 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e  an.** expression
28a40 20 6f 72 20 73 75 62 71 75 65 72 79 29 20 74 68   or subquery) th
28a50 65 6e 20 74 68 65 20 64 65 63 6c 61 72 65 64 20  en the declared 
28a60 74 79 70 65 20 6f 66 20 74 68 65 20 74 61 62 6c  type of the tabl
28a70 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 73 20 72  e.** column is r
28a80 65 74 75 72 6e 65 64 2e 29 5e 20 20 5e 49 66 20  eturned.)^  ^If 
28a90 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f  the Nth column o
28aa0 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
28ab0 20 69 73 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73   is an.** expres
28ac0 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79  sion or subquery
28ad0 2c 20 74 68 65 6e 20 61 20 4e 55 4c 4c 20 70 6f  , then a NULL po
28ae0 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e 65  inter is returne
28af0 64 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72  d..** ^The retur
28b00 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 61 6c  ned string is al
28b10 77 61 79 73 20 55 54 46 2d 38 20 65 6e 63 6f 64  ways UTF-8 encod
28b20 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 20  ed..**.** ^(For 
28b30 65 78 61 6d 70 6c 65 2c 20 67 69 76 65 6e 20 74  example, given t
28b40 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65  he database sche
28b50 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54 45  ma:.**.** CREATE
28b60 20 54 41 42 4c 45 20 74 31 28 63 31 20 56 41 52   TABLE t1(c1 VAR
28b70 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64  IANT);.**.** and
28b80 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73   the following s
28b90 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63  tatement to be c
28ba0 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53  ompiled:.**.** S
28bb0 45 4c 45 43 54 20 63 31 20 2b 20 31 2c 20 63 31  ELECT c1 + 1, c1
28bc0 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20   FROM t1;.**.** 
28bd0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 6f 75  this routine wou
28be0 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20 73 74  ld return the st
28bf0 72 69 6e 67 20 22 56 41 52 49 41 4e 54 22 20 66  ring "VARIANT" f
28c00 6f 72 20 74 68 65 20 73 65 63 6f 6e 64 20 72 65  or the second re
28c10 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 28  sult.** column (
28c20 69 3d 3d 31 29 2c 20 61 6e 64 20 61 20 4e 55 4c  i==1), and a NUL
28c30 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 74 68  L pointer for th
28c40 65 20 66 69 72 73 74 20 72 65 73 75 6c 74 20 63  e first result c
28c50 6f 6c 75 6d 6e 20 28 69 3d 3d 30 29 2e 29 5e 0a  olumn (i==0).)^.
28c60 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73  **.** ^SQLite us
28c70 65 73 20 64 79 6e 61 6d 69 63 20 72 75 6e 2d 74  es dynamic run-t
28c80 69 6d 65 20 74 79 70 69 6e 67 2e 20 20 5e 53 6f  ime typing.  ^So
28c90 20 6a 75 73 74 20 62 65 63 61 75 73 65 20 61 20   just because a 
28ca0 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 64 65 63  column.** is dec
28cb0 6c 61 72 65 64 20 74 6f 20 63 6f 6e 74 61 69 6e  lared to contain
28cc0 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 74 79   a particular ty
28cd0 70 65 20 64 6f 65 73 20 6e 6f 74 20 6d 65 61 6e  pe does not mean
28ce0 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 64 61 74   that the.** dat
28cf0 61 20 73 74 6f 72 65 64 20 69 6e 20 74 68 61 74  a stored in that
28d00 20 63 6f 6c 75 6d 6e 20 69 73 20 6f 66 20 74 68   column is of th
28d10 65 20 64 65 63 6c 61 72 65 64 20 74 79 70 65 2e  e declared type.
28d20 20 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 73    SQLite is.** s
28d30 74 72 6f 6e 67 6c 79 20 74 79 70 65 64 2c 20 62  trongly typed, b
28d40 75 74 20 74 68 65 20 74 79 70 69 6e 67 20 69 73  ut the typing is
28d50 20 64 79 6e 61 6d 69 63 20 6e 6f 74 20 73 74 61   dynamic not sta
28d60 74 69 63 2e 20 20 5e 54 79 70 65 0a 2a 2a 20 69  tic.  ^Type.** i
28d70 73 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  s associated wit
28d80 68 20 69 6e 64 69 76 69 64 75 61 6c 20 76 61 6c  h individual val
28d90 75 65 73 2c 20 6e 6f 74 20 77 69 74 68 20 74 68  ues, not with th
28da0 65 20 63 6f 6e 74 61 69 6e 65 72 73 0a 2a 2a 20  e containers.** 
28db0 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 74 68 6f  used to hold tho
28dc0 73 65 20 76 61 6c 75 65 73 2e 0a 2a 2f 0a 63 6f  se values..*/.co
28dd0 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
28de0 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70  3_column_decltyp
28df0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
28e00 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  int);.const void
28e10 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
28e20 5f 64 65 63 6c 74 79 70 65 31 36 28 73 71 6c 69  _decltype16(sqli
28e30 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
28e40 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
28e50 20 45 76 61 6c 75 61 74 65 20 41 6e 20 53 51 4c   Evaluate An SQL
28e60 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a   Statement.**.**
28e70 20 41 66 74 65 72 20 61 20 5b 70 72 65 70 61 72   After a [prepar
28e80 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 68 61  ed statement] ha
28e90 73 20 62 65 65 6e 20 70 72 65 70 61 72 65 64 20  s been prepared 
28ea0 75 73 69 6e 67 20 65 69 74 68 65 72 0a 2a 2a 20  using either.** 
28eb0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
28ec0 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  _v2()] or [sqlit
28ed0 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
28ee0 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65  )] or one of the
28ef0 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72   legacy.** inter
28f00 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33 5f 70  faces [sqlite3_p
28f10 72 65 70 61 72 65 28 29 5d 20 6f 72 20 5b 73 71  repare()] or [sq
28f20 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
28f30 29 5d 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f  )], this functio
28f40 6e 0a 2a 2a 20 6d 75 73 74 20 62 65 20 63 61 6c  n.** must be cal
28f50 6c 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  led one or more 
28f60 74 69 6d 65 73 20 74 6f 20 65 76 61 6c 75 61 74  times to evaluat
28f70 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2e  e the statement.
28f80 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 74 61 69  .**.** The detai
28f90 6c 73 20 6f 66 20 74 68 65 20 62 65 68 61 76 69  ls of the behavi
28fa0 6f 72 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65  or of the sqlite
28fb0 33 5f 73 74 65 70 28 29 20 69 6e 74 65 72 66 61  3_step() interfa
28fc0 63 65 20 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20  ce depend.** on 
28fd0 77 68 65 74 68 65 72 20 74 68 65 20 73 74 61 74  whether the stat
28fe0 65 6d 65 6e 74 20 77 61 73 20 70 72 65 70 61 72  ement was prepar
28ff0 65 64 20 75 73 69 6e 67 20 74 68 65 20 6e 65 77  ed using the new
29000 65 72 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  er "v2" interfac
29010 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  e.** [sqlite3_pr
29020 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20  epare_v2()] and 
29030 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
29040 31 36 5f 76 32 28 29 5d 20 6f 72 20 74 68 65 20  16_v2()] or the 
29050 6f 6c 64 65 72 20 6c 65 67 61 63 79 0a 2a 2a 20  older legacy.** 
29060 69 6e 74 65 72 66 61 63 65 20 5b 73 71 6c 69 74  interface [sqlit
29070 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e  e3_prepare()] an
29080 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  d [sqlite3_prepa
29090 72 65 31 36 28 29 5d 2e 20 20 54 68 65 20 75 73  re16()].  The us
290a0 65 20 6f 66 20 74 68 65 0a 2a 2a 20 6e 65 77 20  e of the.** new 
290b0 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 20 69  "v2" interface i
290c0 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f  s recommended fo
290d0 72 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f  r new applicatio
290e0 6e 73 20 62 75 74 20 74 68 65 20 6c 65 67 61 63  ns but the legac
290f0 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 77  y.** interface w
29100 69 6c 6c 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20  ill continue to 
29110 62 65 20 73 75 70 70 6f 72 74 65 64 2e 0a 2a 2a  be supported..**
29120 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 6c 65 67 61  .** ^In the lega
29130 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68  cy interface, th
29140 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 77  e return value w
29150 69 6c 6c 20 62 65 20 65 69 74 68 65 72 20 5b 53  ill be either [S
29160 51 4c 49 54 45 5f 42 55 53 59 5d 2c 0a 2a 2a 20  QLITE_BUSY],.** 
29170 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b  [SQLITE_DONE], [
29180 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 5b 53 51  SQLITE_ROW], [SQ
29190 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 6f 72 20  LITE_ERROR], or 
291a0 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e  [SQLITE_MISUSE].
291b0 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 20 22 76  .** ^With the "v
291c0 32 22 20 69 6e 74 65 72 66 61 63 65 2c 20 61 6e  2" interface, an
291d0 79 20 6f 66 20 74 68 65 20 6f 74 68 65 72 20 5b  y of the other [
291e0 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6f 72  result codes] or
291f0 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65  .** [extended re
29200 73 75 6c 74 20 63 6f 64 65 73 5d 20 6d 69 67 68  sult codes] migh
29210 74 20 62 65 20 72 65 74 75 72 6e 65 64 20 61 73  t be returned as
29220 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53   well..**.** ^[S
29230 51 4c 49 54 45 5f 42 55 53 59 5d 20 6d 65 61 6e  QLITE_BUSY] mean
29240 73 20 74 68 61 74 20 74 68 65 20 64 61 74 61 62  s that the datab
29250 61 73 65 20 65 6e 67 69 6e 65 20 77 61 73 20 75  ase engine was u
29260 6e 61 62 6c 65 20 74 6f 20 61 63 71 75 69 72 65  nable to acquire
29270 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
29280 20 6c 6f 63 6b 73 20 69 74 20 6e 65 65 64 73 20   locks it needs 
29290 74 6f 20 64 6f 20 69 74 73 20 6a 6f 62 2e 20 20  to do its job.  
292a0 5e 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e  ^If the statemen
292b0 74 20 69 73 20 61 20 5b 43 4f 4d 4d 49 54 5d 0a  t is a [COMMIT].
292c0 2a 2a 20 6f 72 20 6f 63 63 75 72 73 20 6f 75 74  ** or occurs out
292d0 73 69 64 65 20 6f 66 20 61 6e 20 65 78 70 6c 69  side of an expli
292e0 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c  cit transaction,
292f0 20 74 68 65 6e 20 79 6f 75 20 63 61 6e 20 72 65   then you can re
29300 74 72 79 20 74 68 65 0a 2a 2a 20 73 74 61 74 65  try the.** state
29310 6d 65 6e 74 2e 20 20 49 66 20 74 68 65 20 73 74  ment.  If the st
29320 61 74 65 6d 65 6e 74 20 69 73 20 6e 6f 74 20 61  atement is not a
29330 20 5b 43 4f 4d 4d 49 54 5d 20 61 6e 64 20 6f 63   [COMMIT] and oc
29340 63 75 72 73 20 77 69 74 68 69 6e 20 61 6e 0a 2a  curs within an.*
29350 2a 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73  * explicit trans
29360 61 63 74 69 6f 6e 20 74 68 65 6e 20 79 6f 75 20  action then you 
29370 73 68 6f 75 6c 64 20 72 6f 6c 6c 62 61 63 6b 20  should rollback 
29380 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  the transaction 
29390 62 65 66 6f 72 65 0a 2a 2a 20 63 6f 6e 74 69 6e  before.** contin
293a0 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51  uing..**.** ^[SQ
293b0 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d 65 61 6e 73  LITE_DONE] means
293c0 20 74 68 61 74 20 74 68 65 20 73 74 61 74 65 6d   that the statem
293d0 65 6e 74 20 68 61 73 20 66 69 6e 69 73 68 65 64  ent has finished
293e0 20 65 78 65 63 75 74 69 6e 67 0a 2a 2a 20 73 75   executing.** su
293f0 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 73 71 6c  ccessfully.  sql
29400 69 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75  ite3_step() shou
29410 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64  ld not be called
29420 20 61 67 61 69 6e 20 6f 6e 20 74 68 69 73 20 76   again on this v
29430 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e  irtual.** machin
29440 65 20 77 69 74 68 6f 75 74 20 66 69 72 73 74 20  e without first 
29450 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
29460 5f 72 65 73 65 74 28 29 5d 20 74 6f 20 72 65 73  _reset()] to res
29470 65 74 20 74 68 65 20 76 69 72 74 75 61 6c 0a 2a  et the virtual.*
29480 2a 20 6d 61 63 68 69 6e 65 20 62 61 63 6b 20 74  * machine back t
29490 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74  o its initial st
294a0 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ate..**.** ^If t
294b0 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
294c0 20 62 65 69 6e 67 20 65 78 65 63 75 74 65 64 20   being executed 
294d0 72 65 74 75 72 6e 73 20 61 6e 79 20 64 61 74 61  returns any data
294e0 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 52  , then [SQLITE_R
294f0 4f 57 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e  OW].** is return
29500 65 64 20 65 61 63 68 20 74 69 6d 65 20 61 20 6e  ed each time a n
29510 65 77 20 72 6f 77 20 6f 66 20 64 61 74 61 20 69  ew row of data i
29520 73 20 72 65 61 64 79 20 66 6f 72 20 70 72 6f 63  s ready for proc
29530 65 73 73 69 6e 67 20 62 79 20 74 68 65 0a 2a 2a  essing by the.**
29540 20 63 61 6c 6c 65 72 2e 20 54 68 65 20 76 61 6c   caller. The val
29550 75 65 73 20 6d 61 79 20 62 65 20 61 63 63 65 73  ues may be acces
29560 73 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b 63  sed using the [c
29570 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e  olumn access fun
29580 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 6c 69  ctions]..** sqli
29590 74 65 33 5f 73 74 65 70 28 29 20 69 73 20 63 61  te3_step() is ca
295a0 6c 6c 65 64 20 61 67 61 69 6e 20 74 6f 20 72 65  lled again to re
295b0 74 72 69 65 76 65 20 74 68 65 20 6e 65 78 74 20  trieve the next 
295c0 72 6f 77 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a  row of data..**.
295d0 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 45 52 52 4f  ** ^[SQLITE_ERRO
295e0 52 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 61 20  R] means that a 
295f0 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 20 28  run-time error (
29600 73 75 63 68 20 61 73 20 61 20 63 6f 6e 73 74 72  such as a constr
29610 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74 69 6f  aint.** violatio
29620 6e 29 20 68 61 73 20 6f 63 63 75 72 72 65 64 2e  n) has occurred.
29630 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29    sqlite3_step()
29640 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63   should not be c
29650 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 0a 2a  alled again on.*
29660 2a 20 74 68 65 20 56 4d 2e 20 4d 6f 72 65 20 69  * the VM. More i
29670 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d 61 79 20 62  nformation may b
29680 65 20 66 6f 75 6e 64 20 62 79 20 63 61 6c 6c 69  e found by calli
29690 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  ng [sqlite3_errm
296a0 73 67 28 29 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20  sg()]..** ^With 
296b0 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72  the legacy inter
296c0 66 61 63 65 2c 20 61 20 6d 6f 72 65 20 73 70 65  face, a more spe
296d0 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65  cific error code
296e0 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a   (for example,.*
296f0 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52  * [SQLITE_INTERR
29700 55 50 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 53 43  UPT], [SQLITE_SC
29710 48 45 4d 41 5d 2c 20 5b 53 51 4c 49 54 45 5f 43  HEMA], [SQLITE_C
29720 4f 52 52 55 50 54 5d 2c 20 61 6e 64 20 73 6f 20  ORRUPT], and so 
29730 66 6f 72 74 68 29 0a 2a 2a 20 63 61 6e 20 62 65  forth).** can be
29740 20 6f 62 74 61 69 6e 65 64 20 62 79 20 63 61 6c   obtained by cal
29750 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65  ling [sqlite3_re
29760 73 65 74 28 29 5d 20 6f 6e 20 74 68 65 0a 2a 2a  set()] on the.**
29770 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
29780 6d 65 6e 74 5d 2e 20 20 5e 49 6e 20 74 68 65 20  ment].  ^In the 
29790 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c 0a  "v2" interface,.
297a0 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63  ** the more spec
297b0 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20  ific error code 
297c0 69 73 20 72 65 74 75 72 6e 65 64 20 64 69 72 65  is returned dire
297d0 63 74 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f  ctly by sqlite3_
297e0 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53  step()..**.** [S
297f0 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 6d 65  QLITE_MISUSE] me
29800 61 6e 73 20 74 68 61 74 20 74 68 65 20 74 68 69  ans that the thi
29810 73 20 72 6f 75 74 69 6e 65 20 77 61 73 20 63 61  s routine was ca
29820 6c 6c 65 64 20 69 6e 61 70 70 72 6f 70 72 69 61  lled inappropria
29830 74 65 6c 79 2e 0a 2a 2a 20 50 65 72 68 61 70 73  tely..** Perhaps
29840 20 69 74 20 77 61 73 20 63 61 6c 6c 65 64 20 6f   it was called o
29850 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  n a [prepared st
29860 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61  atement] that ha
29870 73 0a 2a 2a 20 61 6c 72 65 61 64 79 20 62 65 65  s.** already bee
29880 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  n [sqlite3_final
29890 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 64 5d  ize | finalized]
298a0 20 6f 72 20 6f 6e 20 6f 6e 65 20 74 68 61 74 20   or on one that 
298b0 68 61 64 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c  had.** previousl
298c0 79 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49  y returned [SQLI
298d0 54 45 5f 45 52 52 4f 52 5d 20 6f 72 20 5b 53 51  TE_ERROR] or [SQ
298e0 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f 72 20  LITE_DONE].  Or 
298f0 69 74 20 63 6f 75 6c 64 0a 2a 2a 20 62 65 20 74  it could.** be t
29900 68 65 20 63 61 73 65 20 74 68 61 74 20 74 68 65  he case that the
29910 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63   same database c
29920 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 62 65 69  onnection is bei
29930 6e 67 20 75 73 65 64 20 62 79 20 74 77 6f 20 6f  ng used by two o
29940 72 0a 2a 2a 20 6d 6f 72 65 20 74 68 72 65 61 64  r.** more thread
29950 73 20 61 74 20 74 68 65 20 73 61 6d 65 20 6d 6f  s at the same mo
29960 6d 65 6e 74 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a  ment in time..**
29970 0a 2a 2a 20 46 6f 72 20 61 6c 6c 20 76 65 72 73  .** For all vers
29980 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 75  ions of SQLite u
29990 70 20 74 6f 20 61 6e 64 20 69 6e 63 6c 75 64 69  p to and includi
299a0 6e 67 20 33 2e 36 2e 32 33 2e 31 2c 20 61 20 63  ng 3.6.23.1, a c
299b0 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  all to.** [sqlit
299c0 65 33 5f 72 65 73 65 74 28 29 5d 20 77 61 73 20  e3_reset()] was 
299d0 72 65 71 75 69 72 65 64 20 61 66 74 65 72 20 73  required after s
299e0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 72 65  qlite3_step() re
299f0 74 75 72 6e 65 64 20 61 6e 79 74 68 69 6e 67 0a  turned anything.
29a00 2a 2a 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53  ** other than [S
29a10 51 4c 49 54 45 5f 52 4f 57 5d 20 62 65 66 6f 72  QLITE_ROW] befor
29a20 65 20 61 6e 79 20 73 75 62 73 65 71 75 65 6e 74  e any subsequent
29a30 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 0a 2a   invocation of.*
29a40 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  * sqlite3_step()
29a50 2e 20 20 46 61 69 6c 75 72 65 20 74 6f 20 72 65  .  Failure to re
29a60 73 65 74 20 74 68 65 20 70 72 65 70 61 72 65 64  set the prepared
29a70 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67   statement using
29a80 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65   .** [sqlite3_re
29a90 73 65 74 28 29 5d 20 77 6f 75 6c 64 20 72 65 73  set()] would res
29aa0 75 6c 74 20 69 6e 20 61 6e 20 5b 53 51 4c 49 54  ult in an [SQLIT
29ab0 45 5f 4d 49 53 55 53 45 5d 20 72 65 74 75 72 6e  E_MISUSE] return
29ac0 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 33   from.** sqlite3
29ad0 5f 73 74 65 70 28 29 2e 20 20 42 75 74 20 61 66  _step().  But af
29ae0 74 65 72 20 76 65 72 73 69 6f 6e 20 33 2e 36 2e  ter version 3.6.
29af0 32 33 2e 31 2c 20 73 71 6c 69 74 65 33 5f 73 74  23.1, sqlite3_st
29b00 65 70 28 29 20 62 65 67 61 6e 0a 2a 2a 20 63 61  ep() began.** ca
29b10 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72  lling [sqlite3_r
29b20 65 73 65 74 28 29 5d 20 61 75 74 6f 6d 61 74 69  eset()] automati
29b30 63 61 6c 6c 79 20 69 6e 20 74 68 69 73 20 63 69  cally in this ci
29b40 72 63 75 6d 73 74 61 6e 63 65 20 72 61 74 68 65  rcumstance rathe
29b50 72 0a 2a 2a 20 74 68 61 6e 20 72 65 74 75 72 6e  r.** than return
29b60 69 6e 67 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55  ing [SQLITE_MISU
29b70 53 45 5d 2e 20 20 54 68 69 73 20 69 73 20 6e 6f  SE].  This is no
29b80 74 20 63 6f 6e 73 69 64 65 72 65 64 20 61 20 63  t considered a c
29b90 6f 6d 70 61 74 69 62 69 6c 69 74 79 0a 2a 2a 20  ompatibility.** 
29ba0 62 72 65 61 6b 20 62 65 63 61 75 73 65 20 61 6e  break because an
29bb0 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 68  y application th
29bc0 61 74 20 65 76 65 72 20 72 65 63 65 69 76 65 73  at ever receives
29bd0 20 61 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53   an SQLITE_MISUS
29be0 45 20 65 72 72 6f 72 0a 2a 2a 20 69 73 20 62 72  E error.** is br
29bf0 6f 6b 65 6e 20 62 79 20 64 65 66 69 6e 69 74 69  oken by definiti
29c00 6f 6e 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45  on.  The [SQLITE
29c10 5f 4f 4d 49 54 5f 41 55 54 4f 52 45 53 45 54 5d  _OMIT_AUTORESET]
29c20 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
29c30 74 69 6f 6e 0a 2a 2a 20 63 61 6e 20 62 65 20 75  tion.** can be u
29c40 73 65 64 20 74 6f 20 72 65 73 74 6f 72 65 20 74  sed to restore t
29c50 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 69  he legacy behavi
29c60 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f  or..**.** <b>Goo
29c70 66 79 20 49 6e 74 65 72 66 61 63 65 20 41 6c 65  fy Interface Ale
29c80 72 74 3a 3c 2f 62 3e 20 49 6e 20 74 68 65 20 6c  rt:</b> In the l
29c90 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c  egacy interface,
29ca0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65   the sqlite3_ste
29cb0 70 28 29 0a 2a 2a 20 41 50 49 20 61 6c 77 61 79  p().** API alway
29cc0 73 20 72 65 74 75 72 6e 73 20 61 20 67 65 6e 65  s returns a gene
29cd0 72 69 63 20 65 72 72 6f 72 20 63 6f 64 65 2c 20  ric error code, 
29ce0 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20  [SQLITE_ERROR], 
29cf0 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 0a 2a 2a  following any.**
29d00 20 65 72 72 6f 72 20 6f 74 68 65 72 20 74 68 61   error other tha
29d10 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  n [SQLITE_BUSY] 
29d20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55  and [SQLITE_MISU
29d30 53 45 5d 2e 20 20 59 6f 75 20 6d 75 73 74 20 63  SE].  You must c
29d40 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  all.** [sqlite3_
29d50 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c  reset()] or [sql
29d60 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
29d70 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e   in order to fin
29d80 64 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20  d one of the.** 
29d90 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20  specific [error 
29da0 63 6f 64 65 73 5d 20 74 68 61 74 20 62 65 74 74  codes] that bett
29db0 65 72 20 64 65 73 63 72 69 62 65 73 20 74 68 65  er describes the
29dc0 20 65 72 72 6f 72 2e 0a 2a 2a 20 57 65 20 61 64   error..** We ad
29dd0 6d 69 74 20 74 68 61 74 20 74 68 69 73 20 69 73  mit that this is
29de0 20 61 20 67 6f 6f 66 79 20 64 65 73 69 67 6e 2e   a goofy design.
29df0 20 20 54 68 65 20 70 72 6f 62 6c 65 6d 20 68 61    The problem ha
29e00 73 20 62 65 65 6e 20 66 69 78 65 64 0a 2a 2a 20  s been fixed.** 
29e10 77 69 74 68 20 74 68 65 20 22 76 32 22 20 69 6e  with the "v2" in
29e20 74 65 72 66 61 63 65 2e 20 20 49 66 20 79 6f 75  terface.  If you
29e30 20 70 72 65 70 61 72 65 20 61 6c 6c 20 6f 66 20   prepare all of 
29e40 79 6f 75 72 20 53 51 4c 20 73 74 61 74 65 6d 65  your SQL stateme
29e50 6e 74 73 0a 2a 2a 20 75 73 69 6e 67 20 65 69 74  nts.** using eit
29e60 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  her [sqlite3_pre
29e70 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73  pare_v2()] or [s
29e80 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
29e90 5f 76 32 28 29 5d 20 69 6e 73 74 65 61 64 0a 2a  _v2()] instead.*
29ea0 2a 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79 20  * of the legacy 
29eb0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
29ec0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
29ed0 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 69 6e  _prepare16()] in
29ee0 74 65 72 66 61 63 65 73 2c 0a 2a 2a 20 74 68 65  terfaces,.** the
29ef0 6e 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69  n the more speci
29f00 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73  fic [error codes
29f10 5d 20 61 72 65 20 72 65 74 75 72 6e 65 64 20 64  ] are returned d
29f20 69 72 65 63 74 6c 79 0a 2a 2a 20 62 79 20 73 71  irectly.** by sq
29f30 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 54  lite3_step().  T
29f40 68 65 20 75 73 65 20 6f 66 20 74 68 65 20 22 76  he use of the "v
29f50 32 22 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  2" interface is 
29f60 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2f 0a  recommended..*/.
29f70 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 65 70  int sqlite3_step
29f80 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b  (sqlite3_stmt*);
29f90 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
29fa0 3a 20 4e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  : Number of colu
29fb0 6d 6e 73 20 69 6e 20 61 20 72 65 73 75 6c 74 20  mns in a result 
29fc0 73 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  set.**.** ^The s
29fd0 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e  qlite3_data_coun
29fe0 74 28 50 29 20 69 6e 74 65 72 66 61 63 65 20 72  t(P) interface r
29ff0 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
2a000 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
2a010 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 72  the.** current r
2a020 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  ow of the result
2a030 20 73 65 74 20 6f 66 20 5b 70 72 65 70 61 72 65   set of [prepare
2a040 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a  d statement] P..
2a050 2a 2a 20 5e 49 66 20 70 72 65 70 61 72 65 64 20  ** ^If prepared 
2a060 73 74 61 74 65 6d 65 6e 74 20 50 20 64 6f 65 73  statement P does
2a070 20 6e 6f 74 20 68 61 76 65 20 72 65 73 75 6c 74   not have result
2a080 73 20 72 65 61 64 79 20 74 6f 20 72 65 74 75 72  s ready to retur
2a090 6e 0a 2a 2a 20 28 76 69 61 20 63 61 6c 6c 73 20  n.** (via calls 
2a0a0 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
2a0b0 63 6f 6c 75 6d 6e 5f 69 6e 74 20 7c 20 73 71 6c  column_int | sql
2a0c0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 2a 28 29 5d  ite3_column_*()]
2a0d0 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65   of.** interface
2a0e0 73 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  s) then sqlite3_
2a0f0 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 65  data_count(P) re
2a100 74 75 72 6e 73 20 30 2e 0a 2a 2a 20 5e 54 68 65  turns 0..** ^The
2a110 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f   sqlite3_data_co
2a120 75 6e 74 28 50 29 20 72 6f 75 74 69 6e 65 20 61  unt(P) routine a
2a130 6c 73 6f 20 72 65 74 75 72 6e 73 20 30 20 69 66  lso returns 0 if
2a140 20 50 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69   P is a NULL poi
2a150 6e 74 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  nter..** ^The sq
2a160 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
2a170 28 50 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  (P) routine retu
2a180 72 6e 73 20 30 20 69 66 20 74 68 65 20 70 72 65  rns 0 if the pre
2a190 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 0a 2a 2a  vious call to.**
2a1a0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 5d 28   [sqlite3_step](
2a1b0 50 29 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c  P) returned [SQL
2a1c0 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 5e 54 68 65  ITE_DONE].  ^The
2a1d0 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f   sqlite3_data_co
2a1e0 75 6e 74 28 50 29 0a 2a 2a 20 77 69 6c 6c 20 72  unt(P).** will r
2a1f0 65 74 75 72 6e 20 6e 6f 6e 2d 7a 65 72 6f 20 69  eturn non-zero i
2a200 66 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20  f previous call 
2a210 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
2a220 5d 28 50 29 20 72 65 74 75 72 6e 65 64 0a 2a 2a  ](P) returned.**
2a230 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 65   [SQLITE_ROW], e
2a240 78 63 65 70 74 20 69 6e 20 74 68 65 20 63 61 73  xcept in the cas
2a250 65 20 6f 66 20 74 68 65 20 5b 50 52 41 47 4d 41  e of the [PRAGMA
2a260 20 69 6e 63 72 65 6d 65 6e 74 61 6c 5f 76 61 63   incremental_vac
2a270 75 75 6d 5d 0a 2a 2a 20 77 68 65 72 65 20 69 74  uum].** where it
2a280 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20   always returns 
2a290 7a 65 72 6f 20 73 69 6e 63 65 20 65 61 63 68 20  zero since each 
2a2a0 73 74 65 70 20 6f 66 20 74 68 61 74 20 6d 75 6c  step of that mul
2a2b0 74 69 2d 73 74 65 70 0a 2a 2a 20 70 72 61 67 6d  ti-step.** pragm
2a2c0 61 20 72 65 74 75 72 6e 73 20 30 20 63 6f 6c 75  a returns 0 colu
2a2d0 6d 6e 73 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a  mns of data..**.
2a2e0 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
2a2f0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75  lite3_column_cou
2a300 6e 74 28 29 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c  nt()].*/.int sql
2a310 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
2a320 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
2a330 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
2a340 49 33 52 45 46 3a 20 46 75 6e 64 61 6d 65 6e 74  I3REF: Fundament
2a350 61 6c 20 44 61 74 61 74 79 70 65 73 0a 2a 2a 20  al Datatypes.** 
2a360 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45  KEYWORDS: SQLITE
2a370 5f 54 45 58 54 0a 2a 2a 0a 2a 2a 20 5e 28 45 76  _TEXT.**.** ^(Ev
2a380 65 72 79 20 76 61 6c 75 65 20 69 6e 20 53 51 4c  ery value in SQL
2a390 69 74 65 20 68 61 73 20 6f 6e 65 20 6f 66 20 66  ite has one of f
2a3a0 69 76 65 20 66 75 6e 64 61 6d 65 6e 74 61 6c 20  ive fundamental 
2a3b0 64 61 74 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a  datatypes:.**.**
2a3c0 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34   <ul>.** <li> 64
2a3d0 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65  -bit signed inte
2a3e0 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62  ger.** <li> 64-b
2a3f0 69 74 20 49 45 45 45 20 66 6c 6f 61 74 69 6e 67  it IEEE floating
2a400 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a   point number.**
2a410 20 3c 6c 69 3e 20 73 74 72 69 6e 67 0a 2a 2a 20   <li> string.** 
2a420 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69  <li> BLOB.** <li
2a430 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 29  > NULL.** </ul>)
2a440 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f  ^.**.** These co
2a450 6e 73 74 61 6e 74 73 20 61 72 65 20 63 6f 64 65  nstants are code
2a460 73 20 66 6f 72 20 65 61 63 68 20 6f 66 20 74 68  s for each of th
2a470 6f 73 65 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a  ose types..**.**
2a480 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 53   Note that the S
2a490 51 4c 49 54 45 5f 54 45 58 54 20 63 6f 6e 73 74  QLITE_TEXT const
2a4a0 61 6e 74 20 77 61 73 20 61 6c 73 6f 20 75 73 65  ant was also use
2a4b0 64 20 69 6e 20 53 51 4c 69 74 65 20 76 65 72 73  d in SQLite vers
2a4c0 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20 61 20 63  ion 2.** for a c
2a4d0 6f 6d 70 6c 65 74 65 6c 79 20 64 69 66 66 65 72  ompletely differ
2a4e0 65 6e 74 20 6d 65 61 6e 69 6e 67 2e 20 20 53 6f  ent meaning.  So
2a4f0 66 74 77 61 72 65 20 74 68 61 74 20 6c 69 6e 6b  ftware that link
2a500 73 20 61 67 61 69 6e 73 74 20 62 6f 74 68 0a 2a  s against both.*
2a510 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  * SQLite version
2a520 20 32 20 61 6e 64 20 53 51 4c 69 74 65 20 76 65   2 and SQLite ve
2a530 72 73 69 6f 6e 20 33 20 73 68 6f 75 6c 64 20 75  rsion 3 should u
2a540 73 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54 2c  se SQLITE3_TEXT,
2a550 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54 45 5f 54   not.** SQLITE_T
2a560 45 58 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  EXT..*/.#define 
2a570 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 20  SQLITE_INTEGER  
2a580 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
2a590 5f 46 4c 4f 41 54 20 20 20 20 32 0a 23 64 65 66  _FLOAT    2.#def
2a5a0 69 6e 65 20 53 51 4c 49 54 45 5f 42 4c 4f 42 20  ine SQLITE_BLOB 
2a5b0 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51      4.#define SQ
2a5c0 4c 49 54 45 5f 4e 55 4c 4c 20 20 20 20 20 35 0a  LITE_NULL     5.
2a5d0 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 54 45  #ifdef SQLITE_TE
2a5e0 58 54 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54  XT.# undef SQLIT
2a5f0 45 5f 54 45 58 54 0a 23 65 6c 73 65 0a 23 20 64  E_TEXT.#else.# d
2a600 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 58  efine SQLITE_TEX
2a610 54 20 20 20 20 20 33 0a 23 65 6e 64 69 66 0a 23  T     3.#endif.#
2a620 64 65 66 69 6e 65 20 53 51 4c 49 54 45 33 5f 54  define SQLITE3_T
2a630 45 58 54 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a  EXT     3../*.**
2a640 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c   CAPI3REF: Resul
2a650 74 20 56 61 6c 75 65 73 20 46 72 6f 6d 20 41 20  t Values From A 
2a660 51 75 65 72 79 0a 2a 2a 20 4b 45 59 57 4f 52 44  Query.** KEYWORD
2a670 53 3a 20 7b 63 6f 6c 75 6d 6e 20 61 63 63 65 73  S: {column acces
2a680 73 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a  s functions}.**.
2a690 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
2a6a0 73 20 66 6f 72 6d 20 74 68 65 20 22 72 65 73 75  s form the "resu
2a6b0 6c 74 20 73 65 74 22 20 69 6e 74 65 72 66 61 63  lt set" interfac
2a6c0 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  e..**.** ^These 
2a6d0 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
2a6e0 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75  information abou
2a6f0 74 20 61 20 73 69 6e 67 6c 65 20 63 6f 6c 75 6d  t a single colum
2a700 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74  n of the current
2a710 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77 20 6f  .** result row o
2a720 66 20 61 20 71 75 65 72 79 2e 20 20 5e 49 6e 20  f a query.  ^In 
2a730 65 76 65 72 79 20 63 61 73 65 20 74 68 65 20 66  every case the f
2a740 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73  irst argument is
2a750 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f   a pointer.** to
2a760 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
2a770 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69  tatement] that i
2a780 73 20 62 65 69 6e 67 20 65 76 61 6c 75 61 74 65  s being evaluate
2a790 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  d (the [sqlite3_
2a7a0 73 74 6d 74 2a 5d 0a 2a 2a 20 74 68 61 74 20 77  stmt*].** that w
2a7b0 61 73 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d  as returned from
2a7c0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2a7d0 65 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f  e_v2()] or one o
2a7e0 66 20 69 74 73 20 76 61 72 69 61 6e 74 73 29 0a  f its variants).
2a7f0 2a 2a 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e  ** and the secon
2a800 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  d argument is th
2a810 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 63  e index of the c
2a820 6f 6c 75 6d 6e 20 66 6f 72 20 77 68 69 63 68 20  olumn for which 
2a830 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73  information.** s
2a840 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65  hould be returne
2a850 64 2e 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74  d. ^The leftmost
2a860 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72   column of the r
2a870 65 73 75 6c 74 20 73 65 74 20 68 61 73 20 74 68  esult set has th
2a880 65 20 69 6e 64 65 78 20 30 2e 0a 2a 2a 20 5e 54  e index 0..** ^T
2a890 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  he number of col
2a8a0 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75  umns in the resu
2a8b0 6c 74 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d  lt can be determ
2a8c0 69 6e 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73  ined using.** [s
2a8d0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f  qlite3_column_co
2a8e0 75 6e 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66  unt()]..**.** If
2a8f0 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
2a900 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 75 72 72  nt does not curr
2a910 65 6e 74 6c 79 20 70 6f 69 6e 74 20 74 6f 20 61  ently point to a
2a920 20 76 61 6c 69 64 20 72 6f 77 2c 20 6f 72 20 69   valid row, or i
2a930 66 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20  f the.** column 
2a940 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20  index is out of 
2a950 72 61 6e 67 65 2c 20 74 68 65 20 72 65 73 75 6c  range, the resul
2a960 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  t is undefined..
2a970 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
2a980 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 63 61  s may only be ca
2a990 6c 6c 65 64 20 77 68 65 6e 20 74 68 65 20 6d 6f  lled when the mo
2a9a0 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74  st recent call t
2a9b0 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74  o.** [sqlite3_st
2a9c0 65 70 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e  ep()] has return
2a9d0 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20  ed [SQLITE_ROW] 
2a9e0 61 6e 64 20 6e 65 69 74 68 65 72 0a 2a 2a 20 5b  and neither.** [
2a9f0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
2aa00 20 6e 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69   nor [sqlite3_fi
2aa10 6e 61 6c 69 7a 65 28 29 5d 20 68 61 76 65 20 62  nalize()] have b
2aa20 65 65 6e 20 63 61 6c 6c 65 64 20 73 75 62 73 65  een called subse
2aa30 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20 61  quently..** If a
2aa40 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  ny of these rout
2aa50 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20  ines are called 
2aa60 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 72  after [sqlite3_r
2aa70 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73  eset()] or.** [s
2aa80 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2aa90 29 5d 20 6f 72 20 61 66 74 65 72 20 5b 73 71 6c  )] or after [sql
2aaa0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73  ite3_step()] has
2aab0 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d   returned.** som
2aac0 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61  ething other tha
2aad0 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20  n [SQLITE_ROW], 
2aae0 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20  the results are 
2aaf0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66  undefined..** If
2ab00 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
2ab10 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  ] or [sqlite3_re
2ab20 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  set()] or [sqlit
2ab30 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a  e3_finalize()].*
2ab40 2a 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f  * are called fro
2ab50 6d 20 61 20 64 69 66 66 65 72 65 6e 74 20 74 68  m a different th
2ab60 72 65 61 64 20 77 68 69 6c 65 20 61 6e 79 20 6f  read while any o
2ab70 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
2ab80 0a 2a 2a 20 61 72 65 20 70 65 6e 64 69 6e 67 2c  .** are pending,
2ab90 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74   then the result
2aba0 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e  s are undefined.
2abb0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2abc0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
2abd0 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ) routine return
2abe0 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  s the.** [SQLITE
2abf0 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74  _INTEGER | datat
2ac00 79 70 65 20 63 6f 64 65 5d 20 66 6f 72 20 74 68  ype code] for th
2ac10 65 20 69 6e 69 74 69 61 6c 20 64 61 74 61 20 74  e initial data t
2ac20 79 70 65 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65  ype.** of the re
2ac30 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20 5e 54  sult column.  ^T
2ac40 68 65 20 72 65 74 75 72 6e 65 64 20 76 61 6c 75  he returned valu
2ac50 65 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c  e is one of [SQL
2ac60 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a  ITE_INTEGER],.**
2ac70 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c   [SQLITE_FLOAT],
2ac80 20 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20   [SQLITE_TEXT], 
2ac90 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f  [SQLITE_BLOB], o
2aca0 72 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e  r [SQLITE_NULL].
2acb0 20 20 54 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72    The value.** r
2acc0 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
2acd0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29  e3_column_type()
2ace0 20 69 73 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67   is only meaning
2acf0 66 75 6c 20 69 66 20 6e 6f 20 74 79 70 65 0a 2a  ful if no type.*
2ad00 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 68 61  * conversions ha
2ad10 76 65 20 6f 63 63 75 72 72 65 64 20 61 73 20 64  ve occurred as d
2ad20 65 73 63 72 69 62 65 64 20 62 65 6c 6f 77 2e 20  escribed below. 
2ad30 20 41 66 74 65 72 20 61 20 74 79 70 65 20 63 6f   After a type co
2ad40 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a 20 74 68 65  nversion,.** the
2ad50 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
2ad60 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
2ad70 6e 5f 74 79 70 65 28 29 20 69 73 20 75 6e 64 65  n_type() is unde
2ad80 66 69 6e 65 64 2e 20 20 46 75 74 75 72 65 0a 2a  fined.  Future.*
2ad90 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  * versions of SQ
2ada0 4c 69 74 65 20 6d 61 79 20 63 68 61 6e 67 65 20  Lite may change 
2adb0 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20  the behavior of 
2adc0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2add0 79 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69  ype().** followi
2ade0 6e 67 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72  ng a type conver
2adf0 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  sion..**.** ^If 
2ae00 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20  the result is a 
2ae10 42 4c 4f 42 20 6f 72 20 55 54 46 2d 38 20 73 74  BLOB or UTF-8 st
2ae20 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71  ring then the sq
2ae30 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2ae40 65 73 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  es().** routine 
2ae50 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
2ae60 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
2ae70 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69  hat BLOB or stri
2ae80 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72  ng..** ^If the r
2ae90 65 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d 31  esult is a UTF-1
2aea0 36 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73  6 string, then s
2aeb0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2aec0 74 65 73 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a  tes() converts.*
2aed0 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20  * the string to 
2aee0 55 54 46 2d 38 20 61 6e 64 20 74 68 65 6e 20 72  UTF-8 and then r
2aef0 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
2af00 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e  r of bytes..** ^
2af10 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
2af20 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65   a numeric value
2af30 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f   then sqlite3_co
2af40 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 75 73 65  lumn_bytes() use
2af50 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e  s.** [sqlite3_sn
2af60 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e  printf()] to con
2af70 76 65 72 74 20 74 68 61 74 20 76 61 6c 75 65 20  vert that value 
2af80 74 6f 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e  to a UTF-8 strin
2af90 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a  g and returns.**
2afa0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
2afb0 79 74 65 73 20 69 6e 20 74 68 61 74 20 73 74 72  ytes in that str
2afc0 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ing..** ^If the 
2afd0 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20  result is NULL, 
2afe0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  then sqlite3_col
2aff0 75 6d 6e 5f 62 79 74 65 73 28 29 20 72 65 74 75  umn_bytes() retu
2b000 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20  rns zero..**.** 
2b010 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69  ^If the result i
2b020 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d  s a BLOB or UTF-
2b030 31 36 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74  16 string then t
2b040 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  he sqlite3_colum
2b050 6e 5f 62 79 74 65 73 31 36 28 29 0a 2a 2a 20 72  n_bytes16().** r
2b060 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
2b070 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
2b080 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20  es in that BLOB 
2b090 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49  or string..** ^I
2b0a0 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
2b0b0 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2c 20  a UTF-8 string, 
2b0c0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  then sqlite3_col
2b0d0 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 63 6f  umn_bytes16() co
2b0e0 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74  nverts.** the st
2b0f0 72 69 6e 67 20 74 6f 20 55 54 46 2d 31 36 20 61  ring to UTF-16 a
2b100 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20  nd then returns 
2b110 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
2b120 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  tes..** ^If the 
2b130 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65  result is a nume
2b140 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73  ric value then s
2b150 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2b160 74 65 73 31 36 28 29 20 75 73 65 73 0a 2a 2a 20  tes16() uses.** 
2b170 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74  [sqlite3_snprint
2b180 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20  f()] to convert 
2b190 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20  that value to a 
2b1a0 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 61 6e  UTF-16 string an
2b1b0 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65  d returns.** the
2b1c0 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
2b1d0 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e   in that string.
2b1e0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
2b1f0 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e  lt is NULL, then
2b200 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2b210 62 79 74 65 73 31 36 28 29 20 72 65 74 75 72 6e  bytes16() return
2b220 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 54  s zero..**.** ^T
2b230 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e  he values return
2b240 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63  ed by [sqlite3_c
2b250 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61  olumn_bytes()] a
2b260 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  nd .** [sqlite3_
2b270 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
2b280 5d 20 64 6f 20 6e 6f 74 20 69 6e 63 6c 75 64 65  ] do not include
2b290 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e   the zero termin
2b2a0 61 74 6f 72 73 20 61 74 20 74 68 65 20 65 6e 64  ators at the end
2b2b0 0a 2a 2a 20 6f 66 20 74 68 65 20 73 74 72 69 6e  .** of the strin
2b2c0 67 2e 20 20 5e 46 6f 72 20 63 6c 61 72 69 74 79  g.  ^For clarity
2b2d0 3a 20 74 68 65 20 76 61 6c 75 65 73 20 72 65 74  : the values ret
2b2e0 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c  urned by.** [sql
2b2f0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2b300 73 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  s()] and [sqlite
2b310 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
2b320 28 29 5d 20 61 72 65 20 74 68 65 20 6e 75 6d 62  ()] are the numb
2b330 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69  er of.** bytes i
2b340 6e 20 74 68 65 20 73 74 72 69 6e 67 2c 20 6e 6f  n the string, no
2b350 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  t the number of 
2b360 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a  characters..**.*
2b370 2a 20 5e 53 74 72 69 6e 67 73 20 72 65 74 75 72  * ^Strings retur
2b380 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  ned by sqlite3_c
2b390 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 61 6e 64  olumn_text() and
2b3a0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2b3b0 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 65 76 65  text16(),.** eve
2b3c0 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 73 2c  n empty strings,
2b3d0 20 61 72 65 20 61 6c 77 61 79 73 20 7a 65 72 6f   are always zero
2b3e0 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54  -terminated.  ^T
2b3f0 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c  he return.** val
2b400 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ue from sqlite3_
2b410 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f  column_blob() fo
2b420 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20  r a zero-length 
2b430 42 4c 4f 42 20 69 73 20 61 20 4e 55 4c 4c 20 70  BLOB is a NULL p
2b440 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ointer..**.** ^T
2b450 68 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e  he object return
2b460 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63  ed by [sqlite3_c
2b470 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69  olumn_value()] i
2b480 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65  s an.** [unprote
2b490 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
2b4a0 75 65 5d 20 6f 62 6a 65 63 74 2e 20 20 41 6e 20  ue] object.  An 
2b4b0 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
2b4c0 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
2b4d0 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20  .** may only be 
2b4e0 75 73 65 64 20 77 69 74 68 20 5b 73 71 6c 69 74  used with [sqlit
2b4f0 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d  e3_bind_value()]
2b500 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65   and [sqlite3_re
2b510 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a  sult_value()]..*
2b520 2a 20 49 66 20 74 68 65 20 5b 75 6e 70 72 6f 74  * If the [unprot
2b530 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
2b540 6c 75 65 5d 20 6f 62 6a 65 63 74 20 72 65 74 75  lue] object retu
2b550 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69  rned by.** [sqli
2b560 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65  te3_column_value
2b570 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e 20 61  ()] is used in a
2b580 6e 79 20 6f 74 68 65 72 20 77 61 79 2c 20 69 6e  ny other way, in
2b590 63 6c 75 64 69 6e 67 20 63 61 6c 6c 73 0a 2a 2a  cluding calls.**
2b5a0 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b   to routines lik
2b5b0 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
2b5c0 5f 69 6e 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65  _int()], [sqlite
2b5d0 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c  3_value_text()],
2b5e0 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  .** or [sqlite3_
2b5f0 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20  value_bytes()], 
2b600 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
2b610 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  r is undefined..
2b620 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
2b630 69 6e 65 73 20 61 74 74 65 6d 70 74 20 74 6f 20  ines attempt to 
2b640 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75  convert the valu
2b650 65 20 77 68 65 72 65 20 61 70 70 72 6f 70 72 69  e where appropri
2b660 61 74 65 2e 20 20 5e 46 6f 72 0a 2a 2a 20 65 78  ate.  ^For.** ex
2b670 61 6d 70 6c 65 2c 20 69 66 20 74 68 65 20 69 6e  ample, if the in
2b680 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74  ternal represent
2b690 61 74 69 6f 6e 20 69 73 20 46 4c 4f 41 54 20 61  ation is FLOAT a
2b6a0 6e 64 20 61 20 74 65 78 74 20 72 65 73 75 6c 74  nd a text result
2b6b0 0a 2a 2a 20 69 73 20 72 65 71 75 65 73 74 65 64  .** is requested
2b6c0 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  , [sqlite3_snpri
2b6d0 6e 74 66 28 29 5d 20 69 73 20 75 73 65 64 20 69  ntf()] is used i
2b6e0 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20 70 65 72  nternally to per
2b6f0 66 6f 72 6d 20 74 68 65 0a 2a 2a 20 63 6f 6e 76  form the.** conv
2b700 65 72 73 69 6f 6e 20 61 75 74 6f 6d 61 74 69 63  ersion automatic
2b710 61 6c 6c 79 2e 20 20 5e 28 54 68 65 20 66 6f 6c  ally.  ^(The fol
2b720 6c 6f 77 69 6e 67 20 74 61 62 6c 65 20 64 65 74  lowing table det
2b730 61 69 6c 73 20 74 68 65 20 63 6f 6e 76 65 72 73  ails the convers
2b740 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 20 61 72 65  ions.** that are
2b750 20 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20   applied:.**.** 
2b760 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20  <blockquote>.** 
2b770 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31  <table border="1
2b780 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 49  ">.** <tr><th> I
2b790 6e 74 65 72 6e 61 6c 3c 62 72 3e 54 79 70 65 20  nternal<br>Type 
2b7a0 3c 74 68 3e 20 52 65 71 75 65 73 74 65 64 3c 62  <th> Requested<b
2b7b0 72 3e 54 79 70 65 20 3c 74 68 3e 20 20 43 6f 6e  r>Type <th>  Con
2b7c0 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74  version.**.** <t
2b7d0 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20  r><td>  NULL    
2b7e0 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c  <td> INTEGER   <
2b7f0 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30 0a  td> Result is 0.
2b800 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c  ** <tr><td>  NUL
2b810 4c 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54  L    <td>  FLOAT
2b820 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20      <td> Result 
2b830 69 73 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74  is 0.0.** <tr><t
2b840 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e  d>  NULL    <td>
2b850 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20     TEXT    <td> 
2b860 52 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20 70  Result is NULL p
2b870 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74  ointer.** <tr><t
2b880 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e  d>  NULL    <td>
2b890 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20     BLOB    <td> 
2b8a0 52 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20 70  Result is NULL p
2b8b0 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74  ointer.** <tr><t
2b8c0 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e  d> INTEGER  <td>
2b8d0 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20    FLOAT    <td> 
2b8e0 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 69 6e 74  Convert from int
2b8f0 65 67 65 72 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a  eger to float.**
2b900 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45   <tr><td> INTEGE
2b910 52 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20  R  <td>   TEXT  
2b920 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e    <td> ASCII ren
2b930 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 69 6e  dering of the in
2b940 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64  teger.** <tr><td
2b950 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20  > INTEGER  <td> 
2b960 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53    BLOB    <td> S
2b970 61 6d 65 20 61 73 20 49 4e 54 45 47 45 52 2d 3e  ame as INTEGER->
2b980 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  TEXT.** <tr><td>
2b990 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 49    FLOAT   <td> I
2b9a0 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 43 6f  NTEGER   <td> Co
2b9b0 6e 76 65 72 74 20 66 72 6f 6d 20 66 6c 6f 61 74  nvert from float
2b9c0 20 74 6f 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c   to integer.** <
2b9d0 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20  tr><td>  FLOAT  
2b9e0 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20   <td>   TEXT    
2b9f0 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65  <td> ASCII rende
2ba00 72 69 6e 67 20 6f 66 20 74 68 65 20 66 6c 6f 61  ring of the floa
2ba10 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46  t.** <tr><td>  F
2ba20 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 42 4c  LOAT   <td>   BL
2ba30 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20  OB    <td> Same 
2ba40 61 73 20 46 4c 4f 41 54 2d 3e 54 45 58 54 0a 2a  as FLOAT->TEXT.*
2ba50 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54  * <tr><td>  TEXT
2ba60 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52      <td> INTEGER
2ba70 20 20 20 3c 74 64 3e 20 55 73 65 20 61 74 6f 69     <td> Use atoi
2ba80 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  ().** <tr><td>  
2ba90 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20 46 4c  TEXT    <td>  FL
2baa0 4f 41 54 20 20 20 20 3c 74 64 3e 20 55 73 65 20  OAT    <td> Use 
2bab0 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74  atof().** <tr><t
2bac0 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  d>  TEXT    <td>
2bad0 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20     BLOB    <td> 
2bae0 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 3c 74 72  No change.** <tr
2baf0 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c  ><td>  BLOB    <
2bb00 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74  td> INTEGER   <t
2bb10 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20 54 45  d> Convert to TE
2bb20 58 54 20 74 68 65 6e 20 75 73 65 20 61 74 6f 69  XT then use atoi
2bb30 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  ().** <tr><td>  
2bb40 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 46 4c  BLOB    <td>  FL
2bb50 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76  OAT    <td> Conv
2bb60 65 72 74 20 74 6f 20 54 45 58 54 20 74 68 65 6e  ert to TEXT then
2bb70 20 75 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c   use atof().** <
2bb80 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20  tr><td>  BLOB   
2bb90 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20   <td>   TEXT    
2bba0 3c 74 64 3e 20 41 64 64 20 61 20 7a 65 72 6f 20  <td> Add a zero 
2bbb0 74 65 72 6d 69 6e 61 74 6f 72 20 69 66 20 6e 65  terminator if ne
2bbc0 65 64 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e  eded.** </table>
2bbd0 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  .** </blockquote
2bbe0 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61  >)^.**.** The ta
2bbf0 62 6c 65 20 61 62 6f 76 65 20 6d 61 6b 65 73 20  ble above makes 
2bc00 72 65 66 65 72 65 6e 63 65 20 74 6f 20 73 74 61  reference to sta
2bc10 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 20  ndard C library 
2bc20 66 75 6e 63 74 69 6f 6e 73 20 61 74 6f 69 28 29  functions atoi()
2bc30 0a 2a 2a 20 61 6e 64 20 61 74 6f 66 28 29 2e 20  .** and atof(). 
2bc40 20 53 51 4c 69 74 65 20 64 6f 65 73 20 6e 6f 74   SQLite does not
2bc50 20 72 65 61 6c 6c 79 20 75 73 65 20 74 68 65 73   really use thes
2bc60 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 49 74  e functions.  It
2bc70 20 68 61 73 20 69 74 73 0a 2a 2a 20 6f 77 6e 20   has its.** own 
2bc80 65 71 75 69 76 61 6c 65 6e 74 20 69 6e 74 65 72  equivalent inter
2bc90 6e 61 6c 20 72 6f 75 74 69 6e 65 73 2e 20 20 54  nal routines.  T
2bca0 68 65 20 61 74 6f 69 28 29 20 61 6e 64 20 61 74  he atoi() and at
2bcb0 6f 66 28 29 20 6e 61 6d 65 73 20 61 72 65 0a 2a  of() names are.*
2bcc0 2a 20 75 73 65 64 20 69 6e 20 74 68 65 20 74 61  * used in the ta
2bcd0 62 6c 65 20 66 6f 72 20 62 72 65 76 69 74 79 20  ble for brevity 
2bce0 61 6e 64 20 62 65 63 61 75 73 65 20 74 68 65 79  and because they
2bcf0 20 61 72 65 20 66 61 6d 69 6c 69 61 72 20 74 6f   are familiar to
2bd00 20 6d 6f 73 74 0a 2a 2a 20 43 20 70 72 6f 67 72   most.** C progr
2bd10 61 6d 6d 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f  ammers..**.** No
2bd20 74 65 20 74 68 61 74 20 77 68 65 6e 20 74 79 70  te that when typ
2bd30 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 6f 63  e conversions oc
2bd40 63 75 72 2c 20 70 6f 69 6e 74 65 72 73 20 72 65  cur, pointers re
2bd50 74 75 72 6e 65 64 20 62 79 20 70 72 69 6f 72 0a  turned by prior.
2bd60 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  ** calls to sqli
2bd70 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
2bd80 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ), sqlite3_colum
2bd90 6e 5f 74 65 78 74 28 29 2c 20 61 6e 64 2f 6f 72  n_text(), and/or
2bda0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
2bdb0 6d 6e 5f 74 65 78 74 31 36 28 29 20 6d 61 79 20  mn_text16() may 
2bdc0 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a  be invalidated..
2bdd0 2a 2a 20 54 79 70 65 20 63 6f 6e 76 65 72 73 69  ** Type conversi
2bde0 6f 6e 73 20 61 6e 64 20 70 6f 69 6e 74 65 72 20  ons and pointer 
2bdf0 69 6e 76 61 6c 69 64 61 74 69 6f 6e 73 20 6d 69  invalidations mi
2be00 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20  ght occur.** in 
2be10 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61  the following ca
2be20 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ses:.**.** <ul>.
2be30 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74  ** <li> The init
2be40 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 61  ial content is a
2be50 20 42 4c 4f 42 20 61 6e 64 20 73 71 6c 69 74 65   BLOB and sqlite
2be60 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20  3_column_text() 
2be70 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74  or.**      sqlit
2be80 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
2be90 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 41  () is called.  A
2bea0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72   zero-terminator
2beb0 20 6d 69 67 68 74 0a 2a 2a 20 20 20 20 20 20 6e   might.**      n
2bec0 65 65 64 20 74 6f 20 62 65 20 61 64 64 65 64 20  eed to be added 
2bed0 74 6f 20 74 68 65 20 73 74 72 69 6e 67 2e 3c 2f  to the string.</
2bee0 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20  li>.** <li> The 
2bef0 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20  initial content 
2bf00 69 73 20 55 54 46 2d 38 20 74 65 78 74 20 61 6e  is UTF-8 text an
2bf10 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  d sqlite3_column
2bf20 5f 62 79 74 65 73 31 36 28 29 20 6f 72 0a 2a 2a  _bytes16() or.**
2bf30 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f        sqlite3_co
2bf40 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73  lumn_text16() is
2bf50 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f   called.  The co
2bf60 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f  ntent must be co
2bf70 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20  nverted.**      
2bf80 74 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c 69 3e 0a  to UTF-16.</li>.
2bf90 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74  ** <li> The init
2bfa0 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55  ial content is U
2bfb0 54 46 2d 31 36 20 74 65 78 74 20 61 6e 64 20 73  TF-16 text and s
2bfc0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2bfd0 74 65 73 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20  tes() or.**     
2bfe0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2bff0 74 65 78 74 28 29 20 69 73 20 63 61 6c 6c 65 64  text() is called
2c000 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d  .  The content m
2c010 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64  ust be converted
2c020 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d  .**      to UTF-
2c030 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e  8.</li>.** </ul>
2c040 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 76 65 72 73 69  .**.** ^Conversi
2c050 6f 6e 73 20 62 65 74 77 65 65 6e 20 55 54 46 2d  ons between UTF-
2c060 31 36 62 65 20 61 6e 64 20 55 54 46 2d 31 36 6c  16be and UTF-16l
2c070 65 20 61 72 65 20 61 6c 77 61 79 73 20 64 6f 6e  e are always don
2c080 65 20 69 6e 20 70 6c 61 63 65 20 61 6e 64 20 64  e in place and d
2c090 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61 6c 69 64  o.** not invalid
2c0a0 61 74 65 20 61 20 70 72 69 6f 72 20 70 6f 69 6e  ate a prior poin
2c0b0 74 65 72 2c 20 74 68 6f 75 67 68 20 6f 66 20 63  ter, though of c
2c0c0 6f 75 72 73 65 20 74 68 65 20 63 6f 6e 74 65 6e  ourse the conten
2c0d0 74 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 0a  t of the buffer.
2c0e0 2a 2a 20 74 68 61 74 20 74 68 65 20 70 72 69 6f  ** that the prio
2c0f0 72 20 70 6f 69 6e 74 65 72 20 72 65 66 65 72 65  r pointer refere
2c100 6e 63 65 73 20 77 69 6c 6c 20 68 61 76 65 20 62  nces will have b
2c110 65 65 6e 20 6d 6f 64 69 66 69 65 64 2e 20 20 4f  een modified.  O
2c120 74 68 65 72 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66  ther kinds.** of
2c130 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 72 65 20   conversion are 
2c140 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 77 68  done in place wh
2c150 65 6e 20 69 74 20 69 73 20 70 6f 73 73 69 62 6c  en it is possibl
2c160 65 2c 20 62 75 74 20 73 6f 6d 65 74 69 6d 65 73  e, but sometimes
2c170 20 74 68 65 79 0a 2a 2a 20 61 72 65 20 6e 6f 74   they.** are not
2c180 20 70 6f 73 73 69 62 6c 65 20 61 6e 64 20 69 6e   possible and in
2c190 20 74 68 6f 73 65 20 63 61 73 65 73 20 70 72 69   those cases pri
2c1a0 6f 72 20 70 6f 69 6e 74 65 72 73 20 61 72 65 20  or pointers are 
2c1b0 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 0a  invalidated..**.
2c1c0 2a 2a 20 54 68 65 20 73 61 66 65 73 74 20 61 6e  ** The safest an
2c1d0 64 20 65 61 73 69 65 73 74 20 74 6f 20 72 65 6d  d easiest to rem
2c1e0 65 6d 62 65 72 20 70 6f 6c 69 63 79 20 69 73 20  ember policy is 
2c1f0 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 73 65 20  to invoke these 
2c200 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f  routines.** in o
2c210 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77  ne of the follow
2c220 69 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20  ing ways:.**.** 
2c230 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c  <ul>.**  <li>sql
2c240 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2c250 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73  () followed by s
2c260 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2c270 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c  tes()</li>.**  <
2c280 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  li>sqlite3_colum
2c290 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77 65  n_blob() followe
2c2a0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
2c2b0 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e  umn_bytes()</li>
2c2c0 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33  .**  <li>sqlite3
2c2d0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
2c2e0 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c   followed by sql
2c2f0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2c300 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f  s16()</li>.** </
2c310 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68  ul>.**.** In oth
2c320 65 72 20 77 6f 72 64 73 2c 20 79 6f 75 20 73 68  er words, you sh
2c330 6f 75 6c 64 20 63 61 6c 6c 20 73 71 6c 69 74 65  ould call sqlite
2c340 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c  3_column_text(),
2c350 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
2c360 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72 20 73 71  mn_blob(), or sq
2c370 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
2c380 74 31 36 28 29 20 66 69 72 73 74 20 74 6f 20 66  t16() first to f
2c390 6f 72 63 65 20 74 68 65 20 72 65 73 75 6c 74 0a  orce the result.
2c3a0 2a 2a 20 69 6e 74 6f 20 74 68 65 20 64 65 73 69  ** into the desi
2c3b0 72 65 64 20 66 6f 72 6d 61 74 2c 20 74 68 65 6e  red format, then
2c3c0 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f   invoke sqlite3_
2c3d0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f  column_bytes() o
2c3e0 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c  r.** sqlite3_col
2c3f0 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 74 6f  umn_bytes16() to
2c400 20 66 69 6e 64 20 74 68 65 20 73 69 7a 65 20 6f   find the size o
2c410 66 20 74 68 65 20 72 65 73 75 6c 74 2e 20 20 44  f the result.  D
2c420 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 0a  o not mix calls.
2c430 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ** to sqlite3_co
2c440 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 20 73  lumn_text() or s
2c450 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
2c460 6f 62 28 29 20 77 69 74 68 20 63 61 6c 6c 73 20  ob() with calls 
2c470 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  to.** sqlite3_co
2c480 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 2c 20  lumn_bytes16(), 
2c490 61 6e 64 20 64 6f 20 6e 6f 74 20 6d 69 78 20 63  and do not mix c
2c4a0 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
2c4b0 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 0a  column_text16().
2c4c0 2a 2a 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f  ** with calls to
2c4d0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2c4e0 62 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e  bytes()..**.** ^
2c4f0 54 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74  The pointers ret
2c500 75 72 6e 65 64 20 61 72 65 20 76 61 6c 69 64 20  urned are valid 
2c510 75 6e 74 69 6c 20 61 20 74 79 70 65 20 63 6f 6e  until a type con
2c520 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 20 61  version occurs a
2c530 73 0a 2a 2a 20 64 65 73 63 72 69 62 65 64 20 61  s.** described a
2c540 62 6f 76 65 2c 20 6f 72 20 75 6e 74 69 6c 20 5b  bove, or until [
2c550 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
2c560 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  or [sqlite3_rese
2c570 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  t()] or.** [sqli
2c580 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
2c590 69 73 20 63 61 6c 6c 65 64 2e 20 20 5e 54 68 65  is called.  ^The
2c5a0 20 6d 65 6d 6f 72 79 20 73 70 61 63 65 20 75 73   memory space us
2c5b0 65 64 20 74 6f 20 68 6f 6c 64 20 73 74 72 69 6e  ed to hold strin
2c5c0 67 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f 42 73 20  gs.** and BLOBs 
2c5d0 69 73 20 66 72 65 65 64 20 61 75 74 6f 6d 61 74  is freed automat
2c5e0 69 63 61 6c 6c 79 2e 20 20 44 6f 20 3c 62 3e 6e  ically.  Do <b>n
2c5f0 6f 74 3c 2f 62 3e 20 70 61 73 73 20 74 68 65 20  ot</b> pass the 
2c600 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65  pointers returne
2c610 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d.** [sqlite3_co
2c620 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73  lumn_blob()], [s
2c630 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2c640 78 74 28 29 5d 2c 20 65 74 63 2e 20 69 6e 74 6f  xt()], etc. into
2c650 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  .** [sqlite3_fre
2c660 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66  e()]..**.** ^(If
2c670 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
2c680 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  tion error occur
2c690 73 20 64 75 72 69 6e 67 20 74 68 65 20 65 76 61  s during the eva
2c6a0 6c 75 61 74 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a  luation of any.*
2c6b0 2a 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  * of these routi
2c6c0 6e 65 73 2c 20 61 20 64 65 66 61 75 6c 74 20 76  nes, a default v
2c6d0 61 6c 75 65 20 69 73 20 72 65 74 75 72 6e 65 64  alue is returned
2c6e0 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 76  .  The default v
2c6f0 61 6c 75 65 0a 2a 2a 20 69 73 20 65 69 74 68 65  alue.** is eithe
2c700 72 20 74 68 65 20 69 6e 74 65 67 65 72 20 30 2c  r the integer 0,
2c710 20 74 68 65 20 66 6c 6f 61 74 69 6e 67 20 70 6f   the floating po
2c720 69 6e 74 20 6e 75 6d 62 65 72 20 30 2e 30 2c 20  int number 0.0, 
2c730 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69  or a NULL.** poi
2c740 6e 74 65 72 2e 20 20 53 75 62 73 65 71 75 65 6e  nter.  Subsequen
2c750 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  t calls to [sqli
2c760 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 77  te3_errcode()] w
2c770 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53  ill return.** [S
2c780 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 29 5e 0a  QLITE_NOMEM].)^.
2c790 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  */.const void *s
2c7a0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
2c7b0 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ob(sqlite3_stmt*
2c7c0 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74  , int iCol);.int
2c7d0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2c7e0 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f 73 74  bytes(sqlite3_st
2c7f0 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
2c800 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  int sqlite3_colu
2c810 6d 6e 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74  mn_bytes16(sqlit
2c820 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
2c830 6f 6c 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69  ol);.double sqli
2c840 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c  te3_column_doubl
2c850 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
2c860 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20   int iCol);.int 
2c870 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69  sqlite3_column_i
2c880 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  nt(sqlite3_stmt*
2c890 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c  , int iCol);.sql
2c8a0 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74  ite3_int64 sqlit
2c8b0 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28  e3_column_int64(
2c8c0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2c8d0 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20  nt iCol);.const 
2c8e0 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73  unsigned char *s
2c8f0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2c900 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  xt(sqlite3_stmt*
2c910 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e  , int iCol);.con
2c920 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
2c930 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 73  _column_text16(s
2c940 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2c950 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c  t iCol);.int sql
2c960 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
2c970 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2c980 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74  int iCol);.sqlit
2c990 65 33 5f 76 61 6c 75 65 20 2a 73 71 6c 69 74 65  e3_value *sqlite
2c9a0 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 73  3_column_value(s
2c9b0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2c9c0 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20  t iCol);../*.** 
2c9d0 43 41 50 49 33 52 45 46 3a 20 44 65 73 74 72 6f  CAPI3REF: Destro
2c9e0 79 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61  y A Prepared Sta
2c9f0 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a  tement Object.**
2ca00 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2ca10 5f 66 69 6e 61 6c 69 7a 65 28 29 20 66 75 6e 63  _finalize() func
2ca20 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74  tion is called t
2ca30 6f 20 64 65 6c 65 74 65 20 61 20 5b 70 72 65 70  o delete a [prep
2ca40 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
2ca50 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74  .** ^If the most
2ca60 20 72 65 63 65 6e 74 20 65 76 61 6c 75 61 74 69   recent evaluati
2ca70 6f 6e 20 6f 66 20 74 68 65 20 73 74 61 74 65 6d  on of the statem
2ca80 65 6e 74 20 65 6e 63 6f 75 6e 74 65 72 65 64 20  ent encountered 
2ca90 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a 20 6f 72 20  no errors.** or 
2caa0 69 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  if the statement
2cab0 20 69 73 20 6e 65 76 65 72 20 62 65 65 6e 20 65   is never been e
2cac0 76 61 6c 75 61 74 65 64 2c 20 74 68 65 6e 20 73  valuated, then s
2cad0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2cae0 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 53 51 4c  ) returns.** SQL
2caf0 49 54 45 5f 4f 4b 2e 20 20 5e 49 66 20 74 68 65  ITE_OK.  ^If the
2cb00 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 76 61   most recent eva
2cb10 6c 75 61 74 69 6f 6e 20 6f 66 20 73 74 61 74 65  luation of state
2cb20 6d 65 6e 74 20 53 20 66 61 69 6c 65 64 2c 20 74  ment S failed, t
2cb30 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66  hen.** sqlite3_f
2cb40 69 6e 61 6c 69 7a 65 28 53 29 20 72 65 74 75 72  inalize(S) retur
2cb50 6e 73 20 74 68 65 20 61 70 70 72 6f 70 72 69 61  ns the appropria
2cb60 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  te [error code] 
2cb70 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20  or.** [extended 
2cb80 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a  error code]..**.
2cb90 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2cba0 66 69 6e 61 6c 69 7a 65 28 53 29 20 72 6f 75 74  finalize(S) rout
2cbb0 69 6e 65 20 63 61 6e 20 62 65 20 63 61 6c 6c 65  ine can be calle
2cbc0 64 20 61 74 20 61 6e 79 20 70 6f 69 6e 74 20 64  d at any point d
2cbd0 75 72 69 6e 67 0a 2a 2a 20 74 68 65 20 6c 69 66  uring.** the lif
2cbe0 65 20 63 79 63 6c 65 20 6f 66 20 5b 70 72 65 70  e cycle of [prep
2cbf0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2cc00 53 3a 0a 2a 2a 20 62 65 66 6f 72 65 20 73 74 61  S:.** before sta
2cc10 74 65 6d 65 6e 74 20 53 20 69 73 20 65 76 65 72  tement S is ever
2cc20 20 65 76 61 6c 75 61 74 65 64 2c 20 61 66 74 65   evaluated, afte
2cc30 72 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  r.** one or more
2cc40 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   calls to [sqlit
2cc50 65 33 5f 72 65 73 65 74 28 29 5d 2c 20 6f 72 20  e3_reset()], or 
2cc60 61 66 74 65 72 20 61 6e 79 20 63 61 6c 6c 0a 2a  after any call.*
2cc70 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74  * to [sqlite3_st
2cc80 65 70 28 29 5d 20 72 65 67 61 72 64 6c 65 73 73  ep()] regardless
2cc90 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e   of whether or n
2cca0 6f 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  ot the statement
2ccb0 20 68 61 73 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65   has.** complete
2ccc0 64 20 65 78 65 63 75 74 69 6f 6e 2e 0a 2a 2a 0a  d execution..**.
2ccd0 2a 2a 20 5e 49 6e 76 6f 6b 69 6e 67 20 73 71 6c  ** ^Invoking sql
2cce0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20  ite3_finalize() 
2ccf0 6f 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  on a NULL pointe
2cd00 72 20 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20  r is a harmless 
2cd10 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  no-op..**.** The
2cd20 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
2cd30 74 20 66 69 6e 61 6c 69 7a 65 20 65 76 65 72 79  t finalize every
2cd40 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2cd50 6d 65 6e 74 5d 20 69 6e 20 6f 72 64 65 72 20 74  ment] in order t
2cd60 6f 20 61 76 6f 69 64 0a 2a 2a 20 72 65 73 6f 75  o avoid.** resou
2cd70 72 63 65 20 6c 65 61 6b 73 2e 20 20 49 74 20 69  rce leaks.  It i
2cd80 73 20 61 20 67 72 69 65 76 6f 75 73 20 65 72 72  s a grievous err
2cd90 6f 72 20 66 6f 72 20 74 68 65 20 61 70 70 6c 69  or for the appli
2cda0 63 61 74 69 6f 6e 20 74 6f 20 74 72 79 20 74 6f  cation to try to
2cdb0 20 75 73 65 0a 2a 2a 20 61 20 70 72 65 70 61 72   use.** a prepar
2cdc0 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74  ed statement aft
2cdd0 65 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 66  er it has been f
2cde0 69 6e 61 6c 69 7a 65 64 2e 20 20 41 6e 79 20 75  inalized.  Any u
2cdf0 73 65 20 6f 66 20 61 20 70 72 65 70 61 72 65 64  se of a prepared
2ce00 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 66  .** statement af
2ce10 74 65 72 20 69 74 20 68 61 73 20 62 65 65 6e 20  ter it has been 
2ce20 66 69 6e 61 6c 69 7a 65 64 20 63 61 6e 20 72 65  finalized can re
2ce30 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e 65  sult in undefine
2ce40 64 20 61 6e 64 0a 2a 2a 20 75 6e 64 65 73 69 72  d and.** undesir
2ce50 61 62 6c 65 20 62 65 68 61 76 69 6f 72 20 73 75  able behavior su
2ce60 63 68 20 61 73 20 73 65 67 66 61 75 6c 74 73 20  ch as segfaults 
2ce70 61 6e 64 20 68 65 61 70 20 63 6f 72 72 75 70 74  and heap corrupt
2ce80 69 6f 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ion..*/.int sqli
2ce90 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 73 71 6c  te3_finalize(sql
2cea0 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
2ceb0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2cec0 45 46 3a 20 52 65 73 65 74 20 41 20 50 72 65 70  EF: Reset A Prep
2ced0 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f  ared Statement O
2cee0 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20  bject.**.** The 
2cef0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 20  sqlite3_reset() 
2cf00 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c  function is call
2cf10 65 64 20 74 6f 20 72 65 73 65 74 20 61 20 5b 70  ed to reset a [p
2cf20 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2cf30 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 62 61 63  t].** object bac
2cf40 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c  k to its initial
2cf50 20 73 74 61 74 65 2c 20 72 65 61 64 79 20 74 6f   state, ready to
2cf60 20 62 65 20 72 65 2d 65 78 65 63 75 74 65 64 2e   be re-executed.
2cf70 0a 2a 2a 20 5e 41 6e 79 20 53 51 4c 20 73 74 61  .** ^Any SQL sta
2cf80 74 65 6d 65 6e 74 20 76 61 72 69 61 62 6c 65 73  tement variables
2cf90 20 74 68 61 74 20 68 61 64 20 76 61 6c 75 65 73   that had values
2cfa0 20 62 6f 75 6e 64 20 74 6f 20 74 68 65 6d 20 75   bound to them u
2cfb0 73 69 6e 67 0a 2a 2a 20 74 68 65 20 5b 73 71 6c  sing.** the [sql
2cfc0 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c  ite3_bind_blob |
2cfd0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28   sqlite3_bind_*(
2cfe0 29 20 41 50 49 5d 20 72 65 74 61 69 6e 20 74 68  ) API] retain th
2cff0 65 69 72 20 76 61 6c 75 65 73 2e 0a 2a 2a 20 55  eir values..** U
2d000 73 65 20 5b 73 71 6c 69 74 65 33 5f 63 6c 65 61  se [sqlite3_clea
2d010 72 5f 62 69 6e 64 69 6e 67 73 28 29 5d 20 74 6f  r_bindings()] to
2d020 20 72 65 73 65 74 20 74 68 65 20 62 69 6e 64 69   reset the bindi
2d030 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ngs..**.** ^The 
2d040 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53  [sqlite3_reset(S
2d050 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 73  )] interface res
2d060 65 74 73 20 74 68 65 20 5b 70 72 65 70 61 72 65  ets the [prepare
2d070 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 0a 2a  d statement] S.*
2d080 2a 20 62 61 63 6b 20 74 6f 20 74 68 65 20 62 65  * back to the be
2d090 67 69 6e 6e 69 6e 67 20 6f 66 20 69 74 73 20 70  ginning of its p
2d0a0 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 49  rogram..**.** ^I
2d0b0 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  f the most recen
2d0c0 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  t call to [sqlit
2d0d0 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20  e3_step(S)] for 
2d0e0 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
2d0f0 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 72 65   statement] S re
2d100 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52  turned [SQLITE_R
2d110 4f 57 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44  OW] or [SQLITE_D
2d120 4f 4e 45 5d 2c 0a 2a 2a 20 6f 72 20 69 66 20 5b  ONE],.** or if [
2d130 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d  sqlite3_step(S)]
2d140 20 68 61 73 20 6e 65 76 65 72 20 62 65 66 6f 72   has never befor
2d150 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6f 6e  e been called on
2d160 20 53 2c 0a 2a 2a 20 74 68 65 6e 20 5b 73 71 6c   S,.** then [sql
2d170 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72  ite3_reset(S)] r
2d180 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
2d190 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  K]..**.** ^If th
2d1a0 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61  e most recent ca
2d1b0 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ll to [sqlite3_s
2d1c0 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a  tep(S)] for the.
2d1d0 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
2d1e0 74 65 6d 65 6e 74 5d 20 53 20 69 6e 64 69 63 61  tement] S indica
2d1f0 74 65 64 20 61 6e 20 65 72 72 6f 72 2c 20 74 68  ted an error, th
2d200 65 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72  en.** [sqlite3_r
2d210 65 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73  eset(S)] returns
2d220 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20   an appropriate 
2d230 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a  [error code]..**
2d240 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65  .** ^The [sqlite
2d250 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65  3_reset(S)] inte
2d260 72 66 61 63 65 20 64 6f 65 73 20 6e 6f 74 20 63  rface does not c
2d270 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65 73  hange the values
2d280 0a 2a 2a 20 6f 66 20 61 6e 79 20 5b 73 71 6c 69  .** of any [sqli
2d290 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 62 69  te3_bind_blob|bi
2d2a0 6e 64 69 6e 67 73 5d 20 6f 6e 20 74 68 65 20 5b  ndings] on the [
2d2b0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2d2c0 6e 74 5d 20 53 2e 0a 2a 2f 0a 69 6e 74 20 73 71  nt] S..*/.int sq
2d2d0 6c 69 74 65 33 5f 72 65 73 65 74 28 73 71 6c 69  lite3_reset(sqli
2d2e0 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
2d2f0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2d300 46 3a 20 43 72 65 61 74 65 20 4f 72 20 52 65 64  F: Create Or Red
2d310 65 66 69 6e 65 20 53 51 4c 20 46 75 6e 63 74 69  efine SQL Functi
2d320 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ons.** KEYWORDS:
2d330 20 7b 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74   {function creat
2d340 69 6f 6e 20 72 6f 75 74 69 6e 65 73 7d 0a 2a 2a  ion routines}.**
2d350 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c   KEYWORDS: {appl
2d360 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
2d370 53 51 4c 20 66 75 6e 63 74 69 6f 6e 7d 0a 2a 2a  SQL function}.**
2d380 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c   KEYWORDS: {appl
2d390 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
2d3a0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a  SQL functions}.*
2d3b0 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e 63  *.** ^These func
2d3c0 74 69 6f 6e 73 20 28 63 6f 6c 6c 65 63 74 69 76  tions (collectiv
2d3d0 65 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 22 66 75  ely known as "fu
2d3e0 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20  nction creation 
2d3f0 72 6f 75 74 69 6e 65 73 22 29 0a 2a 2a 20 61 72  routines").** ar
2d400 65 20 75 73 65 64 20 74 6f 20 61 64 64 20 53 51  e used to add SQ
2d410 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61  L functions or a
2d420 67 67 72 65 67 61 74 65 73 20 6f 72 20 74 6f 20  ggregates or to 
2d430 72 65 64 65 66 69 6e 65 20 74 68 65 20 62 65 68  redefine the beh
2d440 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 65 78 69 73  avior.** of exis
2d450 74 69 6e 67 20 53 51 4c 20 66 75 6e 63 74 69 6f  ting SQL functio
2d460 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 65 73  ns or aggregates
2d470 2e 20 20 54 68 65 20 6f 6e 6c 79 20 64 69 66 66  .  The only diff
2d480 65 72 65 6e 63 65 73 20 62 65 74 77 65 65 6e 0a  erences between.
2d490 2a 2a 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  ** these routine
2d4a0 73 20 61 72 65 20 74 68 65 20 74 65 78 74 20 65  s are the text e
2d4b0 6e 63 6f 64 69 6e 67 20 65 78 70 65 63 74 65 64  ncoding expected
2d4c0 20 66 6f 72 0a 2a 2a 20 74 68 65 20 73 65 63 6f   for.** the seco
2d4d0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 28 74 68  nd parameter (th
2d4e0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 66 75  e name of the fu
2d4f0 6e 63 74 69 6f 6e 20 62 65 69 6e 67 20 63 72 65  nction being cre
2d500 61 74 65 64 29 0a 2a 2a 20 61 6e 64 20 74 68 65  ated).** and the
2d510 20 70 72 65 73 65 6e 63 65 20 6f 72 20 61 62 73   presence or abs
2d520 65 6e 63 65 20 6f 66 20 61 20 64 65 73 74 72 75  ence of a destru
2d530 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20 66 6f  ctor callback fo
2d540 72 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61  r.** the applica
2d550 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65  tion data pointe
2d560 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  r..**.** ^The fi
2d570 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73  rst parameter is
2d580 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
2d590 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 77 68  onnection] to wh
2d5a0 69 63 68 20 74 68 65 20 53 51 4c 0a 2a 2a 20 66  ich the SQL.** f
2d5b0 75 6e 63 74 69 6f 6e 20 69 73 20 74 6f 20 62 65  unction is to be
2d5c0 20 61 64 64 65 64 2e 20 20 5e 49 66 20 61 6e 20   added.  ^If an 
2d5d0 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 65 73  application uses
2d5e0 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 64   more than one d
2d5f0 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65  atabase.** conne
2d600 63 74 69 6f 6e 20 74 68 65 6e 20 61 70 70 6c 69  ction then appli
2d610 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
2d620 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6d 75 73  QL functions mus
2d630 74 20 62 65 20 61 64 64 65 64 0a 2a 2a 20 74 6f  t be added.** to
2d640 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20 63   each database c
2d650 6f 6e 6e 65 63 74 69 6f 6e 20 73 65 70 61 72 61  onnection separa
2d660 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  tely..**.** ^The
2d670 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
2d680 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  r is the name of
2d690 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
2d6a0 6e 20 74 6f 20 62 65 20 63 72 65 61 74 65 64 20  n to be created 
2d6b0 6f 72 0a 2a 2a 20 72 65 64 65 66 69 6e 65 64 2e  or.** redefined.
2d6c0 20 20 5e 54 68 65 20 6c 65 6e 67 74 68 20 6f 66    ^The length of
2d6d0 20 74 68 65 20 6e 61 6d 65 20 69 73 20 6c 69 6d   the name is lim
2d6e0 69 74 65 64 20 74 6f 20 32 35 35 20 62 79 74 65  ited to 255 byte
2d6f0 73 20 69 6e 20 61 20 55 54 46 2d 38 0a 2a 2a 20  s in a UTF-8.** 
2d700 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 2c 20  representation, 
2d710 65 78 63 6c 75 73 69 76 65 20 6f 66 20 74 68 65  exclusive of the
2d720 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72   zero-terminator
2d730 2e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20 74 68  .  ^Note that th
2d740 65 20 6e 61 6d 65 0a 2a 2a 20 6c 65 6e 67 74 68  e name.** length
2d750 20 6c 69 6d 69 74 20 69 73 20 69 6e 20 55 54 46   limit is in UTF
2d760 2d 38 20 62 79 74 65 73 2c 20 6e 6f 74 20 63 68  -8 bytes, not ch
2d770 61 72 61 63 74 65 72 73 20 6e 6f 72 20 55 54 46  aracters nor UTF
2d780 2d 31 36 20 62 79 74 65 73 2e 20 20 0a 2a 2a 20  -16 bytes.  .** 
2d790 5e 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20  ^Any attempt to 
2d7a0 63 72 65 61 74 65 20 61 20 66 75 6e 63 74 69 6f  create a functio
2d7b0 6e 20 77 69 74 68 20 61 20 6c 6f 6e 67 65 72 20  n with a longer 
2d7c0 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20 72 65 73  name.** will res
2d7d0 75 6c 74 20 69 6e 20 5b 53 51 4c 49 54 45 5f 4d  ult in [SQLITE_M
2d7e0 49 53 55 53 45 5d 20 62 65 69 6e 67 20 72 65 74  ISUSE] being ret
2d7f0 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  urned..**.** ^Th
2d800 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
2d810 72 20 28 6e 41 72 67 29 0a 2a 2a 20 69 73 20 74  r (nArg).** is t
2d820 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67  he number of arg
2d830 75 6d 65 6e 74 73 20 74 68 61 74 20 74 68 65 20  uments that the 
2d840 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a  SQL function or.
2d850 2a 2a 20 61 67 67 72 65 67 61 74 65 20 74 61 6b  ** aggregate tak
2d860 65 73 2e 20 5e 49 66 20 74 68 69 73 20 70 61 72  es. ^If this par
2d870 61 6d 65 74 65 72 20 69 73 20 2d 31 2c 20 74 68  ameter is -1, th
2d880 65 6e 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  en the SQL funct
2d890 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67  ion or.** aggreg
2d8a0 61 74 65 20 6d 61 79 20 74 61 6b 65 20 61 6e 79  ate may take any
2d8b0 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d   number of argum
2d8c0 65 6e 74 73 20 62 65 74 77 65 65 6e 20 30 20 61  ents between 0 a
2d8d0 6e 64 20 74 68 65 20 6c 69 6d 69 74 0a 2a 2a 20  nd the limit.** 
2d8e0 73 65 74 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  set by [sqlite3_
2d8f0 6c 69 6d 69 74 5d 28 5b 53 51 4c 49 54 45 5f 4c  limit]([SQLITE_L
2d900 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52  IMIT_FUNCTION_AR
2d910 47 5d 29 2e 20 20 49 66 20 74 68 65 20 74 68 69  G]).  If the thi
2d920 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  rd.** parameter 
2d930 69 73 20 6c 65 73 73 20 74 68 61 6e 20 2d 31 20  is less than -1 
2d940 6f 72 20 67 72 65 61 74 65 72 20 74 68 61 6e 20  or greater than 
2d950 31 32 37 20 74 68 65 6e 20 74 68 65 20 62 65 68  127 then the beh
2d960 61 76 69 6f 72 20 69 73 0a 2a 2a 20 75 6e 64 65  avior is.** unde
2d970 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  fined..**.** ^Th
2d980 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
2d990 65 72 2c 20 65 54 65 78 74 52 65 70 2c 20 73 70  er, eTextRep, sp
2d9a0 65 63 69 66 69 65 73 20 77 68 61 74 0a 2a 2a 20  ecifies what.** 
2d9b0 5b 53 51 4c 49 54 45 5f 55 54 46 38 20 7c 20 74  [SQLITE_UTF8 | t
2d9c0 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20 74 68  ext encoding] th
2d9d0 69 73 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  is SQL function 
2d9e0 70 72 65 66 65 72 73 20 66 6f 72 0a 2a 2a 20 69  prefers for.** i
2d9f0 74 73 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20  ts parameters.  
2da00 45 76 65 72 79 20 53 51 4c 20 66 75 6e 63 74 69  Every SQL functi
2da10 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  on implementatio
2da20 6e 20 6d 75 73 74 20 62 65 20 61 62 6c 65 20 74  n must be able t
2da30 6f 20 77 6f 72 6b 0a 2a 2a 20 77 69 74 68 20 55  o work.** with U
2da40 54 46 2d 38 2c 20 55 54 46 2d 31 36 6c 65 2c 20  TF-8, UTF-16le, 
2da50 6f 72 20 55 54 46 2d 31 36 62 65 2e 20 20 42 75  or UTF-16be.  Bu
2da60 74 20 73 6f 6d 65 20 69 6d 70 6c 65 6d 65 6e 74  t some implement
2da70 61 74 69 6f 6e 73 20 6d 61 79 20 62 65 0a 2a 2a  ations may be.**
2da80 20 6d 6f 72 65 20 65 66 66 69 63 69 65 6e 74 20   more efficient 
2da90 77 69 74 68 20 6f 6e 65 20 65 6e 63 6f 64 69 6e  with one encodin
2daa0 67 20 74 68 61 6e 20 61 6e 6f 74 68 65 72 2e 20  g than another. 
2dab0 20 5e 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e   ^An application
2dac0 20 6d 61 79 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73   may.** invoke s
2dad0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
2dae0 6e 63 74 69 6f 6e 28 29 20 6f 72 20 73 71 6c 69  nction() or sqli
2daf0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2db00 69 6f 6e 31 36 28 29 20 6d 75 6c 74 69 70 6c 65  ion16() multiple
2db10 0a 2a 2a 20 74 69 6d 65 73 20 77 69 74 68 20 74  .** times with t
2db20 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e  he same function
2db30 20 62 75 74 20 77 69 74 68 20 64 69 66 66 65 72   but with differ
2db40 65 6e 74 20 76 61 6c 75 65 73 20 6f 66 20 65 54  ent values of eT
2db50 65 78 74 52 65 70 2e 0a 2a 2a 20 5e 57 68 65 6e  extRep..** ^When
2db60 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d   multiple implem
2db70 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65  entations of the
2db80 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 61   same function a
2db90 72 65 20 61 76 61 69 6c 61 62 6c 65 2c 20 53 51  re available, SQ
2dba0 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 70 69 63  Lite.** will pic
2dbb0 6b 20 74 68 65 20 6f 6e 65 20 74 68 61 74 20 69  k the one that i
2dbc0 6e 76 6f 6c 76 65 73 20 74 68 65 20 6c 65 61 73  nvolves the leas
2dbd0 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74 61  t amount of data
2dbe0 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 20   conversion..** 
2dbf0 49 66 20 74 68 65 72 65 20 69 73 20 6f 6e 6c 79  If there is only
2dc00 20 61 20 73 69 6e 67 6c 65 20 69 6d 70 6c 65 6d   a single implem
2dc10 65 6e 74 61 74 69 6f 6e 20 77 68 69 63 68 20 64  entation which d
2dc20 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 77 68 61  oes not care wha
2dc30 74 20 74 65 78 74 0a 2a 2a 20 65 6e 63 6f 64 69  t text.** encodi
2dc40 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68 65 6e  ng is used, then
2dc50 20 74 68 65 20 66 6f 75 72 74 68 20 61 72 67 75   the fourth argu
2dc60 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 5b  ment should be [
2dc70 53 51 4c 49 54 45 5f 41 4e 59 5d 2e 0a 2a 2a 0a  SQLITE_ANY]..**.
2dc80 2a 2a 20 5e 28 54 68 65 20 66 69 66 74 68 20 70  ** ^(The fifth p
2dc90 61 72 61 6d 65 74 65 72 20 69 73 20 61 6e 20 61  arameter is an a
2dca0 72 62 69 74 72 61 72 79 20 70 6f 69 6e 74 65 72  rbitrary pointer
2dcb0 2e 20 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74  .  The implement
2dcc0 61 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20  ation of the.** 
2dcd0 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 67 61 69  function can gai
2dce0 6e 20 61 63 63 65 73 73 20 74 6f 20 74 68 69 73  n access to this
2dcf0 20 70 6f 69 6e 74 65 72 20 75 73 69 6e 67 20 5b   pointer using [
2dd00 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74  sqlite3_user_dat
2dd10 61 28 29 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54  a()].)^.**.** ^T
2dd20 68 65 20 73 69 78 74 68 2c 20 73 65 76 65 6e 74  he sixth, sevent
2dd30 68 20 61 6e 64 20 65 69 67 68 74 68 20 70 61 72  h and eighth par
2dd40 61 6d 65 74 65 72 73 2c 20 78 46 75 6e 63 2c 20  ameters, xFunc, 
2dd50 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c  xStep and xFinal
2dd60 2c 20 61 72 65 0a 2a 2a 20 70 6f 69 6e 74 65 72  , are.** pointer
2dd70 73 20 74 6f 20 43 2d 6c 61 6e 67 75 61 67 65 20  s to C-language 
2dd80 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 69  functions that i
2dd90 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c  mplement the SQL
2dda0 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20   function or.** 
2ddb0 61 67 67 72 65 67 61 74 65 2e 20 5e 41 20 73 63  aggregate. ^A sc
2ddc0 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f  alar SQL functio
2ddd0 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d  n requires an im
2dde0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
2ddf0 74 68 65 20 78 46 75 6e 63 0a 2a 2a 20 63 61 6c  the xFunc.** cal
2de00 6c 62 61 63 6b 20 6f 6e 6c 79 3b 20 4e 55 4c 4c  lback only; NULL
2de10 20 70 6f 69 6e 74 65 72 73 20 6d 75 73 74 20 62   pointers must b
2de20 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  e passed as the 
2de30 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c  xStep and xFinal
2de40 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e 20  .** parameters. 
2de50 5e 41 6e 20 61 67 67 72 65 67 61 74 65 20 53 51  ^An aggregate SQ
2de60 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69  L function requi
2de70 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74  res an implement
2de80 61 74 69 6f 6e 20 6f 66 20 78 53 74 65 70 0a 2a  ation of xStep.*
2de90 2a 20 61 6e 64 20 78 46 69 6e 61 6c 20 61 6e 64  * and xFinal and
2dea0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6d 75   NULL pointer mu
2deb0 73 74 20 62 65 20 70 61 73 73 65 64 20 66 6f 72  st be passed for
2dec0 20 78 46 75 6e 63 2e 20 5e 54 6f 20 64 65 6c 65   xFunc. ^To dele
2ded0 74 65 20 61 6e 20 65 78 69 73 74 69 6e 67 0a 2a  te an existing.*
2dee0 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f  * SQL function o
2def0 72 20 61 67 67 72 65 67 61 74 65 2c 20 70 61 73  r aggregate, pas
2df00 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20  s NULL pointers 
2df10 66 6f 72 20 61 6c 6c 20 74 68 72 65 65 20 66 75  for all three fu
2df20 6e 63 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61  nction.** callba
2df30 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20  cks..**.** ^(If 
2df40 74 68 65 20 6e 69 6e 74 68 20 70 61 72 61 6d 65  the ninth parame
2df50 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  ter to sqlite3_c
2df60 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76  reate_function_v
2df70 32 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c  2() is not NULL,
2df80 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20 64  .** then it is d
2df90 65 73 74 72 75 63 74 6f 72 20 66 6f 72 20 74 68  estructor for th
2dfa0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61  e application da
2dfb0 74 61 20 70 6f 69 6e 74 65 72 2e 20 0a 2a 2a 20  ta pointer. .** 
2dfc0 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 69  The destructor i
2dfd0 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 74  s invoked when t
2dfe0 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 64  he function is d
2dff0 65 6c 65 74 65 64 2c 20 65 69 74 68 65 72 20 62  eleted, either b
2e000 79 20 62 65 69 6e 67 0a 2a 2a 20 6f 76 65 72 6c  y being.** overl
2e010 6f 61 64 65 64 20 6f 72 20 77 68 65 6e 20 74 68  oaded or when th
2e020 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
2e030 63 74 69 6f 6e 20 63 6c 6f 73 65 73 2e 29 5e 0a  ction closes.)^.
2e040 2a 2a 20 5e 54 68 65 20 64 65 73 74 72 75 63 74  ** ^The destruct
2e050 6f 72 20 69 73 20 61 6c 73 6f 20 69 6e 76 6f 6b  or is also invok
2e060 65 64 20 69 66 20 74 68 65 20 63 61 6c 6c 20 74  ed if the call t
2e070 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72 65  o.** sqlite3_cre
2e080 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28  ate_function_v2(
2e090 29 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e 57 68 65  ) fails..** ^Whe
2e0a0 6e 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  n the destructor
2e0b0 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65   callback of the
2e0c0 20 74 65 6e 74 68 20 70 61 72 61 6d 65 74 65 72   tenth parameter
2e0d0 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 69 74 0a   is invoked, it.
2e0e0 2a 2a 20 69 73 20 70 61 73 73 65 64 20 61 20 73  ** is passed a s
2e0f0 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77  ingle argument w
2e100 68 69 63 68 20 69 73 20 61 20 63 6f 70 79 20 6f  hich is a copy o
2e110 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  f the applicatio
2e120 6e 20 64 61 74 61 20 0a 2a 2a 20 70 6f 69 6e 74  n data .** point
2e130 65 72 20 77 68 69 63 68 20 77 61 73 20 74 68 65  er which was the
2e140 20 66 69 66 74 68 20 70 61 72 61 6d 65 74 65 72   fifth parameter
2e150 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 61   to sqlite3_crea
2e160 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29  te_function_v2()
2e170 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 70  ..**.** ^It is p
2e180 65 72 6d 69 74 74 65 64 20 74 6f 20 72 65 67 69  ermitted to regi
2e190 73 74 65 72 20 6d 75 6c 74 69 70 6c 65 20 69 6d  ster multiple im
2e1a0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66  plementations of
2e1b0 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 66 75 6e   the same.** fun
2e1c0 63 74 69 6f 6e 73 20 77 69 74 68 20 74 68 65 20  ctions with the 
2e1d0 73 61 6d 65 20 6e 61 6d 65 20 62 75 74 20 77 69  same name but wi
2e1e0 74 68 20 65 69 74 68 65 72 20 64 69 66 66 65 72  th either differ
2e1f0 69 6e 67 20 6e 75 6d 62 65 72 73 20 6f 66 0a 2a  ing numbers of.*
2e200 2a 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 64  * arguments or d
2e210 69 66 66 65 72 69 6e 67 20 70 72 65 66 65 72 72  iffering preferr
2e220 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67  ed text encoding
2e230 73 2e 20 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c  s.  ^SQLite will
2e240 20 75 73 65 0a 2a 2a 20 74 68 65 20 69 6d 70 6c   use.** the impl
2e250 65 6d 65 6e 74 61 74 69 6f 6e 20 74 68 61 74 20  ementation that 
2e260 6d 6f 73 74 20 63 6c 6f 73 65 6c 79 20 6d 61 74  most closely mat
2e270 63 68 65 73 20 74 68 65 20 77 61 79 20 69 6e 20  ches the way in 
2e280 77 68 69 63 68 20 74 68 65 0a 2a 2a 20 53 51 4c  which the.** SQL
2e290 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 73 65   function is use
2e2a0 64 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20  d.  ^A function 
2e2b0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77  implementation w
2e2c0 69 74 68 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69  ith a non-negati
2e2d0 76 65 0a 2a 2a 20 6e 41 72 67 20 70 61 72 61 6d  ve.** nArg param
2e2e0 65 74 65 72 20 69 73 20 61 20 62 65 74 74 65 72  eter is a better
2e2f0 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66 75   match than a fu
2e300 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74  nction implement
2e310 61 74 69 6f 6e 20 77 69 74 68 0a 2a 2a 20 61 20  ation with.** a 
2e320 6e 65 67 61 74 69 76 65 20 6e 41 72 67 2e 20 20  negative nArg.  
2e330 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72  ^A function wher
2e340 65 20 74 68 65 20 70 72 65 66 65 72 72 65 64 20  e the preferred 
2e350 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a  text encoding.**
2e360 20 6d 61 74 63 68 65 73 20 74 68 65 20 64 61 74   matches the dat
2e370 61 62 61 73 65 20 65 6e 63 6f 64 69 6e 67 20 69  abase encoding i
2e380 73 20 61 20 62 65 74 74 65 72 0a 2a 2a 20 6d 61  s a better.** ma
2e390 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74  tch than a funct
2e3a0 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e  ion where the en
2e3b0 63 6f 64 69 6e 67 20 69 73 20 64 69 66 66 65 72  coding is differ
2e3c0 65 6e 74 2e 20 20 0a 2a 2a 20 5e 41 20 66 75 6e  ent.  .** ^A fun
2e3d0 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20  ction where the 
2e3e0 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 65 72 65  encoding differe
2e3f0 6e 63 65 20 69 73 20 62 65 74 77 65 65 6e 20 55  nce is between U
2e400 54 46 31 36 6c 65 20 61 6e 64 20 55 54 46 31 36  TF16le and UTF16
2e410 62 65 0a 2a 2a 20 69 73 20 61 20 63 6c 6f 73 65  be.** is a close
2e420 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66  r match than a f
2e430 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68  unction where th
2e440 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 65  e encoding diffe
2e450 72 65 6e 63 65 20 69 73 0a 2a 2a 20 62 65 74 77  rence is.** betw
2e460 65 65 6e 20 55 54 46 38 20 61 6e 64 20 55 54 46  een UTF8 and UTF
2e470 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 42 75 69 6c 74  16..**.** ^Built
2e480 2d 69 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61  -in functions ma
2e490 79 20 62 65 20 6f 76 65 72 6c 6f 61 64 65 64 20  y be overloaded 
2e4a0 62 79 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69  by new applicati
2e4b0 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
2e4c0 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20  ions..**.** ^An 
2e4d0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
2e4e0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  ned function is 
2e4f0 70 65 72 6d 69 74 74 65 64 20 74 6f 20 63 61 6c  permitted to cal
2e500 6c 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74  l other.** SQLit
2e510 65 20 69 6e 74 65 72 66 61 63 65 73 2e 20 20 48  e interfaces.  H
2e520 6f 77 65 76 65 72 2c 20 73 75 63 68 20 63 61 6c  owever, such cal
2e530 6c 73 20 6d 75 73 74 20 6e 6f 74 0a 2a 2a 20 63  ls must not.** c
2e540 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62 61 73  lose the databas
2e550 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6e 6f 72  e connection nor
2e560 20 66 69 6e 61 6c 69 7a 65 20 6f 72 20 72 65 73   finalize or res
2e570 65 74 20 74 68 65 20 70 72 65 70 61 72 65 64 0a  et the prepared.
2e580 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20  ** statement in 
2e590 77 68 69 63 68 20 74 68 65 20 66 75 6e 63 74 69  which the functi
2e5a0 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a  on is running..*
2e5b0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72  /.int sqlite3_cr
2e5c0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 0a 20  eate_function(. 
2e5d0 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20   sqlite3 *db,.  
2e5e0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e  const char *zFun
2e5f0 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74  ctionName,.  int
2e600 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65   nArg,.  int eTe
2e610 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70  xtRep,.  void *p
2e620 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46  App,.  void (*xF
2e630 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  unc)(sqlite3_con
2e640 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
2e650 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f  3_value**),.  vo
2e660 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69  id (*xStep)(sqli
2e670 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74  te3_context*,int
2e680 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a  ,sqlite3_value**
2e690 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e  ),.  void (*xFin
2e6a0 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  al)(sqlite3_cont
2e6b0 65 78 74 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c  ext*).);.int sql
2e6c0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2e6d0 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65  tion16(.  sqlite
2e6e0 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 76  3 *db,.  const v
2e6f0 6f 69 64 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61  oid *zFunctionNa
2e700 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a  me,.  int nArg,.
2e710 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a    int eTextRep,.
2e720 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20    void *pApp,.  
2e730 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71  void (*xFunc)(sq
2e740 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69  lite3_context*,i
2e750 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt,sqlite3_value
2e760 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53  **),.  void (*xS
2e770 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  tep)(sqlite3_con
2e780 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
2e790 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f  3_value**),.  vo
2e7a0 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c  id (*xFinal)(sql
2e7b0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29  ite3_context*).)
2e7c0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72  ;.int sqlite3_cr
2e7d0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32  eate_function_v2
2e7e0 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
2e7f0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
2e800 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20  FunctionName,.  
2e810 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20  int nArg,.  int 
2e820 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64  eTextRep,.  void
2e830 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28   *pApp,.  void (
2e840 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f  *xFunc)(sqlite3_
2e850 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c  context*,int,sql
2e860 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20  ite3_value**),. 
2e870 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73   void (*xStep)(s
2e880 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
2e890 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75  int,sqlite3_valu
2e8a0 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78  e**),.  void (*x
2e8b0 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63  Final)(sqlite3_c
2e8c0 6f 6e 74 65 78 74 2a 29 2c 0a 20 20 76 6f 69 64  ontext*),.  void
2e8d0 28 2a 78 44 65 73 74 72 6f 79 29 28 76 6f 69 64  (*xDestroy)(void
2e8e0 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  *).);../*.** CAP
2e8f0 49 33 52 45 46 3a 20 54 65 78 74 20 45 6e 63 6f  I3REF: Text Enco
2e900 64 69 6e 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  dings.**.** Thes
2e910 65 20 63 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e  e constant defin
2e920 65 20 69 6e 74 65 67 65 72 20 63 6f 64 65 73 20  e integer codes 
2e930 74 68 61 74 20 72 65 70 72 65 73 65 6e 74 20 74  that represent t
2e940 68 65 20 76 61 72 69 6f 75 73 0a 2a 2a 20 74 65  he various.** te
2e950 78 74 20 65 6e 63 6f 64 69 6e 67 73 20 73 75 70  xt encodings sup
2e960 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74 65  ported by SQLite
2e970 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
2e980 49 54 45 5f 55 54 46 38 20 20 20 20 20 20 20 20  ITE_UTF8        
2e990 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c     1.#define SQL
2e9a0 49 54 45 5f 55 54 46 31 36 4c 45 20 20 20 20 20  ITE_UTF16LE     
2e9b0 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c     2.#define SQL
2e9c0 49 54 45 5f 55 54 46 31 36 42 45 20 20 20 20 20  ITE_UTF16BE     
2e9d0 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c     3.#define SQL
2e9e0 49 54 45 5f 55 54 46 31 36 20 20 20 20 20 20 20  ITE_UTF16       
2e9f0 20 20 20 34 20 20 20 20 2f 2a 20 55 73 65 20 6e     4    /* Use n
2ea00 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
2ea10 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
2ea20 54 45 5f 41 4e 59 20 20 20 20 20 20 20 20 20 20  TE_ANY          
2ea30 20 20 35 20 20 20 20 2f 2a 20 73 71 6c 69 74 65    5    /* sqlite
2ea40 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
2ea50 6e 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e  n only */.#defin
2ea60 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41  e SQLITE_UTF16_A
2ea70 4c 49 47 4e 45 44 20 20 38 20 20 20 20 2f 2a 20  LIGNED  8    /* 
2ea80 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
2ea90 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f  ollation only */
2eaa0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2eab0 3a 20 44 65 70 72 65 63 61 74 65 64 20 46 75 6e  : Deprecated Fun
2eac0 63 74 69 6f 6e 73 0a 2a 2a 20 44 45 50 52 45 43  ctions.** DEPREC
2ead0 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ATED.**.** These
2eae0 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 5b   functions are [
2eaf0 64 65 70 72 65 63 61 74 65 64 5d 2e 20 20 49 6e  deprecated].  In
2eb00 20 6f 72 64 65 72 20 74 6f 20 6d 61 69 6e 74 61   order to mainta
2eb10 69 6e 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20  in.** backwards 
2eb20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 77 69  compatibility wi
2eb30 74 68 20 6f 6c 64 65 72 20 63 6f 64 65 2c 20 74  th older code, t
2eb40 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 63  hese functions c
2eb50 6f 6e 74 69 6e 75 65 20 0a 2a 2a 20 74 6f 20 62  ontinue .** to b
2eb60 65 20 73 75 70 70 6f 72 74 65 64 2e 20 20 48 6f  e supported.  Ho
2eb70 77 65 76 65 72 2c 20 6e 65 77 20 61 70 70 6c 69  wever, new appli
2eb80 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 61  cations should a
2eb90 76 6f 69 64 0a 2a 2a 20 74 68 65 20 75 73 65 20  void.** the use 
2eba0 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f  of these functio
2ebb0 6e 73 2e 20 20 54 6f 20 68 65 6c 70 20 65 6e 63  ns.  To help enc
2ebc0 6f 75 72 61 67 65 20 70 65 6f 70 6c 65 20 74 6f  ourage people to
2ebd0 20 61 76 6f 69 64 0a 2a 2a 20 75 73 69 6e 67 20   avoid.** using 
2ebe0 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2c  these functions,
2ebf0 20 77 65 20 61 72 65 20 6e 6f 74 20 67 6f 69 6e   we are not goin
2ec00 67 20 74 6f 20 74 65 6c 6c 20 79 6f 75 20 77 68  g to tell you wh
2ec10 61 74 20 74 68 65 79 20 64 6f 2e 0a 2a 2f 0a 23  at they do..*/.#
2ec20 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d  ifndef SQLITE_OM
2ec30 49 54 5f 44 45 50 52 45 43 41 54 45 44 0a 53 51  IT_DEPRECATED.SQ
2ec40 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20  LITE_DEPRECATED 
2ec50 69 6e 74 20 73 71 6c 69 74 65 33 5f 61 67 67 72  int sqlite3_aggr
2ec60 65 67 61 74 65 5f 63 6f 75 6e 74 28 73 71 6c 69  egate_count(sqli
2ec70 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 53  te3_context*);.S
2ec80 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
2ec90 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 70   int sqlite3_exp
2eca0 69 72 65 64 28 73 71 6c 69 74 65 33 5f 73 74 6d  ired(sqlite3_stm
2ecb0 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52  t*);.SQLITE_DEPR
2ecc0 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74  ECATED int sqlit
2ecd0 65 33 5f 74 72 61 6e 73 66 65 72 5f 62 69 6e 64  e3_transfer_bind
2ece0 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d  ings(sqlite3_stm
2ecf0 74 2a 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  t*, sqlite3_stmt
2ed00 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45  *);.SQLITE_DEPRE
2ed10 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65  CATED int sqlite
2ed20 33 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f 76 65 72  3_global_recover
2ed30 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 44  (void);.SQLITE_D
2ed40 45 50 52 45 43 41 54 45 44 20 76 6f 69 64 20 73  EPRECATED void s
2ed50 71 6c 69 74 65 33 5f 74 68 72 65 61 64 5f 63 6c  qlite3_thread_cl
2ed60 65 61 6e 75 70 28 76 6f 69 64 29 3b 0a 53 51 4c  eanup(void);.SQL
2ed70 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69  ITE_DEPRECATED i
2ed80 6e 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  nt sqlite3_memor
2ed90 79 5f 61 6c 61 72 6d 28 76 6f 69 64 28 2a 29 28  y_alarm(void(*)(
2eda0 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e  void*,sqlite3_in
2edb0 74 36 34 2c 69 6e 74 29 2c 76 6f 69 64 2a 2c 73  t64,int),void*,s
2edc0 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 23  qlite3_int64);.#
2edd0 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  endif../*.** CAP
2ede0 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 69 6e 67  I3REF: Obtaining
2edf0 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 50 61   SQL Function Pa
2ee00 72 61 6d 65 74 65 72 20 56 61 6c 75 65 73 0a 2a  rameter Values.*
2ee10 2a 0a 2a 2a 20 54 68 65 20 43 2d 6c 61 6e 67 75  *.** The C-langu
2ee20 61 67 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  age implementati
2ee30 6f 6e 20 6f 66 20 53 51 4c 20 66 75 6e 63 74 69  on of SQL functi
2ee40 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74  ons and aggregat
2ee50 65 73 20 75 73 65 73 0a 2a 2a 20 74 68 69 73 20  es uses.** this 
2ee60 73 65 74 20 6f 66 20 69 6e 74 65 72 66 61 63 65  set of interface
2ee70 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 61 63 63   routines to acc
2ee80 65 73 73 20 74 68 65 20 70 61 72 61 6d 65 74 65  ess the paramete
2ee90 72 20 76 61 6c 75 65 73 20 6f 6e 0a 2a 2a 20 74  r values on.** t
2eea0 68 65 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61  he function or a
2eeb0 67 67 72 65 67 61 74 65 2e 0a 2a 2a 0a 2a 2a 20  ggregate..**.** 
2eec0 54 68 65 20 78 46 75 6e 63 20 28 66 6f 72 20 73  The xFunc (for s
2eed0 63 61 6c 61 72 20 66 75 6e 63 74 69 6f 6e 73 29  calar functions)
2eee0 20 6f 72 20 78 53 74 65 70 20 28 66 6f 72 20 61   or xStep (for a
2eef0 67 67 72 65 67 61 74 65 73 29 20 70 61 72 61 6d  ggregates) param
2ef00 65 74 65 72 73 0a 2a 2a 20 74 6f 20 5b 73 71 6c  eters.** to [sql
2ef10 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2ef20 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c  tion()] and [sql
2ef30 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2ef40 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 64 65 66  tion16()].** def
2ef50 69 6e 65 20 63 61 6c 6c 62 61 63 6b 73 20 74 68  ine callbacks th
2ef60 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65  at implement the
2ef70 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61   SQL functions a
2ef80 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e 0a 2a  nd aggregates..*
2ef90 2a 20 54 68 65 20 33 72 64 20 70 61 72 61 6d 65  * The 3rd parame
2efa0 74 65 72 20 74 6f 20 74 68 65 73 65 20 63 61 6c  ter to these cal
2efb0 6c 62 61 63 6b 73 20 69 73 20 61 6e 20 61 72 72  lbacks is an arr
2efc0 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74  ay of pointers t
2efd0 6f 0a 2a 2a 20 5b 70 72 6f 74 65 63 74 65 64 20  o.** [protected 
2efe0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
2eff0 62 6a 65 63 74 73 2e 20 20 54 68 65 72 65 20 69  bjects.  There i
2f000 73 20 6f 6e 65 20 5b 73 71 6c 69 74 65 33 5f 76  s one [sqlite3_v
2f010 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 66 6f 72  alue] object for
2f020 0a 2a 2a 20 65 61 63 68 20 70 61 72 61 6d 65 74  .** each paramet
2f030 65 72 20 74 6f 20 74 68 65 20 53 51 4c 20 66 75  er to the SQL fu
2f040 6e 63 74 69 6f 6e 2e 20 20 54 68 65 73 65 20 72  nction.  These r
2f050 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 64  outines are used
2f060 20 74 6f 0a 2a 2a 20 65 78 74 72 61 63 74 20 76   to.** extract v
2f070 61 6c 75 65 73 20 66 72 6f 6d 20 74 68 65 20 5b  alues from the [
2f080 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
2f090 62 6a 65 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  bjects..**.** Th
2f0a0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72  ese routines wor
2f0b0 6b 20 6f 6e 6c 79 20 77 69 74 68 20 5b 70 72 6f  k only with [pro
2f0c0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2f0d0 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a  alue] objects..*
2f0e0 2a 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f  * Any attempt to
2f0f0 20 75 73 65 20 74 68 65 73 65 20 72 6f 75 74 69   use these routi
2f100 6e 65 73 20 6f 6e 20 61 6e 20 5b 75 6e 70 72 6f  nes on an [unpro
2f110 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2f120 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20  alue].** object 
2f130 72 65 73 75 6c 74 73 20 69 6e 20 75 6e 64 65 66  results in undef
2f140 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a  ined behavior..*
2f150 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74  *.** ^These rout
2f160 69 6e 65 73 20 77 6f 72 6b 20 6a 75 73 74 20 6c  ines work just l
2f170 69 6b 65 20 74 68 65 20 63 6f 72 72 65 73 70 6f  ike the correspo
2f180 6e 64 69 6e 67 20 5b 63 6f 6c 75 6d 6e 20 61 63  nding [column ac
2f190 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 0a  cess functions].
2f1a0 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 20  ** except that  
2f1b0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74  these routines t
2f1c0 61 6b 65 20 61 20 73 69 6e 67 6c 65 20 5b 70 72  ake a single [pr
2f1d0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
2f1e0 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 0a 2a 2a  value] object.**
2f1f0 20 70 6f 69 6e 74 65 72 20 69 6e 73 74 65 61 64   pointer instead
2f200 20 6f 66 20 61 20 5b 73 71 6c 69 74 65 33 5f 73   of a [sqlite3_s
2f210 74 6d 74 2a 5d 20 70 6f 69 6e 74 65 72 20 61 6e  tmt*] pointer an
2f220 64 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 6c  d an integer col
2f230 75 6d 6e 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a  umn number..**.*
2f240 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76  * ^The sqlite3_v
2f250 61 6c 75 65 5f 74 65 78 74 31 36 28 29 20 69 6e  alue_text16() in
2f260 74 65 72 66 61 63 65 20 65 78 74 72 61 63 74 73  terface extracts
2f270 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67   a UTF-16 string
2f280 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 74 69 76  .** in the nativ
2f290 65 20 62 79 74 65 2d 6f 72 64 65 72 20 6f 66 20  e byte-order of 
2f2a0 74 68 65 20 68 6f 73 74 20 6d 61 63 68 69 6e 65  the host machine
2f2b0 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74  .  ^The.** sqlit
2f2c0 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62  e3_value_text16b
2f2d0 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  e() and sqlite3_
2f2e0 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 29  value_text16le()
2f2f0 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 65   interfaces.** e
2f300 78 74 72 61 63 74 20 55 54 46 2d 31 36 20 73 74  xtract UTF-16 st
2f310 72 69 6e 67 73 20 61 73 20 62 69 67 2d 65 6e 64  rings as big-end
2f320 69 61 6e 20 61 6e 64 20 6c 69 74 74 6c 65 2d 65  ian and little-e
2f330 6e 64 69 61 6e 20 72 65 73 70 65 63 74 69 76 65  ndian respective
2f340 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  ly..**.** ^(The 
2f350 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75  sqlite3_value_nu
2f360 6d 65 72 69 63 5f 74 79 70 65 28 29 20 69 6e 74  meric_type() int
2f370 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20  erface attempts 
2f380 74 6f 20 61 70 70 6c 79 0a 2a 2a 20 6e 75 6d 65  to apply.** nume
2f390 72 69 63 20 61 66 66 69 6e 69 74 79 20 74 6f 20  ric affinity to 
2f3a0 74 68 65 20 76 61 6c 75 65 2e 20 20 54 68 69 73  the value.  This
2f3b0 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6e 20 61   means that an a
2f3c0 74 74 65 6d 70 74 20 69 73 0a 2a 2a 20 6d 61 64  ttempt is.** mad
2f3d0 65 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65  e to convert the
2f3e0 20 76 61 6c 75 65 20 74 6f 20 61 6e 20 69 6e 74   value to an int
2f3f0 65 67 65 72 20 6f 72 20 66 6c 6f 61 74 69 6e 67  eger or floating
2f400 20 70 6f 69 6e 74 2e 20 20 49 66 0a 2a 2a 20 73   point.  If.** s
2f410 75 63 68 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e  uch a conversion
2f420 20 69 73 20 70 6f 73 73 69 62 6c 65 20 77 69 74   is possible wit
2f430 68 6f 75 74 20 6c 6f 73 73 20 6f 66 20 69 6e 66  hout loss of inf
2f440 6f 72 6d 61 74 69 6f 6e 20 28 69 6e 20 6f 74 68  ormation (in oth
2f450 65 72 0a 2a 2a 20 77 6f 72 64 73 2c 20 69 66 20  er.** words, if 
2f460 74 68 65 20 76 61 6c 75 65 20 69 73 20 61 20 73  the value is a s
2f470 74 72 69 6e 67 20 74 68 61 74 20 6c 6f 6f 6b 73  tring that looks
2f480 20 6c 69 6b 65 20 61 20 6e 75 6d 62 65 72 29 0a   like a number).
2f490 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 6f 6e 76  ** then the conv
2f4a0 65 72 73 69 6f 6e 20 69 73 20 70 65 72 66 6f 72  ersion is perfor
2f4b0 6d 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20  med.  Otherwise 
2f4c0 6e 6f 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63  no conversion oc
2f4d0 63 75 72 73 2e 0a 2a 2a 20 54 68 65 20 5b 53 51  curs..** The [SQ
2f4e0 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64  LITE_INTEGER | d
2f4f0 61 74 61 74 79 70 65 5d 20 61 66 74 65 72 20 63  atatype] after c
2f500 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 72 65 74  onversion is ret
2f510 75 72 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 50  urned.)^.**.** P
2f520 6c 65 61 73 65 20 70 61 79 20 70 61 72 74 69 63  lease pay partic
2f530 75 6c 61 72 20 61 74 74 65 6e 74 69 6f 6e 20 74  ular attention t
2f540 6f 20 74 68 65 20 66 61 63 74 20 74 68 61 74 20  o the fact that 
2f550 74 68 65 20 70 6f 69 6e 74 65 72 20 72 65 74 75  the pointer retu
2f560 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71  rned.** from [sq
2f570 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62  lite3_value_blob
2f580 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61  ()], [sqlite3_va
2f590 6c 75 65 5f 74 65 78 74 28 29 5d 2c 20 6f 72 0a  lue_text()], or.
2f5a0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ** [sqlite3_valu
2f5b0 65 5f 74 65 78 74 31 36 28 29 5d 20 63 61 6e 20  e_text16()] can 
2f5c0 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64 20 62  be invalidated b
2f5d0 79 20 61 20 73 75 62 73 65 71 75 65 6e 74 20 63  y a subsequent c
2f5e0 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  all to.** [sqlit
2f5f0 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29  e3_value_bytes()
2f600 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ], [sqlite3_valu
2f610 65 5f 62 79 74 65 73 31 36 28 29 5d 2c 20 5b 73  e_bytes16()], [s
2f620 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
2f630 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c  t()],.** or [sql
2f640 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
2f650 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  6()]..**.** Thes
2f660 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20  e routines must 
2f670 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74  be called from t
2f680 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 61  he same thread a
2f690 73 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e  s.** the SQL fun
2f6a0 63 74 69 6f 6e 20 74 68 61 74 20 73 75 70 70 6c  ction that suppl
2f6b0 69 65 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ied the [sqlite3
2f6c0 5f 76 61 6c 75 65 2a 5d 20 70 61 72 61 6d 65 74  _value*] paramet
2f6d0 65 72 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f  ers..*/.const vo
2f6e0 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75  id *sqlite3_valu
2f6f0 65 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 76  e_blob(sqlite3_v
2f700 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69  alue*);.int sqli
2f710 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28  te3_value_bytes(
2f720 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
2f730 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c  .int sqlite3_val
2f740 75 65 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74  ue_bytes16(sqlit
2f750 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 64 6f 75 62  e3_value*);.doub
2f760 6c 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  le sqlite3_value
2f770 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f  _double(sqlite3_
2f780 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c  value*);.int sql
2f790 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 73  ite3_value_int(s
2f7a0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
2f7b0 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71  sqlite3_int64 sq
2f7c0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 36  lite3_value_int6
2f7d0 34 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  4(sqlite3_value*
2f7e0 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65  );.const unsigne
2f7f0 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  d char *sqlite3_
2f800 76 61 6c 75 65 5f 74 65 78 74 28 73 71 6c 69 74  value_text(sqlit
2f810 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73  e3_value*);.cons
2f820 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
2f830 76 61 6c 75 65 5f 74 65 78 74 31 36 28 73 71 6c  value_text16(sql
2f840 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f  ite3_value*);.co
2f850 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
2f860 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65  3_value_text16le
2f870 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
2f880 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
2f890 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
2f8a0 31 36 62 65 28 73 71 6c 69 74 65 33 5f 76 61 6c  16be(sqlite3_val
2f8b0 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  ue*);.int sqlite
2f8c0 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 73 71 6c  3_value_type(sql
2f8d0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e  ite3_value*);.in
2f8e0 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  t sqlite3_value_
2f8f0 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 73 71 6c  numeric_type(sql
2f900 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f  ite3_value*);../
2f910 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
2f920 62 74 61 69 6e 20 41 67 67 72 65 67 61 74 65 20  btain Aggregate 
2f930 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74  Function Context
2f940 0a 2a 2a 0a 2a 2a 20 49 6d 70 6c 65 6d 65 6e 74  .**.** Implement
2f950 61 74 69 6f 6e 73 20 6f 66 20 61 67 67 72 65 67  ations of aggreg
2f960 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ate SQL function
2f970 73 20 75 73 65 20 74 68 69 73 0a 2a 2a 20 72 6f  s use this.** ro
2f980 75 74 69 6e 65 20 74 6f 20 61 6c 6c 6f 63 61 74  utine to allocat
2f990 65 20 6d 65 6d 6f 72 79 20 66 6f 72 20 73 74 6f  e memory for sto
2f9a0 72 69 6e 67 20 74 68 65 69 72 20 73 74 61 74 65  ring their state
2f9b0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72  ..**.** ^The fir
2f9c0 73 74 20 74 69 6d 65 20 74 68 65 20 73 71 6c 69  st time the sqli
2f9d0 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
2f9e0 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f 75 74 69  ntext(C,N) routi
2f9f0 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 0a 2a 2a  ne is called .**
2fa00 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61   for a particula
2fa10 72 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63  r aggregate func
2fa20 74 69 6f 6e 2c 20 53 51 4c 69 74 65 0a 2a 2a 20  tion, SQLite.** 
2fa30 61 6c 6c 6f 63 61 74 65 73 20 4e 20 6f 66 20 6d  allocates N of m
2fa40 65 6d 6f 72 79 2c 20 7a 65 72 6f 65 73 20 6f 75  emory, zeroes ou
2fa50 74 20 74 68 61 74 20 6d 65 6d 6f 72 79 2c 20 61  t that memory, a
2fa60 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  nd returns a poi
2fa70 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 6e  nter.** to the n
2fa80 65 77 20 6d 65 6d 6f 72 79 2e 20 5e 4f 6e 20 73  ew memory. ^On s
2fa90 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71  econd and subseq
2faa0 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a  uent calls to.**
2fab0 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
2fac0 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 66 6f 72  te_context() for
2fad0 20 74 68 65 20 73 61 6d 65 20 61 67 67 72 65 67   the same aggreg
2fae0 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73  ate function ins
2faf0 74 61 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 73 61  tance,.** the sa
2fb00 6d 65 20 62 75 66 66 65 72 20 69 73 20 72 65 74  me buffer is ret
2fb10 75 72 6e 65 64 2e 20 20 53 71 6c 69 74 65 33 5f  urned.  Sqlite3_
2fb20 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
2fb30 74 28 29 20 69 73 20 6e 6f 72 6d 61 6c 6c 79 0a  t() is normally.
2fb40 2a 2a 20 63 61 6c 6c 65 64 20 6f 6e 63 65 20 66  ** called once f
2fb50 6f 72 20 65 61 63 68 20 69 6e 76 6f 63 61 74 69  or each invocati
2fb60 6f 6e 20 6f 66 20 74 68 65 20 78 53 74 65 70 20  on of the xStep 
2fb70 63 61 6c 6c 62 61 63 6b 20 61 6e 64 20 74 68 65  callback and the
2fb80 6e 20 6f 6e 65 0a 2a 2a 20 6c 61 73 74 20 74 69  n one.** last ti
2fb90 6d 65 20 77 68 65 6e 20 74 68 65 20 78 46 69 6e  me when the xFin
2fba0 61 6c 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  al callback is i
2fbb0 6e 76 6f 6b 65 64 2e 20 20 5e 28 57 68 65 6e 20  nvoked.  ^(When 
2fbc0 6e 6f 20 72 6f 77 73 20 6d 61 74 63 68 0a 2a 2a  no rows match.**
2fbd0 20 61 6e 20 61 67 67 72 65 67 61 74 65 20 71 75   an aggregate qu
2fbe0 65 72 79 2c 20 74 68 65 20 78 53 74 65 70 28 29  ery, the xStep()
2fbf0 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65   callback of the
2fc00 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74   aggregate funct
2fc10 69 6f 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  ion.** implement
2fc20 61 74 69 6f 6e 20 69 73 20 6e 65 76 65 72 20 63  ation is never c
2fc30 61 6c 6c 65 64 20 61 6e 64 20 78 46 69 6e 61 6c  alled and xFinal
2fc40 28 29 20 69 73 20 63 61 6c 6c 65 64 20 65 78 61  () is called exa
2fc50 63 74 6c 79 20 6f 6e 63 65 2e 0a 2a 2a 20 49 6e  ctly once..** In
2fc60 20 74 68 6f 73 65 20 63 61 73 65 73 2c 20 73 71   those cases, sq
2fc70 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
2fc80 63 6f 6e 74 65 78 74 28 29 20 6d 69 67 68 74 20  context() might 
2fc90 62 65 20 63 61 6c 6c 65 64 20 66 6f 72 20 74 68  be called for th
2fca0 65 0a 2a 2a 20 66 69 72 73 74 20 74 69 6d 65 20  e.** first time 
2fcb0 66 72 6f 6d 20 77 69 74 68 69 6e 20 78 46 69 6e  from within xFin
2fcc0 61 6c 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54  al().)^.**.** ^T
2fcd0 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  he sqlite3_aggre
2fce0 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e  gate_context(C,N
2fcf0 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ) routine return
2fd00 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
2fd10 20 69 66 20 4e 20 69 73 0a 2a 2a 20 6c 65 73 73   if N is.** less
2fd20 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74   than or equal t
2fd30 6f 20 7a 65 72 6f 20 6f 72 20 69 66 20 61 20 6d  o zero or if a m
2fd40 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 65 20 65  emory allocate e
2fd50 72 72 6f 72 20 6f 63 63 75 72 73 2e 0a 2a 2a 0a  rror occurs..**.
2fd60 2a 2a 20 5e 28 54 68 65 20 61 6d 6f 75 6e 74 20  ** ^(The amount 
2fd70 6f 66 20 73 70 61 63 65 20 61 6c 6c 6f 63 61 74  of space allocat
2fd80 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 61 67  ed by sqlite3_ag
2fd90 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
2fda0 43 2c 4e 29 20 69 73 0a 2a 2a 20 64 65 74 65 72  C,N) is.** deter
2fdb0 6d 69 6e 65 64 20 62 79 20 74 68 65 20 4e 20 70  mined by the N p
2fdc0 61 72 61 6d 65 74 65 72 20 6f 6e 20 66 69 72 73  arameter on firs
2fdd0 74 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c  t successful cal
2fde0 6c 2e 20 20 43 68 61 6e 67 69 6e 67 20 74 68 65  l.  Changing the
2fdf0 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 4e 20 69  .** value of N i
2fe00 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  n subsequent cal
2fe10 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 61 67 67  l to sqlite3_agg
2fe20 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29  regate_context()
2fe30 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20 73   within.** the s
2fe40 61 6d 65 20 61 67 67 72 65 67 61 74 65 20 66 75  ame aggregate fu
2fe50 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65 20  nction instance 
2fe60 77 69 6c 6c 20 6e 6f 74 20 72 65 73 69 7a 65 20  will not resize 
2fe70 74 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c  the memory.** al
2fe80 6c 6f 63 61 74 69 6f 6e 2e 29 5e 0a 2a 2a 0a 2a  location.)^.**.*
2fe90 2a 20 5e 53 51 4c 69 74 65 20 61 75 74 6f 6d 61  * ^SQLite automa
2fea0 74 69 63 61 6c 6c 79 20 66 72 65 65 73 20 74 68  tically frees th
2feb0 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
2fec0 65 64 20 62 79 20 0a 2a 2a 20 73 71 6c 69 74 65  ed by .** sqlite
2fed0 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
2fee0 65 78 74 28 29 20 77 68 65 6e 20 74 68 65 20 61  ext() when the a
2fef0 67 67 72 65 67 61 74 65 20 71 75 65 72 79 20 63  ggregate query c
2ff00 6f 6e 63 6c 75 64 65 73 2e 0a 2a 2a 0a 2a 2a 20  oncludes..**.** 
2ff10 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
2ff20 74 65 72 20 6d 75 73 74 20 62 65 20 61 20 63 6f  ter must be a co
2ff30 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71  py of the.** [sq
2ff40 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 7c 20  lite3_context | 
2ff50 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63 6f 6e  SQL function con
2ff60 74 65 78 74 5d 20 74 68 61 74 20 69 73 20 74 68  text] that is th
2ff70 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
2ff80 72 0a 2a 2a 20 74 6f 20 74 68 65 20 78 53 74 65  r.** to the xSte
2ff90 70 20 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c  p or xFinal call
2ffa0 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 74 68 61  back routine tha
2ffb0 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65  t implements the
2ffc0 20 61 67 67 72 65 67 61 74 65 0a 2a 2a 20 66 75   aggregate.** fu
2ffd0 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68  nction..**.** Th
2ffe0 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20  is routine must 
2fff0 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74  be called from t
30000 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69  he same thread i
30010 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61  n which.** the a
30020 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e  ggregate SQL fun
30030 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67  ction is running
30040 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74  ..*/.void *sqlit
30050 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
30060 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e  text(sqlite3_con
30070 74 65 78 74 2a 2c 20 69 6e 74 20 6e 42 79 74 65  text*, int nByte
30080 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  s);../*.** CAPI3
30090 52 45 46 3a 20 55 73 65 72 20 44 61 74 61 20 46  REF: User Data F
300a0 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a  or Functions.**.
300b0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
300c0 75 73 65 72 5f 64 61 74 61 28 29 20 69 6e 74 65  user_data() inte
300d0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
300e0 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70  copy of.** the p
300f0 6f 69 6e 74 65 72 20 74 68 61 74 20 77 61 73 20  ointer that was 
30100 74 68 65 20 70 55 73 65 72 44 61 74 61 20 70 61  the pUserData pa
30110 72 61 6d 65 74 65 72 20 28 74 68 65 20 35 74 68  rameter (the 5th
30120 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f   parameter).** o
30130 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  f the [sqlite3_c
30140 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
30150 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65  ].** and [sqlite
30160 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
30170 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20  n16()] routines 
30180 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a  that originally.
30190 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20 74 68  ** registered th
301a0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65  e application de
301b0 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a  fined function..
301c0 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  **.** This routi
301d0 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65  ne must be calle
301e0 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20  d from the same 
301f0 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a  thread in which.
30200 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ** the applicati
30210 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
30220 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  ion is running..
30230 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  */.void *sqlite3
30240 5f 75 73 65 72 5f 64 61 74 61 28 73 71 6c 69 74  _user_data(sqlit
30250 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f  e3_context*);../
30260 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
30270 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69  atabase Connecti
30280 6f 6e 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73  on For Functions
30290 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
302a0 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68  te3_context_db_h
302b0 61 6e 64 6c 65 28 29 20 69 6e 74 65 72 66 61 63  andle() interfac
302c0 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79  e returns a copy
302d0 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74   of.** the point
302e0 65 72 20 74 6f 20 74 68 65 20 5b 64 61 74 61 62  er to the [datab
302f0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
30300 28 74 68 65 20 31 73 74 20 70 61 72 61 6d 65 74  (the 1st paramet
30310 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73  er).** of the [s
30320 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
30330 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64  nction()].** and
30340 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
30350 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72  _function16()] r
30360 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69  outines that ori
30370 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73  ginally.** regis
30380 74 65 72 65 64 20 74 68 65 20 61 70 70 6c 69 63  tered the applic
30390 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75  ation defined fu
303a0 6e 63 74 69 6f 6e 2e 0a 2a 2f 0a 73 71 6c 69 74  nction..*/.sqlit
303b0 65 33 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6e 74  e3 *sqlite3_cont
303c0 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71  ext_db_handle(sq
303d0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b  lite3_context*);
303e0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
303f0 3a 20 46 75 6e 63 74 69 6f 6e 20 41 75 78 69 6c  : Function Auxil
30400 69 61 72 79 20 44 61 74 61 0a 2a 2a 0a 2a 2a 20  iary Data.**.** 
30410 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 77  The following tw
30420 6f 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20  o functions may 
30430 62 65 20 75 73 65 64 20 62 79 20 73 63 61 6c 61  be used by scala
30440 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  r SQL functions 
30450 74 6f 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 20  to.** associate 
30460 6d 65 74 61 64 61 74 61 20 77 69 74 68 20 61 72  metadata with ar
30470 67 75 6d 65 6e 74 20 76 61 6c 75 65 73 2e 20 49  gument values. I
30480 66 20 74 68 65 20 73 61 6d 65 20 76 61 6c 75 65  f the same value
30490 20 69 73 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a   is passed to.**
304a0 20 6d 75 6c 74 69 70 6c 65 20 69 6e 76 6f 63 61   multiple invoca
304b0 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d  tions of the sam
304c0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 64  e SQL function d
304d0 75 72 69 6e 67 20 71 75 65 72 79 20 65 78 65 63  uring query exec
304e0 75 74 69 6f 6e 2c 20 75 6e 64 65 72 0a 2a 2a 20  ution, under.** 
304f0 73 6f 6d 65 20 63 69 72 63 75 6d 73 74 61 6e 63  some circumstanc
30500 65 73 20 74 68 65 20 61 73 73 6f 63 69 61 74 65  es the associate
30510 64 20 6d 65 74 61 64 61 74 61 20 6d 61 79 20 62  d metadata may b
30520 65 20 70 72 65 73 65 72 76 65 64 2e 20 54 68 69  e preserved. Thi
30530 73 20 6d 61 79 0a 2a 2a 20 62 65 20 75 73 65 64  s may.** be used
30540 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 74  , for example, t
30550 6f 20 61 64 64 20 61 20 72 65 67 75 6c 61 72 2d  o add a regular-
30560 65 78 70 72 65 73 73 69 6f 6e 20 6d 61 74 63 68  expression match
30570 69 6e 67 20 73 63 61 6c 61 72 0a 2a 2a 20 66 75  ing scalar.** fu
30580 6e 63 74 69 6f 6e 2e 20 54 68 65 20 63 6f 6d 70  nction. The comp
30590 69 6c 65 64 20 76 65 72 73 69 6f 6e 20 6f 66 20  iled version of 
305a0 74 68 65 20 72 65 67 75 6c 61 72 20 65 78 70 72  the regular expr
305b0 65 73 73 69 6f 6e 20 69 73 20 73 74 6f 72 65 64  ession is stored
305c0 20 61 73 0a 2a 2a 20 6d 65 74 61 64 61 74 61 20   as.** metadata 
305d0 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
305e0 74 68 65 20 53 51 4c 20 76 61 6c 75 65 20 70 61  the SQL value pa
305f0 73 73 65 64 20 61 73 20 74 68 65 20 72 65 67 75  ssed as the regu
30600 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 0a 2a  lar expression.*
30610 2a 20 70 61 74 74 65 72 6e 2e 20 20 54 68 65 20  * pattern.  The 
30620 63 6f 6d 70 69 6c 65 64 20 72 65 67 75 6c 61 72  compiled regular
30630 20 65 78 70 72 65 73 73 69 6f 6e 20 63 61 6e 20   expression can 
30640 62 65 20 72 65 75 73 65 64 20 6f 6e 20 6d 75 6c  be reused on mul
30650 74 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f 63 61 74  tiple.** invocat
30660 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65  ions of the same
30670 20 66 75 6e 63 74 69 6f 6e 20 73 6f 20 74 68 61   function so tha
30680 74 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 70  t the original p
30690 61 74 74 65 72 6e 20 73 74 72 69 6e 67 0a 2a 2a  attern string.**
306a0 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74   does not need t
306b0 6f 20 62 65 20 72 65 63 6f 6d 70 69 6c 65 64 20  o be recompiled 
306c0 6f 6e 20 65 61 63 68 20 69 6e 76 6f 63 61 74 69  on each invocati
306d0 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  on..**.** ^The s
306e0 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61  qlite3_get_auxda
306f0 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  ta() interface r
30700 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
30710 20 74 6f 20 74 68 65 20 6d 65 74 61 64 61 74 61   to the metadata
30720 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 62  .** associated b
30730 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65  y the sqlite3_se
30740 74 5f 61 75 78 64 61 74 61 28 29 20 66 75 6e 63  t_auxdata() func
30750 74 69 6f 6e 20 77 69 74 68 20 74 68 65 20 4e 74  tion with the Nt
30760 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 76 61  h argument.** va
30770 6c 75 65 20 74 6f 20 74 68 65 20 61 70 70 6c 69  lue to the appli
30780 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
30790 75 6e 63 74 69 6f 6e 2e 20 5e 49 66 20 6e 6f 20  unction. ^If no 
307a0 6d 65 74 61 64 61 74 61 20 68 61 73 20 62 65 65  metadata has bee
307b0 6e 20 65 76 65 72 0a 2a 2a 20 62 65 65 6e 20 73  n ever.** been s
307c0 65 74 20 66 6f 72 20 74 68 65 20 4e 74 68 20 61  et for the Nth a
307d0 72 67 75 6d 65 6e 74 20 6f 66 20 74 68 65 20 66  rgument of the f
307e0 75 6e 63 74 69 6f 6e 2c 20 6f 72 20 69 66 20 74  unction, or if t
307f0 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
30800 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 61 72  .** function par
30810 61 6d 65 74 65 72 20 68 61 73 20 63 68 61 6e 67  ameter has chang
30820 65 64 20 73 69 6e 63 65 20 74 68 65 20 6d 65 74  ed since the met
30830 61 2d 64 61 74 61 20 77 61 73 20 73 65 74 2c 0a  a-data was set,.
30840 2a 2a 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  ** then sqlite3_
30850 67 65 74 5f 61 75 78 64 61 74 61 28 29 20 72 65  get_auxdata() re
30860 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69  turns a NULL poi
30870 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  nter..**.** ^The
30880 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78   sqlite3_set_aux
30890 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65  data() interface
308a0 20 73 61 76 65 73 20 74 68 65 20 6d 65 74 61 64   saves the metad
308b0 61 74 61 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74  ata.** pointed t
308c0 6f 20 62 79 20 69 74 73 20 33 72 64 20 70 61 72  o by its 3rd par
308d0 61 6d 65 74 65 72 20 61 73 20 74 68 65 20 6d 65  ameter as the me
308e0 74 61 64 61 74 61 20 66 6f 72 20 74 68 65 20 4e  tadata for the N
308f0 2d 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  -th.** argument 
30900 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  of the applicati
30910 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
30920 69 6f 6e 2e 20 20 53 75 62 73 65 71 75 65 6e 74  ion.  Subsequent
30930 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  .** calls to sql
30940 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61  ite3_get_auxdata
30950 28 29 20 6d 69 67 68 74 20 72 65 74 75 72 6e 20  () might return 
30960 74 68 69 73 20 64 61 74 61 2c 20 69 66 20 69 74  this data, if it
30970 20 68 61 73 0a 2a 2a 20 6e 6f 74 20 62 65 65 6e   has.** not been
30980 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a 20 5e   destroyed..** ^
30990 49 66 20 69 74 20 69 73 20 6e 6f 74 20 4e 55 4c  If it is not NUL
309a0 4c 2c 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 69  L, SQLite will i
309b0 6e 76 6f 6b 65 20 74 68 65 20 64 65 73 74 72 75  nvoke the destru
309c0 63 74 6f 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  ctor.** function
309d0 20 67 69 76 65 6e 20 62 79 20 74 68 65 20 34 74   given by the 4t
309e0 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  h parameter to s
309f0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
30a00 74 61 28 29 20 6f 6e 0a 2a 2a 20 74 68 65 20 6d  ta() on.** the m
30a10 65 74 61 64 61 74 61 20 77 68 65 6e 20 74 68 65  etadata when the
30a20 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 66   corresponding f
30a30 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 65  unction paramete
30a40 72 20 63 68 61 6e 67 65 73 0a 2a 2a 20 6f 72 20  r changes.** or 
30a50 77 68 65 6e 20 74 68 65 20 53 51 4c 20 73 74 61  when the SQL sta
30a60 74 65 6d 65 6e 74 20 63 6f 6d 70 6c 65 74 65 73  tement completes
30a70 2c 20 77 68 69 63 68 65 76 65 72 20 63 6f 6d 65  , whichever come
30a80 73 20 66 69 72 73 74 2e 0a 2a 2a 0a 2a 2a 20 53  s first..**.** S
30a90 51 4c 69 74 65 20 69 73 20 66 72 65 65 20 74 6f  QLite is free to
30aa0 20 63 61 6c 6c 20 74 68 65 20 64 65 73 74 72 75   call the destru
30ab0 63 74 6f 72 20 61 6e 64 20 64 72 6f 70 20 6d 65  ctor and drop me
30ac0 74 61 64 61 74 61 20 6f 6e 20 61 6e 79 0a 2a 2a  tadata on any.**
30ad0 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 61 6e   parameter of an
30ae0 79 20 66 75 6e 63 74 69 6f 6e 20 61 74 20 61 6e  y function at an
30af0 79 20 74 69 6d 65 2e 20 20 5e 54 68 65 20 6f 6e  y time.  ^The on
30b00 6c 79 20 67 75 61 72 61 6e 74 65 65 20 69 73 20  ly guarantee is 
30b10 74 68 61 74 0a 2a 2a 20 74 68 65 20 64 65 73 74  that.** the dest
30b20 72 75 63 74 6f 72 20 77 69 6c 6c 20 62 65 20 63  ructor will be c
30b30 61 6c 6c 65 64 20 62 65 66 6f 72 65 20 74 68 65  alled before the
30b40 20 6d 65 74 61 64 61 74 61 20 69 73 20 64 72 6f   metadata is dro
30b50 70 70 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e  pped..**.** ^(In
30b60 20 70 72 61 63 74 69 63 65 2c 20 6d 65 74 61 64   practice, metad
30b70 61 74 61 20 69 73 20 70 72 65 73 65 72 76 65 64  ata is preserved
30b80 20 62 65 74 77 65 65 6e 20 66 75 6e 63 74 69 6f   between functio
30b90 6e 20 63 61 6c 6c 73 20 66 6f 72 0a 2a 2a 20 65  n calls for.** e
30ba0 78 70 72 65 73 73 69 6f 6e 73 20 74 68 61 74 20  xpressions that 
30bb0 61 72 65 20 63 6f 6e 73 74 61 6e 74 20 61 74 20  are constant at 
30bc0 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 54 68  compile time. Th
30bd0 69 73 20 69 6e 63 6c 75 64 65 73 20 6c 69 74 65  is includes lite
30be0 72 61 6c 0a 2a 2a 20 76 61 6c 75 65 73 20 61 6e  ral.** values an
30bf0 64 20 5b 70 61 72 61 6d 65 74 65 72 73 5d 2e 29  d [parameters].)
30c00 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ^.**.** These ro
30c10 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63  utines must be c
30c20 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73  alled from the s
30c30 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68  ame thread in wh
30c40 69 63 68 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66  ich.** the SQL f
30c50 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69  unction is runni
30c60 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c  ng..*/.void *sql
30c70 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61  ite3_get_auxdata
30c80 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
30c90 2a 2c 20 69 6e 74 20 4e 29 3b 0a 76 6f 69 64 20  *, int N);.void 
30ca0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
30cb0 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ata(sqlite3_cont
30cc0 65 78 74 2a 2c 20 69 6e 74 20 4e 2c 20 76 6f 69  ext*, int N, voi
30cd0 64 2a 2c 20 76 6f 69 64 20 28 2a 29 28 76 6f 69  d*, void (*)(voi
30ce0 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41  d*));.../*.** CA
30cf0 50 49 33 52 45 46 3a 20 43 6f 6e 73 74 61 6e 74  PI3REF: Constant
30d00 73 20 44 65 66 69 6e 69 6e 67 20 53 70 65 63 69  s Defining Speci
30d10 61 6c 20 44 65 73 74 72 75 63 74 6f 72 20 42 65  al Destructor Be
30d20 68 61 76 69 6f 72 0a 2a 2a 0a 2a 2a 20 54 68 65  havior.**.** The
30d30 73 65 20 61 72 65 20 73 70 65 63 69 61 6c 20 76  se are special v
30d40 61 6c 75 65 73 20 66 6f 72 20 74 68 65 20 64 65  alues for the de
30d50 73 74 72 75 63 74 6f 72 20 74 68 61 74 20 69 73  structor that is
30d60 20 70 61 73 73 65 64 20 69 6e 20 61 73 20 74 68   passed in as th
30d70 65 0a 2a 2a 20 66 69 6e 61 6c 20 61 72 67 75 6d  e.** final argum
30d80 65 6e 74 20 74 6f 20 72 6f 75 74 69 6e 65 73 20  ent to routines 
30d90 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 72 65  like [sqlite3_re
30da0 73 75 6c 74 5f 62 6c 6f 62 28 29 5d 2e 20 20 5e  sult_blob()].  ^
30db0 49 66 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  If the destructo
30dc0 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73  r.** argument is
30dd0 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20   SQLITE_STATIC, 
30de0 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  it means that th
30df0 65 20 63 6f 6e 74 65 6e 74 20 70 6f 69 6e 74 65  e content pointe
30e00 72 20 69 73 20 63 6f 6e 73 74 61 6e 74 0a 2a 2a  r is constant.**
30e10 20 61 6e 64 20 77 69 6c 6c 20 6e 65 76 65 72 20   and will never 
30e20 63 68 61 6e 67 65 2e 20 20 49 74 20 64 6f 65 73  change.  It does
30e30 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20   not need to be 
30e40 64 65 73 74 72 6f 79 65 64 2e 20 20 5e 54 68 65  destroyed.  ^The
30e50 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 52 41 4e 53  .** SQLITE_TRANS
30e60 49 45 4e 54 20 76 61 6c 75 65 20 6d 65 61 6e 73  IENT value means
30e70 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e   that the conten
30e80 74 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 63 68  t will likely ch
30e90 61 6e 67 65 20 69 6e 0a 2a 2a 20 74 68 65 20 6e  ange in.** the n
30ea0 65 61 72 20 66 75 74 75 72 65 20 61 6e 64 20 74  ear future and t
30eb0 68 61 74 20 53 51 4c 69 74 65 20 73 68 6f 75 6c  hat SQLite shoul
30ec0 64 20 6d 61 6b 65 20 69 74 73 20 6f 77 6e 20 70  d make its own p
30ed0 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 0a 2a  rivate copy of.*
30ee0 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 62 65  * the content be
30ef0 66 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 2e 0a  fore returning..
30f00 2a 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 64 65  **.** The typede
30f10 66 20 69 73 20 6e 65 63 65 73 73 61 72 79 20 74  f is necessary t
30f20 6f 20 77 6f 72 6b 20 61 72 6f 75 6e 64 20 70 72  o work around pr
30f30 6f 62 6c 65 6d 73 20 69 6e 20 63 65 72 74 61 69  oblems in certai
30f40 6e 0a 2a 2a 20 43 2b 2b 20 63 6f 6d 70 69 6c 65  n.** C++ compile
30f50 72 73 2e 20 20 53 65 65 20 74 69 63 6b 65 74 20  rs.  See ticket 
30f60 23 32 31 39 31 2e 0a 2a 2f 0a 74 79 70 65 64 65  #2191..*/.typede
30f70 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 74 65 33  f void (*sqlite3
30f80 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65  _destructor_type
30f90 29 28 76 6f 69 64 2a 29 3b 0a 23 64 65 66 69 6e  )(void*);.#defin
30fa0 65 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 20  e SQLITE_STATIC 
30fb0 20 20 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64       ((sqlite3_d
30fc0 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 30  estructor_type)0
30fd0 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
30fe0 5f 54 52 41 4e 53 49 45 4e 54 20 20 20 28 28 73  _TRANSIENT   ((s
30ff0 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f  qlite3_destructo
31000 72 5f 74 79 70 65 29 2d 31 29 0a 0a 2f 2a 0a 2a  r_type)-1)../*.*
31010 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 74 74  * CAPI3REF: Sett
31020 69 6e 67 20 54 68 65 20 52 65 73 75 6c 74 20 4f  ing The Result O
31030 66 20 41 6e 20 53 51 4c 20 46 75 6e 63 74 69 6f  f An SQL Functio
31040 6e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  n.**.** These ro
31050 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 64 20  utines are used 
31060 62 79 20 74 68 65 20 78 46 75 6e 63 20 6f 72 20  by the xFunc or 
31070 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 73  xFinal callbacks
31080 20 74 68 61 74 0a 2a 2a 20 69 6d 70 6c 65 6d 65   that.** impleme
31090 6e 74 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  nt SQL functions
310a0 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e   and aggregates.
310b0 20 20 53 65 65 0a 2a 2a 20 5b 73 71 6c 69 74 65    See.** [sqlite
310c0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
310d0 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  n()] and [sqlite
310e0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
310f0 6e 31 36 28 29 5d 0a 2a 2a 20 66 6f 72 20 61 64  n16()].** for ad
31100 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61  ditional informa
31110 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  tion..**.** Thes
31120 65 20 66 75 6e 63 74 69 6f 6e 73 20 77 6f 72 6b  e functions work
31130 20 76 65 72 79 20 6d 75 63 68 20 6c 69 6b 65 20   very much like 
31140 74 68 65 20 5b 70 61 72 61 6d 65 74 65 72 20 62  the [parameter b
31150 69 6e 64 69 6e 67 5d 20 66 61 6d 69 6c 79 20 6f  inding] family o
31160 66 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 75  f.** functions u
31170 73 65 64 20 74 6f 20 62 69 6e 64 20 76 61 6c 75  sed to bind valu
31180 65 73 20 74 6f 20 68 6f 73 74 20 70 61 72 61 6d  es to host param
31190 65 74 65 72 73 20 69 6e 20 70 72 65 70 61 72 65  eters in prepare
311a0 64 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  d statements..**
311b0 20 52 65 66 65 72 20 74 6f 20 74 68 65 20 5b 53   Refer to the [S
311c0 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 64 6f  QL parameter] do
311d0 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20  cumentation for 
311e0 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72  additional infor
311f0 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54  mation..**.** ^T
31200 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
31210 74 5f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66 61  t_blob() interfa
31220 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75  ce sets the resu
31230 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70  lt from.** an ap
31240 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
31250 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
31260 20 74 68 65 20 42 4c 4f 42 20 77 68 6f 73 65 20   the BLOB whose 
31270 63 6f 6e 74 65 6e 74 20 69 73 20 70 6f 69 6e 74  content is point
31280 65 64 0a 2a 2a 20 74 6f 20 62 79 20 74 68 65 20  ed.** to by the 
31290 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
312a0 20 61 6e 64 20 77 68 69 63 68 20 69 73 20 4e 20   and which is N 
312b0 62 79 74 65 73 20 6c 6f 6e 67 20 77 68 65 72 65  bytes long where
312c0 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20 74 68 69   N is the.** thi
312d0 72 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  rd parameter..**
312e0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
312f0 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62  _result_zeroblob
31300 28 29 20 69 6e 74 65 72 66 61 63 65 73 20 73 65  () interfaces se
31310 74 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 0a  t the result of.
31320 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ** the applicati
31330 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
31340 69 6f 6e 20 74 6f 20 62 65 20 61 20 42 4c 4f 42  ion to be a BLOB
31350 20 63 6f 6e 74 61 69 6e 69 6e 67 20 61 6c 6c 20   containing all 
31360 7a 65 72 6f 0a 2a 2a 20 62 79 74 65 73 20 61 6e  zero.** bytes an
31370 64 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a  d N bytes in siz
31380 65 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68  e, where N is th
31390 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 32  e value of the 2
313a0 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  nd parameter..**
313b0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
313c0 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 29  _result_double()
313d0 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20   interface sets 
313e0 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a  the result from.
313f0 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  ** an applicatio
31400 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
31410 6f 6e 20 74 6f 20 62 65 20 61 20 66 6c 6f 61 74  on to be a float
31420 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 20  ing point value 
31430 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20  specified.** by 
31440 69 74 73 20 32 6e 64 20 61 72 67 75 6d 65 6e 74  its 2nd argument
31450 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
31460 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
31470 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  r() and sqlite3_
31480 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29  result_error16()
31490 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 63 61   functions.** ca
314a0 75 73 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e  use the implemen
314b0 74 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ted SQL function
314c0 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 78 63   to throw an exc
314d0 65 70 74 69 6f 6e 2e 0a 2a 2a 20 5e 53 51 4c 69  eption..** ^SQLi
314e0 74 65 20 75 73 65 73 20 74 68 65 20 73 74 72 69  te uses the stri
314f0 6e 67 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79  ng pointed to by
31500 20 74 68 65 0a 2a 2a 20 32 6e 64 20 70 61 72 61   the.** 2nd para
31510 6d 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33  meter of sqlite3
31520 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20  _result_error() 
31530 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  or sqlite3_resul
31540 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20 61  t_error16().** a
31550 73 20 74 68 65 20 74 65 78 74 20 6f 66 20 61 6e  s the text of an
31560 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 20   error message. 
31570 20 5e 53 51 4c 69 74 65 20 69 6e 74 65 72 70 72   ^SQLite interpr
31580 65 74 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a  ets the error.**
31590 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20   message string 
315a0 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73  from sqlite3_res
315b0 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 73 20 55  ult_error() as U
315c0 54 46 2d 38 2e 20 5e 53 51 4c 69 74 65 0a 2a 2a  TF-8. ^SQLite.**
315d0 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 65 20   interprets the 
315e0 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69  string from sqli
315f0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
31600 31 36 28 29 20 61 73 20 55 54 46 2d 31 36 20 69  16() as UTF-16 i
31610 6e 20 6e 61 74 69 76 65 0a 2a 2a 20 62 79 74 65  n native.** byte
31620 20 6f 72 64 65 72 2e 20 20 5e 49 66 20 74 68 65   order.  ^If the
31630 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
31640 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75   to sqlite3_resu
31650 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72  lt_error().** or
31660 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
31670 65 72 72 6f 72 31 36 28 29 20 69 73 20 6e 65 67  error16() is neg
31680 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69 74  ative then SQLit
31690 65 20 74 61 6b 65 73 20 61 73 20 74 68 65 20 65  e takes as the e
316a0 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20  rror.** message 
316b0 61 6c 6c 20 74 65 78 74 20 75 70 20 74 68 72 6f  all text up thro
316c0 75 67 68 20 74 68 65 20 66 69 72 73 74 20 7a 65  ugh the first ze
316d0 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a  ro character..**
316e0 20 5e 49 66 20 74 68 65 20 74 68 69 72 64 20 70   ^If the third p
316f0 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
31700 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
31710 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  () or.** sqlite3
31720 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
31730 29 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  ) is non-negativ
31740 65 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61  e then SQLite ta
31750 6b 65 73 20 74 68 61 74 20 6d 61 6e 79 0a 2a 2a  kes that many.**
31760 20 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72   bytes (not char
31770 61 63 74 65 72 73 29 20 66 72 6f 6d 20 74 68 65  acters) from the
31780 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61   2nd parameter a
31790 73 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73  s the error mess
317a0 61 67 65 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  age..** ^The sql
317b0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
317c0 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  r() and sqlite3_
317d0 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29  result_error16()
317e0 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 6d 61 6b  .** routines mak
317f0 65 20 61 20 70 72 69 76 61 74 65 20 63 6f 70 79  e a private copy
31800 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20 6d 65   of the error me
31810 73 73 61 67 65 20 74 65 78 74 20 62 65 66 6f 72  ssage text befor
31820 65 0a 2a 2a 20 74 68 65 79 20 72 65 74 75 72 6e  e.** they return
31830 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20 63 61  .  Hence, the ca
31840 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63  lling function c
31850 61 6e 20 64 65 61 6c 6c 6f 63 61 74 65 20 6f 72  an deallocate or
31860 0a 2a 2a 20 6d 6f 64 69 66 79 20 74 68 65 20 74  .** modify the t
31870 65 78 74 20 61 66 74 65 72 20 74 68 65 79 20 72  ext after they r
31880 65 74 75 72 6e 20 77 69 74 68 6f 75 74 20 68 61  eturn without ha
31890 72 6d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  rm..** ^The sqli
318a0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
318b0 5f 63 6f 64 65 28 29 20 66 75 6e 63 74 69 6f 6e  _code() function
318c0 20 63 68 61 6e 67 65 73 20 74 68 65 20 65 72 72   changes the err
318d0 6f 72 20 63 6f 64 65 0a 2a 2a 20 72 65 74 75 72  or code.** retur
318e0 6e 65 64 20 62 79 20 53 51 4c 69 74 65 20 61 73  ned by SQLite as
318f0 20 61 20 72 65 73 75 6c 74 20 6f 66 20 61 6e 20   a result of an 
31900 65 72 72 6f 72 20 69 6e 20 61 20 66 75 6e 63 74  error in a funct
31910 69 6f 6e 2e 20 20 5e 42 79 20 64 65 66 61 75 6c  ion.  ^By defaul
31920 74 2c 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72 20  t,.** the error 
31930 63 6f 64 65 20 69 73 20 53 51 4c 49 54 45 5f 45  code is SQLITE_E
31940 52 52 4f 52 2e 20 20 5e 41 20 73 75 62 73 65 71  RROR.  ^A subseq
31950 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c  uent call to sql
31960 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
31970 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65  r().** or sqlite
31980 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
31990 28 29 20 72 65 73 65 74 73 20 74 68 65 20 65 72  () resets the er
319a0 72 6f 72 20 63 6f 64 65 20 74 6f 20 53 51 4c 49  ror code to SQLI
319b0 54 45 5f 45 52 52 4f 52 2e 0a 2a 2a 0a 2a 2a 20  TE_ERROR..**.** 
319c0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
319d0 75 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67  ult_error_toobig
319e0 28 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 75  () interface cau
319f0 73 65 73 20 53 51 4c 69 74 65 20 74 6f 20 74 68  ses SQLite to th
31a00 72 6f 77 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20  row an.** error 
31a10 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74 20  indicating that 
31a20 61 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42  a string or BLOB
31a30 20 69 73 20 74 6f 6f 20 6c 6f 6e 67 20 74 6f 20   is too long to 
31a40 72 65 70 72 65 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a  represent..**.**
31a50 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
31a60 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d  sult_error_nomem
31a70 28 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 75  () interface cau
31a80 73 65 73 20 53 51 4c 69 74 65 20 74 6f 20 74 68  ses SQLite to th
31a90 72 6f 77 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20  row an.** error 
31aa0 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74 20  indicating that 
31ab0 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
31ac0 69 6f 6e 20 66 61 69 6c 65 64 2e 0a 2a 2a 0a 2a  ion failed..**.*
31ad0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
31ae0 65 73 75 6c 74 5f 69 6e 74 28 29 20 69 6e 74 65  esult_int() inte
31af0 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72  rface sets the r
31b00 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f  eturn value.** o
31b10 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  f the applicatio
31b20 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
31b30 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 33 32 2d  on to be the 32-
31b40 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67  bit signed integ
31b50 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76 65  er.** value give
31b60 6e 20 69 6e 20 74 68 65 20 32 6e 64 20 61 72 67  n in the 2nd arg
31b70 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 73  ument..** ^The s
31b80 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e  qlite3_result_in
31b90 74 36 34 28 29 20 69 6e 74 65 72 66 61 63 65 20  t64() interface 
31ba0 73 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20  sets the return 
31bb0 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20  value.** of the 
31bc0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
31bd0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
31be0 62 65 20 74 68 65 20 36 34 2d 62 69 74 20 73 69  be the 64-bit si
31bf0 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20  gned integer.** 
31c00 76 61 6c 75 65 20 67 69 76 65 6e 20 69 6e 20 74  value given in t
31c10 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e  he 2nd argument.
31c20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
31c30 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28  te3_result_null(
31c40 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73  ) interface sets
31c50 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
31c60 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c  e.** of the appl
31c70 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
31c80 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 4e  function to be N
31c90 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ULL..**.** ^The 
31ca0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
31cb0 65 78 74 28 29 2c 20 73 71 6c 69 74 65 33 5f 72  ext(), sqlite3_r
31cc0 65 73 75 6c 74 5f 74 65 78 74 31 36 28 29 2c 0a  esult_text16(),.
31cd0 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  ** sqlite3_resul
31ce0 74 5f 74 65 78 74 31 36 6c 65 28 29 2c 20 61 6e  t_text16le(), an
31cf0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
31d00 5f 74 65 78 74 31 36 62 65 28 29 20 69 6e 74 65  _text16be() inte
31d10 72 66 61 63 65 73 0a 2a 2a 20 73 65 74 20 74 68  rfaces.** set th
31d20 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f  e return value o
31d30 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  f the applicatio
31d40 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
31d50 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 61 20 74 65  on to be.** a te
31d60 78 74 20 73 74 72 69 6e 67 20 77 68 69 63 68 20  xt string which 
31d70 69 73 20 72 65 70 72 65 73 65 6e 74 65 64 20 61  is represented a
31d80 73 20 55 54 46 2d 38 2c 20 55 54 46 2d 31 36 20  s UTF-8, UTF-16 
31d90 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
31da0 72 2c 0a 2a 2a 20 55 54 46 2d 31 36 20 6c 69 74  r,.** UTF-16 lit
31db0 74 6c 65 20 65 6e 64 69 61 6e 2c 20 6f 72 20 55  tle endian, or U
31dc0 54 46 2d 31 36 20 62 69 67 20 65 6e 64 69 61 6e  TF-16 big endian
31dd0 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a  , respectively..
31de0 2a 2a 20 5e 53 51 4c 69 74 65 20 74 61 6b 65 73  ** ^SQLite takes
31df0 20 74 68 65 20 74 65 78 74 20 72 65 73 75 6c 74   the text result
31e00 20 66 72 6f 6d 20 74 68 65 20 61 70 70 6c 69 63   from the applic
31e10 61 74 69 6f 6e 20 66 72 6f 6d 0a 2a 2a 20 74 68  ation from.** th
31e20 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  e 2nd parameter 
31e30 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72  of the sqlite3_r
31e40 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65  esult_text* inte
31e50 72 66 61 63 65 73 2e 0a 2a 2a 20 5e 49 66 20 74  rfaces..** ^If t
31e60 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  he 3rd parameter
31e70 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
31e80 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74  result_text* int
31e90 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e 65  erfaces.** is ne
31ea0 67 61 74 69 76 65 2c 20 74 68 65 6e 20 53 51 4c  gative, then SQL
31eb0 69 74 65 20 74 61 6b 65 73 20 72 65 73 75 6c 74  ite takes result
31ec0 20 74 65 78 74 20 66 72 6f 6d 20 74 68 65 20 32   text from the 2
31ed0 6e 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  nd parameter.** 
31ee0 74 68 72 6f 75 67 68 20 74 68 65 20 66 69 72 73  through the firs
31ef0 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74 65 72  t zero character
31f00 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 33 72 64  ..** ^If the 3rd
31f10 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
31f20 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
31f30 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65  _text* interface
31f40 73 0a 2a 2a 20 69 73 20 6e 6f 6e 2d 6e 65 67 61  s.** is non-nega
31f50 74 69 76 65 2c 20 74 68 65 6e 20 61 73 20 6d 61  tive, then as ma
31f60 6e 79 20 62 79 74 65 73 20 28 6e 6f 74 20 63 68  ny bytes (not ch
31f70 61 72 61 63 74 65 72 73 29 20 6f 66 20 74 68 65  aracters) of the
31f80 20 74 65 78 74 0a 2a 2a 20 70 6f 69 6e 74 65 64   text.** pointed
31f90 20 74 6f 20 62 79 20 74 68 65 20 32 6e 64 20 70   to by the 2nd p
31fa0 61 72 61 6d 65 74 65 72 20 61 72 65 20 74 61 6b  arameter are tak
31fb0 65 6e 20 61 73 20 74 68 65 20 61 70 70 6c 69 63  en as the applic
31fc0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 0a 2a 2a  ation-defined.**
31fd0 20 66 75 6e 63 74 69 6f 6e 20 72 65 73 75 6c 74   function result
31fe0 2e 20 20 49 66 20 74 68 65 20 33 72 64 20 70 61  .  If the 3rd pa
31ff0 72 61 6d 65 74 65 72 20 69 73 20 6e 6f 6e 2d 6e  rameter is non-n
32000 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 69 74  egative, then it
32010 0a 2a 2a 20 6d 75 73 74 20 62 65 20 74 68 65 20  .** must be the 
32020 62 79 74 65 20 6f 66 66 73 65 74 20 69 6e 74 6f  byte offset into
32030 20 74 68 65 20 73 74 72 69 6e 67 20 77 68 65 72   the string wher
32040 65 20 74 68 65 20 4e 55 4c 20 74 65 72 6d 69 6e  e the NUL termin
32050 61 74 6f 72 20 77 6f 75 6c 64 0a 2a 2a 20 61 70  ator would.** ap
32060 70 65 61 72 20 69 66 20 74 68 65 20 73 74 72 69  pear if the stri
32070 6e 67 20 77 68 65 72 65 20 4e 55 4c 20 74 65 72  ng where NUL ter
32080 6d 69 6e 61 74 65 64 2e 20 20 49 66 20 61 6e 79  minated.  If any
32090 20 4e 55 4c 20 63 68 61 72 61 63 74 65 72 73 20   NUL characters 
320a0 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20  occur.** in the 
320b0 73 74 72 69 6e 67 20 61 74 20 61 20 62 79 74 65  string at a byte
320c0 20 6f 66 66 73 65 74 20 74 68 61 74 20 69 73 20   offset that is 
320d0 6c 65 73 73 20 74 68 61 6e 20 74 68 65 20 76 61  less than the va
320e0 6c 75 65 20 6f 66 20 74 68 65 20 33 72 64 0a 2a  lue of the 3rd.*
320f0 2a 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65  * parameter, the
32100 6e 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20  n the resulting 
32110 73 74 72 69 6e 67 20 77 69 6c 6c 20 63 6f 6e 74  string will cont
32120 61 69 6e 20 65 6d 62 65 64 64 65 64 20 4e 55 4c  ain embedded NUL
32130 73 20 61 6e 64 20 74 68 65 0a 2a 2a 20 72 65 73  s and the.** res
32140 75 6c 74 20 6f 66 20 65 78 70 72 65 73 73 69 6f  ult of expressio
32150 6e 73 20 6f 70 65 72 61 74 69 6e 67 20 6f 6e 20  ns operating on 
32160 73 74 72 69 6e 67 73 20 77 69 74 68 20 65 6d 62  strings with emb
32170 65 64 64 65 64 20 4e 55 4c 73 20 69 73 20 75 6e  edded NULs is un
32180 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e 49 66 20  defined..** ^If 
32190 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65  the 4th paramete
321a0 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  r to the sqlite3
321b0 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e  _result_text* in
321c0 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73  terfaces.** or s
321d0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c  qlite3_result_bl
321e0 6f 62 20 69 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c  ob is a non-NULL
321f0 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 53   pointer, then S
32200 51 4c 69 74 65 20 63 61 6c 6c 73 20 74 68 61 74  QLite calls that
32210 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 61 73 20  .** function as 
32220 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 6f  the destructor o
32230 6e 20 74 68 65 20 74 65 78 74 20 6f 72 20 42 4c  n the text or BL
32240 4f 42 20 72 65 73 75 6c 74 20 77 68 65 6e 20 69  OB result when i
32250 74 20 68 61 73 0a 2a 2a 20 66 69 6e 69 73 68 65  t has.** finishe
32260 64 20 75 73 69 6e 67 20 74 68 61 74 20 72 65 73  d using that res
32270 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ult..** ^If the 
32280 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  4th parameter to
32290 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   the sqlite3_res
322a0 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66  ult_text* interf
322b0 61 63 65 73 20 6f 72 20 74 6f 0a 2a 2a 20 73 71  aces or to.** sq
322c0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f  lite3_result_blo
322d0 62 20 69 73 20 74 68 65 20 73 70 65 63 69 61 6c  b is the special
322e0 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54 45   constant SQLITE
322f0 5f 53 54 41 54 49 43 2c 20 74 68 65 6e 20 53 51  _STATIC, then SQ
32300 4c 69 74 65 0a 2a 2a 20 61 73 73 75 6d 65 73 20  Lite.** assumes 
32310 74 68 61 74 20 74 68 65 20 74 65 78 74 20 6f 72  that the text or
32320 20 42 4c 4f 42 20 72 65 73 75 6c 74 20 69 73 20   BLOB result is 
32330 69 6e 20 63 6f 6e 73 74 61 6e 74 20 73 70 61 63  in constant spac
32340 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 0a 2a  e and does not.*
32350 2a 20 63 6f 70 79 20 74 68 65 20 63 6f 6e 74 65  * copy the conte
32360 6e 74 20 6f 66 20 74 68 65 20 70 61 72 61 6d 65  nt of the parame
32370 74 65 72 20 6e 6f 72 20 63 61 6c 6c 20 61 20 64  ter nor call a d
32380 65 73 74 72 75 63 74 6f 72 20 6f 6e 20 74 68 65  estructor on the
32390 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20 77 68 65 6e   content.** when
323a0 20 69 74 20 68 61 73 20 66 69 6e 69 73 68 65 64   it has finished
323b0 20 75 73 69 6e 67 20 74 68 61 74 20 72 65 73 75   using that resu
323c0 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34  lt..** ^If the 4
323d0 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
323e0 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  the sqlite3_resu
323f0 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61  lt_text* interfa
32400 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65  ces.** or sqlite
32410 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73  3_result_blob is
32420 20 74 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e   the special con
32430 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 54 52 41  stant SQLITE_TRA
32440 4e 53 49 45 4e 54 0a 2a 2a 20 74 68 65 6e 20 53  NSIENT.** then S
32450 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f  QLite makes a co
32460 70 79 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  py of the result
32470 20 69 6e 74 6f 20 73 70 61 63 65 20 6f 62 74 61   into space obta
32480 69 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 66 72 6f  ined from.** fro
32490 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
324a0 63 28 29 5d 20 62 65 66 6f 72 65 20 69 74 20 72  c()] before it r
324b0 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  eturns..**.** ^T
324c0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
324d0 74 5f 76 61 6c 75 65 28 29 20 69 6e 74 65 72 66  t_value() interf
324e0 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73  ace sets the res
324f0 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70  ult of.** the ap
32500 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
32510 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
32520 20 61 20 63 6f 70 79 20 74 68 65 0a 2a 2a 20 5b   a copy the.** [
32530 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
32540 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
32550 74 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74  t specified by t
32560 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
32570 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74  .  ^The.** sqlit
32580 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28  e3_result_value(
32590 29 20 69 6e 74 65 72 66 61 63 65 20 6d 61 6b 65  ) interface make
325a0 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
325b0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a  [sqlite3_value].
325c0 2a 2a 20 73 6f 20 74 68 61 74 20 74 68 65 20 5b  ** so that the [
325d0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 73  sqlite3_value] s
325e0 70 65 63 69 66 69 65 64 20 69 6e 20 74 68 65 20  pecified in the 
325f0 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 63 68  parameter may ch
32600 61 6e 67 65 20 6f 72 0a 2a 2a 20 62 65 20 64 65  ange or.** be de
32610 61 6c 6c 6f 63 61 74 65 64 20 61 66 74 65 72 20  allocated after 
32620 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
32630 61 6c 75 65 28 29 20 72 65 74 75 72 6e 73 20 77  alue() returns w
32640 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20  ithout harm..** 
32650 5e 41 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71  ^A [protected sq
32660 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
32670 65 63 74 20 6d 61 79 20 61 6c 77 61 79 73 20 62  ect may always b
32680 65 20 75 73 65 64 20 77 68 65 72 65 20 61 6e 0a  e used where an.
32690 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20  ** [unprotected 
326a0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
326b0 62 6a 65 63 74 20 69 73 20 72 65 71 75 69 72 65  bject is require
326c0 64 2c 20 73 6f 20 65 69 74 68 65 72 0a 2a 2a 20  d, so either.** 
326d0 6b 69 6e 64 20 6f 66 20 5b 73 71 6c 69 74 65 33  kind of [sqlite3
326e0 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 63  _value] object c
326f0 61 6e 20 62 65 20 75 73 65 64 20 77 69 74 68 20  an be used with 
32700 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e 0a  this interface..
32710 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 73 65 20 72  **.** If these r
32720 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c  outines are call
32730 65 64 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 74  ed from within t
32740 68 65 20 64 69 66 66 65 72 65 6e 74 20 74 68 72  he different thr
32750 65 61 64 0a 2a 2a 20 74 68 61 6e 20 74 68 65 20  ead.** than the 
32760 6f 6e 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  one containing t
32770 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
32780 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
32790 74 68 61 74 20 72 65 63 65 69 76 65 64 0a 2a 2a  that received.**
327a0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   the [sqlite3_co
327b0 6e 74 65 78 74 5d 20 70 6f 69 6e 74 65 72 2c 20  ntext] pointer, 
327c0 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20  the results are 
327d0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 76 6f  undefined..*/.vo
327e0 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
327f0 74 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63  t_blob(sqlite3_c
32800 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76  ontext*, const v
32810 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28  oid*, int, void(
32820 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64  *)(void*));.void
32830 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
32840 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 63  double(sqlite3_c
32850 6f 6e 74 65 78 74 2a 2c 20 64 6f 75 62 6c 65 29  ontext*, double)
32860 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
32870 65 73 75 6c 74 5f 65 72 72 6f 72 28 73 71 6c 69  esult_error(sqli
32880 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f  te3_context*, co
32890 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 29 3b  nst char*, int);
328a0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
328b0 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 73 71 6c  sult_error16(sql
328c0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63  ite3_context*, c
328d0 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 29  onst void*, int)
328e0 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
328f0 65 73 75 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62  esult_error_toob
32900 69 67 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ig(sqlite3_conte
32910 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  xt*);.void sqlit
32920 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f  e3_result_error_
32930 6e 6f 6d 65 6d 28 73 71 6c 69 74 65 33 5f 63 6f  nomem(sqlite3_co
32940 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71  ntext*);.void sq
32950 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
32960 6f 72 5f 63 6f 64 65 28 73 71 6c 69 74 65 33 5f  or_code(sqlite3_
32970 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a  context*, int);.
32980 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
32990 75 6c 74 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f  ult_int(sqlite3_
329a0 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a  context*, int);.
329b0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
329c0 75 6c 74 5f 69 6e 74 36 34 28 73 71 6c 69 74 65  ult_int64(sqlite
329d0 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69  3_context*, sqli
329e0 74 65 33 5f 69 6e 74 36 34 29 3b 0a 76 6f 69 64  te3_int64);.void
329f0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
32a00 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 63 6f 6e  null(sqlite3_con
32a10 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c  text*);.void sql
32a20 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
32a30 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
32a40 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  *, const char*, 
32a50 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  int, void(*)(voi
32a60 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  d*));.void sqlit
32a70 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
32a80 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
32a90 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  *, const void*, 
32aa0 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  int, void(*)(voi
32ab0 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  d*));.void sqlit
32ac0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
32ad0 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  le(sqlite3_conte
32ae0 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  xt*, const void*
32af0 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f  , int,void(*)(vo
32b00 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69  id*));.void sqli
32b10 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
32b20 36 62 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  6be(sqlite3_cont
32b30 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64  ext*, const void
32b40 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76  *, int,void(*)(v
32b50 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c  oid*));.void sql
32b60 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75  ite3_result_valu
32b70 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  e(sqlite3_contex
32b80 74 2a 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  t*, sqlite3_valu
32b90 65 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  e*);.void sqlite
32ba0 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f  3_result_zeroblo
32bb0 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  b(sqlite3_contex
32bc0 74 2a 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a  t*, int n);../*.
32bd0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 66  ** CAPI3REF: Def
32be0 69 6e 65 20 4e 65 77 20 43 6f 6c 6c 61 74 69 6e  ine New Collatin
32bf0 67 20 53 65 71 75 65 6e 63 65 73 0a 2a 2a 0a 2a  g Sequences.**.*
32c00 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f  * ^These functio
32c10 6e 73 20 61 64 64 2c 20 72 65 6d 6f 76 65 2c 20  ns add, remove, 
32c20 6f 72 20 6d 6f 64 69 66 79 20 61 20 5b 63 6f 6c  or modify a [col
32c30 6c 61 74 69 6f 6e 5d 20 61 73 73 6f 63 69 61 74  lation] associat
32c40 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b  ed.** with the [
32c50 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
32c60 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20 61  ion] specified a
32c70 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  s the first argu
32c80 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ment..**.** ^The
32c90 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c   name of the col
32ca0 6c 61 74 69 6f 6e 20 69 73 20 61 20 55 54 46 2d  lation is a UTF-
32cb0 38 20 73 74 72 69 6e 67 0a 2a 2a 20 66 6f 72 20  8 string.** for 
32cc0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
32cd0 6f 6c 6c 61 74 69 6f 6e 28 29 20 61 6e 64 20 73  ollation() and s
32ce0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
32cf0 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 0a 2a 2a 20  llation_v2().** 
32d00 61 6e 64 20 61 20 55 54 46 2d 31 36 20 73 74 72  and a UTF-16 str
32d10 69 6e 67 20 69 6e 20 6e 61 74 69 76 65 20 62 79  ing in native by
32d20 74 65 20 6f 72 64 65 72 20 66 6f 72 20 73 71 6c  te order for sql
32d30 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
32d40 61 74 69 6f 6e 31 36 28 29 2e 0a 2a 2a 20 5e 43  ation16()..** ^C
32d50 6f 6c 6c 61 74 69 6f 6e 20 6e 61 6d 65 73 20 74  ollation names t
32d60 68 61 74 20 63 6f 6d 70 61 72 65 20 65 71 75 61  hat compare equa
32d70 6c 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 5b  l according to [
32d80 73 71 6c 69 74 65 33 5f 73 74 72 6e 69 63 6d 70  sqlite3_strnicmp
32d90 28 29 5d 20 61 72 65 0a 2a 2a 20 63 6f 6e 73 69  ()] are.** consi
32da0 64 65 72 65 64 20 74 6f 20 62 65 20 74 68 65 20  dered to be the 
32db0 73 61 6d 65 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a  same name..**.**
32dc0 20 5e 28 54 68 65 20 74 68 69 72 64 20 61 72 67   ^(The third arg
32dd0 75 6d 65 6e 74 20 28 65 54 65 78 74 52 65 70 29  ument (eTextRep)
32de0 20 6d 75 73 74 20 62 65 20 6f 6e 65 20 6f 66 20   must be one of 
32df0 74 68 65 20 63 6f 6e 73 74 61 6e 74 73 3a 0a 2a  the constants:.*
32e00 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b  * <ul>.** <li> [
32e10 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 0a 2a 2a  SQLITE_UTF8],.**
32e20 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54   <li> [SQLITE_UT
32e30 46 31 36 4c 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20  F16LE],.** <li> 
32e40 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d  [SQLITE_UTF16BE]
32e50 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ,.** <li> [SQLIT
32e60 45 5f 55 54 46 31 36 5d 2c 20 6f 72 0a 2a 2a 20  E_UTF16], or.** 
32e70 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46  <li> [SQLITE_UTF
32e80 31 36 5f 41 4c 49 47 4e 45 44 5d 2e 0a 2a 2a 20  16_ALIGNED]..** 
32e90 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 54 68 65 20  </ul>)^.** ^The 
32ea0 65 54 65 78 74 52 65 70 20 61 72 67 75 6d 65 6e  eTextRep argumen
32eb0 74 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68 65  t determines the
32ec0 20 65 6e 63 6f 64 69 6e 67 20 6f 66 20 73 74 72   encoding of str
32ed0 69 6e 67 73 20 70 61 73 73 65 64 0a 2a 2a 20 74  ings passed.** t
32ee0 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20  o the collating 
32ef0 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63  function callbac
32f00 6b 2c 20 78 43 61 6c 6c 62 61 63 6b 2e 0a 2a 2a  k, xCallback..**
32f10 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 55 54   ^The [SQLITE_UT
32f20 46 31 36 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45  F16] and [SQLITE
32f30 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d 20  _UTF16_ALIGNED] 
32f40 76 61 6c 75 65 73 20 66 6f 72 20 65 54 65 78 74  values for eText
32f50 52 65 70 0a 2a 2a 20 66 6f 72 63 65 20 73 74 72  Rep.** force str
32f60 69 6e 67 73 20 74 6f 20 62 65 20 55 54 46 31 36  ings to be UTF16
32f70 20 77 69 74 68 20 6e 61 74 69 76 65 20 62 79 74   with native byt
32f80 65 20 6f 72 64 65 72 2e 0a 2a 2a 20 5e 54 68 65  e order..** ^The
32f90 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41   [SQLITE_UTF16_A
32fa0 4c 49 47 4e 45 44 5d 20 76 61 6c 75 65 20 66 6f  LIGNED] value fo
32fb0 72 20 65 54 65 78 74 52 65 70 20 66 6f 72 63 65  r eTextRep force
32fc0 73 20 73 74 72 69 6e 67 73 20 74 6f 20 62 65 67  s strings to beg
32fd0 69 6e 0a 2a 2a 20 6f 6e 20 61 6e 20 65 76 65 6e  in.** on an even
32fe0 20 62 79 74 65 20 61 64 64 72 65 73 73 2e 0a 2a   byte address..*
32ff0 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68  *.** ^The fourth
33000 20 61 72 67 75 6d 65 6e 74 2c 20 70 41 72 67 2c   argument, pArg,
33010 20 69 73 20 61 6e 20 61 70 70 6c 69 63 61 74 69   is an applicati
33020 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 20  on data pointer 
33030 74 68 61 74 20 69 73 20 70 61 73 73 65 64 0a 2a  that is passed.*
33040 2a 20 74 68 72 6f 75 67 68 20 61 73 20 74 68 65  * through as the
33050 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
33060 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67  to the collating
33070 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61   function callba
33080 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  ck..**.** ^The f
33090 69 66 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 78  ifth argument, x
330a0 43 61 6c 6c 62 61 63 6b 2c 20 69 73 20 61 20 70  Callback, is a p
330b0 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 63 6f  ointer to the co
330c0 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
330d0 2e 0a 2a 2a 20 5e 4d 75 6c 74 69 70 6c 65 20 63  ..** ^Multiple c
330e0 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
330f0 6e 73 20 63 61 6e 20 62 65 20 72 65 67 69 73 74  ns can be regist
33100 65 72 65 64 20 75 73 69 6e 67 20 74 68 65 20 73  ered using the s
33110 61 6d 65 20 6e 61 6d 65 20 62 75 74 0a 2a 2a 20  ame name but.** 
33120 77 69 74 68 20 64 69 66 66 65 72 65 6e 74 20 65  with different e
33130 54 65 78 74 52 65 70 20 70 61 72 61 6d 65 74 65  TextRep paramete
33140 72 73 20 61 6e 64 20 53 51 4c 69 74 65 20 77 69  rs and SQLite wi
33150 6c 6c 20 75 73 65 20 77 68 69 63 68 65 76 65 72  ll use whichever
33160 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 72 65 71  .** function req
33170 75 69 72 65 73 20 74 68 65 20 6c 65 61 73 74 20  uires the least 
33180 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74 61 20 74  amount of data t
33190 72 61 6e 73 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  ransformation..*
331a0 2a 20 5e 49 66 20 74 68 65 20 78 43 61 6c 6c 62  * ^If the xCallb
331b0 61 63 6b 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ack argument is 
331c0 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65 20 63 6f  NULL then the co
331d0 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
331e0 20 69 73 0a 2a 2a 20 64 65 6c 65 74 65 64 2e 20   is.** deleted. 
331f0 20 5e 57 68 65 6e 20 61 6c 6c 20 63 6f 6c 6c 61   ^When all colla
33200 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 68  ting functions h
33210 61 76 69 6e 67 20 74 68 65 20 73 61 6d 65 20 6e  aving the same n
33220 61 6d 65 20 61 72 65 20 64 65 6c 65 74 65 64 2c  ame are deleted,
33230 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 6c 61 74 69  .** that collati
33240 6f 6e 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20  on is no longer 
33250 75 73 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54  usable..**.** ^T
33260 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e  he collating fun
33270 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 20 69  ction callback i
33280 73 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61  s invoked with a
33290 20 63 6f 70 79 20 6f 66 20 74 68 65 20 70 41 72   copy of the pAr
332a0 67 20 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f  g .** applicatio
332b0 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 20 61  n data pointer a
332c0 6e 64 20 77 69 74 68 20 74 77 6f 20 73 74 72 69  nd with two stri
332d0 6e 67 73 20 69 6e 20 74 68 65 20 65 6e 63 6f 64  ngs in the encod
332e0 69 6e 67 20 73 70 65 63 69 66 69 65 64 0a 2a 2a  ing specified.**
332f0 20 62 79 20 74 68 65 20 65 54 65 78 74 52 65 70   by the eTextRep
33300 20 61 72 67 75 6d 65 6e 74 2e 20 20 54 68 65 20   argument.  The 
33310 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
33320 6f 6e 20 6d 75 73 74 20 72 65 74 75 72 6e 20 61  on must return a
33330 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20 74 68 61  n.** integer tha
33340 74 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 7a  t is negative, z
33350 65 72 6f 2c 20 6f 72 20 70 6f 73 69 74 69 76 65  ero, or positive
33360 0a 2a 2a 20 69 66 20 74 68 65 20 66 69 72 73 74  .** if the first
33370 20 73 74 72 69 6e 67 20 69 73 20 6c 65 73 73 20   string is less 
33380 74 68 61 6e 2c 20 65 71 75 61 6c 20 74 6f 2c 20  than, equal to, 
33390 6f 72 20 67 72 65 61 74 65 72 20 74 68 61 6e 20  or greater than 
333a0 74 68 65 20 73 65 63 6f 6e 64 2c 0a 2a 2a 20 72  the second,.** r
333b0 65 73 70 65 63 74 69 76 65 6c 79 2e 20 20 41 20  espectively.  A 
333c0 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
333d0 6f 6e 20 6d 75 73 74 20 61 6c 77 61 79 73 20 72  on must always r
333e0 65 74 75 72 6e 20 74 68 65 20 73 61 6d 65 20 61  eturn the same a
333f0 6e 73 77 65 72 0a 2a 2a 20 67 69 76 65 6e 20 74  nswer.** given t
33400 68 65 20 73 61 6d 65 20 69 6e 70 75 74 73 2e 20  he same inputs. 
33410 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20   If two or more 
33420 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
33430 6f 6e 73 20 61 72 65 20 72 65 67 69 73 74 65 72  ons are register
33440 65 64 0a 2a 2a 20 74 6f 20 74 68 65 20 73 61 6d  ed.** to the sam
33450 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 6e 61 6d 65  e collation name
33460 20 28 75 73 69 6e 67 20 64 69 66 66 65 72 65 6e   (using differen
33470 74 20 65 54 65 78 74 52 65 70 20 76 61 6c 75 65  t eTextRep value
33480 73 29 20 74 68 65 6e 20 61 6c 6c 0a 2a 2a 20 6d  s) then all.** m
33490 75 73 74 20 67 69 76 65 20 61 6e 20 65 71 75 69  ust give an equi
334a0 76 61 6c 65 6e 74 20 61 6e 73 77 65 72 20 77 68  valent answer wh
334b0 65 6e 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20  en invoked with 
334c0 65 71 75 69 76 61 6c 65 6e 74 20 73 74 72 69 6e  equivalent strin
334d0 67 73 2e 0a 2a 2a 20 54 68 65 20 63 6f 6c 6c 61  gs..** The colla
334e0 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75  ting function mu
334f0 73 74 20 6f 62 65 79 20 74 68 65 20 66 6f 6c 6c  st obey the foll
33500 6f 77 69 6e 67 20 70 72 6f 70 65 72 74 69 65 73  owing properties
33510 20 66 6f 72 20 61 6c 6c 0a 2a 2a 20 73 74 72 69   for all.** stri
33520 6e 67 73 20 41 2c 20 42 2c 20 61 6e 64 20 43 3a  ngs A, B, and C:
33530 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c  .**.** <ol>.** <
33540 6c 69 3e 20 49 66 20 41 3d 3d 42 20 74 68 65 6e  li> If A==B then
33550 20 42 3d 3d 41 2e 0a 2a 2a 20 3c 6c 69 3e 20 49   B==A..** <li> I
33560 66 20 41 3d 3d 42 20 61 6e 64 20 42 3d 3d 43 20  f A==B and B==C 
33570 74 68 65 6e 20 41 3d 3d 43 2e 0a 2a 2a 20 3c 6c  then A==C..** <l
33580 69 3e 20 49 66 20 41 26 6c 74 3b 42 20 54 48 45  i> If A&lt;B THE
33590 4e 20 42 26 67 74 3b 41 2e 0a 2a 2a 20 3c 6c 69  N B&gt;A..** <li
335a0 3e 20 49 66 20 41 26 6c 74 3b 42 20 61 6e 64 20  > If A&lt;B and 
335b0 42 26 6c 74 3b 43 20 74 68 65 6e 20 41 26 6c 74  B&lt;C then A&lt
335c0 3b 43 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a  ;C..** </ol>.**.
335d0 2a 2a 20 49 66 20 61 20 63 6f 6c 6c 61 74 69 6e  ** If a collatin
335e0 67 20 66 75 6e 63 74 69 6f 6e 20 66 61 69 6c 73  g function fails
335f0 20 61 6e 79 20 6f 66 20 74 68 65 20 61 62 6f 76   any of the abov
33600 65 20 63 6f 6e 73 74 72 61 69 6e 74 73 20 61 6e  e constraints an
33610 64 20 74 68 61 74 0a 2a 2a 20 63 6f 6c 6c 61 74  d that.** collat
33620 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  ing function is 
33630 20 72 65 67 69 73 74 65 72 65 64 20 61 6e 64 20   registered and 
33640 75 73 65 64 2c 20 74 68 65 6e 20 74 68 65 20 62  used, then the b
33650 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 74  ehavior of SQLit
33660 65 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e 65  e.** is undefine
33670 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  d..**.** ^The sq
33680 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
33690 6c 61 74 69 6f 6e 5f 76 32 28 29 20 77 6f 72 6b  lation_v2() work
336a0 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f 63  s like sqlite3_c
336b0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28  reate_collation(
336c0 29 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 61 64  ).** with the ad
336d0 64 69 74 69 6f 6e 20 74 68 61 74 20 74 68 65 20  dition that the 
336e0 78 44 65 73 74 72 6f 79 20 63 61 6c 6c 62 61 63  xDestroy callbac
336f0 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 20  k is invoked on 
33700 70 41 72 67 20 77 68 65 6e 0a 2a 2a 20 74 68 65  pArg when.** the
33710 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
33720 69 6f 6e 20 69 73 20 64 65 6c 65 74 65 64 2e 0a  ion is deleted..
33730 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6e 67 20 66 75  ** ^Collating fu
33740 6e 63 74 69 6f 6e 73 20 61 72 65 20 64 65 6c 65  nctions are dele
33750 74 65 64 20 77 68 65 6e 20 74 68 65 79 20 61 72  ted when they ar
33760 65 20 6f 76 65 72 72 69 64 64 65 6e 20 62 79 20  e overridden by 
33770 6c 61 74 65 72 0a 2a 2a 20 63 61 6c 6c 73 20 74  later.** calls t
33780 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20  o the collation 
33790 63 72 65 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f  creation functio
337a0 6e 73 20 6f 72 20 77 68 65 6e 20 74 68 65 0a 2a  ns or when the.*
337b0 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
337c0 65 63 74 69 6f 6e 5d 20 69 73 20 63 6c 6f 73 65  ection] is close
337d0 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
337e0 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a  _close()]..**.**
337f0 20 5e 54 68 65 20 78 44 65 73 74 72 6f 79 20 63   ^The xDestroy c
33800 61 6c 6c 62 61 63 6b 20 69 73 20 3c 75 3e 6e 6f  allback is <u>no
33810 74 3c 2f 75 3e 20 63 61 6c 6c 65 64 20 69 66 20  t</u> called if 
33820 74 68 65 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  the .** sqlite3_
33830 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
33840 5f 76 32 28 29 20 66 75 6e 63 74 69 6f 6e 20 66  _v2() function f
33850 61 69 6c 73 2e 20 20 41 70 70 6c 69 63 61 74 69  ails.  Applicati
33860 6f 6e 73 20 74 68 61 74 20 69 6e 76 6f 6b 65 0a  ons that invoke.
33870 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  ** sqlite3_creat
33880 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29  e_collation_v2()
33890 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c   with a non-NULL
338a0 20 78 44 65 73 74 72 6f 79 20 61 72 67 75 6d 65   xDestroy argume
338b0 6e 74 20 73 68 6f 75 6c 64 20 0a 2a 2a 20 63 68  nt should .** ch
338c0 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63  eck the return c
338d0 6f 64 65 20 61 6e 64 20 64 69 73 70 6f 73 65 20  ode and dispose 
338e0 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  of the applicati
338f0 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 0a  on data pointer.
33900 2a 2a 20 74 68 65 6d 73 65 6c 76 65 73 20 72 61  ** themselves ra
33910 74 68 65 72 20 74 68 61 6e 20 65 78 70 65 63 74  ther than expect
33920 69 6e 67 20 53 51 4c 69 74 65 20 74 6f 20 64 65  ing SQLite to de
33930 61 6c 20 77 69 74 68 20 69 74 20 66 6f 72 20 74  al with it for t
33940 68 65 6d 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20  hem..** This is 
33950 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 65  different from e
33960 76 65 72 79 20 6f 74 68 65 72 20 53 51 4c 69 74  very other SQLit
33970 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20 54 68  e interface.  Th
33980 65 20 69 6e 63 6f 6e 73 69 73 74 65 6e 63 79 20  e inconsistency 
33990 0a 2a 2a 20 69 73 20 75 6e 66 6f 72 74 75 6e 61  .** is unfortuna
339a0 74 65 20 62 75 74 20 63 61 6e 6e 6f 74 20 62 65  te but cannot be
339b0 20 63 68 61 6e 67 65 64 20 77 69 74 68 6f 75 74   changed without
339c0 20 62 72 65 61 6b 69 6e 67 20 62 61 63 6b 77 61   breaking backwa
339d0 72 64 73 20 0a 2a 2a 20 63 6f 6d 70 61 74 69 62  rds .** compatib
339e0 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  ility..**.** See
339f0 20 61 6c 73 6f 3a 20 20 5b 73 71 6c 69 74 65 33   also:  [sqlite3
33a00 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
33a10 64 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  d()] and [sqlite
33a20 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
33a30 65 64 31 36 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20  ed16()]..*/.int 
33a40 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
33a50 6f 6c 6c 61 74 69 6f 6e 28 0a 20 20 73 71 6c 69  ollation(.  sqli
33a60 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63  te3*, .  const c
33a70 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69  har *zName, .  i
33a80 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20  nt eTextRep, .  
33a90 76 6f 69 64 20 2a 70 41 72 67 2c 0a 20 20 69 6e  void *pArg,.  in
33aa0 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69  t(*xCompare)(voi
33ab0 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69  d*,int,const voi
33ac0 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69  d*,int,const voi
33ad0 64 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  d*).);.int sqlit
33ae0 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
33af0 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74 65  ion_v2(.  sqlite
33b00 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68 61  3*, .  const cha
33b10 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74  r *zName, .  int
33b20 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f   eTextRep, .  vo
33b30 69 64 20 2a 70 41 72 67 2c 0a 20 20 69 6e 74 28  id *pArg,.  int(
33b40 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a  *xCompare)(void*
33b50 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a  ,int,const void*
33b60 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a  ,int,const void*
33b70 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74  ),.  void(*xDest
33b80 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 69  roy)(void*).);.i
33b90 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nt sqlite3_creat
33ba0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 0a 20  e_collation16(. 
33bb0 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f   sqlite3*, .  co
33bc0 6e 73 74 20 76 6f 69 64 20 2a 7a 4e 61 6d 65 2c  nst void *zName,
33bd0 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c  .  int eTextRep,
33be0 20 0a 20 20 76 6f 69 64 20 2a 70 41 72 67 2c 0a   .  void *pArg,.
33bf0 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29    int(*xCompare)
33c00 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74  (void*,int,const
33c10 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74   void*,int,const
33c20 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a   void*).);../*.*
33c30 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 6c  * CAPI3REF: Coll
33c40 61 74 69 6f 6e 20 4e 65 65 64 65 64 20 43 61 6c  ation Needed Cal
33c50 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 6f  lbacks.**.** ^To
33c60 20 61 76 6f 69 64 20 68 61 76 69 6e 67 20 74 6f   avoid having to
33c70 20 72 65 67 69 73 74 65 72 20 61 6c 6c 20 63 6f   register all co
33c80 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65  llation sequence
33c90 73 20 62 65 66 6f 72 65 20 61 20 64 61 74 61 62  s before a datab
33ca0 61 73 65 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73  ase.** can be us
33cb0 65 64 2c 20 61 20 73 69 6e 67 6c 65 20 63 61 6c  ed, a single cal
33cc0 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6d  lback function m
33cd0 61 79 20 62 65 20 72 65 67 69 73 74 65 72 65 64  ay be registered
33ce0 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 64 61   with the.** [da
33cf0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
33d00 6e 5d 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64  n] to be invoked
33d10 20 77 68 65 6e 65 76 65 72 20 61 6e 20 75 6e 64   whenever an und
33d20 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e  efined collation
33d30 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 69 73 20  .** sequence is 
33d40 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20  required..**.** 
33d50 5e 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  ^If the function
33d60 20 69 73 20 72 65 67 69 73 74 65 72 65 64 20 75   is registered u
33d70 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33  sing the sqlite3
33d80 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
33d90 64 28 29 20 41 50 49 2c 0a 2a 2a 20 74 68 65 6e  d() API,.** then
33da0 20 69 74 20 69 73 20 70 61 73 73 65 64 20 74 68   it is passed th
33db0 65 20 6e 61 6d 65 73 20 6f 66 20 75 6e 64 65 66  e names of undef
33dc0 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73  ined collation s
33dd0 65 71 75 65 6e 63 65 73 20 61 73 20 73 74 72 69  equences as stri
33de0 6e 67 73 0a 2a 2a 20 65 6e 63 6f 64 65 64 20 69  ngs.** encoded i
33df0 6e 20 55 54 46 2d 38 2e 20 5e 49 66 20 73 71 6c  n UTF-8. ^If sql
33e00 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
33e10 65 65 64 65 64 31 36 28 29 20 69 73 20 75 73 65  eeded16() is use
33e20 64 2c 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 73 20  d,.** the names 
33e30 61 72 65 20 70 61 73 73 65 64 20 61 73 20 55 54  are passed as UT
33e40 46 2d 31 36 20 69 6e 20 6d 61 63 68 69 6e 65 20  F-16 in machine 
33e50 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
33e60 72 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f  r..** ^A call to
33e70 20 65 69 74 68 65 72 20 66 75 6e 63 74 69 6f 6e   either function
33e80 20 72 65 70 6c 61 63 65 73 20 74 68 65 20 65 78   replaces the ex
33e90 69 73 74 69 6e 67 20 63 6f 6c 6c 61 74 69 6f 6e  isting collation
33ea0 2d 6e 65 65 64 65 64 20 63 61 6c 6c 62 61 63 6b  -needed callback
33eb0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 57 68 65 6e 20 74  ..**.** ^(When t
33ec0 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  he callback is i
33ed0 6e 76 6f 6b 65 64 2c 20 74 68 65 20 66 69 72 73  nvoked, the firs
33ee0 74 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65  t argument passe
33ef0 64 20 69 73 20 61 20 63 6f 70 79 0a 2a 2a 20 6f  d is a copy.** o
33f00 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  f the second arg
33f10 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
33f20 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
33f30 64 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  d() or.** sqlite
33f40 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
33f50 65 64 31 36 28 29 2e 20 20 54 68 65 20 73 65 63  ed16().  The sec
33f60 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ond argument is 
33f70 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  the database.** 
33f80 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 54 68 65  connection.  The
33f90 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
33fa0 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  is one of [SQLIT
33fb0 45 5f 55 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45  E_UTF8], [SQLITE
33fc0 5f 55 54 46 31 36 42 45 5d 2c 0a 2a 2a 20 6f 72  _UTF16BE],.** or
33fd0 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45   [SQLITE_UTF16LE
33fe0 5d 2c 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68  ], indicating th
33ff0 65 20 6d 6f 73 74 20 64 65 73 69 72 61 62 6c 65  e most desirable
34000 20 66 6f 72 6d 20 6f 66 20 74 68 65 20 63 6f 6c   form of the col
34010 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e  lation.** sequen
34020 63 65 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75  ce function requ
34030 69 72 65 64 2e 20 20 54 68 65 20 66 6f 75 72 74  ired.  The fourt
34040 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  h parameter is t
34050 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a  he name of the.*
34060 2a 20 72 65 71 75 69 72 65 64 20 63 6f 6c 6c 61  * required colla
34070 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 2e 29 5e  tion sequence.)^
34080 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62  .**.** The callb
34090 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f  ack function sho
340a0 75 6c 64 20 72 65 67 69 73 74 65 72 20 74 68 65  uld register the
340b0 20 64 65 73 69 72 65 64 20 63 6f 6c 6c 61 74 69   desired collati
340c0 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c  on using.** [sql
340d0 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
340e0 61 74 69 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  ation()], [sqlit
340f0 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
34100 69 6f 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20  ion16()], or.** 
34110 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
34120 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 5d 2e  collation_v2()].
34130 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
34140 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
34150 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20  (.  sqlite3*, . 
34160 20 76 6f 69 64 2a 2c 20 0a 20 20 76 6f 69 64 28   void*, .  void(
34170 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33  *)(void*,sqlite3
34180 2a 2c 69 6e 74 20 65 54 65 78 74 52 65 70 2c 63  *,int eTextRep,c
34190 6f 6e 73 74 20 63 68 61 72 2a 29 0a 29 3b 0a 69  onst char*).);.i
341a0 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61  nt sqlite3_colla
341b0 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 0a 20  tion_needed16(. 
341c0 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f   sqlite3*, .  vo
341d0 69 64 2a 2c 0a 20 20 76 6f 69 64 28 2a 29 28 76  id*,.  void(*)(v
341e0 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e  oid*,sqlite3*,in
341f0 74 20 65 54 65 78 74 52 65 70 2c 63 6f 6e 73 74  t eTextRep,const
34200 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 23 69 66 64   void*).);..#ifd
34210 65 66 20 53 51 4c 49 54 45 5f 48 41 53 5f 43 4f  ef SQLITE_HAS_CO
34220 44 45 43 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66  DEC./*.** Specif
34230 79 20 74 68 65 20 6b 65 79 20 66 6f 72 20 61 6e  y the key for an
34240 20 65 6e 63 72 79 70 74 65 64 20 64 61 74 61 62   encrypted datab
34250 61 73 65 2e 20 20 54 68 69 73 20 72 6f 75 74 69  ase.  This routi
34260 6e 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20  ne should be.** 
34270 63 61 6c 6c 65 64 20 72 69 67 68 74 20 61 66 74  called right aft
34280 65 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  er sqlite3_open(
34290 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64  )..**.** The cod
342a0 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74  e to implement t
342b0 68 69 73 20 41 50 49 20 69 73 20 6e 6f 74 20 61  his API is not a
342c0 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 20  vailable in the 
342d0 70 75 62 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a  public release.*
342e0 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a  * of SQLite..*/.
342f0 69 6e 74 20 73 71 6c 69 74 65 33 5f 6b 65 79 28  int sqlite3_key(
34300 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
34310 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
34320 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f    /* Database to
34330 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20   be rekeyed */. 
34340 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65   const void *pKe
34350 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20  y, int nKey     
34360 2f 2a 20 54 68 65 20 6b 65 79 20 2a 2f 0a 29 3b  /* The key */.);
34370 0a 0a 2f 2a 0a 2a 2a 20 43 68 61 6e 67 65 20 74  ../*.** Change t
34380 68 65 20 6b 65 79 20 6f 6e 20 61 6e 20 6f 70 65  he key on an ope
34390 6e 20 64 61 74 61 62 61 73 65 2e 20 20 49 66 20  n database.  If 
343a0 74 68 65 20 63 75 72 72 65 6e 74 20 64 61 74 61  the current data
343b0 62 61 73 65 20 69 73 20 6e 6f 74 0a 2a 2a 20 65  base is not.** e
343c0 6e 63 72 79 70 74 65 64 2c 20 74 68 69 73 20 72  ncrypted, this r
343d0 6f 75 74 69 6e 65 20 77 69 6c 6c 20 65 6e 63 72  outine will encr
343e0 79 70 74 20 69 74 2e 20 20 49 66 20 70 4e 65 77  ypt it.  If pNew
343f0 3d 3d 30 20 6f 72 20 6e 4e 65 77 3d 3d 30 2c 20  ==0 or nNew==0, 
34400 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  the.** database 
34410 69 73 20 64 65 63 72 79 70 74 65 64 2e 0a 2a 2a  is decrypted..**
34420 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 74 6f 20  .** The code to 
34430 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73 20 41  implement this A
34440 50 49 20 69 73 20 6e 6f 74 20 61 76 61 69 6c 61  PI is not availa
34450 62 6c 65 20 69 6e 20 74 68 65 20 70 75 62 6c 69  ble in the publi
34460 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20  c release.** of 
34470 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73  SQLite..*/.int s
34480 71 6c 69 74 65 33 5f 72 65 6b 65 79 28 0a 20 20  qlite3_rekey(.  
34490 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
344a0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
344b0 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20 62 65  * Database to be
344c0 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f   rekeyed */.  co
344d0 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20  nst void *pKey, 
344e0 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20  int nKey     /* 
344f0 54 68 65 20 6e 65 77 20 6b 65 79 20 2a 2f 0a 29  The new key */.)
34500 3b 0a 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79  ;../*.** Specify
34510 20 74 68 65 20 61 63 74 69 76 61 74 69 6f 6e 20   the activation 
34520 6b 65 79 20 66 6f 72 20 61 20 53 45 45 20 64 61  key for a SEE da
34530 74 61 62 61 73 65 2e 20 20 55 6e 6c 65 73 73 20  tabase.  Unless 
34540 0a 2a 2a 20 61 63 74 69 76 61 74 65 64 2c 20 6e  .** activated, n
34550 6f 6e 65 20 6f 66 20 74 68 65 20 53 45 45 20 72  one of the SEE r
34560 6f 75 74 69 6e 65 73 20 77 69 6c 6c 20 77 6f 72  outines will wor
34570 6b 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74  k..*/.void sqlit
34580 65 33 5f 61 63 74 69 76 61 74 65 5f 73 65 65 28  e3_activate_see(
34590 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
345a0 50 61 73 73 50 68 72 61 73 65 20 20 20 20 20 20  PassPhrase      
345b0 20 20 2f 2a 20 41 63 74 69 76 61 74 69 6f 6e 20    /* Activation 
345c0 70 68 72 61 73 65 20 2a 2f 0a 29 3b 0a 23 65 6e  phrase */.);.#en
345d0 64 69 66 0a 0a 23 69 66 64 65 66 20 53 51 4c 49  dif..#ifdef SQLI
345e0 54 45 5f 45 4e 41 42 4c 45 5f 43 45 52 4f 44 0a  TE_ENABLE_CEROD.
345f0 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20 74 68  /*.** Specify th
34600 65 20 61 63 74 69 76 61 74 69 6f 6e 20 6b 65 79  e activation key
34610 20 66 6f 72 20 61 20 43 45 52 4f 44 20 64 61 74   for a CEROD dat
34620 61 62 61 73 65 2e 20 20 55 6e 6c 65 73 73 20 0a  abase.  Unless .
34630 2a 2a 20 61 63 74 69 76 61 74 65 64 2c 20 6e 6f  ** activated, no
34640 6e 65 20 6f 66 20 74 68 65 20 43 45 52 4f 44 20  ne of the CEROD 
34650 72 6f 75 74 69 6e 65 73 20 77 69 6c 6c 20 77 6f  routines will wo
34660 72 6b 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69  rk..*/.void sqli
34670 74 65 33 5f 61 63 74 69 76 61 74 65 5f 63 65 72  te3_activate_cer
34680 6f 64 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  od(.  const char
34690 20 2a 7a 50 61 73 73 50 68 72 61 73 65 20 20 20   *zPassPhrase   
346a0 20 20 20 20 20 2f 2a 20 41 63 74 69 76 61 74 69       /* Activati
346b0 6f 6e 20 70 68 72 61 73 65 20 2a 2f 0a 29 3b 0a  on phrase */.);.
346c0 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41  #endif../*.** CA
346d0 50 49 33 52 45 46 3a 20 53 75 73 70 65 6e 64 20  PI3REF: Suspend 
346e0 45 78 65 63 75 74 69 6f 6e 20 46 6f 72 20 41 20  Execution For A 
346f0 53 68 6f 72 74 20 54 69 6d 65 0a 2a 2a 0a 2a 2a  Short Time.**.**
34700 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6c 65   The sqlite3_sle
34710 65 70 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 61  ep() function ca
34720 75 73 65 73 20 74 68 65 20 63 75 72 72 65 6e 74  uses the current
34730 20 74 68 72 65 61 64 20 74 6f 20 73 75 73 70 65   thread to suspe
34740 6e 64 20 65 78 65 63 75 74 69 6f 6e 0a 2a 2a 20  nd execution.** 
34750 66 6f 72 20 61 74 20 6c 65 61 73 74 20 61 20 6e  for at least a n
34760 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65  umber of millise
34770 63 6f 6e 64 73 20 73 70 65 63 69 66 69 65 64 20  conds specified 
34780 69 6e 20 69 74 73 20 70 61 72 61 6d 65 74 65 72  in its parameter
34790 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 6f  ..**.** If the o
347a0 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20  perating system 
347b0 64 6f 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74  does not support
347c0 20 73 6c 65 65 70 20 72 65 71 75 65 73 74 73 20   sleep requests 
347d0 77 69 74 68 0a 2a 2a 20 6d 69 6c 6c 69 73 65 63  with.** millisec
347e0 6f 6e 64 20 74 69 6d 65 20 72 65 73 6f 6c 75 74  ond time resolut
347f0 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 74 69  ion, then the ti
34800 6d 65 20 77 69 6c 6c 20 62 65 20 72 6f 75 6e 64  me will be round
34810 65 64 20 75 70 20 74 6f 0a 2a 2a 20 74 68 65 20  ed up to.** the 
34820 6e 65 61 72 65 73 74 20 73 65 63 6f 6e 64 2e 20  nearest second. 
34830 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69  The number of mi
34840 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c  lliseconds of sl
34850 65 65 70 20 61 63 74 75 61 6c 6c 79 0a 2a 2a 20  eep actually.** 
34860 72 65 71 75 65 73 74 65 64 20 66 72 6f 6d 20 74  requested from t
34870 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  he operating sys
34880 74 65 6d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  tem is returned.
34890 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 69  .**.** ^SQLite i
348a0 6d 70 6c 65 6d 65 6e 74 73 20 74 68 69 73 20 69  mplements this i
348b0 6e 74 65 72 66 61 63 65 20 62 79 20 63 61 6c 6c  nterface by call
348c0 69 6e 67 20 74 68 65 20 78 53 6c 65 65 70 28 29  ing the xSleep()
348d0 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f 66 20 74 68  .** method of th
348e0 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74  e default [sqlit
348f0 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 20  e3_vfs] object. 
34900 20 49 66 20 74 68 65 20 78 53 6c 65 65 70 28 29   If the xSleep()
34910 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68   method.** of th
34920 65 20 64 65 66 61 75 6c 74 20 56 46 53 20 69 73  e default VFS is
34930 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74 65 64   not implemented
34940 20 63 6f 72 72 65 63 74 6c 79 2c 20 6f 72 20 6e   correctly, or n
34950 6f 74 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61  ot implemented a
34960 74 0a 2a 2a 20 61 6c 6c 2c 20 74 68 65 6e 20 74  t.** all, then t
34970 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 73  he behavior of s
34980 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 29 20 6d  qlite3_sleep() m
34990 61 79 20 64 65 76 69 61 74 65 20 66 72 6f 6d 20  ay deviate from 
349a0 74 68 65 20 64 65 73 63 72 69 70 74 69 6f 6e 0a  the description.
349b0 2a 2a 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f  ** in the previo
349c0 75 73 20 70 61 72 61 67 72 61 70 68 73 2e 0a 2a  us paragraphs..*
349d0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 6c  /.int sqlite3_sl
349e0 65 65 70 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  eep(int);../*.**
349f0 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20   CAPI3REF: Name 
34a00 4f 66 20 54 68 65 20 46 6f 6c 64 65 72 20 48 6f  Of The Folder Ho
34a10 6c 64 69 6e 67 20 54 65 6d 70 6f 72 61 72 79 20  lding Temporary 
34a20 46 69 6c 65 73 0a 2a 2a 0a 2a 2a 20 5e 28 49 66  Files.**.** ^(If
34a30 20 74 68 69 73 20 67 6c 6f 62 61 6c 20 76 61 72   this global var
34a40 69 61 62 6c 65 20 69 73 20 6d 61 64 65 20 74 6f  iable is made to
34a50 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 69   point to a stri
34a60 6e 67 20 77 68 69 63 68 20 69 73 0a 2a 2a 20 74  ng which is.** t
34a70 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 66 6f 6c  he name of a fol
34a80 64 65 72 20 28 61 2e 6b 2e 61 2e 20 64 69 72 65  der (a.k.a. dire
34a90 63 74 6f 72 79 29 2c 20 74 68 65 6e 20 61 6c 6c  ctory), then all
34aa0 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 73   temporary files
34ab0 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20 53  .** created by S
34ac0 51 4c 69 74 65 20 77 68 65 6e 20 75 73 69 6e 67  QLite when using
34ad0 20 61 20 62 75 69 6c 74 2d 69 6e 20 5b 73 71 6c   a built-in [sql
34ae0 69 74 65 33 5f 76 66 73 20 7c 20 56 46 53 5d 0a  ite3_vfs | VFS].
34af0 2a 2a 20 77 69 6c 6c 20 62 65 20 70 6c 61 63 65  ** will be place
34b00 64 20 69 6e 20 74 68 61 74 20 64 69 72 65 63 74  d in that direct
34b10 6f 72 79 2e 29 5e 20 20 5e 49 66 20 74 68 69 73  ory.)^  ^If this
34b20 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 69 73 20   variable.** is 
34b30 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  a NULL pointer, 
34b40 74 68 65 6e 20 53 51 4c 69 74 65 20 70 65 72 66  then SQLite perf
34b50 6f 72 6d 73 20 61 20 73 65 61 72 63 68 20 66 6f  orms a search fo
34b60 72 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65  r an appropriate
34b70 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 69  .** temporary fi
34b80 6c 65 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a  le directory..**
34b90 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61  .** It is not sa
34ba0 66 65 20 74 6f 20 72 65 61 64 20 6f 72 20 6d 6f  fe to read or mo
34bb0 64 69 66 79 20 74 68 69 73 20 76 61 72 69 61 62  dify this variab
34bc0 6c 65 20 69 6e 20 6d 6f 72 65 20 74 68 61 6e 20  le in more than 
34bd0 6f 6e 65 0a 2a 2a 20 74 68 72 65 61 64 20 61 74  one.** thread at
34be0 20 61 20 74 69 6d 65 2e 20 20 49 74 20 69 73 20   a time.  It is 
34bf0 6e 6f 74 20 73 61 66 65 20 74 6f 20 72 65 61 64  not safe to read
34c00 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20   or modify this 
34c10 76 61 72 69 61 62 6c 65 0a 2a 2a 20 69 66 20 61  variable.** if a
34c20 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
34c30 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20  ction] is being 
34c40 75 73 65 64 20 61 74 20 74 68 65 20 73 61 6d 65  used at the same
34c50 20 74 69 6d 65 20 69 6e 20 61 20 73 65 70 61 72   time in a separ
34c60 61 74 65 0a 2a 2a 20 74 68 72 65 61 64 2e 0a 2a  ate.** thread..*
34c70 2a 20 49 74 20 69 73 20 69 6e 74 65 6e 64 65 64  * It is intended
34c80 20 74 68 61 74 20 74 68 69 73 20 76 61 72 69 61   that this varia
34c90 62 6c 65 20 62 65 20 73 65 74 20 6f 6e 63 65 0a  ble be set once.
34ca0 2a 2a 20 61 73 20 70 61 72 74 20 6f 66 20 70 72  ** as part of pr
34cb0 6f 63 65 73 73 20 69 6e 69 74 69 61 6c 69 7a 61  ocess initializa
34cc0 74 69 6f 6e 20 61 6e 64 20 62 65 66 6f 72 65 20  tion and before 
34cd0 61 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 65 72  any SQLite inter
34ce0 66 61 63 65 0a 2a 2a 20 72 6f 75 74 69 6e 65 73  face.** routines
34cf0 20 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c 65   have been calle
34d00 64 20 61 6e 64 20 74 68 61 74 20 74 68 69 73 20  d and that this 
34d10 76 61 72 69 61 62 6c 65 20 72 65 6d 61 69 6e 20  variable remain 
34d20 75 6e 63 68 61 6e 67 65 64 0a 2a 2a 20 74 68 65  unchanged.** the
34d30 72 65 61 66 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  reafter..**.** ^
34d40 54 68 65 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f  The [temp_store_
34d50 64 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61  directory pragma
34d60 5d 20 6d 61 79 20 6d 6f 64 69 66 79 20 74 68 69  ] may modify thi
34d70 73 20 76 61 72 69 61 62 6c 65 20 61 6e 64 20 63  s variable and c
34d80 61 75 73 65 0a 2a 2a 20 69 74 20 74 6f 20 70 6f  ause.** it to po
34d90 69 6e 74 20 74 6f 20 6d 65 6d 6f 72 79 20 6f 62  int to memory ob
34da0 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  tained from [sql
34db0 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 2e 20 20 5e  ite3_malloc].  ^
34dc0 46 75 72 74 68 65 72 6d 6f 72 65 2c 0a 2a 2a 20  Furthermore,.** 
34dd0 74 68 65 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f  the [temp_store_
34de0 64 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61  directory pragma
34df0 5d 20 61 6c 77 61 79 73 20 61 73 73 75 6d 65 73  ] always assumes
34e00 20 74 68 61 74 20 61 6e 79 20 73 74 72 69 6e 67   that any string
34e10 0a 2a 2a 20 74 68 61 74 20 74 68 69 73 20 76 61  .** that this va
34e20 72 69 61 62 6c 65 20 70 6f 69 6e 74 73 20 74 6f  riable points to
34e30 20 69 73 20 68 65 6c 64 20 69 6e 20 6d 65 6d 6f   is held in memo
34e40 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ry obtained from
34e50 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61   .** [sqlite3_ma
34e60 6c 6c 6f 63 5d 20 61 6e 64 20 74 68 65 20 70 72  lloc] and the pr
34e70 61 67 6d 61 20 6d 61 79 20 61 74 74 65 6d 70 74  agma may attempt
34e80 20 74 6f 20 66 72 65 65 20 74 68 61 74 20 6d 65   to free that me
34e90 6d 6f 72 79 0a 2a 2a 20 75 73 69 6e 67 20 5b 73  mory.** using [s
34ea0 71 6c 69 74 65 33 5f 66 72 65 65 5d 2e 0a 2a 2a  qlite3_free]..**
34eb0 20 48 65 6e 63 65 2c 20 69 66 20 74 68 69 73 20   Hence, if this 
34ec0 76 61 72 69 61 62 6c 65 20 69 73 20 6d 6f 64 69  variable is modi
34ed0 66 69 65 64 20 64 69 72 65 63 74 6c 79 2c 20 65  fied directly, e
34ee0 69 74 68 65 72 20 69 74 20 73 68 6f 75 6c 64 20  ither it should 
34ef0 62 65 0a 2a 2a 20 6d 61 64 65 20 4e 55 4c 4c 20  be.** made NULL 
34f00 6f 72 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74  or made to point
34f10 20 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69   to memory obtai
34f20 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ned from [sqlite
34f30 33 5f 6d 61 6c 6c 6f 63 5d 0a 2a 2a 20 6f 72 20  3_malloc].** or 
34f40 65 6c 73 65 20 74 68 65 20 75 73 65 20 6f 66 20  else the use of 
34f50 74 68 65 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f  the [temp_store_
34f60 64 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61  directory pragma
34f70 5d 20 73 68 6f 75 6c 64 20 62 65 20 61 76 6f 69  ] should be avoi
34f80 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f  ded..**.** <b>No
34f90 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 52 75  te to Windows Ru
34fa0 6e 74 69 6d 65 20 75 73 65 72 73 3a 3c 2f 62 3e  ntime users:</b>
34fb0 20 20 54 68 65 20 74 65 6d 70 6f 72 61 72 79 20    The temporary 
34fc0 64 69 72 65 63 74 6f 72 79 20 6d 75 73 74 20 62  directory must b
34fd0 65 20 73 65 74 0a 2a 2a 20 70 72 69 6f 72 20 74  e set.** prior t
34fe0 6f 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  o calling [sqlit
34ff0 65 33 5f 6f 70 65 6e 5d 20 6f 72 20 5b 73 71 6c  e3_open] or [sql
35000 69 74 65 33 5f 6f 70 65 6e 5f 76 32 5d 2e 20 20  ite3_open_v2].  
35010 4f 74 68 65 72 77 69 73 65 2c 20 76 61 72 69 6f  Otherwise, vario
35020 75 73 0a 2a 2a 20 66 65 61 74 75 72 65 73 20 74  us.** features t
35030 68 61 74 20 72 65 71 75 69 72 65 20 74 68 65 20  hat require the 
35040 75 73 65 20 6f 66 20 74 65 6d 70 6f 72 61 72 79  use of temporary
35050 20 66 69 6c 65 73 20 6d 61 79 20 66 61 69 6c 2e   files may fail.
35060 20 20 48 65 72 65 20 69 73 20 61 6e 0a 2a 2a 20    Here is an.** 
35070 65 78 61 6d 70 6c 65 20 6f 66 20 68 6f 77 20 74  example of how t
35080 6f 20 64 6f 20 74 68 69 73 20 75 73 69 6e 67 20  o do this using 
35090 43 2b 2b 20 77 69 74 68 20 74 68 65 20 57 69 6e  C++ with the Win
350a0 64 6f 77 73 20 52 75 6e 74 69 6d 65 3a 0a 2a 2a  dows Runtime:.**
350b0 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
350c0 3c 70 72 65 3e 0a 2a 2a 20 4c 50 43 57 53 54 52  <pre>.** LPCWSTR
350d0 20 7a 50 61 74 68 20 3d 20 57 69 6e 64 6f 77 73   zPath = Windows
350e0 3a 3a 53 74 6f 72 61 67 65 3a 3a 41 70 70 6c 69  ::Storage::Appli
350f0 63 61 74 69 6f 6e 44 61 74 61 3a 3a 43 75 72 72  cationData::Curr
35100 65 6e 74 2d 3e 0a 2a 2a 20 26 6e 62 73 70 3b 20  ent->.** &nbsp; 
35110 20 20 20 20 54 65 6d 70 6f 72 61 72 79 46 6f 6c      TemporaryFol
35120 64 65 72 2d 3e 50 61 74 68 2d 3e 44 61 74 61 28  der->Path->Data(
35130 29 3b 0a 2a 2a 20 63 68 61 72 20 7a 50 61 74 68  );.** char zPath
35140 42 75 66 26 23 39 31 3b 4d 41 58 5f 50 41 54 48  Buf&#91;MAX_PATH
35150 20 2b 20 31 26 23 39 33 3b 3b 0a 2a 2a 20 6d 65   + 1&#93;;.** me
35160 6d 73 65 74 28 7a 50 61 74 68 42 75 66 2c 20 30  mset(zPathBuf, 0
35170 2c 20 73 69 7a 65 6f 66 28 7a 50 61 74 68 42 75  , sizeof(zPathBu
35180 66 29 29 3b 0a 2a 2a 20 57 69 64 65 43 68 61 72  f));.** WideChar
35190 54 6f 4d 75 6c 74 69 42 79 74 65 28 43 50 5f 55  ToMultiByte(CP_U
351a0 54 46 38 2c 20 30 2c 20 7a 50 61 74 68 2c 20 2d  TF8, 0, zPath, -
351b0 31 2c 20 7a 50 61 74 68 42 75 66 2c 20 73 69 7a  1, zPathBuf, siz
351c0 65 6f 66 28 7a 50 61 74 68 42 75 66 29 2c 0a 2a  eof(zPathBuf),.*
351d0 2a 20 26 6e 62 73 70 3b 20 20 20 20 20 4e 55 4c  * &nbsp;     NUL
351e0 4c 2c 20 4e 55 4c 4c 29 3b 0a 2a 2a 20 73 71 6c  L, NULL);.** sql
351f0 69 74 65 33 5f 74 65 6d 70 5f 64 69 72 65 63 74  ite3_temp_direct
35200 6f 72 79 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70  ory = sqlite3_mp
35210 72 69 6e 74 66 28 22 25 73 22 2c 20 7a 50 61 74  rintf("%s", zPat
35220 68 42 75 66 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e  hBuf);.** </pre>
35230 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2f  </blockquote>.*/
35240 0a 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 20 63  .SQLITE_EXTERN c
35250 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 74 65 6d  har *sqlite3_tem
35260 70 5f 64 69 72 65 63 74 6f 72 79 3b 0a 0a 2f 2a  p_directory;../*
35270 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 61  .** CAPI3REF: Na
35280 6d 65 20 4f 66 20 54 68 65 20 46 6f 6c 64 65 72  me Of The Folder
35290 20 48 6f 6c 64 69 6e 67 20 44 61 74 61 62 61 73   Holding Databas
352a0 65 20 46 69 6c 65 73 0a 2a 2a 0a 2a 2a 20 5e 28  e Files.**.** ^(
352b0 49 66 20 74 68 69 73 20 67 6c 6f 62 61 6c 20 76  If this global v
352c0 61 72 69 61 62 6c 65 20 69 73 20 6d 61 64 65 20  ariable is made 
352d0 74 6f 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74  to point to a st
352e0 72 69 6e 67 20 77 68 69 63 68 20 69 73 0a 2a 2a  ring which is.**
352f0 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 66   the name of a f
35300 6f 6c 64 65 72 20 28 61 2e 6b 2e 61 2e 20 64 69  older (a.k.a. di
35310 72 65 63 74 6f 72 79 29 2c 20 74 68 65 6e 20 61  rectory), then a
35320 6c 6c 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  ll database file
35330 73 0a 2a 2a 20 73 70 65 63 69 66 69 65 64 20 77  s.** specified w
35340 69 74 68 20 61 20 72 65 6c 61 74 69 76 65 20 70  ith a relative p
35350 61 74 68 6e 61 6d 65 20 61 6e 64 20 63 72 65 61  athname and crea
35360 74 65 64 20 6f 72 20 61 63 63 65 73 73 65 64 20  ted or accessed 
35370 62 79 0a 2a 2a 20 53 51 4c 69 74 65 20 77 68 65  by.** SQLite whe
35380 6e 20 75 73 69 6e 67 20 61 20 62 75 69 6c 74 2d  n using a built-
35390 69 6e 20 77 69 6e 64 6f 77 73 20 5b 73 71 6c 69  in windows [sqli
353a0 74 65 33 5f 76 66 73 20 7c 20 56 46 53 5d 20 77  te3_vfs | VFS] w
353b0 69 6c 6c 20 62 65 20 61 73 73 75 6d 65 64 0a 2a  ill be assumed.*
353c0 2a 20 74 6f 20 62 65 20 72 65 6c 61 74 69 76 65  * to be relative
353d0 20 74 6f 20 74 68 61 74 20 64 69 72 65 63 74 6f   to that directo
353e0 72 79 2e 29 5e 20 5e 49 66 20 74 68 69 73 20 76  ry.)^ ^If this v
353f0 61 72 69 61 62 6c 65 20 69 73 20 61 20 4e 55 4c  ariable is a NUL
35400 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 2c 20 74 68  L.** pointer, th
35410 65 6e 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65  en SQLite assume
35420 73 20 74 68 61 74 20 61 6c 6c 20 64 61 74 61 62  s that all datab
35430 61 73 65 20 66 69 6c 65 73 20 73 70 65 63 69 66  ase files specif
35440 69 65 64 0a 2a 2a 20 77 69 74 68 20 61 20 72 65  ied.** with a re
35450 6c 61 74 69 76 65 20 70 61 74 68 6e 61 6d 65 20  lative pathname 
35460 61 72 65 20 72 65 6c 61 74 69 76 65 20 74 6f 20  are relative to 
35470 74 68 65 20 63 75 72 72 65 6e 74 20 64 69 72 65  the current dire
35480 63 74 6f 72 79 0a 2a 2a 20 66 6f 72 20 74 68 65  ctory.** for the
35490 20 70 72 6f 63 65 73 73 2e 20 20 4f 6e 6c 79 20   process.  Only 
354a0 74 68 65 20 77 69 6e 64 6f 77 73 20 56 46 53 20  the windows VFS 
354b0 6d 61 6b 65 73 20 75 73 65 20 6f 66 20 74 68 69  makes use of thi
354c0 73 20 67 6c 6f 62 61 6c 0a 2a 2a 20 76 61 72 69  s global.** vari
354d0 61 62 6c 65 3b 20 69 74 20 69 73 20 69 67 6e 6f  able; it is igno
354e0 72 65 64 20 62 79 20 74 68 65 20 75 6e 69 78 20  red by the unix 
354f0 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 43 68 61 6e 67  VFS..**.** Chang
35500 69 6e 67 20 74 68 65 20 76 61 6c 75 65 20 6f 66  ing the value of
35510 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 77   this variable w
35520 68 69 6c 65 20 61 20 64 61 74 61 62 61 73 65 20  hile a database 
35530 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 0a 2a 2a  connection is.**
35540 20 6f 70 65 6e 20 63 61 6e 20 72 65 73 75 6c 74   open can result
35550 20 69 6e 20 61 20 63 6f 72 72 75 70 74 20 64 61   in a corrupt da
35560 74 61 62 61 73 65 2e 0a 2a 2a 0a 2a 2a 20 49 74  tabase..**.** It
35570 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20   is not safe to 
35580 72 65 61 64 20 6f 72 20 6d 6f 64 69 66 79 20 74  read or modify t
35590 68 69 73 20 76 61 72 69 61 62 6c 65 20 69 6e 20  his variable in 
355a0 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 0a 2a 2a  more than one.**
355b0 20 74 68 72 65 61 64 20 61 74 20 61 20 74 69 6d   thread at a tim
355c0 65 2e 20 20 49 74 20 69 73 20 6e 6f 74 20 73 61  e.  It is not sa
355d0 66 65 20 74 6f 20 72 65 61 64 20 6f 72 20 6d 6f  fe to read or mo
355e0 64 69 66 79 20 74 68 69 73 20 76 61 72 69 61 62  dify this variab
355f0 6c 65 0a 2a 2a 20 69 66 20 61 20 5b 64 61 74 61  le.** if a [data
35600 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
35610 20 69 73 20 62 65 69 6e 67 20 75 73 65 64 20 61   is being used a
35620 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20  t the same time 
35630 69 6e 20 61 20 73 65 70 61 72 61 74 65 0a 2a 2a  in a separate.**
35640 20 74 68 72 65 61 64 2e 0a 2a 2a 20 49 74 20 69   thread..** It i
35650 73 20 69 6e 74 65 6e 64 65 64 20 74 68 61 74 20  s intended that 
35660 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 62 65  this variable be
35670 20 73 65 74 20 6f 6e 63 65 0a 2a 2a 20 61 73 20   set once.** as 
35680 70 61 72 74 20 6f 66 20 70 72 6f 63 65 73 73 20  part of process 
35690 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61  initialization a
356a0 6e 64 20 62 65 66 6f 72 65 20 61 6e 79 20 53 51  nd before any SQ
356b0 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 0a 2a  Lite interface.*
356c0 2a 20 72 6f 75 74 69 6e 65 73 20 68 61 76 65 20  * routines have 
356d0 62 65 65 6e 20 63 61 6c 6c 65 64 20 61 6e 64 20  been called and 
356e0 74 68 61 74 20 74 68 69 73 20 76 61 72 69 61 62  that this variab
356f0 6c 65 20 72 65 6d 61 69 6e 20 75 6e 63 68 61 6e  le remain unchan
35700 67 65 64 0a 2a 2a 20 74 68 65 72 65 61 66 74 65  ged.** thereafte
35710 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 64  r..**.** ^The [d
35720 61 74 61 5f 73 74 6f 72 65 5f 64 69 72 65 63 74  ata_store_direct
35730 6f 72 79 20 70 72 61 67 6d 61 5d 20 6d 61 79 20  ory pragma] may 
35740 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61 72 69  modify this vari
35750 61 62 6c 65 20 61 6e 64 20 63 61 75 73 65 0a 2a  able and cause.*
35760 2a 20 69 74 20 74 6f 20 70 6f 69 6e 74 20 74 6f  * it to point to
35770 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64   memory obtained
35780 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
35790 61 6c 6c 6f 63 5d 2e 20 20 5e 46 75 72 74 68 65  alloc].  ^Furthe
357a0 72 6d 6f 72 65 2c 0a 2a 2a 20 74 68 65 20 5b 64  rmore,.** the [d
357b0 61 74 61 5f 73 74 6f 72 65 5f 64 69 72 65 63 74  ata_store_direct
357c0 6f 72 79 20 70 72 61 67 6d 61 5d 20 61 6c 77 61  ory pragma] alwa
357d0 79 73 20 61 73 73 75 6d 65 73 20 74 68 61 74 20  ys assumes that 
357e0 61 6e 79 20 73 74 72 69 6e 67 0a 2a 2a 20 74 68  any string.** th
357f0 61 74 20 74 68 69 73 20 76 61 72 69 61 62 6c 65  at this variable
35800 20 70 6f 69 6e 74 73 20 74 6f 20 69 73 20 68 65   points to is he
35810 6c 64 20 69 6e 20 6d 65 6d 6f 72 79 20 6f 62 74  ld in memory obt
35820 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b  ained from .** [
35830 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 20  sqlite3_malloc] 
35840 61 6e 64 20 74 68 65 20 70 72 61 67 6d 61 20 6d  and the pragma m
35850 61 79 20 61 74 74 65 6d 70 74 20 74 6f 20 66 72  ay attempt to fr
35860 65 65 20 74 68 61 74 20 6d 65 6d 6f 72 79 0a 2a  ee that memory.*
35870 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  * using [sqlite3
35880 5f 66 72 65 65 5d 2e 0a 2a 2a 20 48 65 6e 63 65  _free]..** Hence
35890 2c 20 69 66 20 74 68 69 73 20 76 61 72 69 61 62  , if this variab
358a0 6c 65 20 69 73 20 6d 6f 64 69 66 69 65 64 20 64  le is modified d
358b0 69 72 65 63 74 6c 79 2c 20 65 69 74 68 65 72 20  irectly, either 
358c0 69 74 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20  it should be.** 
358d0 6d 61 64 65 20 4e 55 4c 4c 20 6f 72 20 6d 61 64  made NULL or mad
358e0 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 6d 65  e to point to me
358f0 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72  mory obtained fr
35900 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
35910 6f 63 5d 0a 2a 2a 20 6f 72 20 65 6c 73 65 20 74  oc].** or else t
35920 68 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b 64  he use of the [d
35930 61 74 61 5f 73 74 6f 72 65 5f 64 69 72 65 63 74  ata_store_direct
35940 6f 72 79 20 70 72 61 67 6d 61 5d 20 73 68 6f 75  ory pragma] shou
35950 6c 64 20 62 65 20 61 76 6f 69 64 65 64 2e 0a 2a  ld be avoided..*
35960 2f 0a 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 20  /.SQLITE_EXTERN 
35970 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 64 61  char *sqlite3_da
35980 74 61 5f 64 69 72 65 63 74 6f 72 79 3b 0a 0a 2f  ta_directory;../
35990 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
359a0 65 73 74 20 46 6f 72 20 41 75 74 6f 2d 43 6f 6d  est For Auto-Com
359b0 6d 69 74 20 4d 6f 64 65 0a 2a 2a 20 4b 45 59 57  mit Mode.** KEYW
359c0 4f 52 44 53 3a 20 7b 61 75 74 6f 63 6f 6d 6d 69  ORDS: {autocommi
359d0 74 20 6d 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 5e 54  t mode}.**.** ^T
359e0 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  he sqlite3_get_a
359f0 75 74 6f 63 6f 6d 6d 69 74 28 29 20 69 6e 74 65  utocommit() inte
35a00 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 6e 6f  rface returns no
35a10 6e 2d 7a 65 72 6f 20 6f 72 0a 2a 2a 20 7a 65 72  n-zero or.** zer
35a20 6f 20 69 66 20 74 68 65 20 67 69 76 65 6e 20 64  o if the given d
35a30 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
35a40 6f 6e 20 69 73 20 6f 72 20 69 73 20 6e 6f 74 20  on is or is not 
35a50 69 6e 20 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f  in autocommit mo
35a60 64 65 2c 0a 2a 2a 20 72 65 73 70 65 63 74 69 76  de,.** respectiv
35a70 65 6c 79 2e 20 20 5e 41 75 74 6f 63 6f 6d 6d 69  ely.  ^Autocommi
35a80 74 20 6d 6f 64 65 20 69 73 20 6f 6e 20 62 79 20  t mode is on by 
35a90 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 5e 41 75 74  default..** ^Aut
35aa0 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20  ocommit mode is 
35ab0 64 69 73 61 62 6c 65 64 20 62 79 20 61 20 5b 42  disabled by a [B
35ac0 45 47 49 4e 5d 20 73 74 61 74 65 6d 65 6e 74 2e  EGIN] statement.
35ad0 0a 2a 2a 20 5e 41 75 74 6f 63 6f 6d 6d 69 74 20  .** ^Autocommit 
35ae0 6d 6f 64 65 20 69 73 20 72 65 2d 65 6e 61 62 6c  mode is re-enabl
35af0 65 64 20 62 79 20 61 20 5b 43 4f 4d 4d 49 54 5d  ed by a [COMMIT]
35b00 20 6f 72 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2e 0a   or [ROLLBACK]..
35b10 2a 2a 0a 2a 2a 20 49 66 20 63 65 72 74 61 69 6e  **.** If certain
35b20 20 6b 69 6e 64 73 20 6f 66 20 65 72 72 6f 72 73   kinds of errors
35b30 20 6f 63 63 75 72 20 6f 6e 20 61 20 73 74 61 74   occur on a stat
35b40 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 61 20 6d  ement within a m
35b50 75 6c 74 69 2d 73 74 61 74 65 6d 65 6e 74 0a 2a  ulti-statement.*
35b60 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 28 65  * transaction (e
35b70 72 72 6f 72 73 20 69 6e 63 6c 75 64 69 6e 67 20  rrors including 
35b80 5b 53 51 4c 49 54 45 5f 46 55 4c 4c 5d 2c 20 5b  [SQLITE_FULL], [
35b90 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 2c 0a 2a  SQLITE_IOERR],.*
35ba0 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d  * [SQLITE_NOMEM]
35bb0 2c 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c  , [SQLITE_BUSY],
35bc0 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 49 4e 54   and [SQLITE_INT
35bd0 45 52 52 55 50 54 5d 29 20 74 68 65 6e 20 74 68  ERRUPT]) then th
35be0 65 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e  e.** transaction
35bf0 20 6d 69 67 68 74 20 62 65 20 72 6f 6c 6c 65 64   might be rolled
35c00 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63 61   back automatica
35c10 6c 6c 79 2e 20 20 54 68 65 20 6f 6e 6c 79 20 77  lly.  The only w
35c20 61 79 20 74 6f 0a 2a 2a 20 66 69 6e 64 20 6f 75  ay to.** find ou
35c30 74 20 77 68 65 74 68 65 72 20 53 51 4c 69 74 65  t whether SQLite
35c40 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72   automatically r
35c50 6f 6c 6c 65 64 20 62 61 63 6b 20 74 68 65 20 74  olled back the t
35c60 72 61 6e 73 61 63 74 69 6f 6e 20 61 66 74 65 72  ransaction after
35c70 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20 69 73 20  .** an error is 
35c80 74 6f 20 75 73 65 20 74 68 69 73 20 66 75 6e 63  to use this func
35c90 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61  tion..**.** If a
35ca0 6e 6f 74 68 65 72 20 74 68 72 65 61 64 20 63 68  nother thread ch
35cb0 61 6e 67 65 73 20 74 68 65 20 61 75 74 6f 63 6f  anges the autoco
35cc0 6d 6d 69 74 20 73 74 61 74 75 73 20 6f 66 20 74  mmit status of t
35cd0 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63  he database.** c
35ce0 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 20  onnection while 
35cf0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20  this routine is 
35d00 72 75 6e 6e 69 6e 67 2c 20 74 68 65 6e 20 74 68  running, then th
35d10 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a  e return value.*
35d20 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  * is undefined..
35d30 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 67  */.int sqlite3_g
35d40 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 73 71  et_autocommit(sq
35d50 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  lite3*);../*.** 
35d60 43 41 50 49 33 52 45 46 3a 20 46 69 6e 64 20 54  CAPI3REF: Find T
35d70 68 65 20 44 61 74 61 62 61 73 65 20 48 61 6e 64  he Database Hand
35d80 6c 65 20 4f 66 20 41 20 50 72 65 70 61 72 65 64  le Of A Prepared
35d90 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a   Statement.**.**
35da0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62   ^The sqlite3_db
35db0 5f 68 61 6e 64 6c 65 20 69 6e 74 65 72 66 61 63  _handle interfac
35dc0 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 5b 64  e returns the [d
35dd0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
35de0 6f 6e 5d 20 68 61 6e 64 6c 65 0a 2a 2a 20 74 6f  on] handle.** to
35df0 20 77 68 69 63 68 20 61 20 5b 70 72 65 70 61 72   which a [prepar
35e00 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 62 65  ed statement] be
35e10 6c 6f 6e 67 73 2e 20 20 5e 54 68 65 20 5b 64 61  longs.  ^The [da
35e20 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
35e30 6e 5d 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62  n].** returned b
35e40 79 20 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e  y sqlite3_db_han
35e50 64 6c 65 20 69 73 20 74 68 65 20 73 61 6d 65 20  dle is the same 
35e60 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
35e70 74 69 6f 6e 5d 0a 2a 2a 20 74 68 61 74 20 77 61  tion].** that wa
35e80 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  s the first argu
35e90 6d 65 6e 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b  ment.** to the [
35ea0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
35eb0 76 32 28 29 5d 20 63 61 6c 6c 20 28 6f 72 20 69  v2()] call (or i
35ec0 74 73 20 76 61 72 69 61 6e 74 73 29 20 74 68 61  ts variants) tha
35ed0 74 20 77 61 73 20 75 73 65 64 20 74 6f 0a 2a 2a  t was used to.**
35ee0 20 63 72 65 61 74 65 20 74 68 65 20 73 74 61 74   create the stat
35ef0 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 66 69 72  ement in the fir
35f00 73 74 20 70 6c 61 63 65 2e 0a 2a 2f 0a 73 71 6c  st place..*/.sql
35f10 69 74 65 33 20 2a 73 71 6c 69 74 65 33 5f 64 62  ite3 *sqlite3_db
35f20 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f  _handle(sqlite3_
35f30 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  stmt*);../*.** C
35f40 41 50 49 33 52 45 46 3a 20 52 65 74 75 72 6e 20  API3REF: Return 
35f50 54 68 65 20 46 69 6c 65 6e 61 6d 65 20 46 6f 72  The Filename For
35f60 20 41 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e   A Database Conn
35f70 65 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ection.**.** ^Th
35f80 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 66 69 6c  e sqlite3_db_fil
35f90 65 6e 61 6d 65 28 44 2c 4e 29 20 69 6e 74 65 72  ename(D,N) inter
35fa0 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70  face returns a p
35fb0 6f 69 6e 74 65 72 20 74 6f 20 61 20 66 69 6c 65  ointer to a file
35fc0 6e 61 6d 65 0a 2a 2a 20 61 73 73 6f 63 69 61 74  name.** associat
35fd0 65 64 20 77 69 74 68 20 64 61 74 61 62 61 73 65  ed with database
35fe0 20 4e 20 6f 66 20 63 6f 6e 6e 65 63 74 69 6f 6e   N of connection
35ff0 20 44 2e 20 20 5e 54 68 65 20 6d 61 69 6e 20 64   D.  ^The main d
36000 61 74 61 62 61 73 65 20 66 69 6c 65 0a 2a 2a 20  atabase file.** 
36010 68 61 73 20 74 68 65 20 6e 61 6d 65 20 22 6d 61  has the name "ma
36020 69 6e 22 2e 20 20 49 66 20 74 68 65 72 65 20 69  in".  If there i
36030 73 20 6e 6f 20 61 74 74 61 63 68 65 64 20 64 61  s no attached da
36040 74 61 62 61 73 65 20 4e 20 6f 6e 20 74 68 65 20  tabase N on the 
36050 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
36060 65 63 74 69 6f 6e 20 44 2c 20 6f 72 20 69 66 20  ection D, or if 
36070 64 61 74 61 62 61 73 65 20 4e 20 69 73 20 61 20  database N is a 
36080 74 65 6d 70 6f 72 61 72 79 20 6f 72 20 69 6e 2d  temporary or in-
36090 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 2c  memory database,
360a0 20 74 68 65 6e 0a 2a 2a 20 61 20 4e 55 4c 4c 20   then.** a NULL 
360b0 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 72  pointer is retur
360c0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ned..**.** ^The 
360d0 66 69 6c 65 6e 61 6d 65 20 72 65 74 75 72 6e 65  filename returne
360e0 64 20 62 79 20 74 68 69 73 20 66 75 6e 63 74 69  d by this functi
360f0 6f 6e 20 69 73 20 74 68 65 20 6f 75 74 70 75 74  on is the output
36100 20 6f 66 20 74 68 65 0a 2a 2a 20 78 46 75 6c 6c   of the.** xFull
36110 50 61 74 68 6e 61 6d 65 20 6d 65 74 68 6f 64 20  Pathname method 
36120 6f 66 20 74 68 65 20 5b 56 46 53 5d 2e 20 20 5e  of the [VFS].  ^
36130 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  In other words, 
36140 74 68 65 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20  the filename.** 
36150 77 69 6c 6c 20 62 65 20 61 6e 20 61 62 73 6f 6c  will be an absol
36160 75 74 65 20 70 61 74 68 6e 61 6d 65 2c 20 65 76  ute pathname, ev
36170 65 6e 20 69 66 20 74 68 65 20 66 69 6c 65 6e 61  en if the filena
36180 6d 65 20 75 73 65 64 0a 2a 2a 20 74 6f 20 6f 70  me used.** to op
36190 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
361a0 6f 72 69 67 69 6e 61 6c 6c 79 20 77 61 73 20 61  originally was a
361b0 20 55 52 49 20 6f 72 20 72 65 6c 61 74 69 76 65   URI or relative
361c0 20 70 61 74 68 6e 61 6d 65 2e 0a 2a 2f 0a 63 6f   pathname..*/.co
361d0 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
361e0 33 5f 64 62 5f 66 69 6c 65 6e 61 6d 65 28 73 71  3_db_filename(sq
361f0 6c 69 74 65 33 20 2a 64 62 2c 20 63 6f 6e 73 74  lite3 *db, const
36200 20 63 68 61 72 20 2a 7a 44 62 4e 61 6d 65 29 3b   char *zDbName);
36210 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
36220 3a 20 44 65 74 65 72 6d 69 6e 65 20 69 66 20 61  : Determine if a
36230 20 64 61 74 61 62 61 73 65 20 69 73 20 72 65 61   database is rea
36240 64 2d 6f 6e 6c 79 0a 2a 2a 0a 2a 2a 20 5e 54 68  d-only.**.** ^Th
36250 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 72 65 61  e sqlite3_db_rea
36260 64 6f 6e 6c 79 28 44 2c 4e 29 20 69 6e 74 65 72  donly(D,N) inter
36270 66 61 63 65 20 72 65 74 75 72 6e 73 20 31 20 69  face returns 1 i
36280 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 4e  f the database N
36290 0a 2a 2a 20 6f 66 20 63 6f 6e 6e 65 63 74 69 6f  .** of connectio
362a0 6e 20 44 20 69 73 20 72 65 61 64 2d 6f 6e 6c 79  n D is read-only
362b0 2c 20 30 20 69 66 20 69 74 20 69 73 20 72 65 61  , 0 if it is rea
362c0 64 2f 77 72 69 74 65 2c 20 6f 72 20 2d 31 20 69  d/write, or -1 i
362d0 66 20 4e 20 69 73 20 6e 6f 74 0a 2a 2a 20 74 68  f N is not.** th
362e0 65 20 6e 61 6d 65 20 6f 66 20 61 20 64 61 74 61  e name of a data
362f0 62 61 73 65 20 6f 6e 20 63 6f 6e 6e 65 63 74 69  base on connecti
36300 6f 6e 20 44 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  on D..*/.int sql
36310 69 74 65 33 5f 64 62 5f 72 65 61 64 6f 6e 6c 79  ite3_db_readonly
36320 28 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 63 6f  (sqlite3 *db, co
36330 6e 73 74 20 63 68 61 72 20 2a 7a 44 62 4e 61 6d  nst char *zDbNam
36340 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  e);../*.** CAPI3
36350 52 45 46 3a 20 46 69 6e 64 20 74 68 65 20 6e 65  REF: Find the ne
36360 78 74 20 70 72 65 70 61 72 65 64 20 73 74 61 74  xt prepared stat
36370 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  ement.**.** ^Thi
36380 73 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  s interface retu
36390 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
363a0 20 74 68 65 20 6e 65 78 74 20 5b 70 72 65 70 61   the next [prepa
363b0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61  red statement] a
363c0 66 74 65 72 0a 2a 2a 20 70 53 74 6d 74 20 61 73  fter.** pStmt as
363d0 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68  sociated with th
363e0 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
363f0 65 63 74 69 6f 6e 5d 20 70 44 62 2e 20 20 5e 49  ection] pDb.  ^I
36400 66 20 70 53 74 6d 74 20 69 73 20 4e 55 4c 4c 0a  f pStmt is NULL.
36410 2a 2a 20 74 68 65 6e 20 74 68 69 73 20 69 6e 74  ** then this int
36420 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
36430 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
36440 66 69 72 73 74 20 70 72 65 70 61 72 65 64 20 73  first prepared s
36450 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 61 73 73 6f  tatement.** asso
36460 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20  ciated with the 
36470 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
36480 69 6f 6e 20 70 44 62 2e 20 20 5e 49 66 20 6e 6f  ion pDb.  ^If no
36490 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
364a0 65 6e 74 0a 2a 2a 20 73 61 74 69 73 66 69 65 73  ent.** satisfies
364b0 20 74 68 65 20 63 6f 6e 64 69 74 69 6f 6e 73 20   the conditions 
364c0 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c  of this routine,
364d0 20 69 74 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c   it returns NULL
364e0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 64 61 74  ..**.** The [dat
364f0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
36500 5d 20 70 6f 69 6e 74 65 72 20 44 20 69 6e 20 61  ] pointer D in a
36510 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c   call to.** [sql
36520 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 44  ite3_next_stmt(D
36530 2c 53 29 5d 20 6d 75 73 74 20 72 65 66 65 72 20  ,S)] must refer 
36540 74 6f 20 61 6e 20 6f 70 65 6e 20 64 61 74 61 62  to an open datab
36550 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  ase.** connectio
36560 6e 20 61 6e 64 20 69 6e 20 70 61 72 74 69 63 75  n and in particu
36570 6c 61 72 20 6d 75 73 74 20 6e 6f 74 20 62 65 20  lar must not be 
36580 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
36590 2a 2f 0a 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  */.sqlite3_stmt 
365a0 2a 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74  *sqlite3_next_st
365b0 6d 74 28 73 71 6c 69 74 65 33 20 2a 70 44 62 2c  mt(sqlite3 *pDb,
365c0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70   sqlite3_stmt *p
365d0 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
365e0 50 49 33 52 45 46 3a 20 43 6f 6d 6d 69 74 20 41  PI3REF: Commit A
365f0 6e 64 20 52 6f 6c 6c 62 61 63 6b 20 4e 6f 74 69  nd Rollback Noti
36600 66 69 63 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63  fication Callbac
36610 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ks.**.** ^The sq
36620 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f  lite3_commit_hoo
36630 6b 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  k() interface re
36640 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61  gisters a callba
36650 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74  ck.** function t
36660 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65  o be invoked whe
36670 6e 65 76 65 72 20 61 20 74 72 61 6e 73 61 63 74  never a transact
36680 69 6f 6e 20 69 73 20 5b 43 4f 4d 4d 49 54 20 7c  ion is [COMMIT |
36690 20 63 6f 6d 6d 69 74 74 65 64 5d 2e 0a 2a 2a 20   committed]..** 
366a0 5e 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73 65  ^Any callback se
366b0 74 20 62 79 20 61 20 70 72 65 76 69 6f 75 73 20  t by a previous 
366c0 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
366d0 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 0a 2a 2a  commit_hook().**
366e0 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 64 61   for the same da
366f0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
36700 6e 20 69 73 20 6f 76 65 72 72 69 64 64 65 6e 2e  n is overridden.
36710 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
36720 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29  _rollback_hook()
36730 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73   interface regis
36740 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 0a  ters a callback.
36750 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ** function to b
36760 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76  e invoked whenev
36770 65 72 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e  er a transaction
36780 20 69 73 20 5b 52 4f 4c 4c 42 41 43 4b 20 7c 20   is [ROLLBACK | 
36790 72 6f 6c 6c 65 64 20 62 61 63 6b 5d 2e 0a 2a 2a  rolled back]..**
367a0 20 5e 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73   ^Any callback s
367b0 65 74 20 62 79 20 61 20 70 72 65 76 69 6f 75 73  et by a previous
367c0 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
367d0 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29  _rollback_hook()
367e0 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65  .** for the same
367f0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
36800 74 69 6f 6e 20 69 73 20 6f 76 65 72 72 69 64 64  tion is overridd
36810 65 6e 2e 0a 2a 2a 20 5e 54 68 65 20 70 41 72 67  en..** ^The pArg
36820 20 61 72 67 75 6d 65 6e 74 20 69 73 20 70 61 73   argument is pas
36830 73 65 64 20 74 68 72 6f 75 67 68 20 74 6f 20 74  sed through to t
36840 68 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20  he callback..** 
36850 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  ^If the callback
36860 20 6f 6e 20 61 20 63 6f 6d 6d 69 74 20 68 6f 6f   on a commit hoo
36870 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  k function retur
36880 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 0a 2a 2a 20  ns non-zero,.** 
36890 74 68 65 6e 20 74 68 65 20 63 6f 6d 6d 69 74 20  then the commit 
368a0 69 73 20 63 6f 6e 76 65 72 74 65 64 20 69 6e 74  is converted int
368b0 6f 20 61 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a  o a rollback..**
368c0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
368d0 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 44 2c 43  _commit_hook(D,C
368e0 2c 50 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  ,P) and sqlite3_
368f0 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 44 2c  rollback_hook(D,
36900 43 2c 50 29 20 66 75 6e 63 74 69 6f 6e 73 0a 2a  C,P) functions.*
36910 2a 20 72 65 74 75 72 6e 20 74 68 65 20 50 20 61  * return the P a
36920 72 67 75 6d 65 6e 74 20 66 72 6f 6d 20 74 68 65  rgument from the
36930 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 6f   previous call o
36940 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74  f the same funct
36950 69 6f 6e 0a 2a 2a 20 6f 6e 20 74 68 65 20 73 61  ion.** on the sa
36960 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  me [database con
36970 6e 65 63 74 69 6f 6e 5d 20 44 2c 20 6f 72 20 4e  nection] D, or N
36980 55 4c 4c 20 66 6f 72 0a 2a 2a 20 74 68 65 20 66  ULL for.** the f
36990 69 72 73 74 20 63 61 6c 6c 20 66 6f 72 20 65 61  irst call for ea
369a0 63 68 20 66 75 6e 63 74 69 6f 6e 20 6f 6e 20 44  ch function on D
369b0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6d 6d  ..**.** The comm
369c0 69 74 20 61 6e 64 20 72 6f 6c 6c 62 61 63 6b 20  it and rollback 
369d0 68 6f 6f 6b 20 63 61 6c 6c 62 61 63 6b 73 20 61  hook callbacks a
369e0 72 65 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74  re not reentrant
369f0 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63  ..** The callbac
36a00 6b 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  k implementation
36a10 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79   must not do any
36a20 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20  thing that will 
36a30 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61  modify.** the da
36a40 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
36a50 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74  n that invoked t
36a60 68 65 20 63 61 6c 6c 62 61 63 6b 2e 20 20 41 6e  he callback.  An
36a70 79 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 74 6f 20  y actions.** to 
36a80 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74 61 62  modify the datab
36a90 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d  ase connection m
36aa0 75 73 74 20 62 65 20 64 65 66 65 72 72 65 64 20  ust be deferred 
36ab0 75 6e 74 69 6c 20 61 66 74 65 72 20 74 68 65 0a  until after the.
36ac0 2a 2a 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 6f 66  ** completion of
36ad0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74   the [sqlite3_st
36ae0 65 70 28 29 5d 20 63 61 6c 6c 20 74 68 61 74 20  ep()] call that 
36af0 74 72 69 67 67 65 72 65 64 20 74 68 65 20 63 6f  triggered the co
36b00 6d 6d 69 74 0a 2a 2a 20 6f 72 20 72 6f 6c 6c 62  mmit.** or rollb
36b10 61 63 6b 20 68 6f 6f 6b 20 69 6e 20 74 68 65 20  ack hook in the 
36b20 66 69 72 73 74 20 70 6c 61 63 65 2e 0a 2a 2a 20  first place..** 
36b30 4e 6f 74 65 20 74 68 61 74 20 72 75 6e 6e 69 6e  Note that runnin
36b40 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 20  g any other SQL 
36b50 73 74 61 74 65 6d 65 6e 74 73 2c 20 69 6e 63 6c  statements, incl
36b60 75 64 69 6e 67 20 53 45 4c 45 43 54 20 73 74 61  uding SELECT sta
36b70 74 65 6d 65 6e 74 73 2c 0a 2a 2a 20 6f 72 20 6d  tements,.** or m
36b80 65 72 65 6c 79 20 63 61 6c 6c 69 6e 67 20 5b 73  erely calling [s
36b90 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
36ba0 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  2()] and [sqlite
36bb0 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 6d  3_step()] will m
36bc0 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74  odify.** the dat
36bd0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
36be0 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e  s for the meanin
36bf0 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e  g of "modify" in
36c00 20 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e   this paragraph.
36c10 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 69 73 74 65 72  .**.** ^Register
36c20 69 6e 67 20 61 20 4e 55 4c 4c 20 66 75 6e 63 74  ing a NULL funct
36c30 69 6f 6e 20 64 69 73 61 62 6c 65 73 20 74 68 65  ion disables the
36c40 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a   callback..**.**
36c50 20 5e 57 68 65 6e 20 74 68 65 20 63 6f 6d 6d 69   ^When the commi
36c60 74 20 68 6f 6f 6b 20 63 61 6c 6c 62 61 63 6b 20  t hook callback 
36c70 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
36c80 7a 65 72 6f 2c 20 74 68 65 20 5b 43 4f 4d 4d 49  zero, the [COMMI
36c90 54 5d 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 20  T].** operation 
36ca0 69 73 20 61 6c 6c 6f 77 65 64 20 74 6f 20 63 6f  is allowed to co
36cb0 6e 74 69 6e 75 65 20 6e 6f 72 6d 61 6c 6c 79 2e  ntinue normally.
36cc0 20 20 5e 49 66 20 74 68 65 20 63 6f 6d 6d 69 74    ^If the commit
36cd0 20 68 6f 6f 6b 0a 2a 2a 20 72 65 74 75 72 6e 73   hook.** returns
36ce0 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20   non-zero, then 
36cf0 74 68 65 20 5b 43 4f 4d 4d 49 54 5d 20 69 73 20  the [COMMIT] is 
36d00 63 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 61  converted into a
36d10 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a 20   [ROLLBACK]..** 
36d20 5e 54 68 65 20 72 6f 6c 6c 62 61 63 6b 20 68 6f  ^The rollback ho
36d30 6f 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e  ok is invoked on
36d40 20 61 20 72 6f 6c 6c 62 61 63 6b 20 74 68 61 74   a rollback that
36d50 20 72 65 73 75 6c 74 73 20 66 72 6f 6d 20 61 20   results from a 
36d60 63 6f 6d 6d 69 74 0a 2a 2a 20 68 6f 6f 6b 20 72  commit.** hook r
36d70 65 74 75 72 6e 69 6e 67 20 6e 6f 6e 2d 7a 65 72  eturning non-zer
36d80 6f 2c 20 6a 75 73 74 20 61 73 20 69 74 20 77 6f  o, just as it wo
36d90 75 6c 64 20 62 65 20 77 69 74 68 20 61 6e 79 20  uld be with any 
36da0 6f 74 68 65 72 20 72 6f 6c 6c 62 61 63 6b 2e 0a  other rollback..
36db0 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20 70  **.** ^For the p
36dc0 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20  urposes of this 
36dd0 41 50 49 2c 20 61 20 74 72 61 6e 73 61 63 74 69  API, a transacti
36de0 6f 6e 20 69 73 20 73 61 69 64 20 74 6f 20 68 61  on is said to ha
36df0 76 65 20 62 65 65 6e 0a 2a 2a 20 72 6f 6c 6c 65  ve been.** rolle
36e00 64 20 62 61 63 6b 20 69 66 20 61 6e 20 65 78 70  d back if an exp
36e10 6c 69 63 69 74 20 22 52 4f 4c 4c 42 41 43 4b 22  licit "ROLLBACK"
36e20 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 65 78   statement is ex
36e30 65 63 75 74 65 64 2c 20 6f 72 0a 2a 2a 20 61 6e  ecuted, or.** an
36e40 20 65 72 72 6f 72 20 6f 72 20 63 6f 6e 73 74 72   error or constr
36e50 61 69 6e 74 20 63 61 75 73 65 73 20 61 6e 20 69  aint causes an i
36e60 6d 70 6c 69 63 69 74 20 72 6f 6c 6c 62 61 63 6b  mplicit rollback
36e70 20 74 6f 20 6f 63 63 75 72 2e 0a 2a 2a 20 5e 54   to occur..** ^T
36e80 68 65 20 72 6f 6c 6c 62 61 63 6b 20 63 61 6c 6c  he rollback call
36e90 62 61 63 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f  back is not invo
36ea0 6b 65 64 20 69 66 20 61 20 74 72 61 6e 73 61 63  ked if a transac
36eb0 74 69 6f 6e 20 69 73 0a 2a 2a 20 61 75 74 6f 6d  tion is.** autom
36ec0 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20  atically rolled 
36ed0 62 61 63 6b 20 62 65 63 61 75 73 65 20 74 68 65  back because the
36ee0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
36ef0 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a  tion is closed..
36f00 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74  **.** See also t
36f10 68 65 20 5b 73 71 6c 69 74 65 33 5f 75 70 64 61  he [sqlite3_upda
36f20 74 65 5f 68 6f 6f 6b 28 29 5d 20 69 6e 74 65 72  te_hook()] inter
36f30 66 61 63 65 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73  face..*/.void *s
36f40 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f  qlite3_commit_ho
36f50 6f 6b 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  ok(sqlite3*, int
36f60 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64  (*)(void*), void
36f70 2a 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65  *);.void *sqlite
36f80 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28  3_rollback_hook(
36f90 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a  sqlite3*, void(*
36fa0 29 28 76 6f 69 64 20 2a 29 2c 20 76 6f 69 64 2a  )(void *), void*
36fb0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
36fc0 45 46 3a 20 44 61 74 61 20 43 68 61 6e 67 65 20  EF: Data Change 
36fd0 4e 6f 74 69 66 69 63 61 74 69 6f 6e 20 43 61 6c  Notification Cal
36fe0 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68  lbacks.**.** ^Th
36ff0 65 20 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65  e sqlite3_update
37000 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61 63  _hook() interfac
37010 65 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61  e registers a ca
37020 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a  llback function.
37030 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 64 61 74  ** with the [dat
37040 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
37050 5d 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20  ] identified by 
37060 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
37070 6e 74 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 76 6f  nt.** to be invo
37080 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 20 72  ked whenever a r
37090 6f 77 20 69 73 20 75 70 64 61 74 65 64 2c 20 69  ow is updated, i
370a0 6e 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74  nserted or delet
370b0 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20 63 61 6c 6c  ed..** ^Any call
370c0 62 61 63 6b 20 73 65 74 20 62 79 20 61 20 70 72  back set by a pr
370d0 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 74  evious call to t
370e0 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  his function.** 
370f0 66 6f 72 20 74 68 65 20 73 61 6d 65 20 64 61 74  for the same dat
37100 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
37110 20 69 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a   is overridden..
37120 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e  **.** ^The secon
37130 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  d argument is a 
37140 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 66  pointer to the f
37150 75 6e 63 74 69 6f 6e 20 74 6f 20 69 6e 76 6f 6b  unction to invok
37160 65 20 77 68 65 6e 20 61 0a 2a 2a 20 72 6f 77 20  e when a.** row 
37170 69 73 20 75 70 64 61 74 65 64 2c 20 69 6e 73 65  is updated, inse
37180 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64 2e  rted or deleted.
37190 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61  .** ^The first a
371a0 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 63  rgument to the c
371b0 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70  allback is a cop
371c0 79 20 6f 66 20 74 68 65 20 74 68 69 72 64 20 61  y of the third a
371d0 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 73 71  rgument.** to sq
371e0 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f  lite3_update_hoo
371f0 6b 28 29 2e 0a 2a 2a 20 5e 54 68 65 20 73 65 63  k()..** ^The sec
37200 6f 6e 64 20 63 61 6c 6c 62 61 63 6b 20 61 72 67  ond callback arg
37210 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20  ument is one of 
37220 5b 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 5d 2c  [SQLITE_INSERT],
37230 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d   [SQLITE_DELETE]
37240 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ,.** or [SQLITE_
37250 55 50 44 41 54 45 5d 2c 20 64 65 70 65 6e 64 69  UPDATE], dependi
37260 6e 67 20 6f 6e 20 74 68 65 20 6f 70 65 72 61 74  ng on the operat
37270 69 6f 6e 20 74 68 61 74 20 63 61 75 73 65 64 20  ion that caused 
37280 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  the callback.** 
37290 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 2e 0a 2a  to be invoked..*
372a0 2a 20 5e 54 68 65 20 74 68 69 72 64 20 61 6e 64  * ^The third and
372b0 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74   fourth argument
372c0 73 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63  s to the callbac
372d0 6b 20 63 6f 6e 74 61 69 6e 20 70 6f 69 6e 74 65  k contain pointe
372e0 72 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74  rs to the.** dat
372f0 61 62 61 73 65 20 61 6e 64 20 74 61 62 6c 65 20  abase and table 
37300 6e 61 6d 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20  name containing 
37310 74 68 65 20 61 66 66 65 63 74 65 64 20 72 6f 77  the affected row
37320 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 6e 61 6c 20  ..** ^The final 
37330 63 61 6c 6c 62 61 63 6b 20 70 61 72 61 6d 65 74  callback paramet
37340 65 72 20 69 73 20 74 68 65 20 5b 72 6f 77 69 64  er is the [rowid
37350 5d 20 6f 66 20 74 68 65 20 72 6f 77 2e 0a 2a 2a  ] of the row..**
37360 20 5e 49 6e 20 74 68 65 20 63 61 73 65 20 6f 66   ^In the case of
37370 20 61 6e 20 75 70 64 61 74 65 2c 20 74 68 69 73   an update, this
37380 20 69 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20   is the [rowid] 
37390 61 66 74 65 72 20 74 68 65 20 75 70 64 61 74 65  after the update
373a0 20 74 61 6b 65 73 20 70 6c 61 63 65 2e 0a 2a 2a   takes place..**
373b0 0a 2a 2a 20 5e 28 54 68 65 20 75 70 64 61 74 65  .** ^(The update
373c0 20 68 6f 6f 6b 20 69 73 20 6e 6f 74 20 69 6e 76   hook is not inv
373d0 6f 6b 65 64 20 77 68 65 6e 20 69 6e 74 65 72 6e  oked when intern
373e0 61 6c 20 73 79 73 74 65 6d 20 74 61 62 6c 65 73  al system tables
373f0 20 61 72 65 0a 2a 2a 20 6d 6f 64 69 66 69 65 64   are.** modified
37400 20 28 69 2e 65 2e 20 73 71 6c 69 74 65 5f 6d 61   (i.e. sqlite_ma
37410 73 74 65 72 20 61 6e 64 20 73 71 6c 69 74 65 5f  ster and sqlite_
37420 73 65 71 75 65 6e 63 65 29 2e 29 5e 0a 2a 2a 0a  sequence).)^.**.
37430 2a 2a 20 5e 49 6e 20 74 68 65 20 63 75 72 72 65  ** ^In the curre
37440 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  nt implementatio
37450 6e 2c 20 74 68 65 20 75 70 64 61 74 65 20 68 6f  n, the update ho
37460 6f 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 69 6e 76  ok.** is not inv
37470 6f 6b 65 64 20 77 68 65 6e 20 64 75 70 6c 69 63  oked when duplic
37480 61 74 69 6f 6e 20 72 6f 77 73 20 61 72 65 20 64  ation rows are d
37490 65 6c 65 74 65 64 20 62 65 63 61 75 73 65 20 6f  eleted because o
374a0 66 20 61 6e 0a 2a 2a 20 5b 4f 4e 20 43 4f 4e 46  f an.** [ON CONF
374b0 4c 49 43 54 20 7c 20 4f 4e 20 43 4f 4e 46 4c 49  LICT | ON CONFLI
374c0 43 54 20 52 45 50 4c 41 43 45 5d 20 63 6c 61 75  CT REPLACE] clau
374d0 73 65 2e 20 20 5e 4e 6f 72 20 69 73 20 74 68 65  se.  ^Nor is the
374e0 20 75 70 64 61 74 65 20 68 6f 6f 6b 0a 2a 2a 20   update hook.** 
374f0 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 72 6f 77  invoked when row
37500 73 20 61 72 65 20 64 65 6c 65 74 65 64 20 75 73  s are deleted us
37510 69 6e 67 20 74 68 65 20 5b 74 72 75 6e 63 61 74  ing the [truncat
37520 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 2e  e optimization].
37530 0a 2a 2a 20 54 68 65 20 65 78 63 65 70 74 69 6f  .** The exceptio
37540 6e 73 20 64 65 66 69 6e 65 64 20 69 6e 20 74 68  ns defined in th
37550 69 73 20 70 61 72 61 67 72 61 70 68 20 6d 69 67  is paragraph mig
37560 68 74 20 63 68 61 6e 67 65 20 69 6e 20 61 20 66  ht change in a f
37570 75 74 75 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65  uture.** release
37580 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a   of SQLite..**.*
37590 2a 20 54 68 65 20 75 70 64 61 74 65 20 68 6f 6f  * The update hoo
375a0 6b 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  k implementation
375b0 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79   must not do any
375c0 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20  thing that will 
375d0 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61  modify.** the da
375e0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
375f0 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74  n that invoked t
37600 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 2e 20  he update hook. 
37610 20 41 6e 79 20 61 63 74 69 6f 6e 73 0a 2a 2a 20   Any actions.** 
37620 74 6f 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61  to modify the da
37630 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
37640 6e 20 6d 75 73 74 20 62 65 20 64 65 66 65 72 72  n must be deferr
37650 65 64 20 75 6e 74 69 6c 20 61 66 74 65 72 20 74  ed until after t
37660 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 69 6f 6e  he.** completion
37670 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
37680 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 74 68  _step()] call th
37690 61 74 20 74 72 69 67 67 65 72 65 64 20 74 68 65  at triggered the
376a0 20 75 70 64 61 74 65 20 68 6f 6f 6b 2e 0a 2a 2a   update hook..**
376b0 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69   Note that [sqli
376c0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
376d0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73  ] and [sqlite3_s
376e0 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69  tep()] both modi
376f0 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61  fy their.** data
37700 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
37710 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67   for the meaning
37720 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20   of "modify" in 
37730 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a  this paragraph..
37740 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
37750 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 44  e3_update_hook(D
37760 2c 43 2c 50 29 20 66 75 6e 63 74 69 6f 6e 0a 2a  ,C,P) function.*
37770 2a 20 72 65 74 75 72 6e 73 20 74 68 65 20 50 20  * returns the P 
37780 61 72 67 75 6d 65 6e 74 20 66 72 6f 6d 20 74 68  argument from th
37790 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 0a  e previous call.
377a0 2a 2a 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b  ** on the same [
377b0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
377c0 69 6f 6e 5d 20 44 2c 20 6f 72 20 4e 55 4c 4c 20  ion] D, or NULL 
377d0 66 6f 72 0a 2a 2a 20 74 68 65 20 66 69 72 73 74  for.** the first
377e0 20 63 61 6c 6c 20 6f 6e 20 44 2e 0a 2a 2a 0a 2a   call on D..**.*
377f0 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b  * See also the [
37800 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68  sqlite3_commit_h
37810 6f 6f 6b 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ook()] and [sqli
37820 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f  te3_rollback_hoo
37830 6b 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63  k()].** interfac
37840 65 73 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c  es..*/.void *sql
37850 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b  ite3_update_hook
37860 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20  (.  sqlite3*, . 
37870 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 20 2a 2c   void(*)(void *,
37880 69 6e 74 20 2c 63 68 61 72 20 63 6f 6e 73 74 20  int ,char const 
37890 2a 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a 2c 73  *,char const *,s
378a0 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 2c 0a 20  qlite3_int64),. 
378b0 20 76 6f 69 64 2a 0a 29 3b 0a 0a 2f 2a 0a 2a 2a   void*.);../*.**
378c0 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c   CAPI3REF: Enabl
378d0 65 20 4f 72 20 44 69 73 61 62 6c 65 20 53 68 61  e Or Disable Sha
378e0 72 65 64 20 50 61 67 65 72 20 43 61 63 68 65 0a  red Pager Cache.
378f0 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f 75  **.** ^(This rou
37900 74 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72 20  tine enables or 
37910 64 69 73 61 62 6c 65 73 20 74 68 65 20 73 68 61  disables the sha
37920 72 69 6e 67 20 6f 66 20 74 68 65 20 64 61 74 61  ring of the data
37930 62 61 73 65 20 63 61 63 68 65 0a 2a 2a 20 61 6e  base cache.** an
37940 64 20 73 63 68 65 6d 61 20 64 61 74 61 20 73 74  d schema data st
37950 72 75 63 74 75 72 65 73 20 62 65 74 77 65 65 6e  ructures between
37960 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
37970 63 74 69 6f 6e 20 7c 20 63 6f 6e 6e 65 63 74 69  ction | connecti
37980 6f 6e 73 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 73  ons].** to the s
37990 61 6d 65 20 64 61 74 61 62 61 73 65 2e 20 53 68  ame database. Sh
379a0 61 72 69 6e 67 20 69 73 20 65 6e 61 62 6c 65 64  aring is enabled
379b0 20 69 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74   if the argument
379c0 20 69 73 20 74 72 75 65 0a 2a 2a 20 61 6e 64 20   is true.** and 
379d0 64 69 73 61 62 6c 65 64 20 69 66 20 74 68 65 20  disabled if the 
379e0 61 72 67 75 6d 65 6e 74 20 69 73 20 66 61 6c 73  argument is fals
379f0 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 43 61 63 68  e.)^.**.** ^Cach
37a00 65 20 73 68 61 72 69 6e 67 20 69 73 20 65 6e 61  e sharing is ena
37a10 62 6c 65 64 20 61 6e 64 20 64 69 73 61 62 6c 65  bled and disable
37a20 64 20 66 6f 72 20 61 6e 20 65 6e 74 69 72 65 20  d for an entire 
37a30 70 72 6f 63 65 73 73 2e 0a 2a 2a 20 54 68 69 73  process..** This
37a40 20 69 73 20 61 20 63 68 61 6e 67 65 20 61 73 20   is a change as 
37a50 6f 66 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  of SQLite versio
37a60 6e 20 33 2e 35 2e 30 2e 20 49 6e 20 70 72 69 6f  n 3.5.0. In prio
37a70 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  r versions of SQ
37a80 4c 69 74 65 2c 0a 2a 2a 20 73 68 61 72 69 6e 67  Lite,.** sharing
37a90 20 77 61 73 20 65 6e 61 62 6c 65 64 20 6f 72 20   was enabled or 
37aa0 64 69 73 61 62 6c 65 64 20 66 6f 72 20 65 61 63  disabled for eac
37ab0 68 20 74 68 72 65 61 64 20 73 65 70 61 72 61 74  h thread separat
37ac0 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ely..**.** ^(The
37ad0 20 63 61 63 68 65 20 73 68 61 72 69 6e 67 20 6d   cache sharing m
37ae0 6f 64 65 20 73 65 74 20 62 79 20 74 68 69 73 20  ode set by this 
37af0 69 6e 74 65 72 66 61 63 65 20 65 66 66 65 63 74  interface effect
37b00 73 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74  s all subsequent
37b10 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71  .** calls to [sq
37b20 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b  lite3_open()], [
37b30 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
37b40 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  )], and [sqlite3
37b50 5f 6f 70 65 6e 31 36 28 29 5d 2e 0a 2a 2a 20 45  _open16()]..** E
37b60 78 69 73 74 69 6e 67 20 64 61 74 61 62 61 73 65  xisting database
37b70 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 63 6f 6e   connections con
37b80 74 69 6e 75 65 20 75 73 65 20 74 68 65 20 73 68  tinue use the sh
37b90 61 72 69 6e 67 20 6d 6f 64 65 0a 2a 2a 20 74 68  aring mode.** th
37ba0 61 74 20 77 61 73 20 69 6e 20 65 66 66 65 63 74  at was in effect
37bb0 20 61 74 20 74 68 65 20 74 69 6d 65 20 74 68 65   at the time the
37bc0 79 20 77 65 72 65 20 6f 70 65 6e 65 64 2e 29 5e  y were opened.)^
37bd0 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f  .**.** ^(This ro
37be0 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53  utine returns [S
37bf0 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 20 73 68 61  QLITE_OK] if sha
37c00 72 65 64 20 63 61 63 68 65 20 77 61 73 20 65 6e  red cache was en
37c10 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65  abled or disable
37c20 64 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c  d.** successfull
37c30 79 2e 20 20 41 6e 20 5b 65 72 72 6f 72 20 63 6f  y.  An [error co
37c40 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20  de] is returned 
37c50 6f 74 68 65 72 77 69 73 65 2e 29 5e 0a 2a 2a 0a  otherwise.)^.**.
37c60 2a 2a 20 5e 53 68 61 72 65 64 20 63 61 63 68 65  ** ^Shared cache
37c70 20 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 20   is disabled by 
37c80 64 65 66 61 75 6c 74 2e 20 42 75 74 20 74 68 69  default. But thi
37c90 73 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20 69  s might change i
37ca0 6e 0a 2a 2a 20 66 75 74 75 72 65 20 72 65 6c 65  n.** future rele
37cb0 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 20  ases of SQLite. 
37cc0 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68   Applications th
37cd0 61 74 20 63 61 72 65 20 61 62 6f 75 74 20 73 68  at care about sh
37ce0 61 72 65 64 0a 2a 2a 20 63 61 63 68 65 20 73 65  ared.** cache se
37cf0 74 74 69 6e 67 20 73 68 6f 75 6c 64 20 73 65 74  tting should set
37d00 20 69 74 20 65 78 70 6c 69 63 69 74 6c 79 2e 0a   it explicitly..
37d10 2a 2a 0a 2a 2a 20 53 65 65 20 41 6c 73 6f 3a 20  **.** See Also: 
37d20 20 5b 53 51 4c 69 74 65 20 53 68 61 72 65 64 2d   [SQLite Shared-
37d30 43 61 63 68 65 20 4d 6f 64 65 5d 0a 2a 2f 0a 69  Cache Mode].*/.i
37d40 6e 74 20 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c  nt sqlite3_enabl
37d50 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65 28 69  e_shared_cache(i
37d60 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
37d70 33 52 45 46 3a 20 41 74 74 65 6d 70 74 20 54 6f  3REF: Attempt To
37d80 20 46 72 65 65 20 48 65 61 70 20 4d 65 6d 6f 72   Free Heap Memor
37d90 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  y.**.** ^The sql
37da0 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d  ite3_release_mem
37db0 6f 72 79 28 29 20 69 6e 74 65 72 66 61 63 65 20  ory() interface 
37dc0 61 74 74 65 6d 70 74 73 20 74 6f 20 66 72 65 65  attempts to free
37dd0 20 4e 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 68   N bytes.** of h
37de0 65 61 70 20 6d 65 6d 6f 72 79 20 62 79 20 64 65  eap memory by de
37df0 61 6c 6c 6f 63 61 74 69 6e 67 20 6e 6f 6e 2d 65  allocating non-e
37e00 73 73 65 6e 74 69 61 6c 20 6d 65 6d 6f 72 79 20  ssential memory 
37e10 61 6c 6c 6f 63 61 74 69 6f 6e 73 0a 2a 2a 20 68  allocations.** h
37e20 65 6c 64 20 62 79 20 74 68 65 20 64 61 74 61 62  eld by the datab
37e30 61 73 65 20 6c 69 62 72 61 72 79 2e 20 20 20 4d  ase library.   M
37e40 65 6d 6f 72 79 20 75 73 65 64 20 74 6f 20 63 61  emory used to ca
37e50 63 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  che database.** 
37e60 70 61 67 65 73 20 74 6f 20 69 6d 70 72 6f 76 65  pages to improve
37e70 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 69 73 20   performance is 
37e80 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 6e 6f  an example of no
37e90 6e 2d 65 73 73 65 6e 74 69 61 6c 20 6d 65 6d 6f  n-essential memo
37ea0 72 79 2e 0a 2a 2a 20 5e 73 71 6c 69 74 65 33 5f  ry..** ^sqlite3_
37eb0 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29  release_memory()
37ec0 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
37ed0 62 65 72 20 6f 66 20 62 79 74 65 73 20 61 63 74  ber of bytes act
37ee0 75 61 6c 6c 79 20 66 72 65 65 64 2c 0a 2a 2a 20  ually freed,.** 
37ef0 77 68 69 63 68 20 6d 69 67 68 74 20 62 65 20 6d  which might be m
37f00 6f 72 65 20 6f 72 20 6c 65 73 73 20 74 68 61 6e  ore or less than
37f10 20 74 68 65 20 61 6d 6f 75 6e 74 20 72 65 71 75   the amount requ
37f20 65 73 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73  ested..** ^The s
37f30 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d  qlite3_release_m
37f40 65 6d 6f 72 79 28 29 20 72 6f 75 74 69 6e 65 20  emory() routine 
37f50 69 73 20 61 20 6e 6f 2d 6f 70 20 72 65 74 75 72  is a no-op retur
37f60 6e 69 6e 67 20 7a 65 72 6f 0a 2a 2a 20 69 66 20  ning zero.** if 
37f70 53 51 4c 69 74 65 20 69 73 20 6e 6f 74 20 63 6f  SQLite is not co
37f80 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c  mpiled with [SQL
37f90 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 4f 52  ITE_ENABLE_MEMOR
37fa0 59 5f 4d 41 4e 41 47 45 4d 45 4e 54 5d 2e 0a 2a  Y_MANAGEMENT]..*
37fb0 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
37fc0 73 71 6c 69 74 65 33 5f 64 62 5f 72 65 6c 65 61  sqlite3_db_relea
37fd0 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 0a 2a 2f 0a  se_memory()].*/.
37fe0 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 6c 65  int sqlite3_rele
37ff0 61 73 65 5f 6d 65 6d 6f 72 79 28 69 6e 74 29 3b  ase_memory(int);
38000 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
38010 3a 20 46 72 65 65 20 4d 65 6d 6f 72 79 20 55 73  : Free Memory Us
38020 65 64 20 42 79 20 41 20 44 61 74 61 62 61 73 65  ed By A Database
38030 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 0a 2a   Connection.**.*
38040 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64  * ^The sqlite3_d
38050 62 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79  b_release_memory
38060 28 44 29 20 69 6e 74 65 72 66 61 63 65 20 61 74  (D) interface at
38070 74 65 6d 70 74 73 20 74 6f 20 66 72 65 65 20 61  tempts to free a
38080 73 20 6d 75 63 68 20 68 65 61 70 0a 2a 2a 20 6d  s much heap.** m
38090 65 6d 6f 72 79 20 61 73 20 70 6f 73 73 69 62 6c  emory as possibl
380a0 65 20 66 72 6f 6d 20 64 61 74 61 62 61 73 65 20  e from database 
380b0 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 55 6e  connection D. Un
380c0 6c 69 6b 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  like the.** [sql
380d0 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d  ite3_release_mem
380e0 6f 72 79 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ory()] interface
380f0 2c 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65  , this interface
38100 20 69 73 20 65 66 66 65 63 74 20 65 76 65 6e 0a   is effect even.
38110 2a 2a 20 77 68 65 6e 20 74 68 65 6e 20 5b 53 51  ** when then [SQ
38120 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 4f  LITE_ENABLE_MEMO
38130 52 59 5f 4d 41 4e 41 47 45 4d 45 4e 54 5d 20 63  RY_MANAGEMENT] c
38140 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
38150 6f 6e 20 69 73 0a 2a 2a 20 6f 6d 69 74 74 65 64  on is.** omitted
38160 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
38170 3a 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61  : [sqlite3_relea
38180 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 0a 2a 2f 0a  se_memory()].*/.
38190 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 62 5f 72  int sqlite3_db_r
381a0 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 73 71  elease_memory(sq
381b0 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  lite3*);../*.** 
381c0 43 41 50 49 33 52 45 46 3a 20 49 6d 70 6f 73 65  CAPI3REF: Impose
381d0 20 41 20 4c 69 6d 69 74 20 4f 6e 20 48 65 61 70   A Limit On Heap
381e0 20 53 69 7a 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65   Size.**.** ^The
381f0 20 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65   sqlite3_soft_he
38200 61 70 5f 6c 69 6d 69 74 36 34 28 29 20 69 6e 74  ap_limit64() int
38210 65 72 66 61 63 65 20 73 65 74 73 20 61 6e 64 2f  erface sets and/
38220 6f 72 20 71 75 65 72 69 65 73 20 74 68 65 0a 2a  or queries the.*
38230 2a 20 73 6f 66 74 20 6c 69 6d 69 74 20 6f 6e 20  * soft limit on 
38240 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 68 65  the amount of he
38250 61 70 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 6d  ap memory that m
38260 61 79 20 62 65 20 61 6c 6c 6f 63 61 74 65 64 20  ay be allocated 
38270 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 5e 53  by SQLite..** ^S
38280 51 4c 69 74 65 20 73 74 72 69 76 65 73 20 74 6f  QLite strives to
38290 20 6b 65 65 70 20 68 65 61 70 20 6d 65 6d 6f 72   keep heap memor
382a0 79 20 75 74 69 6c 69 7a 61 74 69 6f 6e 20 62 65  y utilization be
382b0 6c 6f 77 20 74 68 65 20 73 6f 66 74 20 68 65 61  low the soft hea
382c0 70 0a 2a 2a 20 6c 69 6d 69 74 20 62 79 20 72 65  p.** limit by re
382d0 64 75 63 69 6e 67 20 74 68 65 20 6e 75 6d 62 65  ducing the numbe
382e0 72 20 6f 66 20 70 61 67 65 73 20 68 65 6c 64 20  r of pages held 
382f0 69 6e 20 74 68 65 20 70 61 67 65 20 63 61 63 68  in the page cach
38300 65 0a 2a 2a 20 61 73 20 68 65 61 70 20 6d 65 6d  e.** as heap mem
38310 6f 72 79 20 75 73 61 67 65 73 20 61 70 70 72 6f  ory usages appro
38320 61 63 68 65 73 20 74 68 65 20 6c 69 6d 69 74 2e  aches the limit.
38330 0a 2a 2a 20 5e 54 68 65 20 73 6f 66 74 20 68 65  .** ^The soft he
38340 61 70 20 6c 69 6d 69 74 20 69 73 20 22 73 6f 66  ap limit is "sof
38350 74 22 20 62 65 63 61 75 73 65 20 65 76 65 6e 20  t" because even 
38360 74 68 6f 75 67 68 20 53 51 4c 69 74 65 20 73 74  though SQLite st
38370 72 69 76 65 73 20 74 6f 20 73 74 61 79 0a 2a 2a  rives to stay.**
38380 20 62 65 6c 6f 77 20 74 68 65 20 6c 69 6d 69 74   below the limit
38390 2c 20 69 74 20 77 69 6c 6c 20 65 78 63 65 65 64  , it will exceed
383a0 20 74 68 65 20 6c 69 6d 69 74 20 72 61 74 68 65   the limit rathe
383b0 72 20 74 68 61 6e 20 67 65 6e 65 72 61 74 65 0a  r than generate.
383c0 2a 2a 20 61 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f  ** an [SQLITE_NO
383d0 4d 45 4d 5d 20 65 72 72 6f 72 2e 20 20 49 6e 20  MEM] error.  In 
383e0 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65  other words, the
383f0 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74   soft heap limit
38400 20 0a 2a 2a 20 69 73 20 61 64 76 69 73 6f 72 79   .** is advisory
38410 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68   only..**.** ^Th
38420 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66  e return value f
38430 72 6f 6d 20 73 71 6c 69 74 65 33 5f 73 6f 66 74  rom sqlite3_soft
38440 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28 29 20  _heap_limit64() 
38450 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66 0a 2a  is the size of.*
38460 2a 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20  * the soft heap 
38470 6c 69 6d 69 74 20 70 72 69 6f 72 20 74 6f 20 74  limit prior to t
38480 68 65 20 63 61 6c 6c 2c 20 6f 72 20 6e 65 67 61  he call, or nega
38490 74 69 76 65 20 69 6e 20 74 68 65 20 63 61 73 65  tive in the case
384a0 20 6f 66 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 2e   of an.** error.
384b0 20 20 5e 49 66 20 74 68 65 20 61 72 67 75 6d 65    ^If the argume
384c0 6e 74 20 4e 20 69 73 20 6e 65 67 61 74 69 76 65  nt N is negative
384d0 0a 2a 2a 20 74 68 65 6e 20 6e 6f 20 63 68 61 6e  .** then no chan
384e0 67 65 20 69 73 20 6d 61 64 65 20 74 6f 20 74 68  ge is made to th
384f0 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69  e soft heap limi
38500 74 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20 63  t.  Hence, the c
38510 75 72 72 65 6e 74 0a 2a 2a 20 73 69 7a 65 20 6f  urrent.** size o
38520 66 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20  f the soft heap 
38530 6c 69 6d 69 74 20 63 61 6e 20 62 65 20 64 65 74  limit can be det
38540 65 72 6d 69 6e 65 64 20 62 79 20 69 6e 76 6f 6b  ermined by invok
38550 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73  ing.** sqlite3_s
38560 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34  oft_heap_limit64
38570 28 29 20 77 69 74 68 20 61 20 6e 65 67 61 74 69  () with a negati
38580 76 65 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a  ve argument..**.
38590 2a 2a 20 5e 49 66 20 74 68 65 20 61 72 67 75 6d  ** ^If the argum
385a0 65 6e 74 20 4e 20 69 73 20 7a 65 72 6f 20 74 68  ent N is zero th
385b0 65 6e 20 74 68 65 20 73 6f 66 74 20 68 65 61 70  en the soft heap
385c0 20 6c 69 6d 69 74 20 69 73 20 64 69 73 61 62 6c   limit is disabl
385d0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  ed..**.** ^(The 
385e0 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20  soft heap limit 
385f0 69 73 20 6e 6f 74 20 65 6e 66 6f 72 63 65 64 20  is not enforced 
38600 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 69  in the current i
38610 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a  mplementation.**
38620 20 69 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20   if one or more 
38630 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 6f 6e  of following con
38640 64 69 74 69 6f 6e 73 20 61 72 65 20 74 72 75 65  ditions are true
38650 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
38660 3c 6c 69 3e 20 54 68 65 20 73 6f 66 74 20 68 65  <li> The soft he
38670 61 70 20 6c 69 6d 69 74 20 69 73 20 73 65 74 20  ap limit is set 
38680 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 20 3c 6c 69 3e  to zero..** <li>
38690 20 4d 65 6d 6f 72 79 20 61 63 63 6f 75 6e 74 69   Memory accounti
386a0 6e 67 20 69 73 20 64 69 73 61 62 6c 65 64 20 75  ng is disabled u
386b0 73 69 6e 67 20 61 20 63 6f 6d 62 69 6e 61 74 69  sing a combinati
386c0 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20  on of the.**    
386d0 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69    [sqlite3_confi
386e0 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  g]([SQLITE_CONFI
386f0 47 5f 4d 45 4d 53 54 41 54 55 53 5d 2c 2e 2e 2e  G_MEMSTATUS],...
38700 29 20 73 74 61 72 74 2d 74 69 6d 65 20 6f 70 74  ) start-time opt
38710 69 6f 6e 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20  ion and.**      
38720 74 68 65 20 5b 53 51 4c 49 54 45 5f 44 45 46 41  the [SQLITE_DEFA
38730 55 4c 54 5f 4d 45 4d 53 54 41 54 55 53 5d 20 63  ULT_MEMSTATUS] c
38740 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
38750 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20 41 6e 20 61  on..** <li> An a
38760 6c 74 65 72 6e 61 74 69 76 65 20 70 61 67 65 20  lternative page 
38770 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  cache implementa
38780 74 69 6f 6e 20 69 73 20 73 70 65 63 69 66 69 65  tion is specifie
38790 64 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20  d using.**      
387a0 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d  [sqlite3_config]
387b0 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  ([SQLITE_CONFIG_
387c0 50 43 41 43 48 45 32 5d 2c 2e 2e 2e 29 2e 0a 2a  PCACHE2],...)..*
387d0 2a 20 3c 6c 69 3e 20 54 68 65 20 70 61 67 65 20  * <li> The page 
387e0 63 61 63 68 65 20 61 6c 6c 6f 63 61 74 65 73 20  cache allocates 
387f0 66 72 6f 6d 20 69 74 73 20 6f 77 6e 20 6d 65 6d  from its own mem
38800 6f 72 79 20 70 6f 6f 6c 20 73 75 70 70 6c 69 65  ory pool supplie
38810 64 0a 2a 2a 20 20 20 20 20 20 62 79 20 5b 73 71  d.**      by [sq
38820 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53  lite3_config]([S
38830 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47  QLITE_CONFIG_PAG
38840 45 43 41 43 48 45 5d 2c 2e 2e 2e 29 20 72 61 74  ECACHE],...) rat
38850 68 65 72 20 74 68 61 6e 0a 2a 2a 20 20 20 20 20  her than.**     
38860 20 66 72 6f 6d