/ Hex Artifact Content
Login

Artifact a291a999d28ebc16cd1fe7fdd010dfe5266ef767:


0000: 2f 2a 0a 2a 2a 20 32 30 30 31 20 53 65 70 74 65  /*.** 2001 Septe
0010: 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68  mber 15.**.** Th
0020: 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69  e author disclai
0030: 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20  ms copyright to 
0040: 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65  this source code
0050: 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  .  In place of.*
0060: 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65  * a legal notice
0070: 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 73  , here is a bles
0080: 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d  sing:.**.**    M
0090: 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61  ay you do good a
00a0: 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20  nd not evil..** 
00b0: 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20     May you find 
00c0: 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20  forgiveness for 
00d0: 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72  yourself and for
00e0: 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20  give others..** 
00f0: 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65     May you share
0100: 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74   freely, never t
0110: 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20  aking more than 
0120: 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a  you give..**.***
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0170: 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 68  ******.** This h
0180: 65 61 64 65 72 20 66 69 6c 65 20 64 65 66 69 6e  eader file defin
0190: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
01a0: 20 74 68 61 74 20 74 68 65 20 53 51 4c 69 74 65   that the SQLite
01b0: 20 6c 69 62 72 61 72 79 0a 2a 2a 20 70 72 65 73   library.** pres
01c0: 65 6e 74 73 20 74 6f 20 63 6c 69 65 6e 74 20 70  ents to client p
01d0: 72 6f 67 72 61 6d 73 2e 20 20 49 66 20 61 20 43  rograms.  If a C
01e0: 2d 66 75 6e 63 74 69 6f 6e 2c 20 73 74 72 75 63  -function, struc
01f0: 74 75 72 65 2c 20 64 61 74 61 74 79 70 65 2c 0a  ture, datatype,.
0200: 2a 2a 20 6f 72 20 63 6f 6e 73 74 61 6e 74 20 64  ** or constant d
0210: 65 66 69 6e 69 74 69 6f 6e 20 64 6f 65 73 20 6e  efinition does n
0220: 6f 74 20 61 70 70 65 61 72 20 69 6e 20 74 68 69  ot appear in thi
0230: 73 20 66 69 6c 65 2c 20 74 68 65 6e 20 69 74 20  s file, then it 
0240: 69 73 0a 2a 2a 20 6e 6f 74 20 61 20 70 75 62 6c  is.** not a publ
0250: 69 73 68 65 64 20 41 50 49 20 6f 66 20 53 51 4c  ished API of SQL
0260: 69 74 65 2c 20 69 73 20 73 75 62 6a 65 63 74 20  ite, is subject 
0270: 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75  to change withou
0280: 74 0a 2a 2a 20 6e 6f 74 69 63 65 2c 20 61 6e 64  t.** notice, and
0290: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 72   should not be r
02a0: 65 66 65 72 65 6e 63 65 64 20 62 79 20 70 72 6f  eferenced by pro
02b0: 67 72 61 6d 73 20 74 68 61 74 20 75 73 65 20 53  grams that use S
02c0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d  QLite..**.** Som
02d0: 65 20 6f 66 20 74 68 65 20 64 65 66 69 6e 69 74  e of the definit
02e0: 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 69 6e  ions that are in
02f0: 20 74 68 69 73 20 66 69 6c 65 20 61 72 65 20 6d   this file are m
0300: 61 72 6b 65 64 20 61 73 0a 2a 2a 20 22 65 78 70  arked as.** "exp
0310: 65 72 69 6d 65 6e 74 61 6c 22 2e 20 20 45 78 70  erimental".  Exp
0320: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
0330: 61 63 65 73 20 61 72 65 20 6e 6f 72 6d 61 6c 6c  aces are normall
0340: 79 20 6e 65 77 0a 2a 2a 20 66 65 61 74 75 72 65  y new.** feature
0350: 73 20 72 65 63 65 6e 74 6c 79 20 61 64 64 65 64  s recently added
0360: 20 74 6f 20 53 51 4c 69 74 65 2e 20 20 57 65 20   to SQLite.  We 
0370: 64 6f 20 6e 6f 74 20 61 6e 74 69 63 69 70 61 74  do not anticipat
0380: 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20  e changes.** to 
0390: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
03a0: 65 72 66 61 63 65 73 20 62 75 74 20 72 65 73 65  erfaces but rese
03b0: 72 76 65 20 74 68 65 20 72 69 67 68 74 20 74 6f  rve the right to
03c0: 20 6d 61 6b 65 20 6d 69 6e 6f 72 20 63 68 61 6e   make minor chan
03d0: 67 65 73 0a 2a 2a 20 69 66 20 65 78 70 65 72 69  ges.** if experi
03e0: 65 6e 63 65 20 66 72 6f 6d 20 75 73 65 20 22 69  ence from use "i
03f0: 6e 20 74 68 65 20 77 69 6c 64 22 20 73 75 67 67  n the wild" sugg
0400: 65 73 74 20 73 75 63 68 20 63 68 61 6e 67 65 73  est such changes
0410: 20 61 72 65 20 70 72 75 64 65 6e 74 2e 0a 2a 2a   are prudent..**
0420: 0a 2a 2a 20 54 68 65 20 6f 66 66 69 63 69 61 6c  .** The official
0430: 20 43 2d 6c 61 6e 67 75 61 67 65 20 41 50 49 20   C-language API 
0440: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  documentation fo
0450: 72 20 53 51 4c 69 74 65 20 69 73 20 64 65 72 69  r SQLite is deri
0460: 76 65 64 0a 2a 2a 20 66 72 6f 6d 20 63 6f 6d 6d  ved.** from comm
0470: 65 6e 74 73 20 69 6e 20 74 68 69 73 20 66 69 6c  ents in this fil
0480: 65 2e 20 20 54 68 69 73 20 66 69 6c 65 20 69 73  e.  This file is
0490: 20 74 68 65 20 61 75 74 68 6f 72 69 74 61 74 69   the authoritati
04a0: 76 65 20 73 6f 75 72 63 65 0a 2a 2a 20 6f 6e 20  ve source.** on 
04b0: 68 6f 77 20 53 51 4c 69 74 65 20 69 6e 74 65 72  how SQLite inter
04c0: 66 61 63 65 73 20 61 72 65 20 73 75 70 70 6f 73  faces are suppos
04d0: 65 20 74 6f 20 6f 70 65 72 61 74 65 2e 0a 2a 2a  e to operate..**
04e0: 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20  .** The name of 
04f0: 74 68 69 73 20 66 69 6c 65 20 75 6e 64 65 72 20  this file under 
0500: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61  configuration ma
0510: 6e 61 67 65 6d 65 6e 74 20 69 73 20 22 73 71 6c  nagement is "sql
0520: 69 74 65 2e 68 2e 69 6e 22 2e 0a 2a 2a 20 54 68  ite.h.in"..** Th
0530: 65 20 6d 61 6b 65 66 69 6c 65 20 6d 61 6b 65 73  e makefile makes
0540: 20 73 6f 6d 65 20 6d 69 6e 6f 72 20 63 68 61 6e   some minor chan
0550: 67 65 73 20 74 6f 20 74 68 69 73 20 66 69 6c 65  ges to this file
0560: 20 28 73 75 63 68 20 61 73 20 69 6e 73 65 72 74   (such as insert
0570: 69 6e 67 0a 2a 2a 20 74 68 65 20 76 65 72 73 69  ing.** the versi
0580: 6f 6e 20 6e 75 6d 62 65 72 29 20 61 6e 64 20 63  on number) and c
0590: 68 61 6e 67 65 73 20 69 74 73 20 6e 61 6d 65 20  hanges its name 
05a0: 74 6f 20 22 73 71 6c 69 74 65 33 2e 68 22 20 61  to "sqlite3.h" a
05b0: 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74 68 65  s.** part of the
05c0: 20 62 75 69 6c 64 20 70 72 6f 63 65 73 73 2e 0a   build process..
05d0: 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 53 51 4c 49  */.#ifndef _SQLI
05e0: 54 45 33 5f 48 5f 0a 23 64 65 66 69 6e 65 20 5f  TE3_H_.#define _
05f0: 53 51 4c 49 54 45 33 5f 48 5f 0a 23 69 6e 63 6c  SQLITE3_H_.#incl
0600: 75 64 65 20 3c 73 74 64 61 72 67 2e 68 3e 20 20  ude <stdarg.h>  
0610: 20 20 20 2f 2a 20 4e 65 65 64 65 64 20 66 6f 72     /* Needed for
0620: 20 74 68 65 20 64 65 66 69 6e 69 74 69 6f 6e 20   the definition 
0630: 6f 66 20 76 61 5f 6c 69 73 74 20 2a 2f 0a 0a 2f  of va_list */../
0640: 2a 0a 2a 2a 20 4d 61 6b 65 20 73 75 72 65 20 77  *.** Make sure w
0650: 65 20 63 61 6e 20 63 61 6c 6c 20 74 68 69 73 20  e can call this 
0660: 73 74 75 66 66 20 66 72 6f 6d 20 43 2b 2b 2e 0a  stuff from C++..
0670: 2a 2f 0a 23 69 66 64 65 66 20 5f 5f 63 70 6c 75  */.#ifdef __cplu
0680: 73 70 6c 75 73 0a 65 78 74 65 72 6e 20 22 43 22  splus.extern "C"
0690: 20 7b 0a 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a   {.#endif.../*.*
06a0: 2a 20 41 64 64 20 74 68 65 20 61 62 69 6c 69 74  * Add the abilit
06b0: 79 20 74 6f 20 6f 76 65 72 72 69 64 65 20 27 65  y to override 'e
06c0: 78 74 65 72 6e 27 0a 2a 2f 0a 23 69 66 6e 64 65  xtern'.*/.#ifnde
06d0: 66 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 0a  f SQLITE_EXTERN.
06e0: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
06f0: 45 58 54 45 52 4e 20 65 78 74 65 72 6e 0a 23 65  EXTERN extern.#e
0700: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 73  ndif../*.** Thes
0710: 65 20 6e 6f 2d 6f 70 20 6d 61 63 72 6f 73 20 61  e no-op macros a
0720: 72 65 20 75 73 65 64 20 69 6e 20 66 72 6f 6e 74  re used in front
0730: 20 6f 66 20 69 6e 74 65 72 66 61 63 65 73 20 74   of interfaces t
0740: 6f 20 6d 61 72 6b 20 74 68 6f 73 65 0a 2a 2a 20  o mark those.** 
0750: 69 6e 74 65 72 66 61 63 65 73 20 61 73 20 65 69  interfaces as ei
0760: 74 68 65 72 20 64 65 70 72 65 63 61 74 65 64 20  ther deprecated 
0770: 6f 72 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e  or experimental.
0780: 20 20 4e 65 77 20 61 70 70 6c 69 63 61 74 69 6f    New applicatio
0790: 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f 74  ns.** should not
07a0: 20 75 73 65 20 64 65 70 72 65 63 61 74 65 64 20   use deprecated 
07b0: 69 6e 74 65 72 66 61 63 65 73 20 2d 20 74 68 65  interfaces - the
07c0: 79 20 61 72 65 20 73 75 70 70 6f 72 74 20 66 6f  y are support fo
07d0: 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63  r backwards.** c
07e0: 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c  ompatibility onl
07f0: 79 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 20  y.  Application 
0800: 77 72 69 74 65 72 73 20 73 68 6f 75 6c 64 20 62  writers should b
0810: 65 20 61 77 61 72 65 20 74 68 61 74 0a 2a 2a 20  e aware that.** 
0820: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
0830: 65 72 66 61 63 65 73 20 61 72 65 20 73 75 62 6a  erfaces are subj
0840: 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 69 6e  ect to change in
0850: 20 70 6f 69 6e 74 20 72 65 6c 65 61 73 65 73 2e   point releases.
0860: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 6d 61 63  .**.** These mac
0870: 72 6f 73 20 75 73 65 64 20 74 6f 20 72 65 73 6f  ros used to reso
0880: 6c 76 65 20 74 6f 20 76 61 72 69 6f 75 73 20 6b  lve to various k
0890: 69 6e 64 73 20 6f 66 20 63 6f 6d 70 69 6c 65 72  inds of compiler
08a0: 20 6d 61 67 69 63 20 74 68 61 74 0a 2a 2a 20 77   magic that.** w
08b0: 6f 75 6c 64 20 67 65 6e 65 72 61 74 65 20 77 61  ould generate wa
08c0: 72 6e 69 6e 67 20 6d 65 73 73 61 67 65 73 20 77  rning messages w
08d0: 68 65 6e 20 74 68 65 79 20 77 65 72 65 20 75 73  hen they were us
08e0: 65 64 2e 20 20 42 75 74 20 74 68 61 74 0a 2a 2a  ed.  But that.**
08f0: 20 63 6f 6d 70 69 6c 65 72 20 6d 61 67 69 63 20   compiler magic 
0900: 65 6e 64 65 64 20 75 70 20 67 65 6e 65 72 61 74  ended up generat
0910: 69 6e 67 20 73 75 63 68 20 61 20 66 6c 75 72 72  ing such a flurr
0920: 79 20 6f 66 20 62 75 67 20 72 65 70 6f 72 74 73  y of bug reports
0930: 0a 2a 2a 20 74 68 61 74 20 77 65 20 68 61 76 65  .** that we have
0940: 20 74 61 6b 65 6e 20 69 74 20 61 6c 6c 20 6f 75   taken it all ou
0950: 74 20 61 6e 64 20 67 6f 6e 65 20 62 61 63 6b 20  t and gone back 
0960: 74 6f 20 75 73 69 6e 67 20 73 69 6d 70 6c 65 0a  to using simple.
0970: 2a 2a 20 6e 6f 6f 70 20 6d 61 63 72 6f 73 2e 0a  ** noop macros..
0980: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
0990: 45 5f 44 45 50 52 45 43 41 54 45 44 0a 23 64 65  E_DEPRECATED.#de
09a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 58 50 45  fine SQLITE_EXPE
09b0: 52 49 4d 45 4e 54 41 4c 0a 0a 2f 2a 0a 2a 2a 20  RIMENTAL../*.** 
09c0: 45 6e 73 75 72 65 20 74 68 65 73 65 20 73 79 6d  Ensure these sym
09d0: 62 6f 6c 73 20 77 65 72 65 20 6e 6f 74 20 64 65  bols were not de
09e0: 66 69 6e 65 64 20 62 79 20 73 6f 6d 65 20 70 72  fined by some pr
09f0: 65 76 69 6f 75 73 20 68 65 61 64 65 72 20 66 69  evious header fi
0a00: 6c 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51  le..*/.#ifdef SQ
0a10: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 0a 23 20 75  LITE_VERSION.# u
0a20: 6e 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53  ndef SQLITE_VERS
0a30: 49 4f 4e 0a 23 65 6e 64 69 66 0a 23 69 66 64 65  ION.#endif.#ifde
0a40: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  f SQLITE_VERSION
0a50: 5f 4e 55 4d 42 45 52 0a 23 20 75 6e 64 65 66 20  _NUMBER.# undef 
0a60: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e  SQLITE_VERSION_N
0a70: 55 4d 42 45 52 0a 23 65 6e 64 69 66 0a 0a 2f 2a  UMBER.#endif../*
0a80: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
0a90: 6d 70 69 6c 65 2d 54 69 6d 65 20 4c 69 62 72 61  mpile-Time Libra
0aa0: 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65  ry Version Numbe
0ab0: 72 73 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 5b  rs.**.** ^(The [
0ac0: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 20  SQLITE_VERSION] 
0ad0: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
0ae0: 61 63 72 6f 20 69 6e 20 74 68 65 20 73 71 6c 69  acro in the sqli
0af0: 74 65 33 2e 68 20 68 65 61 64 65 72 0a 2a 2a 20  te3.h header.** 
0b00: 65 76 61 6c 75 61 74 65 73 20 74 6f 20 61 20 73  evaluates to a s
0b10: 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 20 74 68  tring literal th
0b20: 61 74 20 69 73 20 74 68 65 20 53 51 4c 69 74 65  at is the SQLite
0b30: 20 76 65 72 73 69 6f 6e 20 69 6e 20 74 68 65 0a   version in the.
0b40: 2a 2a 20 66 6f 72 6d 61 74 20 22 58 2e 59 2e 5a  ** format "X.Y.Z
0b50: 22 20 77 68 65 72 65 20 58 20 69 73 20 74 68 65  " where X is the
0b60: 20 6d 61 6a 6f 72 20 76 65 72 73 69 6f 6e 20 6e   major version n
0b70: 75 6d 62 65 72 20 28 61 6c 77 61 79 73 20 33 20  umber (always 3 
0b80: 66 6f 72 0a 2a 2a 20 53 51 4c 69 74 65 33 29 20  for.** SQLite3) 
0b90: 61 6e 64 20 59 20 69 73 20 74 68 65 20 6d 69 6e  and Y is the min
0ba0: 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65  or version numbe
0bb0: 72 20 61 6e 64 20 5a 20 69 73 20 74 68 65 20 72  r and Z is the r
0bc0: 65 6c 65 61 73 65 20 6e 75 6d 62 65 72 2e 29 5e  elease number.)^
0bd0: 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c 49 54  .** ^(The [SQLIT
0be0: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
0bf0: 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C preprocessor
0c00: 20 6d 61 63 72 6f 20 72 65 73 6f 6c 76 65 73 20   macro resolves 
0c10: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a  to an integer.**
0c20: 20 77 69 74 68 20 74 68 65 20 76 61 6c 75 65 20   with the value 
0c30: 28 58 2a 31 30 30 30 30 30 30 20 2b 20 59 2a 31  (X*1000000 + Y*1
0c40: 30 30 30 20 2b 20 5a 29 20 77 68 65 72 65 20 58  000 + Z) where X
0c50: 2c 20 59 2c 20 61 6e 64 20 5a 20 61 72 65 20 74  , Y, and Z are t
0c60: 68 65 20 73 61 6d 65 0a 2a 2a 20 6e 75 6d 62 65  he same.** numbe
0c70: 72 73 20 75 73 65 64 20 69 6e 20 5b 53 51 4c 49  rs used in [SQLI
0c80: 54 45 5f 56 45 52 53 49 4f 4e 5d 2e 29 5e 0a 2a  TE_VERSION].)^.*
0c90: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 56 45 52  * The SQLITE_VER
0ca0: 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 66 6f 72 20  SION_NUMBER for 
0cb0: 61 6e 79 20 67 69 76 65 6e 20 72 65 6c 65 61 73  any given releas
0cc0: 65 20 6f 66 20 53 51 4c 69 74 65 20 77 69 6c 6c  e of SQLite will
0cd0: 20 61 6c 73 6f 0a 2a 2a 20 62 65 20 6c 61 72 67   also.** be larg
0ce0: 65 72 20 74 68 61 6e 20 74 68 65 20 72 65 6c 65  er than the rele
0cf0: 61 73 65 20 66 72 6f 6d 20 77 68 69 63 68 20 69  ase from which i
0d00: 74 20 69 73 20 64 65 72 69 76 65 64 2e 20 20 45  t is derived.  E
0d10: 69 74 68 65 72 20 59 20 77 69 6c 6c 0a 2a 2a 20  ither Y will.** 
0d20: 62 65 20 68 65 6c 64 20 63 6f 6e 73 74 61 6e 74  be held constant
0d30: 20 61 6e 64 20 5a 20 77 69 6c 6c 20 62 65 20 69   and Z will be i
0d40: 6e 63 72 65 6d 65 6e 74 65 64 20 6f 72 20 65 6c  ncremented or el
0d50: 73 65 20 59 20 77 69 6c 6c 20 62 65 20 69 6e 63  se Y will be inc
0d60: 72 65 6d 65 6e 74 65 64 0a 2a 2a 20 61 6e 64 20  remented.** and 
0d70: 5a 20 77 69 6c 6c 20 62 65 20 72 65 73 65 74 20  Z will be reset 
0d80: 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53  to zero..**.** S
0d90: 69 6e 63 65 20 76 65 72 73 69 6f 6e 20 33 2e 36  ince version 3.6
0da0: 2e 31 38 2c 20 53 51 4c 69 74 65 20 73 6f 75 72  .18, SQLite sour
0db0: 63 65 20 63 6f 64 65 20 68 61 73 20 62 65 65 6e  ce code has been
0dc0: 20 73 74 6f 72 65 64 20 69 6e 20 74 68 65 0a 2a   stored in the.*
0dd0: 2a 20 3c 61 20 68 72 65 66 3d 22 68 74 74 70 3a  * <a href="http:
0de0: 2f 2f 77 77 77 2e 66 6f 73 73 69 6c 2d 73 63 6d  //www.fossil-scm
0df0: 2e 6f 72 67 2f 22 3e 46 6f 73 73 69 6c 20 63 6f  .org/">Fossil co
0e00: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61  nfiguration mana
0e10: 67 65 6d 65 6e 74 0a 2a 2a 20 73 79 73 74 65 6d  gement.** system
0e20: 3c 2f 61 3e 2e 20 20 5e 54 68 65 20 53 51 4c 49  </a>.  ^The SQLI
0e30: 54 45 5f 53 4f 55 52 43 45 5f 49 44 20 6d 61 63  TE_SOURCE_ID mac
0e40: 72 6f 20 65 76 61 6c 75 61 74 65 73 20 74 6f 0a  ro evaluates to.
0e50: 2a 2a 20 61 20 73 74 72 69 6e 67 20 77 68 69 63  ** a string whic
0e60: 68 20 69 64 65 6e 74 69 66 69 65 73 20 61 20 70  h identifies a p
0e70: 61 72 74 69 63 75 6c 61 72 20 63 68 65 63 6b 2d  articular check-
0e80: 69 6e 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20  in of SQLite.** 
0e90: 77 69 74 68 69 6e 20 69 74 73 20 63 6f 6e 66 69  within its confi
0ea0: 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d  guration managem
0eb0: 65 6e 74 20 73 79 73 74 65 6d 2e 20 20 5e 54 68  ent system.  ^Th
0ec0: 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f  e SQLITE_SOURCE_
0ed0: 49 44 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e  ID.** string con
0ee0: 74 61 69 6e 73 20 74 68 65 20 64 61 74 65 20 61  tains the date a
0ef0: 6e 64 20 74 69 6d 65 20 6f 66 20 74 68 65 20 63  nd time of the c
0f00: 68 65 63 6b 2d 69 6e 20 28 55 54 43 29 20 61 6e  heck-in (UTC) an
0f10: 64 20 61 6e 20 53 48 41 31 0a 2a 2a 20 68 61 73  d an SHA1.** has
0f20: 68 20 6f 66 20 74 68 65 20 65 6e 74 69 72 65 20  h of the entire 
0f30: 73 6f 75 72 63 65 20 74 72 65 65 2e 0a 2a 2a 0a  source tree..**.
0f40: 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
0f50: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
0f60: 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
0f70: 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62  _libversion_numb
0f80: 65 72 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  er()], [sqlite3_
0f90: 73 6f 75 72 63 65 69 64 28 29 5d 2c 0a 2a 2a 20  sourceid()],.** 
0fa0: 5b 73 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28  [sqlite_version(
0fb0: 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73  )] and [sqlite_s
0fc0: 6f 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a  ource_id()]..*/.
0fd0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56  #define SQLITE_V
0fe0: 45 52 53 49 4f 4e 20 20 20 20 20 20 20 20 22 2d  ERSION        "-
0ff0: 2d 56 45 52 53 2d 2d 22 0a 23 64 65 66 69 6e 65  -VERS--".#define
1000: 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f   SQLITE_VERSION_
1010: 4e 55 4d 42 45 52 20 2d 2d 56 45 52 53 49 4f 4e  NUMBER --VERSION
1020: 2d 4e 55 4d 42 45 52 2d 2d 0a 23 64 65 66 69 6e  -NUMBER--.#defin
1030: 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f  e SQLITE_SOURCE_
1040: 49 44 20 20 20 20 20 20 22 2d 2d 53 4f 55 52 43  ID      "--SOURC
1050: 45 2d 49 44 2d 2d 22 0a 0a 2f 2a 0a 2a 2a 20 43  E-ID--"../*.** C
1060: 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d  API3REF: Run-Tim
1070: 65 20 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f  e Library Versio
1080: 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 20 4b 45 59  n Numbers.** KEY
1090: 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76  WORDS: sqlite3_v
10a0: 65 72 73 69 6f 6e 2c 20 73 71 6c 69 74 65 33 5f  ersion, sqlite3_
10b0: 73 6f 75 72 63 65 69 64 0a 2a 2a 0a 2a 2a 20 54  sourceid.**.** T
10c0: 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20  hese interfaces 
10d0: 70 72 6f 76 69 64 65 20 74 68 65 20 73 61 6d 65  provide the same
10e0: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20   information as 
10f0: 74 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 53  the [SQLITE_VERS
1100: 49 4f 4e 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  ION],.** [SQLITE
1110: 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d  _VERSION_NUMBER]
1120: 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 53 4f  , and [SQLITE_SO
1130: 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65 70 72  URCE_ID] C prepr
1140: 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 73 0a 2a  ocessor macros.*
1150: 2a 20 62 75 74 20 61 72 65 20 61 73 73 6f 63 69  * but are associ
1160: 61 74 65 64 20 77 69 74 68 20 74 68 65 20 6c 69  ated with the li
1170: 62 72 61 72 79 20 69 6e 73 74 65 61 64 20 6f 66  brary instead of
1180: 20 74 68 65 20 68 65 61 64 65 72 20 66 69 6c 65   the header file
1190: 2e 20 20 5e 28 43 61 75 74 69 6f 75 73 0a 2a 2a  .  ^(Cautious.**
11a0: 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67   programmers mig
11b0: 68 74 20 69 6e 63 6c 75 64 65 20 61 73 73 65 72  ht include asser
11c0: 74 28 29 20 73 74 61 74 65 6d 65 6e 74 73 20 69  t() statements i
11d0: 6e 20 74 68 65 69 72 20 61 70 70 6c 69 63 61 74  n their applicat
11e0: 69 6f 6e 20 74 6f 0a 2a 2a 20 76 65 72 69 66 79  ion to.** verify
11f0: 20 74 68 61 74 20 76 61 6c 75 65 73 20 72 65 74   that values ret
1200: 75 72 6e 65 64 20 62 79 20 74 68 65 73 65 20 69  urned by these i
1210: 6e 74 65 72 66 61 63 65 73 20 6d 61 74 63 68 20  nterfaces match 
1220: 74 68 65 20 6d 61 63 72 6f 73 20 69 6e 0a 2a 2a  the macros in.**
1230: 20 74 68 65 20 68 65 61 64 65 72 2c 20 61 6e 64   the header, and
1240: 20 74 68 75 73 20 69 6e 73 75 72 65 20 74 68 61   thus insure tha
1250: 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  t the applicatio
1260: 6e 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64  n is.** compiled
1270: 20 77 69 74 68 20 6d 61 74 63 68 69 6e 67 20 6c   with matching l
1280: 69 62 72 61 72 79 20 61 6e 64 20 68 65 61 64 65  ibrary and heade
1290: 72 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 3c  r files..**.** <
12a0: 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
12b0: 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 71 6c 69  .** assert( sqli
12c0: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e  te3_libversion_n
12d0: 75 6d 62 65 72 28 29 3d 3d 53 51 4c 49 54 45 5f  umber()==SQLITE_
12e0: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 29  VERSION_NUMBER )
12f0: 3b 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 74 72  ;.** assert( str
1300: 63 6d 70 28 73 71 6c 69 74 65 33 5f 73 6f 75 72  cmp(sqlite3_sour
1310: 63 65 69 64 28 29 2c 53 51 4c 49 54 45 5f 53 4f  ceid(),SQLITE_SO
1320: 55 52 43 45 5f 49 44 29 3d 3d 30 20 29 3b 0a 2a  URCE_ID)==0 );.*
1330: 2a 20 61 73 73 65 72 74 28 20 73 74 72 63 6d 70  * assert( strcmp
1340: 28 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73  (sqlite3_libvers
1350: 69 6f 6e 28 29 2c 53 51 4c 49 54 45 5f 56 45 52  ion(),SQLITE_VER
1360: 53 49 4f 4e 29 3d 3d 30 20 29 3b 0a 2a 2a 20 3c  SION)==0 );.** <
1370: 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
1380: 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  e>)^.**.** ^The 
1390: 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b  sqlite3_version[
13a0: 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e  ] string constan
13b0: 74 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 74  t contains the t
13c0: 65 78 74 20 6f 66 20 5b 53 51 4c 49 54 45 5f 56  ext of [SQLITE_V
13d0: 45 52 53 49 4f 4e 5d 0a 2a 2a 20 6d 61 63 72 6f  ERSION].** macro
13e0: 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
13f0: 6c 69 62 76 65 72 73 69 6f 6e 28 29 20 66 75 6e  libversion() fun
1400: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 20  ction returns a 
1410: 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a  pointer to the.*
1420: 2a 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  * to the sqlite3
1430: 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e  _version[] strin
1440: 67 20 63 6f 6e 73 74 61 6e 74 2e 20 20 54 68 65  g constant.  The
1450: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73   sqlite3_libvers
1460: 69 6f 6e 28 29 0a 2a 2a 20 66 75 6e 63 74 69 6f  ion().** functio
1470: 6e 20 69 73 20 70 72 6f 76 69 64 65 64 20 66 6f  n is provided fo
1480: 72 20 75 73 65 20 69 6e 20 44 4c 4c 73 20 73 69  r use in DLLs si
1490: 6e 63 65 20 44 4c 4c 20 75 73 65 72 73 20 75 73  nce DLL users us
14a0: 75 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 68 61 76  ually do not hav
14b0: 65 0a 2a 2a 20 64 69 72 65 63 74 20 61 63 63 65  e.** direct acce
14c0: 73 73 20 74 6f 20 73 74 72 69 6e 67 20 63 6f 6e  ss to string con
14d0: 73 74 61 6e 74 73 20 77 69 74 68 69 6e 20 74 68  stants within th
14e0: 65 20 44 4c 4c 2e 20 20 5e 54 68 65 0a 2a 2a 20  e DLL.  ^The.** 
14f0: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
1500: 6f 6e 5f 6e 75 6d 62 65 72 28 29 20 66 75 6e 63  on_number() func
1510: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 6e 20  tion returns an 
1520: 69 6e 74 65 67 65 72 20 65 71 75 61 6c 20 74 6f  integer equal to
1530: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52 53  .** [SQLITE_VERS
1540: 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 20 20 5e 54  ION_NUMBER].  ^T
1550: 68 65 20 73 71 6c 69 74 65 33 5f 73 6f 75 72 63  he sqlite3_sourc
1560: 65 69 64 28 29 20 66 75 6e 63 74 69 6f 6e 20 72  eid() function r
1570: 65 74 75 72 6e 73 20 0a 2a 2a 20 61 20 70 6f 69  eturns .** a poi
1580: 6e 74 65 72 20 74 6f 20 61 20 73 74 72 69 6e 67  nter to a string
1590: 20 63 6f 6e 73 74 61 6e 74 20 77 68 6f 73 65 20   constant whose 
15a0: 76 61 6c 75 65 20 69 73 20 74 68 65 20 73 61 6d  value is the sam
15b0: 65 20 61 73 20 74 68 65 20 0a 2a 2a 20 5b 53 51  e as the .** [SQ
15c0: 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20  LITE_SOURCE_ID] 
15d0: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
15e0: 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  acro..**.** See 
15f0: 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 5f 76 65  also: [sqlite_ve
1600: 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71  rsion()] and [sq
1610: 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29  lite_source_id()
1620: 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54  ]..*/.SQLITE_EXT
1630: 45 52 4e 20 63 6f 6e 73 74 20 63 68 61 72 20 73  ERN const char s
1640: 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d  qlite3_version[]
1650: 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  ;.const char *sq
1660: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
1670: 28 76 6f 69 64 29 3b 0a 63 6f 6e 73 74 20 63 68  (void);.const ch
1680: 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6f 75 72  ar *sqlite3_sour
1690: 63 65 69 64 28 76 6f 69 64 29 3b 0a 69 6e 74 20  ceid(void);.int 
16a0: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
16b0: 6f 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b  on_number(void);
16c0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
16d0: 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61  : Run-Time Libra
16e0: 72 79 20 43 6f 6d 70 69 6c 61 74 69 6f 6e 20 4f  ry Compilation O
16f0: 70 74 69 6f 6e 73 20 44 69 61 67 6e 6f 73 74 69  ptions Diagnosti
1700: 63 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  cs.**.** ^The sq
1710: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
1720: 69 6f 6e 5f 75 73 65 64 28 29 20 66 75 6e 63 74  ion_used() funct
1730: 69 6f 6e 20 72 65 74 75 72 6e 73 20 30 20 6f 72  ion returns 0 or
1740: 20 31 20 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e   1 .** indicatin
1750: 67 20 77 68 65 74 68 65 72 20 74 68 65 20 73 70  g whether the sp
1760: 65 63 69 66 69 65 64 20 6f 70 74 69 6f 6e 20 77  ecified option w
1770: 61 73 20 64 65 66 69 6e 65 64 20 61 74 20 0a 2a  as defined at .*
1780: 2a 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20  * compile time. 
1790: 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 70 72   ^The SQLITE_ pr
17a0: 65 66 69 78 20 6d 61 79 20 62 65 20 6f 6d 69 74  efix may be omit
17b0: 74 65 64 20 66 72 6f 6d 20 74 68 65 20 0a 2a 2a  ted from the .**
17c0: 20 6f 70 74 69 6f 6e 20 6e 61 6d 65 20 70 61 73   option name pas
17d0: 73 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  sed to sqlite3_c
17e0: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
17f0: 64 28 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68  d().  .**.** ^Th
1800: 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c  e sqlite3_compil
1810: 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 66 75  eoption_get() fu
1820: 6e 63 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 69 74  nction allows it
1830: 65 72 61 74 69 6e 67 0a 2a 2a 20 6f 76 65 72 20  erating.** over 
1840: 74 68 65 20 6c 69 73 74 20 6f 66 20 6f 70 74 69  the list of opti
1850: 6f 6e 73 20 74 68 61 74 20 77 65 72 65 20 64 65  ons that were de
1860: 66 69 6e 65 64 20 61 74 20 63 6f 6d 70 69 6c 65  fined at compile
1870: 20 74 69 6d 65 20 62 79 0a 2a 2a 20 72 65 74 75   time by.** retu
1880: 72 6e 69 6e 67 20 74 68 65 20 4e 2d 74 68 20 63  rning the N-th c
1890: 6f 6d 70 69 6c 65 20 74 69 6d 65 20 6f 70 74 69  ompile time opti
18a0: 6f 6e 20 73 74 72 69 6e 67 2e 20 20 5e 49 66 20  on string.  ^If 
18b0: 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67  N is out of rang
18c0: 65 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  e,.** sqlite3_co
18d0: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28  mpileoption_get(
18e0: 29 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c  ) returns a NULL
18f0: 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20   pointer.  ^The 
1900: 53 51 4c 49 54 45 5f 20 0a 2a 2a 20 70 72 65 66  SQLITE_ .** pref
1910: 69 78 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72  ix is omitted fr
1920: 6f 6d 20 61 6e 79 20 73 74 72 69 6e 67 73 20 72  om any strings r
1930: 65 74 75 72 6e 65 64 20 62 79 20 0a 2a 2a 20 73  eturned by .** s
1940: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70  qlite3_compileop
1950: 74 69 6f 6e 5f 67 65 74 28 29 2e 0a 2a 2a 0a 2a  tion_get()..**.*
1960: 2a 20 5e 53 75 70 70 6f 72 74 20 66 6f 72 20 74  * ^Support for t
1970: 68 65 20 64 69 61 67 6e 6f 73 74 69 63 20 66 75  he diagnostic fu
1980: 6e 63 74 69 6f 6e 73 20 73 71 6c 69 74 65 33 5f  nctions sqlite3_
1990: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73  compileoption_us
19a0: 65 64 28 29 0a 2a 2a 20 61 6e 64 20 73 71 6c 69  ed().** and sqli
19b0: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  te3_compileoptio
19c0: 6e 5f 67 65 74 28 29 20 6d 61 79 20 62 65 20 6f  n_get() may be o
19d0: 6d 69 74 74 65 64 20 62 79 20 73 70 65 63 69 66  mitted by specif
19e0: 79 69 6e 67 20 74 68 65 20 0a 2a 2a 20 5b 53 51  ying the .** [SQ
19f0: 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c  LITE_OMIT_COMPIL
1a00: 45 4f 50 54 49 4f 4e 5f 44 49 41 47 53 5d 20 6f  EOPTION_DIAGS] o
1a10: 70 74 69 6f 6e 20 61 74 20 63 6f 6d 70 69 6c 65  ption at compile
1a20: 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65   time..**.** See
1a30: 20 61 6c 73 6f 3a 20 53 51 4c 20 66 75 6e 63 74   also: SQL funct
1a40: 69 6f 6e 73 20 5b 73 71 6c 69 74 65 5f 63 6f 6d  ions [sqlite_com
1a50: 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28  pileoption_used(
1a60: 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  )] and.** [sqlit
1a70: 65 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f  e_compileoption_
1a80: 67 65 74 28 29 5d 20 61 6e 64 20 74 68 65 20 5b  get()] and the [
1a90: 63 6f 6d 70 69 6c 65 5f 6f 70 74 69 6f 6e 73 20  compile_options 
1aa0: 70 72 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 69 66 6e  pragma]..*/.#ifn
1ab0: 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  def SQLITE_OMIT_
1ac0: 43 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49  COMPILEOPTION_DI
1ad0: 41 47 53 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  AGS.int sqlite3_
1ae0: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73  compileoption_us
1af0: 65 64 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  ed(const char *z
1b00: 4f 70 74 4e 61 6d 65 29 3b 0a 63 6f 6e 73 74 20  OptName);.const 
1b10: 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
1b20: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28  mpileoption_get(
1b30: 69 6e 74 20 4e 29 3b 0a 23 65 6e 64 69 66 0a 0a  int N);.#endif..
1b40: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1b50: 54 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 54  Test To See If T
1b60: 68 65 20 4c 69 62 72 61 72 79 20 49 73 20 54 68  he Library Is Th
1b70: 72 65 61 64 73 61 66 65 0a 2a 2a 0a 2a 2a 20 5e  readsafe.**.** ^
1b80: 54 68 65 20 73 71 6c 69 74 65 33 5f 74 68 72 65  The sqlite3_thre
1b90: 61 64 73 61 66 65 28 29 20 66 75 6e 63 74 69 6f  adsafe() functio
1ba0: 6e 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 69  n returns zero i
1bb0: 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a  f and only if.**
1bc0: 20 53 51 4c 69 74 65 20 77 61 73 20 63 6f 6d 70   SQLite was comp
1bd0: 69 6c 65 64 20 77 69 74 68 20 6d 75 74 65 78 69  iled with mutexi
1be0: 6e 67 20 63 6f 64 65 20 6f 6d 69 74 74 65 64 20  ng code omitted 
1bf0: 64 75 65 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 53  due to the.** [S
1c00: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
1c10: 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
1c20: 70 74 69 6f 6e 20 62 65 69 6e 67 20 73 65 74 20  ption being set 
1c30: 74 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  to 0..**.** SQLi
1c40: 74 65 20 63 61 6e 20 62 65 20 63 6f 6d 70 69 6c  te can be compil
1c50: 65 64 20 77 69 74 68 20 6f 72 20 77 69 74 68 6f  ed with or witho
1c60: 75 74 20 6d 75 74 65 78 65 73 2e 20 20 57 68 65  ut mutexes.  Whe
1c70: 6e 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  n.** the [SQLITE
1c80: 5f 54 48 52 45 41 44 53 41 46 45 5d 20 43 20 70  _THREADSAFE] C p
1c90: 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  reprocessor macr
1ca0: 6f 20 69 73 20 31 20 6f 72 20 32 2c 20 6d 75 74  o is 1 or 2, mut
1cb0: 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62  exes.** are enab
1cc0: 6c 65 64 20 61 6e 64 20 53 51 4c 69 74 65 20 69  led and SQLite i
1cd0: 73 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 57  s threadsafe.  W
1ce0: 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  hen the.** [SQLI
1cf0: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d  TE_THREADSAFE] m
1d00: 61 63 72 6f 20 69 73 20 30 2c 20 0a 2a 2a 20 74  acro is 0, .** t
1d10: 68 65 20 6d 75 74 65 78 65 73 20 61 72 65 20 6f  he mutexes are o
1d20: 6d 69 74 74 65 64 2e 20 20 57 69 74 68 6f 75 74  mitted.  Without
1d30: 20 74 68 65 20 6d 75 74 65 78 65 73 2c 20 69 74   the mutexes, it
1d40: 20 69 73 20 6e 6f 74 20 73 61 66 65 0a 2a 2a 20   is not safe.** 
1d50: 74 6f 20 75 73 65 20 53 51 4c 69 74 65 20 63 6f  to use SQLite co
1d60: 6e 63 75 72 72 65 6e 74 6c 79 20 66 72 6f 6d 20  ncurrently from 
1d70: 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 74 68  more than one th
1d80: 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e 61 62  read..**.** Enab
1d90: 6c 69 6e 67 20 6d 75 74 65 78 65 73 20 69 6e 63  ling mutexes inc
1da0: 75 72 73 20 61 20 6d 65 61 73 75 72 61 62 6c 65  urs a measurable
1db0: 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 70 65 6e   performance pen
1dc0: 61 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69 66 20 73  alty..** So if s
1dd0: 70 65 65 64 20 69 73 20 6f 66 20 75 74 6d 6f 73  peed is of utmos
1de0: 74 20 69 6d 70 6f 72 74 61 6e 63 65 2c 20 69 74  t importance, it
1df0: 20 6d 61 6b 65 73 20 73 65 6e 73 65 20 74 6f 20   makes sense to 
1e00: 64 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 6d  disable.** the m
1e10: 75 74 65 78 65 73 2e 20 20 42 75 74 20 66 6f 72  utexes.  But for
1e20: 20 6d 61 78 69 6d 75 6d 20 73 61 66 65 74 79 2c   maximum safety,
1e30: 20 6d 75 74 65 78 65 73 20 73 68 6f 75 6c 64 20   mutexes should 
1e40: 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 5e  be enabled..** ^
1e50: 54 68 65 20 64 65 66 61 75 6c 74 20 62 65 68 61  The default beha
1e60: 76 69 6f 72 20 69 73 20 66 6f 72 20 6d 75 74 65  vior is for mute
1e70: 78 65 73 20 74 6f 20 62 65 20 65 6e 61 62 6c 65  xes to be enable
1e80: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e  d..**.** This in
1e90: 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75  terface can be u
1ea0: 73 65 64 20 62 79 20 61 6e 20 61 70 70 6c 69 63  sed by an applic
1eb0: 61 74 69 6f 6e 20 74 6f 20 6d 61 6b 65 20 73 75  ation to make su
1ec0: 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 76  re that the.** v
1ed0: 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65  ersion of SQLite
1ee0: 20 74 68 61 74 20 69 74 20 69 73 20 6c 69 6e 6b   that it is link
1ef0: 69 6e 67 20 61 67 61 69 6e 73 74 20 77 61 73 20  ing against was 
1f00: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
1f10: 20 74 68 65 20 64 65 73 69 72 65 64 20 73 65 74   the desired set
1f20: 74 69 6e 67 20 6f 66 20 74 68 65 20 5b 53 51 4c  ting of the [SQL
1f30: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20  ITE_THREADSAFE] 
1f40: 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  macro..**.** Thi
1f50: 73 20 69 6e 74 65 72 66 61 63 65 20 6f 6e 6c 79  s interface only
1f60: 20 72 65 70 6f 72 74 73 20 6f 6e 20 74 68 65 20   reports on the 
1f70: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 75 74  compile-time mut
1f80: 65 78 20 73 65 74 74 69 6e 67 0a 2a 2a 20 6f 66  ex setting.** of
1f90: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
1fa0: 45 41 44 53 41 46 45 5d 20 66 6c 61 67 2e 20 20  EADSAFE] flag.  
1fb0: 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
1fc0: 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 53 51  piled with.** SQ
1fd0: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
1fe0: 31 20 6f 72 20 3d 32 20 74 68 65 6e 20 6d 75 74  1 or =2 then mut
1ff0: 65 78 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64  exes are enabled
2000: 20 62 79 20 64 65 66 61 75 6c 74 20 62 75 74 0a   by default but.
2010: 2a 2a 20 63 61 6e 20 62 65 20 66 75 6c 6c 79 20  ** can be fully 
2020: 6f 72 20 70 61 72 74 69 61 6c 6c 79 20 64 69 73  or partially dis
2030: 61 62 6c 65 64 20 75 73 69 6e 67 20 61 20 63 61  abled using a ca
2040: 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ll to [sqlite3_c
2050: 6f 6e 66 69 67 28 29 5d 0a 2a 2a 20 77 69 74 68  onfig()].** with
2060: 20 74 68 65 20 76 65 72 62 73 20 5b 53 51 4c 49   the verbs [SQLI
2070: 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
2080: 54 48 52 45 41 44 5d 2c 20 5b 53 51 4c 49 54 45  THREAD], [SQLITE
2090: 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
20a0: 45 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c  EAD],.** or [SQL
20b0: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
20c0: 5d 2e 20 20 5e 28 54 68 65 20 72 65 74 75 72 6e  ].  ^(The return
20d0: 20 76 61 6c 75 65 20 6f 66 20 74 68 65 0a 2a 2a   value of the.**
20e0: 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73   sqlite3_threads
20f0: 61 66 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 73  afe() function s
2100: 68 6f 77 73 20 6f 6e 6c 79 20 74 68 65 20 63 6f  hows only the co
2110: 6d 70 69 6c 65 2d 74 69 6d 65 20 73 65 74 74 69  mpile-time setti
2120: 6e 67 20 6f 66 0a 2a 2a 20 74 68 72 65 61 64 20  ng of.** thread 
2130: 73 61 66 65 74 79 2c 20 6e 6f 74 20 61 6e 79 20  safety, not any 
2140: 72 75 6e 2d 74 69 6d 65 20 63 68 61 6e 67 65 73  run-time changes
2150: 20 74 6f 20 74 68 61 74 20 73 65 74 74 69 6e 67   to that setting
2160: 20 6d 61 64 65 20 62 79 0a 2a 2a 20 73 71 6c 69   made by.** sqli
2170: 74 65 33 5f 63 6f 6e 66 69 67 28 29 2e 20 49 6e  te3_config(). In
2180: 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
2190: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66  e return value f
21a0: 72 6f 6d 20 73 71 6c 69 74 65 33 5f 74 68 72 65  rom sqlite3_thre
21b0: 61 64 73 61 66 65 28 29 0a 2a 2a 20 69 73 20 75  adsafe().** is u
21c0: 6e 63 68 61 6e 67 65 64 20 62 79 20 63 61 6c 6c  nchanged by call
21d0: 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e  s to sqlite3_con
21e0: 66 69 67 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53  fig().)^.**.** S
21f0: 65 65 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e  ee the [threadin
2200: 67 20 6d 6f 64 65 5d 20 64 6f 63 75 6d 65 6e 74  g mode] document
2210: 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69  ation for additi
2220: 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
2230: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
2240: 5f 74 68 72 65 61 64 73 61 66 65 28 76 6f 69 64  _threadsafe(void
2250: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2260: 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e  EF: Database Con
2270: 6e 65 63 74 69 6f 6e 20 48 61 6e 64 6c 65 0a 2a  nection Handle.*
2280: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 64 61 74  * KEYWORDS: {dat
2290: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
22a0: 7d 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  } {database conn
22b0: 65 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45  ections}.**.** E
22c0: 61 63 68 20 6f 70 65 6e 20 53 51 4c 69 74 65 20  ach open SQLite 
22d0: 64 61 74 61 62 61 73 65 20 69 73 20 72 65 70 72  database is repr
22e0: 65 73 65 6e 74 65 64 20 62 79 20 61 20 70 6f 69  esented by a poi
22f0: 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61  nter to an insta
2300: 6e 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6f 70  nce of.** the op
2310: 61 71 75 65 20 73 74 72 75 63 74 75 72 65 20 6e  aque structure n
2320: 61 6d 65 64 20 22 73 71 6c 69 74 65 33 22 2e 20  amed "sqlite3". 
2330: 20 49 74 20 69 73 20 75 73 65 66 75 6c 20 74 6f   It is useful to
2340: 20 74 68 69 6e 6b 20 6f 66 20 61 6e 20 73 71 6c   think of an sql
2350: 69 74 65 33 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  ite3.** pointer 
2360: 61 73 20 61 6e 20 6f 62 6a 65 63 74 2e 20 20 54  as an object.  T
2370: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  he [sqlite3_open
2380: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
2390: 65 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20  en16()], and.** 
23a0: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
23b0: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 61  ()] interfaces a
23c0: 72 65 20 69 74 73 20 63 6f 6e 73 74 72 75 63 74  re its construct
23d0: 6f 72 73 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65  ors, and [sqlite
23e0: 33 5f 63 6c 6f 73 65 28 29 5d 0a 2a 2a 20 61 6e  3_close()].** an
23f0: 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  d [sqlite3_close
2400: 5f 76 32 28 29 5d 20 61 72 65 20 69 74 73 20 64  _v2()] are its d
2410: 65 73 74 72 75 63 74 6f 72 73 2e 20 20 54 68 65  estructors.  The
2420: 72 65 20 61 72 65 20 6d 61 6e 79 20 6f 74 68 65  re are many othe
2430: 72 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  r.** interfaces 
2440: 28 73 75 63 68 20 61 73 0a 2a 2a 20 5b 73 71 6c  (such as.** [sql
2450: 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
2460: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  )], [sqlite3_cre
2470: 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 2c  ate_function()],
2480: 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
2490: 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d  _busy_timeout()]
24a0: 20 74 6f 20 6e 61 6d 65 20 62 75 74 20 74 68 72   to name but thr
24b0: 65 65 29 20 74 68 61 74 20 61 72 65 20 6d 65 74  ee) that are met
24c0: 68 6f 64 73 20 6f 6e 20 61 6e 0a 2a 2a 20 73 71  hods on an.** sq
24d0: 6c 69 74 65 33 20 6f 62 6a 65 63 74 2e 0a 2a 2f  lite3 object..*/
24e0: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
24f0: 73 71 6c 69 74 65 33 20 73 71 6c 69 74 65 33 3b  sqlite3 sqlite3;
2500: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2510: 3a 20 36 34 2d 42 69 74 20 49 6e 74 65 67 65 72  : 64-Bit Integer
2520: 20 54 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52   Types.** KEYWOR
2530: 44 53 3a 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  DS: sqlite_int64
2540: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 0a 2a   sqlite_uint64.*
2550: 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65  *.** Because the
2560: 72 65 20 69 73 20 6e 6f 20 63 72 6f 73 73 2d 70  re is no cross-p
2570: 6c 61 74 66 6f 72 6d 20 77 61 79 20 74 6f 20 73  latform way to s
2580: 70 65 63 69 66 79 20 36 34 2d 62 69 74 20 69 6e  pecify 64-bit in
2590: 74 65 67 65 72 20 74 79 70 65 73 0a 2a 2a 20 53  teger types.** S
25a0: 51 4c 69 74 65 20 69 6e 63 6c 75 64 65 73 20 74  QLite includes t
25b0: 79 70 65 64 65 66 73 20 66 6f 72 20 36 34 2d 62  ypedefs for 64-b
25c0: 69 74 20 73 69 67 6e 65 64 20 61 6e 64 20 75 6e  it signed and un
25d0: 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 73 2e  signed integers.
25e0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
25f0: 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c  e3_int64 and sql
2600: 69 74 65 33 5f 75 69 6e 74 36 34 20 61 72 65 20  ite3_uint64 are 
2610: 74 68 65 20 70 72 65 66 65 72 72 65 64 20 74 79  the preferred ty
2620: 70 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 2e 0a  pe definitions..
2630: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 5f 69 6e  ** The sqlite_in
2640: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 75  t64 and sqlite_u
2650: 69 6e 74 36 34 20 74 79 70 65 73 20 61 72 65 20  int64 types are 
2660: 73 75 70 70 6f 72 74 65 64 20 66 6f 72 20 62 61  supported for ba
2670: 63 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d 70 61  ckwards.** compa
2680: 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e 0a 2a  tibility only..*
2690: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
26a0: 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69  3_int64 and sqli
26b0: 74 65 5f 69 6e 74 36 34 20 74 79 70 65 73 20 63  te_int64 types c
26c0: 61 6e 20 73 74 6f 72 65 20 69 6e 74 65 67 65 72  an store integer
26d0: 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65   values.** betwe
26e0: 65 6e 20 2d 39 32 32 33 33 37 32 30 33 36 38 35  en -922337203685
26f0: 34 37 37 35 38 30 38 20 61 6e 64 20 2b 39 32 32  4775808 and +922
2700: 33 33 37 32 30 33 36 38 35 34 37 37 35 38 30 37  3372036854775807
2710: 20 69 6e 63 6c 75 73 69 76 65 2e 20 20 5e 54 68   inclusive.  ^Th
2720: 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 69 6e  e.** sqlite3_uin
2730: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 75  t64 and sqlite_u
2740: 69 6e 74 36 34 20 74 79 70 65 73 20 63 61 6e 20  int64 types can 
2750: 73 74 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61  store integer va
2760: 6c 75 65 73 20 0a 2a 2a 20 62 65 74 77 65 65 6e  lues .** between
2770: 20 30 20 61 6e 64 20 2b 31 38 34 34 36 37 34 34   0 and +18446744
2780: 30 37 33 37 30 39 35 35 31 36 31 35 20 69 6e 63  073709551615 inc
2790: 6c 75 73 69 76 65 2e 0a 2a 2f 0a 23 69 66 64 65  lusive..*/.#ifde
27a0: 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54  f SQLITE_INT64_T
27b0: 59 50 45 0a 20 20 74 79 70 65 64 65 66 20 53 51  YPE.  typedef SQ
27c0: 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20  LITE_INT64_TYPE 
27d0: 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20  sqlite_int64;.  
27e0: 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64  typedef unsigned
27f0: 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59   SQLITE_INT64_TY
2800: 50 45 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  PE sqlite_uint64
2810: 3b 0a 23 65 6c 69 66 20 64 65 66 69 6e 65 64 28  ;.#elif defined(
2820: 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64 65 66  _MSC_VER) || def
2830: 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f  ined(__BORLANDC_
2840: 5f 29 0a 20 20 74 79 70 65 64 65 66 20 5f 5f 69  _).  typedef __i
2850: 6e 74 36 34 20 73 71 6c 69 74 65 5f 69 6e 74 36  nt64 sqlite_int6
2860: 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73  4;.  typedef uns
2870: 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20 73 71  igned __int64 sq
2880: 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c  lite_uint64;.#el
2890: 73 65 0a 20 20 74 79 70 65 64 65 66 20 6c 6f 6e  se.  typedef lon
28a0: 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74  g long int sqlit
28b0: 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64  e_int64;.  typed
28c0: 65 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f 6e 67  ef unsigned long
28d0: 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65   long int sqlite
28e0: 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69 66 0a  _uint64;.#endif.
28f0: 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f 69  typedef sqlite_i
2900: 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 69 6e 74  nt64 sqlite3_int
2910: 36 34 3b 0a 74 79 70 65 64 65 66 20 73 71 6c 69  64;.typedef sqli
2920: 74 65 5f 75 69 6e 74 36 34 20 73 71 6c 69 74 65  te_uint64 sqlite
2930: 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a  3_uint64;../*.**
2940: 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20 66 6f   If compiling fo
2950: 72 20 61 20 70 72 6f 63 65 73 73 6f 72 20 74 68  r a processor th
2960: 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74 69 6e  at lacks floatin
2970: 67 20 70 6f 69 6e 74 20 73 75 70 70 6f 72 74 2c  g point support,
2980: 0a 2a 2a 20 73 75 62 73 74 69 74 75 74 65 20 69  .** substitute i
2990: 6e 74 65 67 65 72 20 66 6f 72 20 66 6c 6f 61 74  nteger for float
29a0: 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69  ing-point..*/.#i
29b0: 66 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54  fdef SQLITE_OMIT
29c0: 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a  _FLOATING_POINT.
29d0: 23 20 64 65 66 69 6e 65 20 64 6f 75 62 6c 65 20  # define double 
29e0: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a 23 65  sqlite3_int64.#e
29f0: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ndif../*.** CAPI
2a00: 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20 41 20  3REF: Closing A 
2a10: 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
2a20: 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ion.**.** ^The s
2a30: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 61  qlite3_close() a
2a40: 6e 64 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  nd sqlite3_close
2a50: 5f 76 32 28 29 20 72 6f 75 74 69 6e 65 73 20 61  _v2() routines a
2a60: 72 65 20 64 65 73 74 72 75 63 74 6f 72 73 0a 2a  re destructors.*
2a70: 2a 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74  * for the [sqlit
2a80: 65 33 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e  e3] object..** ^
2a90: 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  Calls to sqlite3
2aa0: 5f 63 6c 6f 73 65 28 29 20 61 6e 64 20 73 71 6c  _close() and sql
2ab0: 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20  ite3_close_v2() 
2ac0: 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b  return SQLITE_OK
2ad0: 20 69 66 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69   if.** the [sqli
2ae0: 74 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 73  te3] object is s
2af0: 75 63 63 65 73 73 66 75 6c 6c 79 20 64 65 73 74  uccessfully dest
2b00: 72 6f 79 65 64 20 61 6e 64 20 61 6c 6c 20 61 73  royed and all as
2b10: 73 6f 63 69 61 74 65 64 0a 2a 2a 20 72 65 73 6f  sociated.** reso
2b20: 75 72 63 65 73 20 61 72 65 20 64 65 61 6c 6c 6f  urces are deallo
2b30: 63 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  cated..**.** ^If
2b40: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
2b50: 6e 6e 65 63 74 69 6f 6e 20 69 73 20 61 73 73 6f  nnection is asso
2b60: 63 69 61 74 65 64 20 77 69 74 68 20 75 6e 66 69  ciated with unfi
2b70: 6e 61 6c 69 7a 65 64 20 70 72 65 70 61 72 65 64  nalized prepared
2b80: 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 20 6f  .** statements o
2b90: 72 20 75 6e 66 69 6e 69 73 68 65 64 20 73 71 6c  r unfinished sql
2ba0: 69 74 65 33 5f 62 61 63 6b 75 70 20 6f 62 6a 65  ite3_backup obje
2bb0: 63 74 73 20 74 68 65 6e 20 73 71 6c 69 74 65 33  cts then sqlite3
2bc0: 5f 63 6c 6f 73 65 28 29 0a 2a 2a 20 77 69 6c 6c  _close().** will
2bd0: 20 6c 65 61 76 65 20 74 68 65 20 64 61 74 61 62   leave the datab
2be0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f  ase connection o
2bf0: 70 65 6e 20 61 6e 64 20 72 65 74 75 72 6e 20 5b  pen and return [
2c00: 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a  SQLITE_BUSY]..**
2c10: 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6c 6f   ^If sqlite3_clo
2c20: 73 65 5f 76 32 28 29 20 69 73 20 63 61 6c 6c 65  se_v2() is calle
2c30: 64 20 77 69 74 68 20 75 6e 66 69 6e 61 6c 69 7a  d with unfinaliz
2c40: 65 64 20 70 72 65 70 61 72 65 64 20 73 74 61 74  ed prepared stat
2c50: 65 6d 65 6e 74 73 0a 2a 2a 20 61 6e 64 20 75 6e  ements.** and un
2c60: 66 69 6e 69 73 68 65 64 20 73 71 6c 69 74 65 33  finished sqlite3
2c70: 5f 62 61 63 6b 75 70 73 2c 20 74 68 65 6e 20 74  _backups, then t
2c80: 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
2c90: 65 63 74 69 6f 6e 20 62 65 63 6f 6d 65 73 0a 2a  ection becomes.*
2ca0: 2a 20 61 6e 20 75 6e 75 73 61 62 6c 65 20 22 7a  * an unusable "z
2cb0: 6f 6d 62 69 65 22 20 77 68 69 63 68 20 77 69 6c  ombie" which wil
2cc0: 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  l automatically 
2cd0: 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 77  be deallocated w
2ce0: 68 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 73 74 20  hen the.** last 
2cf0: 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2d00: 6e 74 20 69 73 20 66 69 6e 61 6c 69 7a 65 64 20  nt is finalized 
2d10: 6f 72 20 74 68 65 20 6c 61 73 74 20 73 71 6c 69  or the last sqli
2d20: 74 65 33 5f 62 61 63 6b 75 70 20 69 73 0a 2a 2a  te3_backup is.**
2d30: 20 66 69 6e 69 73 68 65 64 2e 20 20 54 68 65 20   finished.  The 
2d40: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32  sqlite3_close_v2
2d50: 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
2d60: 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65  intended for use
2d70: 20 77 69 74 68 0a 2a 2a 20 68 6f 73 74 20 6c 61   with.** host la
2d80: 6e 67 75 61 67 65 73 20 74 68 61 74 20 61 72 65  nguages that are
2d90: 20 67 61 72 62 61 67 65 20 63 6f 6c 6c 65 63 74   garbage collect
2da0: 65 64 2c 20 61 6e 64 20 77 68 65 72 65 20 74 68  ed, and where th
2db0: 65 20 6f 72 64 65 72 20 69 6e 20 77 68 69 63 68  e order in which
2dc0: 0a 2a 2a 20 64 65 73 74 72 75 63 74 6f 72 73 20  .** destructors 
2dd0: 61 72 65 20 63 61 6c 6c 65 64 20 69 73 20 61 72  are called is ar
2de0: 62 69 74 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 41  bitrary..**.** A
2df0: 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75  pplications shou
2e00: 6c 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ld [sqlite3_fina
2e10: 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 5d  lize | finalize]
2e20: 20 61 6c 6c 20 5b 70 72 65 70 61 72 65 64 20 73   all [prepared s
2e30: 74 61 74 65 6d 65 6e 74 73 5d 2c 0a 2a 2a 20 5b  tatements],.** [
2e40: 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f  sqlite3_blob_clo
2e50: 73 65 20 7c 20 63 6c 6f 73 65 5d 20 61 6c 6c 20  se | close] all 
2e60: 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20  [BLOB handles], 
2e70: 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  and .** [sqlite3
2e80: 5f 62 61 63 6b 75 70 5f 66 69 6e 69 73 68 20 7c  _backup_finish |
2e90: 20 66 69 6e 69 73 68 5d 20 61 6c 6c 20 5b 73 71   finish] all [sq
2ea0: 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62  lite3_backup] ob
2eb0: 6a 65 63 74 73 20 61 73 73 6f 63 69 61 74 65 64  jects associated
2ec0: 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 73 71  .** with the [sq
2ed0: 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 70 72  lite3] object pr
2ee0: 69 6f 72 20 74 6f 20 61 74 74 65 6d 70 74 69 6e  ior to attemptin
2ef0: 67 20 74 6f 20 63 6c 6f 73 65 20 74 68 65 20 6f  g to close the o
2f00: 62 6a 65 63 74 2e 20 20 5e 49 66 0a 2a 2a 20 73  bject.  ^If.** s
2f10: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28  qlite3_close_v2(
2f20: 29 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61  ) is called on a
2f30: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
2f40: 63 74 69 6f 6e 5d 20 74 68 61 74 20 73 74 69 6c  ction] that stil
2f50: 6c 20 68 61 73 0a 2a 2a 20 6f 75 74 73 74 61 6e  l has.** outstan
2f60: 64 69 6e 67 20 5b 70 72 65 70 61 72 65 64 20 73  ding [prepared s
2f70: 74 61 74 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f  tatements], [BLO
2f80: 42 20 68 61 6e 64 6c 65 73 5d 2c 20 61 6e 64 2f  B handles], and/
2f90: 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  or.** [sqlite3_b
2fa0: 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74 73 20 74  ackup] objects t
2fb0: 68 65 6e 20 69 74 20 72 65 74 75 72 6e 73 20 53  hen it returns S
2fc0: 51 4c 49 54 45 5f 4f 4b 20 62 75 74 20 74 68 65  QLITE_OK but the
2fd0: 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a   deallocation.**
2fe0: 20 6f 66 20 72 65 73 6f 75 72 63 65 73 20 69 73   of resources is
2ff0: 20 64 65 66 65 72 72 65 64 20 75 6e 74 69 6c 20   deferred until 
3000: 61 6c 6c 20 5b 70 72 65 70 61 72 65 64 20 73 74  all [prepared st
3010: 61 74 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42  atements], [BLOB
3020: 20 68 61 6e 64 6c 65 73 5d 2c 0a 2a 2a 20 61 6e   handles],.** an
3030: 64 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75  d [sqlite3_backu
3040: 70 5d 20 6f 62 6a 65 63 74 73 20 61 72 65 20 61  p] objects are a
3050: 6c 73 6f 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a  lso destroyed..*
3060: 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 5b 73 71 6c  *.** ^If an [sql
3070: 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20  ite3] object is 
3080: 64 65 73 74 72 6f 79 65 64 20 77 68 69 6c 65 20  destroyed while 
3090: 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73  a transaction is
30a0: 20 6f 70 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72   open,.** the tr
30b0: 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 61 75 74  ansaction is aut
30c0: 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65  omatically rolle
30d0: 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68  d back..**.** Th
30e0: 65 20 43 20 70 61 72 61 6d 65 74 65 72 20 74 6f  e C parameter to
30f0: 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28   [sqlite3_close(
3100: 43 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  C)] and [sqlite3
3110: 5f 63 6c 6f 73 65 5f 76 32 28 43 29 5d 0a 2a 2a  _close_v2(C)].**
3120: 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20   must be either 
3130: 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65  a NULL.** pointe
3140: 72 20 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65 33  r or an [sqlite3
3150: 5d 20 6f 62 6a 65 63 74 20 70 6f 69 6e 74 65 72  ] object pointer
3160: 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f   obtained.** fro
3170: 6d 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  m [sqlite3_open(
3180: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  )], [sqlite3_ope
3190: 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73  n16()], or.** [s
31a0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
31b0: 5d 2c 20 61 6e 64 20 6e 6f 74 20 70 72 65 76 69  ], and not previ
31c0: 6f 75 73 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a  ously closed..**
31d0: 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65   ^Calling sqlite
31e0: 33 5f 63 6c 6f 73 65 28 29 20 6f 72 20 73 71 6c  3_close() or sql
31f0: 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20  ite3_close_v2() 
3200: 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  with a NULL poin
3210: 74 65 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  ter.** argument 
3220: 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f  is a harmless no
3230: 2d 6f 70 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  -op..*/.int sqli
3240: 74 65 33 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65  te3_close(sqlite
3250: 33 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  3*);.int sqlite3
3260: 5f 63 6c 6f 73 65 5f 76 32 28 73 71 6c 69 74 65  _close_v2(sqlite
3270: 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20  3*);../*.** The 
3280: 74 79 70 65 20 66 6f 72 20 61 20 63 61 6c 6c 62  type for a callb
3290: 61 63 6b 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a  ack function..**
32a0: 20 54 68 69 73 20 69 73 20 6c 65 67 61 63 79 20   This is legacy 
32b0: 61 6e 64 20 64 65 70 72 65 63 61 74 65 64 2e 20  and deprecated. 
32c0: 20 49 74 20 69 73 20 69 6e 63 6c 75 64 65 64 20   It is included 
32d0: 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 0a 2a  for historical.*
32e0: 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20  * compatibility 
32f0: 61 6e 64 20 69 73 20 6e 6f 74 20 64 6f 63 75 6d  and is not docum
3300: 65 6e 74 65 64 2e 0a 2a 2f 0a 74 79 70 65 64 65  ented..*/.typede
3310: 66 20 69 6e 74 20 28 2a 73 71 6c 69 74 65 33 5f  f int (*sqlite3_
3320: 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c  callback)(void*,
3330: 69 6e 74 2c 63 68 61 72 2a 2a 2c 20 63 68 61 72  int,char**, char
3340: 2a 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  **);../*.** CAPI
3350: 33 52 45 46 3a 20 4f 6e 65 2d 53 74 65 70 20 51  3REF: One-Step Q
3360: 75 65 72 79 20 45 78 65 63 75 74 69 6f 6e 20 49  uery Execution I
3370: 6e 74 65 72 66 61 63 65 0a 2a 2a 0a 2a 2a 20 54  nterface.**.** T
3380: 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  he sqlite3_exec(
3390: 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 61  ) interface is a
33a0: 20 63 6f 6e 76 65 6e 69 65 6e 63 65 20 77 72 61   convenience wra
33b0: 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b  pper around.** [
33c0: 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
33d0: 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  v2()], [sqlite3_
33e0: 73 74 65 70 28 29 5d 2c 20 61 6e 64 20 5b 73 71  step()], and [sq
33f0: 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
3400: 5d 2c 0a 2a 2a 20 74 68 61 74 20 61 6c 6c 6f 77  ],.** that allow
3410: 73 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  s an application
3420: 20 74 6f 20 72 75 6e 20 6d 75 6c 74 69 70 6c 65   to run multiple
3430: 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 66 20 53   statements of S
3440: 51 4c 0a 2a 2a 20 77 69 74 68 6f 75 74 20 68 61  QL.** without ha
3450: 76 69 6e 67 20 74 6f 20 75 73 65 20 61 20 6c 6f  ving to use a lo
3460: 74 20 6f 66 20 43 20 63 6f 64 65 2e 20 0a 2a 2a  t of C code. .**
3470: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
3480: 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66 61 63  _exec() interfac
3490: 65 20 72 75 6e 73 20 7a 65 72 6f 20 6f 72 20 6d  e runs zero or m
34a0: 6f 72 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 65  ore UTF-8 encode
34b0: 64 2c 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d  d,.** semicolon-
34c0: 73 65 70 61 72 61 74 65 20 53 51 4c 20 73 74 61  separate SQL sta
34d0: 74 65 6d 65 6e 74 73 20 70 61 73 73 65 64 20 69  tements passed i
34e0: 6e 74 6f 20 69 74 73 20 32 6e 64 20 61 72 67 75  nto its 2nd argu
34f0: 6d 65 6e 74 2c 0a 2a 2a 20 69 6e 20 74 68 65 20  ment,.** in the 
3500: 63 6f 6e 74 65 78 74 20 6f 66 20 74 68 65 20 5b  context of the [
3510: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
3520: 69 6f 6e 5d 20 70 61 73 73 65 64 20 69 6e 20 61  ion] passed in a
3530: 73 20 69 74 73 20 31 73 74 0a 2a 2a 20 61 72 67  s its 1st.** arg
3540: 75 6d 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 20  ument.  ^If the 
3550: 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
3560: 6e 20 6f 66 20 74 68 65 20 33 72 64 20 61 72 67  n of the 3rd arg
3570: 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c 69  ument to.** sqli
3580: 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 6e 6f  te3_exec() is no
3590: 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 69 74 20  t NULL, then it 
35a0: 69 73 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 65  is invoked for e
35b0: 61 63 68 20 72 65 73 75 6c 74 20 72 6f 77 0a 2a  ach result row.*
35c0: 2a 20 63 6f 6d 69 6e 67 20 6f 75 74 20 6f 66 20  * coming out of 
35d0: 74 68 65 20 65 76 61 6c 75 61 74 65 64 20 53 51  the evaluated SQ
35e0: 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 20 20 5e  L statements.  ^
35f0: 54 68 65 20 34 74 68 20 61 72 67 75 6d 65 6e 74  The 4th argument
3600: 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65   to.** sqlite3_e
3610: 78 65 63 28 29 20 69 73 20 72 65 6c 61 79 65 64  xec() is relayed
3620: 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68 65 20   through to the 
3630: 31 73 74 20 61 72 67 75 6d 65 6e 74 20 6f 66 20  1st argument of 
3640: 65 61 63 68 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b  each.** callback
3650: 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 20 20 5e 49   invocation.  ^I
3660: 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 70  f the callback p
3670: 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ointer to sqlite
3680: 33 5f 65 78 65 63 28 29 0a 2a 2a 20 69 73 20 4e  3_exec().** is N
3690: 55 4c 4c 2c 20 74 68 65 6e 20 6e 6f 20 63 61 6c  ULL, then no cal
36a0: 6c 62 61 63 6b 20 69 73 20 65 76 65 72 20 69 6e  lback is ever in
36b0: 76 6f 6b 65 64 20 61 6e 64 20 72 65 73 75 6c 74  voked and result
36c0: 20 72 6f 77 73 20 61 72 65 0a 2a 2a 20 69 67 6e   rows are.** ign
36d0: 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ored..**.** ^If 
36e0: 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20  an error occurs 
36f0: 77 68 69 6c 65 20 65 76 61 6c 75 61 74 69 6e 67  while evaluating
3700: 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
3710: 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74 6f 0a  nts passed into.
3720: 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  ** sqlite3_exec(
3730: 29 2c 20 74 68 65 6e 20 65 78 65 63 75 74 69 6f  ), then executio
3740: 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74  n of the current
3750: 20 73 74 61 74 65 6d 65 6e 74 20 73 74 6f 70 73   statement stops
3760: 20 61 6e 64 0a 2a 2a 20 73 75 62 73 65 71 75 65   and.** subseque
3770: 6e 74 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72  nt statements ar
3780: 65 20 73 6b 69 70 70 65 64 2e 20 20 5e 49 66 20  e skipped.  ^If 
3790: 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65  the 5th paramete
37a0: 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65  r to sqlite3_exe
37b0: 63 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55  c().** is not NU
37c0: 4c 4c 20 74 68 65 6e 20 61 6e 79 20 65 72 72 6f  LL then any erro
37d0: 72 20 6d 65 73 73 61 67 65 20 69 73 20 77 72 69  r message is wri
37e0: 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79  tten into memory
37f0: 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f   obtained.** fro
3800: 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
3810: 63 28 29 5d 20 61 6e 64 20 70 61 73 73 65 64 20  c()] and passed 
3820: 62 61 63 6b 20 74 68 72 6f 75 67 68 20 74 68 65  back through the
3830: 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 2e 0a   5th parameter..
3840: 2a 2a 20 54 6f 20 61 76 6f 69 64 20 6d 65 6d 6f  ** To avoid memo
3850: 72 79 20 6c 65 61 6b 73 2c 20 74 68 65 20 61 70  ry leaks, the ap
3860: 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64  plication should
3870: 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33   invoke [sqlite3
3880: 5f 66 72 65 65 28 29 5d 0a 2a 2a 20 6f 6e 20 65  _free()].** on e
3890: 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72  rror message str
38a0: 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 74 68  ings returned th
38b0: 72 6f 75 67 68 20 74 68 65 20 35 74 68 20 70 61  rough the 5th pa
38c0: 72 61 6d 65 74 65 72 20 6f 66 0a 2a 2a 20 6f 66  rameter of.** of
38d0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
38e0: 61 66 74 65 72 20 74 68 65 20 65 72 72 6f 72 20  after the error 
38f0: 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 69  message string i
3900: 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64  s no longer need
3910: 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 35  ed..** ^If the 5
3920: 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
3930: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69  sqlite3_exec() i
3940: 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 6e  s not NULL and n
3950: 6f 20 65 72 72 6f 72 73 0a 2a 2a 20 6f 63 63 75  o errors.** occu
3960: 72 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  r, then sqlite3_
3970: 65 78 65 63 28 29 20 73 65 74 73 20 74 68 65 20  exec() sets the 
3980: 70 6f 69 6e 74 65 72 20 69 6e 20 69 74 73 20 35  pointer in its 5
3990: 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  th parameter to.
39a0: 2a 2a 20 4e 55 4c 4c 20 62 65 66 6f 72 65 20 72  ** NULL before r
39b0: 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  eturning..**.** 
39c0: 5e 49 66 20 61 6e 20 73 71 6c 69 74 65 33 5f 65  ^If an sqlite3_e
39d0: 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 72  xec() callback r
39e0: 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c  eturns non-zero,
39f0: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65   the sqlite3_exe
3a00: 63 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72  c().** routine r
3a10: 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 41 42  eturns SQLITE_AB
3a20: 4f 52 54 20 77 69 74 68 6f 75 74 20 69 6e 76 6f  ORT without invo
3a30: 6b 69 6e 67 20 74 68 65 20 63 61 6c 6c 62 61 63  king the callbac
3a40: 6b 20 61 67 61 69 6e 20 61 6e 64 0a 2a 2a 20 77  k again and.** w
3a50: 69 74 68 6f 75 74 20 72 75 6e 6e 69 6e 67 20 61  ithout running a
3a60: 6e 79 20 73 75 62 73 65 71 75 65 6e 74 20 53 51  ny subsequent SQ
3a70: 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  L statements..**
3a80: 0a 2a 2a 20 5e 54 68 65 20 32 6e 64 20 61 72 67  .** ^The 2nd arg
3a90: 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c  ument to the sql
3aa0: 69 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c  ite3_exec() call
3ab0: 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 69 73  back function is
3ac0: 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f   the.** number o
3ad0: 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65  f columns in the
3ae0: 20 72 65 73 75 6c 74 2e 20 20 5e 54 68 65 20 33   result.  ^The 3
3af0: 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  rd argument to t
3b00: 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  he sqlite3_exec(
3b10: 29 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 73  ).** callback is
3b20: 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69   an array of poi
3b30: 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73  nters to strings
3b40: 20 6f 62 74 61 69 6e 65 64 20 61 73 20 69 66 20   obtained as if 
3b50: 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  from.** [sqlite3
3b60: 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c  _column_text()],
3b70: 20 6f 6e 65 20 66 6f 72 20 65 61 63 68 20 63 6f   one for each co
3b80: 6c 75 6d 6e 2e 20 20 5e 49 66 20 61 6e 20 65 6c  lumn.  ^If an el
3b90: 65 6d 65 6e 74 20 6f 66 20 61 0a 2a 2a 20 72 65  ement of a.** re
3ba0: 73 75 6c 74 20 72 6f 77 20 69 73 20 4e 55 4c 4c  sult row is NULL
3bb0: 20 74 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73   then the corres
3bc0: 70 6f 6e 64 69 6e 67 20 73 74 72 69 6e 67 20 70  ponding string p
3bd0: 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 65 0a 2a  ointer for the.*
3be0: 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  * sqlite3_exec()
3bf0: 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 4e   callback is a N
3c00: 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54  ULL pointer.  ^T
3c10: 68 65 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20  he 4th argument 
3c20: 74 6f 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65  to the.** sqlite
3c30: 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63  3_exec() callbac
3c40: 6b 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66  k is an array of
3c50: 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72   pointers to str
3c60: 69 6e 67 73 20 77 68 65 72 65 20 65 61 63 68 0a  ings where each.
3c70: 2a 2a 20 65 6e 74 72 79 20 72 65 70 72 65 73 65  ** entry represe
3c80: 6e 74 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  nts the name of 
3c90: 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 72 65  corresponding re
3ca0: 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 61 73 20 6f  sult column as o
3cb0: 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  btained.** from 
3cc0: 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
3cd0: 6e 61 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  name()]..**.** ^
3ce0: 49 66 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  If the 2nd param
3cf0: 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
3d00: 65 78 65 63 28 29 20 69 73 20 61 20 4e 55 4c 4c  exec() is a NULL
3d10: 20 70 6f 69 6e 74 65 72 2c 20 61 20 70 6f 69 6e   pointer, a poin
3d20: 74 65 72 0a 2a 2a 20 74 6f 20 61 6e 20 65 6d 70  ter.** to an emp
3d30: 74 79 20 73 74 72 69 6e 67 2c 20 6f 72 20 61 20  ty string, or a 
3d40: 70 6f 69 6e 74 65 72 20 74 68 61 74 20 63 6f 6e  pointer that con
3d50: 74 61 69 6e 73 20 6f 6e 6c 79 20 77 68 69 74 65  tains only white
3d60: 73 70 61 63 65 20 61 6e 64 2f 6f 72 20 0a 2a 2a  space and/or .**
3d70: 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 73 2c 20 74   SQL comments, t
3d80: 68 65 6e 20 6e 6f 20 53 51 4c 20 73 74 61 74 65  hen no SQL state
3d90: 6d 65 6e 74 73 20 61 72 65 20 65 76 61 6c 75 61  ments are evalua
3da0: 74 65 64 20 61 6e 64 20 74 68 65 20 64 61 74 61  ted and the data
3db0: 62 61 73 65 0a 2a 2a 20 69 73 20 6e 6f 74 20 63  base.** is not c
3dc0: 68 61 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65  hanged..**.** Re
3dd0: 73 74 72 69 63 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a  strictions:.**.*
3de0: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54  * <ul>.** <li> T
3df0: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
3e00: 75 73 74 20 69 6e 73 75 72 65 20 74 68 61 74 20  ust insure that 
3e10: 74 68 65 20 31 73 74 20 70 61 72 61 6d 65 74 65  the 1st paramete
3e20: 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65  r to sqlite3_exe
3e30: 63 28 29 0a 2a 2a 20 20 20 20 20 20 69 73 20 61  c().**      is a
3e40: 20 76 61 6c 69 64 20 61 6e 64 20 6f 70 65 6e 20   valid and open 
3e50: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
3e60: 74 69 6f 6e 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 54  tion]..** <li> T
3e70: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
3e80: 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20 5b 64  ust not close [d
3e90: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
3ea0: 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20 62 79  on] specified by
3eb0: 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 31 73 74  .**      the 1st
3ec0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
3ed0: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 77 68 69  lite3_exec() whi
3ee0: 6c 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  le sqlite3_exec(
3ef0: 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a  ) is running..**
3f00: 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 63   <li> The applic
3f10: 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 6d  ation must not m
3f20: 6f 64 69 66 79 20 74 68 65 20 53 51 4c 20 73 74  odify the SQL st
3f30: 61 74 65 6d 65 6e 74 20 74 65 78 74 20 70 61 73  atement text pas
3f40: 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 20 20 20 20  sed into.**     
3f50: 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
3f60: 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 65 78  er of sqlite3_ex
3f70: 65 63 28 29 20 77 68 69 6c 65 20 73 71 6c 69 74  ec() while sqlit
3f80: 65 33 5f 65 78 65 63 28 29 20 69 73 20 72 75 6e  e3_exec() is run
3f90: 6e 69 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  ning..** </ul>.*
3fa0: 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78  /.int sqlite3_ex
3fb0: 65 63 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20  ec(.  sqlite3*, 
3fc0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3fd0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3fe0: 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61   /* An open data
3ff0: 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  base */.  const 
4000: 63 68 61 72 20 2a 73 71 6c 2c 20 20 20 20 20 20  char *sql,      
4010: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4020: 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62       /* SQL to b
4030: 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20  e evaluated */. 
4040: 20 69 6e 74 20 28 2a 63 61 6c 6c 62 61 63 6b 29   int (*callback)
4050: 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a  (void*,int,char*
4060: 2a 2c 63 68 61 72 2a 2a 29 2c 20 20 2f 2a 20 43  *,char**),  /* C
4070: 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
4080: 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c 20 20 20   */.  void *,   
4090: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
40a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
40b0: 20 2f 2a 20 31 73 74 20 61 72 67 75 6d 65 6e 74   /* 1st argument
40c0: 20 74 6f 20 63 61 6c 6c 62 61 63 6b 20 2a 2f 0a   to callback */.
40d0: 20 20 63 68 61 72 20 2a 2a 65 72 72 6d 73 67 20    char **errmsg 
40e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
40f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
4100: 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65  Error msg writte
4110: 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a  n here */.);../*
4120: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
4130: 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45  sult Codes.** KE
4140: 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 4f  YWORDS: SQLITE_O
4150: 4b 20 7b 65 72 72 6f 72 20 63 6f 64 65 7d 20 7b  K {error code} {
4160: 65 72 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20  error codes}.** 
4170: 4b 45 59 57 4f 52 44 53 3a 20 7b 72 65 73 75 6c  KEYWORDS: {resul
4180: 74 20 63 6f 64 65 7d 20 7b 72 65 73 75 6c 74 20  t code} {result 
4190: 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e  codes}.**.** Man
41a0: 79 20 53 51 4c 69 74 65 20 66 75 6e 63 74 69 6f  y SQLite functio
41b0: 6e 73 20 72 65 74 75 72 6e 20 61 6e 20 69 6e 74  ns return an int
41c0: 65 67 65 72 20 72 65 73 75 6c 74 20 63 6f 64 65  eger result code
41d0: 20 66 72 6f 6d 20 74 68 65 20 73 65 74 20 73 68   from the set sh
41e0: 6f 77 6e 0a 2a 2a 20 68 65 72 65 20 69 6e 20 6f  own.** here in o
41f0: 72 64 65 72 20 74 6f 20 69 6e 64 69 63 61 74 65  rder to indicate
4200: 20 73 75 63 63 65 73 73 20 6f 72 20 66 61 69 6c   success or fail
4210: 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65  ure..**.** New e
4220: 72 72 6f 72 20 63 6f 64 65 73 20 6d 61 79 20 62  rror codes may b
4230: 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72  e added in futur
4240: 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  e versions of SQ
4250: 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  Lite..**.** See 
4260: 61 6c 73 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f  also: [SQLITE_IO
4270: 45 52 52 5f 52 45 41 44 20 7c 20 65 78 74 65 6e  ERR_READ | exten
4280: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
4290: 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76  ],.** [sqlite3_v
42a0: 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28  tab_on_conflict(
42b0: 29 5d 20 5b 53 51 4c 49 54 45 5f 52 4f 4c 4c 42  )] [SQLITE_ROLLB
42c0: 41 43 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f 64  ACK | result cod
42d0: 65 73 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  es]..*/.#define 
42e0: 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20 20 20 20  SQLITE_OK       
42f0: 20 20 20 20 30 20 20 20 2f 2a 20 53 75 63 63 65      0   /* Succe
4300: 73 73 66 75 6c 20 72 65 73 75 6c 74 20 2a 2f 0a  ssful result */.
4310: 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 2d 6f 66 2d  /* beginning-of-
4320: 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 23  error-codes */.#
4330: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 52  define SQLITE_ER
4340: 52 4f 52 20 20 20 20 20 20 20 20 31 20 20 20 2f  ROR        1   /
4350: 2a 20 53 51 4c 20 65 72 72 6f 72 20 6f 72 20 6d  * SQL error or m
4360: 69 73 73 69 6e 67 20 64 61 74 61 62 61 73 65 20  issing database 
4370: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4380: 45 5f 49 4e 54 45 52 4e 41 4c 20 20 20 20 20 32  E_INTERNAL     2
4390: 20 20 20 2f 2a 20 49 6e 74 65 72 6e 61 6c 20 6c     /* Internal l
43a0: 6f 67 69 63 20 65 72 72 6f 72 20 69 6e 20 53 51  ogic error in SQ
43b0: 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  Lite */.#define 
43c0: 53 51 4c 49 54 45 5f 50 45 52 4d 20 20 20 20 20  SQLITE_PERM     
43d0: 20 20 20 20 33 20 20 20 2f 2a 20 41 63 63 65 73      3   /* Acces
43e0: 73 20 70 65 72 6d 69 73 73 69 6f 6e 20 64 65 6e  s permission den
43f0: 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ied */.#define S
4400: 51 4c 49 54 45 5f 41 42 4f 52 54 20 20 20 20 20  QLITE_ABORT     
4410: 20 20 20 34 20 20 20 2f 2a 20 43 61 6c 6c 62 61     4   /* Callba
4420: 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 71 75 65  ck routine reque
4430: 73 74 65 64 20 61 6e 20 61 62 6f 72 74 20 2a 2f  sted an abort */
4440: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4450: 42 55 53 59 20 20 20 20 20 20 20 20 20 35 20 20  BUSY         5  
4460: 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 65   /* The database
4470: 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b 65 64 20   file is locked 
4480: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4490: 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 36  E_LOCKED       6
44a0: 20 20 20 2f 2a 20 41 20 74 61 62 6c 65 20 69 6e     /* A table in
44b0: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73   the database is
44c0: 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69   locked */.#defi
44d0: 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20  ne SQLITE_NOMEM 
44e0: 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 41 20         7   /* A 
44f0: 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 65 64 20  malloc() failed 
4500: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4510: 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 38  E_READONLY     8
4520: 20 20 20 2f 2a 20 41 74 74 65 6d 70 74 20 74 6f     /* Attempt to
4530: 20 77 72 69 74 65 20 61 20 72 65 61 64 6f 6e 6c   write a readonl
4540: 79 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64  y database */.#d
4550: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54  efine SQLITE_INT
4560: 45 52 52 55 50 54 20 20 20 20 39 20 20 20 2f 2a  ERRUPT    9   /*
4570: 20 4f 70 65 72 61 74 69 6f 6e 20 74 65 72 6d 69   Operation termi
4580: 6e 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33  nated by sqlite3
4590: 5f 69 6e 74 65 72 72 75 70 74 28 29 2a 2f 0a 23  _interrupt()*/.#
45a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
45b0: 45 52 52 20 20 20 20 20 20 20 31 30 20 20 20 2f  ERR       10   /
45c0: 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f 66 20 64  * Some kind of d
45d0: 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72 20 6f 63  isk I/O error oc
45e0: 63 75 72 72 65 64 20 2a 2f 0a 23 64 65 66 69 6e  curred */.#defin
45f0: 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54  e SQLITE_CORRUPT
4600: 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 68 65       11   /* The
4610: 20 64 61 74 61 62 61 73 65 20 64 69 73 6b 20 69   database disk i
4620: 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f 72 6d 65  mage is malforme
4630: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
4640: 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 20 20 20  ITE_NOTFOUND    
4650: 31 32 20 20 20 2f 2a 20 55 6e 6b 6e 6f 77 6e 20  12   /* Unknown 
4660: 6f 70 63 6f 64 65 20 69 6e 20 73 71 6c 69 74 65  opcode in sqlite
4670: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
4680: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4690: 54 45 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 31  TE_FULL        1
46a0: 33 20 20 20 2f 2a 20 49 6e 73 65 72 74 69 6f 6e  3   /* Insertion
46b0: 20 66 61 69 6c 65 64 20 62 65 63 61 75 73 65 20   failed because 
46c0: 64 61 74 61 62 61 73 65 20 69 73 20 66 75 6c 6c  database is full
46d0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
46e0: 54 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20 20 31  TE_CANTOPEN    1
46f0: 34 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20 74 6f  4   /* Unable to
4700: 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61   open the databa
4710: 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69  se file */.#defi
4720: 6e 65 20 53 51 4c 49 54 45 5f 50 52 4f 54 4f 43  ne SQLITE_PROTOC
4730: 4f 4c 20 20 20 20 31 35 20 20 20 2f 2a 20 44 61  OL    15   /* Da
4740: 74 61 62 61 73 65 20 6c 6f 63 6b 20 70 72 6f 74  tabase lock prot
4750: 6f 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a 23 64  ocol error */.#d
4760: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 4d 50  efine SQLITE_EMP
4770: 54 59 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a  TY       16   /*
4780: 20 44 61 74 61 62 61 73 65 20 69 73 20 65 6d 70   Database is emp
4790: 74 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ty */.#define SQ
47a0: 4c 49 54 45 5f 53 43 48 45 4d 41 20 20 20 20 20  LITE_SCHEMA     
47b0: 20 31 37 20 20 20 2f 2a 20 54 68 65 20 64 61 74   17   /* The dat
47c0: 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 61  abase schema cha
47d0: 6e 67 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nged */.#define 
47e0: 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 20 20 20  SQLITE_TOOBIG   
47f0: 20 20 20 31 38 20 20 20 2f 2a 20 53 74 72 69 6e     18   /* Strin
4800: 67 20 6f 72 20 42 4c 4f 42 20 65 78 63 65 65 64  g or BLOB exceed
4810: 73 20 73 69 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a  s size limit */.
4820: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
4830: 4f 4e 53 54 52 41 49 4e 54 20 20 31 39 20 20 20  ONSTRAINT  19   
4840: 2f 2a 20 41 62 6f 72 74 20 64 75 65 20 74 6f 20  /* Abort due to 
4850: 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61  constraint viola
4860: 74 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20  tion */.#define 
4870: 53 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43 48 20  SQLITE_MISMATCH 
4880: 20 20 20 32 30 20 20 20 2f 2a 20 44 61 74 61 20     20   /* Data 
4890: 74 79 70 65 20 6d 69 73 6d 61 74 63 68 20 2a 2f  type mismatch */
48a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
48b0: 4d 49 53 55 53 45 20 20 20 20 20 20 32 31 20 20  MISUSE      21  
48c0: 20 2f 2a 20 4c 69 62 72 61 72 79 20 75 73 65 64   /* Library used
48d0: 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 2a 2f 0a   incorrectly */.
48e0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e  #define SQLITE_N
48f0: 4f 4c 46 53 20 20 20 20 20 20 20 32 32 20 20 20  OLFS       22   
4900: 2f 2a 20 55 73 65 73 20 4f 53 20 66 65 61 74 75  /* Uses OS featu
4910: 72 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 65  res not supporte
4920: 64 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23 64 65  d on host */.#de
4930: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54 48  fine SQLITE_AUTH
4940: 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20          23   /* 
4950: 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 64 65  Authorization de
4960: 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nied */.#define 
4970: 53 51 4c 49 54 45 5f 46 4f 52 4d 41 54 20 20 20  SQLITE_FORMAT   
4980: 20 20 20 32 34 20 20 20 2f 2a 20 41 75 78 69 6c     24   /* Auxil
4990: 69 61 72 79 20 64 61 74 61 62 61 73 65 20 66 6f  iary database fo
49a0: 72 6d 61 74 20 65 72 72 6f 72 20 2a 2f 0a 23 64  rmat error */.#d
49b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 41 4e  efine SQLITE_RAN
49c0: 47 45 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a  GE       25   /*
49d0: 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74   2nd parameter t
49e0: 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 20 6f  o sqlite3_bind o
49f0: 75 74 20 6f 66 20 72 61 6e 67 65 20 2a 2f 0a 23  ut of range */.#
4a00: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
4a10: 54 41 44 42 20 20 20 20 20 20 32 36 20 20 20 2f  TADB      26   /
4a20: 2a 20 46 69 6c 65 20 6f 70 65 6e 65 64 20 74 68  * File opened th
4a30: 61 74 20 69 73 20 6e 6f 74 20 61 20 64 61 74 61  at is not a data
4a40: 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65  base file */.#de
4a50: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49  fine SQLITE_NOTI
4a60: 43 45 20 20 20 20 20 20 32 37 20 20 20 2f 2a 20  CE      27   /* 
4a70: 4e 6f 74 69 66 69 63 61 74 69 6f 6e 73 20 66 72  Notifications fr
4a80: 6f 6d 20 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29  om sqlite3_log()
4a90: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4aa0: 54 45 5f 57 41 52 4e 49 4e 47 20 20 20 20 20 32  TE_WARNING     2
4ab0: 38 20 20 20 2f 2a 20 57 61 72 6e 69 6e 67 73 20  8   /* Warnings 
4ac0: 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6c 6f 67  from sqlite3_log
4ad0: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
4ae0: 4c 49 54 45 5f 52 4f 57 20 20 20 20 20 20 20 20  LITE_ROW        
4af0: 20 31 30 30 20 20 2f 2a 20 73 71 6c 69 74 65 33   100  /* sqlite3
4b00: 5f 73 74 65 70 28 29 20 68 61 73 20 61 6e 6f 74  _step() has anot
4b10: 68 65 72 20 72 6f 77 20 72 65 61 64 79 20 2a 2f  her row ready */
4b20: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4b30: 44 4f 4e 45 20 20 20 20 20 20 20 20 31 30 31 20  DONE        101 
4b40: 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70   /* sqlite3_step
4b50: 28 29 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  () has finished 
4b60: 65 78 65 63 75 74 69 6e 67 20 2a 2f 0a 2f 2a 20  executing */./* 
4b70: 65 6e 64 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64  end-of-error-cod
4b80: 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  es */../*.** CAP
4b90: 49 33 52 45 46 3a 20 45 78 74 65 6e 64 65 64 20  I3REF: Extended 
4ba0: 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20  Result Codes.** 
4bb0: 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e  KEYWORDS: {exten
4bc0: 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 7d 20  ded error code} 
4bd0: 7b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20  {extended error 
4be0: 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52  codes}.** KEYWOR
4bf0: 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 72 65  DS: {extended re
4c00: 73 75 6c 74 20 63 6f 64 65 7d 20 7b 65 78 74 65  sult code} {exte
4c10: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
4c20: 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 69 74 73 20  s}.**.** In its 
4c30: 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72  default configur
4c40: 61 74 69 6f 6e 2c 20 53 51 4c 69 74 65 20 41 50  ation, SQLite AP
4c50: 49 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  I routines retur
4c60: 6e 20 6f 6e 65 20 6f 66 20 32 36 20 69 6e 74 65  n one of 26 inte
4c70: 67 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  ger.** [SQLITE_O
4c80: 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65 73  K | result codes
4c90: 5d 2e 20 20 48 6f 77 65 76 65 72 2c 20 65 78 70  ].  However, exp
4ca0: 65 72 69 65 6e 63 65 20 68 61 73 20 73 68 6f 77  erience has show
4cb0: 6e 20 74 68 61 74 20 6d 61 6e 79 20 6f 66 0a 2a  n that many of.*
4cc0: 2a 20 74 68 65 73 65 20 72 65 73 75 6c 74 20 63  * these result c
4cd0: 6f 64 65 73 20 61 72 65 20 74 6f 6f 20 63 6f 61  odes are too coa
4ce0: 72 73 65 2d 67 72 61 69 6e 65 64 2e 20 20 54 68  rse-grained.  Th
4cf0: 65 79 20 64 6f 20 6e 6f 74 20 70 72 6f 76 69 64  ey do not provid
4d00: 65 20 61 73 0a 2a 2a 20 6d 75 63 68 20 69 6e 66  e as.** much inf
4d10: 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 70  ormation about p
4d20: 72 6f 62 6c 65 6d 73 20 61 73 20 70 72 6f 67 72  roblems as progr
4d30: 61 6d 6d 65 72 73 20 6d 69 67 68 74 20 6c 69 6b  ammers might lik
4d40: 65 2e 20 20 49 6e 20 61 6e 20 65 66 66 6f 72 74  e.  In an effort
4d50: 20 74 6f 0a 2a 2a 20 61 64 64 72 65 73 73 20 74   to.** address t
4d60: 68 69 73 2c 20 6e 65 77 65 72 20 76 65 72 73 69  his, newer versi
4d70: 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 28 76  ons of SQLite (v
4d80: 65 72 73 69 6f 6e 20 33 2e 33 2e 38 20 61 6e 64  ersion 3.3.8 and
4d90: 20 6c 61 74 65 72 29 20 69 6e 63 6c 75 64 65 0a   later) include.
4da0: 2a 2a 20 73 75 70 70 6f 72 74 20 66 6f 72 20 61  ** support for a
4db0: 64 64 69 74 69 6f 6e 61 6c 20 72 65 73 75 6c 74  dditional result
4dc0: 20 63 6f 64 65 73 20 74 68 61 74 20 70 72 6f 76   codes that prov
4dd0: 69 64 65 20 6d 6f 72 65 20 64 65 74 61 69 6c 65  ide more detaile
4de0: 64 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a  d information.**
4df0: 20 61 62 6f 75 74 20 65 72 72 6f 72 73 2e 20 54   about errors. T
4e00: 68 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 75  he extended resu
4e10: 6c 74 20 63 6f 64 65 73 20 61 72 65 20 65 6e 61  lt codes are ena
4e20: 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64  bled or disabled
4e30: 0a 2a 2a 20 6f 6e 20 61 20 70 65 72 20 64 61 74  .** on a per dat
4e40: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
4e50: 20 62 61 73 69 73 20 75 73 69 6e 67 20 74 68 65   basis using the
4e60: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 74  .** [sqlite3_ext
4e70: 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64  ended_result_cod
4e80: 65 73 28 29 5d 20 41 50 49 2e 0a 2a 2a 0a 2a 2a  es()] API..**.**
4e90: 20 53 6f 6d 65 20 6f 66 20 74 68 65 20 61 76 61   Some of the ava
4ea0: 69 6c 61 62 6c 65 20 65 78 74 65 6e 64 65 64 20  ilable extended 
4eb0: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65  result codes are
4ec0: 20 6c 69 73 74 65 64 20 68 65 72 65 2e 0a 2a 2a   listed here..**
4ed0: 20 4f 6e 65 20 6d 61 79 20 65 78 70 65 63 74 20   One may expect 
4ee0: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 78  the number of ex
4ef0: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
4f00: 64 65 73 20 77 69 6c 6c 20 62 65 20 65 78 70 61  des will be expa
4f10: 6e 64 0a 2a 2a 20 6f 76 65 72 20 74 69 6d 65 2e  nd.** over time.
4f20: 20 20 53 6f 66 74 77 61 72 65 20 74 68 61 74 20    Software that 
4f30: 75 73 65 73 20 65 78 74 65 6e 64 65 64 20 72 65  uses extended re
4f40: 73 75 6c 74 20 63 6f 64 65 73 20 73 68 6f 75 6c  sult codes shoul
4f50: 64 20 65 78 70 65 63 74 0a 2a 2a 20 74 6f 20 73  d expect.** to s
4f60: 65 65 20 6e 65 77 20 72 65 73 75 6c 74 20 63 6f  ee new result co
4f70: 64 65 73 20 69 6e 20 66 75 74 75 72 65 20 72 65  des in future re
4f80: 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65  leases of SQLite
4f90: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49  ..**.** The SQLI
4fa0: 54 45 5f 4f 4b 20 72 65 73 75 6c 74 20 63 6f 64  TE_OK result cod
4fb0: 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 62 65 20  e will never be 
4fc0: 65 78 74 65 6e 64 65 64 2e 20 20 49 74 20 77 69  extended.  It wi
4fd0: 6c 6c 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65 20  ll always.** be 
4fe0: 65 78 61 63 74 6c 79 20 7a 65 72 6f 2e 0a 2a 2f  exactly zero..*/
4ff0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5000: 49 4f 45 52 52 5f 52 45 41 44 20 20 20 20 20 20  IOERR_READ      
5010: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5020: 49 4f 45 52 52 20 7c 20 28 31 3c 3c 38 29 29 0a  IOERR | (1<<8)).
5030: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5040: 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 20  OERR_SHORT_READ 
5050: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
5060: 4f 45 52 52 20 7c 20 28 32 3c 3c 38 29 29 0a 23  OERR | (2<<8)).#
5070: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5080: 45 52 52 5f 57 52 49 54 45 20 20 20 20 20 20 20  ERR_WRITE       
5090: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
50a0: 45 52 52 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64  ERR | (3<<8)).#d
50b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
50c0: 52 52 5f 46 53 59 4e 43 20 20 20 20 20 20 20 20  RR_FSYNC        
50d0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
50e0: 52 52 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65  RR | (4<<8)).#de
50f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
5100: 52 5f 44 49 52 5f 46 53 59 4e 43 20 20 20 20 20  R_DIR_FSYNC     
5110: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
5120: 52 20 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65 66  R | (5<<8)).#def
5130: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5140: 5f 54 52 55 4e 43 41 54 45 20 20 20 20 20 20 20  _TRUNCATE       
5150: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5160: 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64 65 66 69   | (6<<8)).#defi
5170: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5180: 46 53 54 41 54 20 20 20 20 20 20 20 20 20 20 20  FSTAT           
5190: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
51a0: 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (7<<8)).#defin
51b0: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 55  e SQLITE_IOERR_U
51c0: 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20  NLOCK           
51d0: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
51e0: 20 28 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (8<<8)).#define
51f0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 44   SQLITE_IOERR_RD
5200: 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 20  LOCK            
5210: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
5220: 28 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (9<<8)).#define 
5230: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 45 4c  SQLITE_IOERR_DEL
5240: 45 54 45 20 20 20 20 20 20 20 20 20 20 20 20 28  ETE            (
5250: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5260: 31 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  10<<8)).#define 
5270: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f  SQLITE_IOERR_BLO
5280: 43 4b 45 44 20 20 20 20 20 20 20 20 20 20 20 28  CKED           (
5290: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
52a0: 31 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  11<<8)).#define 
52b0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4e 4f 4d  SQLITE_IOERR_NOM
52c0: 45 4d 20 20 20 20 20 20 20 20 20 20 20 20 20 28  EM             (
52d0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
52e0: 31 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  12<<8)).#define 
52f0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 41 43 43  SQLITE_IOERR_ACC
5300: 45 53 53 20 20 20 20 20 20 20 20 20 20 20 20 28  ESS            (
5310: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5320: 31 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  13<<8)).#define 
5330: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 48 45  SQLITE_IOERR_CHE
5340: 43 4b 52 45 53 45 52 56 45 44 4c 4f 43 4b 20 28  CKRESERVEDLOCK (
5350: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5360: 31 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  14<<8)).#define 
5370: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4c 4f 43  SQLITE_IOERR_LOC
5380: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28  K              (
5390: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
53a0: 31 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  15<<8)).#define 
53b0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 4c 4f  SQLITE_IOERR_CLO
53c0: 53 45 20 20 20 20 20 20 20 20 20 20 20 20 20 28  SE             (
53d0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
53e0: 31 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  16<<8)).#define 
53f0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49 52  SQLITE_IOERR_DIR
5400: 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20 28  _CLOSE         (
5410: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5420: 31 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  17<<8)).#define 
5430: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d  SQLITE_IOERR_SHM
5440: 4f 50 45 4e 20 20 20 20 20 20 20 20 20 20 20 28  OPEN           (
5450: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5460: 31 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  18<<8)).#define 
5470: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d  SQLITE_IOERR_SHM
5480: 53 49 5a 45 20 20 20 20 20 20 20 20 20 20 20 28  SIZE           (
5490: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
54a0: 31 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  19<<8)).#define 
54b0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d  SQLITE_IOERR_SHM
54c0: 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 28  LOCK           (
54d0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
54e0: 32 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  20<<8)).#define 
54f0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d  SQLITE_IOERR_SHM
5500: 4d 41 50 20 20 20 20 20 20 20 20 20 20 20 20 28  MAP            (
5510: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5520: 32 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  21<<8)).#define 
5530: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 45 45  SQLITE_IOERR_SEE
5540: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28  K              (
5550: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5560: 32 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  22<<8)).#define 
5570: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 45 4c  SQLITE_IOERR_DEL
5580: 45 54 45 5f 4e 4f 45 4e 54 20 20 20 20 20 20 28  ETE_NOENT      (
5590: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
55a0: 32 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  23<<8)).#define 
55b0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4d 4d 41  SQLITE_IOERR_MMA
55c0: 50 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28  P              (
55d0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
55e0: 32 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  24<<8)).#define 
55f0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 5f 53 48  SQLITE_LOCKED_SH
5600: 41 52 45 44 43 41 43 48 45 20 20 20 20 20 20 28  AREDCACHE      (
5610: 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 7c 20  SQLITE_LOCKED | 
5620: 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (1<<8)).#define
5630: 20 53 51 4c 49 54 45 5f 42 55 53 59 5f 52 45 43   SQLITE_BUSY_REC
5640: 4f 56 45 52 59 20 20 20 20 20 20 20 20 20 20 20  OVERY           
5650: 28 53 51 4c 49 54 45 5f 42 55 53 59 20 20 20 7c  (SQLITE_BUSY   |
5660: 20 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e    (1<<8)).#defin
5670: 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45  e SQLITE_CANTOPE
5680: 4e 5f 4e 4f 54 45 4d 50 44 49 52 20 20 20 20 20  N_NOTEMPDIR     
5690: 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45   (SQLITE_CANTOPE
56a0: 4e 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66  N | (1<<8)).#def
56b0: 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f  ine SQLITE_CANTO
56c0: 50 45 4e 5f 49 53 44 49 52 20 20 20 20 20 20 20  PEN_ISDIR       
56d0: 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f     (SQLITE_CANTO
56e0: 50 45 4e 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64  PEN | (2<<8)).#d
56f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e  efine SQLITE_CAN
5700: 54 4f 50 45 4e 5f 46 55 4c 4c 50 41 54 48 20 20  TOPEN_FULLPATH  
5710: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e       (SQLITE_CAN
5720: 54 4f 50 45 4e 20 7c 20 28 33 3c 3c 38 29 29 0a  TOPEN | (3<<8)).
5730: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
5740: 4f 52 52 55 50 54 5f 56 54 41 42 20 20 20 20 20  ORRUPT_VTAB     
5750: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43         (SQLITE_C
5760: 4f 52 52 55 50 54 20 7c 20 28 31 3c 3c 38 29 29  ORRUPT | (1<<8))
5770: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5780: 52 45 41 44 4f 4e 4c 59 5f 52 45 43 4f 56 45 52  READONLY_RECOVER
5790: 59 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  Y       (SQLITE_
57a0: 52 45 41 44 4f 4e 4c 59 20 7c 20 28 31 3c 3c 38  READONLY | (1<<8
57b0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
57c0: 45 5f 52 45 41 44 4f 4e 4c 59 5f 43 41 4e 54 4c  E_READONLY_CANTL
57d0: 4f 43 4b 20 20 20 20 20 20 20 28 53 51 4c 49 54  OCK       (SQLIT
57e0: 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 32 3c  E_READONLY | (2<
57f0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5800: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 52 4f 4c  ITE_READONLY_ROL
5810: 4c 42 41 43 4b 20 20 20 20 20 20 20 28 53 51 4c  LBACK       (SQL
5820: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28  ITE_READONLY | (
5830: 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  3<<8)).#define S
5840: 51 4c 49 54 45 5f 41 42 4f 52 54 5f 52 4f 4c 4c  QLITE_ABORT_ROLL
5850: 42 41 43 4b 20 20 20 20 20 20 20 20 20 20 28 53  BACK          (S
5860: 51 4c 49 54 45 5f 41 42 4f 52 54 20 7c 20 28 32  QLITE_ABORT | (2
5870: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5880: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  LITE_CONSTRAINT_
5890: 43 48 45 43 4b 20 20 20 20 20 20 20 20 28 53 51  CHECK        (SQ
58a0: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20  LITE_CONSTRAINT 
58b0: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
58c0: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
58d0: 49 4e 54 5f 43 4f 4d 4d 49 54 48 4f 4f 4b 20 20  INT_COMMITHOOK  
58e0: 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41   (SQLITE_CONSTRA
58f0: 49 4e 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64  INT | (2<<8)).#d
5900: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
5910: 53 54 52 41 49 4e 54 5f 46 4f 52 45 49 47 4e 4b  STRAINT_FOREIGNK
5920: 45 59 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e  EY   (SQLITE_CON
5930: 53 54 52 41 49 4e 54 20 7c 20 28 33 3c 3c 38 29  STRAINT | (3<<8)
5940: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5950: 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 46 55 4e 43  _CONSTRAINT_FUNC
5960: 54 49 4f 4e 20 20 20 20 20 28 53 51 4c 49 54 45  TION     (SQLITE
5970: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 34  _CONSTRAINT | (4
5980: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5990: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  LITE_CONSTRAINT_
59a0: 4e 4f 54 4e 55 4c 4c 20 20 20 20 20 20 28 53 51  NOTNULL      (SQ
59b0: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20  LITE_CONSTRAINT 
59c0: 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (5<<8)).#defin
59d0: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
59e0: 49 4e 54 5f 50 52 49 4d 41 52 59 4b 45 59 20 20  INT_PRIMARYKEY  
59f0: 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41   (SQLITE_CONSTRA
5a00: 49 4e 54 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64  INT | (6<<8)).#d
5a10: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
5a20: 53 54 52 41 49 4e 54 5f 54 52 49 47 47 45 52 20  STRAINT_TRIGGER 
5a30: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e       (SQLITE_CON
5a40: 53 54 52 41 49 4e 54 20 7c 20 28 37 3c 3c 38 29  STRAINT | (7<<8)
5a50: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5a60: 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 55 4e 49 51  _CONSTRAINT_UNIQ
5a70: 55 45 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  UE       (SQLITE
5a80: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 38  _CONSTRAINT | (8
5a90: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5aa0: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  LITE_CONSTRAINT_
5ab0: 56 54 41 42 20 20 20 20 20 20 20 20 20 28 53 51  VTAB         (SQ
5ac0: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20  LITE_CONSTRAINT 
5ad0: 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (9<<8)).#defin
5ae0: 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 5f  e SQLITE_NOTICE_
5af0: 52 45 43 4f 56 45 52 5f 57 41 4c 20 20 20 20 20  RECOVER_WAL     
5b00: 20 28 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20   (SQLITE_NOTICE 
5b10: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
5b20: 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 5f  e SQLITE_NOTICE_
5b30: 52 45 43 4f 56 45 52 5f 52 4f 4c 4c 42 41 43 4b  RECOVER_ROLLBACK
5b40: 20 28 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20   (SQLITE_NOTICE 
5b50: 7c 20 28 32 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a  | (2<<8))../*.**
5b60: 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73   CAPI3REF: Flags
5b70: 20 46 6f 72 20 46 69 6c 65 20 4f 70 65 6e 20 4f   For File Open O
5b80: 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20  perations.**.** 
5b90: 54 68 65 73 65 20 62 69 74 20 76 61 6c 75 65 73  These bit values
5ba0: 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f   are intended fo
5bb0: 72 20 75 73 65 20 69 6e 20 74 68 65 0a 2a 2a 20  r use in the.** 
5bc0: 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  3rd parameter to
5bd0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70   the [sqlite3_op
5be0: 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61  en_v2()] interfa
5bf0: 63 65 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 68 65  ce and.** in the
5c00: 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   4th parameter t
5c10: 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  o the [sqlite3_v
5c20: 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64  fs.xOpen] method
5c30: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
5c40: 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c  ITE_OPEN_READONL
5c50: 59 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30  Y         0x0000
5c60: 30 30 30 31 20 20 2f 2a 20 4f 6b 20 66 6f 72 20  0001  /* Ok for 
5c70: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
5c80: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
5c90: 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
5ca0: 54 45 20 20 20 20 20 20 20 20 30 78 30 30 30 30  TE        0x0000
5cb0: 30 30 30 32 20 20 2f 2a 20 4f 6b 20 66 6f 72 20  0002  /* Ok for 
5cc0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
5cd0: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
5ce0: 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 20  ITE_OPEN_CREATE 
5cf0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
5d00: 30 30 30 34 20 20 2f 2a 20 4f 6b 20 66 6f 72 20  0004  /* Ok for 
5d10: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
5d20: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
5d30: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f  ITE_OPEN_DELETEO
5d40: 4e 43 4c 4f 53 45 20 20 20 20 30 78 30 30 30 30  NCLOSE    0x0000
5d50: 30 30 30 38 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  0008  /* VFS onl
5d60: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
5d70: 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49  ITE_OPEN_EXCLUSI
5d80: 56 45 20 20 20 20 20 20 20 20 30 78 30 30 30 30  VE        0x0000
5d90: 30 30 31 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  0010  /* VFS onl
5da0: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
5db0: 49 54 45 5f 4f 50 45 4e 5f 41 55 54 4f 50 52 4f  ITE_OPEN_AUTOPRO
5dc0: 58 59 20 20 20 20 20 20 20 20 30 78 30 30 30 30  XY        0x0000
5dd0: 30 30 32 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  0020  /* VFS onl
5de0: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
5df0: 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20 20 20 20  ITE_OPEN_URI    
5e00: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
5e10: 30 30 34 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20  0040  /* Ok for 
5e20: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
5e30: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
5e40: 49 54 45 5f 4f 50 45 4e 5f 4d 45 4d 4f 52 59 20  ITE_OPEN_MEMORY 
5e50: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
5e60: 30 30 38 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20  0080  /* Ok for 
5e70: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
5e80: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
5e90: 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42  ITE_OPEN_MAIN_DB
5ea0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
5eb0: 30 31 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  0100  /* VFS onl
5ec0: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
5ed0: 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42  ITE_OPEN_TEMP_DB
5ee0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
5ef0: 30 32 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  0200  /* VFS onl
5f00: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
5f10: 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45  ITE_OPEN_TRANSIE
5f20: 4e 54 5f 44 42 20 20 20 20 20 30 78 30 30 30 30  NT_DB     0x0000
5f30: 30 34 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  0400  /* VFS onl
5f40: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
5f50: 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f  ITE_OPEN_MAIN_JO
5f60: 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30  URNAL     0x0000
5f70: 30 38 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  0800  /* VFS onl
5f80: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
5f90: 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f  ITE_OPEN_TEMP_JO
5fa0: 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30  URNAL     0x0000
5fb0: 31 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  1000  /* VFS onl
5fc0: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
5fd0: 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52  ITE_OPEN_SUBJOUR
5fe0: 4e 41 4c 20 20 20 20 20 20 20 30 78 30 30 30 30  NAL       0x0000
5ff0: 32 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  2000  /* VFS onl
6000: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
6010: 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f  ITE_OPEN_MASTER_
6020: 4a 4f 55 52 4e 41 4c 20 20 20 30 78 30 30 30 30  JOURNAL   0x0000
6030: 34 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  4000  /* VFS onl
6040: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
6050: 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58  ITE_OPEN_NOMUTEX
6060: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
6070: 38 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20  8000  /* Ok for 
6080: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
6090: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
60a0: 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54  ITE_OPEN_FULLMUT
60b0: 45 58 20 20 20 20 20 20 20 20 30 78 30 30 30 31  EX        0x0001
60c0: 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20  0000  /* Ok for 
60d0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
60e0: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
60f0: 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43  ITE_OPEN_SHAREDC
6100: 41 43 48 45 20 20 20 20 20 20 30 78 30 30 30 32  ACHE      0x0002
6110: 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20  0000  /* Ok for 
6120: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
6130: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
6140: 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45  ITE_OPEN_PRIVATE
6150: 43 41 43 48 45 20 20 20 20 20 30 78 30 30 30 34  CACHE     0x0004
6160: 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20  0000  /* Ok for 
6170: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
6180: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
6190: 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 20 20 20 20  ITE_OPEN_WAL    
61a0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 38            0x0008
61b0: 30 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  0000  /* VFS onl
61c0: 79 20 2a 2f 0a 0a 2f 2a 20 52 65 73 65 72 76 65  y */../* Reserve
61d0: 64 3a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  d:              
61e0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 46             0x00F
61f0: 30 30 30 30 30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20  00000 */../*.** 
6200: 43 41 50 49 33 52 45 46 3a 20 44 65 76 69 63 65  CAPI3REF: Device
6210: 20 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73   Characteristics
6220: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 44 65 76 69  .**.** The xDevi
6230: 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63  ceCharacteristic
6240: 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20  s method of the 
6250: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
6260: 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72  ods].** object r
6270: 65 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65  eturns an intege
6280: 72 20 77 68 69 63 68 20 69 73 20 61 20 76 65 63  r which is a vec
6290: 74 6f 72 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20  tor of these.** 
62a0: 62 69 74 20 76 61 6c 75 65 73 20 65 78 70 72 65  bit values expre
62b0: 73 73 69 6e 67 20 49 2f 4f 20 63 68 61 72 61 63  ssing I/O charac
62c0: 74 65 72 69 73 74 69 63 73 20 6f 66 20 74 68 65  teristics of the
62d0: 20 6d 61 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a   mass storage.**
62e0: 20 64 65 76 69 63 65 20 74 68 61 74 20 68 6f 6c   device that hol
62f0: 64 73 20 74 68 65 20 66 69 6c 65 20 74 68 61 74  ds the file that
6300: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f   the [sqlite3_io
6310: 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66  _methods].** ref
6320: 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68  ers to..**.** Th
6330: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
6340: 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d  TOMIC property m
6350: 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72  eans that all wr
6360: 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73  ites of.** any s
6370: 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20  ize are atomic. 
6380: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
6390: 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75  P_ATOMICnnn valu
63a0: 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20  es.** mean that 
63b0: 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73  writes of blocks
63c0: 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79   that are nnn by
63d0: 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a  tes in size and.
63e0: 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74  ** are aligned t
63f0: 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69  o an address whi
6400: 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  ch is an integer
6410: 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20   multiple of.** 
6420: 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20  nnn are atomic. 
6430: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
6440: 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61  P_SAFE_APPEND va
6450: 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61  lue means.** tha
6460: 74 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61  t when data is a
6470: 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c  ppended to a fil
6480: 65 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61  e, the data is a
6490: 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74  ppended.** first
64a0: 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f   then the size o
64b0: 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78  f the file is ex
64c0: 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68  tended, never th
64d0: 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61  e other.** way a
64e0: 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49  round.  The SQLI
64f0: 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54  TE_IOCAP_SEQUENT
6500: 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61  IAL property mea
6510: 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72  ns that.** infor
6520: 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65  mation is writte
6530: 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65  n to disk in the
6540: 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63   same order as c
6550: 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74  alls.** to xWrit
6560: 65 28 29 2e 20 20 54 68 65 20 53 51 4c 49 54 45  e().  The SQLITE
6570: 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45  _IOCAP_POWERSAFE
6580: 5f 4f 56 45 52 57 52 49 54 45 20 70 72 6f 70 65  _OVERWRITE prope
6590: 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a  rty means that.*
65a0: 2a 20 61 66 74 65 72 20 72 65 62 6f 6f 74 20 66  * after reboot f
65b0: 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 72 61 73 68  ollowing a crash
65c0: 20 6f 72 20 70 6f 77 65 72 20 6c 6f 73 73 2c 20   or power loss, 
65d0: 74 68 65 20 6f 6e 6c 79 20 62 79 74 65 73 20 69  the only bytes i
65e0: 6e 20 61 0a 2a 2a 20 66 69 6c 65 20 74 68 61 74  n a.** file that
65f0: 20 77 65 72 65 20 77 72 69 74 74 65 6e 20 61 74   were written at
6600: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
6610: 20 6c 65 76 65 6c 20 6d 69 67 68 74 20 68 61 76   level might hav
6620: 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20 61 6e 64  e changed.** and
6630: 20 74 68 61 74 20 61 64 6a 61 63 65 6e 74 20 62   that adjacent b
6640: 79 74 65 73 2c 20 65 76 65 6e 20 62 79 74 65 73  ytes, even bytes
6650: 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65   within the same
6660: 20 73 65 63 74 6f 72 20 61 72 65 0a 2a 2a 20 67   sector are.** g
6670: 75 61 72 61 6e 74 65 65 64 20 74 6f 20 62 65 20  uaranteed to be 
6680: 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2f 0a 23 64  unchanged..*/.#d
6690: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
66a0: 41 50 5f 41 54 4f 4d 49 43 20 20 20 20 20 20 20  AP_ATOMIC       
66b0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
66c0: 30 30 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c  0001.#define SQL
66d0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
66e0: 35 31 32 20 20 20 20 20 20 20 20 20 20 20 20 20  512             
66f0: 20 30 78 30 30 30 30 30 30 30 32 0a 23 64 65 66   0x00000002.#def
6700: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
6710: 5f 41 54 4f 4d 49 43 31 4b 20 20 20 20 20 20 20  _ATOMIC1K       
6720: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
6730: 30 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  04.#define SQLIT
6740: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b  E_IOCAP_ATOMIC2K
6750: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
6760: 78 30 30 30 30 30 30 30 38 0a 23 64 65 66 69 6e  x00000008.#defin
6770: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
6780: 54 4f 4d 49 43 34 4b 20 20 20 20 20 20 20 20 20  TOMIC4K         
6790: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 31 30        0x00000010
67a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
67b0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 20 20  IOCAP_ATOMIC8K  
67c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
67d0: 30 30 30 30 30 32 30 0a 23 64 65 66 69 6e 65 20  0000020.#define 
67e0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
67f0: 4d 49 43 31 36 4b 20 20 20 20 20 20 20 20 20 20  MIC16K          
6800: 20 20 20 20 30 78 30 30 30 30 30 30 34 30 0a 23      0x00000040.#
6810: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
6820: 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 20 20 20  CAP_ATOMIC32K   
6830: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
6840: 30 30 30 38 30 0a 23 64 65 66 69 6e 65 20 53 51  00080.#define SQ
6850: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
6860: 43 36 34 4b 20 20 20 20 20 20 20 20 20 20 20 20  C64K            
6870: 20 20 30 78 30 30 30 30 30 31 30 30 0a 23 64 65    0x00000100.#de
6880: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
6890: 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 20 20  P_SAFE_APPEND   
68a0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
68b0: 32 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  200.#define SQLI
68c0: 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54  TE_IOCAP_SEQUENT
68d0: 49 41 4c 20 20 20 20 20 20 20 20 20 20 20 20 20  IAL             
68e0: 30 78 30 30 30 30 30 34 30 30 0a 23 64 65 66 69  0x00000400.#defi
68f0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
6900: 55 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e  UNDELETABLE_WHEN
6910: 5f 4f 50 45 4e 20 20 30 78 30 30 30 30 30 38 30  _OPEN  0x0000080
6920: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
6930: 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45  _IOCAP_POWERSAFE
6940: 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20 30 78  _OVERWRITE    0x
6950: 30 30 30 30 31 30 30 30 0a 0a 2f 2a 0a 2a 2a 20  00001000../*.** 
6960: 43 41 50 49 33 52 45 46 3a 20 46 69 6c 65 20 4c  CAPI3REF: File L
6970: 6f 63 6b 69 6e 67 20 4c 65 76 65 6c 73 0a 2a 2a  ocking Levels.**
6980: 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20  .** SQLite uses 
6990: 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 69 6e 74  one of these int
69a0: 65 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74  eger values as t
69b0: 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67  he second.** arg
69c0: 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73 20 69  ument to calls i
69d0: 74 20 6d 61 6b 65 73 20 74 6f 20 74 68 65 20 78  t makes to the x
69e0: 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f  Lock() and xUnlo
69f0: 63 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a 2a 20  ck() methods.** 
6a00: 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69  of an [sqlite3_i
6a10: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63  o_methods] objec
6a20: 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  t..*/.#define SQ
6a30: 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20  LITE_LOCK_NONE  
6a40: 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e          0.#defin
6a50: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48  e SQLITE_LOCK_SH
6a60: 41 52 45 44 20 20 20 20 20 20 20 20 31 0a 23 64  ARED        1.#d
6a70: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43  efine SQLITE_LOC
6a80: 4b 5f 52 45 53 45 52 56 45 44 20 20 20 20 20 20  K_RESERVED      
6a90: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
6aa0: 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 20 20  _LOCK_PENDING   
6ab0: 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51      3.#define SQ
6ac0: 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53  LITE_LOCK_EXCLUS
6ad0: 49 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a  IVE     4../*.**
6ae0: 20 43 41 50 49 33 52 45 46 3a 20 53 79 6e 63 68   CAPI3REF: Synch
6af0: 72 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70 65 20  ronization Type 
6b00: 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  Flags.**.** When
6b10: 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20   SQLite invokes 
6b20: 74 68 65 20 78 53 79 6e 63 28 29 20 6d 65 74 68  the xSync() meth
6b30: 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c  od of an.** [sql
6b40: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
6b50: 20 6f 62 6a 65 63 74 20 69 74 20 75 73 65 73 20   object it uses 
6b60: 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66  a combination of
6b70: 0a 2a 2a 20 74 68 65 73 65 20 69 6e 74 65 67 65  .** these intege
6b80: 72 20 76 61 6c 75 65 73 20 61 73 20 74 68 65 20  r values as the 
6b90: 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e  second argument.
6ba0: 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20  .**.** When the 
6bb0: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41  SQLITE_SYNC_DATA
6bc0: 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20 75 73 65  ONLY flag is use
6bd0: 64 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74  d, it means that
6be0: 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f 70 65   the.** sync ope
6bf0: 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64  ration only need
6c00: 73 20 74 6f 20 66 6c 75 73 68 20 64 61 74 61 20  s to flush data 
6c10: 74 6f 20 6d 61 73 73 20 73 74 6f 72 61 67 65 2e  to mass storage.
6c20: 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72    Inode.** infor
6c30: 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f 74 20  mation need not 
6c40: 62 65 20 66 6c 75 73 68 65 64 2e 20 49 66 20 74  be flushed. If t
6c50: 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69  he lower four bi
6c60: 74 73 20 6f 66 20 74 68 65 20 66 6c 61 67 0a 2a  ts of the flag.*
6c70: 2a 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53  * equal SQLITE_S
6c80: 59 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68 61 74  YNC_NORMAL, that
6c90: 20 6d 65 61 6e 73 20 74 6f 20 75 73 65 20 6e 6f   means to use no
6ca0: 72 6d 61 6c 20 66 73 79 6e 63 28 29 20 73 65 6d  rmal fsync() sem
6cb0: 61 6e 74 69 63 73 2e 0a 2a 2a 20 49 66 20 74 68  antics..** If th
6cc0: 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74  e lower four bit
6cd0: 73 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53  s equal SQLITE_S
6ce0: 59 4e 43 5f 46 55 4c 4c 2c 20 74 68 61 74 20 6d  YNC_FULL, that m
6cf0: 65 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65 20 4d  eans.** to use M
6d00: 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75  ac OS X style fu
6d10: 6c 6c 73 79 6e 63 20 69 6e 73 74 65 61 64 20 6f  llsync instead o
6d20: 66 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a  f fsync()..**.**
6d30: 20 44 6f 20 6e 6f 74 20 63 6f 6e 66 75 73 65 20   Do not confuse 
6d40: 74 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  the SQLITE_SYNC_
6d50: 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54  NORMAL and SQLIT
6d60: 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67  E_SYNC_FULL flag
6d70: 73 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 50  s.** with the [P
6d80: 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75  RAGMA synchronou
6d90: 73 5d 3d 4e 4f 52 4d 41 4c 20 61 6e 64 20 5b 50  s]=NORMAL and [P
6da0: 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75  RAGMA synchronou
6db0: 73 5d 3d 46 55 4c 4c 0a 2a 2a 20 73 65 74 74 69  s]=FULL.** setti
6dc0: 6e 67 73 2e 20 20 54 68 65 20 5b 73 79 6e 63 68  ngs.  The [synch
6dd0: 72 6f 6e 6f 75 73 20 70 72 61 67 6d 61 5d 20 64  ronous pragma] d
6de0: 65 74 65 72 6d 69 6e 65 73 20 77 68 65 6e 20 63  etermines when c
6df0: 61 6c 6c 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78  alls to the.** x
6e00: 53 79 6e 63 20 56 46 53 20 6d 65 74 68 6f 64 20  Sync VFS method 
6e10: 6f 63 63 75 72 20 61 6e 64 20 61 70 70 6c 69 65  occur and applie
6e20: 73 20 75 6e 69 66 6f 72 6d 6c 79 20 61 63 72 6f  s uniformly acro
6e30: 73 73 20 61 6c 6c 20 70 6c 61 74 66 6f 72 6d 73  ss all platforms
6e40: 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f  ..** The SQLITE_
6e50: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20  SYNC_NORMAL and 
6e60: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c  SQLITE_SYNC_FULL
6e70: 20 66 6c 61 67 73 20 64 65 74 65 72 6d 69 6e 65   flags determine
6e80: 20 68 6f 77 0a 2a 2a 20 65 6e 65 72 67 65 74 69   how.** energeti
6e90: 63 20 6f 72 20 72 69 67 6f 72 6f 75 73 20 6f 72  c or rigorous or
6ea0: 20 66 6f 72 63 65 66 75 6c 20 74 68 65 20 73 79   forceful the sy
6eb0: 6e 63 20 6f 70 65 72 61 74 69 6f 6e 73 20 61 72  nc operations ar
6ec0: 65 20 61 6e 64 0a 2a 2a 20 6f 6e 6c 79 20 6d 61  e and.** only ma
6ed0: 6b 65 20 61 20 64 69 66 66 65 72 65 6e 63 65 20  ke a difference 
6ee0: 6f 6e 20 4d 61 63 20 4f 53 58 20 66 6f 72 20 74  on Mac OSX for t
6ef0: 68 65 20 64 65 66 61 75 6c 74 20 53 51 4c 69 74  he default SQLit
6f00: 65 20 63 6f 64 65 2e 0a 2a 2a 20 28 54 68 69 72  e code..** (Thir
6f10: 64 2d 70 61 72 74 79 20 56 46 53 20 69 6d 70 6c  d-party VFS impl
6f20: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 69 67 68  ementations migh
6f30: 74 20 61 6c 73 6f 20 6d 61 6b 65 20 74 68 65 20  t also make the 
6f40: 64 69 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62  distinction.** b
6f50: 65 74 77 65 65 6e 20 53 51 4c 49 54 45 5f 53 59  etween SQLITE_SY
6f60: 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51  NC_NORMAL and SQ
6f70: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20  LITE_SYNC_FULL, 
6f80: 62 75 74 20 61 6d 6f 6e 67 20 74 68 65 0a 2a 2a  but among the.**
6f90: 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
6fa0: 6d 73 20 6e 61 74 69 76 65 6c 79 20 73 75 70 70  ms natively supp
6fb0: 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74 65 2c  orted by SQLite,
6fc0: 20 6f 6e 6c 79 20 4d 61 63 20 4f 53 58 0a 2a 2a   only Mac OSX.**
6fd0: 20 63 61 72 65 73 20 61 62 6f 75 74 20 74 68 65   cares about the
6fe0: 20 64 69 66 66 65 72 65 6e 63 65 2e 29 0a 2a 2f   difference.).*/
6ff0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
7000: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20  SYNC_NORMAL     
7010: 20 20 20 30 78 30 30 30 30 32 0a 23 64 65 66 69     0x00002.#defi
7020: 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46  ne SQLITE_SYNC_F
7030: 55 4c 4c 20 20 20 20 20 20 20 20 20 20 30 78 30  ULL          0x0
7040: 30 30 30 33 0a 23 64 65 66 69 6e 65 20 53 51 4c  0003.#define SQL
7050: 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c  ITE_SYNC_DATAONL
7060: 59 20 20 20 20 20 20 30 78 30 30 30 31 30 0a 0a  Y      0x00010..
7070: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
7080: 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f 70 65  OS Interface Ope
7090: 6e 20 46 69 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a  n File Handle.**
70a0: 0a 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f  .** An [sqlite3_
70b0: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65 70  file] object rep
70c0: 72 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20  resents an open 
70d0: 66 69 6c 65 20 69 6e 20 74 68 65 20 0a 2a 2a 20  file in the .** 
70e0: 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 4f  [sqlite3_vfs | O
70f0: 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65  S interface laye
7100: 72 5d 2e 20 20 49 6e 64 69 76 69 64 75 61 6c 20  r].  Individual 
7110: 4f 53 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  OS interface.** 
7120: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
7130: 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f 20  will.** want to 
7140: 73 75 62 63 6c 61 73 73 20 74 68 69 73 20 6f 62  subclass this ob
7150: 6a 65 63 74 20 62 79 20 61 70 70 65 6e 64 69 6e  ject by appendin
7160: 67 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65  g additional fie
7170: 6c 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65 69 72  lds.** for their
7180: 20 6f 77 6e 20 75 73 65 2e 20 20 54 68 65 20 70   own use.  The p
7190: 4d 65 74 68 6f 64 73 20 65 6e 74 72 79 20 69 73  Methods entry is
71a0: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
71b0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  .** [sqlite3_io_
71c0: 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20  methods] object 
71d0: 74 68 61 74 20 64 65 66 69 6e 65 73 20 6d 65 74  that defines met
71e0: 68 6f 64 73 20 66 6f 72 20 70 65 72 66 6f 72 6d  hods for perform
71f0: 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72 61  ing.** I/O opera
7200: 74 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70 65  tions on the ope
7210: 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64  n file..*/.typed
7220: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
7230: 33 5f 66 69 6c 65 20 73 71 6c 69 74 65 33 5f 66  3_file sqlite3_f
7240: 69 6c 65 3b 0a 73 74 72 75 63 74 20 73 71 6c 69  ile;.struct sqli
7250: 74 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f 6e  te3_file {.  con
7260: 73 74 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  st struct sqlite
7270: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70 4d  3_io_methods *pM
7280: 65 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74 68  ethods;  /* Meth
7290: 6f 64 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e 20  ods for an open 
72a0: 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a  file */.};../*.*
72b0: 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49  * CAPI3REF: OS I
72c0: 6e 74 65 72 66 61 63 65 20 46 69 6c 65 20 56 69  nterface File Vi
72d0: 72 74 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f 62  rtual Methods Ob
72e0: 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79  ject.**.** Every
72f0: 20 66 69 6c 65 20 6f 70 65 6e 65 64 20 62 79 20   file opened by 
7300: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  the [sqlite3_vfs
7310: 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20 70  .xOpen] method p
7320: 6f 70 75 6c 61 74 65 73 20 61 6e 0a 2a 2a 20 5b  opulates an.** [
7330: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62  sqlite3_file] ob
7340: 6a 65 63 74 20 28 6f 72 2c 20 6d 6f 72 65 20 63  ject (or, more c
7350: 6f 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 63 6c  ommonly, a subcl
7360: 61 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73  ass of the.** [s
7370: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a  qlite3_file] obj
7380: 65 63 74 29 20 77 69 74 68 20 61 20 70 6f 69 6e  ect) with a poin
7390: 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e  ter to an instan
73a0: 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63  ce of this objec
73b0: 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63  t..** This objec
73c0: 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 6d 65  t defines the me
73d0: 74 68 6f 64 73 20 75 73 65 64 20 74 6f 20 70 65  thods used to pe
73e0: 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f 70  rform various op
73f0: 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 61 69  erations.** agai
7400: 6e 73 74 20 74 68 65 20 6f 70 65 6e 20 66 69 6c  nst the open fil
7410: 65 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79  e represented by
7420: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69   the [sqlite3_fi
7430: 6c 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a  le] object..**.*
7440: 2a 20 49 66 20 74 68 65 20 5b 73 71 6c 69 74 65  * If the [sqlite
7450: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74  3_vfs.xOpen] met
7460: 68 6f 64 20 73 65 74 73 20 74 68 65 20 73 71 6c  hod sets the sql
7470: 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f  ite3_file.pMetho
7480: 64 73 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20 74  ds element .** t
7490: 6f 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69  o a non-NULL poi
74a0: 6e 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20 73  nter, then the s
74b0: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
74c0: 73 2e 78 43 6c 6f 73 65 20 6d 65 74 68 6f 64 0a  s.xClose method.
74d0: 2a 2a 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65  ** may be invoke
74e0: 64 20 65 76 65 6e 20 69 66 20 74 68 65 20 5b 73  d even if the [s
74f0: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e  qlite3_vfs.xOpen
7500: 5d 20 72 65 70 6f 72 74 65 64 20 74 68 61 74 20  ] reported that 
7510: 69 74 20 66 61 69 6c 65 64 2e 20 20 54 68 65 0a  it failed.  The.
7520: 2a 2a 20 6f 6e 6c 79 20 77 61 79 20 74 6f 20 70  ** only way to p
7530: 72 65 76 65 6e 74 20 61 20 63 61 6c 6c 20 74 6f  revent a call to
7540: 20 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f 77 69 6e   xClose followin
7550: 67 20 61 20 66 61 69 6c 65 64 20 5b 73 71 6c 69  g a failed [sqli
7560: 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 0a 2a  te3_vfs.xOpen].*
7570: 2a 20 69 73 20 66 6f 72 20 74 68 65 20 5b 73 71  * is for the [sq
7580: 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d  lite3_vfs.xOpen]
7590: 20 74 6f 20 73 65 74 20 74 68 65 20 73 71 6c 69   to set the sqli
75a0: 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64  te3_file.pMethod
75b0: 73 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 74 6f 20  s element.** to 
75c0: 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  NULL..**.** The 
75d0: 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74  flags argument t
75e0: 6f 20 78 53 79 6e 63 20 6d 61 79 20 62 65 20 6f  o xSync may be o
75f0: 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53 59  ne of [SQLITE_SY
7600: 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a  NC_NORMAL] or.**
7610: 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55   [SQLITE_SYNC_FU
7620: 4c 4c 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20  LL].  The first 
7630: 63 68 6f 69 63 65 20 69 73 20 74 68 65 20 6e 6f  choice is the no
7640: 72 6d 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a 2a  rmal fsync()..**
7650: 20 54 68 65 20 73 65 63 6f 6e 64 20 63 68 6f 69   The second choi
7660: 63 65 20 69 73 20 61 20 4d 61 63 20 4f 53 20 58  ce is a Mac OS X
7670: 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 2e   style fullsync.
7680: 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 53 59    The [SQLITE_SY
7690: 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20  NC_DATAONLY].** 
76a0: 66 6c 61 67 20 6d 61 79 20 62 65 20 4f 52 65 64  flag may be ORed
76b0: 20 69 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20   in to indicate 
76c0: 74 68 61 74 20 6f 6e 6c 79 20 74 68 65 20 64 61  that only the da
76d0: 74 61 20 6f 66 20 74 68 65 20 66 69 6c 65 0a 2a  ta of the file.*
76e0: 2a 20 61 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e  * and not its in
76f0: 6f 64 65 20 6e 65 65 64 73 20 74 6f 20 62 65 20  ode needs to be 
7700: 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  synced..**.** Th
7710: 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73  e integer values
7720: 20 74 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20   to xLock() and 
7730: 78 55 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f 6e  xUnlock() are on
7740: 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  e of.** <ul>.** 
7750: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
7760: 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e  K_NONE],.** <li>
7770: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48   [SQLITE_LOCK_SH
7780: 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b  ARED],.** <li> [
7790: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45  SQLITE_LOCK_RESE
77a0: 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b  RVED],.** <li> [
77b0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44  SQLITE_LOCK_PEND
77c0: 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e  ING], or.** <li>
77d0: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58   [SQLITE_LOCK_EX
77e0: 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75  CLUSIVE]..** </u
77f0: 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 6e  l>.** xLock() in
7800: 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b  creases the lock
7810: 2e 20 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63 72  . xUnlock() decr
7820: 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 0a  eases the lock..
7830: 2a 2a 20 54 68 65 20 78 43 68 65 63 6b 52 65 73  ** The xCheckRes
7840: 65 72 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74 68  ervedLock() meth
7850: 6f 64 20 63 68 65 63 6b 73 20 77 68 65 74 68 65  od checks whethe
7860: 72 20 61 6e 79 20 64 61 74 61 62 61 73 65 20 63  r any database c
7870: 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69  onnection,.** ei
7880: 74 68 65 72 20 69 6e 20 74 68 69 73 20 70 72 6f  ther in this pro
7890: 63 65 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65 20  cess or in some 
78a0: 6f 74 68 65 72 20 70 72 6f 63 65 73 73 2c 20 69  other process, i
78b0: 73 20 68 6f 6c 64 69 6e 67 20 61 20 52 45 53 45  s holding a RESE
78c0: 52 56 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47  RVED,.** PENDING
78d0: 2c 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 6c  , or EXCLUSIVE l
78e0: 6f 63 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65 2e  ock on the file.
78f0: 20 20 49 74 20 72 65 74 75 72 6e 73 20 74 72 75    It returns tru
7900: 65 0a 2a 2a 20 69 66 20 73 75 63 68 20 61 20 6c  e.** if such a l
7910: 6f 63 6b 20 65 78 69 73 74 73 20 61 6e 64 20 66  ock exists and f
7920: 61 6c 73 65 20 6f 74 68 65 72 77 69 73 65 2e 0a  alse otherwise..
7930: 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65 43  **.** The xFileC
7940: 6f 6e 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64 20  ontrol() method 
7950: 69 73 20 61 20 67 65 6e 65 72 69 63 20 69 6e 74  is a generic int
7960: 65 72 66 61 63 65 20 74 68 61 74 20 61 6c 6c 6f  erface that allo
7970: 77 73 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 53  ws custom.** VFS
7980: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
7990: 20 74 6f 20 64 69 72 65 63 74 6c 79 20 63 6f 6e   to directly con
79a0: 74 72 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69 6c  trol an open fil
79b0: 65 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b  e using the.** [
79c0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
79d0: 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61 63  trol()] interfac
79e0: 65 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 22  e.  The second "
79f0: 6f 70 22 20 61 72 67 75 6d 65 6e 74 20 69 73 20  op" argument is 
7a00: 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6f 70  an.** integer op
7a10: 63 6f 64 65 2e 20 20 54 68 65 20 74 68 69 72 64  code.  The third
7a20: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 67   argument is a g
7a30: 65 6e 65 72 69 63 20 70 6f 69 6e 74 65 72 20 69  eneric pointer i
7a40: 6e 74 65 6e 64 65 64 20 74 6f 0a 2a 2a 20 70 6f  ntended to.** po
7a50: 69 6e 74 20 74 6f 20 61 20 73 74 72 75 63 74 75  int to a structu
7a60: 72 65 20 74 68 61 74 20 6d 61 79 20 63 6f 6e 74  re that may cont
7a70: 61 69 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f 72  ain arguments or
7a80: 20 73 70 61 63 65 20 69 6e 20 77 68 69 63 68 20   space in which 
7a90: 74 6f 0a 2a 2a 20 77 72 69 74 65 20 72 65 74 75  to.** write retu
7aa0: 72 6e 20 76 61 6c 75 65 73 2e 20 20 50 6f 74 65  rn values.  Pote
7ab0: 6e 74 69 61 6c 20 75 73 65 73 20 66 6f 72 20 78  ntial uses for x
7ac0: 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 69  FileControl() mi
7ad0: 67 68 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74 69  ght be.** functi
7ae0: 6f 6e 73 20 74 6f 20 65 6e 61 62 6c 65 20 62 6c  ons to enable bl
7af0: 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69 74  ocking locks wit
7b00: 68 20 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20 63  h timeouts, to c
7b10: 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f 63  hange the.** loc
7b20: 6b 69 6e 67 20 73 74 72 61 74 65 67 79 20 28 66  king strategy (f
7b30: 6f 72 20 65 78 61 6d 70 6c 65 20 74 6f 20 75 73  or example to us
7b40: 65 20 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 73  e dot-file locks
7b50: 29 2c 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a 2a  ), to inquire.**
7b60: 20 61 62 6f 75 74 20 74 68 65 20 73 74 61 74 75   about the statu
7b70: 73 20 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 20  s of a lock, or 
7b80: 74 6f 20 62 72 65 61 6b 20 73 74 61 6c 65 20 6c  to break stale l
7b90: 6f 63 6b 73 2e 20 20 54 68 65 20 53 51 4c 69 74  ocks.  The SQLit
7ba0: 65 0a 2a 2a 20 63 6f 72 65 20 72 65 73 65 72 76  e.** core reserv
7bb0: 65 73 20 61 6c 6c 20 6f 70 63 6f 64 65 73 20 6c  es all opcodes l
7bc0: 65 73 73 20 74 68 61 6e 20 31 30 30 20 66 6f 72  ess than 100 for
7bd0: 20 69 74 73 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a   its own use..**
7be0: 20 41 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c   A [SQLITE_FCNTL
7bf0: 5f 4c 4f 43 4b 53 54 41 54 45 20 7c 20 6c 69 73  _LOCKSTATE | lis
7c00: 74 20 6f 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65  t of opcodes] le
7c10: 73 73 20 74 68 61 6e 20 31 30 30 20 69 73 20 61  ss than 100 is a
7c20: 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 70  vailable..** App
7c30: 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 64  lications that d
7c40: 65 66 69 6e 65 20 61 20 63 75 73 74 6f 6d 20 78  efine a custom x
7c50: 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68  FileControl meth
7c60: 6f 64 20 73 68 6f 75 6c 64 20 75 73 65 20 6f 70  od should use op
7c70: 63 6f 64 65 73 0a 2a 2a 20 67 72 65 61 74 65 72  codes.** greater
7c80: 20 74 68 61 6e 20 31 30 30 20 74 6f 20 61 76 6f   than 100 to avo
7c90: 69 64 20 63 6f 6e 66 6c 69 63 74 73 2e 20 20 56  id conflicts.  V
7ca0: 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  FS implementatio
7cb0: 6e 73 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74  ns should.** ret
7cc0: 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46  urn [SQLITE_NOTF
7cd0: 4f 55 4e 44 5d 20 66 6f 72 20 66 69 6c 65 20 63  OUND] for file c
7ce0: 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20 74  ontrol opcodes t
7cf0: 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a  hat they do not.
7d00: 2a 2a 20 72 65 63 6f 67 6e 69 7a 65 2e 0a 2a 2a  ** recognize..**
7d10: 0a 2a 2a 20 54 68 65 20 78 53 65 63 74 6f 72 53  .** The xSectorS
7d20: 69 7a 65 28 29 20 6d 65 74 68 6f 64 20 72 65 74  ize() method ret
7d30: 75 72 6e 73 20 74 68 65 20 73 65 63 74 6f 72 20  urns the sector 
7d40: 73 69 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20 64  size of the.** d
7d50: 65 76 69 63 65 20 74 68 61 74 20 75 6e 64 65 72  evice that under
7d60: 6c 69 65 73 20 74 68 65 20 66 69 6c 65 2e 20 20  lies the file.  
7d70: 54 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20  The sector size 
7d80: 69 73 20 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75  is the.** minimu
7d90: 6d 20 77 72 69 74 65 20 74 68 61 74 20 63 61 6e  m write that can
7da0: 20 62 65 20 70 65 72 66 6f 72 6d 65 64 20 77 69   be performed wi
7db0: 74 68 6f 75 74 20 64 69 73 74 75 72 62 69 6e 67  thout disturbing
7dc0: 0a 2a 2a 20 6f 74 68 65 72 20 62 79 74 65 73 20  .** other bytes 
7dd0: 69 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68  in the file.  Th
7de0: 65 20 78 44 65 76 69 63 65 43 68 61 72 61 63 74  e xDeviceCharact
7df0: 65 72 69 73 74 69 63 73 28 29 0a 2a 2a 20 6d 65  eristics().** me
7e00: 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 62  thod returns a b
7e10: 69 74 20 76 65 63 74 6f 72 20 64 65 73 63 72 69  it vector descri
7e20: 62 69 6e 67 20 62 65 68 61 76 69 6f 72 73 20 6f  bing behaviors o
7e30: 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79  f the.** underly
7e40: 69 6e 67 20 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a  ing device:.**.*
7e50: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b  * <ul>.** <li> [
7e60: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
7e70: 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  MIC].** <li> [SQ
7e80: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
7e90: 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  C512].** <li> [S
7ea0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
7eb0: 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  IC1K].** <li> [S
7ec0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
7ed0: 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  IC2K].** <li> [S
7ee0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
7ef0: 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  IC4K].** <li> [S
7f00: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
7f10: 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  IC8K].** <li> [S
7f20: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
7f30: 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  IC16K].** <li> [
7f40: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
7f50: 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  MIC32K].** <li> 
7f60: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
7f70: 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e  OMIC64K].** <li>
7f80: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53   [SQLITE_IOCAP_S
7f90: 41 46 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c  AFE_APPEND].** <
7fa0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
7fb0: 50 5f 53 45 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a  P_SEQUENTIAL].**
7fc0: 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65   </ul>.**.** The
7fd0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
7fe0: 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65  OMIC property me
7ff0: 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69  ans that all wri
8000: 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69  tes of.** any si
8010: 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  ze are atomic.  
8020: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
8030: 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65  _ATOMICnnn value
8040: 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77  s.** mean that w
8050: 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20  rites of blocks 
8060: 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74  that are nnn byt
8070: 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a  es in size and.*
8080: 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f  * are aligned to
8090: 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63   an address whic
80a0: 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  h is an integer 
80b0: 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e  multiple of.** n
80c0: 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  nn are atomic.  
80d0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
80e0: 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c  _SAFE_APPEND val
80f0: 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74  ue means.** that
8100: 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70   when data is ap
8110: 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65  pended to a file
8120: 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70  , the data is ap
8130: 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20  pended.** first 
8140: 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66  then the size of
8150: 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74   the file is ext
8160: 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65  ended, never the
8170: 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72   other.** way ar
8180: 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54  ound.  The SQLIT
8190: 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49  E_IOCAP_SEQUENTI
81a0: 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e  AL property mean
81b0: 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d  s that.** inform
81c0: 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e  ation is written
81d0: 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20   to disk in the 
81e0: 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61  same order as ca
81f0: 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65  lls.** to xWrite
8200: 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 78 52 65  ()..**.** If xRe
8210: 61 64 28 29 20 72 65 74 75 72 6e 73 20 53 51 4c  ad() returns SQL
8220: 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f  ITE_IOERR_SHORT_
8230: 52 45 41 44 20 69 74 20 6d 75 73 74 20 61 6c 73  READ it must als
8240: 6f 20 66 69 6c 6c 0a 2a 2a 20 69 6e 20 74 68 65  o fill.** in the
8250: 20 75 6e 72 65 61 64 20 70 6f 72 74 69 6f 6e 73   unread portions
8260: 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 20 77   of the buffer w
8270: 69 74 68 20 7a 65 72 6f 73 2e 20 20 41 20 56 46  ith zeros.  A VF
8280: 53 20 74 68 61 74 0a 2a 2a 20 66 61 69 6c 73 20  S that.** fails 
8290: 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f  to zero-fill sho
82a0: 72 74 20 72 65 61 64 73 20 6d 69 67 68 74 20 73  rt reads might s
82b0: 65 65 6d 20 74 6f 20 77 6f 72 6b 2e 20 20 48 6f  eem to work.  Ho
82c0: 77 65 76 65 72 2c 0a 2a 2a 20 66 61 69 6c 75 72  wever,.** failur
82d0: 65 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73  e to zero-fill s
82e0: 68 6f 72 74 20 72 65 61 64 73 20 77 69 6c 6c 20  hort reads will 
82f0: 65 76 65 6e 74 75 61 6c 6c 79 20 6c 65 61 64 20  eventually lead 
8300: 74 6f 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  to.** database c
8310: 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 74 79  orruption..*/.ty
8320: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
8330: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20  ite3_io_methods 
8340: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
8350: 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74  ds;.struct sqlit
8360: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a  e3_io_methods {.
8370: 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a    int iVersion;.
8380: 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28    int (*xClose)(
8390: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a  sqlite3_file*);.
83a0: 20 20 69 6e 74 20 28 2a 78 52 65 61 64 29 28 73    int (*xRead)(s
83b0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 76 6f  qlite3_file*, vo
83c0: 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73  id*, int iAmt, s
83d0: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66  qlite3_int64 iOf
83e0: 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 57 72  st);.  int (*xWr
83f0: 69 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ite)(sqlite3_fil
8400: 65 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  e*, const void*,
8410: 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74   int iAmt, sqlit
8420: 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b  e3_int64 iOfst);
8430: 0a 20 20 69 6e 74 20 28 2a 78 54 72 75 6e 63 61  .  int (*xTrunca
8440: 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  te)(sqlite3_file
8450: 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
8460: 20 73 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a   size);.  int (*
8470: 78 53 79 6e 63 29 28 73 71 6c 69 74 65 33 5f 66  xSync)(sqlite3_f
8480: 69 6c 65 2a 2c 20 69 6e 74 20 66 6c 61 67 73 29  ile*, int flags)
8490: 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 53  ;.  int (*xFileS
84a0: 69 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ize)(sqlite3_fil
84b0: 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  e*, sqlite3_int6
84c0: 34 20 2a 70 53 69 7a 65 29 3b 0a 20 20 69 6e 74  4 *pSize);.  int
84d0: 20 28 2a 78 4c 6f 63 6b 29 28 73 71 6c 69 74 65   (*xLock)(sqlite
84e0: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20  3_file*, int);. 
84f0: 20 69 6e 74 20 28 2a 78 55 6e 6c 6f 63 6b 29 28   int (*xUnlock)(
8500: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
8510: 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 68  nt);.  int (*xCh
8520: 65 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 29  eckReservedLock)
8530: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
8540: 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20  int *pResOut);. 
8550: 20 69 6e 74 20 28 2a 78 46 69 6c 65 43 6f 6e 74   int (*xFileCont
8560: 72 6f 6c 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  rol)(sqlite3_fil
8570: 65 2a 2c 20 69 6e 74 20 6f 70 2c 20 76 6f 69 64  e*, int op, void
8580: 20 2a 70 41 72 67 29 3b 0a 20 20 69 6e 74 20 28   *pArg);.  int (
8590: 2a 78 53 65 63 74 6f 72 53 69 7a 65 29 28 73 71  *xSectorSize)(sq
85a0: 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20  lite3_file*);.  
85b0: 69 6e 74 20 28 2a 78 44 65 76 69 63 65 43 68 61  int (*xDeviceCha
85c0: 72 61 63 74 65 72 69 73 74 69 63 73 29 28 73 71  racteristics)(sq
85d0: 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20  lite3_file*);.  
85e0: 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65  /* Methods above
85f0: 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76   are valid for v
8600: 65 72 73 69 6f 6e 20 31 20 2a 2f 0a 20 20 69 6e  ersion 1 */.  in
8610: 74 20 28 2a 78 53 68 6d 4d 61 70 29 28 73 71 6c  t (*xShmMap)(sql
8620: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20  ite3_file*, int 
8630: 69 50 67 2c 20 69 6e 74 20 70 67 73 7a 2c 20 69  iPg, int pgsz, i
8640: 6e 74 2c 20 76 6f 69 64 20 76 6f 6c 61 74 69 6c  nt, void volatil
8650: 65 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53  e**);.  int (*xS
8660: 68 6d 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f  hmLock)(sqlite3_
8670: 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 66 66 73 65  file*, int offse
8680: 74 2c 20 69 6e 74 20 6e 2c 20 69 6e 74 20 66 6c  t, int n, int fl
8690: 61 67 73 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78  ags);.  void (*x
86a0: 53 68 6d 42 61 72 72 69 65 72 29 28 73 71 6c 69  ShmBarrier)(sqli
86b0: 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e  te3_file*);.  in
86c0: 74 20 28 2a 78 53 68 6d 55 6e 6d 61 70 29 28 73  t (*xShmUnmap)(s
86d0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
86e0: 74 20 64 65 6c 65 74 65 46 6c 61 67 29 3b 0a 20  t deleteFlag);. 
86f0: 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76   /* Methods abov
8700: 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20  e are valid for 
8710: 76 65 72 73 69 6f 6e 20 32 20 2a 2f 0a 20 20 69  version 2 */.  i
8720: 6e 74 20 28 2a 78 46 65 74 63 68 29 28 73 71 6c  nt (*xFetch)(sql
8730: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69  ite3_file*, sqli
8740: 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 2c  te3_int64 iOfst,
8750: 20 69 6e 74 20 69 41 6d 74 2c 20 76 6f 69 64 20   int iAmt, void 
8760: 2a 2a 70 70 29 3b 0a 20 20 69 6e 74 20 28 2a 78  **pp);.  int (*x
8770: 55 6e 66 65 74 63 68 29 28 73 71 6c 69 74 65 33  Unfetch)(sqlite3
8780: 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f  _file*, sqlite3_
8790: 69 6e 74 36 34 20 69 4f 66 73 74 2c 20 76 6f 69  int64 iOfst, voi
87a0: 64 20 2a 70 29 3b 0a 20 20 2f 2a 20 4d 65 74 68  d *p);.  /* Meth
87b0: 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 76 61  ods above are va
87c0: 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20  lid for version 
87d0: 33 20 2a 2f 0a 20 20 2f 2a 20 41 64 64 69 74 69  3 */.  /* Additi
87e0: 6f 6e 61 6c 20 6d 65 74 68 6f 64 73 20 6d 61 79  onal methods may
87f0: 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74   be added in fut
8800: 75 72 65 20 72 65 6c 65 61 73 65 73 20 2a 2f 0a  ure releases */.
8810: 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  };../*.** CAPI3R
8820: 45 46 3a 20 53 74 61 6e 64 61 72 64 20 46 69 6c  EF: Standard Fil
8830: 65 20 43 6f 6e 74 72 6f 6c 20 4f 70 63 6f 64 65  e Control Opcode
8840: 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e  s.**.** These in
8850: 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20  teger constants 
8860: 61 72 65 20 6f 70 63 6f 64 65 73 20 66 6f 72 20  are opcodes for 
8870: 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  the xFileControl
8880: 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68   method.** of th
8890: 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  e [sqlite3_io_me
88a0: 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 61 6e  thods] object an
88b0: 64 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74  d for the [sqlit
88c0: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
88d0: 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e  )].** interface.
88e0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  .**.** The [SQLI
88f0: 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41  TE_FCNTL_LOCKSTA
8900: 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73  TE] opcode is us
8910: 65 64 20 66 6f 72 20 64 65 62 75 67 67 69 6e 67  ed for debugging
8920: 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64  .  This.** opcod
8930: 65 20 63 61 75 73 65 73 20 74 68 65 20 78 46 69  e causes the xFi
8940: 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64  leControl method
8950: 20 74 6f 20 77 72 69 74 65 20 74 68 65 20 63 75   to write the cu
8960: 72 72 65 6e 74 20 73 74 61 74 65 20 6f 66 0a 2a  rrent state of.*
8970: 2a 20 74 68 65 20 6c 6f 63 6b 20 28 6f 6e 65 20  * the lock (one 
8980: 6f 66 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  of [SQLITE_LOCK_
8990: 4e 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c  NONE], [SQLITE_L
89a0: 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20  OCK_SHARED],.** 
89b0: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53  [SQLITE_LOCK_RES
89c0: 45 52 56 45 44 5d 2c 20 5b 53 51 4c 49 54 45 5f  ERVED], [SQLITE_
89d0: 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f  LOCK_PENDING], o
89e0: 72 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45  r [SQLITE_LOCK_E
89f0: 58 43 4c 55 53 49 56 45 5d 29 0a 2a 2a 20 69 6e  XCLUSIVE]).** in
8a00: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 74 68  to an integer th
8a10: 61 74 20 74 68 65 20 70 41 72 67 20 61 72 67 75  at the pArg argu
8a20: 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 2e 20  ment points to. 
8a30: 54 68 69 73 20 63 61 70 61 62 69 6c 69 74 79 0a  This capability.
8a40: 2a 2a 20 69 73 20 75 73 65 64 20 64 75 72 69 6e  ** is used durin
8a50: 67 20 74 65 73 74 69 6e 67 20 61 6e 64 20 6f 6e  g testing and on
8a60: 6c 79 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73  ly needs to be s
8a70: 75 70 70 6f 72 74 65 64 20 77 68 65 6e 20 53 51  upported when SQ
8a80: 4c 49 54 45 5f 54 45 53 54 0a 2a 2a 20 69 73 20  LITE_TEST.** is 
8a90: 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 3c 75 6c 3e  defined..** <ul>
8aa0: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
8ab0: 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54  _FCNTL_SIZE_HINT
8ac0: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
8ad0: 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e  E_FCNTL_SIZE_HIN
8ae0: 54 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65  T] opcode is use
8af0: 64 20 62 79 20 53 51 4c 69 74 65 20 74 6f 20 67  d by SQLite to g
8b00: 69 76 65 20 74 68 65 20 56 46 53 0a 2a 2a 20 6c  ive the VFS.** l
8b10: 61 79 65 72 20 61 20 68 69 6e 74 20 6f 66 20 68  ayer a hint of h
8b20: 6f 77 20 6c 61 72 67 65 20 74 68 65 20 64 61 74  ow large the dat
8b30: 61 62 61 73 65 20 66 69 6c 65 20 77 69 6c 6c 20  abase file will 
8b40: 67 72 6f 77 20 74 6f 20 62 65 20 64 75 72 69 6e  grow to be durin
8b50: 67 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74  g the.** current
8b60: 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 20 54   transaction.  T
8b70: 68 69 73 20 68 69 6e 74 20 69 73 20 6e 6f 74 20  his hint is not 
8b80: 67 75 61 72 61 6e 74 65 65 64 20 74 6f 20 62 65  guaranteed to be
8b90: 20 61 63 63 75 72 61 74 65 20 62 75 74 20 69 74   accurate but it
8ba0: 0a 2a 2a 20 69 73 20 6f 66 74 65 6e 20 63 6c 6f  .** is often clo
8bb0: 73 65 2e 20 20 54 68 65 20 75 6e 64 65 72 6c 79  se.  The underly
8bc0: 69 6e 67 20 56 46 53 20 6d 69 67 68 74 20 63 68  ing VFS might ch
8bd0: 6f 6f 73 65 20 74 6f 20 70 72 65 61 6c 6c 6f 63  oose to prealloc
8be0: 61 74 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  ate database.** 
8bf0: 66 69 6c 65 20 73 70 61 63 65 20 62 61 73 65 64  file space based
8c00: 20 6f 6e 20 74 68 69 73 20 68 69 6e 74 20 69 6e   on this hint in
8c10: 20 6f 72 64 65 72 20 74 6f 20 68 65 6c 70 20 77   order to help w
8c20: 72 69 74 65 73 20 74 6f 20 74 68 65 20 64 61 74  rites to the dat
8c30: 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 72 75  abase.** file ru
8c40: 6e 20 66 61 73 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  n faster..**.** 
8c50: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
8c60: 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 5d 0a  TL_CHUNK_SIZE]].
8c70: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
8c80: 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d  CNTL_CHUNK_SIZE]
8c90: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20   opcode is used 
8ca0: 74 6f 20 72 65 71 75 65 73 74 20 74 68 61 74 20  to request that 
8cb0: 74 68 65 20 56 46 53 0a 2a 2a 20 65 78 74 65 6e  the VFS.** exten
8cc0: 64 73 20 61 6e 64 20 74 72 75 6e 63 61 74 65 73  ds and truncates
8cd0: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
8ce0: 6c 65 20 69 6e 20 63 68 75 6e 6b 73 20 6f 66 20  le in chunks of 
8cf0: 61 20 73 69 7a 65 20 73 70 65 63 69 66 69 65 64  a size specified
8d00: 0a 2a 2a 20 62 79 20 74 68 65 20 75 73 65 72 2e  .** by the user.
8d10: 20 54 68 65 20 66 6f 75 72 74 68 20 61 72 67 75   The fourth argu
8d20: 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  ment to [sqlite3
8d30: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d  _file_control()]
8d40: 20 73 68 6f 75 6c 64 20 0a 2a 2a 20 70 6f 69 6e   should .** poin
8d50: 74 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20  t to an integer 
8d60: 28 74 79 70 65 20 69 6e 74 29 20 63 6f 6e 74 61  (type int) conta
8d70: 69 6e 69 6e 67 20 74 68 65 20 6e 65 77 20 63 68  ining the new ch
8d80: 75 6e 6b 2d 73 69 7a 65 20 74 6f 20 75 73 65 0a  unk-size to use.
8d90: 2a 2a 20 66 6f 72 20 74 68 65 20 6e 6f 6d 69 6e  ** for the nomin
8da0: 61 74 65 64 20 64 61 74 61 62 61 73 65 2e 20 41  ated database. A
8db0: 6c 6c 6f 63 61 74 69 6e 67 20 64 61 74 61 62 61  llocating databa
8dc0: 73 65 20 66 69 6c 65 20 73 70 61 63 65 20 69 6e  se file space in
8dd0: 20 6c 61 72 67 65 0a 2a 2a 20 63 68 75 6e 6b 73   large.** chunks
8de0: 20 28 73 61 79 20 31 4d 42 20 61 74 20 61 20 74   (say 1MB at a t
8df0: 69 6d 65 29 2c 20 6d 61 79 20 72 65 64 75 63 65  ime), may reduce
8e00: 20 66 69 6c 65 2d 73 79 73 74 65 6d 20 66 72 61   file-system fra
8e10: 67 6d 65 6e 74 61 74 69 6f 6e 20 61 6e 64 0a 2a  gmentation and.*
8e20: 2a 20 69 6d 70 72 6f 76 65 20 70 65 72 66 6f 72  * improve perfor
8e30: 6d 61 6e 63 65 20 6f 6e 20 73 6f 6d 65 20 73 79  mance on some sy
8e40: 73 74 65 6d 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  stems..**.** <li
8e50: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
8e60: 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a  FILE_POINTER]].*
8e70: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
8e80: 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52  NTL_FILE_POINTER
8e90: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64  ] opcode is used
8ea0: 20 74 6f 20 6f 62 74 61 69 6e 20 61 20 70 6f 69   to obtain a poi
8eb0: 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b  nter.** to the [
8ec0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62  sqlite3_file] ob
8ed0: 6a 65 63 74 20 61 73 73 6f 63 69 61 74 65 64 20  ject associated 
8ee0: 77 69 74 68 20 61 20 70 61 72 74 69 63 75 6c 61  with a particula
8ef0: 72 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f  r database.** co
8f00: 6e 6e 65 63 74 69 6f 6e 2e 20 20 53 65 65 20 74  nnection.  See t
8f10: 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  he [sqlite3_file
8f20: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 64 6f 63 75  _control()] docu
8f30: 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a  mentation for.**
8f40: 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f   additional info
8f50: 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c  rmation..**.** <
8f60: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
8f70: 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 5d 5d  L_SYNC_OMITTED]]
8f80: 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c 49 54  .** ^(The [SQLIT
8f90: 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49  E_FCNTL_SYNC_OMI
8fa0: 54 54 45 44 5d 20 6f 70 63 6f 64 65 20 69 73 20  TTED] opcode is 
8fb0: 67 65 6e 65 72 61 74 65 64 20 69 6e 74 65 72 6e  generated intern
8fc0: 61 6c 6c 79 20 62 79 0a 2a 2a 20 53 51 4c 69 74  ally by.** SQLit
8fd0: 65 20 61 6e 64 20 73 65 6e 74 20 74 6f 20 61 6c  e and sent to al
8fe0: 6c 20 56 46 53 65 73 20 69 6e 20 70 6c 61 63 65  l VFSes in place
8ff0: 20 6f 66 20 61 20 63 61 6c 6c 20 74 6f 20 74 68   of a call to th
9000: 65 20 78 53 79 6e 63 20 6d 65 74 68 6f 64 0a 2a  e xSync method.*
9010: 2a 20 77 68 65 6e 20 74 68 65 20 64 61 74 61 62  * when the datab
9020: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 68  ase connection h
9030: 61 73 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68  as [PRAGMA synch
9040: 72 6f 6e 6f 75 73 5d 20 73 65 74 20 74 6f 20 4f  ronous] set to O
9050: 46 46 2e 29 5e 0a 2a 2a 20 53 6f 6d 65 20 73 70  FF.)^.** Some sp
9060: 65 63 69 61 6c 69 7a 65 64 20 56 46 53 65 73 20  ecialized VFSes 
9070: 6e 65 65 64 20 74 68 69 73 20 73 69 67 6e 61 6c  need this signal
9080: 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 6f 70 65   in order to ope
9090: 72 61 74 65 20 63 6f 72 72 65 63 74 6c 79 0a 2a  rate correctly.*
90a0: 2a 20 77 68 65 6e 20 5b 50 52 41 47 4d 41 20 73  * when [PRAGMA s
90b0: 79 6e 63 68 72 6f 6e 6f 75 73 20 7c 20 50 52 41  ynchronous | PRA
90c0: 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 3d  GMA synchronous=
90d0: 4f 46 46 5d 20 69 73 20 73 65 74 2c 20 62 75 74  OFF] is set, but
90e0: 20 6d 6f 73 74 20 0a 2a 2a 20 56 46 53 65 73 20   most .** VFSes 
90f0: 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 68 69 73  do not need this
9100: 20 73 69 67 6e 61 6c 20 61 6e 64 20 73 68 6f 75   signal and shou
9110: 6c 64 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e 6f  ld silently igno
9120: 72 65 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 0a  re this opcode..
9130: 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20  ** Applications 
9140: 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c 6c 20  should not call 
9150: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
9160: 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68 20 74 68  ntrol()] with th
9170: 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 61 73 20  is.** opcode as 
9180: 64 6f 69 6e 67 20 73 6f 20 6d 61 79 20 64 69 73  doing so may dis
9190: 72 75 70 74 20 74 68 65 20 6f 70 65 72 61 74 69  rupt the operati
91a0: 6f 6e 20 6f 66 20 74 68 65 20 73 70 65 63 69 61  on of the specia
91b0: 6c 69 7a 65 64 20 56 46 53 65 73 0a 2a 2a 20 74  lized VFSes.** t
91c0: 68 61 74 20 64 6f 20 72 65 71 75 69 72 65 20 69  hat do require i
91d0: 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  t.  .**.** <li>[
91e0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49  [SQLITE_FCNTL_WI
91f0: 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d 5d 0a 2a  N32_AV_RETRY]].*
9200: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  * ^The [SQLITE_F
9210: 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45  CNTL_WIN32_AV_RE
9220: 54 52 59 5d 20 6f 70 63 6f 64 65 20 69 73 20 75  TRY] opcode is u
9230: 73 65 64 20 74 6f 20 63 6f 6e 66 69 67 75 72 65  sed to configure
9240: 20 61 75 74 6f 6d 61 74 69 63 0a 2a 2a 20 72 65   automatic.** re
9250: 74 72 79 20 63 6f 75 6e 74 73 20 61 6e 64 20 69  try counts and i
9260: 6e 74 65 72 76 61 6c 73 20 66 6f 72 20 63 65 72  ntervals for cer
9270: 74 61 69 6e 20 64 69 73 6b 20 49 2f 4f 20 6f 70  tain disk I/O op
9280: 65 72 61 74 69 6f 6e 73 20 66 6f 72 20 74 68 65  erations for the
9290: 0a 2a 2a 20 77 69 6e 64 6f 77 73 20 5b 56 46 53  .** windows [VFS
92a0: 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 70 72  ] in order to pr
92b0: 6f 76 69 64 65 20 72 6f 62 75 73 74 6e 65 73 73  ovide robustness
92c0: 20 69 6e 20 74 68 65 20 70 72 65 73 65 6e 63 65   in the presence
92d0: 20 6f 66 0a 2a 2a 20 61 6e 74 69 2d 76 69 72 75   of.** anti-viru
92e0: 73 20 70 72 6f 67 72 61 6d 73 2e 20 20 42 79 20  s programs.  By 
92f0: 64 65 66 61 75 6c 74 2c 20 74 68 65 20 77 69 6e  default, the win
9300: 64 6f 77 73 20 56 46 53 20 77 69 6c 6c 20 72 65  dows VFS will re
9310: 74 72 79 20 66 69 6c 65 20 72 65 61 64 2c 0a 2a  try file read,.*
9320: 2a 20 66 69 6c 65 20 77 72 69 74 65 2c 20 61 6e  * file write, an
9330: 64 20 66 69 6c 65 20 64 65 6c 65 74 65 20 6f 70  d file delete op
9340: 65 72 61 74 69 6f 6e 73 20 75 70 20 74 6f 20 31  erations up to 1
9350: 30 20 74 69 6d 65 73 2c 20 77 69 74 68 20 61 20  0 times, with a 
9360: 64 65 6c 61 79 0a 2a 2a 20 6f 66 20 32 35 20 6d  delay.** of 25 m
9370: 69 6c 6c 69 73 65 63 6f 6e 64 73 20 62 65 66 6f  illiseconds befo
9380: 72 65 20 74 68 65 20 66 69 72 73 74 20 72 65 74  re the first ret
9390: 72 79 20 61 6e 64 20 77 69 74 68 20 74 68 65 20  ry and with the 
93a0: 64 65 6c 61 79 20 69 6e 63 72 65 61 73 69 6e 67  delay increasing
93b0: 0a 2a 2a 20 62 79 20 61 6e 20 61 64 64 69 74 69  .** by an additi
93c0: 6f 6e 61 6c 20 32 35 20 6d 69 6c 6c 69 73 65 63  onal 25 millisec
93d0: 6f 6e 64 73 20 77 69 74 68 20 65 61 63 68 20 73  onds with each s
93e0: 75 62 73 65 71 75 65 6e 74 20 72 65 74 72 79 2e  ubsequent retry.
93f0: 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65    This.** opcode
9400: 20 61 6c 6c 6f 77 73 20 74 68 65 73 65 20 74 77   allows these tw
9410: 6f 20 76 61 6c 75 65 73 20 28 31 30 20 72 65 74  o values (10 ret
9420: 72 69 65 73 20 61 6e 64 20 32 35 20 6d 69 6c 6c  ries and 25 mill
9430: 69 73 65 63 6f 6e 64 73 20 6f 66 20 64 65 6c 61  iseconds of dela
9440: 79 29 0a 2a 2a 20 74 6f 20 62 65 20 61 64 6a 75  y).** to be adju
9450: 73 74 65 64 2e 20 20 54 68 65 20 76 61 6c 75 65  sted.  The value
9460: 73 20 61 72 65 20 63 68 61 6e 67 65 64 20 66 6f  s are changed fo
9470: 72 20 61 6c 6c 20 64 61 74 61 62 61 73 65 20 63  r all database c
9480: 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 77 69  onnections.** wi
9490: 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20 70 72  thin the same pr
94a0: 6f 63 65 73 73 2e 20 20 54 68 65 20 61 72 67 75  ocess.  The argu
94b0: 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65  ment is a pointe
94c0: 72 20 74 6f 20 61 6e 20 61 72 72 61 79 20 6f 66  r to an array of
94d0: 20 74 77 6f 0a 2a 2a 20 69 6e 74 65 67 65 72 73   two.** integers
94e0: 20 77 68 65 72 65 20 74 68 65 20 66 69 72 73 74   where the first
94f0: 20 69 6e 74 65 67 65 72 20 69 20 74 68 65 20 6e   integer i the n
9500: 65 77 20 72 65 74 72 79 20 63 6f 75 6e 74 20 61  ew retry count a
9510: 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a  nd the second.**
9520: 20 69 6e 74 65 67 65 72 20 69 73 20 74 68 65 20   integer is the 
9530: 64 65 6c 61 79 2e 20 20 49 66 20 65 69 74 68 65  delay.  If eithe
9540: 72 20 69 6e 74 65 67 65 72 20 69 73 20 6e 65 67  r integer is neg
9550: 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65 20  ative, then the 
9560: 73 65 74 74 69 6e 67 0a 2a 2a 20 69 73 20 6e 6f  setting.** is no
9570: 74 20 63 68 61 6e 67 65 64 20 62 75 74 20 69 6e  t changed but in
9580: 73 74 65 61 64 20 74 68 65 20 70 72 69 6f 72 20  stead the prior 
9590: 76 61 6c 75 65 20 6f 66 20 74 68 61 74 20 73 65  value of that se
95a0: 74 74 69 6e 67 20 69 73 20 77 72 69 74 74 65 6e  tting is written
95b0: 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 61 72 72  .** into the arr
95c0: 61 79 20 65 6e 74 72 79 2c 20 61 6c 6c 6f 77 69  ay entry, allowi
95d0: 6e 67 20 74 68 65 20 63 75 72 72 65 6e 74 20 72  ng the current r
95e0: 65 74 72 79 20 73 65 74 74 69 6e 67 73 20 74 6f  etry settings to
95f0: 20 62 65 0a 2a 2a 20 69 6e 74 65 72 72 6f 67 61   be.** interroga
9600: 74 65 64 2e 20 20 54 68 65 20 7a 44 62 4e 61 6d  ted.  The zDbNam
9610: 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 69  e parameter is i
9620: 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  gnored..**.** <l
9630: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
9640: 5f 50 45 52 53 49 53 54 5f 57 41 4c 5d 5d 0a 2a  _PERSIST_WAL]].*
9650: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  * ^The [SQLITE_F
9660: 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c  CNTL_PERSIST_WAL
9670: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64  ] opcode is used
9680: 20 74 6f 20 73 65 74 20 6f 72 20 71 75 65 72 79   to set or query
9690: 20 74 68 65 0a 2a 2a 20 70 65 72 73 69 73 74 65   the.** persiste
96a0: 6e 74 20 5b 57 41 4c 20 7c 20 57 72 69 74 65 20  nt [WAL | Write 
96b0: 41 68 65 61 64 20 4c 6f 67 5d 20 73 65 74 74 69  Ahead Log] setti
96c0: 6e 67 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c  ng.  By default,
96d0: 20 74 68 65 20 61 75 78 69 6c 69 61 72 79 0a 2a   the auxiliary.*
96e0: 2a 20 77 72 69 74 65 20 61 68 65 61 64 20 6c 6f  * write ahead lo
96f0: 67 20 61 6e 64 20 73 68 61 72 65 64 20 6d 65 6d  g and shared mem
9700: 6f 72 79 20 66 69 6c 65 73 20 75 73 65 64 20 66  ory files used f
9710: 6f 72 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 63  or transaction c
9720: 6f 6e 74 72 6f 6c 0a 2a 2a 20 61 72 65 20 61 75  ontrol.** are au
9730: 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c 65  tomatically dele
9740: 74 65 64 20 77 68 65 6e 20 74 68 65 20 6c 61 74  ted when the lat
9750: 65 73 74 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  est connection t
9760: 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  o the database.*
9770: 2a 20 63 6c 6f 73 65 73 2e 20 20 53 65 74 74 69  * closes.  Setti
9780: 6e 67 20 70 65 72 73 69 73 74 65 6e 74 20 57 41  ng persistent WA
9790: 4c 20 6d 6f 64 65 20 63 61 75 73 65 73 20 74 68  L mode causes th
97a0: 6f 73 65 20 66 69 6c 65 73 20 74 6f 20 70 65 72  ose files to per
97b0: 73 69 73 74 20 61 66 74 65 72 0a 2a 2a 20 63 6c  sist after.** cl
97c0: 6f 73 65 2e 20 20 50 65 72 73 69 73 74 69 6e 67  ose.  Persisting
97d0: 20 74 68 65 20 66 69 6c 65 73 20 69 73 20 75 73   the files is us
97e0: 65 66 75 6c 20 77 68 65 6e 20 6f 74 68 65 72 20  eful when other 
97f0: 70 72 6f 63 65 73 73 65 73 20 74 68 61 74 20 64  processes that d
9800: 6f 20 6e 6f 74 0a 2a 2a 20 68 61 76 65 20 77 72  o not.** have wr
9810: 69 74 65 20 70 65 72 6d 69 73 73 69 6f 6e 20 6f  ite permission o
9820: 6e 20 74 68 65 20 64 69 72 65 63 74 6f 72 79 20  n the directory 
9830: 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 64  containing the d
9840: 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 61 6e  atabase file wan
9850: 74 0a 2a 2a 20 74 6f 20 72 65 61 64 20 74 68 65  t.** to read the
9860: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20   database file, 
9870: 61 73 20 74 68 65 20 57 41 4c 20 61 6e 64 20 73  as the WAL and s
9880: 68 61 72 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c  hared memory fil
9890: 65 73 20 6d 75 73 74 20 65 78 69 73 74 0a 2a 2a  es must exist.**
98a0: 20 69 6e 20 6f 72 64 65 72 20 66 6f 72 20 74 68   in order for th
98b0: 65 20 64 61 74 61 62 61 73 65 20 74 6f 20 62 65  e database to be
98c0: 20 72 65 61 64 61 62 6c 65 2e 20 20 54 68 65 20   readable.  The 
98d0: 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
98e0: 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
98f0: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20  file_control()] 
9900: 66 6f 72 20 74 68 69 73 20 6f 70 63 6f 64 65 20  for this opcode 
9910: 73 68 6f 75 6c 64 20 62 65 20 61 20 70 6f 69 6e  should be a poin
9920: 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  ter to an intege
9930: 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e 74 65 67  r..** That integ
9940: 65 72 20 69 73 20 30 20 74 6f 20 64 69 73 61 62  er is 0 to disab
9950: 6c 65 20 70 65 72 73 69 73 74 65 6e 74 20 57 41  le persistent WA
9960: 4c 20 6d 6f 64 65 20 6f 72 20 31 20 74 6f 20 65  L mode or 1 to e
9970: 6e 61 62 6c 65 20 70 65 72 73 69 73 74 65 6e 74  nable persistent
9980: 0a 2a 2a 20 57 41 4c 20 6d 6f 64 65 2e 20 20 49  .** WAL mode.  I
9990: 66 20 74 68 65 20 69 6e 74 65 67 65 72 20 69 73  f the integer is
99a0: 20 2d 31 2c 20 74 68 65 6e 20 69 74 20 69 73 20   -1, then it is 
99b0: 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69 74 68  overwritten with
99c0: 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20   the current.** 
99d0: 57 41 4c 20 70 65 72 73 69 73 74 65 6e 63 65 20  WAL persistence 
99e0: 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c  setting..**.** <
99f0: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
9a00: 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52  L_POWERSAFE_OVER
9a10: 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20  WRITE]].** ^The 
9a20: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f  [SQLITE_FCNTL_PO
9a30: 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54  WERSAFE_OVERWRIT
9a40: 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65  E] opcode is use
9a50: 64 20 74 6f 20 73 65 74 20 6f 72 20 71 75 65 72  d to set or quer
9a60: 79 20 74 68 65 0a 2a 2a 20 70 65 72 73 69 73 74  y the.** persist
9a70: 65 6e 74 20 22 70 6f 77 65 72 73 61 66 65 2d 6f  ent "powersafe-o
9a80: 76 65 72 77 72 69 74 65 22 20 6f 72 20 22 50 53  verwrite" or "PS
9a90: 4f 57 22 20 73 65 74 74 69 6e 67 2e 20 20 54 68  OW" setting.  Th
9aa0: 65 20 50 53 4f 57 20 73 65 74 74 69 6e 67 0a 2a  e PSOW setting.*
9ab0: 2a 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68 65  * determines the
9ac0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50   [SQLITE_IOCAP_P
9ad0: 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49  OWERSAFE_OVERWRI
9ae0: 54 45 5d 20 62 69 74 20 6f 66 20 74 68 65 0a 2a  TE] bit of the.*
9af0: 2a 20 78 44 65 76 69 63 65 43 68 61 72 61 63 74  * xDeviceCharact
9b00: 65 72 69 73 74 69 63 73 20 6d 65 74 68 6f 64 73  eristics methods
9b10: 2e 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72  . The fourth par
9b20: 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71  ameter to.** [sq
9b30: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
9b40: 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 73 20 6f  ol()] for this o
9b50: 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 62 65 20  pcode should be 
9b60: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
9b70: 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61 74  integer..** That
9b80: 20 69 6e 74 65 67 65 72 20 69 73 20 30 20 74 6f   integer is 0 to
9b90: 20 64 69 73 61 62 6c 65 20 7a 65 72 6f 2d 64 61   disable zero-da
9ba0: 6d 61 67 65 20 6d 6f 64 65 20 6f 72 20 31 20 74  mage mode or 1 t
9bb0: 6f 20 65 6e 61 62 6c 65 20 7a 65 72 6f 2d 64 61  o enable zero-da
9bc0: 6d 61 67 65 0a 2a 2a 20 6d 6f 64 65 2e 20 20 49  mage.** mode.  I
9bd0: 66 20 74 68 65 20 69 6e 74 65 67 65 72 20 69 73  f the integer is
9be0: 20 2d 31 2c 20 74 68 65 6e 20 69 74 20 69 73 20   -1, then it is 
9bf0: 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69 74 68  overwritten with
9c00: 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20   the current.** 
9c10: 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 65  zero-damage mode
9c20: 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20   setting..**.** 
9c30: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
9c40: 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a 2a  TL_OVERWRITE]].*
9c50: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  * ^The [SQLITE_F
9c60: 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d 20  CNTL_OVERWRITE] 
9c70: 6f 70 63 6f 64 65 20 69 73 20 69 6e 76 6f 6b 65  opcode is invoke
9c80: 64 20 62 79 20 53 51 4c 69 74 65 20 61 66 74 65  d by SQLite afte
9c90: 72 20 6f 70 65 6e 69 6e 67 0a 2a 2a 20 61 20 77  r opening.** a w
9ca0: 72 69 74 65 20 74 72 61 6e 73 61 63 74 69 6f 6e  rite transaction
9cb0: 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61   to indicate tha
9cc0: 74 2c 20 75 6e 6c 65 73 73 20 69 74 20 69 73 20  t, unless it is 
9cd0: 72 6f 6c 6c 65 64 20 62 61 63 6b 20 66 6f 72 20  rolled back for 
9ce0: 73 6f 6d 65 0a 2a 2a 20 72 65 61 73 6f 6e 2c 20  some.** reason, 
9cf0: 74 68 65 20 65 6e 74 69 72 65 20 64 61 74 61 62  the entire datab
9d00: 61 73 65 20 66 69 6c 65 20 77 69 6c 6c 20 62 65  ase file will be
9d10: 20 6f 76 65 72 77 72 69 74 74 65 6e 20 62 79 20   overwritten by 
9d20: 74 68 65 20 63 75 72 72 65 6e 74 20 0a 2a 2a 20  the current .** 
9d30: 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 54 68 69  transaction. Thi
9d40: 73 20 69 73 20 75 73 65 64 20 62 79 20 56 41 43  s is used by VAC
9d50: 55 55 4d 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a  UUM operations..
9d60: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
9d70: 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45  TE_FCNTL_VFSNAME
9d80: 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  ]].** ^The [SQLI
9d90: 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45  TE_FCNTL_VFSNAME
9da0: 5d 20 6f 70 63 6f 64 65 20 63 61 6e 20 62 65 20  ] opcode can be 
9db0: 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 74  used to obtain t
9dc0: 68 65 20 6e 61 6d 65 73 20 6f 66 0a 2a 2a 20 61  he names of.** a
9dd0: 6c 6c 20 5b 56 46 53 65 73 5d 20 69 6e 20 74 68  ll [VFSes] in th
9de0: 65 20 56 46 53 20 73 74 61 63 6b 2e 20 20 54 68  e VFS stack.  Th
9df0: 65 20 6e 61 6d 65 73 20 61 72 65 20 6f 66 20 61  e names are of a
9e00: 6c 6c 20 56 46 53 20 73 68 69 6d 73 20 61 6e 64  ll VFS shims and
9e10: 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 62 6f   the.** final bo
9e20: 74 74 6f 6d 2d 6c 65 76 65 6c 20 56 46 53 20 61  ttom-level VFS a
9e30: 72 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20  re written into 
9e40: 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20  memory obtained 
9e50: 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65  from .** [sqlite
9e60: 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 20  3_malloc()] and 
9e70: 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 73 74  the result is st
9e80: 6f 72 65 64 20 69 6e 20 74 68 65 20 63 68 61 72  ored in the char
9e90: 2a 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 74 68  * variable.** th
9ea0: 61 74 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  at the fourth pa
9eb0: 72 61 6d 65 74 65 72 20 6f 66 20 5b 73 71 6c 69  rameter of [sqli
9ec0: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
9ed0: 28 29 5d 20 70 6f 69 6e 74 73 20 74 6f 2e 0a 2a  ()] points to..*
9ee0: 2a 20 54 68 65 20 63 61 6c 6c 65 72 20 69 73 20  * The caller is 
9ef0: 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20  responsible for 
9f00: 66 72 65 65 69 6e 67 20 74 68 65 20 6d 65 6d 6f  freeing the memo
9f10: 72 79 20 77 68 65 6e 20 64 6f 6e 65 2e 20 20 41  ry when done.  A
9f20: 73 20 77 69 74 68 0a 2a 2a 20 61 6c 6c 20 66 69  s with.** all fi
9f30: 6c 65 2d 63 6f 6e 74 72 6f 6c 20 61 63 74 69 6f  le-control actio
9f40: 6e 73 2c 20 74 68 65 72 65 20 69 73 20 6e 6f 20  ns, there is no 
9f50: 67 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 74  guarantee that t
9f60: 68 69 73 20 77 69 6c 6c 20 61 63 74 75 61 6c 6c  his will actuall
9f70: 79 0a 2a 2a 20 64 6f 20 61 6e 79 74 68 69 6e 67  y.** do anything
9f80: 2e 20 20 43 61 6c 6c 65 72 73 20 73 68 6f 75 6c  .  Callers shoul
9f90: 64 20 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65  d initialize the
9fa0: 20 63 68 61 72 2a 20 76 61 72 69 61 62 6c 65 20   char* variable 
9fb0: 74 6f 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69  to a NULL.** poi
9fc0: 6e 74 65 72 20 69 6e 20 63 61 73 65 20 74 68 69  nter in case thi
9fd0: 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69  s file-control i
9fe0: 73 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74 65  s not implemente
9ff0: 64 2e 20 20 54 68 69 73 20 66 69 6c 65 2d 63 6f  d.  This file-co
a000: 6e 74 72 6f 6c 0a 2a 2a 20 69 73 20 69 6e 74 65  ntrol.** is inte
a010: 6e 64 65 64 20 66 6f 72 20 64 69 61 67 6e 6f 73  nded for diagnos
a020: 74 69 63 20 75 73 65 20 6f 6e 6c 79 2e 0a 2a 2a  tic use only..**
a030: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
a040: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 5d 0a  _FCNTL_PRAGMA]].
a050: 2a 2a 20 5e 57 68 65 6e 65 76 65 72 20 61 20 5b  ** ^Whenever a [
a060: 50 52 41 47 4d 41 5d 20 73 74 61 74 65 6d 65 6e  PRAGMA] statemen
a070: 74 20 69 73 20 70 61 72 73 65 64 2c 20 61 6e 20  t is parsed, an 
a080: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52  [SQLITE_FCNTL_PR
a090: 41 47 4d 41 5d 20 0a 2a 2a 20 66 69 6c 65 20 63  AGMA] .** file c
a0a0: 6f 6e 74 72 6f 6c 20 69 73 20 73 65 6e 74 20 74  ontrol is sent t
a0b0: 6f 20 74 68 65 20 6f 70 65 6e 20 5b 73 71 6c 69  o the open [sqli
a0c0: 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74  te3_file] object
a0d0: 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a   corresponding.*
a0e0: 2a 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73  * to the databas
a0f0: 65 20 66 69 6c 65 20 74 6f 20 77 68 69 63 68 20  e file to which 
a100: 74 68 65 20 70 72 61 67 6d 61 20 73 74 61 74 65  the pragma state
a110: 6d 65 6e 74 20 72 65 66 65 72 73 2e 20 5e 54 68  ment refers. ^Th
a120: 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f  e argument.** to
a130: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   the [SQLITE_FCN
a140: 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20  TL_PRAGMA] file 
a150: 63 6f 6e 74 72 6f 6c 20 69 73 20 61 6e 20 61 72  control is an ar
a160: 72 61 79 20 6f 66 0a 2a 2a 20 70 6f 69 6e 74 65  ray of.** pointe
a170: 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 28 63  rs to strings (c
a180: 68 61 72 2a 2a 29 20 69 6e 20 77 68 69 63 68 20  har**) in which 
a190: 74 68 65 20 73 65 63 6f 6e 64 20 65 6c 65 6d 65  the second eleme
a1a0: 6e 74 20 6f 66 20 74 68 65 20 61 72 72 61 79 0a  nt of the array.
a1b0: 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  ** is the name o
a1c0: 66 20 74 68 65 20 70 72 61 67 6d 61 20 61 6e 64  f the pragma and
a1d0: 20 74 68 65 20 74 68 69 72 64 20 65 6c 65 6d 65   the third eleme
a1e0: 6e 74 20 69 73 20 74 68 65 20 61 72 67 75 6d 65  nt is the argume
a1f0: 6e 74 20 74 6f 20 74 68 65 0a 2a 2a 20 70 72 61  nt to the.** pra
a200: 67 6d 61 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74  gma or NULL if t
a210: 68 65 20 70 72 61 67 6d 61 20 68 61 73 20 6e 6f  he pragma has no
a220: 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e 54 68 65   argument.  ^The
a230: 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 6e 0a   handler for an.
a240: 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ** [SQLITE_FCNTL
a250: 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f  _PRAGMA] file co
a260: 6e 74 72 6f 6c 20 63 61 6e 20 6f 70 74 69 6f 6e  ntrol can option
a270: 61 6c 6c 79 20 6d 61 6b 65 20 74 68 65 20 66 69  ally make the fi
a280: 72 73 74 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 6f  rst element.** o
a290: 66 20 74 68 65 20 63 68 61 72 2a 2a 20 61 72 67  f the char** arg
a2a0: 75 6d 65 6e 74 20 70 6f 69 6e 74 20 74 6f 20 61  ument point to a
a2b0: 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64   string obtained
a2c0: 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
a2d0: 70 72 69 6e 74 66 28 29 5d 0a 2a 2a 20 6f 72 20  printf()].** or 
a2e0: 74 68 65 20 65 71 75 69 76 61 6c 65 6e 74 20 61  the equivalent a
a2f0: 6e 64 20 74 68 61 74 20 73 74 72 69 6e 67 20 77  nd that string w
a300: 69 6c 6c 20 62 65 63 6f 6d 65 20 74 68 65 20 72  ill become the r
a310: 65 73 75 6c 74 20 6f 66 20 74 68 65 20 70 72 61  esult of the pra
a320: 67 6d 61 20 6f 72 0a 2a 2a 20 74 68 65 20 65 72  gma or.** the er
a330: 72 6f 72 20 6d 65 73 73 61 67 65 20 69 66 20 74  ror message if t
a340: 68 65 20 70 72 61 67 6d 61 20 66 61 69 6c 73 2e  he pragma fails.
a350: 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c   ^If the.** [SQL
a360: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41  ITE_FCNTL_PRAGMA
a370: 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72  ] file control r
a380: 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4e  eturns [SQLITE_N
a390: 4f 54 46 4f 55 4e 44 5d 2c 20 74 68 65 6e 20 6e  OTFOUND], then n
a3a0: 6f 72 6d 61 6c 20 0a 2a 2a 20 5b 50 52 41 47 4d  ormal .** [PRAGM
a3b0: 41 5d 20 70 72 6f 63 65 73 73 69 6e 67 20 63 6f  A] processing co
a3c0: 6e 74 69 6e 75 65 73 2e 20 20 5e 49 66 20 74 68  ntinues.  ^If th
a3d0: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
a3e0: 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20  PRAGMA].** file 
a3f0: 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 20  control returns 
a400: 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 65  [SQLITE_OK], the
a410: 6e 20 74 68 65 20 70 61 72 73 65 72 20 61 73 73  n the parser ass
a420: 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a  umes that the.**
a430: 20 56 46 53 20 68 61 73 20 68 61 6e 64 6c 65 64   VFS has handled
a440: 20 74 68 65 20 50 52 41 47 4d 41 20 69 74 73 65   the PRAGMA itse
a450: 6c 66 20 61 6e 64 20 74 68 65 20 70 61 72 73 65  lf and the parse
a460: 72 20 67 65 6e 65 72 61 74 65 73 20 61 20 6e 6f  r generates a no
a470: 2d 6f 70 0a 2a 2a 20 70 72 65 70 61 72 65 64 20  -op.** prepared 
a480: 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 49 66 20  statement.  ^If 
a490: 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  the [SQLITE_FCNT
a4a0: 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63  L_PRAGMA] file c
a4b0: 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 0a 2a  ontrol returns.*
a4c0: 2a 20 61 6e 79 20 72 65 73 75 6c 74 20 63 6f 64  * any result cod
a4d0: 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51  e other than [SQ
a4e0: 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 5b 53 51 4c  LITE_OK] or [SQL
a4f0: 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74  ITE_NOTFOUND], t
a500: 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61  hat means.** tha
a510: 74 20 74 68 65 20 56 46 53 20 65 6e 63 6f 75 6e  t the VFS encoun
a520: 74 65 72 65 64 20 61 6e 20 65 72 72 6f 72 20 77  tered an error w
a530: 68 69 6c 65 20 68 61 6e 64 6c 69 6e 67 20 74 68  hile handling th
a540: 65 20 5b 50 52 41 47 4d 41 5d 20 61 6e 64 20 74  e [PRAGMA] and t
a550: 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c 61 74 69 6f  he.** compilatio
a560: 6e 20 6f 66 20 74 68 65 20 50 52 41 47 4d 41 20  n of the PRAGMA 
a570: 66 61 69 6c 73 20 77 69 74 68 20 61 6e 20 65 72  fails with an er
a580: 72 6f 72 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49  ror.  ^The [SQLI
a590: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d  TE_FCNTL_PRAGMA]
a5a0: 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  .** file control
a5b0: 20 6f 63 63 75 72 73 20 61 74 20 74 68 65 20 62   occurs at the b
a5c0: 65 67 69 6e 6e 69 6e 67 20 6f 66 20 70 72 61 67  eginning of prag
a5d0: 6d 61 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 61  ma statement ana
a5e0: 6c 79 73 69 73 20 61 6e 64 20 73 6f 0a 2a 2a 20  lysis and so.** 
a5f0: 69 74 20 69 73 20 61 62 6c 65 20 74 6f 20 6f 76  it is able to ov
a600: 65 72 72 69 64 65 20 62 75 69 6c 74 2d 69 6e 20  erride built-in 
a610: 5b 50 52 41 47 4d 41 5d 20 73 74 61 74 65 6d 65  [PRAGMA] stateme
a620: 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  nts..**.** <li>[
a630: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55  [SQLITE_FCNTL_BU
a640: 53 59 48 41 4e 44 4c 45 52 5d 5d 0a 2a 2a 20 5e  SYHANDLER]].** ^
a650: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
a660: 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52 5d 0a 2a  L_BUSYHANDLER].*
a670: 2a 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 6d  * file-control m
a680: 61 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 62 79  ay be invoked by
a690: 20 53 51 4c 69 74 65 20 6f 6e 20 74 68 65 20 64   SQLite on the d
a6a0: 61 74 61 62 61 73 65 20 66 69 6c 65 20 68 61 6e  atabase file han
a6b0: 64 6c 65 0a 2a 2a 20 73 68 6f 72 74 6c 79 20 61  dle.** shortly a
a6c0: 66 74 65 72 20 69 74 20 69 73 20 6f 70 65 6e 65  fter it is opene
a6d0: 64 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 70 72  d in order to pr
a6e0: 6f 76 69 64 65 20 61 20 63 75 73 74 6f 6d 20 56  ovide a custom V
a6f0: 46 53 20 77 69 74 68 20 61 63 63 65 73 73 0a 2a  FS with access.*
a700: 2a 20 74 6f 20 74 68 65 20 63 6f 6e 6e 65 63 74  * to the connect
a710: 69 6f 6e 73 20 62 75 73 79 2d 68 61 6e 64 6c 65  ions busy-handle
a720: 72 20 63 61 6c 6c 62 61 63 6b 2e 20 54 68 65 20  r callback. The 
a730: 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 66 20 74  argument is of t
a740: 79 70 65 20 28 76 6f 69 64 20 2a 2a 29 0a 2a 2a  ype (void **).**
a750: 20 2d 20 61 6e 20 61 72 72 61 79 20 6f 66 20 74   - an array of t
a760: 77 6f 20 28 76 6f 69 64 20 2a 29 20 76 61 6c 75  wo (void *) valu
a770: 65 73 2e 20 54 68 65 20 66 69 72 73 74 20 28 76  es. The first (v
a780: 6f 69 64 20 2a 29 20 61 63 74 75 61 6c 6c 79 20  oid *) actually 
a790: 70 6f 69 6e 74 73 0a 2a 2a 20 74 6f 20 61 20 66  points.** to a f
a7a0: 75 6e 63 74 69 6f 6e 20 6f 66 20 74 79 70 65 20  unction of type 
a7b0: 28 69 6e 74 20 28 2a 29 28 76 6f 69 64 20 2a 29  (int (*)(void *)
a7c0: 29 2e 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 69  ). In order to i
a7d0: 6e 76 6f 6b 65 20 74 68 65 20 63 6f 6e 6e 65 63  nvoke the connec
a7e0: 74 69 6f 6e 73 0a 2a 2a 20 62 75 73 79 2d 68 61  tions.** busy-ha
a7f0: 6e 64 6c 65 72 2c 20 74 68 69 73 20 66 75 6e 63  ndler, this func
a800: 74 69 6f 6e 20 73 68 6f 75 6c 64 20 62 65 20 69  tion should be i
a810: 6e 76 6f 6b 65 64 20 77 69 74 68 20 74 68 65 20  nvoked with the 
a820: 73 65 63 6f 6e 64 20 28 76 6f 69 64 20 2a 29 20  second (void *) 
a830: 69 6e 0a 2a 2a 20 74 68 65 20 61 72 72 61 79 20  in.** the array 
a840: 61 73 20 74 68 65 20 6f 6e 6c 79 20 61 72 67 75  as the only argu
a850: 6d 65 6e 74 2e 20 49 66 20 69 74 20 72 65 74 75  ment. If it retu
a860: 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68  rns non-zero, th
a870: 65 6e 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e  en the operation
a880: 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 65  .** should be re
a890: 74 72 69 65 64 2e 20 49 66 20 69 74 20 72 65 74  tried. If it ret
a8a0: 75 72 6e 73 20 7a 65 72 6f 2c 20 74 68 65 20 63  urns zero, the c
a8b0: 75 73 74 6f 6d 20 56 46 53 20 73 68 6f 75 6c 64  ustom VFS should
a8c0: 20 61 62 61 6e 64 6f 6e 20 74 68 65 0a 2a 2a 20   abandon the.** 
a8d0: 63 75 72 72 65 6e 74 20 6f 70 65 72 61 74 69 6f  current operatio
a8e0: 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  n..**.** <li>[[S
a8f0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50  QLITE_FCNTL_TEMP
a900: 46 49 4c 45 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 41  FILENAME]].** ^A
a910: 70 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 69  pplication can i
a920: 6e 76 6f 6b 65 20 74 68 65 20 5b 53 51 4c 49 54  nvoke the [SQLIT
a930: 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45  E_FCNTL_TEMPFILE
a940: 4e 41 4d 45 5d 20 66 69 6c 65 2d 63 6f 6e 74 72  NAME] file-contr
a950: 6f 6c 0a 2a 2a 20 74 6f 20 68 61 76 65 20 53 51  ol.** to have SQ
a960: 4c 69 74 65 20 67 65 6e 65 72 61 74 65 20 61 0a  Lite generate a.
a970: 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c  ** temporary fil
a980: 65 6e 61 6d 65 20 75 73 69 6e 67 20 74 68 65 20  ename using the 
a990: 73 61 6d 65 20 61 6c 67 6f 72 69 74 68 6d 20 74  same algorithm t
a9a0: 68 61 74 20 69 73 20 66 6f 6c 6c 6f 77 65 64 20  hat is followed 
a9b0: 74 6f 20 67 65 6e 65 72 61 74 65 0a 2a 2a 20 74  to generate.** t
a9c0: 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 6e 61 6d  emporary filenam
a9d0: 65 73 20 66 6f 72 20 54 45 4d 50 20 74 61 62 6c  es for TEMP tabl
a9e0: 65 73 20 61 6e 64 20 6f 74 68 65 72 20 69 6e 74  es and other int
a9f0: 65 72 6e 61 6c 20 75 73 65 73 2e 20 20 54 68 65  ernal uses.  The
aa00: 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f  .** argument sho
aa10: 75 6c 64 20 62 65 20 61 20 63 68 61 72 2a 2a 20  uld be a char** 
aa20: 77 68 69 63 68 20 77 69 6c 6c 20 62 65 20 66 69  which will be fi
aa30: 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 66 69  lled with the fi
aa40: 6c 65 6e 61 6d 65 0a 2a 2a 20 77 72 69 74 74 65  lename.** writte
aa50: 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62  n into memory ob
aa60: 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  tained from [sql
aa70: 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20  ite3_malloc()]. 
aa80: 20 54 68 65 20 63 61 6c 6c 65 72 20 73 68 6f 75   The caller shou
aa90: 6c 64 0a 2a 2a 20 69 6e 76 6f 6b 65 20 5b 73 71  ld.** invoke [sq
aaa0: 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f 6e  lite3_free()] on
aab0: 20 74 68 65 20 72 65 73 75 6c 74 20 74 6f 20 61   the result to a
aac0: 76 6f 69 64 20 61 20 6d 65 6d 6f 72 79 20 6c 65  void a memory le
aad0: 61 6b 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ak..**.** <li>[[
aae0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41  SQLITE_FCNTL_MMA
aaf0: 50 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20  P_SIZE]].** The 
ab00: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d  [SQLITE_FCNTL_MM
ab10: 41 50 5f 53 49 5a 45 5d 20 66 69 6c 65 20 63 6f  AP_SIZE] file co
ab20: 6e 74 72 6f 6c 20 69 73 20 75 73 65 64 20 74 6f  ntrol is used to
ab30: 20 71 75 65 72 79 20 6f 72 20 73 65 74 20 74 68   query or set th
ab40: 65 0a 2a 2a 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  e.** maximum num
ab50: 62 65 72 20 6f 66 20 62 79 74 65 73 20 74 68 61  ber of bytes tha
ab60: 74 20 77 69 6c 6c 20 62 65 20 75 73 65 64 20 66  t will be used f
ab70: 6f 72 20 6d 65 6d 6f 72 79 2d 6d 61 70 70 65 64  or memory-mapped
ab80: 20 49 2f 4f 2e 0a 2a 2a 20 54 68 65 20 61 72 67   I/O..** The arg
ab90: 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74  ument is a point
aba0: 65 72 20 74 6f 20 61 20 76 61 6c 75 65 20 6f 66  er to a value of
abb0: 20 74 79 70 65 20 73 71 6c 69 74 65 33 5f 69 6e   type sqlite3_in
abc0: 74 36 34 20 74 68 61 74 0a 2a 2a 20 69 73 20 61  t64 that.** is a
abd0: 6e 20 61 64 76 69 73 6f 72 79 20 6d 61 78 69 6d  n advisory maxim
abe0: 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  um number of byt
abf0: 65 73 20 69 6e 20 74 68 65 20 66 69 6c 65 20 74  es in the file t
ac00: 6f 20 6d 65 6d 6f 72 79 20 6d 61 70 2e 20 20 54  o memory map.  T
ac10: 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 73  he.** pointer is
ac20: 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69 74   overwritten wit
ac30: 68 20 74 68 65 20 6f 6c 64 20 76 61 6c 75 65 2e  h the old value.
ac40: 20 20 54 68 65 20 6c 69 6d 69 74 20 69 73 20 6e    The limit is n
ac50: 6f 74 20 63 68 61 6e 67 65 64 20 69 66 0a 2a 2a  ot changed if.**
ac60: 20 74 68 65 20 76 61 6c 75 65 20 6f 72 69 67 69   the value origi
ac70: 6e 61 6c 6c 79 20 70 6f 69 6e 74 65 64 20 74 6f  nally pointed to
ac80: 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 61 6e   is negative, an
ac90: 64 20 73 6f 20 74 68 65 20 63 75 72 72 65 6e 74  d so the current
aca0: 20 6c 69 6d 69 74 20 0a 2a 2a 20 63 61 6e 20 62   limit .** can b
acb0: 65 20 71 75 65 72 69 65 64 20 62 79 20 70 61 73  e queried by pas
acc0: 73 69 6e 67 20 69 6e 20 61 20 70 6f 69 6e 74 65  sing in a pointe
acd0: 72 20 74 6f 20 61 20 6e 65 67 61 74 69 76 65 20  r to a negative 
ace0: 6e 75 6d 62 65 72 2e 20 20 54 68 69 73 0a 2a 2a  number.  This.**
acf0: 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 73   file-control is
ad00: 20 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79   used internally
ad10: 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 5b 50   to implement [P
ad20: 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d  RAGMA mmap_size]
ad30: 2e 0a 2a 2a 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f  ..**.** </ul>.*/
ad40: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
ad50: 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20  FCNTL_LOCKSTATE 
ad60: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 0a                1.
ad70: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 47  #define SQLITE_G
ad80: 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45  ET_LOCKPROXYFILE
ad90: 20 20 20 20 20 20 20 20 20 20 20 20 20 32 0a 23               2.#
ada0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45  define SQLITE_SE
adb0: 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20  T_LOCKPROXYFILE 
adc0: 20 20 20 20 20 20 20 20 20 20 20 20 33 0a 23 64              3.#d
add0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 41 53  efine SQLITE_LAS
ade0: 54 5f 45 52 52 4e 4f 20 20 20 20 20 20 20 20 20  T_ERRNO         
adf0: 20 20 20 20 20 20 20 20 20 20 20 34 0a 23 64 65             4.#de
ae00: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
ae10: 4c 5f 53 49 5a 45 5f 48 49 4e 54 20 20 20 20 20  L_SIZE_HINT     
ae20: 20 20 20 20 20 20 20 20 20 20 35 0a 23 64 65 66            5.#def
ae30: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
ae40: 5f 43 48 55 4e 4b 5f 53 49 5a 45 20 20 20 20 20  _CHUNK_SIZE     
ae50: 20 20 20 20 20 20 20 20 20 36 0a 23 64 65 66 69           6.#defi
ae60: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
ae70: 46 49 4c 45 5f 50 4f 49 4e 54 45 52 20 20 20 20  FILE_POINTER    
ae80: 20 20 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e          7.#defin
ae90: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53  e SQLITE_FCNTL_S
aea0: 59 4e 43 5f 4f 4d 49 54 54 45 44 20 20 20 20 20  YNC_OMITTED     
aeb0: 20 20 20 20 20 20 20 38 0a 23 64 65 66 69 6e 65         8.#define
aec0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49   SQLITE_FCNTL_WI
aed0: 4e 33 32 5f 41 56 5f 52 45 54 52 59 20 20 20 20  N32_AV_RETRY    
aee0: 20 20 20 20 20 20 39 0a 23 64 65 66 69 6e 65 20        9.#define 
aef0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52  SQLITE_FCNTL_PER
af00: 53 49 53 54 5f 57 41 4c 20 20 20 20 20 20 20 20  SIST_WAL        
af10: 20 20 20 20 31 30 0a 23 64 65 66 69 6e 65 20 53      10.#define S
af20: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52  QLITE_FCNTL_OVER
af30: 57 52 49 54 45 20 20 20 20 20 20 20 20 20 20 20  WRITE           
af40: 20 20 20 31 31 0a 23 64 65 66 69 6e 65 20 53 51     11.#define SQ
af50: 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41  LITE_FCNTL_VFSNA
af60: 4d 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ME              
af70: 20 20 31 32 0a 23 64 65 66 69 6e 65 20 53 51 4c    12.#define SQL
af80: 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53  ITE_FCNTL_POWERS
af90: 41 46 45 5f 4f 56 45 52 57 52 49 54 45 20 20 20  AFE_OVERWRITE   
afa0: 20 31 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   13.#define SQLI
afb0: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 20  TE_FCNTL_PRAGMA 
afc0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
afd0: 31 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  14.#define SQLIT
afe0: 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44  E_FCNTL_BUSYHAND
aff0: 4c 45 52 20 20 20 20 20 20 20 20 20 20 20 20 31  LER            1
b000: 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  5.#define SQLITE
b010: 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e  _FCNTL_TEMPFILEN
b020: 41 4d 45 20 20 20 20 20 20 20 20 20 20 20 31 36  AME           16
b030: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
b040: 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 20  FCNTL_MMAP_SIZE 
b050: 20 20 20 20 20 20 20 20 20 20 20 20 20 31 38 0a               18.
b060: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
b070: 20 4d 75 74 65 78 20 48 61 6e 64 6c 65 0a 2a 2a   Mutex Handle.**
b080: 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78 20 6d 6f  .** The mutex mo
b090: 64 75 6c 65 20 77 69 74 68 69 6e 20 53 51 4c 69  dule within SQLi
b0a0: 74 65 20 64 65 66 69 6e 65 73 20 5b 73 71 6c 69  te defines [sqli
b0b0: 74 65 33 5f 6d 75 74 65 78 5d 20 74 6f 20 62 65  te3_mutex] to be
b0c0: 20 61 6e 0a 2a 2a 20 61 62 73 74 72 61 63 74 20   an.** abstract 
b0d0: 74 79 70 65 20 66 6f 72 20 61 20 6d 75 74 65 78  type for a mutex
b0e0: 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 53 51   object.  The SQ
b0f0: 4c 69 74 65 20 63 6f 72 65 20 6e 65 76 65 72 20  Lite core never 
b100: 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74 68 65 20  looks.** at the 
b110: 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65  internal represe
b120: 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 5b 73  ntation of an [s
b130: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 2e 20 20  qlite3_mutex].  
b140: 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73  It only.** deals
b150: 20 77 69 74 68 20 70 6f 69 6e 74 65 72 73 20 74   with pointers t
b160: 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  o the [sqlite3_m
b170: 75 74 65 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a  utex] object..**
b180: 0a 2a 2a 20 4d 75 74 65 78 65 73 20 61 72 65 20  .** Mutexes are 
b190: 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 5b 73  created using [s
b1a0: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c  qlite3_mutex_all
b1b0: 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65  oc()]..*/.typede
b1c0: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
b1d0: 5f 6d 75 74 65 78 20 73 71 6c 69 74 65 33 5f 6d  _mutex sqlite3_m
b1e0: 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  utex;../*.** CAP
b1f0: 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66  I3REF: OS Interf
b200: 61 63 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a  ace Object.**.**
b210: 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   An instance of 
b220: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20  the sqlite3_vfs 
b230: 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74  object defines t
b240: 68 65 20 69 6e 74 65 72 66 61 63 65 20 62 65 74  he interface bet
b250: 77 65 65 6e 0a 2a 2a 20 74 68 65 20 53 51 4c 69  ween.** the SQLi
b260: 74 65 20 63 6f 72 65 20 61 6e 64 20 74 68 65 20  te core and the 
b270: 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 72 61  underlying opera
b280: 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 54 68  ting system.  Th
b290: 65 20 22 76 66 73 22 0a 2a 2a 20 69 6e 20 74 68  e "vfs".** in th
b2a0: 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6f 62  e name of the ob
b2b0: 6a 65 63 74 20 73 74 61 6e 64 73 20 66 6f 72 20  ject stands for 
b2c0: 22 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79  "virtual file sy
b2d0: 73 74 65 6d 22 2e 20 20 53 65 65 0a 2a 2a 20 74  stem".  See.** t
b2e0: 68 65 20 5b 56 46 53 20 7c 20 56 46 53 20 64 6f  he [VFS | VFS do
b2f0: 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72  cumentation] for
b300: 20 66 75 72 74 68 65 72 20 69 6e 66 6f 72 6d 61   further informa
b310: 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  tion..**.** The 
b320: 76 61 6c 75 65 20 6f 66 20 74 68 65 20 69 56 65  value of the iVe
b330: 72 73 69 6f 6e 20 66 69 65 6c 64 20 69 73 20 69  rsion field is i
b340: 6e 69 74 69 61 6c 6c 79 20 31 20 62 75 74 20 6d  nitially 1 but m
b350: 61 79 20 62 65 20 6c 61 72 67 65 72 20 69 6e 0a  ay be larger in.
b360: 2a 2a 20 66 75 74 75 72 65 20 76 65 72 73 69 6f  ** future versio
b370: 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 41  ns of SQLite.  A
b380: 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73  dditional fields
b390: 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 64   may be appended
b3a0: 20 74 6f 20 74 68 69 73 0a 2a 2a 20 6f 62 6a 65   to this.** obje
b3b0: 63 74 20 77 68 65 6e 20 74 68 65 20 69 56 65 72  ct when the iVer
b3c0: 73 69 6f 6e 20 76 61 6c 75 65 20 69 73 20 69 6e  sion value is in
b3d0: 63 72 65 61 73 65 64 2e 20 20 4e 6f 74 65 20 74  creased.  Note t
b3e0: 68 61 74 20 74 68 65 20 73 74 72 75 63 74 75 72  hat the structur
b3f0: 65 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69  e.** of the sqli
b400: 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 63  te3_vfs object c
b410: 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 74 72  hanges in the tr
b420: 61 6e 73 61 63 74 69 6f 6e 20 62 65 74 77 65 65  ansaction betwee
b430: 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73  n.** SQLite vers
b440: 69 6f 6e 20 33 2e 35 2e 39 20 61 6e 64 20 33 2e  ion 3.5.9 and 3.
b450: 36 2e 30 20 61 6e 64 20 79 65 74 20 74 68 65 20  6.0 and yet the 
b460: 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 77  iVersion field w
b470: 61 73 20 6e 6f 74 0a 2a 2a 20 6d 6f 64 69 66 69  as not.** modifi
b480: 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a  ed..**.** The sz
b490: 4f 73 46 69 6c 65 20 66 69 65 6c 64 20 69 73 20  OsFile field is 
b4a0: 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
b4b0: 73 75 62 63 6c 61 73 73 65 64 20 5b 73 71 6c 69  subclassed [sqli
b4c0: 74 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74 72  te3_file].** str
b4d0: 75 63 74 75 72 65 20 75 73 65 64 20 62 79 20 74  ucture used by t
b4e0: 68 69 73 20 56 46 53 2e 20 20 6d 78 50 61 74 68  his VFS.  mxPath
b4f0: 6e 61 6d 65 20 69 73 20 74 68 65 20 6d 61 78 69  name is the maxi
b500: 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a  mum length of.**
b510: 20 61 20 70 61 74 68 6e 61 6d 65 20 69 6e 20 74   a pathname in t
b520: 68 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52  his VFS..**.** R
b530: 65 67 69 73 74 65 72 65 64 20 73 71 6c 69 74 65  egistered sqlite
b540: 33 5f 76 66 73 20 6f 62 6a 65 63 74 73 20 61 72  3_vfs objects ar
b550: 65 20 6b 65 70 74 20 6f 6e 20 61 20 6c 69 6e 6b  e kept on a link
b560: 65 64 20 6c 69 73 74 20 66 6f 72 6d 65 64 20 62  ed list formed b
b570: 79 0a 2a 2a 20 74 68 65 20 70 4e 65 78 74 20 70  y.** the pNext p
b580: 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 5b 73 71  ointer.  The [sq
b590: 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74  lite3_vfs_regist
b5a0: 65 72 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71  er()].** and [sq
b5b0: 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 67 69  lite3_vfs_unregi
b5c0: 73 74 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63  ster()] interfac
b5d0: 65 73 20 6d 61 6e 61 67 65 20 74 68 69 73 20 6c  es manage this l
b5e0: 69 73 74 0a 2a 2a 20 69 6e 20 61 20 74 68 72 65  ist.** in a thre
b5f0: 61 64 2d 73 61 66 65 20 77 61 79 2e 20 20 54 68  ad-safe way.  Th
b600: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 66  e [sqlite3_vfs_f
b610: 69 6e 64 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ind()] interface
b620: 0a 2a 2a 20 73 65 61 72 63 68 65 73 20 74 68 65  .** searches the
b630: 20 6c 69 73 74 2e 20 20 4e 65 69 74 68 65 72 20   list.  Neither 
b640: 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
b650: 63 6f 64 65 20 6e 6f 72 20 74 68 65 20 56 46 53  code nor the VFS
b660: 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
b670: 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 20 74 68  on should use th
b680: 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e  e pNext pointer.
b690: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e 65 78 74  .**.** The pNext
b6a0: 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 6f 6e   field is the on
b6b0: 6c 79 20 66 69 65 6c 64 20 69 6e 20 74 68 65 20  ly field in the 
b6c0: 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 73  sqlite3_vfs.** s
b6d0: 74 72 75 63 74 75 72 65 20 74 68 61 74 20 53 51  tructure that SQ
b6e0: 4c 69 74 65 20 77 69 6c 6c 20 65 76 65 72 20 6d  Lite will ever m
b6f0: 6f 64 69 66 79 2e 20 20 53 51 4c 69 74 65 20 77  odify.  SQLite w
b700: 69 6c 6c 20 6f 6e 6c 79 20 61 63 63 65 73 73 0a  ill only access.
b710: 2a 2a 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69  ** or modify thi
b720: 73 20 66 69 65 6c 64 20 77 68 69 6c 65 20 68 6f  s field while ho
b730: 6c 64 69 6e 67 20 61 20 70 61 72 74 69 63 75 6c  lding a particul
b740: 61 72 20 73 74 61 74 69 63 20 6d 75 74 65 78 2e  ar static mutex.
b750: 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
b760: 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72  ion should never
b770: 20 6d 6f 64 69 66 79 20 61 6e 79 74 68 69 6e 67   modify anything
b780: 20 77 69 74 68 69 6e 20 74 68 65 20 73 71 6c 69   within the sqli
b790: 74 65 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65 63  te3_vfs.** objec
b7a0: 74 20 6f 6e 63 65 20 74 68 65 20 6f 62 6a 65 63  t once the objec
b7b0: 74 20 68 61 73 20 62 65 65 6e 20 72 65 67 69 73  t has been regis
b7c0: 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  tered..**.** The
b7d0: 20 7a 4e 61 6d 65 20 66 69 65 6c 64 20 68 6f 6c   zName field hol
b7e0: 64 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  ds the name of t
b7f0: 68 65 20 56 46 53 20 6d 6f 64 75 6c 65 2e 20 20  he VFS module.  
b800: 54 68 65 20 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a  The name must.**
b810: 20 62 65 20 75 6e 69 71 75 65 20 61 63 72 6f 73   be unique acros
b820: 73 20 61 6c 6c 20 56 46 53 20 6d 6f 64 75 6c 65  s all VFS module
b830: 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74  s..**.** [[sqlit
b840: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 5d 0a 2a  e3_vfs.xOpen]].*
b850: 2a 20 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e  * ^SQLite guaran
b860: 74 65 65 73 20 74 68 61 74 20 74 68 65 20 7a 46  tees that the zF
b870: 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65  ilename paramete
b880: 72 20 74 6f 20 78 4f 70 65 6e 0a 2a 2a 20 69 73  r to xOpen.** is
b890: 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 20 70   either a NULL p
b8a0: 6f 69 6e 74 65 72 20 6f 72 20 73 74 72 69 6e 67  ointer or string
b8b0: 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f   obtained.** fro
b8c0: 6d 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 28  m xFullPathname(
b8d0: 29 20 77 69 74 68 20 61 6e 20 6f 70 74 69 6f 6e  ) with an option
b8e0: 61 6c 20 73 75 66 66 69 78 20 61 64 64 65 64 2e  al suffix added.
b8f0: 0a 2a 2a 20 5e 49 66 20 61 20 73 75 66 66 69 78  .** ^If a suffix
b900: 20 69 73 20 61 64 64 65 64 20 74 6f 20 74 68 65   is added to the
b910: 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d   zFilename param
b920: 65 74 65 72 2c 20 69 74 20 77 69 6c 6c 0a 2a 2a  eter, it will.**
b930: 20 63 6f 6e 73 69 73 74 20 6f 66 20 61 20 73 69   consist of a si
b940: 6e 67 6c 65 20 22 2d 22 20 63 68 61 72 61 63 74  ngle "-" charact
b950: 65 72 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 6e  er followed by n
b960: 6f 20 6d 6f 72 65 20 74 68 61 6e 0a 2a 2a 20 31  o more than.** 1
b970: 31 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 61  1 alphanumeric a
b980: 6e 64 2f 6f 72 20 22 2d 22 20 63 68 61 72 61 63  nd/or "-" charac
b990: 74 65 72 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65  ters..** ^SQLite
b9a0: 20 66 75 72 74 68 65 72 20 67 75 61 72 61 6e 74   further guarant
b9b0: 65 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  ees that.** the 
b9c0: 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 20 76  string will be v
b9d0: 61 6c 69 64 20 61 6e 64 20 75 6e 63 68 61 6e 67  alid and unchang
b9e0: 65 64 20 75 6e 74 69 6c 20 78 43 6c 6f 73 65 28  ed until xClose(
b9f0: 29 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20  ) is.** called. 
ba00: 42 65 63 61 75 73 65 20 6f 66 20 74 68 65 20 70  Because of the p
ba10: 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65  revious sentence
ba20: 2c 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65  ,.** the [sqlite
ba30: 33 5f 66 69 6c 65 5d 20 63 61 6e 20 73 61 66 65  3_file] can safe
ba40: 6c 79 20 73 74 6f 72 65 20 61 20 70 6f 69 6e 74  ly store a point
ba50: 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 6c  er to the.** fil
ba60: 65 6e 61 6d 65 20 69 66 20 69 74 20 6e 65 65 64  ename if it need
ba70: 73 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 74 68  s to remember th
ba80: 65 20 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20 73  e filename for s
ba90: 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49  ome reason..** I
baa0: 66 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20  f the zFilename 
bab0: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70  parameter to xOp
bac0: 65 6e 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  en is a NULL poi
bad0: 6e 74 65 72 20 74 68 65 6e 20 78 4f 70 65 6e 0a  nter then xOpen.
bae0: 2a 2a 20 6d 75 73 74 20 69 6e 76 65 6e 74 20 69  ** must invent i
baf0: 74 73 20 6f 77 6e 20 74 65 6d 70 6f 72 61 72 79  ts own temporary
bb00: 20 6e 61 6d 65 20 66 6f 72 20 74 68 65 20 66 69   name for the fi
bb10: 6c 65 2e 20 20 5e 57 68 65 6e 65 76 65 72 20 74  le.  ^Whenever t
bb20: 68 65 20 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d 65  he .** xFilename
bb30: 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 4e 55   parameter is NU
bb40: 4c 4c 20 69 74 20 77 69 6c 6c 20 61 6c 73 6f 20  LL it will also 
bb50: 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61 74  be the case that
bb60: 20 74 68 65 0a 2a 2a 20 66 6c 61 67 73 20 70 61   the.** flags pa
bb70: 72 61 6d 65 74 65 72 20 77 69 6c 6c 20 69 6e 63  rameter will inc
bb80: 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45  lude [SQLITE_OPE
bb90: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d  N_DELETEONCLOSE]
bba0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67  ..**.** The flag
bbb0: 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f  s argument to xO
bbc0: 70 65 6e 28 29 20 69 6e 63 6c 75 64 65 73 20 61  pen() includes a
bbd0: 6c 6c 20 62 69 74 73 20 73 65 74 20 69 6e 0a 2a  ll bits set in.*
bbe0: 2a 20 74 68 65 20 66 6c 61 67 73 20 61 72 67 75  * the flags argu
bbf0: 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  ment to [sqlite3
bc00: 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 20 4f 72  _open_v2()].  Or
bc10: 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   if [sqlite3_ope
bc20: 6e 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69  n()].** or [sqli
bc30: 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 69 73  te3_open16()] is
bc40: 20 75 73 65 64 2c 20 74 68 65 6e 20 66 6c 61 67   used, then flag
bc50: 73 20 69 6e 63 6c 75 64 65 73 20 61 74 20 6c 65  s includes at le
bc60: 61 73 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  ast.** [SQLITE_O
bc70: 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c  PEN_READWRITE] |
bc80: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52   [SQLITE_OPEN_CR
bc90: 45 41 54 45 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f  EATE]. .** If xO
bca0: 70 65 6e 28 29 20 6f 70 65 6e 73 20 61 20 66 69  pen() opens a fi
bcb0: 6c 65 20 72 65 61 64 2d 6f 6e 6c 79 20 74 68 65  le read-only the
bcc0: 6e 20 69 74 20 73 65 74 73 20 2a 70 4f 75 74 46  n it sets *pOutF
bcd0: 6c 61 67 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75  lags to.** inclu
bce0: 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  de [SQLITE_OPEN_
bcf0: 52 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65  READONLY].  Othe
bd00: 72 20 62 69 74 73 20 69 6e 20 2a 70 4f 75 74 46  r bits in *pOutF
bd10: 6c 61 67 73 20 6d 61 79 20 62 65 20 73 65 74 2e  lags may be set.
bd20: 0a 2a 2a 0a 2a 2a 20 5e 28 53 51 4c 69 74 65 20  .**.** ^(SQLite 
bd30: 77 69 6c 6c 20 61 6c 73 6f 20 61 64 64 20 6f 6e  will also add on
bd40: 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69  e of the followi
bd50: 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20  ng flags to the 
bd60: 78 4f 70 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c  xOpen().** call,
bd70: 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68   depending on th
bd80: 65 20 6f 62 6a 65 63 74 20 62 65 69 6e 67 20 6f  e object being o
bd90: 70 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  pened:.**.** <ul
bda0: 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  >.** <li>  [SQLI
bdb0: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d  TE_OPEN_MAIN_DB]
bdc0: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
bdd0: 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52  E_OPEN_MAIN_JOUR
bde0: 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  NAL].** <li>  [S
bdf0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f  QLITE_OPEN_TEMP_
be00: 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  DB].** <li>  [SQ
be10: 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a  LITE_OPEN_TEMP_J
be20: 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20  OURNAL].** <li> 
be30: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52   [SQLITE_OPEN_TR
be40: 41 4e 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c  ANSIENT_DB].** <
be50: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
be60: 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a  N_SUBJOURNAL].**
be70: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
be80: 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e  PEN_MASTER_JOURN
be90: 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  AL].** <li>  [SQ
bea0: 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 5d 0a 2a  LITE_OPEN_WAL].*
beb0: 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20  * </ul>)^.**.** 
bec0: 54 68 65 20 66 69 6c 65 20 49 2f 4f 20 69 6d 70  The file I/O imp
bed0: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e 20  lementation can 
bee0: 75 73 65 20 74 68 65 20 6f 62 6a 65 63 74 20 74  use the object t
bef0: 79 70 65 20 66 6c 61 67 73 20 74 6f 0a 2a 2a 20  ype flags to.** 
bf00: 63 68 61 6e 67 65 20 74 68 65 20 77 61 79 20 69  change the way i
bf10: 74 20 64 65 61 6c 73 20 77 69 74 68 20 66 69 6c  t deals with fil
bf20: 65 73 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65  es.  For example
bf30: 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  , an application
bf40: 0a 2a 2a 20 74 68 61 74 20 64 6f 65 73 20 6e 6f  .** that does no
bf50: 74 20 63 61 72 65 20 61 62 6f 75 74 20 63 72 61  t care about cra
bf60: 73 68 20 72 65 63 6f 76 65 72 79 20 6f 72 20 72  sh recovery or r
bf70: 6f 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 6d 61  ollback might ma
bf80: 6b 65 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 20 6f  ke.** the open o
bf90: 66 20 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65  f a journal file
bfa0: 20 61 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 74 65   a no-op.  Write
bfb0: 73 20 74 6f 20 74 68 69 73 20 6a 6f 75 72 6e 61  s to this journa
bfc0: 6c 20 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20  l would.** also 
bfd0: 62 65 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20 61  be no-ops, and a
bfe0: 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 72 65  ny attempt to re
bff0: 61 64 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20 77  ad the journal w
c000: 6f 75 6c 64 20 72 65 74 75 72 6e 0a 2a 2a 20 53  ould return.** S
c010: 51 4c 49 54 45 5f 49 4f 45 52 52 2e 20 20 4f 72  QLITE_IOERR.  Or
c020: 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   the implementat
c030: 69 6f 6e 20 6d 69 67 68 74 20 72 65 63 6f 67 6e  ion might recogn
c040: 69 7a 65 20 74 68 61 74 20 61 20 64 61 74 61 62  ize that a datab
c050: 61 73 65 0a 2a 2a 20 66 69 6c 65 20 77 69 6c 6c  ase.** file will
c060: 20 62 65 20 64 6f 69 6e 67 20 70 61 67 65 2d 61   be doing page-a
c070: 6c 69 67 6e 65 64 20 73 65 63 74 6f 72 20 72 65  ligned sector re
c080: 61 64 73 20 61 6e 64 20 77 72 69 74 65 73 20 69  ads and writes i
c090: 6e 20 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72  n a random.** or
c0a0: 64 65 72 20 61 6e 64 20 73 65 74 20 75 70 20 69  der and set up i
c0b0: 74 73 20 49 2f 4f 20 73 75 62 73 79 73 74 65 6d  ts I/O subsystem
c0c0: 20 61 63 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a   accordingly..**
c0d0: 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 69 67 68 74  .** SQLite might
c0e0: 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66   also add one of
c0f0: 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66   the following f
c100: 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65  lags to the xOpe
c110: 6e 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20  n method:.**.** 
c120: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  <ul>.** <li> [SQ
c130: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45  LITE_OPEN_DELETE
c140: 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e  ONCLOSE].** <li>
c150: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58   [SQLITE_OPEN_EX
c160: 43 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c  CLUSIVE].** </ul
c170: 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  >.**.** The [SQL
c180: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f  ITE_OPEN_DELETEO
c190: 4e 43 4c 4f 53 45 5d 20 66 6c 61 67 20 6d 65 61  NCLOSE] flag mea
c1a0: 6e 73 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75  ns the file shou
c1b0: 6c 64 20 62 65 0a 2a 2a 20 64 65 6c 65 74 65 64  ld be.** deleted
c1c0: 20 77 68 65 6e 20 69 74 20 69 73 20 63 6c 6f 73   when it is clos
c1d0: 65 64 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49 54  ed.  ^The [SQLIT
c1e0: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43  E_OPEN_DELETEONC
c1f0: 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65  LOSE].** will be
c200: 20 73 65 74 20 66 6f 72 20 54 45 4d 50 20 64 61   set for TEMP da
c210: 74 61 62 61 73 65 73 20 61 6e 64 20 74 68 65 69  tabases and thei
c220: 72 20 6a 6f 75 72 6e 61 6c 73 2c 20 74 72 61 6e  r journals, tran
c230: 73 69 65 6e 74 0a 2a 2a 20 64 61 74 61 62 61 73  sient.** databas
c240: 65 73 2c 20 61 6e 64 20 73 75 62 6a 6f 75 72 6e  es, and subjourn
c250: 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  als..**.** ^The 
c260: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43  [SQLITE_OPEN_EXC
c270: 4c 55 53 49 56 45 5d 20 66 6c 61 67 20 69 73 20  LUSIVE] flag is 
c280: 61 6c 77 61 79 73 20 75 73 65 64 20 69 6e 20 63  always used in c
c290: 6f 6e 6a 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69  onjunction.** wi
c2a0: 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  th the [SQLITE_O
c2b0: 50 45 4e 5f 43 52 45 41 54 45 5d 20 66 6c 61 67  PEN_CREATE] flag
c2c0: 2c 20 77 68 69 63 68 20 61 72 65 20 62 6f 74 68  , which are both
c2d0: 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 61 6e 61   directly.** ana
c2e0: 6c 6f 67 6f 75 73 20 74 6f 20 74 68 65 20 4f 5f  logous to the O_
c2f0: 45 58 43 4c 20 61 6e 64 20 4f 5f 43 52 45 41 54  EXCL and O_CREAT
c300: 20 66 6c 61 67 73 20 6f 66 20 74 68 65 20 50 4f   flags of the PO
c310: 53 49 58 20 6f 70 65 6e 28 29 0a 2a 2a 20 41 50  SIX open().** AP
c320: 49 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 4f  I.  The SQLITE_O
c330: 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 66 6c  PEN_EXCLUSIVE fl
c340: 61 67 2c 20 77 68 65 6e 20 70 61 69 72 65 64 20  ag, when paired 
c350: 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 53 51 4c  with the .** SQL
c360: 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2c  ITE_OPEN_CREATE,
c370: 20 69 73 20 75 73 65 64 20 74 6f 20 69 6e 64 69   is used to indi
c380: 63 61 74 65 20 74 68 61 74 20 66 69 6c 65 20 73  cate that file s
c390: 68 6f 75 6c 64 20 61 6c 77 61 79 73 0a 2a 2a 20  hould always.** 
c3a0: 62 65 20 63 72 65 61 74 65 64 2c 20 61 6e 64 20  be created, and 
c3b0: 74 68 61 74 20 69 74 20 69 73 20 61 6e 20 65 72  that it is an er
c3c0: 72 6f 72 20 69 66 20 69 74 20 61 6c 72 65 61 64  ror if it alread
c3d0: 79 20 65 78 69 73 74 73 2e 0a 2a 2a 20 49 74 20  y exists..** It 
c3e0: 69 73 20 3c 69 3e 6e 6f 74 3c 2f 69 3e 20 75 73  is <i>not</i> us
c3f0: 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74  ed to indicate t
c400: 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62  he file should b
c410: 65 20 6f 70 65 6e 65 64 20 0a 2a 2a 20 66 6f 72  e opened .** for
c420: 20 65 78 63 6c 75 73 69 76 65 20 61 63 63 65 73   exclusive acces
c430: 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 74 20 6c 65 61  s..**.** ^At lea
c440: 73 74 20 73 7a 4f 73 46 69 6c 65 20 62 79 74 65  st szOsFile byte
c450: 73 20 6f 66 20 6d 65 6d 6f 72 79 20 61 72 65 20  s of memory are 
c460: 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 53 51 4c  allocated by SQL
c470: 69 74 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20 74  ite.** to hold t
c480: 68 65 20 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  he  [sqlite3_fil
c490: 65 5d 20 73 74 72 75 63 74 75 72 65 20 70 61 73  e] structure pas
c4a0: 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72 64  sed as the third
c4b0: 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  .** argument to 
c4c0: 78 4f 70 65 6e 2e 20 20 54 68 65 20 78 4f 70 65  xOpen.  The xOpe
c4d0: 6e 20 6d 65 74 68 6f 64 20 64 6f 65 73 20 6e 6f  n method does no
c4e0: 74 20 68 61 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c  t have to.** all
c4f0: 6f 63 61 74 65 20 74 68 65 20 73 74 72 75 63 74  ocate the struct
c500: 75 72 65 3b 20 69 74 20 73 68 6f 75 6c 64 20 6a  ure; it should j
c510: 75 73 74 20 66 69 6c 6c 20 69 74 20 69 6e 2e 20  ust fill it in. 
c520: 20 4e 6f 74 65 20 74 68 61 74 0a 2a 2a 20 74 68   Note that.** th
c530: 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6d  e xOpen method m
c540: 75 73 74 20 73 65 74 20 74 68 65 20 73 71 6c 69  ust set the sqli
c550: 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64  te3_file.pMethod
c560: 73 20 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20 61  s to either.** a
c570: 20 76 61 6c 69 64 20 5b 73 71 6c 69 74 65 33 5f   valid [sqlite3_
c580: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  io_methods] obje
c590: 63 74 20 6f 72 20 74 6f 20 4e 55 4c 4c 2e 20 20  ct or to NULL.  
c5a0: 78 4f 70 65 6e 20 6d 75 73 74 20 64 6f 0a 2a 2a  xOpen must do.**
c5b0: 20 74 68 69 73 20 65 76 65 6e 20 69 66 20 74 68   this even if th
c5c0: 65 20 6f 70 65 6e 20 66 61 69 6c 73 2e 20 20 53  e open fails.  S
c5d0: 51 4c 69 74 65 20 65 78 70 65 63 74 73 20 74 68  QLite expects th
c5e0: 61 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66  at the sqlite3_f
c5f0: 69 6c 65 2e 70 4d 65 74 68 6f 64 73 0a 2a 2a 20  ile.pMethods.** 
c600: 65 6c 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20  element will be 
c610: 76 61 6c 69 64 20 61 66 74 65 72 20 78 4f 70 65  valid after xOpe
c620: 6e 20 72 65 74 75 72 6e 73 20 72 65 67 61 72 64  n returns regard
c630: 6c 65 73 73 20 6f 66 20 74 68 65 20 73 75 63 63  less of the succ
c640: 65 73 73 0a 2a 2a 20 6f 72 20 66 61 69 6c 75 72  ess.** or failur
c650: 65 20 6f 66 20 74 68 65 20 78 4f 70 65 6e 20 63  e of the xOpen c
c660: 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c  all..**.** [[sql
c670: 69 74 65 33 5f 76 66 73 2e 78 41 63 63 65 73 73  ite3_vfs.xAccess
c680: 5d 5d 0a 2a 2a 20 5e 54 68 65 20 66 6c 61 67 73  ]].** ^The flags
c690: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 41 63   argument to xAc
c6a0: 63 65 73 73 28 29 20 6d 61 79 20 62 65 20 5b 53  cess() may be [S
c6b0: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49  QLITE_ACCESS_EXI
c6c0: 53 54 53 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20  STS].** to test 
c6d0: 66 6f 72 20 74 68 65 20 65 78 69 73 74 65 6e 63  for the existenc
c6e0: 65 20 6f 66 20 61 20 66 69 6c 65 2c 20 6f 72 20  e of a file, or 
c6f0: 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52  [SQLITE_ACCESS_R
c700: 45 41 44 57 52 49 54 45 5d 20 74 6f 0a 2a 2a 20  EADWRITE] to.** 
c710: 74 65 73 74 20 77 68 65 74 68 65 72 20 61 20 66  test whether a f
c720: 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65 20  ile is readable 
c730: 61 6e 64 20 77 72 69 74 61 62 6c 65 2c 20 6f 72  and writable, or
c740: 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f   [SQLITE_ACCESS_
c750: 52 45 41 44 5d 0a 2a 2a 20 74 6f 20 74 65 73 74  READ].** to test
c760: 20 77 68 65 74 68 65 72 20 61 20 66 69 6c 65 20   whether a file 
c770: 69 73 20 61 74 20 6c 65 61 73 74 20 72 65 61 64  is at least read
c780: 61 62 6c 65 2e 20 20 20 54 68 65 20 66 69 6c 65  able.   The file
c790: 20 63 61 6e 20 62 65 20 61 0a 2a 2a 20 64 69 72   can be a.** dir
c7a0: 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 53  ectory..**.** ^S
c7b0: 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77 61 79  QLite will alway
c7c0: 73 20 61 6c 6c 6f 63 61 74 65 20 61 74 20 6c 65  s allocate at le
c7d0: 61 73 74 20 6d 78 50 61 74 68 6e 61 6d 65 2b 31  ast mxPathname+1
c7e0: 20 62 79 74 65 73 20 66 6f 72 20 74 68 65 0a 2a   bytes for the.*
c7f0: 2a 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 20  * output buffer 
c800: 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 2e 20 20  xFullPathname.  
c810: 54 68 65 20 65 78 61 63 74 20 73 69 7a 65 20 6f  The exact size o
c820: 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 66  f the output buf
c830: 66 65 72 0a 2a 2a 20 69 73 20 61 6c 73 6f 20 70  fer.** is also p
c840: 61 73 73 65 64 20 61 73 20 61 20 70 61 72 61 6d  assed as a param
c850: 65 74 65 72 20 74 6f 20 62 6f 74 68 20 20 6d 65  eter to both  me
c860: 74 68 6f 64 73 2e 20 49 66 20 74 68 65 20 6f 75  thods. If the ou
c870: 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69  tput buffer.** i
c880: 73 20 6e 6f 74 20 6c 61 72 67 65 20 65 6e 6f 75  s not large enou
c890: 67 68 2c 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54  gh, [SQLITE_CANT
c8a0: 4f 50 45 4e 5d 20 73 68 6f 75 6c 64 20 62 65 20  OPEN] should be 
c8b0: 72 65 74 75 72 6e 65 64 2e 20 53 69 6e 63 65 20  returned. Since 
c8c0: 74 68 69 73 20 69 73 0a 2a 2a 20 68 61 6e 64 6c  this is.** handl
c8d0: 65 64 20 61 73 20 61 20 66 61 74 61 6c 20 65 72  ed as a fatal er
c8e0: 72 6f 72 20 62 79 20 53 51 4c 69 74 65 2c 20 76  ror by SQLite, v
c8f0: 66 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  fs implementatio
c900: 6e 73 20 73 68 6f 75 6c 64 20 65 6e 64 65 61 76  ns should endeav
c910: 6f 72 0a 2a 2a 20 74 6f 20 70 72 65 76 65 6e 74  or.** to prevent
c920: 20 74 68 69 73 20 62 79 20 73 65 74 74 69 6e 67   this by setting
c930: 20 6d 78 50 61 74 68 6e 61 6d 65 20 74 6f 20 61   mxPathname to a
c940: 20 73 75 66 66 69 63 69 65 6e 74 6c 79 20 6c 61   sufficiently la
c950: 72 67 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a  rge value..**.**
c960: 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73   The xRandomness
c970: 28 29 2c 20 78 53 6c 65 65 70 28 29 2c 20 78 43  (), xSleep(), xC
c980: 75 72 72 65 6e 74 54 69 6d 65 28 29 2c 20 61 6e  urrentTime(), an
c990: 64 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e  d xCurrentTimeIn
c9a0: 74 36 34 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61  t64().** interfa
c9b0: 63 65 73 20 61 72 65 20 6e 6f 74 20 73 74 72 69  ces are not stri
c9c0: 63 74 6c 79 20 61 20 70 61 72 74 20 6f 66 20 74  ctly a part of t
c9d0: 68 65 20 66 69 6c 65 73 79 73 74 65 6d 2c 20 62  he filesystem, b
c9e0: 75 74 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 69  ut they are.** i
c9f0: 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65 20 56  ncluded in the V
ca00: 46 53 20 73 74 72 75 63 74 75 72 65 20 66 6f 72  FS structure for
ca10: 20 63 6f 6d 70 6c 65 74 65 6e 65 73 73 2e 0a 2a   completeness..*
ca20: 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73  * The xRandomnes
ca30: 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 74 74  s() function att
ca40: 65 6d 70 74 73 20 74 6f 20 72 65 74 75 72 6e 20  empts to return 
ca50: 6e 42 79 74 65 73 20 62 79 74 65 73 0a 2a 2a 20  nBytes bytes.** 
ca60: 6f 66 20 67 6f 6f 64 2d 71 75 61 6c 69 74 79 20  of good-quality 
ca70: 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20  randomness into 
ca80: 7a 4f 75 74 2e 20 20 54 68 65 20 72 65 74 75 72  zOut.  The retur
ca90: 6e 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 74 68  n value is.** th
caa0: 65 20 61 63 74 75 61 6c 20 6e 75 6d 62 65 72 20  e actual number 
cab0: 6f 66 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64  of bytes of rand
cac0: 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 2e  omness obtained.
cad0: 0a 2a 2a 20 54 68 65 20 78 53 6c 65 65 70 28 29  .** The xSleep()
cae0: 20 6d 65 74 68 6f 64 20 63 61 75 73 65 73 20 74   method causes t
caf0: 68 65 20 63 61 6c 6c 69 6e 67 20 74 68 72 65 61  he calling threa
cb00: 64 20 74 6f 20 73 6c 65 65 70 20 66 6f 72 20 61  d to sleep for a
cb10: 74 0a 2a 2a 20 6c 65 61 73 74 20 74 68 65 20 6e  t.** least the n
cb20: 75 6d 62 65 72 20 6f 66 20 6d 69 63 72 6f 73 65  umber of microse
cb30: 63 6f 6e 64 73 20 67 69 76 65 6e 2e 20 20 5e 54  conds given.  ^T
cb40: 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28  he xCurrentTime(
cb50: 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75  ).** method retu
cb60: 72 6e 73 20 61 20 4a 75 6c 69 61 6e 20 44 61 79  rns a Julian Day
cb70: 20 4e 75 6d 62 65 72 20 66 6f 72 20 74 68 65 20   Number for the 
cb80: 63 75 72 72 65 6e 74 20 64 61 74 65 20 61 6e 64  current date and
cb90: 20 74 69 6d 65 20 61 73 0a 2a 2a 20 61 20 66 6c   time as.** a fl
cba0: 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c  oating point val
cbb0: 75 65 2e 0a 2a 2a 20 5e 54 68 65 20 78 43 75 72  ue..** ^The xCur
cbc0: 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20  rentTimeInt64() 
cbd0: 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 2c 20  method returns, 
cbe0: 61 73 20 61 6e 20 69 6e 74 65 67 65 72 2c 20 74  as an integer, t
cbf0: 68 65 20 4a 75 6c 69 61 6e 0a 2a 2a 20 44 61 79  he Julian.** Day
cc00: 20 4e 75 6d 62 65 72 20 6d 75 6c 74 69 70 6c 69   Number multipli
cc10: 65 64 20 62 79 20 38 36 34 30 30 30 30 30 20 28  ed by 86400000 (
cc20: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69  the number of mi
cc30: 6c 6c 69 73 65 63 6f 6e 64 73 20 69 6e 20 0a 2a  lliseconds in .*
cc40: 2a 20 61 20 32 34 2d 68 6f 75 72 20 64 61 79 29  * a 24-hour day)
cc50: 2e 20 20 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77  .  .** ^SQLite w
cc60: 69 6c 6c 20 75 73 65 20 74 68 65 20 78 43 75 72  ill use the xCur
cc70: 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20  rentTimeInt64() 
cc80: 6d 65 74 68 6f 64 20 74 6f 20 67 65 74 20 74 68  method to get th
cc90: 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 64 61 74  e current.** dat
cca0: 65 20 61 6e 64 20 74 69 6d 65 20 69 66 20 74 68  e and time if th
ccb0: 61 74 20 6d 65 74 68 6f 64 20 69 73 20 61 76 61  at method is ava
ccc0: 69 6c 61 62 6c 65 20 28 69 66 20 69 56 65 72 73  ilable (if iVers
ccd0: 69 6f 6e 20 69 73 20 32 20 6f 72 20 0a 2a 2a 20  ion is 2 or .** 
cce0: 67 72 65 61 74 65 72 20 61 6e 64 20 74 68 65 20  greater and the 
ccf0: 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72  function pointer
cd00: 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 29 20 61 6e   is not NULL) an
cd10: 64 20 77 69 6c 6c 20 66 61 6c 6c 20 62 61 63 6b  d will fall back
cd20: 0a 2a 2a 20 74 6f 20 78 43 75 72 72 65 6e 74 54  .** to xCurrentT
cd30: 69 6d 65 28 29 20 69 66 20 78 43 75 72 72 65 6e  ime() if xCurren
cd40: 74 54 69 6d 65 49 6e 74 36 34 28 29 20 69 73 20  tTimeInt64() is 
cd50: 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 0a  unavailable..**.
cd60: 2a 2a 20 5e 54 68 65 20 78 53 65 74 53 79 73 74  ** ^The xSetSyst
cd70: 65 6d 43 61 6c 6c 28 29 2c 20 78 47 65 74 53 79  emCall(), xGetSy
cd80: 73 74 65 6d 43 61 6c 6c 28 29 2c 20 61 6e 64 20  stemCall(), and 
cd90: 78 4e 65 73 74 53 79 73 74 65 6d 43 61 6c 6c 28  xNestSystemCall(
cda0: 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  ) interfaces.** 
cdb0: 61 72 65 20 6e 6f 74 20 75 73 65 64 20 62 79 20  are not used by 
cdc0: 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 2e  the SQLite core.
cdd0: 20 20 54 68 65 73 65 20 6f 70 74 69 6f 6e 61 6c    These optional
cde0: 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
cdf0: 70 72 6f 76 69 64 65 64 0a 2a 2a 20 62 79 20 73  provided.** by s
ce00: 6f 6d 65 20 56 46 53 65 73 20 74 6f 20 66 61 63  ome VFSes to fac
ce10: 69 6c 69 74 61 74 65 20 74 65 73 74 69 6e 67 20  ilitate testing 
ce20: 6f 66 20 74 68 65 20 56 46 53 20 63 6f 64 65 2e  of the VFS code.
ce30: 20 42 79 20 6f 76 65 72 72 69 64 69 6e 67 20 0a   By overriding .
ce40: 2a 2a 20 73 79 73 74 65 6d 20 63 61 6c 6c 73 20  ** system calls 
ce50: 77 69 74 68 20 66 75 6e 63 74 69 6f 6e 73 20 75  with functions u
ce60: 6e 64 65 72 20 69 74 73 20 63 6f 6e 74 72 6f 6c  nder its control
ce70: 2c 20 61 20 74 65 73 74 20 70 72 6f 67 72 61 6d  , a test program
ce80: 20 63 61 6e 0a 2a 2a 20 73 69 6d 75 6c 61 74 65   can.** simulate
ce90: 20 66 61 75 6c 74 73 20 61 6e 64 20 65 72 72 6f   faults and erro
cea0: 72 20 63 6f 6e 64 69 74 69 6f 6e 73 20 74 68 61  r conditions tha
ceb0: 74 20 77 6f 75 6c 64 20 6f 74 68 65 72 77 69 73  t would otherwis
cec0: 65 20 62 65 20 64 69 66 66 69 63 75 6c 74 0a 2a  e be difficult.*
ced0: 2a 20 6f 72 20 69 6d 70 6f 73 73 69 62 6c 65 20  * or impossible 
cee0: 74 6f 20 69 6e 64 75 63 65 2e 20 20 54 68 65 20  to induce.  The 
cef0: 73 65 74 20 6f 66 20 73 79 73 74 65 6d 20 63 61  set of system ca
cf00: 6c 6c 73 20 74 68 61 74 20 63 61 6e 20 62 65 20  lls that can be 
cf10: 6f 76 65 72 72 69 64 64 65 6e 0a 2a 2a 20 76 61  overridden.** va
cf20: 72 69 65 73 20 66 72 6f 6d 20 6f 6e 65 20 56 46  ries from one VF
cf30: 53 20 74 6f 20 61 6e 6f 74 68 65 72 2c 20 61 6e  S to another, an
cf40: 64 20 66 72 6f 6d 20 6f 6e 65 20 76 65 72 73 69  d from one versi
cf50: 6f 6e 20 6f 66 20 74 68 65 20 73 61 6d 65 20 56  on of the same V
cf60: 46 53 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 65 78  FS to the.** nex
cf70: 74 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  t.  Applications
cf80: 20 74 68 61 74 20 75 73 65 20 74 68 65 73 65 20   that use these 
cf90: 69 6e 74 65 72 66 61 63 65 73 20 6d 75 73 74 20  interfaces must 
cfa0: 62 65 20 70 72 65 70 61 72 65 64 20 66 6f 72 20  be prepared for 
cfb0: 61 6e 79 0a 2a 2a 20 6f 72 20 61 6c 6c 20 6f 66  any.** or all of
cfc0: 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65   these interface
cfd0: 73 20 74 6f 20 62 65 20 4e 55 4c 4c 20 6f 72 20  s to be NULL or 
cfe0: 66 6f 72 20 74 68 65 69 72 20 62 65 68 61 76 69  for their behavi
cff0: 6f 72 20 74 6f 20 63 68 61 6e 67 65 0a 2a 2a 20  or to change.** 
d000: 66 72 6f 6d 20 6f 6e 65 20 72 65 6c 65 61 73 65  from one release
d010: 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 20 20 41   to the next.  A
d020: 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 75 73 74  pplications must
d030: 20 6e 6f 74 20 61 74 74 65 6d 70 74 20 74 6f 20   not attempt to 
d040: 61 63 63 65 73 73 0a 2a 2a 20 61 6e 79 20 6f 66  access.** any of
d050: 20 74 68 65 73 65 20 6d 65 74 68 6f 64 73 20 69   these methods i
d060: 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 6f  f the iVersion o
d070: 66 20 74 68 65 20 56 46 53 20 69 73 20 6c 65 73  f the VFS is les
d080: 73 20 74 68 61 6e 20 33 2e 0a 2a 2f 0a 74 79 70  s than 3..*/.typ
d090: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
d0a0: 74 65 33 5f 76 66 73 20 73 71 6c 69 74 65 33 5f  te3_vfs sqlite3_
d0b0: 76 66 73 3b 0a 74 79 70 65 64 65 66 20 76 6f 69  vfs;.typedef voi
d0c0: 64 20 28 2a 73 71 6c 69 74 65 33 5f 73 79 73 63  d (*sqlite3_sysc
d0d0: 61 6c 6c 5f 70 74 72 29 28 76 6f 69 64 29 3b 0a  all_ptr)(void);.
d0e0: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76  struct sqlite3_v
d0f0: 66 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73  fs {.  int iVers
d100: 69 6f 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20  ion;            
d110: 2f 2a 20 53 74 72 75 63 74 75 72 65 20 76 65 72  /* Structure ver
d120: 73 69 6f 6e 20 6e 75 6d 62 65 72 20 28 63 75 72  sion number (cur
d130: 72 65 6e 74 6c 79 20 33 29 20 2a 2f 0a 20 20 69  rently 3) */.  i
d140: 6e 74 20 73 7a 4f 73 46 69 6c 65 3b 20 20 20 20  nt szOsFile;    
d150: 20 20 20 20 20 20 20 20 2f 2a 20 53 69 7a 65 20          /* Size 
d160: 6f 66 20 73 75 62 63 6c 61 73 73 65 64 20 73 71  of subclassed sq
d170: 6c 69 74 65 33 5f 66 69 6c 65 20 2a 2f 0a 20 20  lite3_file */.  
d180: 69 6e 74 20 6d 78 50 61 74 68 6e 61 6d 65 3b 20  int mxPathname; 
d190: 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69           /* Maxi
d1a0: 6d 75 6d 20 66 69 6c 65 20 70 61 74 68 6e 61 6d  mum file pathnam
d1b0: 65 20 6c 65 6e 67 74 68 20 2a 2f 0a 20 20 73 71  e length */.  sq
d1c0: 6c 69 74 65 33 5f 76 66 73 20 2a 70 4e 65 78 74  lite3_vfs *pNext
d1d0: 3b 20 20 20 20 20 20 2f 2a 20 4e 65 78 74 20 72  ;      /* Next r
d1e0: 65 67 69 73 74 65 72 65 64 20 56 46 53 20 2a 2f  egistered VFS */
d1f0: 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
d200: 4e 61 6d 65 3b 20 20 20 20 20 20 20 2f 2a 20 4e  Name;       /* N
d210: 61 6d 65 20 6f 66 20 74 68 69 73 20 76 69 72 74  ame of this virt
d220: 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 20  ual file system 
d230: 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44  */.  void *pAppD
d240: 61 74 61 3b 20 20 20 20 20 20 20 20 20 20 2f 2a  ata;          /*
d250: 20 50 6f 69 6e 74 65 72 20 74 6f 20 61 70 70 6c   Pointer to appl
d260: 69 63 61 74 69 6f 6e 2d 73 70 65 63 69 66 69 63  ication-specific
d270: 20 64 61 74 61 20 2a 2f 0a 20 20 69 6e 74 20 28   data */.  int (
d280: 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f  *xOpen)(sqlite3_
d290: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
d2a0: 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33   *zName, sqlite3
d2b0: 5f 66 69 6c 65 2a 2c 0a 20 20 20 20 20 20 20 20  _file*,.        
d2c0: 20 20 20 20 20 20 20 69 6e 74 20 66 6c 61 67 73         int flags
d2d0: 2c 20 69 6e 74 20 2a 70 4f 75 74 46 6c 61 67 73  , int *pOutFlags
d2e0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 6c 65  );.  int (*xDele
d2f0: 74 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  te)(sqlite3_vfs*
d300: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
d310: 61 6d 65 2c 20 69 6e 74 20 73 79 6e 63 44 69 72  ame, int syncDir
d320: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 41 63 63 65  );.  int (*xAcce
d330: 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ss)(sqlite3_vfs*
d340: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
d350: 61 6d 65 2c 20 69 6e 74 20 66 6c 61 67 73 2c 20  ame, int flags, 
d360: 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20  int *pResOut);. 
d370: 20 69 6e 74 20 28 2a 78 46 75 6c 6c 50 61 74 68   int (*xFullPath
d380: 6e 61 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66  name)(sqlite3_vf
d390: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
d3a0: 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f 75 74 2c  zName, int nOut,
d3b0: 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20   char *zOut);.  
d3c0: 76 6f 69 64 20 2a 28 2a 78 44 6c 4f 70 65 6e 29  void *(*xDlOpen)
d3d0: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
d3e0: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65  onst char *zFile
d3f0: 6e 61 6d 65 29 3b 0a 20 20 76 6f 69 64 20 28 2a  name);.  void (*
d400: 78 44 6c 45 72 72 6f 72 29 28 73 71 6c 69 74 65  xDlError)(sqlite
d410: 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74  3_vfs*, int nByt
d420: 65 2c 20 63 68 61 72 20 2a 7a 45 72 72 4d 73 67  e, char *zErrMsg
d430: 29 3b 0a 20 20 76 6f 69 64 20 28 2a 28 2a 78 44  );.  void (*(*xD
d440: 6c 53 79 6d 29 28 73 71 6c 69 74 65 33 5f 76 66  lSym)(sqlite3_vf
d450: 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73 74 20  s*,void*, const 
d460: 63 68 61 72 20 2a 7a 53 79 6d 62 6f 6c 29 29 28  char *zSymbol))(
d470: 76 6f 69 64 29 3b 0a 20 20 76 6f 69 64 20 28 2a  void);.  void (*
d480: 78 44 6c 43 6c 6f 73 65 29 28 73 71 6c 69 74 65  xDlClose)(sqlite
d490: 33 5f 76 66 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a  3_vfs*, void*);.
d4a0: 20 20 69 6e 74 20 28 2a 78 52 61 6e 64 6f 6d 6e    int (*xRandomn
d4b0: 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ess)(sqlite3_vfs
d4c0: 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68  *, int nByte, ch
d4d0: 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e 74  ar *zOut);.  int
d4e0: 20 28 2a 78 53 6c 65 65 70 29 28 73 71 6c 69 74   (*xSleep)(sqlit
d4f0: 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 69 63  e3_vfs*, int mic
d500: 72 6f 73 65 63 6f 6e 64 73 29 3b 0a 20 20 69 6e  roseconds);.  in
d510: 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65  t (*xCurrentTime
d520: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
d530: 64 6f 75 62 6c 65 2a 29 3b 0a 20 20 69 6e 74 20  double*);.  int 
d540: 28 2a 78 47 65 74 4c 61 73 74 45 72 72 6f 72 29  (*xGetLastError)
d550: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69  (sqlite3_vfs*, i
d560: 6e 74 2c 20 63 68 61 72 20 2a 29 3b 0a 20 20 2f  nt, char *);.  /
d570: 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f  *.  ** The metho
d580: 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20  ds above are in 
d590: 76 65 72 73 69 6f 6e 20 31 20 6f 66 20 74 68 65  version 1 of the
d5a0: 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65   sqlite_vfs obje
d5b0: 63 74 0a 20 20 2a 2a 20 64 65 66 69 6e 69 74 69  ct.  ** definiti
d5c0: 6f 6e 2e 20 20 54 68 6f 73 65 20 74 68 61 74 20  on.  Those that 
d5d0: 66 6f 6c 6c 6f 77 20 61 72 65 20 61 64 64 65 64  follow are added
d5e0: 20 69 6e 20 76 65 72 73 69 6f 6e 20 32 20 6f 72   in version 2 or
d5f0: 20 6c 61 74 65 72 0a 20 20 2a 2f 0a 20 20 69 6e   later.  */.  in
d600: 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65  t (*xCurrentTime
d610: 49 6e 74 36 34 29 28 73 71 6c 69 74 65 33 5f 76  Int64)(sqlite3_v
d620: 66 73 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  fs*, sqlite3_int
d630: 36 34 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20  64*);.  /*.  ** 
d640: 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76  The methods abov
d650: 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e  e are in version
d660: 73 20 31 20 61 6e 64 20 32 20 6f 66 20 74 68 65  s 1 and 2 of the
d670: 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65   sqlite_vfs obje
d680: 63 74 2e 0a 20 20 2a 2a 20 54 68 6f 73 65 20 62  ct..  ** Those b
d690: 65 6c 6f 77 20 61 72 65 20 66 6f 72 20 76 65 72  elow are for ver
d6a0: 73 69 6f 6e 20 33 20 61 6e 64 20 67 72 65 61 74  sion 3 and great
d6b0: 65 72 2e 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28  er..  */.  int (
d6c0: 2a 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 29  *xSetSystemCall)
d6d0: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
d6e0: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
d6f0: 2c 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c  , sqlite3_syscal
d700: 6c 5f 70 74 72 29 3b 0a 20 20 73 71 6c 69 74 65  l_ptr);.  sqlite
d710: 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 20 28 2a  3_syscall_ptr (*
d720: 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c 29 28  xGetSystemCall)(
d730: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
d740: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29  nst char *zName)
d750: 3b 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  ;.  const char *
d760: 28 2a 78 4e 65 78 74 53 79 73 74 65 6d 43 61 6c  (*xNextSystemCal
d770: 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  l)(sqlite3_vfs*,
d780: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
d790: 6d 65 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54  me);.  /*.  ** T
d7a0: 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65  he methods above
d7b0: 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 73   are in versions
d7c0: 20 31 20 74 68 72 6f 75 67 68 20 33 20 6f 66 20   1 through 3 of 
d7d0: 74 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f  the sqlite_vfs o
d7e0: 62 6a 65 63 74 2e 0a 20 20 2a 2a 20 4e 65 77 20  bject..  ** New 
d7f0: 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70  fields may be ap
d800: 70 65 6e 64 65 64 20 69 6e 20 66 69 67 75 72 65  pended in figure
d810: 20 76 65 72 73 69 6f 6e 73 2e 20 20 54 68 65 20   versions.  The 
d820: 69 56 65 72 73 69 6f 6e 0a 20 20 2a 2a 20 76 61  iVersion.  ** va
d830: 6c 75 65 20 77 69 6c 6c 20 69 6e 63 72 65 6d 65  lue will increme
d840: 6e 74 20 77 68 65 6e 65 76 65 72 20 74 68 69 73  nt whenever this
d850: 20 68 61 70 70 65 6e 73 2e 20 0a 20 20 2a 2f 0a   happens. .  */.
d860: 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  };../*.** CAPI3R
d870: 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68  EF: Flags for th
d880: 65 20 78 41 63 63 65 73 73 20 56 46 53 20 6d 65  e xAccess VFS me
d890: 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  thod.**.** These
d8a0: 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e   integer constan
d8b0: 74 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 61  ts can be used a
d8c0: 73 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  s the third para
d8d0: 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20  meter to.** the 
d8e0: 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20 6f  xAccess method o
d8f0: 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66  f an [sqlite3_vf
d900: 73 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 79  s] object.  They
d910: 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 77 68   determine.** wh
d920: 61 74 20 6b 69 6e 64 20 6f 66 20 70 65 72 6d 69  at kind of permi
d930: 73 73 69 6f 6e 73 20 74 68 65 20 78 41 63 63 65  ssions the xAcce
d940: 73 73 20 6d 65 74 68 6f 64 20 69 73 20 6c 6f 6f  ss method is loo
d950: 6b 69 6e 67 20 66 6f 72 2e 0a 2a 2a 20 57 69 74  king for..** Wit
d960: 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  h SQLITE_ACCESS_
d970: 45 58 49 53 54 53 2c 20 74 68 65 20 78 41 63 63  EXISTS, the xAcc
d980: 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 73 69  ess method.** si
d990: 6d 70 6c 79 20 63 68 65 63 6b 73 20 77 68 65 74  mply checks whet
d9a0: 68 65 72 20 74 68 65 20 66 69 6c 65 20 65 78 69  her the file exi
d9b0: 73 74 73 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c  sts..** With SQL
d9c0: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57  ITE_ACCESS_READW
d9d0: 52 49 54 45 2c 20 74 68 65 20 78 41 63 63 65 73  RITE, the xAcces
d9e0: 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63  s method.** chec
d9f0: 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20 6e  ks whether the n
da00: 61 6d 65 64 20 64 69 72 65 63 74 6f 72 79 20 69  amed directory i
da10: 73 20 62 6f 74 68 20 72 65 61 64 61 62 6c 65 20  s both readable 
da20: 61 6e 64 20 77 72 69 74 61 62 6c 65 0a 2a 2a 20  and writable.** 
da30: 28 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c  (in other words,
da40: 20 69 66 20 66 69 6c 65 73 20 63 61 6e 20 62 65   if files can be
da50: 20 61 64 64 65 64 2c 20 72 65 6d 6f 76 65 64 2c   added, removed,
da60: 20 61 6e 64 20 72 65 6e 61 6d 65 64 20 77 69 74   and renamed wit
da70: 68 69 6e 0a 2a 2a 20 74 68 65 20 64 69 72 65 63  hin.** the direc
da80: 74 6f 72 79 29 2e 0a 2a 2a 20 54 68 65 20 53 51  tory)..** The SQ
da90: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
daa0: 57 52 49 54 45 20 63 6f 6e 73 74 61 6e 74 20 69  WRITE constant i
dab0: 73 20 63 75 72 72 65 6e 74 6c 79 20 75 73 65 64  s currently used
dac0: 20 6f 6e 6c 79 20 62 79 20 74 68 65 0a 2a 2a 20   only by the.** 
dad0: 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65  [temp_store_dire
dae0: 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 2c 20 74  ctory pragma], t
daf0: 68 6f 75 67 68 20 74 68 69 73 20 63 6f 75 6c 64  hough this could
db00: 20 63 68 61 6e 67 65 20 69 6e 20 61 20 66 75 74   change in a fut
db10: 75 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65 20 6f  ure.** release o
db20: 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 57 69 74  f SQLite..** Wit
db30: 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  h SQLITE_ACCESS_
db40: 52 45 41 44 2c 20 74 68 65 20 78 41 63 63 65 73  READ, the xAcces
db50: 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63  s method.** chec
db60: 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20 66  ks whether the f
db70: 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65 2e  ile is readable.
db80: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43    The SQLITE_ACC
db90: 45 53 53 5f 52 45 41 44 20 63 6f 6e 73 74 61 6e  ESS_READ constan
dba0: 74 20 69 73 0a 2a 2a 20 63 75 72 72 65 6e 74 6c  t is.** currentl
dbb0: 79 20 75 6e 75 73 65 64 2c 20 74 68 6f 75 67 68  y unused, though
dbc0: 20 69 74 20 6d 69 67 68 74 20 62 65 20 75 73 65   it might be use
dbd0: 64 20 69 6e 20 61 20 66 75 74 75 72 65 20 72 65  d in a future re
dbe0: 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69  lease of.** SQLi
dbf0: 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  te..*/.#define S
dc00: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49  QLITE_ACCESS_EXI
dc10: 53 54 53 20 20 20 20 30 0a 23 64 65 66 69 6e 65  STS    0.#define
dc20: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52   SQLITE_ACCESS_R
dc30: 45 41 44 57 52 49 54 45 20 31 20 20 20 2f 2a 20  EADWRITE 1   /* 
dc40: 55 73 65 64 20 62 79 20 50 52 41 47 4d 41 20 74  Used by PRAGMA t
dc50: 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74  emp_store_direct
dc60: 6f 72 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ory */.#define S
dc70: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
dc80: 44 20 20 20 20 20 20 32 20 20 20 2f 2a 20 55 6e  D      2   /* Un
dc90: 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  used */../*.** C
dca0: 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 66  API3REF: Flags f
dcb0: 6f 72 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b 20  or the xShmLock 
dcc0: 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a  VFS method.**.**
dcd0: 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63   These integer c
dce0: 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20  onstants define 
dcf0: 74 68 65 20 76 61 72 69 6f 75 73 20 6c 6f 63 6b  the various lock
dd00: 69 6e 67 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a  ing operations.*
dd10: 2a 20 61 6c 6c 6f 77 65 64 20 62 79 20 74 68 65  * allowed by the
dd20: 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64   xShmLock method
dd30: 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f   of [sqlite3_io_
dd40: 6d 65 74 68 6f 64 73 5d 2e 20 20 54 68 65 0a 2a  methods].  The.*
dd50: 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 72 65 20  * following are 
dd60: 74 68 65 20 6f 6e 6c 79 20 6c 65 67 61 6c 20 63  the only legal c
dd70: 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 6f 66 20 66  ombinations of f
dd80: 6c 61 67 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78  lags to the.** x
dd90: 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 3a 0a  ShmLock method:.
dda0: 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
ddb0: 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c  i>  SQLITE_SHM_L
ddc0: 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d  OCK | SQLITE_SHM
ddd0: 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20  _SHARED.** <li> 
dde0: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b   SQLITE_SHM_LOCK
ddf0: 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58   | SQLITE_SHM_EX
de00: 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20  CLUSIVE.** <li> 
de10: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f   SQLITE_SHM_UNLO
de20: 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f  CK | SQLITE_SHM_
de30: 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20  SHARED.** <li>  
de40: 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43  SQLITE_SHM_UNLOC
de50: 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45  K | SQLITE_SHM_E
de60: 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 2f 75 6c  XCLUSIVE.** </ul
de70: 3e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 75 6e 6c  >.**.** When unl
de80: 6f 63 6b 69 6e 67 2c 20 74 68 65 20 73 61 6d 65  ocking, the same
de90: 20 53 48 41 52 45 44 20 6f 72 20 45 58 43 4c 55   SHARED or EXCLU
dea0: 53 49 56 45 20 66 6c 61 67 20 6d 75 73 74 20 62  SIVE flag must b
deb0: 65 20 73 75 70 70 6c 69 65 64 20 61 73 0a 2a 2a  e supplied as.**
dec0: 20 77 61 73 20 67 69 76 65 6e 20 6e 6f 20 74 68   was given no th
ded0: 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  e corresponding 
dee0: 6c 6f 63 6b 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68  lock.  .**.** Th
def0: 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f  e xShmLock metho
df00: 64 20 63 61 6e 20 74 72 61 6e 73 69 74 69 6f 6e  d can transition
df10: 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65   between unlocke
df20: 64 20 61 6e 64 20 53 48 41 52 45 44 20 6f 72 0a  d and SHARED or.
df30: 2a 2a 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63  ** between unloc
df40: 6b 65 64 20 61 6e 64 20 45 58 43 4c 55 53 49 56  ked and EXCLUSIV
df50: 45 2e 20 20 49 74 20 63 61 6e 6e 6f 74 20 74 72  E.  It cannot tr
df60: 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e  ansition between
df70: 20 53 48 41 52 45 44 0a 2a 2a 20 61 6e 64 20 45   SHARED.** and E
df80: 58 43 4c 55 53 49 56 45 2e 0a 2a 2f 0a 23 64 65  XCLUSIVE..*/.#de
df90: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f  fine SQLITE_SHM_
dfa0: 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 31 0a 23  UNLOCK       1.#
dfb0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48  define SQLITE_SH
dfc0: 4d 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 32  M_LOCK         2
dfd0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
dfe0: 53 48 4d 5f 53 48 41 52 45 44 20 20 20 20 20 20  SHM_SHARED      
dff0: 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   4.#define SQLIT
e000: 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 20  E_SHM_EXCLUSIVE 
e010: 20 20 20 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49     8../*.** CAPI
e020: 33 52 45 46 3a 20 4d 61 78 69 6d 75 6d 20 78 53  3REF: Maximum xS
e030: 68 6d 4c 6f 63 6b 20 69 6e 64 65 78 0a 2a 2a 0a  hmLock index.**.
e040: 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b 20  ** The xShmLock 
e050: 6d 65 74 68 6f 64 20 6f 6e 20 5b 73 71 6c 69 74  method on [sqlit
e060: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6d  e3_io_methods] m
e070: 61 79 20 75 73 65 20 76 61 6c 75 65 73 0a 2a 2a  ay use values.**
e080: 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20 74   between 0 and t
e090: 68 69 73 20 75 70 70 65 72 20 62 6f 75 6e 64 20  his upper bound 
e0a0: 61 73 20 69 74 73 20 22 6f 66 66 73 65 74 22 20  as its "offset" 
e0b0: 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65  argument..** The
e0c0: 20 53 51 4c 69 74 65 20 63 6f 72 65 20 77 69 6c   SQLite core wil
e0d0: 6c 20 6e 65 76 65 72 20 61 74 74 65 6d 70 74 20  l never attempt 
e0e0: 74 6f 20 61 63 71 75 69 72 65 20 6f 72 20 72 65  to acquire or re
e0f0: 6c 65 61 73 65 20 61 0a 2a 2a 20 6c 6f 63 6b 20  lease a.** lock 
e100: 6f 75 74 73 69 64 65 20 6f 66 20 74 68 69 73 20  outside of this 
e110: 72 61 6e 67 65 0a 2a 2f 0a 23 64 65 66 69 6e 65  range.*/.#define
e120: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4e 4c 4f 43   SQLITE_SHM_NLOC
e130: 4b 20 20 20 20 20 20 20 20 38 0a 0a 0a 2f 2a 0a  K        8.../*.
e140: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 69  ** CAPI3REF: Ini
e150: 74 69 61 6c 69 7a 65 20 54 68 65 20 53 51 4c 69  tialize The SQLi
e160: 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a  te Library.**.**
e170: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e   ^The sqlite3_in
e180: 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69  itialize() routi
e190: 6e 65 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74  ne initializes t
e1a0: 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20 6c 69 62  he.** SQLite lib
e1b0: 72 61 72 79 2e 20 20 5e 54 68 65 20 73 71 6c 69  rary.  ^The sqli
e1c0: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 72  te3_shutdown() r
e1d0: 6f 75 74 69 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f  outine.** deallo
e1e0: 63 61 74 65 73 20 61 6e 79 20 72 65 73 6f 75 72  cates any resour
e1f0: 63 65 73 20 74 68 61 74 20 77 65 72 65 20 61 6c  ces that were al
e200: 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69 74  located by sqlit
e210: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e  e3_initialize().
e220: 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
e230: 65 73 20 61 72 65 20 64 65 73 69 67 6e 65 64 20  es are designed 
e240: 74 6f 20 61 69 64 20 69 6e 20 70 72 6f 63 65 73  to aid in proces
e250: 73 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  s initialization
e260: 20 61 6e 64 0a 2a 2a 20 73 68 75 74 64 6f 77 6e   and.** shutdown
e270: 20 6f 6e 20 65 6d 62 65 64 64 65 64 20 73 79 73   on embedded sys
e280: 74 65 6d 73 2e 20 20 57 6f 72 6b 73 74 61 74 69  tems.  Workstati
e290: 6f 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  on applications 
e2a0: 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 69 74 65 20  using.** SQLite 
e2b0: 6e 6f 72 6d 61 6c 6c 79 20 64 6f 20 6e 6f 74 20  normally do not 
e2c0: 6e 65 65 64 20 74 6f 20 69 6e 76 6f 6b 65 20 65  need to invoke e
e2d0: 69 74 68 65 72 20 6f 66 20 74 68 65 73 65 20 72  ither of these r
e2e0: 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 41  outines..**.** A
e2f0: 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
e300: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73  _initialize() is
e310: 20 61 6e 20 22 65 66 66 65 63 74 69 76 65 22 20   an "effective" 
e320: 63 61 6c 6c 20 69 66 20 69 74 20 69 73 0a 2a 2a  call if it is.**
e330: 20 74 68 65 20 66 69 72 73 74 20 74 69 6d 65 20   the first time 
e340: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
e350: 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20  ze() is invoked 
e360: 64 75 72 69 6e 67 20 74 68 65 20 6c 69 66 65 74  during the lifet
e370: 69 6d 65 20 6f 66 0a 2a 2a 20 74 68 65 20 70 72  ime of.** the pr
e380: 6f 63 65 73 73 2c 20 6f 72 20 69 66 20 69 74 20  ocess, or if it 
e390: 69 73 20 74 68 65 20 66 69 72 73 74 20 74 69 6d  is the first tim
e3a0: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
e3b0: 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65  lize() is invoke
e3c0: 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  d.** following a
e3d0: 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
e3e0: 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 5e 28  _shutdown().  ^(
e3f0: 4f 6e 6c 79 20 61 6e 20 65 66 66 65 63 74 69 76  Only an effectiv
e400: 65 20 63 61 6c 6c 0a 2a 2a 20 6f 66 20 73 71 6c  e call.** of sql
e410: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
e420: 29 20 64 6f 65 73 20 61 6e 79 20 69 6e 69 74 69  ) does any initi
e430: 61 6c 69 7a 61 74 69 6f 6e 2e 20 20 41 6c 6c 20  alization.  All 
e440: 6f 74 68 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 61  other calls.** a
e450: 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f  re harmless no-o
e460: 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 63 61  ps.)^.**.** A ca
e470: 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68  ll to sqlite3_sh
e480: 75 74 64 6f 77 6e 28 29 20 69 73 20 61 6e 20 22  utdown() is an "
e490: 65 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20  effective" call 
e4a0: 69 66 20 69 74 20 69 73 20 74 68 65 20 66 69 72  if it is the fir
e4b0: 73 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 73 71  st.** call to sq
e4c0: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
e4d0: 20 73 69 6e 63 65 20 74 68 65 20 6c 61 73 74 20   since the last 
e4e0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
e4f0: 7a 65 28 29 2e 20 20 5e 28 4f 6e 6c 79 0a 2a 2a  ze().  ^(Only.**
e500: 20 61 6e 20 65 66 66 65 63 74 69 76 65 20 63 61   an effective ca
e510: 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68  ll to sqlite3_sh
e520: 75 74 64 6f 77 6e 28 29 20 64 6f 65 73 20 61 6e  utdown() does an
e530: 79 20 64 65 69 6e 69 74 69 61 6c 69 7a 61 74 69  y deinitializati
e540: 6f 6e 2e 0a 2a 2a 20 41 6c 6c 20 6f 74 68 65 72  on..** All other
e550: 20 76 61 6c 69 64 20 63 61 6c 6c 73 20 74 6f 20   valid calls to 
e560: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
e570: 28 29 20 61 72 65 20 68 61 72 6d 6c 65 73 73 20  () are harmless 
e580: 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20  no-ops.)^.**.** 
e590: 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  The sqlite3_init
e5a0: 69 61 6c 69 7a 65 28 29 20 69 6e 74 65 72 66 61  ialize() interfa
e5b0: 63 65 20 69 73 20 74 68 72 65 61 64 73 61 66 65  ce is threadsafe
e5c0: 2c 20 62 75 74 20 73 71 6c 69 74 65 33 5f 73 68  , but sqlite3_sh
e5d0: 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 69 73 20 6e  utdown().** is n
e5e0: 6f 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33  ot.  The sqlite3
e5f0: 5f 73 68 75 74 64 6f 77 6e 28 29 20 69 6e 74 65  _shutdown() inte
e600: 72 66 61 63 65 20 6d 75 73 74 20 6f 6e 6c 79 20  rface must only 
e610: 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61  be called from a
e620: 0a 2a 2a 20 73 69 6e 67 6c 65 20 74 68 72 65 61  .** single threa
e630: 64 2e 20 20 41 6c 6c 20 6f 70 65 6e 20 5b 64 61  d.  All open [da
e640: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
e650: 6e 73 5d 20 6d 75 73 74 20 62 65 20 63 6c 6f 73  ns] must be clos
e660: 65 64 20 61 6e 64 20 61 6c 6c 0a 2a 2a 20 6f 74  ed and all.** ot
e670: 68 65 72 20 53 51 4c 69 74 65 20 72 65 73 6f 75  her SQLite resou
e680: 72 63 65 73 20 6d 75 73 74 20 62 65 20 64 65 61  rces must be dea
e690: 6c 6c 6f 63 61 74 65 64 20 70 72 69 6f 72 20 74  llocated prior t
e6a0: 6f 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 73 71  o invoking.** sq
e6b0: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
e6c0: 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 6f 74  ..**.** Among ot
e6d0: 68 65 72 20 74 68 69 6e 67 73 2c 20 5e 73 71 6c  her things, ^sql
e6e0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
e6f0: 29 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a  ) will invoke.**
e700: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
e710: 28 29 2e 20 20 53 69 6d 69 6c 61 72 6c 79 2c 20  ().  Similarly, 
e720: 5e 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77  ^sqlite3_shutdow
e730: 6e 28 29 0a 2a 2a 20 77 69 6c 6c 20 69 6e 76 6f  n().** will invo
e740: 6b 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  ke sqlite3_os_en
e750: 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  d()..**.** ^The 
e760: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
e770: 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74  ze() routine ret
e780: 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  urns [SQLITE_OK]
e790: 20 6f 6e 20 73 75 63 63 65 73 73 2e 0a 2a 2a 20   on success..** 
e7a0: 5e 49 66 20 66 6f 72 20 73 6f 6d 65 20 72 65 61  ^If for some rea
e7b0: 73 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 69 6e 69  son, sqlite3_ini
e7c0: 74 69 61 6c 69 7a 65 28 29 20 69 73 20 75 6e 61  tialize() is una
e7d0: 62 6c 65 20 74 6f 20 69 6e 69 74 69 61 6c 69 7a  ble to initializ
e7e0: 65 0a 2a 2a 20 74 68 65 20 6c 69 62 72 61 72 79  e.** the library
e7f0: 20 28 70 65 72 68 61 70 73 20 69 74 20 69 73 20   (perhaps it is 
e800: 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61  unable to alloca
e810: 74 65 20 61 20 6e 65 65 64 65 64 20 72 65 73 6f  te a needed reso
e820: 75 72 63 65 20 73 75 63 68 0a 2a 2a 20 61 73 20  urce such.** as 
e830: 61 20 6d 75 74 65 78 29 20 69 74 20 72 65 74 75  a mutex) it retu
e840: 72 6e 73 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f  rns an [error co
e850: 64 65 5d 20 6f 74 68 65 72 20 74 68 61 6e 20 5b  de] other than [
e860: 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a  SQLITE_OK]..**.*
e870: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69  * ^The sqlite3_i
e880: 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74  nitialize() rout
e890: 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 69 6e  ine is called in
e8a0: 74 65 72 6e 61 6c 6c 79 20 62 79 20 6d 61 6e 79  ternally by many
e8b0: 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65   other.** SQLite
e8c0: 20 69 6e 74 65 72 66 61 63 65 73 20 73 6f 20 74   interfaces so t
e8d0: 68 61 74 20 61 6e 20 61 70 70 6c 69 63 61 74 69  hat an applicati
e8e0: 6f 6e 20 75 73 75 61 6c 6c 79 20 64 6f 65 73 20  on usually does 
e8f0: 6e 6f 74 20 6e 65 65 64 20 74 6f 0a 2a 2a 20 69  not need to.** i
e900: 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e  nvoke sqlite3_in
e910: 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63  itialize() direc
e920: 74 6c 79 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c  tly.  For exampl
e930: 65 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  e, [sqlite3_open
e940: 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73 71 6c  ()].** calls sql
e950: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
e960: 29 20 73 6f 20 74 68 65 20 53 51 4c 69 74 65 20  ) so the SQLite 
e970: 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 62 65 20  library will be 
e980: 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a  automatically.**
e990: 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 77 68 65   initialized whe
e9a0: 6e 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  n [sqlite3_open(
e9b0: 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 69 66 20  )] is called if 
e9c0: 69 74 20 68 61 73 20 6e 6f 74 20 62 65 20 69 6e  it has not be in
e9d0: 69 74 69 61 6c 69 7a 65 64 0a 2a 2a 20 61 6c 72  itialized.** alr
e9e0: 65 61 64 79 2e 20 20 5e 48 6f 77 65 76 65 72 2c  eady.  ^However,
e9f0: 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f   if SQLite is co
ea00: 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 20  mpiled with the 
ea10: 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54  [SQLITE_OMIT_AUT
ea20: 4f 49 4e 49 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c  OINIT].** compil
ea30: 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 74  e-time option, t
ea40: 68 65 6e 20 74 68 65 20 61 75 74 6f 6d 61 74 69  hen the automati
ea50: 63 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  c calls to sqlit
ea60: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a  e3_initialize().
ea70: 2a 2a 20 61 72 65 20 6f 6d 69 74 74 65 64 20 61  ** are omitted a
ea80: 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  nd the applicati
ea90: 6f 6e 20 6d 75 73 74 20 63 61 6c 6c 20 73 71 6c  on must call sql
eaa0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
eab0: 29 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 70 72  ) directly.** pr
eac0: 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e 79  ior to using any
ead0: 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e   other SQLite in
eae0: 74 65 72 66 61 63 65 2e 20 20 46 6f 72 20 6d 61  terface.  For ma
eaf0: 78 69 6d 75 6d 20 70 6f 72 74 61 62 69 6c 69 74  ximum portabilit
eb00: 79 2c 0a 2a 2a 20 69 74 20 69 73 20 72 65 63 6f  y,.** it is reco
eb10: 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70 70  mmended that app
eb20: 6c 69 63 61 74 69 6f 6e 73 20 61 6c 77 61 79 73  lications always
eb30: 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f   invoke sqlite3_
eb40: 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20  initialize().** 
eb50: 64 69 72 65 63 74 6c 79 20 70 72 69 6f 72 20 74  directly prior t
eb60: 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65  o using any othe
eb70: 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  r SQLite interfa
eb80: 63 65 2e 20 20 46 75 74 75 72 65 20 72 65 6c 65  ce.  Future rele
eb90: 61 73 65 73 0a 2a 2a 20 6f 66 20 53 51 4c 69 74  ases.** of SQLit
eba0: 65 20 6d 61 79 20 72 65 71 75 69 72 65 20 74 68  e may require th
ebb0: 69 73 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f  is.  In other wo
ebc0: 72 64 73 2c 20 74 68 65 20 62 65 68 61 76 69 6f  rds, the behavio
ebd0: 72 20 65 78 68 69 62 69 74 65 64 0a 2a 2a 20 77  r exhibited.** w
ebe0: 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f  hen SQLite is co
ebf0: 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c  mpiled with [SQL
ec00: 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49  ITE_OMIT_AUTOINI
ec10: 54 5d 20 6d 69 67 68 74 20 62 65 63 6f 6d 65 20  T] might become 
ec20: 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74 20 62  the.** default b
ec30: 65 68 61 76 69 6f 72 20 69 6e 20 73 6f 6d 65 20  ehavior in some 
ec40: 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f  future release o
ec50: 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20  f SQLite..**.** 
ec60: 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69  The sqlite3_os_i
ec70: 6e 69 74 28 29 20 72 6f 75 74 69 6e 65 20 64 6f  nit() routine do
ec80: 65 73 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73  es operating-sys
ec90: 74 65 6d 20 73 70 65 63 69 66 69 63 0a 2a 2a 20  tem specific.** 
eca0: 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f  initialization o
ecb0: 66 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62  f the SQLite lib
ecc0: 72 61 72 79 2e 20 20 54 68 65 20 73 71 6c 69 74  rary.  The sqlit
ecd0: 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 72  e3_os_end().** r
ece0: 6f 75 74 69 6e 65 20 75 6e 64 6f 65 73 20 74 68  outine undoes th
ecf0: 65 20 65 66 66 65 63 74 20 6f 66 20 73 71 6c 69  e effect of sqli
ed00: 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20  te3_os_init().  
ed10: 54 79 70 69 63 61 6c 20 74 61 73 6b 73 0a 2a 2a  Typical tasks.**
ed20: 20 70 65 72 66 6f 72 6d 65 64 20 62 79 20 74 68   performed by th
ed30: 65 73 65 20 72 6f 75 74 69 6e 65 73 20 69 6e 63  ese routines inc
ed40: 6c 75 64 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  lude allocation 
ed50: 6f 72 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a  or deallocation.
ed60: 2a 2a 20 6f 66 20 73 74 61 74 69 63 20 72 65 73  ** of static res
ed70: 6f 75 72 63 65 73 2c 20 69 6e 69 74 69 61 6c 69  ources, initiali
ed80: 7a 61 74 69 6f 6e 20 6f 66 20 67 6c 6f 62 61 6c  zation of global
ed90: 20 76 61 72 69 61 62 6c 65 73 2c 0a 2a 2a 20 73   variables,.** s
eda0: 65 74 74 69 6e 67 20 75 70 20 61 20 64 65 66 61  etting up a defa
edb0: 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  ult [sqlite3_vfs
edc0: 5d 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 73 65 74  ] module, or set
edd0: 74 69 6e 67 20 75 70 0a 2a 2a 20 61 20 64 65 66  ting up.** a def
ede0: 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69  ault configurati
edf0: 6f 6e 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  on using [sqlite
ee00: 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a 0a  3_config()]..**.
ee10: 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
ee20: 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20  on should never 
ee30: 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 73 71  invoke either sq
ee40: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a  lite3_os_init().
ee50: 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73  ** or sqlite3_os
ee60: 5f 65 6e 64 28 29 20 64 69 72 65 63 74 6c 79 2e  _end() directly.
ee70: 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f    The applicatio
ee80: 6e 20 73 68 6f 75 6c 64 20 6f 6e 6c 79 20 69 6e  n should only in
ee90: 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  voke.** sqlite3_
eea0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64  initialize() and
eeb0: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
eec0: 6e 28 29 2e 20 20 54 68 65 20 73 71 6c 69 74 65  n().  The sqlite
eed0: 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 69  3_os_init().** i
eee0: 6e 74 65 72 66 61 63 65 20 69 73 20 63 61 6c 6c  nterface is call
eef0: 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ed automatically
ef00: 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74   by sqlite3_init
ef10: 69 61 6c 69 7a 65 28 29 20 61 6e 64 0a 2a 2a 20  ialize() and.** 
ef20: 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
ef30: 20 69 73 20 63 61 6c 6c 65 64 20 62 79 20 73 71   is called by sq
ef40: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
ef50: 2e 20 20 41 70 70 72 6f 70 72 69 61 74 65 0a 2a  .  Appropriate.*
ef60: 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
ef70: 73 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73  s for sqlite3_os
ef80: 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c 69  _init() and sqli
ef90: 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20  te3_os_end().** 
efa0: 61 72 65 20 62 75 69 6c 74 20 69 6e 74 6f 20 53  are built into S
efb0: 51 4c 69 74 65 20 77 68 65 6e 20 69 74 20 69 73  QLite when it is
efc0: 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20 55 6e   compiled for Un
efd0: 69 78 2c 20 57 69 6e 64 6f 77 73 2c 20 6f 72 20  ix, Windows, or 
efe0: 4f 53 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20 5b 63  OS/2..** When [c
eff0: 75 73 74 6f 6d 20 62 75 69 6c 64 73 20 7c 20 62  ustom builds | b
f000: 75 69 6c 74 20 66 6f 72 20 6f 74 68 65 72 20 70  uilt for other p
f010: 6c 61 74 66 6f 72 6d 73 5d 0a 2a 2a 20 28 75 73  latforms].** (us
f020: 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ing the [SQLITE_
f030: 4f 53 5f 4f 54 48 45 52 3d 31 5d 20 63 6f 6d 70  OS_OTHER=1] comp
f040: 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69  ile-time.** opti
f050: 6f 6e 29 20 74 68 65 20 61 70 70 6c 69 63 61 74  on) the applicat
f060: 69 6f 6e 20 6d 75 73 74 20 73 75 70 70 6c 79 20  ion must supply 
f070: 61 20 73 75 69 74 61 62 6c 65 20 69 6d 70 6c 65  a suitable imple
f080: 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a  mentation for.**
f090: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
f0a0: 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f  () and sqlite3_o
f0b0: 73 5f 65 6e 64 28 29 2e 20 20 41 6e 20 61 70 70  s_end().  An app
f0c0: 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65  lication-supplie
f0d0: 64 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  d.** implementat
f0e0: 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f  ion of sqlite3_o
f0f0: 73 5f 69 6e 69 74 28 29 20 6f 72 20 73 71 6c 69  s_init() or sqli
f100: 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20  te3_os_end().** 
f110: 6d 75 73 74 20 72 65 74 75 72 6e 20 5b 53 51 4c  must return [SQL
f120: 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65  ITE_OK] on succe
f130: 73 73 20 61 6e 64 20 73 6f 6d 65 20 6f 74 68 65  ss and some othe
f140: 72 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 75  r [error code] u
f150: 70 6f 6e 0a 2a 2a 20 66 61 69 6c 75 72 65 2e 0a  pon.** failure..
f160: 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 69  */.int sqlite3_i
f170: 6e 69 74 69 61 6c 69 7a 65 28 76 6f 69 64 29 3b  nitialize(void);
f180: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 68 75  .int sqlite3_shu
f190: 74 64 6f 77 6e 28 76 6f 69 64 29 3b 0a 69 6e 74  tdown(void);.int
f1a0: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
f1b0: 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69  (void);.int sqli
f1c0: 74 65 33 5f 6f 73 5f 65 6e 64 28 76 6f 69 64 29  te3_os_end(void)
f1d0: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
f1e0: 46 3a 20 43 6f 6e 66 69 67 75 72 69 6e 67 20 54  F: Configuring T
f1f0: 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72  he SQLite Librar
f200: 79 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  y.**.** The sqli
f210: 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74  te3_config() int
f220: 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74  erface is used t
f230: 6f 20 6d 61 6b 65 20 67 6c 6f 62 61 6c 20 63 6f  o make global co
f240: 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63  nfiguration.** c
f250: 68 61 6e 67 65 73 20 74 6f 20 53 51 4c 69 74 65  hanges to SQLite
f260: 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 74 75 6e   in order to tun
f270: 65 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20  e SQLite to the 
f280: 73 70 65 63 69 66 69 63 20 6e 65 65 64 73 20 6f  specific needs o
f290: 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61  f.** the applica
f2a0: 74 69 6f 6e 2e 20 20 54 68 65 20 64 65 66 61 75  tion.  The defau
f2b0: 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  lt configuration
f2c0: 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20   is recommended 
f2d0: 66 6f 72 20 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c  for most.** appl
f2e0: 69 63 61 74 69 6f 6e 73 20 61 6e 64 20 73 6f 20  ications and so 
f2f0: 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20  this routine is 
f300: 75 73 75 61 6c 6c 79 20 6e 6f 74 20 6e 65 63 65  usually not nece
f310: 73 73 61 72 79 2e 20 20 49 74 20 69 73 0a 2a 2a  ssary.  It is.**
f320: 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73 75 70   provided to sup
f330: 70 6f 72 74 20 72 61 72 65 20 61 70 70 6c 69 63  port rare applic
f340: 61 74 69 6f 6e 73 20 77 69 74 68 20 75 6e 75 73  ations with unus
f350: 75 61 6c 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a  ual needs..**.**
f360: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e   The sqlite3_con
f370: 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20  fig() interface 
f380: 69 73 20 6e 6f 74 20 74 68 72 65 61 64 73 61 66  is not threadsaf
f390: 65 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 74  e.  The applicat
f3a0: 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 73 75  ion.** must insu
f3b0: 72 65 20 74 68 61 74 20 6e 6f 20 6f 74 68 65 72  re that no other
f3c0: 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
f3d0: 65 73 20 61 72 65 20 69 6e 76 6f 6b 65 64 20 62  es are invoked b
f3e0: 79 20 6f 74 68 65 72 0a 2a 2a 20 74 68 72 65 61  y other.** threa
f3f0: 64 73 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33  ds while sqlite3
f400: 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 72 75 6e  _config() is run
f410: 6e 69 6e 67 2e 20 20 46 75 72 74 68 65 72 6d 6f  ning.  Furthermo
f420: 72 65 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  re, sqlite3_conf
f430: 69 67 28 29 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79  ig().** may only
f440: 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 72 69 6f   be invoked prio
f450: 72 20 74 6f 20 6c 69 62 72 61 72 79 20 69 6e 69  r to library ini
f460: 74 69 61 6c 69 7a 61 74 69 6f 6e 20 75 73 69 6e  tialization usin
f470: 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6e  g.** [sqlite3_in
f480: 69 74 69 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61  itialize()] or a
f490: 66 74 65 72 20 73 68 75 74 64 6f 77 6e 20 62 79  fter shutdown by
f4a0: 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f   [sqlite3_shutdo
f4b0: 77 6e 28 29 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71  wn()]..** ^If sq
f4c0: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69  lite3_config() i
f4d0: 73 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20 5b  s called after [
f4e0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
f4f0: 7a 65 28 29 5d 20 61 6e 64 20 62 65 66 6f 72 65  ze()] and before
f500: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68 75  .** [sqlite3_shu
f510: 74 64 6f 77 6e 28 29 5d 20 74 68 65 6e 20 69 74  tdown()] then it
f520: 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 53 51 4c   will return SQL
f530: 49 54 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a 20 4e  ITE_MISUSE..** N
f540: 6f 74 65 2c 20 68 6f 77 65 76 65 72 2c 20 74 68  ote, however, th
f550: 61 74 20 5e 73 71 6c 69 74 65 33 5f 63 6f 6e 66  at ^sqlite3_conf
f560: 69 67 28 29 20 63 61 6e 20 62 65 20 63 61 6c 6c  ig() can be call
f570: 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68  ed as part of th
f580: 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  e.** implementat
f590: 69 6f 6e 20 6f 66 20 61 6e 20 61 70 70 6c 69 63  ion of an applic
f5a0: 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 5b 73  ation-defined [s
f5b0: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
f5c0: 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72  ]..**.** The fir
f5d0: 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  st argument to s
f5e0: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
f5f0: 69 73 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a  is an integer.**
f600: 20 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20   [configuration 
f610: 6f 70 74 69 6f 6e 5d 20 74 68 61 74 20 64 65 74  option] that det
f620: 65 72 6d 69 6e 65 73 0a 2a 2a 20 77 68 61 74 20  ermines.** what 
f630: 70 72 6f 70 65 72 74 79 20 6f 66 20 53 51 4c 69  property of SQLi
f640: 74 65 20 69 73 20 74 6f 20 62 65 20 63 6f 6e 66  te is to be conf
f650: 69 67 75 72 65 64 2e 20 20 53 75 62 73 65 71 75  igured.  Subsequ
f660: 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a  ent arguments.**
f670: 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20   vary depending 
f680: 6f 6e 20 74 68 65 20 5b 63 6f 6e 66 69 67 75 72  on the [configur
f690: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a  ation option].**
f6a0: 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72   in the first ar
f6b0: 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57  gument..**.** ^W
f6c0: 68 65 6e 20 61 20 63 6f 6e 66 69 67 75 72 61 74  hen a configurat
f6d0: 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 73 65  ion option is se
f6e0: 74 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  t, sqlite3_confi
f6f0: 67 28 29 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  g() returns [SQL
f700: 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66 20  ITE_OK]..** ^If 
f710: 74 68 65 20 6f 70 74 69 6f 6e 20 69 73 20 75 6e  the option is un
f720: 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c 69 74 65 20  known or SQLite 
f730: 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 73 65 74  is unable to set
f740: 20 74 68 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 74   the option.** t
f750: 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65  hen this routine
f760: 20 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a   returns a non-z
f770: 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  ero [error code]
f780: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
f790: 5f 63 6f 6e 66 69 67 28 69 6e 74 2c 20 2e 2e 2e  _config(int, ...
f7a0: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
f7b0: 45 46 3a 20 43 6f 6e 66 69 67 75 72 65 20 64 61  EF: Configure da
f7c0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
f7d0: 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  ns.**.** The sql
f7e0: 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
f7f0: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73   interface is us
f800: 65 64 20 74 6f 20 6d 61 6b 65 20 63 6f 6e 66 69  ed to make confi
f810: 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e  guration.** chan
f820: 67 65 73 20 74 6f 20 61 20 5b 64 61 74 61 62 61  ges to a [databa
f830: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20  se connection]. 
f840: 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 20 69   The interface i
f850: 73 20 73 69 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20  s similar to.** 
f860: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
f870: 29 5d 20 65 78 63 65 70 74 20 74 68 61 74 20 74  )] except that t
f880: 68 65 20 63 68 61 6e 67 65 73 20 61 70 70 6c 79  he changes apply
f890: 20 74 6f 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20   to a single.** 
f8a0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
f8b0: 74 69 6f 6e 5d 20 28 73 70 65 63 69 66 69 65 64  tion] (specified
f8c0: 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72   in the first ar
f8d0: 67 75 6d 65 6e 74 29 2e 0a 2a 2a 0a 2a 2a 20 54  gument)..**.** T
f8e0: 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
f8f0: 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 64 62  nt to sqlite3_db
f900: 5f 63 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e 2e 29  _config(D,V,...)
f910: 20 20 69 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c    is the.** [SQL
f920: 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
f930: 4b 41 53 49 44 45 20 7c 20 63 6f 6e 66 69 67 75  KASIDE | configu
f940: 72 61 74 69 6f 6e 20 76 65 72 62 5d 20 2d 20 61  ration verb] - a
f950: 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20 0a  n integer code .
f960: 2a 2a 20 74 68 61 74 20 69 6e 64 69 63 61 74 65  ** that indicate
f970: 73 20 77 68 61 74 20 61 73 70 65 63 74 20 6f 66  s what aspect of
f980: 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
f990: 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 65  onnection] is be
f9a0: 69 6e 67 20 63 6f 6e 66 69 67 75 72 65 64 2e 0a  ing configured..
f9b0: 2a 2a 20 53 75 62 73 65 71 75 65 6e 74 20 61 72  ** Subsequent ar
f9c0: 67 75 6d 65 6e 74 73 20 76 61 72 79 20 64 65 70  guments vary dep
f9d0: 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 63 6f  ending on the co
f9e0: 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62  nfiguration verb
f9f0: 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74  ..**.** ^Calls t
fa00: 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e  o sqlite3_db_con
fa10: 66 69 67 28 29 20 72 65 74 75 72 6e 20 53 51 4c  fig() return SQL
fa20: 49 54 45 5f 4f 4b 20 69 66 20 61 6e 64 20 6f 6e  ITE_OK if and on
fa30: 6c 79 20 69 66 0a 2a 2a 20 74 68 65 20 63 61 6c  ly if.** the cal
fa40: 6c 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20  l is considered 
fa50: 73 75 63 63 65 73 73 66 75 6c 2e 0a 2a 2f 0a 69  successful..*/.i
fa60: 6e 74 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  nt sqlite3_db_co
fa70: 6e 66 69 67 28 73 71 6c 69 74 65 33 2a 2c 20 69  nfig(sqlite3*, i
fa80: 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a  nt op, ...);../*
fa90: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65  .** CAPI3REF: Me
faa0: 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20  mory Allocation 
fab0: 52 6f 75 74 69 6e 65 73 0a 2a 2a 0a 2a 2a 20 41  Routines.**.** A
fac0: 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
fad0: 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65  is object define
fae0: 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20  s the interface 
faf0: 62 65 74 77 65 65 6e 20 53 51 4c 69 74 65 0a 2a  between SQLite.*
fb00: 2a 20 61 6e 64 20 6c 6f 77 2d 6c 65 76 65 6c 20  * and low-level 
fb10: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
fb20: 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a  n routines..**.*
fb30: 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73  * This object is
fb40: 20 75 73 65 64 20 69 6e 20 6f 6e 6c 79 20 6f 6e   used in only on
fb50: 65 20 70 6c 61 63 65 20 69 6e 20 74 68 65 20 53  e place in the S
fb60: 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e  QLite interface.
fb70: 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f  .** A pointer to
fb80: 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   an instance of 
fb90: 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 74  this object is t
fba0: 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a  he argument to.*
fbb0: 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
fbc0: 67 28 29 5d 20 77 68 65 6e 20 74 68 65 20 63 6f  g()] when the co
fbd0: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
fbe0: 6f 6e 20 69 73 0a 2a 2a 20 5b 53 51 4c 49 54 45  on is.** [SQLITE
fbf0: 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 20  _CONFIG_MALLOC] 
fc00: 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  or [SQLITE_CONFI
fc10: 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 2e 20 20 0a  G_GETMALLOC].  .
fc20: 2a 2a 20 42 79 20 63 72 65 61 74 69 6e 67 20 61  ** By creating a
fc30: 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
fc40: 69 73 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e 64  is object.** and
fc50: 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b   passing it to [
fc60: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28  sqlite3_config](
fc70: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
fc80: 41 4c 4c 4f 43 5d 29 0a 2a 2a 20 64 75 72 69 6e  ALLOC]).** durin
fc90: 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c  g configuration,
fca0: 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20   an application 
fcb0: 63 61 6e 20 73 70 65 63 69 66 79 20 61 6e 20 61  can specify an a
fcc0: 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65  lternative.** me
fcd0: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
fce0: 73 75 62 73 79 73 74 65 6d 20 66 6f 72 20 53 51  subsystem for SQ
fcf0: 4c 69 74 65 20 74 6f 20 75 73 65 20 66 6f 72 20  Lite to use for 
fd00: 61 6c 6c 20 6f 66 20 69 74 73 0a 2a 2a 20 64 79  all of its.** dy
fd10: 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 6e 65 65  namic memory nee
fd20: 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74  ds..**.** Note t
fd30: 68 61 74 20 53 51 4c 69 74 65 20 63 6f 6d 65 73  hat SQLite comes
fd40: 20 77 69 74 68 20 73 65 76 65 72 61 6c 20 5b 62   with several [b
fd50: 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61  uilt-in memory a
fd60: 6c 6c 6f 63 61 74 6f 72 73 5d 0a 2a 2a 20 74 68  llocators].** th
fd70: 61 74 20 61 72 65 20 70 65 72 66 65 63 74 6c 79  at are perfectly
fd80: 20 61 64 65 71 75 61 74 65 20 66 6f 72 20 74 68   adequate for th
fd90: 65 20 6f 76 65 72 77 68 65 6c 6d 69 6e 67 20 6d  e overwhelming m
fda0: 61 6a 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69  ajority of appli
fdb0: 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64 20 74  cations.** and t
fdc0: 68 61 74 20 74 68 69 73 20 6f 62 6a 65 63 74 20  hat this object 
fdd0: 69 73 20 6f 6e 6c 79 20 75 73 65 66 75 6c 20 74  is only useful t
fde0: 6f 20 61 20 74 69 6e 79 20 6d 69 6e 6f 72 69 74  o a tiny minorit
fdf0: 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e  y of application
fe00: 73 0a 2a 2a 20 77 69 74 68 20 73 70 65 63 69 61  s.** with specia
fe10: 6c 69 7a 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c  lized memory all
fe20: 6f 63 61 74 69 6f 6e 20 72 65 71 75 69 72 65 6d  ocation requirem
fe30: 65 6e 74 73 2e 20 20 54 68 69 73 20 6f 62 6a 65  ents.  This obje
fe40: 63 74 20 69 73 0a 2a 2a 20 61 6c 73 6f 20 75 73  ct is.** also us
fe50: 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e  ed during testin
fe60: 67 20 6f 66 20 53 51 4c 69 74 65 20 69 6e 20 6f  g of SQLite in o
fe70: 72 64 65 72 20 74 6f 20 73 70 65 63 69 66 79 20  rder to specify 
fe80: 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a  an alternative.*
fe90: 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  * memory allocat
fea0: 6f 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74 65  or that simulate
feb0: 73 20 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f 66 2d  s memory out-of-
fec0: 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 74 69 6f 6e  memory condition
fed0: 73 20 69 6e 0a 2a 2a 20 6f 72 64 65 72 20 74 6f  s in.** order to
fee0: 20 76 65 72 69 66 79 20 74 68 61 74 20 53 51 4c   verify that SQL
fef0: 69 74 65 20 72 65 63 6f 76 65 72 73 20 67 72 61  ite recovers gra
ff00: 63 65 66 75 6c 6c 79 20 66 72 6f 6d 20 73 75 63  cefully from suc
ff10: 68 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e 73 2e  h.** conditions.
ff20: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 61 6c 6c  .**.** The xMall
ff30: 6f 63 2c 20 78 52 65 61 6c 6c 6f 63 2c 20 61 6e  oc, xRealloc, an
ff40: 64 20 78 46 72 65 65 20 6d 65 74 68 6f 64 73 20  d xFree methods 
ff50: 6d 75 73 74 20 77 6f 72 6b 20 6c 69 6b 65 20 74  must work like t
ff60: 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29 2c 20  he.** malloc(), 
ff70: 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72  realloc() and fr
ff80: 65 65 28 29 20 66 75 6e 63 74 69 6f 6e 73 20 66  ee() functions f
ff90: 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64  rom the standard
ffa0: 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 5e   C library..** ^
ffb0: 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74 65 65  SQLite guarantee
ffc0: 73 20 74 68 61 74 20 74 68 65 20 73 65 63 6f 6e  s that the secon
ffd0: 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a  d argument to.**
ffe0: 20 78 52 65 61 6c 6c 6f 63 20 69 73 20 61 6c 77   xRealloc is alw
fff0: 61 79 73 20 61 20 76 61 6c 75 65 20 72 65 74 75  ays a value retu
10000 72 6e 65 64 20 62 79 20 61 20 70 72 69 6f 72 20  rned by a prior 
10010 63 61 6c 6c 20 74 6f 20 78 52 6f 75 6e 64 75 70  call to xRoundup
10020 2e 0a 2a 2a 0a 2a 2a 20 78 53 69 7a 65 20 73 68  ..**.** xSize sh
10030 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20  ould return the 
10040 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f  allocated size o
10050 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  f a memory alloc
10060 61 74 69 6f 6e 0a 2a 2a 20 70 72 65 76 69 6f 75  ation.** previou
10070 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  sly obtained fro
10080 6d 20 78 4d 61 6c 6c 6f 63 20 6f 72 20 78 52 65  m xMalloc or xRe
10090 61 6c 6c 6f 63 2e 20 20 54 68 65 20 61 6c 6c 6f  alloc.  The allo
100a0 63 61 74 65 64 20 73 69 7a 65 0a 2a 2a 20 69 73  cated size.** is
100b0 20 61 6c 77 61 79 73 20 61 74 20 6c 65 61 73 74   always at least
100c0 20 61 73 20 62 69 67 20 61 73 20 74 68 65 20 72   as big as the r
100d0 65 71 75 65 73 74 65 64 20 73 69 7a 65 20 62 75  equested size bu
100e0 74 20 6d 61 79 20 62 65 20 6c 61 72 67 65 72 2e  t may be larger.
100f0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 6f 75 6e  .**.** The xRoun
10100 64 75 70 20 6d 65 74 68 6f 64 20 72 65 74 75 72  dup method retur
10110 6e 73 20 77 68 61 74 20 77 6f 75 6c 64 20 62 65  ns what would be
10120 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73   the allocated s
10130 69 7a 65 20 6f 66 0a 2a 2a 20 61 20 6d 65 6d 6f  ize of.** a memo
10140 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 67 69  ry allocation gi
10150 76 65 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72  ven a particular
10160 20 72 65 71 75 65 73 74 65 64 20 73 69 7a 65 2e   requested size.
10170 20 20 4d 6f 73 74 20 6d 65 6d 6f 72 79 0a 2a 2a    Most memory.**
10180 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e   allocators roun
10190 64 20 75 70 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  d up memory allo
101a0 63 61 74 69 6f 6e 73 20 61 74 20 6c 65 61 73 74  cations at least
101b0 20 74 6f 20 74 68 65 20 6e 65 78 74 20 6d 75 6c   to the next mul
101c0 74 69 70 6c 65 0a 2a 2a 20 6f 66 20 38 2e 20 20  tiple.** of 8.  
101d0 53 6f 6d 65 20 61 6c 6c 6f 63 61 74 6f 72 73 20  Some allocators 
101e0 72 6f 75 6e 64 20 75 70 20 74 6f 20 61 20 6c 61  round up to a la
101f0 72 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 72  rger multiple or
10200 20 74 6f 20 61 20 70 6f 77 65 72 20 6f 66 20 32   to a power of 2
10210 2e 0a 2a 2a 20 45 76 65 72 79 20 6d 65 6d 6f 72  ..** Every memor
10220 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71  y allocation req
10230 75 65 73 74 20 63 6f 6d 69 6e 67 20 69 6e 20 74  uest coming in t
10240 68 72 6f 75 67 68 20 5b 73 71 6c 69 74 65 33 5f  hrough [sqlite3_
10250 6d 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6f 72 20  malloc()].** or 
10260 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
10270 28 29 5d 20 66 69 72 73 74 20 63 61 6c 6c 73 20  ()] first calls 
10280 78 52 6f 75 6e 64 75 70 2e 20 20 49 66 20 78 52  xRoundup.  If xR
10290 6f 75 6e 64 75 70 20 72 65 74 75 72 6e 73 20 30  oundup returns 0
102a0 2c 20 0a 2a 2a 20 74 68 61 74 20 63 61 75 73 65  , .** that cause
102b0 73 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  s the correspond
102c0 69 6e 67 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ing memory alloc
102d0 61 74 69 6f 6e 20 74 6f 20 66 61 69 6c 2e 0a 2a  ation to fail..*
102e0 2a 0a 2a 2a 20 54 68 65 20 78 49 6e 69 74 20 6d  *.** The xInit m
102f0 65 74 68 6f 64 20 69 6e 69 74 69 61 6c 69 7a 65  ethod initialize
10300 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  s the memory all
10310 6f 63 61 74 6f 72 2e 20 20 28 46 6f 72 20 65 78  ocator.  (For ex
10320 61 6d 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69 67  ample,.** it mig
10330 68 74 20 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20  ht allocate any 
10340 72 65 71 75 69 72 65 20 6d 75 74 65 78 65 73 20  require mutexes 
10350 6f 72 20 69 6e 69 74 69 61 6c 69 7a 65 20 69 6e  or initialize in
10360 74 65 72 6e 61 6c 20 64 61 74 61 0a 2a 2a 20 73  ternal data.** s
10370 74 72 75 63 74 75 72 65 73 2e 20 20 54 68 65 20  tructures.  The 
10380 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64  xShutdown method
10390 20 69 73 20 69 6e 76 6f 6b 65 64 20 28 69 6e 64   is invoked (ind
103a0 69 72 65 63 74 6c 79 29 20 62 79 0a 2a 2a 20 5b  irectly) by.** [
103b0 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
103c0 28 29 5d 20 61 6e 64 20 73 68 6f 75 6c 64 20 64  ()] and should d
103d0 65 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65  eallocate any re
103e0 73 6f 75 72 63 65 73 20 61 63 71 75 69 72 65 64  sources acquired
103f0 0a 2a 2a 20 62 79 20 78 49 6e 69 74 2e 20 20 54  .** by xInit.  T
10400 68 65 20 70 41 70 70 44 61 74 61 20 70 6f 69 6e  he pAppData poin
10410 74 65 72 20 69 73 20 75 73 65 64 20 61 73 20 74  ter is used as t
10420 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65  he only paramete
10430 72 20 74 6f 0a 2a 2a 20 78 49 6e 69 74 20 61 6e  r to.** xInit an
10440 64 20 78 53 68 75 74 64 6f 77 6e 2e 0a 2a 2a 0a  d xShutdown..**.
10450 2a 2a 20 53 51 4c 69 74 65 20 68 6f 6c 64 73 20  ** SQLite holds 
10460 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45  the [SQLITE_MUTE
10470 58 5f 53 54 41 54 49 43 5f 4d 41 53 54 45 52 5d  X_STATIC_MASTER]
10480 20 6d 75 74 65 78 20 77 68 65 6e 20 69 74 20 69   mutex when it i
10490 6e 76 6f 6b 65 73 0a 2a 2a 20 74 68 65 20 78 49  nvokes.** the xI
104a0 6e 69 74 20 6d 65 74 68 6f 64 2c 20 73 6f 20 74  nit method, so t
104b0 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20  he xInit method 
104c0 6e 65 65 64 20 6e 6f 74 20 62 65 20 74 68 72 65  need not be thre
104d0 61 64 73 61 66 65 2e 20 20 54 68 65 0a 2a 2a 20  adsafe.  The.** 
104e0 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64  xShutdown method
104f0 20 69 73 20 6f 6e 6c 79 20 63 61 6c 6c 65 64 20   is only called 
10500 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 73 68  from [sqlite3_sh
10510 75 74 64 6f 77 6e 28 29 5d 20 73 6f 20 69 74 20  utdown()] so it 
10520 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 6e 65 65 64  does.** not need
10530 20 74 6f 20 62 65 20 74 68 72 65 61 64 73 61 66   to be threadsaf
10540 65 20 65 69 74 68 65 72 2e 20 20 46 6f 72 20 61  e either.  For a
10550 6c 6c 20 6f 74 68 65 72 20 6d 65 74 68 6f 64 73  ll other methods
10560 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 68 6f 6c 64  , SQLite.** hold
10570 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55  s the [SQLITE_MU
10580 54 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d 5d 20  TEX_STATIC_MEM] 
10590 6d 75 74 65 78 20 61 73 20 6c 6f 6e 67 20 61 73  mutex as long as
105a0 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
105b0 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53  CONFIG_MEMSTATUS
105c0 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  ] configuration 
105d0 6f 70 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64  option is turned
105e0 20 6f 6e 20 28 77 68 69 63 68 0a 2a 2a 20 69 74   on (which.** it
105f0 20 69 73 20 62 79 20 64 65 66 61 75 6c 74 29 20   is by default) 
10600 61 6e 64 20 73 6f 20 74 68 65 20 6d 65 74 68 6f  and so the metho
10610 64 73 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63  ds are automatic
10620 61 6c 6c 79 20 73 65 72 69 61 6c 69 7a 65 64 2e  ally serialized.
10630 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 69 66 20  .** However, if 
10640 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
10650 45 4d 53 54 41 54 55 53 5d 20 69 73 20 64 69 73  EMSTATUS] is dis
10660 61 62 6c 65 64 2c 20 74 68 65 6e 20 74 68 65 20  abled, then the 
10670 6f 74 68 65 72 0a 2a 2a 20 6d 65 74 68 6f 64 73  other.** methods
10680 20 6d 75 73 74 20 62 65 20 74 68 72 65 61 64 73   must be threads
10690 61 66 65 20 6f 72 20 65 6c 73 65 20 6d 61 6b 65  afe or else make
106a0 20 74 68 65 69 72 20 6f 77 6e 20 61 72 72 61 6e   their own arran
106b0 67 65 6d 65 6e 74 73 20 66 6f 72 0a 2a 2a 20 73  gements for.** s
106c0 65 72 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a  erialization..**
106d0 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  .** SQLite will 
106e0 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 78 49 6e  never invoke xIn
106f0 69 74 28 29 20 6d 6f 72 65 20 74 68 61 6e 20 6f  it() more than o
10700 6e 63 65 20 77 69 74 68 6f 75 74 20 61 6e 20 69  nce without an i
10710 6e 74 65 72 76 65 6e 69 6e 67 0a 2a 2a 20 63 61  ntervening.** ca
10720 6c 6c 20 74 6f 20 78 53 68 75 74 64 6f 77 6e 28  ll to xShutdown(
10730 29 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  )..*/.typedef st
10740 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d  ruct sqlite3_mem
10750 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33  _methods sqlite3
10760 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 3b 0a 73 74  _mem_methods;.st
10770 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d  ruct sqlite3_mem
10780 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 76 6f 69  _methods {.  voi
10790 64 20 2a 28 2a 78 4d 61 6c 6c 6f 63 29 28 69 6e  d *(*xMalloc)(in
107a0 74 29 3b 20 20 20 20 20 20 20 20 20 2f 2a 20 4d  t);         /* M
107b0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
107c0 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76   function */.  v
107d0 6f 69 64 20 28 2a 78 46 72 65 65 29 28 76 6f 69  oid (*xFree)(voi
107e0 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a  d*);          /*
107f0 20 46 72 65 65 20 61 20 70 72 69 6f 72 20 61 6c   Free a prior al
10800 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f  location */.  vo
10810 69 64 20 2a 28 2a 78 52 65 61 6c 6c 6f 63 29 28  id *(*xRealloc)(
10820 76 6f 69 64 2a 2c 69 6e 74 29 3b 20 20 2f 2a 20  void*,int);  /* 
10830 52 65 73 69 7a 65 20 61 6e 20 61 6c 6c 6f 63 61  Resize an alloca
10840 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  tion */.  int (*
10850 78 53 69 7a 65 29 28 76 6f 69 64 2a 29 3b 20 20  xSize)(void*);  
10860 20 20 20 20 20 20 20 20 20 2f 2a 20 52 65 74 75           /* Retu
10870 72 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61  rn the size of a
10880 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a  n allocation */.
10890 20 20 69 6e 74 20 28 2a 78 52 6f 75 6e 64 75 70    int (*xRoundup
108a0 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20  )(int);         
108b0 20 2f 2a 20 52 6f 75 6e 64 20 75 70 20 72 65 71   /* Round up req
108c0 75 65 73 74 20 73 69 7a 65 20 74 6f 20 61 6c 6c  uest size to all
108d0 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 2a 2f 0a  ocation size */.
108e0 20 20 69 6e 74 20 28 2a 78 49 6e 69 74 29 28 76    int (*xInit)(v
108f0 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20  oid*);          
10900 20 2f 2a 20 49 6e 69 74 69 61 6c 69 7a 65 20 74   /* Initialize t
10910 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
10920 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a  tor */.  void (*
10930 78 53 68 75 74 64 6f 77 6e 29 28 76 6f 69 64 2a  xShutdown)(void*
10940 29 3b 20 20 20 20 20 20 2f 2a 20 44 65 69 6e 69  );      /* Deini
10950 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f  tialize the memo
10960 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a  ry allocator */.
10970 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61    void *pAppData
10980 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ;               
10990 20 2f 2a 20 41 72 67 75 6d 65 6e 74 20 74 6f 20   /* Argument to 
109a0 78 49 6e 69 74 28 29 20 61 6e 64 20 78 53 68 75  xInit() and xShu
109b0 74 64 6f 77 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f  tdown() */.};../
109c0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
109d0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74  onfiguration Opt
109e0 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ions.** KEYWORDS
109f0 3a 20 7b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  : {configuration
10a00 20 6f 70 74 69 6f 6e 7d 0a 2a 2a 0a 2a 2a 20 54   option}.**.** T
10a10 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61  hese constants a
10a20 72 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65  re the available
10a30 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75   integer configu
10a40 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74  ration options t
10a50 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61  hat.** can be pa
10a60 73 73 65 64 20 61 73 20 74 68 65 20 66 69 72 73  ssed as the firs
10a70 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
10a80 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  e [sqlite3_confi
10a90 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a  g()] interface..
10aa0 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67  **.** New config
10ab0 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20  uration options 
10ac0 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20  may be added in 
10ad0 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
10ae0 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78  of SQLite..** Ex
10af0 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61  isting configura
10b00 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67  tion options mig
10b10 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75  ht be discontinu
10b20 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e  ed.  Application
10b30 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63  s.** should chec
10b40 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64  k the return cod
10b50 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  e from [sqlite3_
10b60 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b  config()] to mak
10b70 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74  e sure that.** t
10b80 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20  he call worked. 
10b90 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   The [sqlite3_co
10ba0 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63  nfig()] interfac
10bb0 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a  e will return a.
10bc0 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72  ** non-zero [err
10bd0 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69  or code] if a di
10be0 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e  scontinued or un
10bf0 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67  supported config
10c00 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a  uration option.*
10c10 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a  * is invoked..**
10c20 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51  .** <dl>.** [[SQ
10c30 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
10c40 4c 45 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53  LETHREAD]] <dt>S
10c50 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e  QLITE_CONFIG_SIN
10c60 47 4c 45 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a  GLETHREAD</dt>.*
10c70 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20  * <dd>There are 
10c80 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  no arguments to 
10c90 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54  this option.  ^T
10ca0 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20  his option sets 
10cb0 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e  the.** [threadin
10cc0 67 20 6d 6f 64 65 5d 20 74 6f 20 53 69 6e 67 6c  g mode] to Singl
10cd0 65 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74  e-thread.  In ot
10ce0 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69  her words, it di
10cf0 73 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75  sables.** all mu
10d00 74 65 78 69 6e 67 20 61 6e 64 20 70 75 74 73 20  texing and puts 
10d10 53 51 4c 69 74 65 20 69 6e 74 6f 20 61 20 6d 6f  SQLite into a mo
10d20 64 65 20 77 68 65 72 65 20 69 74 20 63 61 6e 20  de where it can 
10d30 6f 6e 6c 79 20 62 65 20 75 73 65 64 0a 2a 2a 20  only be used.** 
10d40 62 79 20 61 20 73 69 6e 67 6c 65 20 74 68 72 65  by a single thre
10d50 61 64 2e 20 20 20 5e 49 66 20 53 51 4c 69 74 65  ad.   ^If SQLite
10d60 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
10d70 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  h.** the [SQLITE
10d80 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51  _THREADSAFE | SQ
10d90 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
10da0 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  0] compile-time 
10db0 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69  option then.** i
10dc0 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c  t is not possibl
10dd0 65 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20  e to change the 
10de0 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
10df0 20 66 72 6f 6d 20 69 74 73 20 64 65 66 61 75 6c   from its defaul
10e00 74 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 53 69  t.** value of Si
10e10 6e 67 6c 65 2d 74 68 72 65 61 64 20 61 6e 64 20  ngle-thread and 
10e20 73 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  so [sqlite3_conf
10e30 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72  ig()] will retur
10e40 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52  n .** [SQLITE_ER
10e50 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77  ROR] if called w
10e60 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43  ith the SQLITE_C
10e70 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
10e80 41 44 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74  AD.** configurat
10e90 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e  ion option.</dd>
10ea0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
10eb0 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45  CONFIG_MULTITHRE
10ec0 41 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  AD]] <dt>SQLITE_
10ed0 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45  CONFIG_MULTITHRE
10ee0 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  AD</dt>.** <dd>T
10ef0 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75  here are no argu
10f00 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70  ments to this op
10f10 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74  tion.  ^This opt
10f20 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20  ion sets the.** 
10f30 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
10f40 20 74 6f 20 4d 75 6c 74 69 2d 74 68 72 65 61 64   to Multi-thread
10f50 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  .  In other word
10f60 73 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a  s, it disables.*
10f70 2a 20 6d 75 74 65 78 69 6e 67 20 6f 6e 20 5b 64  * mutexing on [d
10f80 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
10f90 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65  on] and [prepare
10fa0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a  d statement] obj
10fb0 65 63 74 73 2e 0a 2a 2a 20 54 68 65 20 61 70 70  ects..** The app
10fc0 6c 69 63 61 74 69 6f 6e 20 69 73 20 72 65 73 70  lication is resp
10fd0 6f 6e 73 69 62 6c 65 20 66 6f 72 20 73 65 72 69  onsible for seri
10fe0 61 6c 69 7a 69 6e 67 20 61 63 63 65 73 73 20 74  alizing access t
10ff0 6f 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  o.** [database c
11000 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20  onnections] and 
11010 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
11020 65 6e 74 73 5d 2e 20 20 42 75 74 20 6f 74 68 65  ents].  But othe
11030 72 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72 65  r mutexes.** are
11040 20 65 6e 61 62 6c 65 64 20 73 6f 20 74 68 61 74   enabled so that
11050 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20   SQLite will be 
11060 73 61 66 65 20 74 6f 20 75 73 65 20 69 6e 20 61  safe to use in a
11070 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64 0a   multi-threaded.
11080 2a 2a 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 20 61  ** environment a
11090 73 20 6c 6f 6e 67 20 61 73 20 6e 6f 20 74 77 6f  s long as no two
110a0 20 74 68 72 65 61 64 73 20 61 74 74 65 6d 70 74   threads attempt
110b0 20 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65   to use the same
110c0 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
110d0 6e 6e 65 63 74 69 6f 6e 5d 20 61 74 20 74 68 65  nnection] at the
110e0 20 73 61 6d 65 20 74 69 6d 65 2e 20 20 5e 49 66   same time.  ^If
110f0 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
11100 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20  led with.** the 
11110 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
11120 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45  FE | SQLITE_THRE
11130 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c  ADSAFE=0] compil
11140 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68  e-time option th
11150 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20  en.** it is not 
11160 70 6f 73 73 69 62 6c 65 20 74 6f 20 73 65 74 20  possible to set 
11170 74 68 65 20 4d 75 6c 74 69 2d 74 68 72 65 61 64  the Multi-thread
11180 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
11190 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  ] and.** [sqlite
111a0 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c  3_config()] will
111b0 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
111c0 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64  ERROR] if called
111d0 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c   with the.** SQL
111e0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49  ITE_CONFIG_MULTI
111f0 54 48 52 45 41 44 20 63 6f 6e 66 69 67 75 72 61  THREAD configura
11200 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64  tion option.</dd
11210 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
11220 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a  _CONFIG_SERIALIZ
11230 45 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  ED]] <dt>SQLITE_
11240 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45  CONFIG_SERIALIZE
11250 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  D</dt>.** <dd>Th
11260 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d  ere are no argum
11270 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74  ents to this opt
11280 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69  ion.  ^This opti
11290 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b  on sets the.** [
112a0 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
112b0 74 6f 20 53 65 72 69 61 6c 69 7a 65 64 2e 20 49  to Serialized. I
112c0 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74  n other words, t
112d0 68 69 73 20 6f 70 74 69 6f 6e 20 65 6e 61 62 6c  his option enabl
112e0 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 65  es.** all mutexe
112f0 73 20 69 6e 63 6c 75 64 69 6e 67 20 74 68 65 20  s including the 
11300 72 65 63 75 72 73 69 76 65 0a 2a 2a 20 6d 75 74  recursive.** mut
11310 65 78 65 73 20 6f 6e 20 5b 64 61 74 61 62 61 73  exes on [databas
11320 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e  e connection] an
11330 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  d [prepared stat
11340 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a  ement] objects..
11350 2a 2a 20 49 6e 20 74 68 69 73 20 6d 6f 64 65 20  ** In this mode 
11360 28 77 68 69 63 68 20 69 73 20 74 68 65 20 64 65  (which is the de
11370 66 61 75 6c 74 20 77 68 65 6e 20 53 51 4c 69 74  fault when SQLit
11380 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
11390 74 68 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48  th.** [SQLITE_TH
113a0 52 45 41 44 53 41 46 45 3d 31 5d 29 20 74 68 65  READSAFE=1]) the
113b0 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20   SQLite library 
113c0 77 69 6c 6c 20 69 74 73 65 6c 66 20 73 65 72 69  will itself seri
113d0 61 6c 69 7a 65 20 61 63 63 65 73 73 0a 2a 2a 20  alize access.** 
113e0 74 6f 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  to [database con
113f0 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70  nections] and [p
11400 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
11410 74 73 5d 20 73 6f 20 74 68 61 74 20 74 68 65 0a  ts] so that the.
11420 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69  ** application i
11430 73 20 66 72 65 65 20 74 6f 20 75 73 65 20 74 68  s free to use th
11440 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65  e same [database
11450 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72 20   connection] or 
11460 74 68 65 0a 2a 2a 20 73 61 6d 65 20 5b 70 72 65  the.** same [pre
11470 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
11480 20 69 6e 20 64 69 66 66 65 72 65 6e 74 20 74 68   in different th
11490 72 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d  reads at the sam
114a0 65 20 74 69 6d 65 2e 0a 2a 2a 20 5e 49 66 20 53  e time..** ^If S
114b0 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
114c0 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53  d with.** the [S
114d0 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
114e0 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44   | SQLITE_THREAD
114f0 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d  SAFE=0] compile-
11500 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e  time option then
11510 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f  .** it is not po
11520 73 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68  ssible to set th
11530 65 20 53 65 72 69 61 6c 69 7a 65 64 20 5b 74 68  e Serialized [th
11540 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e  reading mode] an
11550 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d.** [sqlite3_co
11560 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74  nfig()] will ret
11570 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  urn [SQLITE_ERRO
11580 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74  R] if called wit
11590 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f  h the.** SQLITE_
115a0 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45  CONFIG_SERIALIZE
115b0 44 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  D configuration 
115c0 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a  option.</dd>.**.
115d0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
115e0 49 47 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e  IG_MALLOC]] <dt>
115f0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41  SQLITE_CONFIG_MA
11600 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  LLOC</dt>.** <dd
11610 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20  > ^(This option 
11620 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
11630 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
11640 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
11650 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20  .** instance of 
11660 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  the [sqlite3_mem
11670 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
11680 75 72 65 2e 20 20 54 68 65 20 61 72 67 75 6d 65  ure.  The argume
11690 6e 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20  nt specifies.** 
116a0 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d  alternative low-
116b0 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c  level memory all
116c0 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  ocation routines
116d0 20 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70   to be used in p
116e0 6c 61 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6d  lace of.** the m
116f0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
11700 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20   routines built 
11710 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 5e  into SQLite.)^ ^
11720 53 51 4c 69 74 65 20 6d 61 6b 65 73 0a 2a 2a 20  SQLite makes.** 
11730 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20  its own private 
11740 63 6f 70 79 20 6f 66 20 74 68 65 20 63 6f 6e 74  copy of the cont
11750 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  ent of the [sqli
11760 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d  te3_mem_methods]
11770 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 62 65   structure.** be
11780 66 6f 72 65 20 74 68 65 20 5b 73 71 6c 69 74 65  fore the [sqlite
11790 33 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6c 6c  3_config()] call
117a0 20 72 65 74 75 72 6e 73 2e 3c 2f 64 64 3e 0a 2a   returns.</dd>.*
117b0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
117c0 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 5d  NFIG_GETMALLOC]]
117d0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
117e0 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74  IG_GETMALLOC</dt
117f0 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73  >.** <dd> ^(This
11800 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
11810 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
11820 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74  which is a point
11830 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74  er to an.** inst
11840 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c  ance of the [sql
11850 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
11860 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68  ] structure.  Th
11870 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  e [sqlite3_mem_m
11880 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63  ethods].** struc
11890 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77  ture is filled w
118a0 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c  ith the currentl
118b0 79 20 64 65 66 69 6e 65 64 20 6d 65 6d 6f 72 79  y defined memory
118c0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74   allocation rout
118d0 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20  ines.)^.** This 
118e0 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73  option can be us
118f0 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74  ed to overload t
11900 68 65 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72  he default memor
11910 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  y allocation.** 
11920 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61 20  routines with a 
11930 77 72 61 70 70 65 72 20 74 68 61 74 20 73 69 6d  wrapper that sim
11940 75 6c 61 74 69 6f 6e 73 20 6d 65 6d 6f 72 79 20  ulations memory 
11950 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75  allocation failu
11960 72 65 20 6f 72 0a 2a 2a 20 74 72 61 63 6b 73 20  re or.** tracks 
11970 6d 65 6d 6f 72 79 20 75 73 61 67 65 2c 20 66 6f  memory usage, fo
11980 72 20 65 78 61 6d 70 6c 65 2e 20 3c 2f 64 64 3e  r example. </dd>
11990 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
119a0 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53  CONFIG_MEMSTATUS
119b0 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
119c0 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 3c 2f  NFIG_MEMSTATUS</
119d0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69  dt>.** <dd> ^Thi
119e0 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 73  s option takes s
119f0 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f  ingle argument o
11a00 66 20 74 79 70 65 20 69 6e 74 2c 20 69 6e 74 65  f type int, inte
11a10 72 70 72 65 74 65 64 20 61 73 20 61 20 0a 2a 2a  rpreted as a .**
11a20 20 62 6f 6f 6c 65 61 6e 2c 20 77 68 69 63 68 20   boolean, which 
11a30 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62  enables or disab
11a40 6c 65 73 20 74 68 65 20 63 6f 6c 6c 65 63 74 69  les the collecti
11a50 6f 6e 20 6f 66 20 6d 65 6d 6f 72 79 20 61 6c 6c  on of memory all
11a60 6f 63 61 74 69 6f 6e 20 0a 2a 2a 20 73 74 61 74  ocation .** stat
11a70 69 73 74 69 63 73 2e 20 5e 28 57 68 65 6e 20 6d  istics. ^(When m
11a80 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
11a90 20 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20   statistics are 
11aa0 64 69 73 61 62 6c 65 64 2c 20 74 68 65 20 0a 2a  disabled, the .*
11ab0 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 69  * following SQLi
11ac0 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 62 65  te interfaces be
11ad0 63 6f 6d 65 20 6e 6f 6e 2d 6f 70 65 72 61 74 69  come non-operati
11ae0 6f 6e 61 6c 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a  onal:.**   <ul>.
11af0 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74  **   <li> [sqlit
11b00 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29  e3_memory_used()
11b10 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c  ].**   <li> [sql
11b20 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
11b30 77 61 74 65 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c  water()].**   <l
11b40 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74  i> [sqlite3_soft
11b50 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28 29 5d  _heap_limit64()]
11b60 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69  .**   <li> [sqli
11b70 74 65 33 5f 73 74 61 74 75 73 28 29 5d 0a 2a 2a  te3_status()].**
11b80 20 20 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d     </ul>)^.** ^M
11b90 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
11ba0 20 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20   statistics are 
11bb0 65 6e 61 62 6c 65 64 20 62 79 20 64 65 66 61 75  enabled by defau
11bc0 6c 74 20 75 6e 6c 65 73 73 20 53 51 4c 69 74 65  lt unless SQLite
11bd0 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20   is.** compiled 
11be0 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 44 45 46  with [SQLITE_DEF
11bf0 41 55 4c 54 5f 4d 45 4d 53 54 41 54 55 53 5d 3d  AULT_MEMSTATUS]=
11c00 30 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20  0 in which case 
11c10 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61  memory.** alloca
11c20 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20  tion statistics 
11c30 61 72 65 20 64 69 73 61 62 6c 65 64 20 62 79 20  are disabled by 
11c40 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 3c 2f 64 64  default..** </dd
11c50 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
11c60 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d  _CONFIG_SCRATCH]
11c70 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
11c80 46 49 47 5f 53 43 52 41 54 43 48 3c 2f 64 74 3e  FIG_SCRATCH</dt>
11c90 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f  .** <dd> ^This o
11ca0 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20  ption specifies 
11cb0 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20  a static memory 
11cc0 62 75 66 66 65 72 20 74 68 61 74 20 53 51 4c 69  buffer that SQLi
11cd0 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72 0a 2a  te can use for.*
11ce0 2a 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79  * scratch memory
11cf0 2e 20 20 54 68 65 72 65 20 61 72 65 20 74 68 72  .  There are thr
11d00 65 65 20 61 72 67 75 6d 65 6e 74 73 3a 20 20 41  ee arguments:  A
11d10 20 70 6f 69 6e 74 65 72 20 61 6e 20 38 2d 62 79   pointer an 8-by
11d20 74 65 0a 2a 2a 20 61 6c 69 67 6e 65 64 20 6d 65  te.** aligned me
11d30 6d 6f 72 79 20 62 75 66 66 65 72 20 66 72 6f 6d  mory buffer from
11d40 20 77 68 69 63 68 20 74 68 65 20 73 63 72 61 74   which the scrat
11d50 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 77  ch allocations w
11d60 69 6c 6c 20 62 65 0a 2a 2a 20 64 72 61 77 6e 2c  ill be.** drawn,
11d70 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63   the size of eac
11d80 68 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61  h scratch alloca
11d90 74 69 6f 6e 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e  tion (sz),.** an
11da0 64 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d the maximum nu
11db0 6d 62 65 72 20 6f 66 20 73 63 72 61 74 63 68 20  mber of scratch 
11dc0 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 28 4e 29 2e  allocations (N).
11dd0 20 20 54 68 65 20 73 7a 0a 2a 2a 20 61 72 67 75    The sz.** argu
11de0 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20 6d  ment must be a m
11df0 75 6c 74 69 70 6c 65 20 6f 66 20 31 36 2e 0a 2a  ultiple of 16..*
11e00 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  * The first argu
11e10 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20 70  ment must be a p
11e20 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 38 2d 62  ointer to an 8-b
11e30 79 74 65 20 61 6c 69 67 6e 65 64 20 62 75 66 66  yte aligned buff
11e40 65 72 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73  er.** of at leas
11e50 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20  t sz*N bytes of 
11e60 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69  memory..** ^SQLi
11e70 74 65 20 77 69 6c 6c 20 75 73 65 20 6e 6f 20 6d  te will use no m
11e80 6f 72 65 20 74 68 61 6e 20 74 77 6f 20 73 63 72  ore than two scr
11e90 61 74 63 68 20 62 75 66 66 65 72 73 20 70 65 72  atch buffers per
11ea0 20 74 68 72 65 61 64 2e 20 20 53 6f 0a 2a 2a 20   thread.  So.** 
11eb0 4e 20 73 68 6f 75 6c 64 20 62 65 20 73 65 74 20  N should be set 
11ec0 74 6f 20 74 77 69 63 65 20 74 68 65 20 65 78 70  to twice the exp
11ed0 65 63 74 65 64 20 6d 61 78 69 6d 75 6d 20 6e 75  ected maximum nu
11ee0 6d 62 65 72 20 6f 66 20 74 68 72 65 61 64 73 2e  mber of threads.
11ef0 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c  .** ^SQLite will
11f00 20 6e 65 76 65 72 20 72 65 71 75 69 72 65 20 61   never require a
11f10 20 73 63 72 61 74 63 68 20 62 75 66 66 65 72 20   scratch buffer 
11f20 74 68 61 74 20 69 73 20 6d 6f 72 65 20 74 68 61  that is more tha
11f30 6e 20 36 0a 2a 2a 20 74 69 6d 65 73 20 74 68 65  n 6.** times the
11f40 20 64 61 74 61 62 61 73 65 20 70 61 67 65 20 73   database page s
11f50 69 7a 65 2e 20 5e 49 66 20 53 51 4c 69 74 65 20  ize. ^If SQLite 
11f60 6e 65 65 64 73 20 6e 65 65 64 73 20 61 64 64 69  needs needs addi
11f70 74 69 6f 6e 61 6c 0a 2a 2a 20 73 63 72 61 74 63  tional.** scratc
11f80 68 20 6d 65 6d 6f 72 79 20 62 65 79 6f 6e 64 20  h memory beyond 
11f90 77 68 61 74 20 69 73 20 70 72 6f 76 69 64 65 64  what is provided
11fa0 20 62 79 20 74 68 69 73 20 63 6f 6e 66 69 67 75   by this configu
11fb0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2c 20 74  ration option, t
11fc0 68 65 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  hen .** [sqlite3
11fd0 5f 6d 61 6c 6c 6f 63 28 29 5d 20 77 69 6c 6c 20  _malloc()] will 
11fe0 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69  be used to obtai
11ff0 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 6e 65 65  n the memory nee
12000 64 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ded.</dd>.**.** 
12010 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
12020 50 41 47 45 43 41 43 48 45 5d 5d 20 3c 64 74 3e  PAGECACHE]] <dt>
12030 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41  SQLITE_CONFIG_PA
12040 47 45 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20  GECACHE</dt>.** 
12050 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f  <dd> ^This optio
12060 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74  n specifies a st
12070 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66  atic memory buff
12080 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 63  er that SQLite c
12090 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68  an use for.** th
120a0 65 20 64 61 74 61 62 61 73 65 20 70 61 67 65 20  e database page 
120b0 63 61 63 68 65 20 77 69 74 68 20 74 68 65 20 64  cache with the d
120c0 65 66 61 75 6c 74 20 70 61 67 65 20 63 61 63 68  efault page cach
120d0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
120e0 2e 20 20 0a 2a 2a 20 54 68 69 73 20 63 6f 6e 66  .  .** This conf
120f0 69 67 75 72 61 74 69 6f 6e 20 73 68 6f 75 6c 64  iguration should
12100 20 6e 6f 74 20 62 65 20 75 73 65 64 20 69 66 20   not be used if 
12110 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  an application-d
12120 65 66 69 6e 65 20 70 61 67 65 0a 2a 2a 20 63 61  efine page.** ca
12130 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  che implementati
12140 6f 6e 20 69 73 20 6c 6f 61 64 65 64 20 75 73 69  on is loaded usi
12150 6e 67 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f  ng the SQLITE_CO
12160 4e 46 49 47 5f 50 43 41 43 48 45 32 20 6f 70 74  NFIG_PCACHE2 opt
12170 69 6f 6e 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72  ion..** There ar
12180 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74  e three argument
12190 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e  s to this option
121a0 3a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 38  : A pointer to 8
121b0 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 0a 2a 2a  -byte aligned.**
121c0 20 6d 65 6d 6f 72 79 2c 20 74 68 65 20 73 69 7a   memory, the siz
121d0 65 20 6f 66 20 65 61 63 68 20 70 61 67 65 20 62  e of each page b
121e0 75 66 66 65 72 20 28 73 7a 29 2c 20 61 6e 64 20  uffer (sz), and 
121f0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 70 61  the number of pa
12200 67 65 73 20 28 4e 29 2e 0a 2a 2a 20 54 68 65 20  ges (N)..** The 
12210 73 7a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75  sz argument shou
12220 6c 64 20 62 65 20 74 68 65 20 73 69 7a 65 20 6f  ld be the size o
12230 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 64 61  f the largest da
12240 74 61 62 61 73 65 20 70 61 67 65 0a 2a 2a 20 28  tabase page.** (
12250 61 20 70 6f 77 65 72 20 6f 66 20 74 77 6f 20 62  a power of two b
12260 65 74 77 65 65 6e 20 35 31 32 20 61 6e 64 20 33  etween 512 and 3
12270 32 37 36 38 29 20 70 6c 75 73 20 61 20 6c 69 74  2768) plus a lit
12280 74 6c 65 20 65 78 74 72 61 20 66 6f 72 20 65 61  tle extra for ea
12290 63 68 0a 2a 2a 20 70 61 67 65 20 68 65 61 64 65  ch.** page heade
122a0 72 2e 20 20 5e 54 68 65 20 70 61 67 65 20 68 65  r.  ^The page he
122b0 61 64 65 72 20 73 69 7a 65 20 69 73 20 32 30 20  ader size is 20 
122c0 74 6f 20 34 30 20 62 79 74 65 73 20 64 65 70 65  to 40 bytes depe
122d0 6e 64 69 6e 67 20 6f 6e 0a 2a 2a 20 74 68 65 20  nding on.** the 
122e0 68 6f 73 74 20 61 72 63 68 69 74 65 63 74 75 72  host architectur
122f0 65 2e 20 20 5e 49 74 20 69 73 20 68 61 72 6d 6c  e.  ^It is harml
12300 65 73 73 2c 20 61 70 61 72 74 20 66 72 6f 6d 20  ess, apart from 
12310 74 68 65 20 77 61 73 74 65 64 20 6d 65 6d 6f 72  the wasted memor
12320 79 2c 0a 2a 2a 20 74 6f 20 6d 61 6b 65 20 73 7a  y,.** to make sz
12330 20 61 20 6c 69 74 74 6c 65 20 74 6f 6f 20 6c 61   a little too la
12340 72 67 65 2e 20 20 54 68 65 20 66 69 72 73 74 0a  rge.  The first.
12350 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75  ** argument shou
12360 6c 64 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 61  ld point to an a
12370 6c 6c 6f 63 61 74 69 6f 6e 20 6f 66 20 61 74 20  llocation of at 
12380 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73  least sz*N bytes
12390 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e   of memory..** ^
123a0 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20  SQLite will use 
123b0 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 76 69  the memory provi
123c0 64 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74  ded by the first
123d0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 61 74   argument to sat
123e0 69 73 66 79 20 69 74 73 0a 2a 2a 20 6d 65 6d 6f  isfy its.** memo
123f0 72 79 20 6e 65 65 64 73 20 66 6f 72 20 74 68 65  ry needs for the
12400 20 66 69 72 73 74 20 4e 20 70 61 67 65 73 20 74   first N pages t
12410 68 61 74 20 69 74 20 61 64 64 73 20 74 6f 20 63  hat it adds to c
12420 61 63 68 65 2e 20 20 5e 49 66 20 61 64 64 69 74  ache.  ^If addit
12430 69 6f 6e 61 6c 0a 2a 2a 20 70 61 67 65 20 63 61  ional.** page ca
12440 63 68 65 20 6d 65 6d 6f 72 79 20 69 73 20 6e 65  che memory is ne
12450 65 64 65 64 20 62 65 79 6f 6e 64 20 77 68 61 74  eded beyond what
12460 20 69 73 20 70 72 6f 76 69 64 65 64 20 62 79 20   is provided by 
12470 74 68 69 73 20 6f 70 74 69 6f 6e 2c 20 74 68 65  this option, the
12480 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 67 6f 65 73  n.** SQLite goes
12490 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c   to [sqlite3_mal
124a0 6c 6f 63 28 29 5d 20 66 6f 72 20 74 68 65 20 61  loc()] for the a
124b0 64 64 69 74 69 6f 6e 61 6c 20 73 74 6f 72 61 67  dditional storag
124c0 65 20 73 70 61 63 65 2e 0a 2a 2a 20 54 68 65 20  e space..** The 
124d0 70 6f 69 6e 74 65 72 20 69 6e 20 74 68 65 20 66  pointer in the f
124e0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75  irst argument mu
124f0 73 74 0a 2a 2a 20 62 65 20 61 6c 69 67 6e 65 64  st.** be aligned
12500 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 62 6f   to an 8-byte bo
12510 75 6e 64 61 72 79 20 6f 72 20 73 75 62 73 65 71  undary or subseq
12520 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20 6f 66  uent behavior of
12530 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20   SQLite.** will 
12540 62 65 20 75 6e 64 65 66 69 6e 65 64 2e 3c 2f 64  be undefined.</d
12550 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
12560 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 5d 5d 20  E_CONFIG_HEAP]] 
12570 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
12580 47 5f 48 45 41 50 3c 2f 64 74 3e 0a 2a 2a 20 3c  G_HEAP</dt>.** <
12590 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  dd> ^This option
125a0 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61   specifies a sta
125b0 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65  tic memory buffe
125c0 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69  r that SQLite wi
125d0 6c 6c 20 75 73 65 0a 2a 2a 20 66 6f 72 20 61 6c  ll use.** for al
125e0 6c 20 6f 66 20 69 74 73 20 64 79 6e 61 6d 69 63  l of its dynamic
125f0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
12600 6f 6e 20 6e 65 65 64 73 20 62 65 79 6f 6e 64 20  on needs beyond 
12610 74 68 6f 73 65 20 70 72 6f 76 69 64 65 64 0a 2a  those provided.*
12620 2a 20 66 6f 72 20 62 79 20 5b 53 51 4c 49 54 45  * for by [SQLITE
12630 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d  _CONFIG_SCRATCH]
12640 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 43 4f 4e   and [SQLITE_CON
12650 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a  FIG_PAGECACHE]..
12660 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74 68 72  ** There are thr
12670 65 65 20 61 72 67 75 6d 65 6e 74 73 3a 20 41 6e  ee arguments: An
12680 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20   8-byte aligned 
12690 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d  pointer to the m
126a0 65 6d 6f 72 79 2c 0a 2a 2a 20 74 68 65 20 6e 75  emory,.** the nu
126b0 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
126c0 20 74 68 65 20 6d 65 6d 6f 72 79 20 62 75 66 66   the memory buff
126d0 65 72 2c 20 61 6e 64 20 74 68 65 20 6d 69 6e 69  er, and the mini
126e0 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  mum allocation s
126f0 69 7a 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ize..** ^If the 
12700 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74  first pointer (t
12710 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65  he memory pointe
12720 72 29 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e  r) is NULL, then
12730 20 53 51 4c 69 74 65 20 72 65 76 65 72 74 73 0a   SQLite reverts.
12740 2a 2a 20 74 6f 20 75 73 69 6e 67 20 69 74 73 20  ** to using its 
12750 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61  default memory a
12760 6c 6c 6f 63 61 74 6f 72 20 28 74 68 65 20 73 79  llocator (the sy
12770 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 69 6d  stem malloc() im
12780 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 29 2c 0a 2a  plementation),.*
12790 2a 20 75 6e 64 6f 69 6e 67 20 61 6e 79 20 70 72  * undoing any pr
127a0 69 6f 72 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f  ior invocation o
127b0 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  f [SQLITE_CONFIG
127c0 5f 4d 41 4c 4c 4f 43 5d 2e 20 20 5e 49 66 20 74  _MALLOC].  ^If t
127d0 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 70 6f 69  he.** memory poi
127e0 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  nter is not NULL
127f0 20 61 6e 64 20 65 69 74 68 65 72 20 5b 53 51 4c   and either [SQL
12800 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59  ITE_ENABLE_MEMSY
12810 53 33 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54  S3] or.** [SQLIT
12820 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 35  E_ENABLE_MEMSYS5
12830 5d 20 61 72 65 20 64 65 66 69 6e 65 64 2c 20 74  ] are defined, t
12840 68 65 6e 20 74 68 65 20 61 6c 74 65 72 6e 61 74  hen the alternat
12850 69 76 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c  ive memory.** al
12860 6c 6f 63 61 74 6f 72 20 69 73 20 65 6e 67 61 67  locator is engag
12870 65 64 20 74 6f 20 68 61 6e 64 6c 65 20 61 6c 6c  ed to handle all
12880 20 6f 66 20 53 51 4c 69 74 65 73 20 6d 65 6d 6f   of SQLites memo
12890 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65  ry allocation ne
128a0 65 64 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73  eds..** The firs
128b0 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d  t pointer (the m
128c0 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 6d  emory pointer) m
128d0 75 73 74 20 62 65 20 61 6c 69 67 6e 65 64 20 74  ust be aligned t
128e0 6f 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 62  o an 8-byte.** b
128f0 6f 75 6e 64 61 72 79 20 6f 72 20 73 75 62 73 65  oundary or subse
12900 71 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20 6f  quent behavior o
12910 66 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65  f SQLite will be
12920 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54   undefined..** T
12930 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63  he minimum alloc
12940 61 74 69 6f 6e 20 73 69 7a 65 20 69 73 20 63 61  ation size is ca
12950 70 70 65 64 20 61 74 20 32 2a 2a 31 32 2e 20 52  pped at 2**12. R
12960 65 61 73 6f 6e 61 62 6c 65 20 76 61 6c 75 65 73  easonable values
12970 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6d 69 6e 69  .** for the mini
12980 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  mum allocation s
12990 69 7a 65 20 61 72 65 20 32 2a 2a 35 20 74 68 72  ize are 2**5 thr
129a0 6f 75 67 68 20 32 2a 2a 38 2e 3c 2f 64 64 3e 0a  ough 2**8.</dd>.
129b0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
129c0 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 5d 20 3c 64  ONFIG_MUTEX]] <d
129d0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
129e0 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  MUTEX</dt>.** <d
129f0 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e  d> ^(This option
12a00 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
12a10 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
12a20 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
12a30 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66  n.** instance of
12a40 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75   the [sqlite3_mu
12a50 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72  tex_methods] str
12a60 75 63 74 75 72 65 2e 20 20 54 68 65 20 61 72 67  ucture.  The arg
12a70 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73 0a  ument specifies.
12a80 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c  ** alternative l
12a90 6f 77 2d 6c 65 76 65 6c 20 6d 75 74 65 78 20 72  ow-level mutex r
12aa0 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73  outines to be us
12ab0 65 64 20 69 6e 20 70 6c 61 63 65 0a 2a 2a 20 74  ed in place.** t
12ac0 68 65 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65  he mutex routine
12ad0 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c  s built into SQL
12ae0 69 74 65 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20  ite.)^  ^SQLite 
12af0 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20  makes a copy of 
12b00 74 68 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 6f  the.** content o
12b10 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
12b20 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74  utex_methods] st
12b30 72 75 63 74 75 72 65 20 62 65 66 6f 72 65 20 74  ructure before t
12b40 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73  he call to.** [s
12b50 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
12b60 20 72 65 74 75 72 6e 73 2e 20 5e 49 66 20 53 51   returns. ^If SQ
12b70 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
12b80 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51   with.** the [SQ
12b90 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20  LITE_THREADSAFE 
12ba0 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53  | SQLITE_THREADS
12bb0 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74  AFE=0] compile-t
12bc0 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a  ime option then.
12bd0 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75  ** the entire mu
12be0 74 65 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d  texing subsystem
12bf0 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d   is omitted from
12c00 20 74 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68   the build and h
12c10 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a  ence calls to.**
12c20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
12c30 28 29 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c  ()] with the SQL
12c40 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
12c50 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
12c60 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65  ption will.** re
12c70 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52  turn [SQLITE_ERR
12c80 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  OR].</dd>.**.** 
12c90 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
12ca0 47 45 54 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53  GETMUTEX]] <dt>S
12cb0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
12cc0 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  MUTEX</dt>.** <d
12cd0 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e  d> ^(This option
12ce0 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
12cf0 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
12d00 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
12d10 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66  n.** instance of
12d20 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75   the [sqlite3_mu
12d30 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72  tex_methods] str
12d40 75 63 74 75 72 65 2e 20 20 54 68 65 0a 2a 2a 20  ucture.  The.** 
12d50 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d  [sqlite3_mutex_m
12d60 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63  ethods].** struc
12d70 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77  ture is filled w
12d80 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c  ith the currentl
12d90 79 20 64 65 66 69 6e 65 64 20 6d 75 74 65 78 20  y defined mutex 
12da0 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54  routines.)^.** T
12db0 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62  his option can b
12dc0 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f  e used to overlo
12dd0 61 64 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d  ad the default m
12de0 75 74 65 78 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a  utex allocation.
12df0 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68  ** routines with
12e00 20 61 20 77 72 61 70 70 65 72 20 75 73 65 64 20   a wrapper used 
12e10 74 6f 20 74 72 61 63 6b 20 6d 75 74 65 78 20 75  to track mutex u
12e20 73 61 67 65 20 66 6f 72 20 70 65 72 66 6f 72 6d  sage for perform
12e30 61 6e 63 65 0a 2a 2a 20 70 72 6f 66 69 6c 69 6e  ance.** profilin
12e40 67 20 6f 72 20 74 65 73 74 69 6e 67 2c 20 66 6f  g or testing, fo
12e50 72 20 65 78 61 6d 70 6c 65 2e 20 20 20 5e 49 66  r example.   ^If
12e60 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
12e70 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20  led with.** the 
12e80 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
12e90 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45  FE | SQLITE_THRE
12ea0 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c  ADSAFE=0] compil
12eb0 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68  e-time option th
12ec0 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72 65  en.** the entire
12ed0 20 6d 75 74 65 78 69 6e 67 20 73 75 62 73 79 73   mutexing subsys
12ee0 74 65 6d 20 69 73 20 6f 6d 69 74 74 65 64 20 66  tem is omitted f
12ef0 72 6f 6d 20 74 68 65 20 62 75 69 6c 64 20 61 6e  rom the build an
12f00 64 20 68 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f  d hence calls to
12f10 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
12f20 66 69 67 28 29 5d 20 77 69 74 68 20 74 68 65 20  fig()] with the 
12f30 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
12f40 54 4d 55 54 45 58 20 63 6f 6e 66 69 67 75 72 61  TMUTEX configura
12f50 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c  tion option will
12f60 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  .** return [SQLI
12f70 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a  TE_ERROR].</dd>.
12f80 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
12f90 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d  ONFIG_LOOKASIDE]
12fa0 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
12fb0 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64  FIG_LOOKASIDE</d
12fc0 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69  t>.** <dd> ^(Thi
12fd0 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74  s option takes t
12fe0 77 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61  wo arguments tha
12ff0 74 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20  t determine the 
13000 64 65 66 61 75 6c 74 0a 2a 2a 20 6d 65 6d 6f 72  default.** memor
13010 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f 72  y allocation for
13020 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d   the lookaside m
13030 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20  emory allocator 
13040 6f 6e 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61  on each.** [data
13050 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
13060 2e 20 20 54 68 65 20 66 69 72 73 74 20 61 72 67  .  The first arg
13070 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20  ument is the.** 
13080 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f  size of each loo
13090 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 73 6c  kaside buffer sl
130a0 6f 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e  ot and the secon
130b0 64 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20  d is the number 
130c0 6f 66 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f  of.** slots allo
130d0 63 61 74 65 64 20 74 6f 20 65 61 63 68 20 64 61  cated to each da
130e0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
130f0 6e 2e 29 5e 20 20 5e 28 54 68 69 73 20 6f 70 74  n.)^  ^(This opt
13100 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20  ion sets the.** 
13110 3c 69 3e 64 65 66 61 75 6c 74 3c 2f 69 3e 20 6c  <i>default</i> l
13120 6f 6f 6b 61 73 69 64 65 20 73 69 7a 65 2e 20 54  ookaside size. T
13130 68 65 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e  he [SQLITE_DBCON
13140 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 0a 2a  FIG_LOOKASIDE].*
13150 2a 20 76 65 72 62 20 74 6f 20 5b 73 71 6c 69 74  * verb to [sqlit
13160 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20  e3_db_config()] 
13170 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 63  can be used to c
13180 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73  hange the lookas
13190 69 64 65 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61  ide.** configura
131a0 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75  tion on individu
131b0 61 6c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e 29  al connections.)
131c0 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  ^ </dd>.**.** [[
131d0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
131e0 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53 51 4c 49  ACHE2]] <dt>SQLI
131f0 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
13200 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  2</dt>.** <dd> ^
13210 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b  (This option tak
13220 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
13230 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20  ment which is a 
13240 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 61 6e  pointer to.** an
13250 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65   [sqlite3_pcache
13260 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63  _methods2] objec
13270 74 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20  t.  This object 
13280 73 70 65 63 69 66 69 65 73 20 74 68 65 20 69 6e  specifies the in
13290 74 65 72 66 61 63 65 0a 2a 2a 20 74 6f 20 61 20  terface.** to a 
132a0 63 75 73 74 6f 6d 20 70 61 67 65 20 63 61 63 68  custom page cach
132b0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
132c0 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61 6b  .)^  ^SQLite mak
132d0 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  es a copy of the
132e0 0a 2a 2a 20 6f 62 6a 65 63 74 20 61 6e 64 20 75  .** object and u
132f0 73 65 73 20 69 74 20 66 6f 72 20 70 61 67 65 20  ses it for page 
13300 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  cache memory all
13310 6f 63 61 74 69 6f 6e 73 2e 3c 2f 64 64 3e 0a 2a  ocations.</dd>.*
13320 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
13330 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 5d  NFIG_GETPCACHE2]
13340 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
13350 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 3c 2f  FIG_GETPCACHE2</
13360 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68  dt>.** <dd> ^(Th
13370 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
13380 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
13390 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69  t which is a poi
133a0 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73  nter to an.** [s
133b0 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65  qlite3_pcache_me
133c0 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e 20  thods2] object. 
133d0 20 53 51 4c 69 74 65 20 63 6f 70 69 65 73 20 6f   SQLite copies o
133e0 66 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a  f the current.**
133f0 20 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c   page cache impl
13400 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 74 6f 20  ementation into 
13410 74 68 61 74 20 6f 62 6a 65 63 74 2e 29 5e 20 3c  that object.)^ <
13420 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
13430 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 5d 5d  ITE_CONFIG_LOG]]
13440 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
13450 49 47 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a 2a 20 3c  IG_LOG</dt>.** <
13460 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 5f  dd> ^The SQLITE_
13470 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f  CONFIG_LOG optio
13480 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75  n takes two argu
13490 6d 65 6e 74 73 3a 20 61 20 70 6f 69 6e 74 65 72  ments: a pointer
134a0 20 74 6f 20 61 0a 2a 2a 20 66 75 6e 63 74 69 6f   to a.** functio
134b0 6e 20 77 69 74 68 20 61 20 63 61 6c 6c 20 73 69  n with a call si
134c0 67 6e 61 74 75 72 65 20 6f 66 20 76 6f 69 64 28  gnature of void(
134d0 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e  *)(void*,int,con
134e0 73 74 20 63 68 61 72 2a 29 2c 20 0a 2a 2a 20 61  st char*), .** a
134f0 6e 64 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  nd a pointer to 
13500 76 6f 69 64 2e 20 5e 49 66 20 74 68 65 20 66 75  void. ^If the fu
13510 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69  nction pointer i
13520 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 69 74 20 69  s not NULL, it i
13530 73 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20 62 79 20  s.** invoked by 
13540 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20  [sqlite3_log()] 
13550 74 6f 20 70 72 6f 63 65 73 73 20 65 61 63 68 20  to process each 
13560 6c 6f 67 67 69 6e 67 20 65 76 65 6e 74 2e 20 20  logging event.  
13570 5e 49 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74  ^If the.** funct
13580 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 4e  ion pointer is N
13590 55 4c 4c 2c 20 74 68 65 20 5b 73 71 6c 69 74 65  ULL, the [sqlite
135a0 33 5f 6c 6f 67 28 29 5d 20 69 6e 74 65 72 66 61  3_log()] interfa
135b0 63 65 20 62 65 63 6f 6d 65 73 20 61 20 6e 6f 2d  ce becomes a no-
135c0 6f 70 2e 0a 2a 2a 20 5e 54 68 65 20 76 6f 69 64  op..** ^The void
135d0 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 69 73   pointer that is
135e0 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
135f0 6d 65 6e 74 20 74 6f 20 53 51 4c 49 54 45 5f 43  ment to SQLITE_C
13600 4f 4e 46 49 47 5f 4c 4f 47 20 69 73 0a 2a 2a 20  ONFIG_LOG is.** 
13610 70 61 73 73 65 64 20 74 68 72 6f 75 67 68 20 61  passed through a
13620 73 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61  s the first para
13630 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 70 70  meter to the app
13640 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
13650 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74   logger.** funct
13660 69 6f 6e 20 77 68 65 6e 65 76 65 72 20 74 68 61  ion whenever tha
13670 74 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 69 6e  t function is in
13680 76 6f 6b 65 64 2e 20 20 5e 54 68 65 20 73 65 63  voked.  ^The sec
13690 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ond parameter to
136a0 0a 2a 2a 20 74 68 65 20 6c 6f 67 67 65 72 20 66  .** the logger f
136b0 75 6e 63 74 69 6f 6e 20 69 73 20 61 20 63 6f 70  unction is a cop
136c0 79 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 70  y of the first p
136d0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
136e0 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a  corresponding.**
136f0 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d   [sqlite3_log()]
13700 20 63 61 6c 6c 20 61 6e 64 20 69 73 20 69 6e 74   call and is int
13710 65 6e 64 65 64 20 74 6f 20 62 65 20 61 20 5b 72  ended to be a [r
13720 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20 61  esult code] or a
13730 6e 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72  n.** [extended r
13740 65 73 75 6c 74 20 63 6f 64 65 5d 2e 20 20 5e 54  esult code].  ^T
13750 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
13760 65 72 20 70 61 73 73 65 64 20 74 6f 20 74 68 65  er passed to the
13770 20 6c 6f 67 67 65 72 20 69 73 0a 2a 2a 20 6c 6f   logger is.** lo
13780 67 20 6d 65 73 73 61 67 65 20 61 66 74 65 72 20  g message after 
13790 66 6f 72 6d 61 74 74 69 6e 67 20 76 69 61 20 5b  formatting via [
137a0 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
137b0 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69  ()]..** The SQLi
137c0 74 65 20 6c 6f 67 67 69 6e 67 20 69 6e 74 65 72  te logging inter
137d0 66 61 63 65 20 69 73 20 6e 6f 74 20 72 65 65 6e  face is not reen
137e0 74 72 61 6e 74 3b 20 74 68 65 20 6c 6f 67 67 65  trant; the logge
137f0 72 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73 75  r function.** su
13800 70 70 6c 69 65 64 20 62 79 20 74 68 65 20 61 70  pplied by the ap
13810 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e  plication must n
13820 6f 74 20 69 6e 76 6f 6b 65 20 61 6e 79 20 53 51  ot invoke any SQ
13830 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 0a  Lite interface..
13840 2a 2a 20 49 6e 20 61 20 6d 75 6c 74 69 2d 74 68  ** In a multi-th
13850 72 65 61 64 65 64 20 61 70 70 6c 69 63 61 74 69  readed applicati
13860 6f 6e 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74  on, the applicat
13870 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67  ion-defined logg
13880 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d  er.** function m
13890 75 73 74 20 62 65 20 74 68 72 65 61 64 73 61 66  ust be threadsaf
138a0 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  e. </dd>.**.** [
138b0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55  [SQLITE_CONFIG_U
138c0 52 49 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  RI]] <dt>SQLITE_
138d0 43 4f 4e 46 49 47 5f 55 52 49 0a 2a 2a 20 3c 64  CONFIG_URI.** <d
138e0 64 3e 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 74  d> This option t
138f0 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
13900 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69  gument of type i
13910 6e 74 2e 20 49 66 20 6e 6f 6e 2d 7a 65 72 6f 2c  nt. If non-zero,
13920 20 74 68 65 6e 0a 2a 2a 20 55 52 49 20 68 61 6e   then.** URI han
13930 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c  dling is globall
13940 79 20 65 6e 61 62 6c 65 64 2e 20 49 66 20 74 68  y enabled. If th
13950 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 7a  e parameter is z
13960 65 72 6f 2c 20 74 68 65 6e 20 55 52 49 20 68 61  ero, then URI ha
13970 6e 64 6c 69 6e 67 0a 2a 2a 20 69 73 20 67 6c 6f  ndling.** is glo
13980 62 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 2e 20  bally disabled. 
13990 49 66 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20  If URI handling 
139a0 69 73 20 67 6c 6f 62 61 6c 6c 79 20 65 6e 61 62  is globally enab
139b0 6c 65 64 2c 20 61 6c 6c 20 66 69 6c 65 6e 61 6d  led, all filenam
139c0 65 73 0a 2a 2a 20 70 61 73 73 65 64 20 74 6f 20  es.** passed to 
139d0 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
139e0 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  , [sqlite3_open_
139f0 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  v2()], [sqlite3_
13a00 6f 70 65 6e 31 36 28 29 5d 20 6f 72 0a 2a 2a 20  open16()] or.** 
13a10 73 70 65 63 69 66 69 65 64 20 61 73 20 70 61 72  specified as par
13a20 74 20 6f 66 20 5b 41 54 54 41 43 48 5d 20 63 6f  t of [ATTACH] co
13a30 6d 6d 61 6e 64 73 20 61 72 65 20 69 6e 74 65 72  mmands are inter
13a40 70 72 65 74 65 64 20 61 73 20 55 52 49 73 2c 20  preted as URIs, 
13a50 72 65 67 61 72 64 6c 65 73 73 0a 2a 2a 20 6f 66  regardless.** of
13a60 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
13a70 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  the [SQLITE_OPEN
13a80 5f 55 52 49 5d 20 66 6c 61 67 20 69 73 20 73 65  _URI] flag is se
13a90 74 20 77 68 65 6e 20 74 68 65 20 64 61 74 61 62  t when the datab
13aa0 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  ase.** connectio
13ab0 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20 49 66 20  n is opened. If 
13ac0 69 74 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64  it is globally d
13ad0 69 73 61 62 6c 65 64 2c 20 66 69 6c 65 6e 61 6d  isabled, filenam
13ae0 65 73 20 61 72 65 0a 2a 2a 20 6f 6e 6c 79 20 69  es are.** only i
13af0 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55 52  nterpreted as UR
13b00 49 73 20 69 66 20 74 68 65 20 53 51 4c 49 54 45  Is if the SQLITE
13b10 5f 4f 50 45 4e 5f 55 52 49 20 66 6c 61 67 20 69  _OPEN_URI flag i
13b20 73 20 73 65 74 20 77 68 65 6e 20 74 68 65 0a 2a  s set when the.*
13b30 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
13b40 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e  ction is opened.
13b50 20 42 79 20 64 65 66 61 75 6c 74 2c 20 55 52 49   By default, URI
13b60 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f   handling is glo
13b70 62 61 6c 6c 79 0a 2a 2a 20 64 69 73 61 62 6c 65  bally.** disable
13b80 64 2e 20 54 68 65 20 64 65 66 61 75 6c 74 20 76  d. The default v
13b90 61 6c 75 65 20 6d 61 79 20 62 65 20 63 68 61 6e  alue may be chan
13ba0 67 65 64 20 62 79 20 63 6f 6d 70 69 6c 69 6e 67  ged by compiling
13bb0 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51   with the.** [SQ
13bc0 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d 20 73 79  LITE_USE_URI] sy
13bd0 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e 0a 2a 2a  mbol defined..**
13be0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
13bf0 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44  FIG_COVERING_IND
13c00 45 58 5f 53 43 41 4e 5d 5d 20 3c 64 74 3e 53 51  EX_SCAN]] <dt>SQ
13c10 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45  LITE_CONFIG_COVE
13c20 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 0a  RING_INDEX_SCAN.
13c30 2a 2a 20 3c 64 64 3e 20 54 68 69 73 20 6f 70 74  ** <dd> This opt
13c40 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
13c50 6c 65 20 69 6e 74 65 67 65 72 20 61 72 67 75 6d  le integer argum
13c60 65 6e 74 20 77 68 69 63 68 20 69 73 20 69 6e 74  ent which is int
13c70 65 72 70 72 65 74 65 64 20 61 73 0a 2a 2a 20 61  erpreted as.** a
13c80 20 62 6f 6f 6c 65 61 6e 20 69 6e 20 6f 72 64 65   boolean in orde
13c90 72 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64  r to enable or d
13ca0 69 73 61 62 6c 65 20 74 68 65 20 75 73 65 20 6f  isable the use o
13cb0 66 20 63 6f 76 65 72 69 6e 67 20 69 6e 64 69 63  f covering indic
13cc0 65 73 20 66 6f 72 0a 2a 2a 20 66 75 6c 6c 20 74  es for.** full t
13cd0 61 62 6c 65 20 73 63 61 6e 73 20 69 6e 20 74 68  able scans in th
13ce0 65 20 71 75 65 72 79 20 6f 70 74 69 6d 69 7a 65  e query optimize
13cf0 72 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20  r.  The default 
13d00 73 65 74 74 69 6e 67 20 69 73 20 64 65 74 65 72  setting is deter
13d10 6d 69 6e 65 64 0a 2a 2a 20 62 79 20 74 68 65 20  mined.** by the 
13d20 5b 53 51 4c 49 54 45 5f 41 4c 4c 4f 57 5f 43 4f  [SQLITE_ALLOW_CO
13d30 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41  VERING_INDEX_SCA
13d40 4e 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  N] compile-time 
13d50 6f 70 74 69 6f 6e 2c 20 6f 72 20 69 73 20 22 6f  option, or is "o
13d60 6e 22 0a 2a 2a 20 69 66 20 74 68 61 74 20 63 6f  n".** if that co
13d70 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
13d80 6e 20 69 73 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a  n is omitted..**
13d90 20 54 68 65 20 61 62 69 6c 69 74 79 20 74 6f 20   The ability to 
13da0 64 69 73 61 62 6c 65 20 74 68 65 20 75 73 65 20  disable the use 
13db0 6f 66 20 63 6f 76 65 72 69 6e 67 20 69 6e 64 69  of covering indi
13dc0 63 65 73 20 66 6f 72 20 66 75 6c 6c 20 74 61 62  ces for full tab
13dd0 6c 65 20 73 63 61 6e 73 0a 2a 2a 20 69 73 20 62  le scans.** is b
13de0 65 63 61 75 73 65 20 73 6f 6d 65 20 69 6e 63 6f  ecause some inco
13df0 72 72 65 63 74 6c 79 20 63 6f 64 65 64 20 6c 65  rrectly coded le
13e00 67 61 63 79 20 61 70 70 6c 69 63 61 74 69 6f 6e  gacy application
13e10 73 20 6d 69 67 68 74 20 6d 61 6c 66 75 6e 63 74  s might malfunct
13e20 69 6f 6e 0a 2a 2a 20 6d 61 6c 66 75 6e 63 74 69  ion.** malfuncti
13e30 6f 6e 20 77 68 65 6e 20 74 68 65 20 6f 70 74 69  on when the opti
13e40 6d 69 7a 61 74 69 6f 6e 20 69 73 20 65 6e 61 62  mization is enab
13e50 6c 65 64 2e 20 20 50 72 6f 76 69 64 69 6e 67 20  led.  Providing 
13e60 74 68 65 20 61 62 69 6c 69 74 79 20 74 6f 0a 2a  the ability to.*
13e70 2a 20 64 69 73 61 62 6c 65 20 74 68 65 20 6f 70  * disable the op
13e80 74 69 6d 69 7a 61 74 69 6f 6e 20 61 6c 6c 6f 77  timization allow
13e90 73 20 74 68 65 20 6f 6c 64 65 72 2c 20 62 75 67  s the older, bug
13ea0 67 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63  gy application c
13eb0 6f 64 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77  ode to work.** w
13ec0 69 74 68 6f 75 74 20 63 68 61 6e 67 65 20 65 76  ithout change ev
13ed0 65 6e 20 77 69 74 68 20 6e 65 77 65 72 20 76 65  en with newer ve
13ee0 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
13ef0 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ..**.** [[SQLITE
13f00 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5d 5d  _CONFIG_PCACHE]]
13f10 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
13f20 5f 47 45 54 50 43 41 43 48 45 5d 5d 0a 2a 2a 20  _GETPCACHE]].** 
13f30 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
13f40 47 5f 50 43 41 43 48 45 20 61 6e 64 20 53 51 4c  G_PCACHE and SQL
13f50 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43  ITE_CONFIG_GETPC
13f60 41 43 48 45 0a 2a 2a 20 3c 64 64 3e 20 54 68 65  ACHE.** <dd> The
13f70 73 65 20 6f 70 74 69 6f 6e 73 20 61 72 65 20 6f  se options are o
13f80 62 73 6f 6c 65 74 65 20 61 6e 64 20 73 68 6f 75  bsolete and shou
13f90 6c 64 20 6e 6f 74 20 62 65 20 75 73 65 64 20 62  ld not be used b
13fa0 79 20 6e 65 77 20 63 6f 64 65 2e 0a 2a 2a 20 54  y new code..** T
13fb0 68 65 79 20 61 72 65 20 72 65 74 61 69 6e 65 64  hey are retained
13fc0 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63   for backwards c
13fd0 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 62 75 74  ompatibility but
13fe0 20 61 72 65 20 6e 6f 77 20 6e 6f 2d 6f 70 73 2e   are now no-ops.
13ff0 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </dl>.**.** 
14000 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
14010 53 51 4c 4c 4f 47 5d 5d 0a 2a 2a 20 3c 64 74 3e  SQLLOG]].** <dt>
14020 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51  SQLITE_CONFIG_SQ
14030 4c 4c 4f 47 0a 2a 2a 20 3c 64 64 3e 54 68 69 73  LLOG.** <dd>This
14040 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20   option is only 
14050 61 76 61 69 6c 61 62 6c 65 20 69 66 20 73 71 6c  available if sql
14060 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
14070 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49  with the.** SQLI
14080 54 45 5f 45 4e 41 42 4c 45 5f 53 51 4c 4c 4f 47  TE_ENABLE_SQLLOG
14090 20 70 72 65 2d 70 72 6f 63 65 73 73 6f 72 20 6d   pre-processor m
140a0 61 63 72 6f 20 64 65 66 69 6e 65 64 2e 20 54 68  acro defined. Th
140b0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
140c0 20 73 68 6f 75 6c 64 0a 2a 2a 20 62 65 20 61 20   should.** be a 
140d0 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 66 75 6e  pointer to a fun
140e0 63 74 69 6f 6e 20 6f 66 20 74 79 70 65 20 76 6f  ction of type vo
140f0 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69  id(*)(void*,sqli
14100 74 65 33 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  te3*,const char*
14110 2c 20 69 6e 74 29 2e 0a 2a 2a 20 54 68 65 20 73  , int)..** The s
14120 65 63 6f 6e 64 20 73 68 6f 75 6c 64 20 62 65 20  econd should be 
14130 6f 66 20 74 79 70 65 20 28 76 6f 69 64 2a 29 2e  of type (void*).
14140 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73   The callback is
14150 20 69 6e 76 6f 6b 65 64 20 62 79 20 74 68 65 20   invoked by the 
14160 6c 69 62 72 61 72 79 0a 2a 2a 20 69 6e 20 74 68  library.** in th
14170 72 65 65 20 73 65 70 61 72 61 74 65 20 63 69 72  ree separate cir
14180 63 75 6d 73 74 61 6e 63 65 73 2c 20 69 64 65 6e  cumstances, iden
14190 74 69 66 69 65 64 20 62 79 20 74 68 65 20 76 61  tified by the va
141a0 6c 75 65 20 70 61 73 73 65 64 20 61 73 20 74 68  lue passed as th
141b0 65 0a 2a 2a 20 66 6f 75 72 74 68 20 70 61 72 61  e.** fourth para
141c0 6d 65 74 65 72 2e 20 49 66 20 74 68 65 20 66 6f  meter. If the fo
141d0 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  urth parameter i
141e0 73 20 30 2c 20 74 68 65 6e 20 74 68 65 20 64 61  s 0, then the da
141f0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
14200 6e 0a 2a 2a 20 70 61 73 73 65 64 20 61 73 20 74  n.** passed as t
14210 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
14220 6e 74 20 68 61 73 20 6a 75 73 74 20 62 65 65 6e  nt has just been
14230 20 6f 70 65 6e 65 64 2e 20 54 68 65 20 74 68 69   opened. The thi
14240 72 64 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 70  rd argument.** p
14250 6f 69 6e 74 73 20 74 6f 20 61 20 62 75 66 66 65  oints to a buffe
14260 72 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  r containing the
14270 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6d 61 69   name of the mai
14280 6e 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e  n database file.
14290 20 49 66 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74   If the.** fourt
142a0 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 31  h parameter is 1
142b0 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c 20 73  , then the SQL s
142c0 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 74 68  tatement that th
142d0 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
142e0 72 0a 2a 2a 20 70 6f 69 6e 74 73 20 74 6f 20 68  r.** points to h
142f0 61 73 20 6a 75 73 74 20 62 65 65 6e 20 65 78 65  as just been exe
14300 63 75 74 65 64 2e 20 4f 72 2c 20 69 66 20 74 68  cuted. Or, if th
14310 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
14320 65 72 20 69 73 20 32 2c 20 74 68 65 6e 0a 2a 2a  er is 2, then.**
14330 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20   the connection 
14340 62 65 69 6e 67 20 70 61 73 73 65 64 20 61 73 20  being passed as 
14350 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
14360 65 74 65 72 20 69 73 20 62 65 69 6e 67 20 63 6c  eter is being cl
14370 6f 73 65 64 2e 20 54 68 65 0a 2a 2a 20 74 68 69  osed. The.** thi
14380 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  rd parameter is 
14390 70 61 73 73 65 64 20 4e 55 4c 4c 20 49 6e 20 74  passed NULL In t
143a0 68 69 73 20 63 61 73 65 2e 0a 2a 2a 0a 2a 2a 20  his case..**.** 
143b0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
143c0 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 3c  MMAP_SIZE]].** <
143d0 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
143e0 5f 4d 4d 41 50 5f 53 49 5a 45 0a 2a 2a 20 3c 64  _MMAP_SIZE.** <d
143f0 64 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  d>SQLITE_CONFIG_
14400 4d 4d 41 50 5f 53 49 5a 45 20 74 61 6b 65 73 20  MMAP_SIZE takes 
14410 74 77 6f 20 36 34 2d 62 69 74 20 69 6e 74 65 67  two 64-bit integ
14420 65 72 20 28 73 71 6c 69 74 65 33 5f 69 6e 74 36  er (sqlite3_int6
14430 34 29 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61  4) values.** tha
14440 74 20 61 72 65 20 74 68 65 20 64 65 66 61 75 6c  t are the defaul
14450 74 20 6d 6d 61 70 20 73 69 7a 65 20 6c 69 6d 69  t mmap size limi
14460 74 20 28 74 68 65 20 64 65 66 61 75 6c 74 20 73  t (the default s
14470 65 74 74 69 6e 67 20 66 6f 72 0a 2a 2a 20 5b 50  etting for.** [P
14480 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d  RAGMA mmap_size]
14490 29 20 61 6e 64 20 74 68 65 20 6d 61 78 69 6d 75  ) and the maximu
144a0 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d 61 70 20 73  m allowed mmap s
144b0 69 7a 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 54 68  ize limit..** Th
144c0 65 20 64 65 66 61 75 6c 74 20 73 65 74 74 69 6e  e default settin
144d0 67 20 63 61 6e 20 62 65 20 6f 76 65 72 72 69 64  g can be overrid
144e0 64 65 6e 20 62 79 20 65 61 63 68 20 64 61 74 61  den by each data
144f0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
14500 75 73 69 6e 67 0a 2a 2a 20 65 69 74 68 65 72 20  using.** either 
14510 74 68 65 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70  the [PRAGMA mmap
14520 5f 73 69 7a 65 5d 20 63 6f 6d 6d 61 6e 64 2c 20  _size] command, 
14530 6f 72 20 62 79 20 75 73 69 6e 67 20 74 68 65 0a  or by using the.
14540 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ** [SQLITE_FCNTL
14550 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 66 69 6c 65  _MMAP_SIZE] file
14560 20 63 6f 6e 74 72 6f 6c 2e 20 20 54 68 65 20 6d   control.  The m
14570 61 78 69 6d 75 6d 20 61 6c 6c 6f 77 65 64 20 6d  aximum allowed m
14580 6d 61 70 20 73 69 7a 65 0a 2a 2a 20 63 61 6e 6e  map size.** cann
14590 6f 74 20 62 65 20 63 68 61 6e 67 65 64 20 61 74  ot be changed at
145a0 20 72 75 6e 2d 74 69 6d 65 2e 20 20 4e 6f 72 20   run-time.  Nor 
145b0 6d 61 79 20 74 68 65 20 6d 61 78 69 6d 75 6d 20  may the maximum 
145c0 61 6c 6c 6f 77 65 64 20 6d 6d 61 70 20 73 69 7a  allowed mmap siz
145d0 65 0a 2a 2a 20 65 78 63 65 65 64 20 74 68 65 20  e.** exceed the 
145e0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 61 78  compile-time max
145f0 69 6d 75 6d 20 6d 6d 61 70 20 73 69 7a 65 20 73  imum mmap size s
14600 65 74 20 62 79 20 74 68 65 0a 2a 2a 20 5b 53 51  et by the.** [SQ
14610 4c 49 54 45 5f 4d 41 58 5f 4d 4d 41 50 5f 53 49  LITE_MAX_MMAP_SI
14620 5a 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  ZE] compile-time
14630 20 6f 70 74 69 6f 6e 2e 20 20 0a 2a 2a 20 49 66   option.  .** If
14640 20 65 69 74 68 65 72 20 61 72 67 75 6d 65 6e 74   either argument
14650 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 20   to this option 
14660 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65  is negative, the
14670 6e 20 74 68 61 74 20 61 72 67 75 6d 65 6e 74 20  n that argument 
14680 69 73 0a 2a 2a 20 63 68 61 6e 67 65 64 20 74 6f  is.** changed to
14690 20 69 74 73 20 63 6f 6d 70 69 6c 65 2d 74 69 6d   its compile-tim
146a0 65 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 3c 2f  e default..** </
146b0 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  dl>.*/.#define S
146c0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e  QLITE_CONFIG_SIN
146d0 47 4c 45 54 48 52 45 41 44 20 20 31 20 20 2f 2a  GLETHREAD  1  /*
146e0 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20   nil */.#define 
146f0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
14700 4c 54 49 54 48 52 45 41 44 20 20 20 32 20 20 2f  LTITHREAD   2  /
14710 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65  * nil */.#define
14720 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
14730 45 52 49 41 4c 49 5a 45 44 20 20 20 20 33 20 20  ERIALIZED    3  
14740 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e  /* nil */.#defin
14750 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
14760 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20 20 34 20  MALLOC        4 
14770 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f   /* sqlite3_mem_
14780 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66  methods* */.#def
14790 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
147a0 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 20 20 20 20  G_GETMALLOC     
147b0 35 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65  5  /* sqlite3_me
147c0 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64  m_methods* */.#d
147d0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
147e0 46 49 47 5f 53 43 52 41 54 43 48 20 20 20 20 20  FIG_SCRATCH     
147f0 20 20 36 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69    6  /* void*, i
14800 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a  nt sz, int N */.
14810 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
14820 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 20  ONFIG_PAGECACHE 
14830 20 20 20 20 37 20 20 2f 2a 20 76 6f 69 64 2a 2c      7  /* void*,
14840 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a   int sz, int N *
14850 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
14860 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 20 20 20  _CONFIG_HEAP    
14870 20 20 20 20 20 20 38 20 20 2f 2a 20 76 6f 69 64        8  /* void
14880 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 69 6e  *, int nByte, in
14890 74 20 6d 69 6e 20 2a 2f 0a 23 64 65 66 69 6e 65  t min */.#define
148a0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
148b0 45 4d 53 54 41 54 55 53 20 20 20 20 20 39 20 20  EMSTATUS     9  
148c0 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 23 64  /* boolean */.#d
148d0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
148e0 46 49 47 5f 4d 55 54 45 58 20 20 20 20 20 20 20  FIG_MUTEX       
148f0 20 31 30 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f   10  /* sqlite3_
14900 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a  mutex_methods* *
14910 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
14920 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58  _CONFIG_GETMUTEX
14930 20 20 20 20 20 31 31 20 20 2f 2a 20 73 71 6c 69       11  /* sqli
14940 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64  te3_mutex_method
14950 73 2a 20 2a 2f 0a 2f 2a 20 70 72 65 76 69 6f 75  s* */./* previou
14960 73 6c 79 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  sly SQLITE_CONFI
14970 47 5f 43 48 55 4e 4b 41 4c 4c 4f 43 20 31 32 20  G_CHUNKALLOC 12 
14980 77 68 69 63 68 20 69 73 20 6e 6f 77 20 75 6e 75  which is now unu
14990 73 65 64 2e 20 2a 2f 20 0a 23 64 65 66 69 6e 65  sed. */ .#define
149a0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c   SQLITE_CONFIG_L
149b0 4f 4f 4b 41 53 49 44 45 20 20 20 20 31 33 20 20  OOKASIDE    13  
149c0 2f 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64  /* int int */.#d
149d0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
149e0 46 49 47 5f 50 43 41 43 48 45 20 20 20 20 20 20  FIG_PCACHE      
149f0 20 31 34 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f   14  /* no-op */
14a00 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
14a10 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45  CONFIG_GETPCACHE
14a20 20 20 20 20 31 35 20 20 2f 2a 20 6e 6f 2d 6f 70      15  /* no-op
14a30 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
14a40 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 20 20  TE_CONFIG_LOG   
14a50 20 20 20 20 20 20 20 31 36 20 20 2f 2a 20 78 46         16  /* xF
14a60 75 6e 63 2c 20 76 6f 69 64 2a 20 2a 2f 0a 23 64  unc, void* */.#d
14a70 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
14a80 46 49 47 5f 55 52 49 20 20 20 20 20 20 20 20 20  FIG_URI         
14a90 20 31 37 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23   17  /* int */.#
14aa0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
14ab0 4e 46 49 47 5f 50 43 41 43 48 45 32 20 20 20 20  NFIG_PCACHE2    
14ac0 20 20 31 38 20 20 2f 2a 20 73 71 6c 69 74 65 33    18  /* sqlite3
14ad0 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32  _pcache_methods2
14ae0 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
14af0 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43  ITE_CONFIG_GETPC
14b00 41 43 48 45 32 20 20 20 31 39 20 20 2f 2a 20 73  ACHE2   19  /* s
14b10 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65  qlite3_pcache_me
14b20 74 68 6f 64 73 32 2a 20 2a 2f 0a 23 64 65 66 69  thods2* */.#defi
14b30 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
14b40 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f  _COVERING_INDEX_
14b50 53 43 41 4e 20 32 30 20 20 2f 2a 20 69 6e 74 20  SCAN 20  /* int 
14b60 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
14b70 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 20  E_CONFIG_SQLLOG 
14b80 20 20 20 20 20 20 32 31 20 20 2f 2a 20 78 53 71        21  /* xSq
14b90 6c 6c 6f 67 2c 20 76 6f 69 64 2a 20 2a 2f 0a 23  llog, void* */.#
14ba0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
14bb0 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 20 20  NFIG_MMAP_SIZE  
14bc0 20 20 32 32 20 20 2f 2a 20 73 71 6c 69 74 65 33    22  /* sqlite3
14bd0 5f 69 6e 74 36 34 2c 20 73 71 6c 69 74 65 33 5f  _int64, sqlite3_
14be0 69 6e 74 36 34 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20  int64 */../*.** 
14bf0 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 62 61  CAPI3REF: Databa
14c00 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 43 6f  se Connection Co
14c10 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69  nfiguration Opti
14c20 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ons.**.** These 
14c30 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68  constants are th
14c40 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65  e available inte
14c50 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ger configuratio
14c60 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a  n options that.*
14c70 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65 64 20  * can be passed 
14c80 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  as the second ar
14c90 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73  gument to the [s
14ca0 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
14cb0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ()] interface..*
14cc0 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75  *.** New configu
14cd0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d  ration options m
14ce0 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66  ay be added in f
14cf0 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f  uture releases o
14d00 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69  f SQLite..** Exi
14d10 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74  sting configurat
14d20 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68  ion options migh
14d30 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65  t be discontinue
14d40 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  d.  Applications
14d50 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b  .** should check
14d60 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65   the return code
14d70 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 64   from [sqlite3_d
14d80 62 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d  b_config()] to m
14d90 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a  ake sure that.**
14da0 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64   the call worked
14db0 2e 20 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33  .  ^The [sqlite3
14dc0 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e  _db_config()] in
14dd0 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74  terface will ret
14de0 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72  urn a.** non-zer
14df0 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  o [error code] i
14e00 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64  f a discontinued
14e10 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20   or unsupported 
14e20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
14e30 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b  tion.** is invok
14e40 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a  ed..**.** <dl>.*
14e50 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43  * <dt>SQLITE_DBC
14e60 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c  ONFIG_LOOKASIDE<
14e70 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
14e80 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
14e90 74 68 72 65 65 20 61 64 64 69 74 69 6f 6e 61 6c  three additional
14ea0 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20   arguments that 
14eb0 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 0a 2a  determine the .*
14ec0 2a 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  * [lookaside mem
14ed0 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 20 63  ory allocator] c
14ee0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f 72  onfiguration for
14ef0 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
14f00 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 5e  onnection]..** ^
14f10 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
14f20 6e 74 20 28 74 68 65 20 74 68 69 72 64 20 70 61  nt (the third pa
14f30 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
14f40 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d  te3_db_config()]
14f50 20 69 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72   is a.** pointer
14f60 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20 62 75 66   to a memory buf
14f70 66 65 72 20 74 6f 20 75 73 65 20 66 6f 72 20 6c  fer to use for l
14f80 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 2e  ookaside memory.
14f90 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61  .** ^The first a
14fa0 72 67 75 6d 65 6e 74 20 61 66 74 65 72 20 74 68  rgument after th
14fb0 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  e SQLITE_DBCONFI
14fc0 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 76 65 72 62  G_LOOKASIDE verb
14fd0 0a 2a 2a 20 6d 61 79 20 62 65 20 4e 55 4c 4c 20  .** may be NULL 
14fe0 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 53 51  in which case SQ
14ff0 4c 69 74 65 20 77 69 6c 6c 20 61 6c 6c 6f 63 61  Lite will alloca
15000 74 65 20 74 68 65 0a 2a 2a 20 6c 6f 6f 6b 61 73  te the.** lookas
15010 69 64 65 20 62 75 66 66 65 72 20 69 74 73 65 6c  ide buffer itsel
15020 66 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  f using [sqlite3
15030 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 5e 54 68 65  _malloc()]. ^The
15040 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
15050 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20   is the.** size 
15060 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64  of each lookasid
15070 65 20 62 75 66 66 65 72 20 73 6c 6f 74 2e 20 20  e buffer slot.  
15080 5e 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d  ^The third argum
15090 65 6e 74 20 69 73 20 74 68 65 20 6e 75 6d 62 65  ent is the numbe
150a0 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 2e 20 20  r of.** slots.  
150b0 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  The size of the 
150c0 62 75 66 66 65 72 20 69 6e 20 74 68 65 20 66 69  buffer in the fi
150d0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73  rst argument mus
150e0 74 20 62 65 20 67 72 65 61 74 65 72 20 74 68 61  t be greater tha
150f0 6e 0a 2a 2a 20 6f 72 20 65 71 75 61 6c 20 74 6f  n.** or equal to
15100 20 74 68 65 20 70 72 6f 64 75 63 74 20 6f 66 20   the product of 
15110 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74  the second and t
15120 68 69 72 64 20 61 72 67 75 6d 65 6e 74 73 2e 20  hird arguments. 
15130 20 54 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 6d   The buffer.** m
15140 75 73 74 20 62 65 20 61 6c 69 67 6e 65 64 20 74  ust be aligned t
15150 6f 20 61 6e 20 38 2d 62 79 74 65 20 62 6f 75 6e  o an 8-byte boun
15160 64 61 72 79 2e 20 20 5e 49 66 20 74 68 65 20 73  dary.  ^If the s
15170 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  econd argument t
15180 6f 0a 2a 2a 20 53 51 4c 49 54 45 5f 44 42 43 4f  o.** SQLITE_DBCO
15190 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 69  NFIG_LOOKASIDE i
151a0 73 20 6e 6f 74 20 61 20 6d 75 6c 74 69 70 6c 65  s not a multiple
151b0 20 6f 66 20 38 2c 20 69 74 20 69 73 20 69 6e 74   of 8, it is int
151c0 65 72 6e 61 6c 6c 79 0a 2a 2a 20 72 6f 75 6e 64  ernally.** round
151d0 65 64 20 64 6f 77 6e 20 74 6f 20 74 68 65 20 6e  ed down to the n
151e0 65 78 74 20 73 6d 61 6c 6c 65 72 20 6d 75 6c 74  ext smaller mult
151f0 69 70 6c 65 20 6f 66 20 38 2e 20 20 5e 28 54 68  iple of 8.  ^(Th
15200 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f  e lookaside memo
15210 72 79 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74  ry.** configurat
15220 69 6f 6e 20 66 6f 72 20 61 20 64 61 74 61 62 61  ion for a databa
15230 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 61  se connection ca
15240 6e 20 6f 6e 6c 79 20 62 65 20 63 68 61 6e 67 65  n only be change
15250 64 20 77 68 65 6e 20 74 68 61 74 0a 2a 2a 20 63  d when that.** c
15260 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6e 6f 74  onnection is not
15270 20 63 75 72 72 65 6e 74 6c 79 20 75 73 69 6e 67   currently using
15280 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72   lookaside memor
15290 79 2c 20 6f 72 20 69 6e 20 6f 74 68 65 72 20 77  y, or in other w
152a0 6f 72 64 73 0a 2a 2a 20 77 68 65 6e 20 74 68 65  ords.** when the
152b0 20 22 63 75 72 72 65 6e 74 20 76 61 6c 75 65 22   "current value"
152c0 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20   returned by.** 
152d0 5b 73 71 6c 69 74 65 33 5f 64 62 5f 73 74 61 74  [sqlite3_db_stat
152e0 75 73 5d 28 44 2c 5b 53 51 4c 49 54 45 5f 43 4f  us](D,[SQLITE_CO
152f0 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 2c  NFIG_LOOKASIDE],
15300 2e 2e 2e 29 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a  ...) is zero..**
15310 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20   Any attempt to 
15320 63 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61  change the looka
15330 73 69 64 65 20 6d 65 6d 6f 72 79 20 63 6f 6e 66  side memory conf
15340 69 67 75 72 61 74 69 6f 6e 20 77 68 65 6e 20 6c  iguration when l
15350 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 6d 65 6d 6f  ookaside.** memo
15360 72 79 20 69 73 20 69 6e 20 75 73 65 20 6c 65 61  ry is in use lea
15370 76 65 73 20 74 68 65 20 63 6f 6e 66 69 67 75 72  ves the configur
15380 61 74 69 6f 6e 20 75 6e 63 68 61 6e 67 65 64 20  ation unchanged 
15390 61 6e 64 20 72 65 74 75 72 6e 73 20 0a 2a 2a 20  and returns .** 
153a0 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 29 5e  [SQLITE_BUSY].)^
153b0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
153c0 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
153d0 45 4e 41 42 4c 45 5f 46 4b 45 59 3c 2f 64 74 3e  ENABLE_FKEY</dt>
153e0 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f  .** <dd> ^This o
153f0 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f  ption is used to
15400 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62   enable or disab
15410 6c 65 20 74 68 65 20 65 6e 66 6f 72 63 65 6d 65  le the enforceme
15420 6e 74 20 6f 66 0a 2a 2a 20 5b 66 6f 72 65 69 67  nt of.** [foreig
15430 6e 20 6b 65 79 20 63 6f 6e 73 74 72 61 69 6e 74  n key constraint
15440 73 5d 2e 20 20 54 68 65 72 65 20 73 68 6f 75 6c  s].  There shoul
15450 64 20 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f  d be two additio
15460 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a  nal arguments..*
15470 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  * The first argu
15480 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 67  ment is an integ
15490 65 72 20 77 68 69 63 68 20 69 73 20 30 20 74 6f  er which is 0 to
154a0 20 64 69 73 61 62 6c 65 20 46 4b 20 65 6e 66 6f   disable FK enfo
154b0 72 63 65 6d 65 6e 74 2c 0a 2a 2a 20 70 6f 73 69  rcement,.** posi
154c0 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 46  tive to enable F
154d0 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 72  K enforcement or
154e0 20 6e 65 67 61 74 69 76 65 20 74 6f 20 6c 65 61   negative to lea
154f0 76 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e  ve FK enforcemen
15500 74 0a 2a 2a 20 75 6e 63 68 61 6e 67 65 64 2e 20  t.** unchanged. 
15510 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   The second para
15520 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74  meter is a point
15530 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72  er to an integer
15540 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69   into which.** i
15550 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31  s written 0 or 1
15560 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65   to indicate whe
15570 74 68 65 72 20 46 4b 20 65 6e 66 6f 72 63 65 6d  ther FK enforcem
15580 65 6e 74 20 69 73 20 6f 66 66 20 6f 72 20 6f 6e  ent is off or on
15590 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68  .** following th
155a0 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65  is call.  The se
155b0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d  cond parameter m
155c0 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69  ay be a NULL poi
155d0 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63  nter, in.** whic
155e0 68 20 63 61 73 65 20 74 68 65 20 46 4b 20 65 6e  h case the FK en
155f0 66 6f 72 63 65 6d 65 6e 74 20 73 65 74 74 69 6e  forcement settin
15600 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65  g is not reporte
15610 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a  d back. </dd>.**
15620 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44  .** <dt>SQLITE_D
15630 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54  BCONFIG_ENABLE_T
15640 52 49 47 47 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c  RIGGER</dt>.** <
15650 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  dd> ^This option
15660 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62   is used to enab
15670 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 5b 43  le or disable [C
15680 52 45 41 54 45 20 54 52 49 47 47 45 52 20 7c 20  REATE TRIGGER | 
15690 74 72 69 67 67 65 72 73 5d 2e 0a 2a 2a 20 54 68  triggers]..** Th
156a0 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77  ere should be tw
156b0 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67  o additional arg
156c0 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66  uments..** The f
156d0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73  irst argument is
156e0 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63   an integer whic
156f0 68 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c  h is 0 to disabl
15700 65 20 74 72 69 67 67 65 72 73 2c 0a 2a 2a 20 70  e triggers,.** p
15710 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c  ositive to enabl
15720 65 20 74 72 69 67 67 65 72 73 20 6f 72 20 6e 65  e triggers or ne
15730 67 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20  gative to leave 
15740 74 68 65 20 73 65 74 74 69 6e 67 20 75 6e 63 68  the setting unch
15750 61 6e 67 65 64 2e 0a 2a 2a 20 54 68 65 20 73 65  anged..** The se
15760 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69  cond parameter i
15770 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
15780 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77  n integer into w
15790 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74  hich.** is writt
157a0 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64  en 0 or 1 to ind
157b0 69 63 61 74 65 20 77 68 65 74 68 65 72 20 74 72  icate whether tr
157c0 69 67 67 65 72 73 20 61 72 65 20 64 69 73 61 62  iggers are disab
157d0 6c 65 64 20 6f 72 20 65 6e 61 62 6c 65 64 0a 2a  led or enabled.*
157e0 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73  * following this
157f0 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f   call.  The seco
15800 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79  nd parameter may
15810 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   be a NULL point
15820 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20  er, in.** which 
15830 63 61 73 65 20 74 68 65 20 74 72 69 67 67 65 72  case the trigger
15840 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20   setting is not 
15850 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c  reported back. <
15860 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e  /dd>.**.** </dl>
15870 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
15880 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  TE_DBCONFIG_LOOK
15890 41 53 49 44 45 20 20 20 20 20 20 20 31 30 30 31  ASIDE       1001
158a0 20 20 2f 2a 20 76 6f 69 64 2a 20 69 6e 74 20 69    /* void* int i
158b0 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  nt */.#define SQ
158c0 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e  LITE_DBCONFIG_EN
158d0 41 42 4c 45 5f 46 4b 45 59 20 20 20 20 20 31 30  ABLE_FKEY     10
158e0 30 32 20 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20  02  /* int int* 
158f0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
15900 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c  E_DBCONFIG_ENABL
15910 45 5f 54 52 49 47 47 45 52 20 20 31 30 30 33 20  E_TRIGGER  1003 
15920 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a   /* int int* */.
15930 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
15940 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61  : Enable Or Disa
15950 62 6c 65 20 45 78 74 65 6e 64 65 64 20 52 65 73  ble Extended Res
15960 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20  ult Codes.**.** 
15970 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74  ^The sqlite3_ext
15980 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64  ended_result_cod
15990 65 73 28 29 20 72 6f 75 74 69 6e 65 20 65 6e 61  es() routine ena
159a0 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73  bles or disables
159b0 20 74 68 65 0a 2a 2a 20 5b 65 78 74 65 6e 64 65   the.** [extende
159c0 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20  d result codes] 
159d0 66 65 61 74 75 72 65 20 6f 66 20 53 51 4c 69 74  feature of SQLit
159e0 65 2e 20 5e 54 68 65 20 65 78 74 65 6e 64 65 64  e. ^The extended
159f0 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 64 65 73   result.** codes
15a00 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 62 79   are disabled by
15a10 20 64 65 66 61 75 6c 74 20 66 6f 72 20 68 69 73   default for his
15a20 74 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74 69 62  torical compatib
15a30 69 6c 69 74 79 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ility..*/.int sq
15a40 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72  lite3_extended_r
15a50 65 73 75 6c 74 5f 63 6f 64 65 73 28 73 71 6c 69  esult_codes(sqli
15a60 74 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66 29  te3*, int onoff)
15a70 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
15a80 46 3a 20 4c 61 73 74 20 49 6e 73 65 72 74 20 52  F: Last Insert R
15a90 6f 77 69 64 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68  owid.**.** ^Each
15aa0 20 65 6e 74 72 79 20 69 6e 20 61 6e 20 53 51 4c   entry in an SQL
15ab0 69 74 65 20 74 61 62 6c 65 20 68 61 73 20 61 20  ite table has a 
15ac0 75 6e 69 71 75 65 20 36 34 2d 62 69 74 20 73 69  unique 64-bit si
15ad0 67 6e 65 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20  gned.** integer 
15ae0 6b 65 79 20 63 61 6c 6c 65 64 20 74 68 65 20 5b  key called the [
15af0 52 4f 57 49 44 20 7c 20 22 72 6f 77 69 64 22 5d  ROWID | "rowid"]
15b00 2e 20 5e 54 68 65 20 72 6f 77 69 64 20 69 73 20  . ^The rowid is 
15b10 61 6c 77 61 79 73 20 61 76 61 69 6c 61 62 6c 65  always available
15b20 0a 2a 2a 20 61 73 20 61 6e 20 75 6e 64 65 63 6c  .** as an undecl
15b30 61 72 65 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65  ared column name
15b40 64 20 52 4f 57 49 44 2c 20 4f 49 44 2c 20 6f 72  d ROWID, OID, or
15b50 20 5f 52 4f 57 49 44 5f 20 61 73 20 6c 6f 6e 67   _ROWID_ as long
15b60 20 61 73 20 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d   as those.** nam
15b70 65 73 20 61 72 65 20 6e 6f 74 20 61 6c 73 6f 20  es are not also 
15b80 75 73 65 64 20 62 79 20 65 78 70 6c 69 63 69 74  used by explicit
15b90 6c 79 20 64 65 63 6c 61 72 65 64 20 63 6f 6c 75  ly declared colu
15ba0 6d 6e 73 2e 20 5e 49 66 0a 2a 2a 20 74 68 65 20  mns. ^If.** the 
15bb0 74 61 62 6c 65 20 68 61 73 20 61 20 63 6f 6c 75  table has a colu
15bc0 6d 6e 20 6f 66 20 74 79 70 65 20 5b 49 4e 54 45  mn of type [INTE
15bd0 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59 5d  GER PRIMARY KEY]
15be0 20 74 68 65 6e 20 74 68 61 74 20 63 6f 6c 75 6d   then that colum
15bf0 6e 0a 2a 2a 20 69 73 20 61 6e 6f 74 68 65 72 20  n.** is another 
15c00 61 6c 69 61 73 20 66 6f 72 20 74 68 65 20 72 6f  alias for the ro
15c10 77 69 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  wid..**.** ^This
15c20 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
15c30 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20   the [rowid] of 
15c40 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 0a  the most recent.
15c50 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49  ** successful [I
15c60 4e 53 45 52 54 5d 20 69 6e 74 6f 20 74 68 65 20  NSERT] into the 
15c70 64 61 74 61 62 61 73 65 20 66 72 6f 6d 20 74 68  database from th
15c80 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
15c90 65 63 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68  ection].** in th
15ca0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
15cb0 2e 20 20 5e 41 73 20 6f 66 20 53 51 4c 69 74 65  .  ^As of SQLite
15cc0 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e 37 2c 20   version 3.7.7, 
15cd0 74 68 69 73 20 72 6f 75 74 69 6e 65 73 0a 2a 2a  this routines.**
15ce0 20 72 65 63 6f 72 64 73 20 74 68 65 20 6c 61 73   records the las
15cf0 74 20 69 6e 73 65 72 74 20 72 6f 77 69 64 20 6f  t insert rowid o
15d00 66 20 62 6f 74 68 20 6f 72 64 69 6e 61 72 79 20  f both ordinary 
15d10 74 61 62 6c 65 73 20 61 6e 64 20 5b 76 69 72 74  tables and [virt
15d20 75 61 6c 20 74 61 62 6c 65 73 5d 2e 0a 2a 2a 20  ual tables]..** 
15d30 5e 49 66 20 6e 6f 20 73 75 63 63 65 73 73 66 75  ^If no successfu
15d40 6c 20 5b 49 4e 53 45 52 54 5d 73 0a 2a 2a 20 68  l [INSERT]s.** h
15d50 61 76 65 20 65 76 65 72 20 6f 63 63 75 72 72 65  ave ever occurre
15d60 64 20 6f 6e 20 74 68 61 74 20 64 61 74 61 62 61  d on that databa
15d70 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 7a  se connection, z
15d80 65 72 6f 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ero is returned.
15d90 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 6e 20 5b  .**.** ^(If an [
15da0 49 4e 53 45 52 54 5d 20 6f 63 63 75 72 73 20 77  INSERT] occurs w
15db0 69 74 68 69 6e 20 61 20 74 72 69 67 67 65 72 20  ithin a trigger 
15dc0 6f 72 20 77 69 74 68 69 6e 20 61 20 5b 76 69 72  or within a [vir
15dd0 74 75 61 6c 20 74 61 62 6c 65 5d 0a 2a 2a 20 6d  tual table].** m
15de0 65 74 68 6f 64 2c 20 74 68 65 6e 20 74 68 69 73  ethod, then this
15df0 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20 72 65   routine will re
15e00 74 75 72 6e 20 74 68 65 20 5b 72 6f 77 69 64 5d  turn the [rowid]
15e10 20 6f 66 20 74 68 65 20 69 6e 73 65 72 74 65 64   of the inserted
15e20 0a 2a 2a 20 72 6f 77 20 61 73 20 6c 6f 6e 67 20  .** row as long 
15e30 61 73 20 74 68 65 20 74 72 69 67 67 65 72 20 6f  as the trigger o
15e40 72 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20  r virtual table 
15e50 6d 65 74 68 6f 64 20 69 73 20 72 75 6e 6e 69 6e  method is runnin
15e60 67 2e 0a 2a 2a 20 42 75 74 20 6f 6e 63 65 20 74  g..** But once t
15e70 68 65 20 74 72 69 67 67 65 72 20 6f 72 20 76 69  he trigger or vi
15e80 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 65 74 68  rtual table meth
15e90 6f 64 20 65 6e 64 73 2c 20 74 68 65 20 76 61 6c  od ends, the val
15ea0 75 65 20 72 65 74 75 72 6e 65 64 20 0a 2a 2a 20  ue returned .** 
15eb0 62 79 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  by this routine 
15ec0 72 65 76 65 72 74 73 20 74 6f 20 77 68 61 74 20  reverts to what 
15ed0 69 74 20 77 61 73 20 62 65 66 6f 72 65 20 74 68  it was before th
15ee0 65 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 72  e trigger or vir
15ef0 74 75 61 6c 0a 2a 2a 20 74 61 62 6c 65 20 6d 65  tual.** table me
15f00 74 68 6f 64 20 62 65 67 61 6e 2e 29 5e 0a 2a 2a  thod began.)^.**
15f10 0a 2a 2a 20 5e 41 6e 20 5b 49 4e 53 45 52 54 5d  .** ^An [INSERT]
15f20 20 74 68 61 74 20 66 61 69 6c 73 20 64 75 65 20   that fails due 
15f30 74 6f 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20  to a constraint 
15f40 76 69 6f 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 74  violation is not
15f50 20 61 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c   a.** successful
15f60 20 5b 49 4e 53 45 52 54 5d 20 61 6e 64 20 64 6f   [INSERT] and do
15f70 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68  es not change th
15f80 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
15f90 20 62 79 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74   by this.** rout
15fa0 69 6e 65 2e 20 20 5e 54 68 75 73 20 49 4e 53 45  ine.  ^Thus INSE
15fb0 52 54 20 4f 52 20 46 41 49 4c 2c 20 49 4e 53 45  RT OR FAIL, INSE
15fc0 52 54 20 4f 52 20 49 47 4e 4f 52 45 2c 20 49 4e  RT OR IGNORE, IN
15fd0 53 45 52 54 20 4f 52 20 52 4f 4c 4c 42 41 43 4b  SERT OR ROLLBACK
15fe0 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53 45 52 54 20  ,.** and INSERT 
15ff0 4f 52 20 41 42 4f 52 54 20 6d 61 6b 65 20 6e 6f  OR ABORT make no
16000 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20   changes to the 
16010 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
16020 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  this.** routine 
16030 77 68 65 6e 20 74 68 65 69 72 20 69 6e 73 65 72  when their inser
16040 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20 5e 28 57  tion fails.  ^(W
16050 68 65 6e 20 49 4e 53 45 52 54 20 4f 52 20 52 45  hen INSERT OR RE
16060 50 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74  PLACE.** encount
16070 65 72 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74  ers a constraint
16080 20 76 69 6f 6c 61 74 69 6f 6e 2c 20 69 74 20 64   violation, it d
16090 6f 65 73 20 6e 6f 74 20 66 61 69 6c 2e 20 20 54  oes not fail.  T
160a0 68 65 0a 2a 2a 20 49 4e 53 45 52 54 20 63 6f 6e  he.** INSERT con
160b0 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65  tinues to comple
160c0 74 69 6f 6e 20 61 66 74 65 72 20 64 65 6c 65 74  tion after delet
160d0 69 6e 67 20 72 6f 77 73 20 74 68 61 74 20 63 61  ing rows that ca
160e0 75 73 65 64 0a 2a 2a 20 74 68 65 20 63 6f 6e 73  used.** the cons
160f0 74 72 61 69 6e 74 20 70 72 6f 62 6c 65 6d 20 73  traint problem s
16100 6f 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c  o INSERT OR REPL
16110 41 43 45 20 77 69 6c 6c 20 61 6c 77 61 79 73 20  ACE will always 
16120 63 68 61 6e 67 65 0a 2a 2a 20 74 68 65 20 72 65  change.** the re
16130 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68  turn value of th
16140 69 73 20 69 6e 74 65 72 66 61 63 65 2e 29 5e 0a  is interface.)^.
16150 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20 70  **.** ^For the p
16160 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20  urposes of this 
16170 72 6f 75 74 69 6e 65 2c 20 61 6e 20 5b 49 4e 53  routine, an [INS
16180 45 52 54 5d 20 69 73 20 63 6f 6e 73 69 64 65 72  ERT] is consider
16190 65 64 20 74 6f 0a 2a 2a 20 62 65 20 73 75 63 63  ed to.** be succ
161a0 65 73 73 66 75 6c 20 65 76 65 6e 20 69 66 20 69  essful even if i
161b0 74 20 69 73 20 73 75 62 73 65 71 75 65 6e 74 6c  t is subsequentl
161c0 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a  y rolled back..*
161d0 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69  *.** This functi
161e0 6f 6e 20 69 73 20 61 63 63 65 73 73 69 62 6c 65  on is accessible
161f0 20 74 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   to SQL statemen
16200 74 73 20 76 69 61 20 74 68 65 0a 2a 2a 20 5b 6c  ts via the.** [l
16210 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
16220 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d  () SQL function]
16230 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70  ..**.** If a sep
16240 61 72 61 74 65 20 74 68 72 65 61 64 20 70 65 72  arate thread per
16250 66 6f 72 6d 73 20 61 20 6e 65 77 20 5b 49 4e 53  forms a new [INS
16260 45 52 54 5d 20 6f 6e 20 74 68 65 20 73 61 6d 65  ERT] on the same
16270 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e  .** database con
16280 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68  nection while th
16290 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f  e [sqlite3_last_
162a0 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 0a  insert_rowid()].
162b0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72  ** function is r
162c0 75 6e 6e 69 6e 67 20 61 6e 64 20 74 68 75 73 20  unning and thus 
162d0 63 68 61 6e 67 65 73 20 74 68 65 20 6c 61 73 74  changes the last
162e0 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2c   insert [rowid],
162f0 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 76 61 6c  .** then the val
16300 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b  ue returned by [
16310 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73  sqlite3_last_ins
16320 65 72 74 5f 72 6f 77 69 64 28 29 5d 20 69 73 0a  ert_rowid()] is.
16330 2a 2a 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65  ** unpredictable
16340 20 61 6e 64 20 6d 69 67 68 74 20 6e 6f 74 20 65   and might not e
16350 71 75 61 6c 20 65 69 74 68 65 72 20 74 68 65 20  qual either the 
16360 6f 6c 64 20 6f 72 20 74 68 65 20 6e 65 77 0a 2a  old or the new.*
16370 2a 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72  * last insert [r
16380 6f 77 69 64 5d 2e 0a 2a 2f 0a 73 71 6c 69 74 65  owid]..*/.sqlite
16390 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  3_int64 sqlite3_
163a0 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
163b0 64 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a  d(sqlite3*);../*
163c0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
163d0 75 6e 74 20 54 68 65 20 4e 75 6d 62 65 72 20 4f  unt The Number O
163e0 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a  f Rows Modified.
163f0 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63  **.** ^This func
16400 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65  tion returns the
16410 20 6e 75 6d 62 65 72 20 6f 66 20 64 61 74 61 62   number of datab
16420 61 73 65 20 72 6f 77 73 20 74 68 61 74 20 77 65  ase rows that we
16430 72 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20 6f 72  re changed.** or
16440 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64 65 6c   inserted or del
16450 65 74 65 64 20 62 79 20 74 68 65 20 6d 6f 73 74  eted by the most
16460 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65   recently comple
16470 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ted SQL statemen
16480 74 0a 2a 2a 20 6f 6e 20 74 68 65 20 5b 64 61 74  t.** on the [dat
16490 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
164a0 5d 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74  ] specified by t
164b0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
164c0 65 72 2e 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 63 68  er..** ^(Only ch
164d0 61 6e 67 65 73 20 74 68 61 74 20 61 72 65 20 64  anges that are d
164e0 69 72 65 63 74 6c 79 20 73 70 65 63 69 66 69 65  irectly specifie
164f0 64 20 62 79 20 74 68 65 20 5b 49 4e 53 45 52 54  d by the [INSERT
16500 5d 2c 20 5b 55 50 44 41 54 45 5d 2c 0a 2a 2a 20  ], [UPDATE],.** 
16510 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73 74 61 74  or [DELETE] stat
16520 65 6d 65 6e 74 20 61 72 65 20 63 6f 75 6e 74 65  ement are counte
16530 64 2e 20 20 41 75 78 69 6c 69 61 72 79 20 63 68  d.  Auxiliary ch
16540 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 0a  anges caused by.
16550 2a 2a 20 74 72 69 67 67 65 72 73 20 6f 72 20 5b  ** triggers or [
16560 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69  foreign key acti
16570 6f 6e 73 5d 20 61 72 65 20 6e 6f 74 20 63 6f 75  ons] are not cou
16580 6e 74 65 64 2e 29 5e 20 55 73 65 20 74 68 65 0a  nted.)^ Use the.
16590 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61  ** [sqlite3_tota
165a0 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 66 75 6e  l_changes()] fun
165b0 63 74 69 6f 6e 20 74 6f 20 66 69 6e 64 20 74 68  ction to find th
165c0 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f  e total number o
165d0 66 20 63 68 61 6e 67 65 73 0a 2a 2a 20 69 6e 63  f changes.** inc
165e0 6c 75 64 69 6e 67 20 63 68 61 6e 67 65 73 20 63  luding changes c
165f0 61 75 73 65 64 20 62 79 20 74 72 69 67 67 65 72  aused by trigger
16600 73 20 61 6e 64 20 66 6f 72 65 69 67 6e 20 6b 65  s and foreign ke
16610 79 20 61 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  y actions..**.**
16620 20 5e 43 68 61 6e 67 65 73 20 74 6f 20 61 20 76   ^Changes to a v
16630 69 65 77 20 74 68 61 74 20 61 72 65 20 73 69 6d  iew that are sim
16640 75 6c 61 74 65 64 20 62 79 20 61 6e 20 5b 49 4e  ulated by an [IN
16650 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 72  STEAD OF trigger
16660 5d 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 63 6f 75  ].** are not cou
16670 6e 74 65 64 2e 20 20 4f 6e 6c 79 20 72 65 61 6c  nted.  Only real
16680 20 74 61 62 6c 65 20 63 68 61 6e 67 65 73 20 61   table changes a
16690 72 65 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a  re counted..**.*
166a0 2a 20 5e 28 41 20 22 72 6f 77 20 63 68 61 6e 67  * ^(A "row chang
166b0 65 22 20 69 73 20 61 20 63 68 61 6e 67 65 20 74  e" is a change t
166c0 6f 20 61 20 73 69 6e 67 6c 65 20 72 6f 77 20 6f  o a single row o
166d0 66 20 61 20 73 69 6e 67 6c 65 20 74 61 62 6c 65  f a single table
166e0 0a 2a 2a 20 63 61 75 73 65 64 20 62 79 20 61 6e  .** caused by an
166f0 20 49 4e 53 45 52 54 2c 20 44 45 4c 45 54 45 2c   INSERT, DELETE,
16700 20 6f 72 20 55 50 44 41 54 45 20 73 74 61 74 65   or UPDATE state
16710 6d 65 6e 74 2e 20 20 52 6f 77 73 20 74 68 61 74  ment.  Rows that
16720 0a 2a 2a 20 61 72 65 20 63 68 61 6e 67 65 64 20  .** are changed 
16730 61 73 20 73 69 64 65 20 65 66 66 65 63 74 73 20  as side effects 
16740 6f 66 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e  of [REPLACE] con
16750 73 74 72 61 69 6e 74 20 72 65 73 6f 6c 75 74 69  straint resoluti
16760 6f 6e 2c 0a 2a 2a 20 72 6f 6c 6c 62 61 63 6b 2c  on,.** rollback,
16770 20 41 42 4f 52 54 20 70 72 6f 63 65 73 73 69 6e   ABORT processin
16780 67 2c 20 5b 44 52 4f 50 20 54 41 42 4c 45 5d 2c  g, [DROP TABLE],
16790 20 6f 72 20 62 79 20 61 6e 79 20 6f 74 68 65 72   or by any other
167a0 0a 2a 2a 20 6d 65 63 68 61 6e 69 73 6d 73 20 64  .** mechanisms d
167b0 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 64  o not count as d
167c0 69 72 65 63 74 20 72 6f 77 20 63 68 61 6e 67 65  irect row change
167d0 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 22 74 72  s.)^.**.** A "tr
167e0 69 67 67 65 72 20 63 6f 6e 74 65 78 74 22 20 69  igger context" i
167f0 73 20 61 20 73 63 6f 70 65 20 6f 66 20 65 78 65  s a scope of exe
16800 63 75 74 69 6f 6e 20 74 68 61 74 20 62 65 67 69  cution that begi
16810 6e 73 20 61 6e 64 0a 2a 2a 20 65 6e 64 73 20 77  ns and.** ends w
16820 69 74 68 20 74 68 65 20 73 63 72 69 70 74 20 6f  ith the script o
16830 66 20 61 20 5b 43 52 45 41 54 45 20 54 52 49 47  f a [CREATE TRIG
16840 47 45 52 20 7c 20 74 72 69 67 67 65 72 5d 2e 20  GER | trigger]. 
16850 0a 2a 2a 20 4d 6f 73 74 20 53 51 4c 20 73 74 61  .** Most SQL sta
16860 74 65 6d 65 6e 74 73 20 61 72 65 0a 2a 2a 20 65  tements are.** e
16870 76 61 6c 75 61 74 65 64 20 6f 75 74 73 69 64 65  valuated outside
16880 20 6f 66 20 61 6e 79 20 74 72 69 67 67 65 72 2e   of any trigger.
16890 20 20 54 68 69 73 20 69 73 20 74 68 65 20 22 74    This is the "t
168a0 6f 70 20 6c 65 76 65 6c 22 0a 2a 2a 20 74 72 69  op level".** tri
168b0 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 20 20 49  gger context.  I
168c0 66 20 61 20 74 72 69 67 67 65 72 20 66 69 72 65  f a trigger fire
168d0 73 20 66 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c  s from the top l
168e0 65 76 65 6c 2c 20 61 0a 2a 2a 20 6e 65 77 20 74  evel, a.** new t
168f0 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 20 69  rigger context i
16900 73 20 65 6e 74 65 72 65 64 20 66 6f 72 20 74 68  s entered for th
16910 65 20 64 75 72 61 74 69 6f 6e 20 6f 66 20 74 68  e duration of th
16920 61 74 20 6f 6e 65 0a 2a 2a 20 74 72 69 67 67 65  at one.** trigge
16930 72 2e 20 20 53 75 62 74 72 69 67 67 65 72 73 20  r.  Subtriggers 
16940 63 72 65 61 74 65 20 73 75 62 63 6f 6e 74 65 78  create subcontex
16950 74 73 20 66 6f 72 20 74 68 65 69 72 20 64 75 72  ts for their dur
16960 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61  ation..**.** ^Ca
16970 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65  lling [sqlite3_e
16980 78 65 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  xec()] or [sqlit
16990 65 33 5f 73 74 65 70 28 29 5d 20 72 65 63 75 72  e3_step()] recur
169a0 73 69 76 65 6c 79 20 64 6f 65 73 0a 2a 2a 20 6e  sively does.** n
169b0 6f 74 20 63 72 65 61 74 65 20 61 20 6e 65 77 20  ot create a new 
169c0 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e  trigger context.
169d0 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e  .**.** ^This fun
169e0 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68  ction returns th
169f0 65 20 6e 75 6d 62 65 72 20 6f 66 20 64 69 72 65  e number of dire
16a00 63 74 20 72 6f 77 20 63 68 61 6e 67 65 73 20 69  ct row changes i
16a10 6e 20 74 68 65 0a 2a 2a 20 6d 6f 73 74 20 72 65  n the.** most re
16a20 63 65 6e 74 20 49 4e 53 45 52 54 2c 20 55 50 44  cent INSERT, UPD
16a30 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 20 73  ATE, or DELETE s
16a40 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20  tatement within 
16a50 74 68 65 20 73 61 6d 65 0a 2a 2a 20 74 72 69 67  the same.** trig
16a60 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a  ger context..**.
16a70 2a 2a 20 5e 54 68 75 73 2c 20 77 68 65 6e 20 63  ** ^Thus, when c
16a80 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 74  alled from the t
16a90 6f 70 20 6c 65 76 65 6c 2c 20 74 68 69 73 20 66  op level, this f
16aa0 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
16ab0 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66  the.** number of
16ac0 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20   changes in the 
16ad0 6d 6f 73 74 20 72 65 63 65 6e 74 20 49 4e 53 45  most recent INSE
16ae0 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44  RT, UPDATE, or D
16af0 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 61 6c  ELETE.** that al
16b00 73 6f 20 6f 63 63 75 72 72 65 64 20 61 74 20 74  so occurred at t
16b10 68 65 20 74 6f 70 20 6c 65 76 65 6c 2e 20 20 5e  he top level.  ^
16b20 28 57 69 74 68 69 6e 20 74 68 65 20 62 6f 64 79  (Within the body
16b30 20 6f 66 20 61 20 74 72 69 67 67 65 72 2c 0a 2a   of a trigger,.*
16b40 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68  * the sqlite3_ch
16b50 61 6e 67 65 73 28 29 20 69 6e 74 65 72 66 61 63  anges() interfac
16b60 65 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20  e can be called 
16b70 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62  to find the numb
16b80 65 72 20 6f 66 0a 2a 2a 20 63 68 61 6e 67 65 73  er of.** changes
16b90 20 69 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63   in the most rec
16ba0 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20  ently completed 
16bb0 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20  INSERT, UPDATE, 
16bc0 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 73 74 61  or DELETE.** sta
16bd0 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68  tement within th
16be0 65 20 62 6f 64 79 20 6f 66 20 74 68 65 20 73 61  e body of the sa
16bf0 6d 65 20 74 72 69 67 67 65 72 2e 0a 2a 2a 20 48  me trigger..** H
16c00 6f 77 65 76 65 72 2c 20 74 68 65 20 6e 75 6d 62  owever, the numb
16c10 65 72 20 72 65 74 75 72 6e 65 64 20 64 6f 65 73  er returned does
16c20 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 63 68 61   not include cha
16c30 6e 67 65 73 0a 2a 2a 20 63 61 75 73 65 64 20 62  nges.** caused b
16c40 79 20 73 75 62 74 72 69 67 67 65 72 73 20 73 69  y subtriggers si
16c50 6e 63 65 20 74 68 6f 73 65 20 68 61 76 65 20 74  nce those have t
16c60 68 65 69 72 20 6f 77 6e 20 63 6f 6e 74 65 78 74  heir own context
16c70 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  .)^.**.** See al
16c80 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  so the [sqlite3_
16c90 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d  total_changes()]
16ca0 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 0a   interface, the.
16cb0 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65  ** [count_change
16cc0 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74  s pragma], and t
16cd0 68 65 20 5b 63 68 61 6e 67 65 73 28 29 20 53 51  he [changes() SQ
16ce0 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a  L function]..**.
16cf0 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65  ** If a separate
16d00 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68   thread makes ch
16d10 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d  anges on the sam
16d20 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
16d30 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b  ction.** while [
16d40 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
16d50 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68  )] is running th
16d60 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  en the value ret
16d70 75 72 6e 65 64 0a 2a 2a 20 69 73 20 75 6e 70 72  urned.** is unpr
16d80 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f  edictable and no
16d90 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f  t meaningful..*/
16da0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 68 61  .int sqlite3_cha
16db0 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a  nges(sqlite3*);.
16dc0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
16dd0 20 54 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66   Total Number Of
16de0 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a   Rows Modified.*
16df0 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74  *.** ^This funct
16e00 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20  ion returns the 
16e10 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 20 63 68  number of row ch
16e20 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 20  anges caused by 
16e30 5b 49 4e 53 45 52 54 5d 2c 0a 2a 2a 20 5b 55 50  [INSERT],.** [UP
16e40 44 41 54 45 5d 20 6f 72 20 5b 44 45 4c 45 54 45  DATE] or [DELETE
16e50 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 73 69 6e  ] statements sin
16e60 63 65 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  ce the [database
16e70 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 61 73   connection] was
16e80 20 6f 70 65 6e 65 64 2e 0a 2a 2a 20 5e 28 54 68   opened..** ^(Th
16e90 65 20 63 6f 75 6e 74 20 72 65 74 75 72 6e 65 64  e count returned
16ea0 20 62 79 20 73 71 6c 69 74 65 33 5f 74 6f 74 61   by sqlite3_tota
16eb0 6c 5f 63 68 61 6e 67 65 73 28 29 20 69 6e 63 6c  l_changes() incl
16ec0 75 64 65 73 20 61 6c 6c 20 63 68 61 6e 67 65 73  udes all changes
16ed0 0a 2a 2a 20 66 72 6f 6d 20 61 6c 6c 20 5b 43 52  .** from all [CR
16ee0 45 41 54 45 20 54 52 49 47 47 45 52 20 7c 20 74  EATE TRIGGER | t
16ef0 72 69 67 67 65 72 5d 20 63 6f 6e 74 65 78 74 73  rigger] contexts
16f00 20 61 6e 64 20 63 68 61 6e 67 65 73 20 6d 61 64   and changes mad
16f10 65 20 62 79 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e  e by.** [foreign
16f20 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d 2e 20 48   key actions]. H
16f30 6f 77 65 76 65 72 2c 0a 2a 2a 20 74 68 65 20 63  owever,.** the c
16f40 6f 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e  ount does not in
16f50 63 6c 75 64 65 20 63 68 61 6e 67 65 73 20 75 73  clude changes us
16f60 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20  ed to implement 
16f70 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72  [REPLACE] constr
16f80 61 69 6e 74 73 2c 0a 2a 2a 20 64 6f 20 72 6f 6c  aints,.** do rol
16f90 6c 62 61 63 6b 73 20 6f 72 20 41 42 4f 52 54 20  lbacks or ABORT 
16fa0 70 72 6f 63 65 73 73 69 6e 67 2c 20 6f 72 20 5b  processing, or [
16fb0 44 52 4f 50 20 54 41 42 4c 45 5d 20 70 72 6f 63  DROP TABLE] proc
16fc0 65 73 73 69 6e 67 2e 20 20 54 68 65 0a 2a 2a 20  essing.  The.** 
16fd0 63 6f 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69  count does not i
16fe0 6e 63 6c 75 64 65 20 72 6f 77 73 20 6f 66 20 76  nclude rows of v
16ff0 69 65 77 73 20 74 68 61 74 20 66 69 72 65 20 61  iews that fire a
17000 6e 20 5b 49 4e 53 54 45 41 44 20 4f 46 20 74 72  n [INSTEAD OF tr
17010 69 67 67 65 72 5d 2c 0a 2a 2a 20 74 68 6f 75 67  igger],.** thoug
17020 68 20 69 66 20 74 68 65 20 49 4e 53 54 45 41 44  h if the INSTEAD
17030 20 4f 46 20 74 72 69 67 67 65 72 20 6d 61 6b 65   OF trigger make
17040 73 20 63 68 61 6e 67 65 73 20 6f 66 20 69 74 73  s changes of its
17050 20 6f 77 6e 2c 20 74 68 6f 73 65 20 63 68 61 6e   own, those chan
17060 67 65 73 20 0a 2a 2a 20 61 72 65 20 63 6f 75 6e  ges .** are coun
17070 74 65 64 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 73  ted.)^.** ^The s
17080 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61  qlite3_total_cha
17090 6e 67 65 73 28 29 20 66 75 6e 63 74 69 6f 6e 20  nges() function 
170a0 63 6f 75 6e 74 73 20 74 68 65 20 63 68 61 6e 67  counts the chang
170b0 65 73 20 61 73 20 73 6f 6f 6e 20 61 73 0a 2a 2a  es as soon as.**
170c0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74   the statement t
170d0 68 61 74 20 6d 61 6b 65 73 20 74 68 65 6d 20 69  hat makes them i
170e0 73 20 63 6f 6d 70 6c 65 74 65 64 20 28 77 68 65  s completed (whe
170f0 6e 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  n the statement 
17100 68 61 6e 64 6c 65 0a 2a 2a 20 69 73 20 70 61 73  handle.** is pas
17110 73 65 64 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  sed to [sqlite3_
17120 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c  reset()] or [sql
17130 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
17140 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  )..**.** See als
17150 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  o the [sqlite3_c
17160 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66  hanges()] interf
17170 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75  ace, the.** [cou
17180 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d  nt_changes pragm
17190 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b 74 6f 74  a], and the [tot
171a0 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 53 51 4c  al_changes() SQL
171b0 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a   function]..**.*
171c0 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20  * If a separate 
171d0 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61  thread makes cha
171e0 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65  nges on the same
171f0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
17200 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73  tion.** while [s
17210 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61  qlite3_total_cha
17220 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69  nges()] is runni
17230 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75  ng then the valu
17240 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 73  e.** returned is
17250 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61   unpredictable a
17260 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75  nd not meaningfu
17270 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  l..*/.int sqlite
17280 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
17290 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a  sqlite3*);../*.*
172a0 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 74 65  * CAPI3REF: Inte
172b0 72 72 75 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e  rrupt A Long-Run
172c0 6e 69 6e 67 20 51 75 65 72 79 0a 2a 2a 0a 2a 2a  ning Query.**.**
172d0 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20   ^This function 
172e0 63 61 75 73 65 73 20 61 6e 79 20 70 65 6e 64 69  causes any pendi
172f0 6e 67 20 64 61 74 61 62 61 73 65 20 6f 70 65 72  ng database oper
17300 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72 74 20 61  ation to abort a
17310 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20 61 74 20  nd.** return at 
17320 69 74 73 20 65 61 72 6c 69 65 73 74 20 6f 70 70  its earliest opp
17330 6f 72 74 75 6e 69 74 79 2e 20 54 68 69 73 20 72  ortunity. This r
17340 6f 75 74 69 6e 65 20 69 73 20 74 79 70 69 63 61  outine is typica
17350 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 69 6e  lly.** called in
17360 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 61 20 75   response to a u
17370 73 65 72 20 61 63 74 69 6f 6e 20 73 75 63 68 20  ser action such 
17380 61 73 20 70 72 65 73 73 69 6e 67 20 22 43 61 6e  as pressing "Can
17390 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d  cel".** or Ctrl-
173a0 43 20 77 68 65 72 65 20 74 68 65 20 75 73 65 72  C where the user
173b0 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67 20 71 75   wants a long qu
173c0 65 72 79 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f  ery operation to
173d0 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69 61   halt.** immedia
173e0 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20  tely..**.** ^It 
173f0 69 73 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20  is safe to call 
17400 74 68 69 73 20 72 6f 75 74 69 6e 65 20 66 72 6f  this routine fro
17410 6d 20 61 20 74 68 72 65 61 64 20 64 69 66 66 65  m a thread diffe
17420 72 65 6e 74 20 66 72 6f 6d 20 74 68 65 0a 2a 2a  rent from the.**
17430 20 74 68 72 65 61 64 20 74 68 61 74 20 69 73 20   thread that is 
17440 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e  currently runnin
17450 67 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6f  g the database o
17460 70 65 72 61 74 69 6f 6e 2e 20 20 42 75 74 20 69  peration.  But i
17470 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 61 66 65  t.** is not safe
17480 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f   to call this ro
17490 75 74 69 6e 65 20 77 69 74 68 20 61 20 5b 64 61  utine with a [da
174a0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
174b0 6e 5d 20 74 68 61 74 0a 2a 2a 20 69 73 20 63 6c  n] that.** is cl
174c0 6f 73 65 64 20 6f 72 20 6d 69 67 68 74 20 63 6c  osed or might cl
174d0 6f 73 65 20 62 65 66 6f 72 65 20 73 71 6c 69 74  ose before sqlit
174e0 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 72  e3_interrupt() r
174f0 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49  eturns..**.** ^I
17500 66 20 61 6e 20 53 51 4c 20 6f 70 65 72 61 74 69  f an SQL operati
17510 6f 6e 20 69 73 20 76 65 72 79 20 6e 65 61 72 6c  on is very nearl
17520 79 20 66 69 6e 69 73 68 65 64 20 61 74 20 74 68  y finished at th
17530 65 20 74 69 6d 65 20 77 68 65 6e 0a 2a 2a 20 73  e time when.** s
17540 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
17550 28 29 20 69 73 20 63 61 6c 6c 65 64 2c 20 74 68  () is called, th
17560 65 6e 20 69 74 20 6d 69 67 68 74 20 6e 6f 74 20  en it might not 
17570 68 61 76 65 20 61 6e 20 6f 70 70 6f 72 74 75 6e  have an opportun
17580 69 74 79 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 74  ity.** to be int
17590 65 72 72 75 70 74 65 64 20 61 6e 64 20 6d 69 67  errupted and mig
175a0 68 74 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 63  ht continue to c
175b0 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  ompletion..**.**
175c0 20 5e 41 6e 20 53 51 4c 20 6f 70 65 72 61 74 69   ^An SQL operati
175d0 6f 6e 20 74 68 61 74 20 69 73 20 69 6e 74 65 72  on that is inter
175e0 72 75 70 74 65 64 20 77 69 6c 6c 20 72 65 74 75  rupted will retu
175f0 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52  rn [SQLITE_INTER
17600 52 55 50 54 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68  RUPT]..** ^If th
17610 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 53 51  e interrupted SQ
17620 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 61  L operation is a
17630 6e 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45  n INSERT, UPDATE
17640 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74  , or DELETE.** t
17650 68 61 74 20 69 73 20 69 6e 73 69 64 65 20 61 6e  hat is inside an
17660 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61   explicit transa
17670 63 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20  ction, then the 
17680 65 6e 74 69 72 65 20 74 72 61 6e 73 61 63 74 69  entire transacti
17690 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 72 6f  on.** will be ro
176a0 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f 6d 61  lled back automa
176b0 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e  tically..**.** ^
176c0 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  The sqlite3_inte
176d0 72 72 75 70 74 28 44 29 20 63 61 6c 6c 20 69 73  rrupt(D) call is
176e0 20 69 6e 20 65 66 66 65 63 74 20 75 6e 74 69 6c   in effect until
176f0 20 61 6c 6c 20 63 75 72 72 65 6e 74 6c 79 20 72   all currently r
17700 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74  unning.** SQL st
17710 61 74 65 6d 65 6e 74 73 20 6f 6e 20 5b 64 61 74  atements on [dat
17720 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
17730 5d 20 44 20 63 6f 6d 70 6c 65 74 65 2e 20 20 5e  ] D complete.  ^
17740 41 6e 79 20 6e 65 77 20 53 51 4c 20 73 74 61 74  Any new SQL stat
17750 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61  ements.** that a
17760 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72  re started after
17770 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74   the sqlite3_int
17780 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20 61 6e  errupt() call an
17790 64 20 62 65 66 6f 72 65 20 74 68 65 20 0a 2a 2a  d before the .**
177a0 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65   running stateme
177b0 6e 74 73 20 72 65 61 63 68 65 73 20 7a 65 72 6f  nts reaches zero
177c0 20 61 72 65 20 69 6e 74 65 72 72 75 70 74 65 64   are interrupted
177d0 20 61 73 20 69 66 20 74 68 65 79 20 68 61 64 20   as if they had 
177e0 62 65 65 6e 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20  been.** running 
177f0 70 72 69 6f 72 20 74 6f 20 74 68 65 20 73 71 6c  prior to the sql
17800 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
17810 20 63 61 6c 6c 2e 20 20 5e 4e 65 77 20 53 51 4c   call.  ^New SQL
17820 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74   statements.** t
17830 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20  hat are started 
17840 61 66 74 65 72 20 74 68 65 20 72 75 6e 6e 69 6e  after the runnin
17850 67 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 75 6e  g statement coun
17860 74 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61  t reaches zero a
17870 72 65 0a 2a 2a 20 6e 6f 74 20 65 66 66 65 63 74  re.** not effect
17880 65 64 20 62 79 20 74 68 65 20 73 71 6c 69 74 65  ed by the sqlite
17890 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2e 0a 2a  3_interrupt()..*
178a0 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c  * ^A call to sql
178b0 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 44  ite3_interrupt(D
178c0 29 20 74 68 61 74 20 6f 63 63 75 72 73 20 77 68  ) that occurs wh
178d0 65 6e 20 74 68 65 72 65 20 61 72 65 20 6e 6f 20  en there are no 
178e0 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73  running.** SQL s
178f0 74 61 74 65 6d 65 6e 74 73 20 69 73 20 61 20 6e  tatements is a n
17900 6f 2d 6f 70 20 61 6e 64 20 68 61 73 20 6e 6f 20  o-op and has no 
17910 65 66 66 65 63 74 20 6f 6e 20 53 51 4c 20 73 74  effect on SQL st
17920 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74  atements.** that
17930 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74   are started aft
17940 65 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69  er the sqlite3_i
17950 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20  nterrupt() call 
17960 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49  returns..**.** I
17970 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  f the database c
17980 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73  onnection closes
17990 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f   while [sqlite3_
179a0 69 6e 74 65 72 72 75 70 74 28 29 5d 0a 2a 2a 20  interrupt()].** 
179b0 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20  is running then 
179c0 62 61 64 20 74 68 69 6e 67 73 20 77 69 6c 6c 20  bad things will 
179d0 6c 69 6b 65 6c 79 20 68 61 70 70 65 6e 2e 0a 2a  likely happen..*
179e0 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 69  /.void sqlite3_i
179f0 6e 74 65 72 72 75 70 74 28 73 71 6c 69 74 65 33  nterrupt(sqlite3
17a00 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
17a10 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49  REF: Determine I
17a20 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65  f An SQL Stateme
17a30 6e 74 20 49 73 20 43 6f 6d 70 6c 65 74 65 0a 2a  nt Is Complete.*
17a40 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
17a50 6e 65 73 20 61 72 65 20 75 73 65 66 75 6c 20 64  nes are useful d
17a60 75 72 69 6e 67 20 63 6f 6d 6d 61 6e 64 2d 6c 69  uring command-li
17a70 6e 65 20 69 6e 70 75 74 20 74 6f 20 64 65 74 65  ne input to dete
17a80 72 6d 69 6e 65 20 69 66 20 74 68 65 0a 2a 2a 20  rmine if the.** 
17a90 63 75 72 72 65 6e 74 6c 79 20 65 6e 74 65 72 65  currently entere
17aa0 64 20 74 65 78 74 20 73 65 65 6d 73 20 74 6f 20  d text seems to 
17ab0 66 6f 72 6d 20 61 20 63 6f 6d 70 6c 65 74 65 20  form a complete 
17ac0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 6f 72  SQL statement or
17ad0 0a 2a 2a 20 69 66 20 61 64 64 69 74 69 6f 6e 61  .** if additiona
17ae0 6c 20 69 6e 70 75 74 20 69 73 20 6e 65 65 64 65  l input is neede
17af0 64 20 62 65 66 6f 72 65 20 73 65 6e 64 69 6e 67  d before sending
17b00 20 74 68 65 20 74 65 78 74 20 69 6e 74 6f 0a 2a   the text into.*
17b10 2a 20 53 51 4c 69 74 65 20 66 6f 72 20 70 61 72  * SQLite for par
17b20 73 69 6e 67 2e 20 20 5e 54 68 65 73 65 20 72 6f  sing.  ^These ro
17b30 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 31 20  utines return 1 
17b40 69 66 20 74 68 65 20 69 6e 70 75 74 20 73 74 72  if the input str
17b50 69 6e 67 0a 2a 2a 20 61 70 70 65 61 72 73 20 74  ing.** appears t
17b60 6f 20 62 65 20 61 20 63 6f 6d 70 6c 65 74 65 20  o be a complete 
17b70 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  SQL statement.  
17b80 5e 41 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  ^A statement is 
17b90 6a 75 64 67 65 64 20 74 6f 20 62 65 0a 2a 2a 20  judged to be.** 
17ba0 63 6f 6d 70 6c 65 74 65 20 69 66 20 69 74 20 65  complete if it e
17bb0 6e 64 73 20 77 69 74 68 20 61 20 73 65 6d 69 63  nds with a semic
17bc0 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64 20 69  olon token and i
17bd0 73 20 6e 6f 74 20 61 20 70 72 65 66 69 78 20 6f  s not a prefix o
17be0 66 20 61 0a 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d  f a.** well-form
17bf0 65 64 20 43 52 45 41 54 45 20 54 52 49 47 47 45  ed CREATE TRIGGE
17c00 52 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 53  R statement.  ^S
17c10 65 6d 69 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61  emicolons that a
17c20 72 65 20 65 6d 62 65 64 64 65 64 20 77 69 74 68  re embedded with
17c30 69 6e 0a 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74  in.** string lit
17c40 65 72 61 6c 73 20 6f 72 20 71 75 6f 74 65 64 20  erals or quoted 
17c50 69 64 65 6e 74 69 66 69 65 72 20 6e 61 6d 65 73  identifier names
17c60 20 6f 72 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65   or comments are
17c70 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64   not.** independ
17c80 65 6e 74 20 74 6f 6b 65 6e 73 20 28 74 68 65 79  ent tokens (they
17c90 20 61 72 65 20 70 61 72 74 20 6f 66 20 74 68 65   are part of the
17ca0 20 74 6f 6b 65 6e 20 69 6e 20 77 68 69 63 68 20   token in which 
17cb0 74 68 65 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65  they are.** embe
17cc0 64 64 65 64 29 20 61 6e 64 20 74 68 75 73 20 64  dded) and thus d
17cd0 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 61  o not count as a
17ce0 20 73 74 61 74 65 6d 65 6e 74 20 74 65 72 6d 69   statement termi
17cf0 6e 61 74 6f 72 2e 20 20 5e 57 68 69 74 65 73 70  nator.  ^Whitesp
17d00 61 63 65 0a 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65  ace.** and comme
17d10 6e 74 73 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20  nts that follow 
17d20 74 68 65 20 66 69 6e 61 6c 20 73 65 6d 69 63 6f  the final semico
17d30 6c 6f 6e 20 61 72 65 20 69 67 6e 6f 72 65 64 2e  lon are ignored.
17d40 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
17d50 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 30 20  utines return 0 
17d60 69 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  if the statement
17d70 20 69 73 20 69 6e 63 6f 6d 70 6c 65 74 65 2e 20   is incomplete. 
17d80 20 5e 49 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79   ^If a.** memory
17d90 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c   allocation fail
17da0 73 2c 20 74 68 65 6e 20 53 51 4c 49 54 45 5f 4e  s, then SQLITE_N
17db0 4f 4d 45 4d 20 69 73 20 72 65 74 75 72 6e 65 64  OMEM is returned
17dc0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72  ..**.** ^These r
17dd0 6f 75 74 69 6e 65 73 20 64 6f 20 6e 6f 74 20 70  outines do not p
17de0 61 72 73 65 20 74 68 65 20 53 51 4c 20 73 74 61  arse the SQL sta
17df0 74 65 6d 65 6e 74 73 20 74 68 75 73 0a 2a 2a 20  tements thus.** 
17e00 77 69 6c 6c 20 6e 6f 74 20 64 65 74 65 63 74 20  will not detect 
17e10 73 79 6e 74 61 63 74 69 63 61 6c 6c 79 20 69 6e  syntactically in
17e20 63 6f 72 72 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a  correct SQL..**.
17e30 2a 2a 20 5e 28 49 66 20 53 51 4c 69 74 65 20 68  ** ^(If SQLite h
17e40 61 73 20 6e 6f 74 20 62 65 65 6e 20 69 6e 69 74  as not been init
17e50 69 61 6c 69 7a 65 64 20 75 73 69 6e 67 20 5b 73  ialized using [s
17e60 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
17e70 65 28 29 5d 20 70 72 69 6f 72 20 0a 2a 2a 20 74  e()] prior .** t
17e80 6f 20 69 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74  o invoking sqlit
17e90 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20  e3_complete16() 
17ea0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 69 6e 69  then sqlite3_ini
17eb0 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76  tialize() is inv
17ec0 6f 6b 65 64 0a 2a 2a 20 61 75 74 6f 6d 61 74 69  oked.** automati
17ed0 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 33  cally by sqlite3
17ee0 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 2e 20 20  _complete16().  
17ef0 49 66 20 74 68 61 74 20 69 6e 69 74 69 61 6c 69  If that initiali
17f00 7a 61 74 69 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a  zation fails,.**
17f10 20 74 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e   then the return
17f20 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69   value from sqli
17f30 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29  te3_complete16()
17f40 20 77 69 6c 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72   will be non-zer
17f50 6f 0a 2a 2a 20 72 65 67 61 72 64 6c 65 73 73 20  o.** regardless 
17f60 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  of whether or no
17f70 74 20 74 68 65 20 69 6e 70 75 74 20 53 51 4c 20  t the input SQL 
17f80 69 73 20 63 6f 6d 70 6c 65 74 65 2e 29 5e 0a 2a  is complete.)^.*
17f90 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74  *.** The input t
17fa0 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  o [sqlite3_compl
17fb0 65 74 65 28 29 5d 20 6d 75 73 74 20 62 65 20 61  ete()] must be a
17fc0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
17fd0 0a 2a 2a 20 55 54 46 2d 38 20 73 74 72 69 6e 67  .** UTF-8 string
17fe0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75  ..**.** The inpu
17ff0 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  t to [sqlite3_co
18000 6d 70 6c 65 74 65 31 36 28 29 5d 20 6d 75 73 74  mplete16()] must
18010 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69   be a zero-termi
18020 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20  nated.** UTF-16 
18030 73 74 72 69 6e 67 20 69 6e 20 6e 61 74 69 76 65  string in native
18040 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a   byte order..*/.
18050 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  int sqlite3_comp
18060 6c 65 74 65 28 63 6f 6e 73 74 20 63 68 61 72 20  lete(const char 
18070 2a 73 71 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74  *sql);.int sqlit
18080 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 63 6f  e3_complete16(co
18090 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 29 3b 0a  nst void *sql);.
180a0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
180b0 20 52 65 67 69 73 74 65 72 20 41 20 43 61 6c 6c   Register A Call
180c0 62 61 63 6b 20 54 6f 20 48 61 6e 64 6c 65 20 53  back To Handle S
180d0 51 4c 49 54 45 5f 42 55 53 59 20 45 72 72 6f 72  QLITE_BUSY Error
180e0 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f  s.**.** ^This ro
180f0 75 74 69 6e 65 20 73 65 74 73 20 61 20 63 61 6c  utine sets a cal
18100 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 74  lback function t
18110 68 61 74 20 6d 69 67 68 74 20 62 65 20 69 6e 76  hat might be inv
18120 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 0a 2a 2a  oked whenever.**
18130 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 20 6d   an attempt is m
18140 61 64 65 20 74 6f 20 6f 70 65 6e 20 61 20 64 61  ade to open a da
18150 74 61 62 61 73 65 20 74 61 62 6c 65 20 74 68 61  tabase table tha
18160 74 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64  t another thread
18170 0a 2a 2a 20 6f 72 20 70 72 6f 63 65 73 73 20 68  .** or process h
18180 61 73 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 0a 2a 2a  as locked..**.**
18190 20 5e 49 66 20 74 68 65 20 62 75 73 79 20 63 61   ^If the busy ca
181a0 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20  llback is NULL, 
181b0 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53  then [SQLITE_BUS
181c0 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f  Y] or [SQLITE_IO
181d0 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20  ERR_BLOCKED].** 
181e0 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65  is returned imme
181f0 64 69 61 74 65 6c 79 20 75 70 6f 6e 20 65 6e 63  diately upon enc
18200 6f 75 6e 74 65 72 69 6e 67 20 74 68 65 20 6c 6f  ountering the lo
18210 63 6b 2e 20 20 5e 49 66 20 74 68 65 20 62 75 73  ck.  ^If the bus
18220 79 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73  y callback.** is
18230 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20   not NULL, then 
18240 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 6d 69 67  the callback mig
18250 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69  ht be invoked wi
18260 74 68 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73  th two arguments
18270 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72  ..**.** ^The fir
18280 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
18290 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  he busy handler 
182a0 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  is a copy of the
182b0 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72 20 77   void* pointer w
182c0 68 69 63 68 0a 2a 2a 20 69 73 20 74 68 65 20 74  hich.** is the t
182d0 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  hird argument to
182e0 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61   sqlite3_busy_ha
182f0 6e 64 6c 65 72 28 29 2e 20 20 5e 54 68 65 20 73  ndler().  ^The s
18300 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  econd argument t
18310 6f 0a 2a 2a 20 74 68 65 20 62 75 73 79 20 68 61  o.** the busy ha
18320 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  ndler callback i
18330 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
18340 74 69 6d 65 73 20 74 68 61 74 20 74 68 65 20 62  times that the b
18350 75 73 79 20 68 61 6e 64 6c 65 72 20 68 61 73 0a  usy handler has.
18360 2a 2a 20 62 65 65 6e 20 69 6e 76 6f 6b 65 64 20  ** been invoked 
18370 66 6f 72 20 74 68 69 73 20 6c 6f 63 6b 69 6e 67  for this locking
18380 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65   event.  ^If the
18390 0a 2a 2a 20 62 75 73 79 20 63 61 6c 6c 62 61 63  .** busy callbac
183a0 6b 20 72 65 74 75 72 6e 73 20 30 2c 20 74 68 65  k returns 0, the
183b0 6e 20 6e 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20  n no additional 
183c0 61 74 74 65 6d 70 74 73 20 61 72 65 20 6d 61 64  attempts are mad
183d0 65 20 74 6f 0a 2a 2a 20 61 63 63 65 73 73 20 74  e to.** access t
183e0 68 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 20  he database and 
183f0 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72  [SQLITE_BUSY] or
18400 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42   [SQLITE_IOERR_B
18410 4c 4f 43 4b 45 44 5d 20 69 73 20 72 65 74 75 72  LOCKED] is retur
18420 6e 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ned..** ^If the 
18430 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
18440 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20   non-zero, then 
18450 61 6e 6f 74 68 65 72 20 61 74 74 65 6d 70 74 0a  another attempt.
18460 2a 2a 20 69 73 20 6d 61 64 65 20 74 6f 20 6f 70  ** is made to op
18470 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
18480 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20  for reading and 
18490 74 68 65 20 63 79 63 6c 65 20 72 65 70 65 61 74  the cycle repeat
184a0 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65  s..**.** The pre
184b0 73 65 6e 63 65 20 6f 66 20 61 20 62 75 73 79 20  sence of a busy 
184c0 68 61 6e 64 6c 65 72 20 64 6f 65 73 20 6e 6f 74  handler does not
184d0 20 67 75 61 72 61 6e 74 65 65 20 74 68 61 74 20   guarantee that 
184e0 69 74 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b  it will be invok
184f0 65 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65 72 65  ed.** when there
18500 20 69 73 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74   is lock content
18510 69 6f 6e 2e 20 5e 49 66 20 53 51 4c 69 74 65 20  ion. ^If SQLite 
18520 64 65 74 65 72 6d 69 6e 65 73 20 74 68 61 74 20  determines that 
18530 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73  invoking the bus
18540 79 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 63 6f 75  y.** handler cou
18550 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61 20 64  ld result in a d
18560 65 61 64 6c 6f 63 6b 2c 20 69 74 20 77 69 6c 6c  eadlock, it will
18570 20 67 6f 20 61 68 65 61 64 20 61 6e 64 20 72 65   go ahead and re
18580 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53  turn [SQLITE_BUS
18590 59 5d 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45  Y].** or [SQLITE
185a0 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20  _IOERR_BLOCKED] 
185b0 69 6e 73 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b  instead of invok
185c0 69 6e 67 20 74 68 65 20 62 75 73 79 20 68 61 6e  ing the busy han
185d0 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65  dler..** Conside
185e0 72 20 61 20 73 63 65 6e 61 72 69 6f 20 77 68 65  r a scenario whe
185f0 72 65 20 6f 6e 65 20 70 72 6f 63 65 73 73 20 69  re one process i
18600 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 61 64  s holding a read
18610 20 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a 20 69 74   lock that.** it
18620 20 69 73 20 74 72 79 69 6e 67 20 74 6f 20 70 72   is trying to pr
18630 6f 6d 6f 74 65 20 74 6f 20 61 20 72 65 73 65 72  omote to a reser
18640 76 65 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20  ved lock and.** 
18650 61 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73  a second process
18660 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65   is holding a re
18670 73 65 72 76 65 64 20 6c 6f 63 6b 20 74 68 61 74  served lock that
18680 20 69 74 20 69 73 20 74 72 79 69 6e 67 0a 2a 2a   it is trying.**
18690 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61   to promote to a
186a0 6e 20 65 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b  n exclusive lock
186b0 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 72 6f  .  The first pro
186c0 63 65 73 73 20 63 61 6e 6e 6f 74 20 70 72 6f 63  cess cannot proc
186d0 65 65 64 0a 2a 2a 20 62 65 63 61 75 73 65 20 69  eed.** because i
186e0 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20  t is blocked by 
186f0 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74  the second and t
18700 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73  he second proces
18710 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63  s cannot.** proc
18720 65 65 64 20 62 65 63 61 75 73 65 20 69 74 20 69  eed because it i
18730 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65  s blocked by the
18740 20 66 69 72 73 74 2e 20 20 49 66 20 62 6f 74 68   first.  If both
18750 20 70 72 6f 63 65 73 73 65 73 0a 2a 2a 20 69 6e   processes.** in
18760 76 6f 6b 65 20 74 68 65 20 62 75 73 79 20 68 61  voke the busy ha
18770 6e 64 6c 65 72 73 2c 20 6e 65 69 74 68 65 72 20  ndlers, neither 
18780 77 69 6c 6c 20 6d 61 6b 65 20 61 6e 79 20 70 72  will make any pr
18790 6f 67 72 65 73 73 2e 20 20 54 68 65 72 65 66 6f  ogress.  Therefo
187a0 72 65 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 72 65  re,.** SQLite re
187b0 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55  turns [SQLITE_BU
187c0 53 59 5d 20 66 6f 72 20 74 68 65 20 66 69 72 73  SY] for the firs
187d0 74 20 70 72 6f 63 65 73 73 2c 20 68 6f 70 69 6e  t process, hopin
187e0 67 20 74 68 61 74 20 74 68 69 73 0a 2a 2a 20 77  g that this.** w
187f0 69 6c 6c 20 69 6e 64 75 63 65 20 74 68 65 20 66  ill induce the f
18800 69 72 73 74 20 70 72 6f 63 65 73 73 20 74 6f 20  irst process to 
18810 72 65 6c 65 61 73 65 20 69 74 73 20 72 65 61 64  release its read
18820 20 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a   lock and allow.
18830 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72  ** the second pr
18840 6f 63 65 73 73 20 74 6f 20 70 72 6f 63 65 65 64  ocess to proceed
18850 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66  ..**.** ^The def
18860 61 75 6c 74 20 62 75 73 79 20 63 61 6c 6c 62 61  ault busy callba
18870 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  ck is NULL..**.*
18880 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 42  * ^The [SQLITE_B
18890 55 53 59 5d 20 65 72 72 6f 72 20 69 73 20 63 6f  USY] error is co
188a0 6e 76 65 72 74 65 64 20 74 6f 20 5b 53 51 4c 49  nverted to [SQLI
188b0 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44  TE_IOERR_BLOCKED
188c0 5d 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74 65  ].** when SQLite
188d0 20 69 73 20 69 6e 20 74 68 65 20 6d 69 64 64 6c   is in the middl
188e0 65 20 6f 66 20 61 20 6c 61 72 67 65 20 74 72 61  e of a large tra
188f0 6e 73 61 63 74 69 6f 6e 20 77 68 65 72 65 20 61  nsaction where a
18900 6c 6c 20 74 68 65 0a 2a 2a 20 63 68 61 6e 67 65  ll the.** change
18910 73 20 77 69 6c 6c 20 6e 6f 74 20 66 69 74 20 69  s will not fit i
18920 6e 74 6f 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72  nto the in-memor
18930 79 20 63 61 63 68 65 2e 20 20 53 51 4c 69 74 65  y cache.  SQLite
18940 20 77 69 6c 6c 0a 2a 2a 20 61 6c 72 65 61 64 79   will.** already
18950 20 68 6f 6c 64 20 61 20 52 45 53 45 52 56 45 44   hold a RESERVED
18960 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 64 61 74   lock on the dat
18970 61 62 61 73 65 20 66 69 6c 65 2c 20 62 75 74 20  abase file, but 
18980 69 74 20 6e 65 65 64 73 0a 2a 2a 20 74 6f 20 70  it needs.** to p
18990 72 6f 6d 6f 74 65 20 74 68 69 73 20 6c 6f 63 6b  romote this lock
189a0 20 74 6f 20 45 58 43 4c 55 53 49 56 45 20 73 6f   to EXCLUSIVE so
189b0 20 74 68 61 74 20 69 74 20 63 61 6e 20 73 70 69   that it can spi
189c0 6c 6c 20 63 61 63 68 65 0a 2a 2a 20 70 61 67 65  ll cache.** page
189d0 73 20 69 6e 74 6f 20 74 68 65 20 64 61 74 61 62  s into the datab
189e0 61 73 65 20 66 69 6c 65 20 77 69 74 68 6f 75 74  ase file without
189f0 20 68 61 72 6d 20 74 6f 20 63 6f 6e 63 75 72 72   harm to concurr
18a00 65 6e 74 0a 2a 2a 20 72 65 61 64 65 72 73 2e 20  ent.** readers. 
18a10 20 5e 49 66 20 69 74 20 69 73 20 75 6e 61 62 6c   ^If it is unabl
18a20 65 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68 65  e to promote the
18a30 20 6c 6f 63 6b 2c 20 74 68 65 6e 20 74 68 65 20   lock, then the 
18a40 69 6e 2d 6d 65 6d 6f 72 79 0a 2a 2a 20 63 61 63  in-memory.** cac
18a50 68 65 20 77 69 6c 6c 20 62 65 20 6c 65 66 74 20  he will be left 
18a60 69 6e 20 61 6e 20 69 6e 63 6f 6e 73 69 73 74 65  in an inconsiste
18a70 6e 74 20 73 74 61 74 65 20 61 6e 64 20 73 6f 20  nt state and so 
18a80 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 63 6f 64  the error.** cod
18a90 65 20 69 73 20 70 72 6f 6d 6f 74 65 64 20 66 72  e is promoted fr
18aa0 6f 6d 20 74 68 65 20 72 65 6c 61 74 69 76 65 6c  om the relativel
18ab0 79 20 62 65 6e 69 67 6e 20 5b 53 51 4c 49 54 45  y benign [SQLITE
18ac0 5f 42 55 53 59 5d 20 74 6f 0a 2a 2a 20 74 68 65  _BUSY] to.** the
18ad0 20 6d 6f 72 65 20 73 65 76 65 72 65 20 5b 53 51   more severe [SQ
18ae0 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b  LITE_IOERR_BLOCK
18af0 45 44 5d 2e 20 20 5e 54 68 69 73 20 65 72 72 6f  ED].  ^This erro
18b00 72 20 63 6f 64 65 20 70 72 6f 6d 6f 74 69 6f 6e  r code promotion
18b10 0a 2a 2a 20 66 6f 72 63 65 73 20 61 6e 20 61 75  .** forces an au
18b20 74 6f 6d 61 74 69 63 20 72 6f 6c 6c 62 61 63 6b  tomatic rollback
18b30 20 6f 66 20 74 68 65 20 63 68 61 6e 67 65 73 2e   of the changes.
18b40 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 3c 61 20    See the.** <a 
18b50 68 72 65 66 3d 22 2f 63 76 73 74 72 61 63 2f 77  href="/cvstrac/w
18b60 69 6b 69 3f 70 3d 43 6f 72 72 75 70 74 69 6f 6e  iki?p=Corruption
18b70 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72 72  FollowingBusyErr
18b80 6f 72 22 3e 0a 2a 2a 20 43 6f 72 72 75 70 74 69  or">.** Corrupti
18b90 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45  onFollowingBusyE
18ba0 72 72 6f 72 3c 2f 61 3e 20 77 69 6b 69 20 70 61  rror</a> wiki pa
18bb0 67 65 20 66 6f 72 20 61 20 64 69 73 63 75 73 73  ge for a discuss
18bc0 69 6f 6e 20 6f 66 20 77 68 79 0a 2a 2a 20 74 68  ion of why.** th
18bd0 69 73 20 69 73 20 69 6d 70 6f 72 74 61 6e 74 2e  is is important.
18be0 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63  .**.** ^(There c
18bf0 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e  an only be a sin
18c00 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  gle busy handler
18c10 20 64 65 66 69 6e 65 64 20 66 6f 72 20 65 61 63   defined for eac
18c20 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  h.** [database c
18c30 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 53 65 74  onnection].  Set
18c40 74 69 6e 67 20 61 20 6e 65 77 20 62 75 73 79 20  ting a new busy 
18c50 68 61 6e 64 6c 65 72 20 63 6c 65 61 72 73 20 61  handler clears a
18c60 6e 79 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79  ny.** previously
18c70 20 73 65 74 20 68 61 6e 64 6c 65 72 2e 29 5e 20   set handler.)^ 
18c80 20 5e 4e 6f 74 65 20 74 68 61 74 20 63 61 6c 6c   ^Note that call
18c90 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73  ing [sqlite3_bus
18ca0 79 5f 74 69 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20  y_timeout()].** 
18cb0 77 69 6c 6c 20 61 6c 73 6f 20 73 65 74 20 6f 72  will also set or
18cc0 20 63 6c 65 61 72 20 74 68 65 20 62 75 73 79 20   clear the busy 
18cd0 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 54  handler..**.** T
18ce0 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b  he busy callback
18cf0 20 73 68 6f 75 6c 64 20 6e 6f 74 20 74 61 6b 65   should not take
18d00 20 61 6e 79 20 61 63 74 69 6f 6e 73 20 77 68 69   any actions whi
18d10 63 68 20 6d 6f 64 69 66 79 20 74 68 65 0a 2a 2a  ch modify the.**
18d20 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
18d30 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65  tion that invoke
18d40 64 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  d the busy handl
18d50 65 72 2e 20 20 41 6e 79 20 73 75 63 68 20 61 63  er.  Any such ac
18d60 74 69 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c 74 20  tions.** result 
18d70 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68  in undefined beh
18d80 61 76 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20 41 20  avior..** .** A 
18d90 62 75 73 79 20 68 61 6e 64 6c 65 72 20 6d 75 73  busy handler mus
18da0 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20  t not close the 
18db0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
18dc0 69 6f 6e 0a 2a 2a 20 6f 72 20 5b 70 72 65 70 61  ion.** or [prepa
18dd0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74  red statement] t
18de0 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20  hat invoked the 
18df0 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f  busy handler..*/
18e00 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73  .int sqlite3_bus
18e10 79 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65  y_handler(sqlite
18e20 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a  3*, int(*)(void*
18e30 2c 69 6e 74 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a  ,int), void*);..
18e40 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
18e50 53 65 74 20 41 20 42 75 73 79 20 54 69 6d 65 6f  Set A Busy Timeo
18e60 75 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72  ut.**.** ^This r
18e70 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20 5b 73  outine sets a [s
18e80 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64  qlite3_busy_hand
18e90 6c 65 72 20 7c 20 62 75 73 79 20 68 61 6e 64 6c  ler | busy handl
18ea0 65 72 5d 20 74 68 61 74 20 73 6c 65 65 70 73 0a  er] that sleeps.
18eb0 2a 2a 20 66 6f 72 20 61 20 73 70 65 63 69 66 69  ** for a specifi
18ec0 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 74 69 6d  ed amount of tim
18ed0 65 20 77 68 65 6e 20 61 20 74 61 62 6c 65 20 69  e when a table i
18ee0 73 20 6c 6f 63 6b 65 64 2e 20 20 5e 54 68 65 20  s locked.  ^The 
18ef0 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20  handler.** will 
18f00 73 6c 65 65 70 20 6d 75 6c 74 69 70 6c 65 20 74  sleep multiple t
18f10 69 6d 65 73 20 75 6e 74 69 6c 20 61 74 20 6c 65  imes until at le
18f20 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65  ast "ms" millise
18f30 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e  conds of sleepin
18f40 67 0a 2a 2a 20 68 61 76 65 20 61 63 63 75 6d 75  g.** have accumu
18f50 6c 61 74 65 64 2e 20 20 5e 41 66 74 65 72 20 61  lated.  ^After a
18f60 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c  t least "ms" mil
18f70 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65  liseconds of sle
18f80 65 70 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 68 61  eping,.** the ha
18f90 6e 64 6c 65 72 20 72 65 74 75 72 6e 73 20 30 20  ndler returns 0 
18fa0 77 68 69 63 68 20 63 61 75 73 65 73 20 5b 73 71  which causes [sq
18fb0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 74 6f  lite3_step()] to
18fc0 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49   return.** [SQLI
18fd0 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c  TE_BUSY] or [SQL
18fe0 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45  ITE_IOERR_BLOCKE
18ff0 44 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69  D]..**.** ^Calli
19000 6e 67 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  ng this routine 
19010 77 69 74 68 20 61 6e 20 61 72 67 75 6d 65 6e 74  with an argument
19020 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71   less than or eq
19030 75 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74  ual to zero.** t
19040 75 72 6e 73 20 6f 66 66 20 61 6c 6c 20 62 75 73  urns off all bus
19050 79 20 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a  y handlers..**.*
19060 2a 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e  * ^(There can on
19070 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62  ly be a single b
19080 75 73 79 20 68 61 6e 64 6c 65 72 20 66 6f 72 20  usy handler for 
19090 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20  a particular.** 
190a0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
190b0 74 69 6f 6e 5d 20 61 6e 79 20 61 6e 79 20 67 69  tion] any any gi
190c0 76 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49 66 20  ven moment.  If 
190d0 61 6e 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e  another busy han
190e0 64 6c 65 72 0a 2a 2a 20 77 61 73 20 64 65 66 69  dler.** was defi
190f0 6e 65 64 20 20 28 75 73 69 6e 67 20 5b 73 71 6c  ned  (using [sql
19100 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
19110 72 28 29 5d 29 20 70 72 69 6f 72 20 74 6f 20 63  r()]) prior to c
19120 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69 73 20 72  alling.** this r
19130 6f 75 74 69 6e 65 2c 20 74 68 61 74 20 6f 74 68  outine, that oth
19140 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  er busy handler 
19150 69 73 20 63 6c 65 61 72 65 64 2e 29 5e 0a 2a 2f  is cleared.)^.*/
19160 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73  .int sqlite3_bus
19170 79 5f 74 69 6d 65 6f 75 74 28 73 71 6c 69 74 65  y_timeout(sqlite
19180 33 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a  3*, int ms);../*
19190 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
191a0 6e 76 65 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e  nvenience Routin
191b0 65 73 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51  es For Running Q
191c0 75 65 72 69 65 73 0a 2a 2a 0a 2a 2a 20 54 68 69  ueries.**.** Thi
191d0 73 20 69 73 20 61 20 6c 65 67 61 63 79 20 69 6e  s is a legacy in
191e0 74 65 72 66 61 63 65 20 74 68 61 74 20 69 73 20  terface that is 
191f0 70 72 65 73 65 72 76 65 64 20 66 6f 72 20 62 61  preserved for ba
19200 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62  ckwards compatib
19210 69 6c 69 74 79 2e 0a 2a 2a 20 55 73 65 20 6f 66  ility..** Use of
19220 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   this interface 
19230 69 73 20 6e 6f 74 20 72 65 63 6f 6d 6d 65 6e 64  is not recommend
19240 65 64 2e 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69  ed..**.** Defini
19250 74 69 6f 6e 3a 20 41 20 3c 62 3e 72 65 73 75 6c  tion: A <b>resul
19260 74 20 74 61 62 6c 65 3c 2f 62 3e 20 69 73 20 6d  t table</b> is m
19270 65 6d 6f 72 79 20 64 61 74 61 20 73 74 72 75 63  emory data struc
19280 74 75 72 65 20 63 72 65 61 74 65 64 20 62 79 20  ture created by 
19290 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
192a0 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 69 6e 74  get_table()] int
192b0 65 72 66 61 63 65 2e 20 20 41 20 72 65 73 75 6c  erface.  A resul
192c0 74 20 74 61 62 6c 65 20 72 65 63 6f 72 64 73 20  t table records 
192d0 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20  the.** complete 
192e0 71 75 65 72 79 20 72 65 73 75 6c 74 73 20 66 72  query results fr
192f0 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 71  om one or more q
19300 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  ueries..**.** Th
19310 65 20 74 61 62 6c 65 20 63 6f 6e 63 65 70 74 75  e table conceptu
19320 61 6c 6c 79 20 68 61 73 20 61 20 6e 75 6d 62 65  ally has a numbe
19330 72 20 6f 66 20 72 6f 77 73 20 61 6e 64 20 63 6f  r of rows and co
19340 6c 75 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a 20 74  lumns.  But.** t
19350 68 65 73 65 20 6e 75 6d 62 65 72 73 20 61 72 65  hese numbers are
19360 20 6e 6f 74 20 70 61 72 74 20 6f 66 20 74 68 65   not part of the
19370 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 74   result table it
19380 73 65 6c 66 2e 20 20 54 68 65 73 65 0a 2a 2a 20  self.  These.** 
19390 6e 75 6d 62 65 72 73 20 61 72 65 20 6f 62 74 61  numbers are obta
193a0 69 6e 65 64 20 73 65 70 61 72 61 74 65 6c 79 2e  ined separately.
193b0 20 20 4c 65 74 20 4e 20 62 65 20 74 68 65 20 6e    Let N be the n
193c0 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 0a 2a 2a  umber of rows.**
193d0 20 61 6e 64 20 4d 20 62 65 20 74 68 65 20 6e 75   and M be the nu
193e0 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e  mber of columns.
193f0 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20  .**.** A result 
19400 74 61 62 6c 65 20 69 73 20 61 6e 20 61 72 72 61  table is an arra
19410 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f  y of pointers to
19420 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
19430 20 55 54 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a   UTF-8 strings..
19440 2a 2a 20 54 68 65 72 65 20 61 72 65 20 28 4e 2b  ** There are (N+
19450 31 29 2a 4d 20 65 6c 65 6d 65 6e 74 73 20 69 6e  1)*M elements in
19460 20 74 68 65 20 61 72 72 61 79 2e 20 20 54 68 65   the array.  The
19470 20 66 69 72 73 74 20 4d 20 70 6f 69 6e 74 65 72   first M pointer
19480 73 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65  s point.** to ze
19490 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74  ro-terminated st
194a0 72 69 6e 67 73 20 74 68 61 74 20 20 63 6f 6e 74  rings that  cont
194b0 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f 66  ain the names of
194c0 20 74 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a   the columns..**
194d0 20 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 65   The remaining e
194e0 6e 74 72 69 65 73 20 61 6c 6c 20 70 6f 69 6e 74  ntries all point
194f0 20 74 6f 20 71 75 65 72 79 20 72 65 73 75 6c 74   to query result
19500 73 2e 20 20 4e 55 4c 4c 20 76 61 6c 75 65 73 20  s.  NULL values 
19510 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c  result.** in NUL
19520 4c 20 70 6f 69 6e 74 65 72 73 2e 20 20 41 6c 6c  L pointers.  All
19530 20 6f 74 68 65 72 20 76 61 6c 75 65 73 20 61 72   other values ar
19540 65 20 69 6e 20 74 68 65 69 72 20 55 54 46 2d 38  e in their UTF-8
19550 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
19560 0a 2a 2a 20 73 74 72 69 6e 67 20 72 65 70 72 65  .** string repre
19570 73 65 6e 74 61 74 69 6f 6e 20 61 73 20 72 65 74  sentation as ret
19580 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65  urned by [sqlite
19590 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d  3_column_text()]
195a0 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74  ..**.** A result
195b0 20 74 61 62 6c 65 20 6d 69 67 68 74 20 63 6f 6e   table might con
195c0 73 69 73 74 20 6f 66 20 6f 6e 65 20 6f 72 20 6d  sist of one or m
195d0 6f 72 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ore memory alloc
195e0 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69 73  ations..** It is
195f0 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 70 61 73   not safe to pas
19600 73 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65  s a result table
19610 20 64 69 72 65 63 74 6c 79 20 74 6f 20 5b 73 71   directly to [sq
19620 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a  lite3_free()]..*
19630 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65  * A result table
19640 20 73 68 6f 75 6c 64 20 62 65 20 64 65 61 6c 6c   should be deall
19650 6f 63 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71  ocated using [sq
19660 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65  lite3_free_table
19670 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 73 20  ()]..**.** ^(As 
19680 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 74 68  an example of th
19690 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 66  e result table f
196a0 6f 72 6d 61 74 2c 20 73 75 70 70 6f 73 65 20 61  ormat, suppose a
196b0 20 71 75 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a   query result.**
196c0 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a   is as follows:.
196d0 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
196e0 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20  e><pre>.**      
196f0 20 20 4e 61 6d 65 20 20 20 20 20 20 20 20 7c 20    Name        | 
19700 41 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 2d 2d  Age.**        --
19710 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
19720 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 20  -----.**        
19730 41 6c 69 63 65 20 20 20 20 20 20 20 7c 20 34 33  Alice       | 43
19740 0a 2a 2a 20 20 20 20 20 20 20 20 42 6f 62 20 20  .**        Bob  
19750 20 20 20 20 20 20 20 7c 20 32 38 0a 2a 2a 20 20         | 28.**  
19760 20 20 20 20 20 20 43 69 6e 64 79 20 20 20 20 20        Cindy     
19770 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e    | 21.** </pre>
19780 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
19790 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74 77  .** There are tw
197a0 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20  o column (M==2) 
197b0 61 6e 64 20 74 68 72 65 65 20 72 6f 77 73 20 28  and three rows (
197c0 4e 3d 3d 33 29 2e 20 20 54 68 75 73 20 74 68 65  N==3).  Thus the
197d0 0a 2a 2a 20 72 65 73 75 6c 74 20 74 61 62 6c 65  .** result table
197e0 20 68 61 73 20 38 20 65 6e 74 72 69 65 73 2e 20   has 8 entries. 
197f0 20 53 75 70 70 6f 73 65 20 74 68 65 20 72 65 73   Suppose the res
19800 75 6c 74 20 74 61 62 6c 65 20 69 73 20 73 74 6f  ult table is sto
19810 72 65 64 0a 2a 2a 20 69 6e 20 61 6e 20 61 72 72  red.** in an arr
19820 61 79 20 6e 61 6d 65 73 20 61 7a 52 65 73 75 6c  ay names azResul
19830 74 2e 20 20 54 68 65 6e 20 61 7a 52 65 73 75 6c  t.  Then azResul
19840 74 20 68 6f 6c 64 73 20 74 68 69 73 20 63 6f 6e  t holds this con
19850 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  tent:.**.** <blo
19860 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
19870 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
19880 26 23 39 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 22  &#91;0] = "Name"
19890 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
198a0 73 75 6c 74 26 23 39 31 3b 31 5d 20 3d 20 22 41  sult&#91;1] = "A
198b0 67 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  ge";.**        a
198c0 7a 52 65 73 75 6c 74 26 23 39 31 3b 32 5d 20 3d  zResult&#91;2] =
198d0 20 22 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 20   "Alice";.**    
198e0 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
198f0 3b 33 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20  ;3] = "43";.**  
19900 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
19910 39 31 3b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a  91;4] = "Bob";.*
19920 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
19930 74 26 23 39 31 3b 35 5d 20 3d 20 22 32 38 22 3b  t&#91;5] = "28";
19940 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
19950 75 6c 74 26 23 39 31 3b 36 5d 20 3d 20 22 43 69  ult&#91;6] = "Ci
19960 6e 64 79 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  ndy";.**        
19970 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 37 5d 20  azResult&#91;7] 
19980 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65  = "21";.** </pre
19990 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e  ></blockquote>)^
199a0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
199b0 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20  te3_get_table() 
199c0 66 75 6e 63 74 69 6f 6e 20 65 76 61 6c 75 61 74  function evaluat
199d0 65 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a  es one or more.*
199e0 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61  * semicolon-sepa
199f0 72 61 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d  rated SQL statem
19a00 65 6e 74 73 20 69 6e 20 74 68 65 20 7a 65 72 6f  ents in the zero
19a10 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d  -terminated UTF-
19a20 38 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 66 20 69  8.** string of i
19a30 74 73 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  ts 2nd parameter
19a40 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 72   and returns a r
19a50 65 73 75 6c 74 20 74 61 62 6c 65 20 74 6f 20 74  esult table to t
19a60 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 67 69  he.** pointer gi
19a70 76 65 6e 20 69 6e 20 69 74 73 20 33 72 64 20 70  ven in its 3rd p
19a80 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  arameter..**.** 
19a90 41 66 74 65 72 20 74 68 65 20 61 70 70 6c 69 63  After the applic
19aa0 61 74 69 6f 6e 20 68 61 73 20 66 69 6e 69 73 68  ation has finish
19ab0 65 64 20 77 69 74 68 20 74 68 65 20 72 65 73 75  ed with the resu
19ac0 6c 74 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  lt from sqlite3_
19ad0 67 65 74 5f 74 61 62 6c 65 28 29 2c 0a 2a 2a 20  get_table(),.** 
19ae0 69 74 20 6d 75 73 74 20 70 61 73 73 20 74 68 65  it must pass the
19af0 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 70 6f   result table po
19b00 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  inter to sqlite3
19b10 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 20 69 6e  _free_table() in
19b20 20 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 72 65 6c   order to.** rel
19b30 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20  ease the memory 
19b40 74 68 61 74 20 77 61 73 20 6d 61 6c 6c 6f 63 65  that was malloce
19b50 64 2e 20 20 42 65 63 61 75 73 65 20 6f 66 20 74  d.  Because of t
19b60 68 65 20 77 61 79 20 74 68 65 0a 2a 2a 20 5b 73  he way the.** [s
19b70 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
19b80 20 68 61 70 70 65 6e 73 20 77 69 74 68 69 6e 20   happens within 
19b90 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
19ba0 65 28 29 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67  e(), the calling
19bb0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73  .** function mus
19bc0 74 20 6e 6f 74 20 74 72 79 20 74 6f 20 63 61 6c  t not try to cal
19bd0 6c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  l [sqlite3_free(
19be0 29 5d 20 64 69 72 65 63 74 6c 79 2e 20 20 4f 6e  )] directly.  On
19bf0 6c 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  ly.** [sqlite3_f
19c00 72 65 65 5f 74 61 62 6c 65 28 29 5d 20 69 73 20  ree_table()] is 
19c10 61 62 6c 65 20 74 6f 20 72 65 6c 65 61 73 65 20  able to release 
19c20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 70 65  the memory prope
19c30 72 6c 79 20 61 6e 64 20 73 61 66 65 6c 79 2e 0a  rly and safely..
19c40 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
19c50 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 69 6e  3_get_table() in
19c60 74 65 72 66 61 63 65 20 69 73 20 69 6d 70 6c 65  terface is imple
19c70 6d 65 6e 74 65 64 20 61 73 20 61 20 77 72 61 70  mented as a wrap
19c80 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73  per around.** [s
19c90 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2e 20  qlite3_exec()]. 
19ca0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74   The sqlite3_get
19cb0 5f 74 61 62 6c 65 28 29 20 72 6f 75 74 69 6e 65  _table() routine
19cc0 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 61   does not have a
19cd0 63 63 65 73 73 0a 2a 2a 20 74 6f 20 61 6e 79 20  ccess.** to any 
19ce0 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 20 73 74  internal data st
19cf0 72 75 63 74 75 72 65 73 20 6f 66 20 53 51 4c 69  ructures of SQLi
19d00 74 65 2e 20 20 49 74 20 75 73 65 73 20 6f 6e 6c  te.  It uses onl
19d10 79 20 74 68 65 20 70 75 62 6c 69 63 0a 2a 2a 20  y the public.** 
19d20 69 6e 74 65 72 66 61 63 65 20 64 65 66 69 6e 65  interface define
19d30 64 20 68 65 72 65 2e 20 20 41 73 20 61 20 63 6f  d here.  As a co
19d40 6e 73 65 71 75 65 6e 63 65 2c 20 65 72 72 6f 72  nsequence, error
19d50 73 20 74 68 61 74 20 6f 63 63 75 72 20 69 6e 20  s that occur in 
19d60 74 68 65 0a 2a 2a 20 77 72 61 70 70 65 72 20 6c  the.** wrapper l
19d70 61 79 65 72 20 6f 75 74 73 69 64 65 20 6f 66 20  ayer outside of 
19d80 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 5b 73 71  the internal [sq
19d90 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 63 61  lite3_exec()] ca
19da0 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65  ll are not.** re
19db0 66 6c 65 63 74 65 64 20 69 6e 20 73 75 62 73 65  flected in subse
19dc0 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b  quent calls to [
19dd0 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
19de0 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  )] or.** [sqlite
19df0 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2f 0a  3_errmsg()]..*/.
19e00 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  int sqlite3_get_
19e10 74 61 62 6c 65 28 0a 20 20 73 71 6c 69 74 65 33  table(.  sqlite3
19e20 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 2f   *db,          /
19e30 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61  * An open databa
19e40 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  se */.  const ch
19e50 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 2f 2a  ar *zSql,     /*
19e60 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75   SQL to be evalu
19e70 61 74 65 64 20 2a 2f 0a 20 20 63 68 61 72 20 2a  ated */.  char *
19e80 2a 2a 70 61 7a 52 65 73 75 6c 74 2c 20 20 20 20  **pazResult,    
19e90 2f 2a 20 52 65 73 75 6c 74 73 20 6f 66 20 74 68  /* Results of th
19ea0 65 20 71 75 65 72 79 20 2a 2f 0a 20 20 69 6e 74  e query */.  int
19eb0 20 2a 70 6e 52 6f 77 2c 20 20 20 20 20 20 20 20   *pnRow,        
19ec0 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20     /* Number of 
19ed0 72 65 73 75 6c 74 20 72 6f 77 73 20 77 72 69 74  result rows writ
19ee0 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 69 6e  ten here */.  in
19ef0 74 20 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20 20 20  t *pnColumn,    
19f00 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66      /* Number of
19f10 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73 20   result columns 
19f20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a  written here */.
19f30 20 20 63 68 61 72 20 2a 2a 70 7a 45 72 72 6d 73    char **pzErrms
19f40 67 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72  g       /* Error
19f50 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65 72   msg written her
19f60 65 20 2a 2f 0a 29 3b 0a 76 6f 69 64 20 73 71 6c  e */.);.void sql
19f70 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28  ite3_free_table(
19f80 63 68 61 72 20 2a 2a 72 65 73 75 6c 74 29 3b 0a  char **result);.
19f90 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
19fa0 20 46 6f 72 6d 61 74 74 65 64 20 53 74 72 69 6e   Formatted Strin
19fb0 67 20 50 72 69 6e 74 69 6e 67 20 46 75 6e 63 74  g Printing Funct
19fc0 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ions.**.** These
19fd0 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 77 6f   routines are wo
19fe0 72 6b 2d 61 6c 69 6b 65 73 20 6f 66 20 74 68 65  rk-alikes of the
19ff0 20 22 70 72 69 6e 74 66 28 29 22 20 66 61 6d 69   "printf()" fami
1a000 6c 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a  ly of functions.
1a010 2a 2a 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e  ** from the stan
1a020 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a  dard C library..
1a030 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1a040 65 33 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e 64  e3_mprintf() and
1a050 20 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74   sqlite3_vmprint
1a060 66 28 29 20 72 6f 75 74 69 6e 65 73 20 77 72 69  f() routines wri
1a070 74 65 20 74 68 65 69 72 0a 2a 2a 20 72 65 73 75  te their.** resu
1a080 6c 74 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20  lts into memory 
1a090 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73  obtained from [s
1a0a0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
1a0b0 2e 0a 2a 2a 20 54 68 65 20 73 74 72 69 6e 67 73  ..** The strings
1a0c0 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65   returned by the
1a0d0 73 65 20 74 77 6f 20 72 6f 75 74 69 6e 65 73 20  se two routines 
1a0e0 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c  should be.** rel
1a0f0 65 61 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65  eased by [sqlite
1a100 33 5f 66 72 65 65 28 29 5d 2e 20 20 5e 42 6f 74  3_free()].  ^Bot
1a110 68 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  h routines retur
1a120 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e  n a.** NULL poin
1a130 74 65 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f  ter if [sqlite3_
1a140 6d 61 6c 6c 6f 63 28 29 5d 20 69 73 20 75 6e 61  malloc()] is una
1a150 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20  ble to allocate 
1a160 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79  enough.** memory
1a170 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 72 65 73   to hold the res
1a180 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a  ulting string..*
1a190 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74  *.** ^(The sqlit
1a1a0 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 20 72 6f  e3_snprintf() ro
1a1b0 75 74 69 6e 65 20 69 73 20 73 69 6d 69 6c 61 72  utine is similar
1a1c0 20 74 6f 20 22 73 6e 70 72 69 6e 74 66 28 29 22   to "snprintf()"
1a1d0 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61   from.** the sta
1a1e0 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e  ndard C library.
1a1f0 20 20 54 68 65 20 72 65 73 75 6c 74 20 69 73 20    The result is 
1a200 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65  written into the
1a210 0a 2a 2a 20 62 75 66 66 65 72 20 73 75 70 70 6c  .** buffer suppl
1a220 69 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e  ied as the secon
1a230 64 20 70 61 72 61 6d 65 74 65 72 20 77 68 6f 73  d parameter whos
1a240 65 20 73 69 7a 65 20 69 73 20 67 69 76 65 6e 20  e size is given 
1a250 62 79 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20  by.** the first 
1a260 70 61 72 61 6d 65 74 65 72 2e 20 4e 6f 74 65 20  parameter. Note 
1a270 74 68 61 74 20 74 68 65 20 6f 72 64 65 72 20 6f  that the order o
1a280 66 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74  f the.** first t
1a290 77 6f 20 70 61 72 61 6d 65 74 65 72 73 20 69 73  wo parameters is
1a2a0 20 72 65 76 65 72 73 65 64 20 66 72 6f 6d 20 73   reversed from s
1a2b0 6e 70 72 69 6e 74 66 28 29 2e 29 5e 20 20 54 68  nprintf().)^  Th
1a2c0 69 73 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74  is is an.** hist
1a2d0 6f 72 69 63 61 6c 20 61 63 63 69 64 65 6e 74 20  orical accident 
1a2e0 74 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 20 66  that cannot be f
1a2f0 69 78 65 64 20 77 69 74 68 6f 75 74 20 62 72 65  ixed without bre
1a300 61 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72  aking.** backwar
1a310 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ds compatibility
1a320 2e 20 20 5e 28 4e 6f 74 65 20 61 6c 73 6f 20 74  .  ^(Note also t
1a330 68 61 74 20 73 71 6c 69 74 65 33 5f 73 6e 70 72  hat sqlite3_snpr
1a340 69 6e 74 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e  intf().** return
1a350 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69  s a pointer to i
1a360 74 73 20 62 75 66 66 65 72 20 69 6e 73 74 65 61  ts buffer instea
1a370 64 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20  d of the number 
1a380 6f 66 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73  of.** characters
1a390 20 61 63 74 75 61 6c 6c 79 20 77 72 69 74 74 65   actually writte
1a3a0 6e 20 69 6e 74 6f 20 74 68 65 20 62 75 66 66 65  n into the buffe
1a3b0 72 2e 29 5e 20 20 57 65 20 61 64 6d 69 74 20 74  r.)^  We admit t
1a3c0 68 61 74 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65  hat.** the numbe
1a3d0 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 20  r of characters 
1a3e0 77 72 69 74 74 65 6e 20 77 6f 75 6c 64 20 62 65  written would be
1a3f0 20 61 20 6d 6f 72 65 20 75 73 65 66 75 6c 20 72   a more useful r
1a400 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62  eturn.** value b
1a410 75 74 20 77 65 20 63 61 6e 6e 6f 74 20 63 68 61  ut we cannot cha
1a420 6e 67 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e  nge the implemen
1a430 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65  tation of sqlite
1a440 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20  3_snprintf().** 
1a450 6e 6f 77 20 77 69 74 68 6f 75 74 20 62 72 65 61  now without brea
1a460 6b 69 6e 67 20 63 6f 6d 70 61 74 69 62 69 6c 69  king compatibili
1a470 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 6c 6f  ty..**.** ^As lo
1a480 6e 67 20 61 73 20 74 68 65 20 62 75 66 66 65 72  ng as the buffer
1a490 20 73 69 7a 65 20 69 73 20 67 72 65 61 74 65 72   size is greater
1a4a0 20 74 68 61 6e 20 7a 65 72 6f 2c 20 73 71 6c 69   than zero, sqli
1a4b0 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a  te3_snprintf().*
1a4c0 2a 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61  * guarantees tha
1a4d0 74 20 74 68 65 20 62 75 66 66 65 72 20 69 73 20  t the buffer is 
1a4e0 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d  always zero-term
1a4f0 69 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 66 69  inated.  ^The fi
1a500 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  rst.** parameter
1a510 20 22 6e 22 20 69 73 20 74 68 65 20 74 6f 74 61   "n" is the tota
1a520 6c 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75  l size of the bu
1a530 66 66 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67 20  ffer, including 
1a540 73 70 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68 65  space for.** the
1a550 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
1a560 2e 20 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73  .  So the longes
1a570 74 20 73 74 72 69 6e 67 20 74 68 61 74 20 63 61  t string that ca
1a580 6e 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a  n be completely.
1a590 2a 2a 20 77 72 69 74 74 65 6e 20 77 69 6c 6c 20  ** written will 
1a5a0 62 65 20 6e 2d 31 20 63 68 61 72 61 63 74 65 72  be n-1 character
1a5b0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  s..**.** ^The sq
1a5c0 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28  lite3_vsnprintf(
1a5d0 29 20 72 6f 75 74 69 6e 65 20 69 73 20 61 20 76  ) routine is a v
1a5e0 61 72 61 72 67 73 20 76 65 72 73 69 6f 6e 20 6f  arargs version o
1a5f0 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e  f sqlite3_snprin
1a600 74 66 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  tf()..**.** Thes
1a610 65 20 72 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69  e routines all i
1a620 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64  mplement some ad
1a630 64 69 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74  ditional formatt
1a640 69 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74  ing.** options t
1a650 68 61 74 20 61 72 65 20 75 73 65 66 75 6c 20 66  hat are useful f
1a660 6f 72 20 63 6f 6e 73 74 72 75 63 74 69 6e 67 20  or constructing 
1a670 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a  SQL statements..
1a680 2a 2a 20 41 6c 6c 20 6f 66 20 74 68 65 20 75 73  ** All of the us
1a690 75 61 6c 20 70 72 69 6e 74 66 28 29 20 66 6f 72  ual printf() for
1a6a0 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20  matting options 
1a6b0 61 70 70 6c 79 2e 20 20 49 6e 20 61 64 64 69 74  apply.  In addit
1a6c0 69 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73  ion, there.** is
1a6d0 20 61 72 65 20 22 25 71 22 2c 20 22 25 51 22 2c   are "%q", "%Q",
1a6e0 20 61 6e 64 20 22 25 7a 22 20 6f 70 74 69 6f 6e   and "%z" option
1a6f0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25  s..**.** ^(The %
1a700 71 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c  q option works l
1a710 69 6b 65 20 25 73 20 69 6e 20 74 68 61 74 20 69  ike %s in that i
1a720 74 20 73 75 62 73 74 69 74 75 74 65 73 20 61 20  t substitutes a 
1a730 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a  nul-terminated.*
1a740 2a 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 74 68  * string from th
1a750 65 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 2e  e argument list.
1a760 20 20 42 75 74 20 25 71 20 61 6c 73 6f 20 64 6f    But %q also do
1a770 75 62 6c 65 73 20 65 76 65 72 79 20 27 5c 27 27  ubles every '\''
1a780 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 25   character..** %
1a790 71 20 69 73 20 64 65 73 69 67 6e 65 64 20 66 6f  q is designed fo
1a7a0 72 20 75 73 65 20 69 6e 73 69 64 65 20 61 20 73  r use inside a s
1a7b0 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 29 5e  tring literal.)^
1a7c0 20 20 42 79 20 64 6f 75 62 6c 69 6e 67 20 65 61    By doubling ea
1a7d0 63 68 20 27 5c 27 27 0a 2a 2a 20 63 68 61 72 61  ch '\''.** chara
1a7e0 63 74 65 72 20 69 74 20 65 73 63 61 70 65 73 20  cter it escapes 
1a7f0 74 68 61 74 20 63 68 61 72 61 63 74 65 72 20 61  that character a
1a800 6e 64 20 61 6c 6c 6f 77 73 20 69 74 20 74 6f 20  nd allows it to 
1a810 62 65 20 69 6e 73 65 72 74 65 64 20 69 6e 74 6f  be inserted into
1a820 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 2e 0a  .** the string..
1a830 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c  **.** For exampl
1a840 65 2c 20 61 73 73 75 6d 65 20 74 68 65 20 73 74  e, assume the st
1a850 72 69 6e 67 20 76 61 72 69 61 62 6c 65 20 7a 54  ring variable zT
1a860 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 74 65 78  ext contains tex
1a870 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a  t as follows:.**
1a880 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
1a890 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a  <pre>.**  char *
1a8a0 7a 54 65 78 74 20 3d 20 22 49 74 27 73 20 61 20  zText = "It's a 
1a8b0 68 61 70 70 79 20 64 61 79 21 22 3b 0a 2a 2a 20  happy day!";.** 
1a8c0 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
1a8d0 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61  te>.**.** One ca
1a8e0 6e 20 75 73 65 20 74 68 69 73 20 74 65 78 74 20  n use this text 
1a8f0 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d  in an SQL statem
1a900 65 6e 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a  ent as follows:.
1a910 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
1a920 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72  e><pre>.**  char
1a930 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33   *zSQL = sqlite3
1a940 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54  _mprintf("INSERT
1a950 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55   INTO table VALU
1a960 45 53 28 27 25 71 27 29 22 2c 20 7a 54 65 78 74  ES('%q')", zText
1a970 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65  );.**  sqlite3_e
1a980 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c  xec(db, zSQL, 0,
1a990 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69   0, 0);.**  sqli
1a9a0 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a  te3_free(zSQL);.
1a9b0 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
1a9c0 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63  quote>.**.** Bec
1a9d0 61 75 73 65 20 74 68 65 20 25 71 20 66 6f 72 6d  ause the %q form
1a9e0 61 74 20 73 74 72 69 6e 67 20 69 73 20 75 73 65  at string is use
1a9f0 64 2c 20 74 68 65 20 27 5c 27 27 20 63 68 61 72  d, the '\'' char
1aa00 61 63 74 65 72 20 69 6e 20 7a 54 65 78 74 0a 2a  acter in zText.*
1aa10 2a 20 69 73 20 65 73 63 61 70 65 64 20 61 6e 64  * is escaped and
1aa20 20 74 68 65 20 53 51 4c 20 67 65 6e 65 72 61 74   the SQL generat
1aa30 65 64 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73  ed is as follows
1aa40 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
1aa50 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e  ote><pre>.**  IN
1aa60 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31  SERT INTO table1
1aa70 20 56 41 4c 55 45 53 28 27 49 74 27 27 73 20 61   VALUES('It''s a
1aa80 20 68 61 70 70 79 20 64 61 79 21 27 29 0a 2a 2a   happy day!').**
1aa90 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
1aaa0 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ote>.**.** This 
1aab0 69 73 20 63 6f 72 72 65 63 74 2e 20 20 48 61 64  is correct.  Had
1aac0 20 77 65 20 75 73 65 64 20 25 73 20 69 6e 73 74   we used %s inst
1aad0 65 61 64 20 6f 66 20 25 71 2c 20 74 68 65 20 67  ead of %q, the g
1aae0 65 6e 65 72 61 74 65 64 20 53 51 4c 0a 2a 2a 20  enerated SQL.** 
1aaf0 77 6f 75 6c 64 20 68 61 76 65 20 6c 6f 6f 6b 65  would have looke
1ab00 64 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a  d like this:.**.
1ab10 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
1ab20 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20  pre>.**  INSERT 
1ab30 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55  INTO table1 VALU
1ab40 45 53 28 27 49 74 27 73 20 61 20 68 61 70 70 79  ES('It's a happy
1ab50 20 64 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72   day!');.** </pr
1ab60 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
1ab70 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 65 63 6f 6e  **.** This secon
1ab80 64 20 65 78 61 6d 70 6c 65 20 69 73 20 61 6e 20  d example is an 
1ab90 53 51 4c 20 73 79 6e 74 61 78 20 65 72 72 6f 72  SQL syntax error
1aba0 2e 20 20 41 73 20 61 20 67 65 6e 65 72 61 6c 20  .  As a general 
1abb0 72 75 6c 65 20 79 6f 75 20 73 68 6f 75 6c 64 0a  rule you should.
1abc0 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 20 25 71  ** always use %q
1abd0 20 69 6e 73 74 65 61 64 20 6f 66 20 25 73 20 77   instead of %s w
1abe0 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 74 65  hen inserting te
1abf0 78 74 20 69 6e 74 6f 20 61 20 73 74 72 69 6e 67  xt into a string
1ac00 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20   literal..**.** 
1ac10 5e 28 54 68 65 20 25 51 20 6f 70 74 69 6f 6e 20  ^(The %Q option 
1ac20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 71 20 65 78  works like %q ex
1ac30 63 65 70 74 20 69 74 20 61 6c 73 6f 20 61 64 64  cept it also add
1ac40 73 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 20  s single quotes 
1ac50 61 72 6f 75 6e 64 0a 2a 2a 20 74 68 65 20 6f 75  around.** the ou
1ac60 74 73 69 64 65 20 6f 66 20 74 68 65 20 74 6f 74  tside of the tot
1ac70 61 6c 20 73 74 72 69 6e 67 2e 20 20 41 64 64 69  al string.  Addi
1ac80 74 69 6f 6e 61 6c 6c 79 2c 20 69 66 20 74 68 65  tionally, if the
1ac90 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68   parameter in th
1aca0 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6c 69  e.** argument li
1acb0 73 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  st is a NULL poi
1acc0 6e 74 65 72 2c 20 25 51 20 73 75 62 73 74 69 74  nter, %Q substit
1acd0 75 74 65 73 20 74 68 65 20 74 65 78 74 20 22 4e  utes the text "N
1ace0 55 4c 4c 22 20 28 77 69 74 68 6f 75 74 0a 2a 2a  ULL" (without.**
1acf0 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 29 2e   single quotes).
1ad00 29 5e 20 20 53 6f 2c 20 66 6f 72 20 65 78 61 6d  )^  So, for exam
1ad10 70 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c 64 20 73  ple, one could s
1ad20 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ay:.**.** <block
1ad30 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
1ad40 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c  char *zSQL = sql
1ad50 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e  ite3_mprintf("IN
1ad60 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20  SERT INTO table 
1ad70 56 41 4c 55 45 53 28 25 51 29 22 2c 20 7a 54 65  VALUES(%Q)", zTe
1ad80 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33  xt);.**  sqlite3
1ad90 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20  _exec(db, zSQL, 
1ada0 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71  0, 0, 0);.**  sq
1adb0 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29  lite3_free(zSQL)
1adc0 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
1add0 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54  ckquote>.**.** T
1ade0 68 65 20 63 6f 64 65 20 61 62 6f 76 65 20 77 69  he code above wi
1adf0 6c 6c 20 72 65 6e 64 65 72 20 61 20 63 6f 72 72  ll render a corr
1ae00 65 63 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ect SQL statemen
1ae10 74 20 69 6e 20 74 68 65 20 7a 53 51 4c 0a 2a 2a  t in the zSQL.**
1ae20 20 76 61 72 69 61 62 6c 65 20 65 76 65 6e 20 69   variable even i
1ae30 66 20 74 68 65 20 7a 54 65 78 74 20 76 61 72 69  f the zText vari
1ae40 61 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c 20 70  able is a NULL p
1ae50 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ointer..**.** ^(
1ae60 54 68 65 20 22 25 7a 22 20 66 6f 72 6d 61 74 74  The "%z" formatt
1ae70 69 6e 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73  ing option works
1ae80 20 6c 69 6b 65 20 22 25 73 22 20 62 75 74 20 77   like "%s" but w
1ae90 69 74 68 20 74 68 65 0a 2a 2a 20 61 64 64 69 74  ith the.** addit
1aea0 69 6f 6e 20 74 68 61 74 20 61 66 74 65 72 20 74  ion that after t
1aeb0 68 65 20 73 74 72 69 6e 67 20 68 61 73 20 62 65  he string has be
1aec0 65 6e 20 72 65 61 64 20 61 6e 64 20 63 6f 70 69  en read and copi
1aed0 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 72  ed into.** the r
1aee0 65 73 75 6c 74 2c 20 5b 73 71 6c 69 74 65 33 5f  esult, [sqlite3_
1aef0 66 72 65 65 28 29 5d 20 69 73 20 63 61 6c 6c 65  free()] is calle
1af00 64 20 6f 6e 20 74 68 65 20 69 6e 70 75 74 20 73  d on the input s
1af10 74 72 69 6e 67 2e 29 5e 0a 2a 2f 0a 63 68 61 72  tring.)^.*/.char
1af20 20 2a 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74   *sqlite3_mprint
1af30 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 2e 2e  f(const char*,..
1af40 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65  .);.char *sqlite
1af50 33 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74  3_vmprintf(const
1af60 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29   char*, va_list)
1af70 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  ;.char *sqlite3_
1af80 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61  snprintf(int,cha
1af90 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  r*,const char*, 
1afa0 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69  ...);.char *sqli
1afb0 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 69 6e  te3_vsnprintf(in
1afc0 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68  t,char*,const ch
1afd0 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 0a  ar*, va_list);..
1afe0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1aff0 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f  Memory Allocatio
1b000 6e 20 53 75 62 73 79 73 74 65 6d 0a 2a 2a 0a 2a  n Subsystem.**.*
1b010 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72  * The SQLite cor
1b020 65 20 75 73 65 73 20 74 68 65 73 65 20 74 68 72  e uses these thr
1b030 65 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 20  ee routines for 
1b040 61 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e 0a 2a  all of its own.*
1b050 2a 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72  * internal memor
1b060 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65  y allocation nee
1b070 64 73 2e 20 22 43 6f 72 65 22 20 69 6e 20 74 68  ds. "Core" in th
1b080 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65  e previous sente
1b090 6e 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20  nce.** does not 
1b0a0 69 6e 63 6c 75 64 65 20 6f 70 65 72 61 74 69 6e  include operatin
1b0b0 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66 69  g-system specifi
1b0c0 63 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61  c VFS implementa
1b0d0 74 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 57 69  tion.  The.** Wi
1b0e0 6e 64 6f 77 73 20 56 46 53 20 75 73 65 73 20 6e  ndows VFS uses n
1b0f0 61 74 69 76 65 20 6d 61 6c 6c 6f 63 28 29 20 61  ative malloc() a
1b100 6e 64 20 66 72 65 65 28 29 20 66 6f 72 20 73 6f  nd free() for so
1b110 6d 65 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a  me operations..*
1b120 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
1b130 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69  3_malloc() routi
1b140 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ne returns a poi
1b150 6e 74 65 72 20 74 6f 20 61 20 62 6c 6f 63 6b 0a  nter to a block.
1b160 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61 74 20  ** of memory at 
1b170 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e  least N bytes in
1b180 20 6c 65 6e 67 74 68 2c 20 77 68 65 72 65 20 4e   length, where N
1b190 20 69 73 20 74 68 65 20 70 61 72 61 6d 65 74 65   is the paramete
1b1a0 72 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65  r..** ^If sqlite
1b1b0 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 75 6e  3_malloc() is un
1b1c0 61 62 6c 65 20 74 6f 20 6f 62 74 61 69 6e 20 73  able to obtain s
1b1d0 75 66 66 69 63 69 65 6e 74 20 66 72 65 65 0a 2a  ufficient free.*
1b1e0 2a 20 6d 65 6d 6f 72 79 2c 20 69 74 20 72 65 74  * memory, it ret
1b1f0 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  urns a NULL poin
1b200 74 65 72 2e 20 20 5e 49 66 20 74 68 65 20 70 61  ter.  ^If the pa
1b210 72 61 6d 65 74 65 72 20 4e 20 74 6f 0a 2a 2a 20  rameter N to.** 
1b220 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1b230 20 69 73 20 7a 65 72 6f 20 6f 72 20 6e 65 67 61   is zero or nega
1b240 74 69 76 65 20 74 68 65 6e 20 73 71 6c 69 74 65  tive then sqlite
1b250 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 74 75 72  3_malloc() retur
1b260 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69  ns.** a NULL poi
1b270 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c  nter..**.** ^Cal
1b280 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 65  ling sqlite3_fre
1b290 65 28 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74  e() with a point
1b2a0 65 72 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65  er previously re
1b2b0 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c  turned.** by sql
1b2c0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72  ite3_malloc() or
1b2d0 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
1b2e0 28 29 20 72 65 6c 65 61 73 65 73 20 74 68 61 74  () releases that
1b2f0 20 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 68   memory so.** th
1b300 61 74 20 69 74 20 6d 69 67 68 74 20 62 65 20 72  at it might be r
1b310 65 75 73 65 64 2e 20 20 5e 54 68 65 20 73 71 6c  eused.  ^The sql
1b320 69 74 65 33 5f 66 72 65 65 28 29 20 72 6f 75 74  ite3_free() rout
1b330 69 6e 65 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f  ine is.** a no-o
1b340 70 20 69 66 20 69 73 20 63 61 6c 6c 65 64 20 77  p if is called w
1b350 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  ith a NULL point
1b360 65 72 2e 20 20 50 61 73 73 69 6e 67 20 61 20 4e  er.  Passing a N
1b370 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74  ULL pointer.** t
1b380 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29  o sqlite3_free()
1b390 20 69 73 20 68 61 72 6d 6c 65 73 73 2e 20 20 41   is harmless.  A
1b3a0 66 74 65 72 20 62 65 69 6e 67 20 66 72 65 65 64  fter being freed
1b3b0 2c 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75  , memory.** shou
1b3c0 6c 64 20 6e 65 69 74 68 65 72 20 62 65 20 72 65  ld neither be re
1b3d0 61 64 20 6e 6f 72 20 77 72 69 74 74 65 6e 2e 20  ad nor written. 
1b3e0 20 45 76 65 6e 20 72 65 61 64 69 6e 67 20 70 72   Even reading pr
1b3f0 65 76 69 6f 75 73 6c 79 20 66 72 65 65 64 0a 2a  eviously freed.*
1b400 2a 20 6d 65 6d 6f 72 79 20 6d 69 67 68 74 20 72  * memory might r
1b410 65 73 75 6c 74 20 69 6e 20 61 20 73 65 67 6d 65  esult in a segme
1b420 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72  ntation fault or
1b430 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 65 72   other severe er
1b440 72 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63  ror..** Memory c
1b450 6f 72 72 75 70 74 69 6f 6e 2c 20 61 20 73 65 67  orruption, a seg
1b460 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 2c  mentation fault,
1b470 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72 65   or other severe
1b480 20 65 72 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 20   error.** might 
1b490 72 65 73 75 6c 74 20 69 66 20 73 71 6c 69 74 65  result if sqlite
1b4a0 33 5f 66 72 65 65 28 29 20 69 73 20 63 61 6c 6c  3_free() is call
1b4b0 65 64 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55  ed with a non-NU
1b4c0 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 61 74 0a  LL pointer that.
1b4d0 2a 2a 20 77 61 73 20 6e 6f 74 20 6f 62 74 61 69  ** was not obtai
1b4e0 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  ned from sqlite3
1b4f0 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c  _malloc() or sql
1b500 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a  ite3_realloc()..
1b510 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69  **.** ^(The sqli
1b520 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69 6e  te3_realloc() in
1b530 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73  terface attempts
1b540 20 74 6f 20 72 65 73 69 7a 65 20 61 0a 2a 2a 20   to resize a.** 
1b550 70 72 69 6f 72 20 6d 65 6d 6f 72 79 20 61 6c 6c  prior memory all
1b560 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65 20 61 74  ocation to be at
1b570 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 2c 20   least N bytes, 
1b580 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 0a 2a  where N is the.*
1b590 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  * second paramet
1b5a0 65 72 2e 20 20 54 68 65 20 6d 65 6d 6f 72 79 20  er.  The memory 
1b5b0 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65  allocation to be
1b5c0 20 72 65 73 69 7a 65 64 20 69 73 20 74 68 65 20   resized is the 
1b5d0 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74  first.** paramet
1b5e0 65 72 2e 29 5e 20 5e 20 49 66 20 74 68 65 20 66  er.)^ ^ If the f
1b5f0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
1b600 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  o sqlite3_reallo
1b610 63 28 29 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c  c().** is a NULL
1b620 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 69 74   pointer then it
1b630 73 20 62 65 68 61 76 69 6f 72 20 69 73 20 69 64  s behavior is id
1b640 65 6e 74 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69  entical to calli
1b650 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61  ng.** sqlite3_ma
1b660 6c 6c 6f 63 28 4e 29 20 77 68 65 72 65 20 4e 20  lloc(N) where N 
1b670 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  is the second pa
1b680 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
1b690 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a  e3_realloc()..**
1b6a0 20 5e 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20   ^If the second 
1b6b0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
1b6c0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69  ite3_realloc() i
1b6d0 73 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67  s zero or.** neg
1b6e0 61 74 69 76 65 20 74 68 65 6e 20 74 68 65 20 62  ative then the b
1b6f0 65 68 61 76 69 6f 72 20 69 73 20 65 78 61 63 74  ehavior is exact
1b700 6c 79 20 74 68 65 20 73 61 6d 65 20 61 73 20 63  ly the same as c
1b710 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65  alling.** sqlite
1b720 33 5f 66 72 65 65 28 50 29 20 77 68 65 72 65 20  3_free(P) where 
1b730 50 20 69 73 20 74 68 65 20 66 69 72 73 74 20 70  P is the first p
1b740 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
1b750 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a  te3_realloc()..*
1b760 2a 20 5e 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  * ^sqlite3_reall
1b770 6f 63 28 29 20 72 65 74 75 72 6e 73 20 61 20 70  oc() returns a p
1b780 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f  ointer to a memo
1b790 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a  ry allocation.**
1b7a0 20 6f 66 20 61 74 20 6c 65 61 73 74 20 4e 20 62   of at least N b
1b7b0 79 74 65 73 20 69 6e 20 73 69 7a 65 20 6f 72 20  ytes in size or 
1b7c0 4e 55 4c 4c 20 69 66 20 73 75 66 66 69 63 69 65  NULL if sufficie
1b7d0 6e 74 20 6d 65 6d 6f 72 79 20 69 73 20 75 6e 61  nt memory is una
1b7e0 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66  vailable..** ^If
1b7f0 20 4d 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f   M is the size o
1b800 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f  f the prior allo
1b810 63 61 74 69 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e  cation, then min
1b820 28 4e 2c 4d 29 20 62 79 74 65 73 0a 2a 2a 20 6f  (N,M) bytes.** o
1b830 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f  f the prior allo
1b840 63 61 74 69 6f 6e 20 61 72 65 20 63 6f 70 69 65  cation are copie
1b850 64 20 69 6e 74 6f 20 74 68 65 20 62 65 67 69 6e  d into the begin
1b860 6e 69 6e 67 20 6f 66 20 62 75 66 66 65 72 20 72  ning of buffer r
1b870 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71  eturned.** by sq
1b880 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20  lite3_realloc() 
1b890 61 6e 64 20 74 68 65 20 70 72 69 6f 72 20 61 6c  and the prior al
1b8a0 6c 6f 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65  location is free
1b8b0 64 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65  d..** ^If sqlite
1b8c0 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 74 75  3_realloc() retu
1b8d0 72 6e 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74  rns NULL, then t
1b8e0 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74  he prior allocat
1b8f0 69 6f 6e 0a 2a 2a 20 69 73 20 6e 6f 74 20 66 72  ion.** is not fr
1b900 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  eed..**.** ^The 
1b910 6d 65 6d 6f 72 79 20 72 65 74 75 72 6e 65 64 20  memory returned 
1b920 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  by sqlite3_mallo
1b930 63 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  c() and sqlite3_
1b940 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20  realloc().** is 
1b950 61 6c 77 61 79 73 20 61 6c 69 67 6e 65 64 20 74  always aligned t
1b960 6f 20 61 74 20 6c 65 61 73 74 20 61 6e 20 38 20  o at least an 8 
1b970 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2c 20 6f  byte boundary, o
1b980 72 20 74 6f 20 61 0a 2a 2a 20 34 20 62 79 74 65  r to a.** 4 byte
1b990 20 62 6f 75 6e 64 61 72 79 20 69 66 20 74 68 65   boundary if the
1b9a0 20 5b 53 51 4c 49 54 45 5f 34 5f 42 59 54 45 5f   [SQLITE_4_BYTE_
1b9b0 41 4c 49 47 4e 45 44 5f 4d 41 4c 4c 4f 43 5d 20  ALIGNED_MALLOC] 
1b9c0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20  compile-time.** 
1b9d0 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 0a  option is used..
1b9e0 2a 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69 74 65 20  **.** In SQLite 
1b9f0 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20 61 6e  version 3.5.0 an
1ba00 64 20 33 2e 35 2e 31 2c 20 69 74 20 77 61 73 20  d 3.5.1, it was 
1ba10 70 6f 73 73 69 62 6c 65 20 74 6f 20 64 65 66 69  possible to defi
1ba20 6e 65 0a 2a 2a 20 74 68 65 20 53 51 4c 49 54 45  ne.** the SQLITE
1ba30 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c  _OMIT_MEMORY_ALL
1ba40 4f 43 41 54 49 4f 4e 20 77 68 69 63 68 20 77 6f  OCATION which wo
1ba50 75 6c 64 20 63 61 75 73 65 20 74 68 65 20 62 75  uld cause the bu
1ba60 69 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d  ilt-in.** implem
1ba70 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 73  entation of thes
1ba80 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65  e routines to be
1ba90 20 6f 6d 69 74 74 65 64 2e 20 20 54 68 61 74 20   omitted.  That 
1baa0 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73  capability.** is
1bab0 20 6e 6f 20 6c 6f 6e 67 65 72 20 70 72 6f 76 69   no longer provi
1bac0 64 65 64 2e 20 20 4f 6e 6c 79 20 62 75 69 6c 74  ded.  Only built
1bad0 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  -in memory alloc
1bae0 61 74 6f 72 73 20 63 61 6e 20 62 65 20 75 73 65  ators can be use
1baf0 64 2e 0a 2a 2a 0a 2a 2a 20 50 72 69 6f 72 20 74  d..**.** Prior t
1bb00 6f 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  o SQLite version
1bb10 20 33 2e 37 2e 31 30 2c 20 74 68 65 20 57 69 6e   3.7.10, the Win
1bb20 64 6f 77 73 20 4f 53 20 69 6e 74 65 72 66 61 63  dows OS interfac
1bb30 65 20 6c 61 79 65 72 20 63 61 6c 6c 65 64 0a 2a  e layer called.*
1bb40 2a 20 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c  * the system mal
1bb50 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29  loc() and free()
1bb60 20 64 69 72 65 63 74 6c 79 20 77 68 65 6e 20 63   directly when c
1bb70 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a 20 66 69 6c  onverting.** fil
1bb80 65 6e 61 6d 65 73 20 62 65 74 77 65 65 6e 20 74  enames between t
1bb90 68 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e  he UTF-8 encodin
1bba0 67 20 75 73 65 64 20 62 79 20 53 51 4c 69 74 65  g used by SQLite
1bbb0 0a 2a 2a 20 61 6e 64 20 77 68 61 74 65 76 65 72  .** and whatever
1bbc0 20 66 69 6c 65 6e 61 6d 65 20 65 6e 63 6f 64 69   filename encodi
1bbd0 6e 67 20 69 73 20 75 73 65 64 20 62 79 20 74 68  ng is used by th
1bbe0 65 20 70 61 72 74 69 63 75 6c 61 72 20 57 69 6e  e particular Win
1bbf0 64 6f 77 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61  dows.** installa
1bc00 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20 61 6c  tion.  Memory al
1bc10 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 73 20  location errors 
1bc20 77 65 72 65 20 64 65 74 65 63 74 65 64 2c 20 62  were detected, b
1bc30 75 74 0a 2a 2a 20 74 68 65 79 20 77 65 72 65 20  ut.** they were 
1bc40 72 65 70 6f 72 74 65 64 20 62 61 63 6b 20 61 73  reported back as
1bc50 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45   [SQLITE_CANTOPE
1bc60 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45  N] or.** [SQLITE
1bc70 5f 49 4f 45 52 52 5d 20 72 61 74 68 65 72 20 74  _IOERR] rather t
1bc80 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45  han [SQLITE_NOME
1bc90 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f  M]..**.** The po
1bca0 69 6e 74 65 72 20 61 72 67 75 6d 65 6e 74 73 20  inter arguments 
1bcb0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  to [sqlite3_free
1bcc0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
1bcd0 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6d  _realloc()].** m
1bce0 75 73 74 20 62 65 20 65 69 74 68 65 72 20 4e 55  ust be either NU
1bcf0 4c 4c 20 6f 72 20 65 6c 73 65 20 70 6f 69 6e 74  LL or else point
1bd00 65 72 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ers obtained fro
1bd10 6d 20 61 20 70 72 69 6f 72 0a 2a 2a 20 69 6e 76  m a prior.** inv
1bd20 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69  ocation of [sqli
1bd30 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72  te3_malloc()] or
1bd40 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   [sqlite3_reallo
1bd50 63 28 29 5d 20 74 68 61 74 20 68 61 76 65 0a 2a  c()] that have.*
1bd60 2a 20 6e 6f 74 20 79 65 74 20 62 65 65 6e 20 72  * not yet been r
1bd70 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  eleased..**.** T
1bd80 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
1bd90 75 73 74 20 6e 6f 74 20 72 65 61 64 20 6f 72 20  ust not read or 
1bda0 77 72 69 74 65 20 61 6e 79 20 70 61 72 74 20 6f  write any part o
1bdb0 66 0a 2a 2a 20 61 20 62 6c 6f 63 6b 20 6f 66 20  f.** a block of 
1bdc0 6d 65 6d 6f 72 79 20 61 66 74 65 72 20 69 74 20  memory after it 
1bdd0 68 61 73 20 62 65 65 6e 20 72 65 6c 65 61 73 65  has been release
1bde0 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  d using.** [sqli
1bdf0 74 65 33 5f 66 72 65 65 28 29 5d 20 6f 72 20 5b  te3_free()] or [
1be00 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1be10 29 5d 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c  )]..*/.void *sql
1be20 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29  ite3_malloc(int)
1be30 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  ;.void *sqlite3_
1be40 72 65 61 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20 69  realloc(void*, i
1be50 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  nt);.void sqlite
1be60 33 5f 66 72 65 65 28 76 6f 69 64 2a 29 3b 0a 0a  3_free(void*);..
1be70 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1be80 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 6f 72  Memory Allocator
1be90 20 53 74 61 74 69 73 74 69 63 73 0a 2a 2a 0a 2a   Statistics.**.*
1bea0 2a 20 53 51 4c 69 74 65 20 70 72 6f 76 69 64 65  * SQLite provide
1beb0 73 20 74 68 65 73 65 20 74 77 6f 20 69 6e 74 65  s these two inte
1bec0 72 66 61 63 65 73 20 66 6f 72 20 72 65 70 6f 72  rfaces for repor
1bed0 74 69 6e 67 20 6f 6e 20 74 68 65 20 73 74 61 74  ting on the stat
1bee0 75 73 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71  us.** of the [sq
1bef0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c  lite3_malloc()],
1bf00 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
1bf10 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ], and [sqlite3_
1bf20 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f  realloc()].** ro
1bf30 75 74 69 6e 65 73 2c 20 77 68 69 63 68 20 66 6f  utines, which fo
1bf40 72 6d 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 20  rm the built-in 
1bf50 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
1bf60 6e 20 73 75 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a  n subsystem..**.
1bf70 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33  ** ^The [sqlite3
1bf80 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20  _memory_used()] 
1bf90 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
1bfa0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
1bfb0 74 65 73 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79  tes.** of memory
1bfc0 20 63 75 72 72 65 6e 74 6c 79 20 6f 75 74 73 74   currently outst
1bfd0 61 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f 63 65 64  anding (malloced
1bfe0 20 62 75 74 20 6e 6f 74 20 66 72 65 65 64 29 2e   but not freed).
1bff0 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65  .** ^The [sqlite
1c000 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
1c010 65 72 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65  er()] routine re
1c020 74 75 72 6e 73 20 74 68 65 20 6d 61 78 69 6d 75  turns the maximu
1c030 6d 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 5b 73  m.** value of [s
1c040 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
1c050 65 64 28 29 5d 20 73 69 6e 63 65 20 74 68 65 20  ed()] since the 
1c060 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a  high-water mark.
1c070 2a 2a 20 77 61 73 20 6c 61 73 74 20 72 65 73 65  ** was last rese
1c080 74 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20  t.  ^The values 
1c090 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c  returned by [sql
1c0a0 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64  ite3_memory_used
1c0b0 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  ()] and.** [sqli
1c0c0 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
1c0d0 61 74 65 72 28 29 5d 20 69 6e 63 6c 75 64 65 20  ater()] include 
1c0e0 61 6e 79 20 6f 76 65 72 68 65 61 64 0a 2a 2a 20  any overhead.** 
1c0f0 61 64 64 65 64 20 62 79 20 53 51 4c 69 74 65 20  added by SQLite 
1c100 69 6e 20 69 74 73 20 69 6d 70 6c 65 6d 65 6e 74  in its implement
1c110 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65  ation of [sqlite
1c120 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20  3_malloc()],.** 
1c130 62 75 74 20 6e 6f 74 20 6f 76 65 72 68 65 61 64  but not overhead
1c140 20 61 64 64 65 64 20 62 79 20 74 68 65 20 61 6e   added by the an
1c150 79 20 75 6e 64 65 72 6c 79 69 6e 67 20 73 79 73  y underlying sys
1c160 74 65 6d 20 6c 69 62 72 61 72 79 0a 2a 2a 20 72  tem library.** r
1c170 6f 75 74 69 6e 65 73 20 74 68 61 74 20 5b 73 71  outines that [sq
1c180 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
1c190 6d 61 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20  may call..**.** 
1c1a0 5e 54 68 65 20 6d 65 6d 6f 72 79 20 68 69 67 68  ^The memory high
1c1b0 2d 77 61 74 65 72 20 6d 61 72 6b 20 69 73 20 72  -water mark is r
1c1c0 65 73 65 74 20 74 6f 20 74 68 65 20 63 75 72 72  eset to the curr
1c1d0 65 6e 74 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20  ent value of.** 
1c1e0 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
1c1f0 75 73 65 64 28 29 5d 20 69 66 20 61 6e 64 20 6f  used()] if and o
1c200 6e 6c 79 20 69 66 20 74 68 65 20 70 61 72 61 6d  nly if the param
1c210 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  eter to.** [sqli
1c220 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
1c230 61 74 65 72 28 29 5d 20 69 73 20 74 72 75 65 2e  ater()] is true.
1c240 20 20 5e 54 68 65 20 76 61 6c 75 65 20 72 65 74    ^The value ret
1c250 75 72 6e 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c  urned.** by [sql
1c260 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
1c270 77 61 74 65 72 28 31 29 5d 20 69 73 20 74 68 65  water(1)] is the
1c280 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b   high-water mark
1c290 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 74 68 65  .** prior to the
1c2a0 20 72 65 73 65 74 2e 0a 2a 2f 0a 73 71 6c 69 74   reset..*/.sqlit
1c2b0 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
1c2c0 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 76 6f 69  _memory_used(voi
1c2d0 64 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36  d);.sqlite3_int6
1c2e0 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79  4 sqlite3_memory
1c2f0 5f 68 69 67 68 77 61 74 65 72 28 69 6e 74 20 72  _highwater(int r
1c300 65 73 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a  esetFlag);../*.*
1c310 2a 20 43 41 50 49 33 52 45 46 3a 20 50 73 65 75  * CAPI3REF: Pseu
1c320 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62 65 72  do-Random Number
1c330 20 47 65 6e 65 72 61 74 6f 72 0a 2a 2a 0a 2a 2a   Generator.**.**
1c340 20 53 51 4c 69 74 65 20 63 6f 6e 74 61 69 6e 73   SQLite contains
1c350 20 61 20 68 69 67 68 2d 71 75 61 6c 69 74 79 20   a high-quality 
1c360 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75  pseudo-random nu
1c370 6d 62 65 72 20 67 65 6e 65 72 61 74 6f 72 20 28  mber generator (
1c380 50 52 4e 47 29 20 75 73 65 64 20 74 6f 0a 2a 2a  PRNG) used to.**
1c390 20 73 65 6c 65 63 74 20 72 61 6e 64 6f 6d 20 5b   select random [
1c3a0 52 4f 57 49 44 20 7c 20 52 4f 57 49 44 73 5d 20  ROWID | ROWIDs] 
1c3b0 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 6e  when inserting n
1c3c0 65 77 20 72 65 63 6f 72 64 73 20 69 6e 74 6f 20  ew records into 
1c3d0 61 20 74 61 62 6c 65 20 74 68 61 74 0a 2a 2a 20  a table that.** 
1c3e0 61 6c 72 65 61 64 79 20 75 73 65 73 20 74 68 65  already uses the
1c3f0 20 6c 61 72 67 65 73 74 20 70 6f 73 73 69 62 6c   largest possibl
1c400 65 20 5b 52 4f 57 49 44 5d 2e 20 20 54 68 65 20  e [ROWID].  The 
1c410 50 52 4e 47 20 69 73 20 61 6c 73 6f 20 75 73 65  PRNG is also use
1c420 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 62 75 69  d for.** the bui
1c430 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d 28 29 20 61  ld-in random() a
1c440 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f 62 28 29 20  nd randomblob() 
1c450 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20  SQL functions.  
1c460 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 61  This interface a
1c470 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c 69 63 61  llows.** applica
1c480 74 69 6f 6e 73 20 74 6f 20 61 63 63 65 73 73 20  tions to access 
1c490 74 68 65 20 73 61 6d 65 20 50 52 4e 47 20 66 6f  the same PRNG fo
1c4a0 72 20 6f 74 68 65 72 20 70 75 72 70 6f 73 65 73  r other purposes
1c4b0 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20  ..**.** ^A call 
1c4c0 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  to this routine 
1c4d0 73 74 6f 72 65 73 20 4e 20 62 79 74 65 73 20 6f  stores N bytes o
1c4e0 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74  f randomness int
1c4f0 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a 0a 2a  o buffer P..**.*
1c500 2a 20 5e 54 68 65 20 66 69 72 73 74 20 74 69 6d  * ^The first tim
1c510 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69  e this routine i
1c520 73 20 69 6e 76 6f 6b 65 64 20 28 65 69 74 68 65  s invoked (eithe
1c530 72 20 69 6e 74 65 72 6e 61 6c 6c 79 20 6f 72 20  r internally or 
1c540 62 79 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63  by.** the applic
1c550 61 74 69 6f 6e 29 20 74 68 65 20 50 52 4e 47 20  ation) the PRNG 
1c560 69 73 20 73 65 65 64 65 64 20 75 73 69 6e 67 20  is seeded using 
1c570 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69  randomness obtai
1c580 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20  ned.** from the 
1c590 78 52 61 6e 64 6f 6d 6e 65 73 73 20 6d 65 74 68  xRandomness meth
1c5a0 6f 64 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c  od of the defaul
1c5b0 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  t [sqlite3_vfs] 
1c5c0 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e 4f 6e 20 61  object..** ^On a
1c5d0 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 20 69 6e  ll subsequent in
1c5e0 76 6f 63 61 74 69 6f 6e 73 2c 20 74 68 65 20 70  vocations, the p
1c5f0 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73  seudo-randomness
1c600 20 69 73 20 67 65 6e 65 72 61 74 65 64 0a 2a 2a   is generated.**
1c610 20 69 6e 74 65 72 6e 61 6c 6c 79 20 61 6e 64 20   internally and 
1c620 77 69 74 68 6f 75 74 20 72 65 63 6f 75 72 73 65  without recourse
1c630 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
1c640 5f 76 66 73 5d 20 78 52 61 6e 64 6f 6d 6e 65 73  _vfs] xRandomnes
1c650 73 0a 2a 2a 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a  s.** method..*/.
1c660 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 61 6e  void sqlite3_ran
1c670 64 6f 6d 6e 65 73 73 28 69 6e 74 20 4e 2c 20 76  domness(int N, v
1c680 6f 69 64 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20  oid *P);../*.** 
1c690 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c  CAPI3REF: Compil
1c6a0 65 2d 54 69 6d 65 20 41 75 74 68 6f 72 69 7a 61  e-Time Authoriza
1c6b0 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a  tion Callbacks.*
1c6c0 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69  *.** ^This routi
1c6d0 6e 65 20 72 65 67 69 73 74 65 72 73 20 61 6e 20  ne registers an 
1c6e0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
1c6f0 61 63 6b 20 77 69 74 68 20 61 20 70 61 72 74 69  ack with a parti
1c700 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61  cular.** [databa
1c710 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20  se connection], 
1c720 73 75 70 70 6c 69 65 64 20 69 6e 20 74 68 65 20  supplied in the 
1c730 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a  first argument..
1c740 2a 2a 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a  ** ^The authoriz
1c750 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  er callback is i
1c760 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c 20 73 74  nvoked as SQL st
1c770 61 74 65 6d 65 6e 74 73 20 61 72 65 20 62 65 69  atements are bei
1c780 6e 67 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62  ng compiled.** b
1c790 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  y [sqlite3_prepa
1c7a0 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72  re()] or its var
1c7b0 69 61 6e 74 73 20 5b 73 71 6c 69 74 65 33 5f 70  iants [sqlite3_p
1c7c0 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a  repare_v2()],.**
1c7d0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1c7e0 65 31 36 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  e16()] and [sqli
1c7f0 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
1c800 28 29 5d 2e 20 20 5e 41 74 20 76 61 72 69 6f 75  ()].  ^At variou
1c810 73 0a 2a 2a 20 70 6f 69 6e 74 73 20 64 75 72 69  s.** points duri
1c820 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 61 74 69  ng the compilati
1c830 6f 6e 20 70 72 6f 63 65 73 73 2c 20 61 73 20 6c  on process, as l
1c840 6f 67 69 63 20 69 73 20 62 65 69 6e 67 20 63 72  ogic is being cr
1c850 65 61 74 65 64 0a 2a 2a 20 74 6f 20 70 65 72 66  eated.** to perf
1c860 6f 72 6d 20 76 61 72 69 6f 75 73 20 61 63 74 69  orm various acti
1c870 6f 6e 73 2c 20 74 68 65 20 61 75 74 68 6f 72 69  ons, the authori
1c880 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
1c890 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73 65  invoked to.** se
1c8a0 65 20 69 66 20 74 68 6f 73 65 20 61 63 74 69 6f  e if those actio
1c8b0 6e 73 20 61 72 65 20 61 6c 6c 6f 77 65 64 2e 20  ns are allowed. 
1c8c0 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72   ^The authorizer
1c8d0 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64   callback should
1c8e0 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  .** return [SQLI
1c8f0 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77 20  TE_OK] to allow 
1c900 74 68 65 20 61 63 74 69 6f 6e 2c 20 5b 53 51 4c  the action, [SQL
1c910 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 6f 20 64  ITE_IGNORE] to d
1c920 69 73 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20 73  isallow the.** s
1c930 70 65 63 69 66 69 63 20 61 63 74 69 6f 6e 20 62  pecific action b
1c940 75 74 20 61 6c 6c 6f 77 20 74 68 65 20 53 51 4c  ut allow the SQL
1c950 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 63 6f   statement to co
1c960 6e 74 69 6e 75 65 20 74 6f 20 62 65 0a 2a 2a 20  ntinue to be.** 
1c970 63 6f 6d 70 69 6c 65 64 2c 20 6f 72 20 5b 53 51  compiled, or [SQ
1c980 4c 49 54 45 5f 44 45 4e 59 5d 20 74 6f 20 63 61  LITE_DENY] to ca
1c990 75 73 65 20 74 68 65 20 65 6e 74 69 72 65 20 53  use the entire S
1c9a0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20  QL statement to 
1c9b0 62 65 0a 2a 2a 20 72 65 6a 65 63 74 65 64 20 77  be.** rejected w
1c9c0 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e  ith an error.  ^
1c9d0 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  If the authorize
1c9e0 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  r callback retur
1c9f0 6e 73 0a 2a 2a 20 61 6e 79 20 76 61 6c 75 65 20  ns.** any value 
1ca00 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  other than [SQLI
1ca10 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c  TE_IGNORE], [SQL
1ca20 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c  ITE_OK], or [SQL
1ca30 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68 65  ITE_DENY].** the
1ca40 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70  n the [sqlite3_p
1ca50 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
1ca60 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20  equivalent call 
1ca70 74 68 61 74 20 74 72 69 67 67 65 72 65 64 0a 2a  that triggered.*
1ca80 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  * the authorizer
1ca90 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20   will fail with 
1caa0 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  an error message
1cab0 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65  ..**.** When the
1cac0 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
1cad0 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74  s [SQLITE_OK], t
1cae0 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 6f 70  hat means the op
1caf0 65 72 61 74 69 6f 6e 0a 2a 2a 20 72 65 71 75 65  eration.** reque
1cb00 73 74 65 64 20 69 73 20 6f 6b 2e 20 20 5e 57 68  sted is ok.  ^Wh
1cb10 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  en the callback 
1cb20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
1cb30 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73  DENY], the.** [s
1cb40 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
1cb50 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65  2()] or equivale
1cb60 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69  nt call that tri
1cb70 67 67 65 72 65 64 20 74 68 65 0a 2a 2a 20 61 75  ggered the.** au
1cb80 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61  thorizer will fa
1cb90 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72  il with an error
1cba0 20 6d 65 73 73 61 67 65 20 65 78 70 6c 61 69 6e   message explain
1cbb0 69 6e 67 20 74 68 61 74 0a 2a 2a 20 61 63 63 65  ing that.** acce
1cbc0 73 73 20 69 73 20 64 65 6e 69 65 64 2e 20 0a 2a  ss is denied. .*
1cbd0 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  *.** ^The first 
1cbe0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
1cbf0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
1cc00 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f  back is a copy o
1cc10 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70  f the third.** p
1cc20 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
1cc30 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
1cc40 6f 72 69 7a 65 72 28 29 20 69 6e 74 65 72 66 61  orizer() interfa
1cc50 63 65 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  ce. ^The second 
1cc60 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20  parameter.** to 
1cc70 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  the callback is 
1cc80 61 6e 20 69 6e 74 65 67 65 72 20 5b 53 51 4c 49  an integer [SQLI
1cc90 54 45 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f 6e  TE_COPY | action
1cca0 20 63 6f 64 65 5d 20 74 68 61 74 20 73 70 65 63   code] that spec
1ccb0 69 66 69 65 73 0a 2a 2a 20 74 68 65 20 70 61 72  ifies.** the par
1ccc0 74 69 63 75 6c 61 72 20 61 63 74 69 6f 6e 20 74  ticular action t
1ccd0 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e  o be authorized.
1cce0 20 5e 54 68 65 20 74 68 69 72 64 20 74 68 72 6f   ^The third thro
1ccf0 75 67 68 20 73 69 78 74 68 20 70 61 72 61 6d 65  ugh sixth parame
1cd00 74 65 72 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63  ters.** to the c
1cd10 61 6c 6c 62 61 63 6b 20 61 72 65 20 7a 65 72 6f  allback are zero
1cd20 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69  -terminated stri
1cd30 6e 67 73 20 74 68 61 74 20 63 6f 6e 74 61 69 6e  ngs that contain
1cd40 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 64   additional.** d
1cd50 65 74 61 69 6c 73 20 61 62 6f 75 74 20 74 68 65  etails about the
1cd60 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75   action to be au
1cd70 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20  thorized..**.** 
1cd80 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20 63  ^If the action c
1cd90 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 52  ode is [SQLITE_R
1cda0 45 41 44 5d 0a 2a 2a 20 61 6e 64 20 74 68 65 20  EAD].** and the 
1cdb0 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
1cdc0 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d   [SQLITE_IGNORE]
1cdd0 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 70 72   then the.** [pr
1cde0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
1cdf0 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 63  ] statement is c
1ce00 6f 6e 73 74 72 75 63 74 65 64 20 74 6f 20 73 75  onstructed to su
1ce10 62 73 74 69 74 75 74 65 0a 2a 2a 20 61 20 4e 55  bstitute.** a NU
1ce20 4c 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c 61 63  LL value in plac
1ce30 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63  e of the table c
1ce40 6f 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c 64  olumn that would
1ce50 20 68 61 76 65 0a 2a 2a 20 62 65 65 6e 20 72 65   have.** been re
1ce60 61 64 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f 4b  ad if [SQLITE_OK
1ce70 5d 20 68 61 64 20 62 65 65 6e 20 72 65 74 75 72  ] had been retur
1ce80 6e 65 64 2e 20 20 54 68 65 20 5b 53 51 4c 49 54  ned.  The [SQLIT
1ce90 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74  E_IGNORE].** ret
1cea0 75 72 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20  urn can be used 
1ceb0 74 6f 20 64 65 6e 79 20 61 6e 20 75 6e 74 72 75  to deny an untru
1cec0 73 74 65 64 20 75 73 65 72 20 61 63 63 65 73 73  sted user access
1ced0 20 74 6f 20 69 6e 64 69 76 69 64 75 61 6c 0a 2a   to individual.*
1cee0 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 61 20 74  * columns of a t
1cef0 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  able..** ^If the
1cf00 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20   action code is 
1cf10 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 20  [SQLITE_DELETE] 
1cf20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  and the callback
1cf30 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c   returns.** [SQL
1cf40 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e  ITE_IGNORE] then
1cf50 20 74 68 65 20 5b 44 45 4c 45 54 45 5d 20 6f 70   the [DELETE] op
1cf60 65 72 61 74 69 6f 6e 20 70 72 6f 63 65 65 64 73  eration proceeds
1cf70 20 62 75 74 20 74 68 65 0a 2a 2a 20 5b 74 72 75   but the.** [tru
1cf80 6e 63 61 74 65 20 6f 70 74 69 6d 69 7a 61 74 69  ncate optimizati
1cf90 6f 6e 5d 20 69 73 20 64 69 73 61 62 6c 65 64 20  on] is disabled 
1cfa0 61 6e 64 20 61 6c 6c 20 72 6f 77 73 20 61 72 65  and all rows are
1cfb0 20 64 65 6c 65 74 65 64 20 69 6e 64 69 76 69 64   deleted individ
1cfc0 75 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20  ually..**.** An 
1cfd0 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 75 73  authorizer is us
1cfe0 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33  ed when [sqlite3
1cff0 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70 61  _prepare | prepa
1d000 72 69 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73 74 61  ring].** SQL sta
1d010 74 65 6d 65 6e 74 73 20 66 72 6f 6d 20 61 6e 20  tements from an 
1d020 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63 65  untrusted source
1d030 2c 20 74 6f 20 65 6e 73 75 72 65 20 74 68 61 74  , to ensure that
1d040 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
1d050 6e 74 73 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74 72  nts.** do not tr
1d060 79 20 74 6f 20 61 63 63 65 73 73 20 64 61 74 61  y to access data
1d070 20 74 68 65 79 20 61 72 65 20 6e 6f 74 20 61 6c   they are not al
1d080 6c 6f 77 65 64 20 74 6f 20 73 65 65 2c 20 6f 72  lowed to see, or
1d090 20 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f   that they do no
1d0a0 74 0a 2a 2a 20 74 72 79 20 74 6f 20 65 78 65 63  t.** try to exec
1d0b0 75 74 65 20 6d 61 6c 69 63 69 6f 75 73 20 73 74  ute malicious st
1d0c0 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20 64 61  atements that da
1d0d0 6d 61 67 65 20 74 68 65 20 64 61 74 61 62 61 73  mage the databas
1d0e0 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70  e.  For.** examp
1d0f0 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69  le, an applicati
1d100 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77 20 61 20 75  on may allow a u
1d110 73 65 72 20 74 6f 20 65 6e 74 65 72 20 61 72 62  ser to enter arb
1d120 69 74 72 61 72 79 0a 2a 2a 20 53 51 4c 20 71 75  itrary.** SQL qu
1d130 65 72 69 65 73 20 66 6f 72 20 65 76 61 6c 75 61  eries for evalua
1d140 74 69 6f 6e 20 62 79 20 61 20 64 61 74 61 62 61  tion by a databa
1d150 73 65 2e 20 20 42 75 74 20 74 68 65 20 61 70 70  se.  But the app
1d160 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a  lication does.**
1d170 20 6e 6f 74 20 77 61 6e 74 20 74 68 65 20 75 73   not want the us
1d180 65 72 20 74 6f 20 62 65 20 61 62 6c 65 20 74 6f  er to be able to
1d190 20 6d 61 6b 65 20 61 72 62 69 74 72 61 72 79 20   make arbitrary 
1d1a0 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 0a 2a  changes to the.*
1d1b0 2a 20 64 61 74 61 62 61 73 65 2e 20 20 41 6e 20  * database.  An 
1d1c0 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 75 6c 64  authorizer could
1d1d0 20 74 68 65 6e 20 62 65 20 70 75 74 20 69 6e 20   then be put in 
1d1e0 70 6c 61 63 65 20 77 68 69 6c 65 20 74 68 65 0a  place while the.
1d1f0 2a 2a 20 75 73 65 72 2d 65 6e 74 65 72 65 64 20  ** user-entered 
1d200 53 51 4c 20 69 73 20 62 65 69 6e 67 20 5b 73 71  SQL is being [sq
1d210 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20  lite3_prepare | 
1d220 70 72 65 70 61 72 65 64 5d 20 74 68 61 74 0a 2a  prepared] that.*
1d230 2a 20 64 69 73 61 6c 6c 6f 77 73 20 65 76 65 72  * disallows ever
1d240 79 74 68 69 6e 67 20 65 78 63 65 70 74 20 5b 53  ything except [S
1d250 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74  ELECT] statement
1d260 73 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61  s..**.** Applica
1d270 74 69 6f 6e 73 20 74 68 61 74 20 6e 65 65 64 20  tions that need 
1d280 74 6f 20 70 72 6f 63 65 73 73 20 53 51 4c 20 66  to process SQL f
1d290 72 6f 6d 20 75 6e 74 72 75 73 74 65 64 20 73 6f  rom untrusted so
1d2a0 75 72 63 65 73 0a 2a 2a 20 6d 69 67 68 74 20 61  urces.** might a
1d2b0 6c 73 6f 20 63 6f 6e 73 69 64 65 72 20 6c 6f 77  lso consider low
1d2c0 65 72 69 6e 67 20 72 65 73 6f 75 72 63 65 20 6c  ering resource l
1d2d0 69 6d 69 74 73 20 75 73 69 6e 67 20 5b 73 71 6c  imits using [sql
1d2e0 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a  ite3_limit()].**
1d2f0 20 61 6e 64 20 6c 69 6d 69 74 69 6e 67 20 64 61   and limiting da
1d300 74 61 62 61 73 65 20 73 69 7a 65 20 75 73 69 6e  tabase size usin
1d310 67 20 74 68 65 20 5b 6d 61 78 5f 70 61 67 65 5f  g the [max_page_
1d320 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 0a  count] [PRAGMA].
1d330 2a 2a 20 69 6e 20 61 64 64 69 74 69 6f 6e 20 74  ** in addition t
1d340 6f 20 75 73 69 6e 67 20 61 6e 20 61 75 74 68 6f  o using an autho
1d350 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f  rizer..**.** ^(O
1d360 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 61 75 74  nly a single aut
1d370 68 6f 72 69 7a 65 72 20 63 61 6e 20 62 65 20 69  horizer can be i
1d380 6e 20 70 6c 61 63 65 20 6f 6e 20 61 20 64 61 74  n place on a dat
1d390 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1d3a0 0a 2a 2a 20 61 74 20 61 20 74 69 6d 65 2e 20 20  .** at a time.  
1d3b0 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c  Each call to sql
1d3c0 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
1d3d0 7a 65 72 20 6f 76 65 72 72 69 64 65 73 20 74 68  zer overrides th
1d3e0 65 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20 63 61  e.** previous ca
1d3f0 6c 6c 2e 29 5e 20 20 5e 44 69 73 61 62 6c 65 20  ll.)^  ^Disable 
1d400 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 62  the authorizer b
1d410 79 20 69 6e 73 74 61 6c 6c 69 6e 67 20 61 20 4e  y installing a N
1d420 55 4c 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a  ULL callback..**
1d430 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   The authorizer 
1d440 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 20 64  is disabled by d
1d450 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 68  efault..**.** Th
1d460 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
1d470 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64  lback must not d
1d480 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20  o anything that 
1d490 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74  will modify.** t
1d4a0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
1d4b0 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f  ection that invo
1d4c0 6b 65 64 20 74 68 65 20 61 75 74 68 6f 72 69 7a  ked the authoriz
1d4d0 65 72 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20  er callback..** 
1d4e0 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74  Note that [sqlit
1d4f0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
1d500 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74   and [sqlite3_st
1d510 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66  ep()] both modif
1d520 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62  y their.** datab
1d530 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20  ase connections 
1d540 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20  for the meaning 
1d550 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74  of "modify" in t
1d560 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a  his paragraph..*
1d570 2a 0a 2a 2a 20 5e 57 68 65 6e 20 5b 73 71 6c 69  *.** ^When [sqli
1d580 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
1d590 5d 20 69 73 20 75 73 65 64 20 74 6f 20 70 72 65  ] is used to pre
1d5a0 70 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74  pare a statement
1d5b0 2c 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65  , the.** stateme
1d5c0 6e 74 20 6d 69 67 68 74 20 62 65 20 72 65 2d 70  nt might be re-p
1d5d0 72 65 70 61 72 65 64 20 64 75 72 69 6e 67 20 5b  repared during [
1d5e0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
1d5f0 64 75 65 20 74 6f 20 61 20 0a 2a 2a 20 73 63 68  due to a .** sch
1d600 65 6d 61 20 63 68 61 6e 67 65 2e 20 20 48 65 6e  ema change.  Hen
1d610 63 65 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74  ce, the applicat
1d620 69 6f 6e 20 73 68 6f 75 6c 64 20 65 6e 73 75 72  ion should ensur
1d630 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 63 6f  e that the.** co
1d640 72 72 65 63 74 20 61 75 74 68 6f 72 69 7a 65 72  rrect authorizer
1d650 20 63 61 6c 6c 62 61 63 6b 20 72 65 6d 61 69 6e   callback remain
1d660 73 20 69 6e 20 70 6c 61 63 65 20 64 75 72 69 6e  s in place durin
1d670 67 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  g the [sqlite3_s
1d680 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e  tep()]..**.** ^N
1d690 6f 74 65 20 74 68 61 74 20 74 68 65 20 61 75 74  ote that the aut
1d6a0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1d6b0 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79   is invoked only
1d6c0 20 64 75 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69   during.** [sqli
1d6d0 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f  te3_prepare()] o
1d6e0 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e 20  r its variants. 
1d6f0 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 69   Authorization i
1d700 73 20 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f 72 6d  s not.** perform
1d710 65 64 20 64 75 72 69 6e 67 20 73 74 61 74 65 6d  ed during statem
1d720 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 69  ent evaluation i
1d730 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  n [sqlite3_step(
1d740 29 5d 2c 20 75 6e 6c 65 73 73 0a 2a 2a 20 61 73  )], unless.** as
1d750 20 73 74 61 74 65 64 20 69 6e 20 74 68 65 20 70   stated in the p
1d760 72 65 76 69 6f 75 73 20 70 61 72 61 67 72 61 70  revious paragrap
1d770 68 2c 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  h, sqlite3_step(
1d780 29 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 73 71 6c  ) invokes.** sql
1d790 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1d7a0 29 20 74 6f 20 72 65 70 72 65 70 61 72 65 20 61  ) to reprepare a
1d7b0 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72   statement after
1d7c0 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65   a schema change
1d7d0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
1d7e0 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28  _set_authorizer(
1d7f0 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 69  .  sqlite3*,.  i
1d800 6e 74 20 28 2a 78 41 75 74 68 29 28 76 6f 69 64  nt (*xAuth)(void
1d810 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72  *,int,const char
1d820 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f  *,const char*,co
1d830 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20  nst char*,const 
1d840 63 68 61 72 2a 29 2c 0a 20 20 76 6f 69 64 20 2a  char*),.  void *
1d850 70 55 73 65 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a  pUserData.);../*
1d860 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75  .** CAPI3REF: Au
1d870 74 68 6f 72 69 7a 65 72 20 52 65 74 75 72 6e 20  thorizer Return 
1d880 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20  Codes.**.** The 
1d890 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74  [sqlite3_set_aut
1d8a0 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72  horizer | author
1d8b0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75  izer callback fu
1d8c0 6e 63 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20  nction] must.** 
1d8d0 72 65 74 75 72 6e 20 65 69 74 68 65 72 20 5b 53  return either [S
1d8e0 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65  QLITE_OK] or one
1d8f0 20 6f 66 20 74 68 65 73 65 20 74 77 6f 20 63 6f   of these two co
1d900 6e 73 74 61 6e 74 73 20 69 6e 20 6f 72 64 65 72  nstants in order
1d910 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20 53 51  .** to signal SQ
1d920 4c 69 74 65 20 77 68 65 74 68 65 72 20 6f 72 20  Lite whether or 
1d930 6e 6f 74 20 74 68 65 20 61 63 74 69 6f 6e 20 69  not the action i
1d940 73 20 70 65 72 6d 69 74 74 65 64 2e 20 20 53 65  s permitted.  Se
1d950 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  e the.** [sqlite
1d960 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
1d970 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 64 6f   | authorizer do
1d980 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72  cumentation] for
1d990 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69   additional.** i
1d9a0 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  nformation..**.*
1d9b0 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 49  * Note that SQLI
1d9c0 54 45 5f 49 47 4e 4f 52 45 20 69 73 20 61 6c 73  TE_IGNORE is als
1d9d0 6f 20 75 73 65 64 20 61 73 20 61 20 5b 53 51 4c  o used as a [SQL
1d9e0 49 54 45 5f 52 4f 4c 4c 42 41 43 4b 20 7c 20 72  ITE_ROLLBACK | r
1d9f0 65 74 75 72 6e 20 63 6f 64 65 5d 0a 2a 2a 20 66  eturn code].** f
1da00 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33  rom the [sqlite3
1da10 5f 76 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63  _vtab_on_conflic
1da20 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a  t()] interface..
1da30 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1da40 45 5f 44 45 4e 59 20 20 20 31 20 20 20 2f 2a 20  E_DENY   1   /* 
1da50 41 62 6f 72 74 20 74 68 65 20 53 51 4c 20 73 74  Abort the SQL st
1da60 61 74 65 6d 65 6e 74 20 77 69 74 68 20 61 6e 20  atement with an 
1da70 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65  error */.#define
1da80 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 32   SQLITE_IGNORE 2
1da90 20 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f     /* Don't allo
1daa0 77 20 61 63 63 65 73 73 2c 20 62 75 74 20 64 6f  w access, but do
1dab0 6e 27 74 20 67 65 6e 65 72 61 74 65 20 61 6e 20  n't generate an 
1dac0 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20  error */../*.** 
1dad0 43 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72  CAPI3REF: Author
1dae0 69 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f 64 65  izer Action Code
1daf0 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c  s.**.** The [sql
1db00 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
1db10 7a 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65  zer()] interface
1db20 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c   registers a cal
1db30 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a  lback function.*
1db40 2a 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b 65  * that is invoke
1db50 64 20 74 6f 20 61 75 74 68 6f 72 69 7a 65 20 63  d to authorize c
1db60 65 72 74 61 69 6e 20 53 51 4c 20 73 74 61 74 65  ertain SQL state
1db70 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e 20 20 54  ment actions.  T
1db80 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72  he.** second par
1db90 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 61  ameter to the ca
1dba0 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74  llback is an int
1dbb0 65 67 65 72 20 63 6f 64 65 20 74 68 61 74 20 73  eger code that s
1dbc0 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 61 74  pecifies.** what
1dbd0 20 61 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67   action is being
1dbe0 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68   authorized.  Th
1dbf0 65 73 65 20 61 72 65 20 74 68 65 20 69 6e 74 65  ese are the inte
1dc00 67 65 72 20 61 63 74 69 6f 6e 20 63 6f 64 65 73  ger action codes
1dc10 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 61 75 74   that.** the aut
1dc20 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1dc30 20 6d 61 79 20 62 65 20 70 61 73 73 65 64 2e 0a   may be passed..
1dc40 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 63 74 69  **.** These acti
1dc50 6f 6e 20 63 6f 64 65 20 76 61 6c 75 65 73 20 73  on code values s
1dc60 69 67 6e 69 66 79 20 77 68 61 74 20 6b 69 6e 64  ignify what kind
1dc70 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e 20 69 73   of operation is
1dc80 20 74 6f 20 62 65 0a 2a 2a 20 61 75 74 68 6f 72   to be.** author
1dc90 69 7a 65 64 2e 20 20 54 68 65 20 33 72 64 20 61  ized.  The 3rd a
1dca0 6e 64 20 34 74 68 20 70 61 72 61 6d 65 74 65 72  nd 4th parameter
1dcb0 73 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69  s to the authori
1dcc0 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61  zation.** callba
1dcd0 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c  ck function will
1dce0 20 62 65 20 70 61 72 61 6d 65 74 65 72 73 20 6f   be parameters o
1dcf0 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67  r NULL depending
1dd00 20 6f 6e 20 77 68 69 63 68 20 6f 66 20 74 68 65   on which of the
1dd10 73 65 0a 2a 2a 20 63 6f 64 65 73 20 69 73 20 75  se.** codes is u
1dd20 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e  sed as the secon
1dd30 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e 28  d parameter.  ^(
1dd40 54 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65  The 5th paramete
1dd50 72 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75 74 68  r to the.** auth
1dd60 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
1dd70 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  is the name of t
1dd80 68 65 20 64 61 74 61 62 61 73 65 20 28 22 6d 61  he database ("ma
1dd90 69 6e 22 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a 20  in", "temp",.** 
1dda0 65 74 63 2e 29 20 69 66 20 61 70 70 6c 69 63 61  etc.) if applica
1ddb0 62 6c 65 2e 29 5e 20 20 5e 54 68 65 20 36 74 68  ble.)^  ^The 6th
1ddc0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
1ddd0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
1dde0 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 74 68 65 20  lback.** is the 
1ddf0 6e 61 6d 65 20 6f 66 20 74 68 65 20 69 6e 6e 65  name of the inne
1de00 72 2d 6d 6f 73 74 20 74 72 69 67 67 65 72 20 6f  r-most trigger o
1de10 72 20 76 69 65 77 20 74 68 61 74 20 69 73 20 72  r view that is r
1de20 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a  esponsible for.*
1de30 2a 20 74 68 65 20 61 63 63 65 73 73 20 61 74 74  * the access att
1de40 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20  empt or NULL if 
1de50 74 68 69 73 20 61 63 63 65 73 73 20 61 74 74 65  this access atte
1de60 6d 70 74 20 69 73 20 64 69 72 65 63 74 6c 79 20  mpt is directly 
1de70 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65  from.** top-leve
1de80 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f  l SQL code..*/./
1de90 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1dea0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1deb0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20  *********** 3rd 
1dec0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68  ************ 4th
1ded0 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64   ***********/.#d
1dee0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
1def0 41 54 45 5f 49 4e 44 45 58 20 20 20 20 20 20 20  ATE_INDEX       
1df00 20 20 20 31 20 20 20 2f 2a 20 49 6e 64 65 78 20     1   /* Index 
1df10 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20  Name      Table 
1df20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
1df30 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
1df40 54 45 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20  TE_TABLE        
1df50 20 20 32 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e    2   /* Table N
1df60 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
1df70 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1df80 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
1df90 45 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20  E_TEMP_INDEX    
1dfa0 20 33 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61   3   /* Index Na
1dfb0 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61  me      Table Na
1dfc0 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
1dfd0 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
1dfe0 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20  _TEMP_TABLE     
1dff0 34 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  4   /* Table Nam
1e000 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
1e010 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
1e020 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
1e030 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 35  TEMP_TRIGGER   5
1e040 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61     /* Trigger Na
1e050 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65  me    Table Name
1e060 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1e070 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
1e080 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20 36 20  EMP_VIEW      6 
1e090 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20    /* View Name  
1e0a0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
1e0b0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1e0c0 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 52  SQLITE_CREATE_TR
1e0d0 49 47 47 45 52 20 20 20 20 20 20 20 20 37 20 20  IGGER        7  
1e0e0 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65   /* Trigger Name
1e0f0 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
1e100 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1e110 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 49 45  QLITE_CREATE_VIE
1e120 57 20 20 20 20 20 20 20 20 20 20 20 38 20 20 20  W           8   
1e130 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20  /* View Name    
1e140 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1e150 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1e160 4c 49 54 45 5f 44 45 4c 45 54 45 20 20 20 20 20  LITE_DELETE     
1e170 20 20 20 20 20 20 20 20 20 20 20 39 20 20 20 2f             9   /
1e180 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
1e190 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1e1a0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1e1b0 49 54 45 5f 44 52 4f 50 5f 49 4e 44 45 58 20 20  ITE_DROP_INDEX  
1e1c0 20 20 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a           10   /*
1e1d0 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20   Index Name     
1e1e0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1e1f0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1e200 54 45 5f 44 52 4f 50 5f 54 41 42 4c 45 20 20 20  TE_DROP_TABLE   
1e210 20 20 20 20 20 20 20 20 31 31 20 20 20 2f 2a 20          11   /* 
1e220 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1e230 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1e240 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1e250 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 49 4e 44 45  E_DROP_TEMP_INDE
1e260 58 20 20 20 20 20 20 31 32 20 20 20 2f 2a 20 49  X      12   /* I
1e270 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54  ndex Name      T
1e280 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
1e290 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1e2a0 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 41 42 4c 45  _DROP_TEMP_TABLE
1e2b0 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20 54 61        13   /* Ta
1e2c0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
1e2d0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
1e2e0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1e2f0 44 52 4f 50 5f 54 45 4d 50 5f 54 52 49 47 47 45  DROP_TEMP_TRIGGE
1e300 52 20 20 20 20 31 34 20 20 20 2f 2a 20 54 72 69  R    14   /* Tri
1e310 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62  gger Name    Tab
1e320 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
1e330 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1e340 52 4f 50 5f 54 45 4d 50 5f 56 49 45 57 20 20 20  ROP_TEMP_VIEW   
1e350 20 20 20 20 31 35 20 20 20 2f 2a 20 56 69 65 77      15   /* View
1e360 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c   Name       NULL
1e370 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1e380 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
1e390 4f 50 5f 54 52 49 47 47 45 52 20 20 20 20 20 20  OP_TRIGGER      
1e3a0 20 20 20 31 36 20 20 20 2f 2a 20 54 72 69 67 67     16   /* Trigg
1e3b0 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65  er Name    Table
1e3c0 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
1e3d0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
1e3e0 50 5f 56 49 45 57 20 20 20 20 20 20 20 20 20 20  P_VIEW          
1e3f0 20 20 31 37 20 20 20 2f 2a 20 56 69 65 77 20 4e    17   /* View N
1e400 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20  ame       NULL  
1e410 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
1e420 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 53 45  fine SQLITE_INSE
1e430 52 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20  RT              
1e440 20 31 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   18   /* Table N
1e450 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
1e460 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1e470 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 41 47 4d  ine SQLITE_PRAGM
1e480 41 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  A               
1e490 31 39 20 20 20 2f 2a 20 50 72 61 67 6d 61 20 4e  19   /* Pragma N
1e4a0 61 6d 65 20 20 20 20 20 31 73 74 20 61 72 67 20  ame     1st arg 
1e4b0 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66 69  or NULL */.#defi
1e4c0 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 20 20  ne SQLITE_READ  
1e4d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
1e4e0 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  0   /* Table Nam
1e4f0 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61  e      Column Na
1e500 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  me     */.#defin
1e510 65 20 53 51 4c 49 54 45 5f 53 45 4c 45 43 54 20  e SQLITE_SELECT 
1e520 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 31                21
1e530 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20     /* NULL      
1e540 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1e550 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1e560 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 41 43 54   SQLITE_TRANSACT
1e570 49 4f 4e 20 20 20 20 20 20 20 20 20 20 32 32 20  ION          22 
1e580 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20    /* Operation  
1e590 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
1e5a0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1e5b0 53 51 4c 49 54 45 5f 55 50 44 41 54 45 20 20 20  SQLITE_UPDATE   
1e5c0 20 20 20 20 20 20 20 20 20 20 20 20 32 33 20 20              23  
1e5d0 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
1e5e0 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20      Column Name 
1e5f0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1e600 51 4c 49 54 45 5f 41 54 54 41 43 48 20 20 20 20  QLITE_ATTACH    
1e610 20 20 20 20 20 20 20 20 20 20 20 32 34 20 20 20             24   
1e620 2f 2a 20 46 69 6c 65 6e 61 6d 65 20 20 20 20 20  /* Filename     
1e630 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1e640 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1e650 4c 49 54 45 5f 44 45 54 41 43 48 20 20 20 20 20  LITE_DETACH     
1e660 20 20 20 20 20 20 20 20 20 20 32 35 20 20 20 2f            25   /
1e670 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20  * Database Name 
1e680 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1e690 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1e6a0 49 54 45 5f 41 4c 54 45 52 5f 54 41 42 4c 45 20  ITE_ALTER_TABLE 
1e6b0 20 20 20 20 20 20 20 20 20 32 36 20 20 20 2f 2a           26   /*
1e6c0 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20   Database Name  
1e6d0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1e6e0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1e6f0 54 45 5f 52 45 49 4e 44 45 58 20 20 20 20 20 20  TE_REINDEX      
1e700 20 20 20 20 20 20 20 20 32 37 20 20 20 2f 2a 20          27   /* 
1e710 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20  Index Name      
1e720 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1e730 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1e740 45 5f 41 4e 41 4c 59 5a 45 20 20 20 20 20 20 20  E_ANALYZE       
1e750 20 20 20 20 20 20 20 32 38 20 20 20 2f 2a 20 54         28   /* T
1e760 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
1e770 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1e780 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1e790 5f 43 52 45 41 54 45 5f 56 54 41 42 4c 45 20 20  _CREATE_VTABLE  
1e7a0 20 20 20 20 20 20 32 39 20 20 20 2f 2a 20 54 61        29   /* Ta
1e7b0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f  ble Name      Mo
1e7c0 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f  dule Name     */
1e7d0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1e7e0 44 52 4f 50 5f 56 54 41 42 4c 45 20 20 20 20 20  DROP_VTABLE     
1e7f0 20 20 20 20 20 33 30 20 20 20 2f 2a 20 54 61 62       30   /* Tab
1e800 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64  le Name      Mod
1e810 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a  ule Name     */.
1e820 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
1e830 55 4e 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20  UNCTION         
1e840 20 20 20 20 33 31 20 20 20 2f 2a 20 4e 55 4c 4c      31   /* NULL
1e850 20 20 20 20 20 20 20 20 20 20 20 20 46 75 6e 63              Func
1e860 74 69 6f 6e 20 4e 61 6d 65 20 20 20 2a 2f 0a 23  tion Name   */.#
1e870 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 41  define SQLITE_SA
1e880 56 45 50 4f 49 4e 54 20 20 20 20 20 20 20 20 20  VEPOINT         
1e890 20 20 20 33 32 20 20 20 2f 2a 20 4f 70 65 72 61     32   /* Opera
1e8a0 74 69 6f 6e 20 20 20 20 20 20 20 53 61 76 65 70  tion       Savep
1e8b0 6f 69 6e 74 20 4e 61 6d 65 20 20 2a 2f 0a 23 64  oint Name  */.#d
1e8c0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 50  efine SQLITE_COP
1e8d0 59 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  Y               
1e8e0 20 20 20 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e     0   /* No lon
1e8f0 67 65 72 20 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a  ger used */../*.
1e900 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 72 61  ** CAPI3REF: Tra
1e910 63 69 6e 67 20 41 6e 64 20 50 72 6f 66 69 6c 69  cing And Profili
1e920 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a  ng Functions.**.
1e930 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
1e940 73 20 72 65 67 69 73 74 65 72 20 63 61 6c 6c 62  s register callb
1e950 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20 74 68  ack functions th
1e960 61 74 20 63 61 6e 20 62 65 20 75 73 65 64 20 66  at can be used f
1e970 6f 72 0a 2a 2a 20 74 72 61 63 69 6e 67 20 61 6e  or.** tracing an
1e980 64 20 70 72 6f 66 69 6c 69 6e 67 20 74 68 65 20  d profiling the 
1e990 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 53 51 4c  execution of SQL
1e9a0 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a   statements..**.
1e9b0 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b  ** ^The callback
1e9c0 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74   function regist
1e9d0 65 72 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  ered by sqlite3_
1e9e0 74 72 61 63 65 28 29 20 69 73 20 69 6e 76 6f 6b  trace() is invok
1e9f0 65 64 20 61 74 0a 2a 2a 20 76 61 72 69 6f 75 73  ed at.** various
1ea00 20 74 69 6d 65 73 20 77 68 65 6e 20 61 6e 20 53   times when an S
1ea10 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  QL statement is 
1ea20 62 65 69 6e 67 20 72 75 6e 20 62 79 20 5b 73 71  being run by [sq
1ea30 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a  lite3_step()]..*
1ea40 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74  * ^The sqlite3_t
1ea50 72 61 63 65 28 29 20 63 61 6c 6c 62 61 63 6b 20  race() callback 
1ea60 69 73 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20  is invoked with 
1ea70 61 20 55 54 46 2d 38 20 72 65 6e 64 65 72 69 6e  a UTF-8 renderin
1ea80 67 20 6f 66 20 74 68 65 0a 2a 2a 20 53 51 4c 20  g of the.** SQL 
1ea90 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61  statement text a
1eaa0 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  s the statement 
1eab0 66 69 72 73 74 20 62 65 67 69 6e 73 20 65 78 65  first begins exe
1eac0 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e 28 41 64 64  cuting..** ^(Add
1ead0 69 74 69 6f 6e 61 6c 20 73 71 6c 69 74 65 33 5f  itional sqlite3_
1eae0 74 72 61 63 65 28 29 20 63 61 6c 6c 62 61 63 6b  trace() callback
1eaf0 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a  s might occur.**
1eb00 20 61 73 20 65 61 63 68 20 74 72 69 67 67 65 72   as each trigger
1eb10 65 64 20 73 75 62 70 72 6f 67 72 61 6d 20 69 73  ed subprogram is
1eb20 20 65 6e 74 65 72 65 64 2e 20 20 54 68 65 20 63   entered.  The c
1eb30 61 6c 6c 62 61 63 6b 73 20 66 6f 72 20 74 72 69  allbacks for tri
1eb40 67 67 65 72 73 0a 2a 2a 20 63 6f 6e 74 61 69 6e  ggers.** contain
1eb50 20 61 20 55 54 46 2d 38 20 53 51 4c 20 63 6f 6d   a UTF-8 SQL com
1eb60 6d 65 6e 74 20 74 68 61 74 20 69 64 65 6e 74 69  ment that identi
1eb70 66 69 65 73 20 74 68 65 20 74 72 69 67 67 65 72  fies the trigger
1eb80 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63  .)^.**.** ^The c
1eb90 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
1eba0 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20 73   registered by s
1ebb0 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29  qlite3_profile()
1ebc0 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61   is invoked.** a
1ebd0 73 20 65 61 63 68 20 53 51 4c 20 73 74 61 74 65  s each SQL state
1ebe0 6d 65 6e 74 20 66 69 6e 69 73 68 65 73 2e 20 20  ment finishes.  
1ebf0 5e 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c  ^The profile cal
1ec00 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a  lback contains.*
1ec10 2a 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73  * the original s
1ec20 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61 6e  tatement text an
1ec30 64 20 61 6e 20 65 73 74 69 6d 61 74 65 20 6f 66  d an estimate of
1ec40 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65   wall-clock time
1ec50 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e 67 20  .** of how long 
1ec60 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20 74  that statement t
1ec70 6f 6f 6b 20 74 6f 20 72 75 6e 2e 20 20 5e 54 68  ook to run.  ^Th
1ec80 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61  e profile callba
1ec90 63 6b 0a 2a 2a 20 74 69 6d 65 20 69 73 20 69 6e  ck.** time is in
1eca0 20 75 6e 69 74 73 20 6f 66 20 6e 61 6e 6f 73 65   units of nanose
1ecb0 63 6f 6e 64 73 2c 20 68 6f 77 65 76 65 72 20 74  conds, however t
1ecc0 68 65 20 63 75 72 72 65 6e 74 20 69 6d 70 6c 65  he current imple
1ecd0 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69 73 20  mentation.** is 
1ece0 6f 6e 6c 79 20 63 61 70 61 62 6c 65 20 6f 66 20  only capable of 
1ecf0 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 72 65 73 6f  millisecond reso
1ed00 6c 75 74 69 6f 6e 20 73 6f 20 74 68 65 20 73 69  lution so the si
1ed10 78 20 6c 65 61 73 74 20 73 69 67 6e 69 66 69 63  x least signific
1ed20 61 6e 74 0a 2a 2a 20 64 69 67 69 74 73 20 69 6e  ant.** digits in
1ed30 20 74 68 65 20 74 69 6d 65 20 61 72 65 20 6d 65   the time are me
1ed40 61 6e 69 6e 67 6c 65 73 73 2e 20 20 46 75 74 75  aningless.  Futu
1ed50 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  re versions of S
1ed60 51 4c 69 74 65 0a 2a 2a 20 6d 69 67 68 74 20 70  QLite.** might p
1ed70 72 6f 76 69 64 65 20 67 72 65 61 74 65 72 20 72  rovide greater r
1ed80 65 73 6f 6c 75 74 69 6f 6e 20 6f 6e 20 74 68 65  esolution on the
1ed90 20 70 72 6f 66 69 6c 65 72 20 63 61 6c 6c 62 61   profiler callba
1eda0 63 6b 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69  ck.  The.** sqli
1edb0 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 66 75  te3_profile() fu
1edc0 6e 63 74 69 6f 6e 20 69 73 20 63 6f 6e 73 69 64  nction is consid
1edd0 65 72 65 64 20 65 78 70 65 72 69 6d 65 6e 74 61  ered experimenta
1ede0 6c 20 61 6e 64 20 69 73 0a 2a 2a 20 73 75 62 6a  l and is.** subj
1edf0 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 69 6e  ect to change in
1ee00 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   future versions
1ee10 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 76   of SQLite..*/.v
1ee20 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 74 72 61  oid *sqlite3_tra
1ee30 63 65 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69  ce(sqlite3*, voi
1ee40 64 28 2a 78 54 72 61 63 65 29 28 76 6f 69 64 2a  d(*xTrace)(void*
1ee50 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20 76  ,const char*), v
1ee60 6f 69 64 2a 29 3b 0a 53 51 4c 49 54 45 5f 45 58  oid*);.SQLITE_EX
1ee70 50 45 52 49 4d 45 4e 54 41 4c 20 76 6f 69 64 20  PERIMENTAL void 
1ee80 2a 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65  *sqlite3_profile
1ee90 28 73 71 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f  (sqlite3*,.   vo
1eea0 69 64 28 2a 78 50 72 6f 66 69 6c 65 29 28 76 6f  id(*xProfile)(vo
1eeb0 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  id*,const char*,
1eec0 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 2c  sqlite3_uint64),
1eed0 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20   void*);../*.** 
1eee0 43 41 50 49 33 52 45 46 3a 20 51 75 65 72 79 20  CAPI3REF: Query 
1eef0 50 72 6f 67 72 65 73 73 20 43 61 6c 6c 62 61 63  Progress Callbac
1ef00 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ks.**.** ^The sq
1ef10 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68  lite3_progress_h
1ef20 61 6e 64 6c 65 72 28 44 2c 4e 2c 58 2c 50 29 20  andler(D,N,X,P) 
1ef30 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73  interface causes
1ef40 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a   the callback.**
1ef50 20 66 75 6e 63 74 69 6f 6e 20 58 20 74 6f 20 62   function X to b
1ef60 65 20 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64  e invoked period
1ef70 69 63 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f  ically during lo
1ef80 6e 67 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73  ng running calls
1ef90 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
1efa0 65 78 65 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65  exec()], [sqlite
1efb0 33 5f 73 74 65 70 28 29 5d 20 61 6e 64 20 5b 73  3_step()] and [s
1efc0 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
1efd0 28 29 5d 20 66 6f 72 0a 2a 2a 20 64 61 74 61 62  ()] for.** datab
1efe0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44  ase connection D
1eff0 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 75 73  .  An example us
1f000 65 20 66 6f 72 20 74 68 69 73 0a 2a 2a 20 69 6e  e for this.** in
1f010 74 65 72 66 61 63 65 20 69 73 20 74 6f 20 6b 65  terface is to ke
1f020 65 70 20 61 20 47 55 49 20 75 70 64 61 74 65 64  ep a GUI updated
1f030 20 64 75 72 69 6e 67 20 61 20 6c 61 72 67 65 20   during a large 
1f040 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  query..**.** ^Th
1f050 65 20 70 61 72 61 6d 65 74 65 72 20 50 20 69 73  e parameter P is
1f060 20 70 61 73 73 65 64 20 74 68 72 6f 75 67 68 20   passed through 
1f070 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61  as the only para
1f080 6d 65 74 65 72 20 74 6f 20 74 68 65 20 0a 2a 2a  meter to the .**
1f090 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
1f0a0 6f 6e 20 58 2e 20 20 5e 54 68 65 20 70 61 72 61  on X.  ^The para
1f0b0 6d 65 74 65 72 20 4e 20 69 73 20 74 68 65 20 6e  meter N is the n
1f0c0 75 6d 62 65 72 20 6f 66 20 0a 2a 2a 20 5b 76 69  umber of .** [vi
1f0d0 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 69 6e  rtual machine in
1f0e0 73 74 72 75 63 74 69 6f 6e 73 5d 20 74 68 61 74  structions] that
1f0f0 20 61 72 65 20 65 76 61 6c 75 61 74 65 64 20 62   are evaluated b
1f100 65 74 77 65 65 6e 20 73 75 63 63 65 73 73 69 76  etween successiv
1f110 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73  e.** invocations
1f120 20 6f 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   of the callback
1f130 20 58 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20   X..**.** ^Only 
1f140 61 20 73 69 6e 67 6c 65 20 70 72 6f 67 72 65 73  a single progres
1f150 73 20 68 61 6e 64 6c 65 72 20 6d 61 79 20 62 65  s handler may be
1f160 20 64 65 66 69 6e 65 64 20 61 74 20 6f 6e 65 20   defined at one 
1f170 74 69 6d 65 20 70 65 72 0a 2a 2a 20 5b 64 61 74  time per.** [dat
1f180 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1f190 5d 3b 20 73 65 74 74 69 6e 67 20 61 20 6e 65 77  ]; setting a new
1f1a0 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65   progress handle
1f1b0 72 20 63 61 6e 63 65 6c 73 20 74 68 65 0a 2a 2a  r cancels the.**
1f1c0 20 6f 6c 64 20 6f 6e 65 2e 20 20 5e 53 65 74 74   old one.  ^Sett
1f1d0 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20 58 20  ing parameter X 
1f1e0 74 6f 20 4e 55 4c 4c 20 64 69 73 61 62 6c 65 73  to NULL disables
1f1f0 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 68 61   the progress ha
1f200 6e 64 6c 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 70  ndler..** ^The p
1f210 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20  rogress handler 
1f220 69 73 20 61 6c 73 6f 20 64 69 73 61 62 6c 65 64  is also disabled
1f230 20 62 79 20 73 65 74 74 69 6e 67 20 4e 20 74 6f   by setting N to
1f240 20 61 20 76 61 6c 75 65 20 6c 65 73 73 0a 2a 2a   a value less.**
1f250 20 74 68 61 6e 20 31 2e 0a 2a 2a 0a 2a 2a 20 5e   than 1..**.** ^
1f260 49 66 20 74 68 65 20 70 72 6f 67 72 65 73 73 20  If the progress 
1f270 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
1f280 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 6f   non-zero, the o
1f290 70 65 72 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 69  peration is.** i
1f2a0 6e 74 65 72 72 75 70 74 65 64 2e 20 20 54 68 69  nterrupted.  Thi
1f2b0 73 20 66 65 61 74 75 72 65 20 63 61 6e 20 62 65  s feature can be
1f2c0 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65   used to impleme
1f2d0 6e 74 20 61 0a 2a 2a 20 22 43 61 6e 63 65 6c 22  nt a.** "Cancel"
1f2e0 20 62 75 74 74 6f 6e 20 6f 6e 20 61 20 47 55 49   button on a GUI
1f2f0 20 70 72 6f 67 72 65 73 73 20 64 69 61 6c 6f 67   progress dialog
1f300 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20   box..**.** The 
1f310 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72  progress handler
1f320 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e   callback must n
1f330 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74  ot do anything t
1f340 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a  hat will modify.
1f350 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ** the database 
1f360 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20  connection that 
1f370 69 6e 76 6f 6b 65 64 20 74 68 65 20 70 72 6f 67  invoked the prog
1f380 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a  ress handler..**
1f390 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69   Note that [sqli
1f3a0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
1f3b0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73  ] and [sqlite3_s
1f3c0 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69  tep()] both modi
1f3d0 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61  fy their.** data
1f3e0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
1f3f0 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67   for the meaning
1f400 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20   of "modify" in 
1f410 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a  this paragraph..
1f420 2a 2a 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74  **.*/.void sqlit
1f430 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64  e3_progress_hand
1f440 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e  ler(sqlite3*, in
1f450 74 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29  t, int(*)(void*)
1f460 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  , void*);../*.**
1f470 20 43 41 50 49 33 52 45 46 3a 20 4f 70 65 6e 69   CAPI3REF: Openi
1f480 6e 67 20 41 20 4e 65 77 20 44 61 74 61 62 61 73  ng A New Databas
1f490 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 0a  e Connection.**.
1f4a0 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
1f4b0 65 73 20 6f 70 65 6e 20 61 6e 20 53 51 4c 69 74  es open an SQLit
1f4c0 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
1f4d0 61 73 20 73 70 65 63 69 66 69 65 64 20 62 79 20  as specified by 
1f4e0 74 68 65 20 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65  the .** filename
1f4f0 20 61 72 67 75 6d 65 6e 74 2e 20 5e 54 68 65 20   argument. ^The 
1f500 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e  filename argumen
1f510 74 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64  t is interpreted
1f520 20 61 73 20 55 54 46 2d 38 20 66 6f 72 0a 2a 2a   as UTF-8 for.**
1f530 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
1f540 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  and sqlite3_open
1f550 5f 76 32 28 29 20 61 6e 64 20 61 73 20 55 54 46  _v2() and as UTF
1f560 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76  -16 in the nativ
1f570 65 20 62 79 74 65 0a 2a 2a 20 6f 72 64 65 72 20  e byte.** order 
1f580 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
1f590 31 36 28 29 2e 20 5e 28 41 20 5b 64 61 74 61 62  16(). ^(A [datab
1f5a0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
1f5b0 68 61 6e 64 6c 65 20 69 73 20 75 73 75 61 6c 6c  handle is usuall
1f5c0 79 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 6e  y.** returned in
1f5d0 20 2a 70 70 44 62 2c 20 65 76 65 6e 20 69 66 20   *ppDb, even if 
1f5e0 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e  an error occurs.
1f5f0 20 20 54 68 65 20 6f 6e 6c 79 20 65 78 63 65 70    The only excep
1f600 74 69 6f 6e 20 69 73 20 74 68 61 74 0a 2a 2a 20  tion is that.** 
1f610 69 66 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61  if SQLite is una
1f620 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20  ble to allocate 
1f630 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74  memory to hold t
1f640 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a  he [sqlite3] obj
1f650 65 63 74 2c 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77  ect,.** a NULL w
1f660 69 6c 6c 20 62 65 20 77 72 69 74 74 65 6e 20 69  ill be written i
1f670 6e 74 6f 20 2a 70 70 44 62 20 69 6e 73 74 65 61  nto *ppDb instea
1f680 64 20 6f 66 20 61 20 70 6f 69 6e 74 65 72 20 74  d of a pointer t
1f690 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 0a  o the [sqlite3].
1f6a0 2a 2a 20 6f 62 6a 65 63 74 2e 29 5e 20 5e 28 49  ** object.)^ ^(I
1f6b0 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  f the database i
1f6c0 73 20 6f 70 65 6e 65 64 20 28 61 6e 64 2f 6f 72  s opened (and/or
1f6d0 20 63 72 65 61 74 65 64 29 20 73 75 63 63 65 73   created) succes
1f6e0 73 66 75 6c 6c 79 2c 20 74 68 65 6e 0a 2a 2a 20  sfully, then.** 
1f6f0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72  [SQLITE_OK] is r
1f700 65 74 75 72 6e 65 64 2e 20 20 4f 74 68 65 72 77  eturned.  Otherw
1f710 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f  ise an [error co
1f720 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  de] is returned.
1f730 29 5e 20 5e 54 68 65 0a 2a 2a 20 5b 73 71 6c 69  )^ ^The.** [sqli
1f740 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 6f 72  te3_errmsg()] or
1f750 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
1f760 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 63  16()] routines c
1f770 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62  an be used to ob
1f780 74 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69  tain.** an Engli
1f790 73 68 20 6c 61 6e 67 75 61 67 65 20 64 65 73 63  sh language desc
1f7a0 72 69 70 74 69 6f 6e 20 6f 66 20 74 68 65 20 65  ription of the e
1f7b0 72 72 6f 72 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  rror following a
1f7c0 20 66 61 69 6c 75 72 65 20 6f 66 20 61 6e 79 0a   failure of any.
1f7d0 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65  ** of the sqlite
1f7e0 33 5f 6f 70 65 6e 28 29 20 72 6f 75 74 69 6e 65  3_open() routine
1f7f0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65  s..**.** ^The de
1f800 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20 66  fault encoding f
1f810 6f 72 20 74 68 65 20 64 61 74 61 62 61 73 65 20  or the database 
1f820 77 69 6c 6c 20 62 65 20 55 54 46 2d 38 20 69 66  will be UTF-8 if
1f830 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  .** sqlite3_open
1f840 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  () or sqlite3_op
1f850 65 6e 5f 76 32 28 29 20 69 73 20 63 61 6c 6c 65  en_v2() is calle
1f860 64 20 61 6e 64 0a 2a 2a 20 55 54 46 2d 31 36 20  d and.** UTF-16 
1f870 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79  in the native by
1f880 74 65 20 6f 72 64 65 72 20 69 66 20 73 71 6c 69  te order if sqli
1f890 74 65 33 5f 6f 70 65 6e 31 36 28 29 20 69 73 20  te3_open16() is 
1f8a0 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74  used..**.** Whet
1f8b0 68 65 72 20 6f 72 20 6e 6f 74 20 61 6e 20 65 72  her or not an er
1f8c0 72 6f 72 20 6f 63 63 75 72 73 20 77 68 65 6e 20  ror occurs when 
1f8d0 69 74 20 69 73 20 6f 70 65 6e 65 64 2c 20 72 65  it is opened, re
1f8e0 73 6f 75 72 63 65 73 0a 2a 2a 20 61 73 73 6f 63  sources.** assoc
1f8f0 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 5b  iated with the [
1f900 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1f910 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 73 68 6f 75  ion] handle shou
1f920 6c 64 20 62 65 20 72 65 6c 65 61 73 65 64 20 62  ld be released b
1f930 79 0a 2a 2a 20 70 61 73 73 69 6e 67 20 69 74 20  y.** passing it 
1f940 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73  to [sqlite3_clos
1f950 65 28 29 5d 20 77 68 65 6e 20 69 74 20 69 73 20  e()] when it is 
1f960 6e 6f 20 6c 6f 6e 67 65 72 20 72 65 71 75 69 72  no longer requir
1f970 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ed..**.** The sq
1f980 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
1f990 69 6e 74 65 72 66 61 63 65 20 77 6f 72 6b 73 20  interface works 
1f9a0 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f 6f 70 65  like sqlite3_ope
1f9b0 6e 28 29 0a 2a 2a 20 65 78 63 65 70 74 20 74 68  n().** except th
1f9c0 61 74 20 69 74 20 61 63 63 65 70 74 73 20 74 77  at it accepts tw
1f9d0 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 70 61 72  o additional par
1f9e0 61 6d 65 74 65 72 73 20 66 6f 72 20 61 64 64 69  ameters for addi
1f9f0 74 69 6f 6e 61 6c 20 63 6f 6e 74 72 6f 6c 0a 2a  tional control.*
1fa00 2a 20 6f 76 65 72 20 74 68 65 20 6e 65 77 20 64  * over the new d
1fa10 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1fa20 6f 6e 2e 20 20 5e 28 54 68 65 20 66 6c 61 67 73  on.  ^(The flags
1fa30 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
1fa40 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
1fa50 28 29 20 63 61 6e 20 74 61 6b 65 20 6f 6e 65 20  () can take one 
1fa60 6f 66 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f 77  of.** the follow
1fa70 69 6e 67 20 74 68 72 65 65 20 76 61 6c 75 65 73  ing three values
1fa80 2c 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d  , optionally com
1fa90 62 69 6e 65 64 20 77 69 74 68 20 74 68 65 20 0a  bined with the .
1faa0 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ** [SQLITE_OPEN_
1fab0 4e 4f 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54  NOMUTEX], [SQLIT
1fac0 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58  E_OPEN_FULLMUTEX
1fad0 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ], [SQLITE_OPEN_
1fae0 53 48 41 52 45 44 43 41 43 48 45 5d 2c 0a 2a 2a  SHAREDCACHE],.**
1faf0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52   [SQLITE_OPEN_PR
1fb00 49 56 41 54 45 43 41 43 48 45 5d 2c 20 61 6e 64  IVATECACHE], and
1fb10 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  /or [SQLITE_OPEN
1fb20 5f 55 52 49 5d 20 66 6c 61 67 73 3a 29 5e 0a 2a  _URI] flags:)^.*
1fb30 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c  *.** <dl>.** ^(<
1fb40 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  dt>[SQLITE_OPEN_
1fb50 52 45 41 44 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a  READONLY]</dt>.*
1fb60 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61  * <dd>The databa
1fb70 73 65 20 69 73 20 6f 70 65 6e 65 64 20 69 6e 20  se is opened in 
1fb80 72 65 61 64 2d 6f 6e 6c 79 20 6d 6f 64 65 2e 20  read-only mode. 
1fb90 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65   If the database
1fba0 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 61 6c 72   does not.** alr
1fbb0 65 61 64 79 20 65 78 69 73 74 2c 20 61 6e 20 65  eady exist, an e
1fbc0 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64  rror is returned
1fbd0 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  .</dd>)^.**.** ^
1fbe0 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45  (<dt>[SQLITE_OPE
1fbf0 4e 5f 52 45 41 44 57 52 49 54 45 5d 3c 2f 64 74  N_READWRITE]</dt
1fc00 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74  >.** <dd>The dat
1fc10 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
1fc20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20  for reading and 
1fc30 77 72 69 74 69 6e 67 20 69 66 20 70 6f 73 73 69  writing if possi
1fc40 62 6c 65 2c 20 6f 72 20 72 65 61 64 69 6e 67 0a  ble, or reading.
1fc50 2a 2a 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 66  ** only if the f
1fc60 69 6c 65 20 69 73 20 77 72 69 74 65 20 70 72 6f  ile is write pro
1fc70 74 65 63 74 65 64 20 62 79 20 74 68 65 20 6f 70  tected by the op
1fc80 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20  erating system. 
1fc90 20 49 6e 20 65 69 74 68 65 72 0a 2a 2a 20 63 61   In either.** ca
1fca0 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  se the database 
1fcb0 6d 75 73 74 20 61 6c 72 65 61 64 79 20 65 78 69  must already exi
1fcc0 73 74 2c 20 6f 74 68 65 72 77 69 73 65 20 61 6e  st, otherwise an
1fcd0 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e   error is return
1fce0 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  ed.</dd>)^.**.**
1fcf0 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f   ^(<dt>[SQLITE_O
1fd00 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c  PEN_READWRITE] |
1fd10 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52   [SQLITE_OPEN_CR
1fd20 45 41 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  EATE]</dt>.** <d
1fd30 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69  d>The database i
1fd40 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61  s opened for rea
1fd50 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67  ding and writing
1fd60 2c 20 61 6e 64 20 69 73 20 63 72 65 61 74 65 64  , and is created
1fd70 20 69 66 0a 2a 2a 20 69 74 20 64 6f 65 73 20 6e   if.** it does n
1fd80 6f 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74  ot already exist
1fd90 2e 20 54 68 69 73 20 69 73 20 74 68 65 20 62 65  . This is the be
1fda0 68 61 76 69 6f 72 20 74 68 61 74 20 69 73 20 61  havior that is a
1fdb0 6c 77 61 79 73 20 75 73 65 64 20 66 6f 72 0a 2a  lways used for.*
1fdc0 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  * sqlite3_open()
1fdd0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65   and sqlite3_ope
1fde0 6e 31 36 28 29 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  n16().</dd>)^.**
1fdf0 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20   </dl>.**.** If 
1fe00 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65  the 3rd paramete
1fe10 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65  r to sqlite3_ope
1fe20 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74 20 6f 6e  n_v2() is not on
1fe30 65 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6d 62  e of the.** comb
1fe40 69 6e 61 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61  inations shown a
1fe50 62 6f 76 65 20 6f 70 74 69 6f 6e 61 6c 6c 79 20  bove optionally 
1fe60 63 6f 6d 62 69 6e 65 64 20 77 69 74 68 20 6f 74  combined with ot
1fe70 68 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  her.** [SQLITE_O
1fe80 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 53  PEN_READONLY | S
1fe90 51 4c 49 54 45 5f 4f 50 45 4e 5f 2a 20 62 69 74  QLITE_OPEN_* bit
1fea0 73 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 62  s].** then the b
1feb0 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66  ehavior is undef
1fec0 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ined..**.** ^If 
1fed0 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  the [SQLITE_OPEN
1fee0 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c 61 67 20 69  _NOMUTEX] flag i
1fef0 73 20 73 65 74 2c 20 74 68 65 6e 20 74 68 65 20  s set, then the 
1ff00 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1ff10 69 6f 6e 0a 2a 2a 20 6f 70 65 6e 73 20 69 6e 20  ion.** opens in 
1ff20 74 68 65 20 6d 75 6c 74 69 2d 74 68 72 65 61 64  the multi-thread
1ff30 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
1ff40 5d 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65  ] as long as the
1ff50 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 0a 2a   single-thread.*
1ff60 2a 20 6d 6f 64 65 20 68 61 73 20 6e 6f 74 20 62  * mode has not b
1ff70 65 65 6e 20 73 65 74 20 61 74 20 63 6f 6d 70 69  een set at compi
1ff80 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74  le-time or start
1ff90 2d 74 69 6d 65 2e 20 20 5e 49 66 20 74 68 65 0a  -time.  ^If the.
1ffa0 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ** [SQLITE_OPEN_
1ffb0 46 55 4c 4c 4d 55 54 45 58 5d 20 66 6c 61 67 20  FULLMUTEX] flag 
1ffc0 69 73 20 73 65 74 20 74 68 65 6e 20 74 68 65 20  is set then the 
1ffd0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1ffe0 69 6f 6e 20 6f 70 65 6e 73 0a 2a 2a 20 69 6e 20  ion opens.** in 
1fff0 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b  the serialized [
20000 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
20010 75 6e 6c 65 73 73 20 73 69 6e 67 6c 65 2d 74 68  unless single-th
20020 72 65 61 64 20 77 61 73 0a 2a 2a 20 70 72 65 76  read was.** prev
20030 69 6f 75 73 6c 79 20 73 65 6c 65 63 74 65 64 20  iously selected 
20040 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  at compile-time 
20050 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 0a 2a  or start-time..*
20060 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f  * ^The [SQLITE_O
20070 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d  PEN_SHAREDCACHE]
20080 20 66 6c 61 67 20 63 61 75 73 65 73 20 74 68 65   flag causes the
20090 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
200a0 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 65 6c  tion to be.** el
200b0 69 67 69 62 6c 65 20 74 6f 20 75 73 65 20 5b 73  igible to use [s
200c0 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65  hared cache mode
200d0 5d 2c 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66  ], regardless of
200e0 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
200f0 73 68 61 72 65 64 0a 2a 2a 20 63 61 63 68 65 20  shared.** cache 
20100 69 73 20 65 6e 61 62 6c 65 64 20 75 73 69 6e 67  is enabled using
20110 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65   [sqlite3_enable
20120 5f 73 68 61 72 65 64 5f 63 61 63 68 65 28 29 5d  _shared_cache()]
20130 2e 20 20 5e 54 68 65 0a 2a 2a 20 5b 53 51 4c 49  .  ^The.** [SQLI
20140 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43  TE_OPEN_PRIVATEC
20150 41 43 48 45 5d 20 66 6c 61 67 20 63 61 75 73 65  ACHE] flag cause
20160 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  s the database c
20170 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 6e 6f 74  onnection to not
20180 0a 2a 2a 20 70 61 72 74 69 63 69 70 61 74 65 20  .** participate 
20190 69 6e 20 5b 73 68 61 72 65 64 20 63 61 63 68 65  in [shared cache
201a0 20 6d 6f 64 65 5d 20 65 76 65 6e 20 69 66 20 69   mode] even if i
201b0 74 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a  t is enabled..**
201c0 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20  .** ^The fourth 
201d0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
201e0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69  ite3_open_v2() i
201f0 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
20200 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66  e.** [sqlite3_vf
20210 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64  s] object that d
20220 65 66 69 6e 65 73 20 74 68 65 20 6f 70 65 72 61  efines the opera
20230 74 69 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 65  ting system inte
20240 72 66 61 63 65 20 74 68 61 74 0a 2a 2a 20 74 68  rface that.** th
20250 65 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63  e new database c
20260 6f 6e 6e 65 63 74 69 6f 6e 20 73 68 6f 75 6c 64  onnection should
20270 20 75 73 65 2e 20 20 5e 49 66 20 74 68 65 20 66   use.  ^If the f
20280 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
20290 69 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69  is.** a NULL poi
202a0 6e 74 65 72 20 74 68 65 6e 20 74 68 65 20 64 65  nter then the de
202b0 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76  fault [sqlite3_v
202c0 66 73 5d 20 6f 62 6a 65 63 74 20 69 73 20 75 73  fs] object is us
202d0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  ed..**.** ^If th
202e0 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 22 3a  e filename is ":
202f0 6d 65 6d 6f 72 79 3a 22 2c 20 74 68 65 6e 20 61  memory:", then a
20300 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72   private, tempor
20310 61 72 79 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61  ary in-memory da
20320 74 61 62 61 73 65 0a 2a 2a 20 69 73 20 63 72 65  tabase.** is cre
20330 61 74 65 64 20 66 6f 72 20 74 68 65 20 63 6f 6e  ated for the con
20340 6e 65 63 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20  nection.  ^This 
20350 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61  in-memory databa
20360 73 65 20 77 69 6c 6c 20 76 61 6e 69 73 68 20 77  se will vanish w
20370 68 65 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62  hen.** the datab
20380 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
20390 73 20 63 6c 6f 73 65 64 2e 20 20 46 75 74 75 72  s closed.  Futur
203a0 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  e versions of SQ
203b0 4c 69 74 65 20 6d 69 67 68 74 0a 2a 2a 20 6d 61  Lite might.** ma
203c0 6b 65 20 75 73 65 20 6f 66 20 61 64 64 69 74 69  ke use of additi
203d0 6f 6e 61 6c 20 73 70 65 63 69 61 6c 20 66 69 6c  onal special fil
203e0 65 6e 61 6d 65 73 20 74 68 61 74 20 62 65 67 69  enames that begi
203f0 6e 20 77 69 74 68 20 74 68 65 20 22 3a 22 20 63  n with the ":" c
20400 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49 74 20  haracter..** It 
20410 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74  is recommended t
20420 68 61 74 20 77 68 65 6e 20 61 20 64 61 74 61 62  hat when a datab
20430 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 61 63 74  ase filename act
20440 75 61 6c 6c 79 20 64 6f 65 73 20 62 65 67 69 6e  ually does begin
20450 20 77 69 74 68 0a 2a 2a 20 61 20 22 3a 22 20 63   with.** a ":" c
20460 68 61 72 61 63 74 65 72 20 79 6f 75 20 73 68 6f  haracter you sho
20470 75 6c 64 20 70 72 65 66 69 78 20 74 68 65 20 66  uld prefix the f
20480 69 6c 65 6e 61 6d 65 20 77 69 74 68 20 61 20 70  ilename with a p
20490 61 74 68 6e 61 6d 65 20 73 75 63 68 20 61 73 0a  athname such as.
204a0 2a 2a 20 22 2e 2f 22 20 74 6f 20 61 76 6f 69 64  ** "./" to avoid
204b0 20 61 6d 62 69 67 75 69 74 79 2e 0a 2a 2a 0a 2a   ambiguity..**.*
204c0 2a 20 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61  * ^If the filena
204d0 6d 65 20 69 73 20 61 6e 20 65 6d 70 74 79 20 73  me is an empty s
204e0 74 72 69 6e 67 2c 20 74 68 65 6e 20 61 20 70 72  tring, then a pr
204f0 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79  ivate, temporary
20500 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20 64 61 74 61  .** on-disk data
20510 62 61 73 65 20 77 69 6c 6c 20 62 65 20 63 72 65  base will be cre
20520 61 74 65 64 2e 20 20 5e 54 68 69 73 20 70 72 69  ated.  ^This pri
20530 76 61 74 65 20 64 61 74 61 62 61 73 65 20 77 69  vate database wi
20540 6c 6c 20 62 65 0a 2a 2a 20 61 75 74 6f 6d 61 74  ll be.** automat
20550 69 63 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 61  ically deleted a
20560 73 20 73 6f 6f 6e 20 61 73 20 74 68 65 20 64 61  s soon as the da
20570 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
20580 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a  n is closed..**.
20590 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d  ** [[URI filenam
205a0 65 73 20 69 6e 20 73 71 6c 69 74 65 33 5f 6f 70  es in sqlite3_op
205b0 65 6e 28 29 5d 5d 20 3c 68 33 3e 55 52 49 20 46  en()]] <h3>URI F
205c0 69 6c 65 6e 61 6d 65 73 3c 2f 68 33 3e 0a 2a 2a  ilenames</h3>.**
205d0 0a 2a 2a 20 5e 49 66 20 5b 55 52 49 20 66 69 6c  .** ^If [URI fil
205e0 65 6e 61 6d 65 5d 20 69 6e 74 65 72 70 72 65 74  ename] interpret
205f0 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64  ation is enabled
20600 2c 20 61 6e 64 20 74 68 65 20 66 69 6c 65 6e 61  , and the filena
20610 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 62  me argument.** b
20620 65 67 69 6e 73 20 77 69 74 68 20 22 66 69 6c 65  egins with "file
20630 3a 22 2c 20 74 68 65 6e 20 74 68 65 20 66 69 6c  :", then the fil
20640 65 6e 61 6d 65 20 69 73 20 69 6e 74 65 72 70 72  ename is interpr
20650 65 74 65 64 20 61 73 20 61 20 55 52 49 2e 20 5e  eted as a URI. ^
20660 55 52 49 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20  URI.** filename 
20670 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69  interpretation i
20680 73 20 65 6e 61 62 6c 65 64 20 69 66 20 74 68 65  s enabled if the
20690 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52   [SQLITE_OPEN_UR
206a0 49 5d 20 66 6c 61 67 20 69 73 0a 2a 2a 20 73 65  I] flag is.** se
206b0 74 20 69 6e 20 74 68 65 20 66 6f 75 72 74 68 20  t in the fourth 
206c0 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
206d0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2c 20 6f  te3_open_v2(), o
206e0 72 20 69 66 20 69 74 20 68 61 73 0a 2a 2a 20 62  r if it has.** b
206f0 65 65 6e 20 65 6e 61 62 6c 65 64 20 67 6c 6f 62  een enabled glob
20700 61 6c 6c 79 20 75 73 69 6e 67 20 74 68 65 20 5b  ally using the [
20710 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52  SQLITE_CONFIG_UR
20720 49 5d 20 6f 70 74 69 6f 6e 20 77 69 74 68 20 74  I] option with t
20730 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  he.** [sqlite3_c
20740 6f 6e 66 69 67 28 29 5d 20 6d 65 74 68 6f 64 20  onfig()] method 
20750 6f 72 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54  or by the [SQLIT
20760 45 5f 55 53 45 5f 55 52 49 5d 20 63 6f 6d 70 69  E_USE_URI] compi
20770 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a  le-time option..
20780 2a 2a 20 41 73 20 6f 66 20 53 51 4c 69 74 65 20  ** As of SQLite 
20790 76 65 72 73 69 6f 6e 20 33 2e 37 2e 37 2c 20 55  version 3.7.7, U
207a0 52 49 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65  RI filename inte
207b0 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20 74 75  rpretation is tu
207c0 72 6e 65 64 20 6f 66 66 0a 2a 2a 20 62 79 20 64  rned off.** by d
207d0 65 66 61 75 6c 74 2c 20 62 75 74 20 66 75 74 75  efault, but futu
207e0 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53  re releases of S
207f0 51 4c 69 74 65 20 6d 69 67 68 74 20 65 6e 61 62  QLite might enab
20800 6c 65 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 0a  le URI filename.
20810 2a 2a 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f  ** interpretatio
20820 6e 20 62 79 20 64 65 66 61 75 6c 74 2e 20 20 53  n by default.  S
20830 65 65 20 22 5b 55 52 49 20 66 69 6c 65 6e 61 6d  ee "[URI filenam
20840 65 73 5d 22 20 66 6f 72 20 61 64 64 69 74 69 6f  es]" for additio
20850 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  nal.** informati
20860 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 55 52 49 20 66 69  on..**.** URI fi
20870 6c 65 6e 61 6d 65 73 20 61 72 65 20 70 61 72 73  lenames are pars
20880 65 64 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20  ed according to 
20890 52 46 43 20 33 39 38 36 2e 20 5e 49 66 20 74 68  RFC 3986. ^If th
208a0 65 20 55 52 49 20 63 6f 6e 74 61 69 6e 73 20 61  e URI contains a
208b0 6e 0a 2a 2a 20 61 75 74 68 6f 72 69 74 79 2c 20  n.** authority, 
208c0 74 68 65 6e 20 69 74 20 6d 75 73 74 20 62 65 20  then it must be 
208d0 65 69 74 68 65 72 20 61 6e 20 65 6d 70 74 79 20  either an empty 
208e0 73 74 72 69 6e 67 20 6f 72 20 74 68 65 20 73 74  string or the st
208f0 72 69 6e 67 20 0a 2a 2a 20 22 6c 6f 63 61 6c 68  ring .** "localh
20900 6f 73 74 22 2e 20 5e 49 66 20 74 68 65 20 61 75  ost". ^If the au
20910 74 68 6f 72 69 74 79 20 69 73 20 6e 6f 74 20 61  thority is not a
20920 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20 6f  n empty string o
20930 72 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2c 20 61  r "localhost", a
20940 6e 20 0a 2a 2a 20 65 72 72 6f 72 20 69 73 20 72  n .** error is r
20950 65 74 75 72 6e 65 64 20 74 6f 20 74 68 65 20 63  eturned to the c
20960 61 6c 6c 65 72 2e 20 5e 54 68 65 20 66 72 61 67  aller. ^The frag
20970 6d 65 6e 74 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f  ment component o
20980 66 20 61 20 55 52 49 2c 20 69 66 20 0a 2a 2a 20  f a URI, if .** 
20990 70 72 65 73 65 6e 74 2c 20 69 73 20 69 67 6e 6f  present, is igno
209a0 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69  red..**.** ^SQLi
209b0 74 65 20 75 73 65 73 20 74 68 65 20 70 61 74 68  te uses the path
209c0 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 74 68   component of th
209d0 65 20 55 52 49 20 61 73 20 74 68 65 20 6e 61 6d  e URI as the nam
209e0 65 20 6f 66 20 74 68 65 20 64 69 73 6b 20 66 69  e of the disk fi
209f0 6c 65 0a 2a 2a 20 77 68 69 63 68 20 63 6f 6e 74  le.** which cont
20a00 61 69 6e 73 20 74 68 65 20 64 61 74 61 62 61 73  ains the databas
20a10 65 2e 20 5e 49 66 20 74 68 65 20 70 61 74 68 20  e. ^If the path 
20a20 62 65 67 69 6e 73 20 77 69 74 68 20 61 20 27 2f  begins with a '/
20a30 27 20 63 68 61 72 61 63 74 65 72 2c 20 0a 2a 2a  ' character, .**
20a40 20 74 68 65 6e 20 69 74 20 69 73 20 69 6e 74 65   then it is inte
20a50 72 70 72 65 74 65 64 20 61 73 20 61 6e 20 61 62  rpreted as an ab
20a60 73 6f 6c 75 74 65 20 70 61 74 68 2e 20 5e 49 66  solute path. ^If
20a70 20 74 68 65 20 70 61 74 68 20 64 6f 65 73 20 6e   the path does n
20a80 6f 74 20 62 65 67 69 6e 20 0a 2a 2a 20 77 69 74  ot begin .** wit
20a90 68 20 61 20 27 2f 27 20 28 6d 65 61 6e 69 6e 67  h a '/' (meaning
20aa0 20 74 68 61 74 20 74 68 65 20 61 75 74 68 6f 72   that the author
20ab0 69 74 79 20 73 65 63 74 69 6f 6e 20 69 73 20 6f  ity section is o
20ac0 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20  mitted from the 
20ad0 55 52 49 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65  URI).** then the
20ae0 20 70 61 74 68 20 69 73 20 69 6e 74 65 72 70 72   path is interpr
20af0 65 74 65 64 20 61 73 20 61 20 72 65 6c 61 74 69  eted as a relati
20b00 76 65 20 70 61 74 68 2e 20 0a 2a 2a 20 5e 4f 6e  ve path. .** ^On
20b10 20 77 69 6e 64 6f 77 73 2c 20 74 68 65 20 66 69   windows, the fi
20b20 72 73 74 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66  rst component of
20b30 20 61 6e 20 61 62 73 6f 6c 75 74 65 20 70 61 74   an absolute pat
20b40 68 20 0a 2a 2a 20 69 73 20 61 20 64 72 69 76 65  h .** is a drive
20b50 20 73 70 65 63 69 66 69 63 61 74 69 6f 6e 20 28   specification (
20b60 65 2e 67 2e 20 22 43 3a 22 29 2e 0a 2a 2a 0a 2a  e.g. "C:")..**.*
20b70 2a 20 5b 5b 63 6f 72 65 20 55 52 49 20 71 75 65  * [[core URI que
20b80 72 79 20 70 61 72 61 6d 65 74 65 72 73 5d 5d 0a  ry parameters]].
20b90 2a 2a 20 54 68 65 20 71 75 65 72 79 20 63 6f 6d  ** The query com
20ba0 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 20  ponent of a URI 
20bb0 6d 61 79 20 63 6f 6e 74 61 69 6e 20 70 61 72 61  may contain para
20bc0 6d 65 74 65 72 73 20 74 68 61 74 20 61 72 65 20  meters that are 
20bd0 69 6e 74 65 72 70 72 65 74 65 64 0a 2a 2a 20 65  interpreted.** e
20be0 69 74 68 65 72 20 62 79 20 53 51 4c 69 74 65 20  ither by SQLite 
20bf0 69 74 73 65 6c 66 2c 20 6f 72 20 62 79 20 61 20  itself, or by a 
20c00 5b 56 46 53 20 7c 20 63 75 73 74 6f 6d 20 56 46  [VFS | custom VF
20c10 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  S implementation
20c20 5d 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74  ]..** SQLite int
20c30 65 72 70 72 65 74 73 20 74 68 65 20 66 6f 6c 6c  erprets the foll
20c40 6f 77 69 6e 67 20 74 68 72 65 65 20 71 75 65 72  owing three quer
20c50 79 20 70 61 72 61 6d 65 74 65 72 73 3a 0a 2a 2a  y parameters:.**
20c60 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c  .** <ul>.**   <l
20c70 69 3e 20 3c 62 3e 76 66 73 3c 2f 62 3e 3a 20 5e  i> <b>vfs</b>: ^
20c80 54 68 65 20 22 76 66 73 22 20 70 61 72 61 6d 65  The "vfs" parame
20c90 74 65 72 20 6d 61 79 20 62 65 20 75 73 65 64 20  ter may be used 
20ca0 74 6f 20 73 70 65 63 69 66 79 20 74 68 65 20 6e  to specify the n
20cb0 61 6d 65 20 6f 66 0a 2a 2a 20 20 20 20 20 61 20  ame of.**     a 
20cc0 56 46 53 20 6f 62 6a 65 63 74 20 74 68 61 74 20  VFS object that 
20cd0 70 72 6f 76 69 64 65 73 20 74 68 65 20 6f 70 65  provides the ope
20ce0 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69 6e  rating system in
20cf0 74 65 72 66 61 63 65 20 74 68 61 74 20 73 68 6f  terface that sho
20d00 75 6c 64 0a 2a 2a 20 20 20 20 20 62 65 20 75 73  uld.**     be us
20d10 65 64 20 74 6f 20 61 63 63 65 73 73 20 74 68 65  ed to access the
20d20 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 6f   database file o
20d30 6e 20 64 69 73 6b 2e 20 5e 49 66 20 74 68 69 73  n disk. ^If this
20d40 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 20 74   option is set t
20d50 6f 0a 2a 2a 20 20 20 20 20 61 6e 20 65 6d 70 74  o.**     an empt
20d60 79 20 73 74 72 69 6e 67 20 74 68 65 20 64 65 66  y string the def
20d70 61 75 6c 74 20 56 46 53 20 6f 62 6a 65 63 74 20  ault VFS object 
20d80 69 73 20 75 73 65 64 2e 20 5e 53 70 65 63 69 66  is used. ^Specif
20d90 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 0a  ying an unknown.
20da0 2a 2a 20 20 20 20 20 56 46 53 20 69 73 20 61 6e  **     VFS is an
20db0 20 65 72 72 6f 72 2e 20 5e 49 66 20 73 71 6c 69   error. ^If sqli
20dc0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73  te3_open_v2() is
20dd0 20 75 73 65 64 20 61 6e 64 20 74 68 65 20 76 66   used and the vf
20de0 73 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20  s option is.**  
20df0 20 20 20 70 72 65 73 65 6e 74 2c 20 74 68 65 6e     present, then
20e00 20 74 68 65 20 56 46 53 20 73 70 65 63 69 66 69   the VFS specifi
20e10 65 64 20 62 79 20 74 68 65 20 6f 70 74 69 6f 6e  ed by the option
20e20 20 74 61 6b 65 73 20 70 72 65 63 65 64 65 6e 63   takes precedenc
20e30 65 20 6f 76 65 72 0a 2a 2a 20 20 20 20 20 74 68  e over.**     th
20e40 65 20 76 61 6c 75 65 20 70 61 73 73 65 64 20 61  e value passed a
20e50 73 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  s the fourth par
20e60 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
20e70 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a  3_open_v2()..**.
20e80 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 6d 6f 64  **   <li> <b>mod
20e90 65 3c 2f 62 3e 3a 20 5e 28 54 68 65 20 6d 6f 64  e</b>: ^(The mod
20ea0 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20  e parameter may 
20eb0 62 65 20 73 65 74 20 74 6f 20 65 69 74 68 65 72  be set to either
20ec0 20 22 72 6f 22 2c 20 22 72 77 22 2c 0a 2a 2a 20   "ro", "rw",.** 
20ed0 20 20 20 20 22 72 77 63 22 2c 20 6f 72 20 22 6d      "rwc", or "m
20ee0 65 6d 6f 72 79 22 2e 20 41 74 74 65 6d 70 74 69  emory". Attempti
20ef0 6e 67 20 74 6f 20 73 65 74 20 69 74 20 74 6f 20  ng to set it to 
20f00 61 6e 79 20 6f 74 68 65 72 20 76 61 6c 75 65 20  any other value 
20f10 69 73 0a 2a 2a 20 20 20 20 20 61 6e 20 65 72 72  is.**     an err
20f20 6f 72 29 5e 2e 20 0a 2a 2a 20 20 20 20 20 5e 49  or)^. .**     ^I
20f30 66 20 22 72 6f 22 20 69 73 20 73 70 65 63 69 66  f "ro" is specif
20f40 69 65 64 2c 20 74 68 65 6e 20 74 68 65 20 64 61  ied, then the da
20f50 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
20f60 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20 0a   for read-only .
20f70 2a 2a 20 20 20 20 20 61 63 63 65 73 73 2c 20 6a  **     access, j
20f80 75 73 74 20 61 73 20 69 66 20 74 68 65 20 5b 53  ust as if the [S
20f90 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f  QLITE_OPEN_READO
20fa0 4e 4c 59 5d 20 66 6c 61 67 20 68 61 64 20 62 65  NLY] flag had be
20fb0 65 6e 20 73 65 74 20 69 6e 20 74 68 65 20 0a 2a  en set in the .*
20fc0 2a 20 20 20 20 20 74 68 69 72 64 20 61 72 67 75  *     third argu
20fd0 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
20fe0 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 49 66 20 74  open_v2(). ^If t
20ff0 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 69  he mode option i
21000 73 20 73 65 74 20 74 6f 20 0a 2a 2a 20 20 20 20  s set to .**    
21010 20 22 72 77 22 2c 20 74 68 65 6e 20 74 68 65 20   "rw", then the 
21020 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
21030 65 64 20 66 6f 72 20 72 65 61 64 2d 77 72 69 74  ed for read-writ
21040 65 20 28 62 75 74 20 6e 6f 74 20 63 72 65 61 74  e (but not creat
21050 65 29 20 0a 2a 2a 20 20 20 20 20 61 63 63 65 73  e) .**     acces
21060 73 2c 20 61 73 20 69 66 20 53 51 4c 49 54 45 5f  s, as if SQLITE_
21070 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 28  OPEN_READWRITE (
21080 62 75 74 20 6e 6f 74 20 53 51 4c 49 54 45 5f 4f  but not SQLITE_O
21090 50 45 4e 5f 43 52 45 41 54 45 29 20 68 61 64 20  PEN_CREATE) had 
210a0 0a 2a 2a 20 20 20 20 20 62 65 65 6e 20 73 65 74  .**     been set
210b0 2e 20 5e 56 61 6c 75 65 20 22 72 77 63 22 20 69  . ^Value "rwc" i
210c0 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20  s equivalent to 
210d0 73 65 74 74 69 6e 67 20 62 6f 74 68 20 0a 2a 2a  setting both .**
210e0 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e       SQLITE_OPEN
210f0 5f 52 45 41 44 57 52 49 54 45 20 61 6e 64 20 53  _READWRITE and S
21100 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
21110 45 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f 64 65  E.  ^If the mode
21120 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20   option is.**   
21130 20 20 73 65 74 20 74 6f 20 22 6d 65 6d 6f 72 79    set to "memory
21140 22 20 74 68 65 6e 20 61 20 70 75 72 65 20 5b 69  " then a pure [i
21150 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73  n-memory databas
21160 65 5d 20 74 68 61 74 20 6e 65 76 65 72 20 72 65  e] that never re
21170 61 64 73 0a 2a 2a 20 20 20 20 20 6f 72 20 77 72  ads.**     or wr
21180 69 74 65 73 20 66 72 6f 6d 20 64 69 73 6b 20 69  ites from disk i
21190 73 20 75 73 65 64 2e 20 5e 49 74 20 69 73 20 61  s used. ^It is a
211a0 6e 20 65 72 72 6f 72 20 74 6f 20 73 70 65 63 69  n error to speci
211b0 66 79 20 61 20 76 61 6c 75 65 20 66 6f 72 0a 2a  fy a value for.*
211c0 2a 20 20 20 20 20 74 68 65 20 6d 6f 64 65 20 70  *     the mode p
211d0 61 72 61 6d 65 74 65 72 20 74 68 61 74 20 69 73  arameter that is
211e0 20 6c 65 73 73 20 72 65 73 74 72 69 63 74 69 76   less restrictiv
211f0 65 20 74 68 61 6e 20 74 68 61 74 20 73 70 65 63  e than that spec
21200 69 66 69 65 64 20 62 79 0a 2a 2a 20 20 20 20 20  ified by.**     
21210 74 68 65 20 66 6c 61 67 73 20 70 61 73 73 65 64  the flags passed
21220 20 69 6e 20 74 68 65 20 74 68 69 72 64 20 70 61   in the third pa
21230 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
21240 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a  e3_open_v2()..**
21250 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 63 61  .**   <li> <b>ca
21260 63 68 65 3c 2f 62 3e 3a 20 5e 54 68 65 20 63 61  che</b>: ^The ca
21270 63 68 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61  che parameter ma
21280 79 20 62 65 20 73 65 74 20 74 6f 20 65 69 74 68  y be set to eith
21290 65 72 20 22 73 68 61 72 65 64 22 20 6f 72 0a 2a  er "shared" or.*
212a0 2a 20 20 20 20 20 22 70 72 69 76 61 74 65 22 2e  *     "private".
212b0 20 5e 53 65 74 74 69 6e 67 20 69 74 20 74 6f 20   ^Setting it to 
212c0 22 73 68 61 72 65 64 22 20 69 73 20 65 71 75 69  "shared" is equi
212d0 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e  valent to settin
212e0 67 20 74 68 65 0a 2a 2a 20 20 20 20 20 53 51 4c  g the.**     SQL
212f0 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43  ITE_OPEN_SHAREDC
21300 41 43 48 45 20 62 69 74 20 69 6e 20 74 68 65 20  ACHE bit in the 
21310 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 70  flags argument p
21320 61 73 73 65 64 20 74 6f 0a 2a 2a 20 20 20 20 20  assed to.**     
21330 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
21340 29 2e 20 5e 53 65 74 74 69 6e 67 20 74 68 65 20  ). ^Setting the 
21350 63 61 63 68 65 20 70 61 72 61 6d 65 74 65 72 20  cache parameter 
21360 74 6f 20 22 70 72 69 76 61 74 65 22 20 69 73 20  to "private" is 
21370 0a 2a 2a 20 20 20 20 20 65 71 75 69 76 61 6c 65  .**     equivale
21380 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20 74 68  nt to setting th
21390 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52  e SQLITE_OPEN_PR
213a0 49 56 41 54 45 43 41 43 48 45 20 62 69 74 2e 0a  IVATECACHE bit..
213b0 2a 2a 20 20 20 20 20 5e 49 66 20 73 71 6c 69 74  **     ^If sqlit
213c0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20  e3_open_v2() is 
213d0 75 73 65 64 20 61 6e 64 20 74 68 65 20 22 63 61  used and the "ca
213e0 63 68 65 22 20 70 61 72 61 6d 65 74 65 72 20 69  che" parameter i
213f0 73 20 70 72 65 73 65 6e 74 20 69 6e 0a 2a 2a 20  s present in.** 
21400 20 20 20 20 61 20 55 52 49 20 66 69 6c 65 6e 61      a URI filena
21410 6d 65 2c 20 69 74 73 20 76 61 6c 75 65 20 6f 76  me, its value ov
21420 65 72 72 69 64 65 73 20 61 6e 79 20 62 65 68 61  errides any beha
21430 76 69 6f 72 20 72 65 71 75 65 73 74 65 64 20 62  vior requested b
21440 79 20 73 65 74 74 69 6e 67 0a 2a 2a 20 20 20 20  y setting.**    
21450 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49   SQLITE_OPEN_PRI
21460 56 41 54 45 43 41 43 48 45 20 6f 72 20 53 51 4c  VATECACHE or SQL
21470 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43  ITE_OPEN_SHAREDC
21480 41 43 48 45 20 66 6c 61 67 2e 0a 2a 2a 20 3c 2f  ACHE flag..** </
21490 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 53 70 65 63 69  ul>.**.** ^Speci
214a0 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e  fying an unknown
214b0 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68   parameter in th
214c0 65 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e  e query componen
214d0 74 20 6f 66 20 61 20 55 52 49 20 69 73 20 6e 6f  t of a URI is no
214e0 74 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 2e 20 20  t an.** error.  
214f0 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20  Future versions 
21500 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20  of SQLite might 
21510 75 6e 64 65 72 73 74 61 6e 64 20 61 64 64 69 74  understand addit
21520 69 6f 6e 61 6c 20 71 75 65 72 79 0a 2a 2a 20 70  ional query.** p
21530 61 72 61 6d 65 74 65 72 73 2e 20 20 53 65 65 20  arameters.  See 
21540 22 5b 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  "[query paramete
21550 72 73 20 77 69 74 68 20 73 70 65 63 69 61 6c 20  rs with special 
21560 6d 65 61 6e 69 6e 67 20 74 6f 20 53 51 4c 69 74  meaning to SQLit
21570 65 5d 22 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74  e]" for.** addit
21580 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f  ional informatio
21590 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66  n..**.** [[URI f
215a0 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73  ilename examples
215b0 5d 5d 20 3c 68 33 3e 55 52 49 20 66 69 6c 65 6e  ]] <h3>URI filen
215c0 61 6d 65 20 65 78 61 6d 70 6c 65 73 3c 2f 68 33  ame examples</h3
215d0 3e 0a 2a 2a 0a 2a 2a 20 3c 74 61 62 6c 65 20 62  >.**.** <table b
215e0 6f 72 64 65 72 3d 22 31 22 20 61 6c 69 67 6e 3d  order="1" align=
215f0 63 65 6e 74 65 72 20 63 65 6c 6c 70 61 64 64 69  center cellpaddi
21600 6e 67 3d 35 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68  ng=5>.** <tr><th
21610 3e 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20  > URI filenames 
21620 3c 74 68 3e 20 52 65 73 75 6c 74 73 0a 2a 2a 20  <th> Results.** 
21630 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61  <tr><td> file:da
21640 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20  ta.db <td> .**  
21650 20 20 20 20 20 20 20 20 4f 70 65 6e 20 74 68 65          Open the
21660 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20   file "data.db" 
21670 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 64  in the current d
21680 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 20 3c 74 72  irectory..** <tr
21690 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65  ><td> file:/home
216a0 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 3c 62 72  /fred/data.db<br
216b0 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69  >.**          fi
216c0 6c 65 3a 2f 2f 2f 68 6f 6d 65 2f 66 72 65 64 2f  le:///home/fred/
216d0 64 61 74 61 2e 64 62 20 3c 62 72 3e 20 0a 2a 2a  data.db <br> .**
216e0 20 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f            file:/
216f0 2f 6c 6f 63 61 6c 68 6f 73 74 2f 68 6f 6d 65 2f  /localhost/home/
21700 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 62 72  fred/data.db <br
21710 3e 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20  > <td> .**      
21720 20 20 20 20 4f 70 65 6e 20 74 68 65 20 64 61 74      Open the dat
21730 61 62 61 73 65 20 66 69 6c 65 20 22 2f 68 6f 6d  abase file "/hom
21740 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 22 2e  e/fred/data.db".
21750 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c  .** <tr><td> fil
21760 65 3a 2f 2f 64 61 72 6b 73 74 61 72 2f 68 6f 6d  e://darkstar/hom
21770 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c  e/fred/data.db <
21780 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  td> .**         
21790 20 41 6e 20 65 72 72 6f 72 2e 20 22 64 61 72 6b   An error. "dark
217a0 73 74 61 72 22 20 69 73 20 6e 6f 74 20 61 20 72  star" is not a r
217b0 65 63 6f 67 6e 69 7a 65 64 20 61 75 74 68 6f 72  ecognized author
217c0 69 74 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 20  ity..** <tr><td 
217d0 73 74 79 6c 65 3d 22 77 68 69 74 65 2d 73 70 61  style="white-spa
217e0 63 65 3a 6e 6f 77 72 61 70 22 3e 20 0a 2a 2a 20  ce:nowrap"> .** 
217f0 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f           file://
21800 2f 43 3a 2f 44 6f 63 75 6d 65 6e 74 73 25 32 30  /C:/Documents%20
21810 61 6e 64 25 32 30 53 65 74 74 69 6e 67 73 2f 66  and%20Settings/f
21820 72 65 64 2f 44 65 73 6b 74 6f 70 2f 64 61 74 61  red/Desktop/data
21830 2e 64 62 0a 2a 2a 20 20 20 20 20 3c 74 64 3e 20  .db.**     <td> 
21840 57 69 6e 64 6f 77 73 20 6f 6e 6c 79 3a 20 4f 70  Windows only: Op
21850 65 6e 20 74 68 65 20 66 69 6c 65 20 22 64 61 74  en the file "dat
21860 61 2e 64 62 22 20 6f 6e 20 66 72 65 64 27 73 20  a.db" on fred's 
21870 64 65 73 6b 74 6f 70 20 6f 6e 20 64 72 69 76 65  desktop on drive
21880 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 43 3a 2e  .**          C:.
21890 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 25   Note that the %
218a0 32 30 20 65 73 63 61 70 69 6e 67 20 69 6e 20 74  20 escaping in t
218b0 68 69 73 20 65 78 61 6d 70 6c 65 20 69 73 20 6e  his example is n
218c0 6f 74 20 73 74 72 69 63 74 6c 79 20 0a 2a 2a 20  ot strictly .** 
218d0 20 20 20 20 20 20 20 20 20 6e 65 63 65 73 73 61           necessa
218e0 72 79 20 2d 20 73 70 61 63 65 20 63 68 61 72 61  ry - space chara
218f0 63 74 65 72 73 20 63 61 6e 20 62 65 20 75 73 65  cters can be use
21900 64 20 6c 69 74 65 72 61 6c 6c 79 0a 2a 2a 20 20  d literally.**  
21910 20 20 20 20 20 20 20 20 69 6e 20 55 52 49 20 66          in URI f
21920 69 6c 65 6e 61 6d 65 73 2e 0a 2a 2a 20 3c 74 72  ilenames..** <tr
21930 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e  ><td> file:data.
21940 64 62 3f 6d 6f 64 65 3d 72 6f 26 63 61 63 68 65  db?mode=ro&cache
21950 3d 70 72 69 76 61 74 65 20 3c 74 64 3e 20 0a 2a  =private <td> .*
21960 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20  *          Open 
21970 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20 69  file "data.db" i
21980 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 69  n the current di
21990 72 65 63 74 6f 72 79 20 66 6f 72 20 72 65 61 64  rectory for read
219a0 2d 6f 6e 6c 79 20 61 63 63 65 73 73 2e 0a 2a 2a  -only access..**
219b0 20 20 20 20 20 20 20 20 20 20 52 65 67 61 72 64            Regard
219c0 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20  less of whether 
219d0 6f 72 20 6e 6f 74 20 73 68 61 72 65 64 2d 63 61  or not shared-ca
219e0 63 68 65 20 6d 6f 64 65 20 69 73 20 65 6e 61 62  che mode is enab
219f0 6c 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 20  led by.**       
21a00 20 20 20 64 65 66 61 75 6c 74 2c 20 75 73 65 20     default, use 
21a10 61 20 70 72 69 76 61 74 65 20 63 61 63 68 65 2e  a private cache.
21a20 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c  .** <tr><td> fil
21a30 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74  e:/home/fred/dat
21a40 61 2e 64 62 3f 76 66 73 3d 75 6e 69 78 2d 6e 6f  a.db?vfs=unix-no
21a50 6c 6f 63 6b 20 3c 74 64 3e 0a 2a 2a 20 20 20 20  lock <td>.**    
21a60 20 20 20 20 20 20 4f 70 65 6e 20 66 69 6c 65 20        Open file 
21a70 22 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61  "/home/fred/data
21a80 2e 64 62 22 2e 20 55 73 65 20 74 68 65 20 73 70  .db". Use the sp
21a90 65 63 69 61 6c 20 56 46 53 20 22 75 6e 69 78 2d  ecial VFS "unix-
21aa0 6e 6f 6c 6f 63 6b 22 2e 0a 2a 2a 20 3c 74 72 3e  nolock"..** <tr>
21ab0 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64  <td> file:data.d
21ac0 62 3f 6d 6f 64 65 3d 72 65 61 64 6f 6e 6c 79 20  b?mode=readonly 
21ad0 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20  <td> .**        
21ae0 20 20 41 6e 20 65 72 72 6f 72 2e 20 22 72 65 61    An error. "rea
21af0 64 6f 6e 6c 79 22 20 69 73 20 6e 6f 74 20 61 20  donly" is not a 
21b00 76 61 6c 69 64 20 6f 70 74 69 6f 6e 20 66 6f 72  valid option for
21b10 20 74 68 65 20 22 6d 6f 64 65 22 20 70 61 72 61   the "mode" para
21b20 6d 65 74 65 72 2e 0a 2a 2a 20 3c 2f 74 61 62 6c  meter..** </tabl
21b30 65 3e 0a 2a 2a 0a 2a 2a 20 5e 55 52 49 20 68 65  e>.**.** ^URI he
21b40 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65  xadecimal escape
21b50 20 73 65 71 75 65 6e 63 65 73 20 28 25 48 48 29   sequences (%HH)
21b60 20 61 72 65 20 73 75 70 70 6f 72 74 65 64 20 77   are supported w
21b70 69 74 68 69 6e 20 74 68 65 20 70 61 74 68 20 61  ithin the path a
21b80 6e 64 0a 2a 2a 20 71 75 65 72 79 20 63 6f 6d 70  nd.** query comp
21b90 6f 6e 65 6e 74 73 20 6f 66 20 61 20 55 52 49 2e  onents of a URI.
21ba0 20 41 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65   A hexadecimal e
21bb0 73 63 61 70 65 20 73 65 71 75 65 6e 63 65 20 63  scape sequence c
21bc0 6f 6e 73 69 73 74 73 20 6f 66 20 61 0a 2a 2a 20  onsists of a.** 
21bd0 70 65 72 63 65 6e 74 20 73 69 67 6e 20 2d 20 22  percent sign - "
21be0 25 22 20 2d 20 66 6f 6c 6c 6f 77 65 64 20 62 79  %" - followed by
21bf0 20 65 78 61 63 74 6c 79 20 74 77 6f 20 68 65 78   exactly two hex
21c00 61 64 65 63 69 6d 61 6c 20 64 69 67 69 74 73 20  adecimal digits 
21c10 0a 2a 2a 20 73 70 65 63 69 66 79 69 6e 67 20 61  .** specifying a
21c20 6e 20 6f 63 74 65 74 20 76 61 6c 75 65 2e 20 5e  n octet value. ^
21c30 42 65 66 6f 72 65 20 74 68 65 20 70 61 74 68 20  Before the path 
21c40 6f 72 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65  or query compone
21c50 6e 74 73 20 6f 66 20 61 0a 2a 2a 20 55 52 49 20  nts of a.** URI 
21c60 66 69 6c 65 6e 61 6d 65 20 61 72 65 20 69 6e 74  filename are int
21c70 65 72 70 72 65 74 65 64 2c 20 74 68 65 79 20 61  erpreted, they a
21c80 72 65 20 65 6e 63 6f 64 65 64 20 75 73 69 6e 67  re encoded using
21c90 20 55 54 46 2d 38 20 61 6e 64 20 61 6c 6c 20 0a   UTF-8 and all .
21ca0 2a 2a 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65  ** hexadecimal e
21cb0 73 63 61 70 65 20 73 65 71 75 65 6e 63 65 73 20  scape sequences 
21cc0 72 65 70 6c 61 63 65 64 20 62 79 20 61 20 73 69  replaced by a si
21cd0 6e 67 6c 65 20 62 79 74 65 20 63 6f 6e 74 61 69  ngle byte contai
21ce0 6e 69 6e 67 20 74 68 65 0a 2a 2a 20 63 6f 72 72  ning the.** corr
21cf0 65 73 70 6f 6e 64 69 6e 67 20 6f 63 74 65 74 2e  esponding octet.
21d00 20 49 66 20 74 68 69 73 20 70 72 6f 63 65 73 73   If this process
21d10 20 67 65 6e 65 72 61 74 65 73 20 61 6e 20 69 6e   generates an in
21d20 76 61 6c 69 64 20 55 54 46 2d 38 20 65 6e 63 6f  valid UTF-8 enco
21d30 64 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 72 65 73  ding,.** the res
21d40 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e  ults are undefin
21d50 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74  ed..**.** <b>Not
21d60 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 75 73 65  e to Windows use
21d70 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 65 6e 63  rs:</b>  The enc
21d80 6f 64 69 6e 67 20 75 73 65 64 20 66 6f 72 20 74  oding used for t
21d90 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75  he filename argu
21da0 6d 65 6e 74 0a 2a 2a 20 6f 66 20 73 71 6c 69 74  ment.** of sqlit
21db0 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71  e3_open() and sq
21dc0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
21dd0 6d 75 73 74 20 62 65 20 55 54 46 2d 38 2c 20 6e  must be UTF-8, n
21de0 6f 74 20 77 68 61 74 65 76 65 72 0a 2a 2a 20 63  ot whatever.** c
21df0 6f 64 65 70 61 67 65 20 69 73 20 63 75 72 72 65  odepage is curre
21e00 6e 74 6c 79 20 64 65 66 69 6e 65 64 2e 20 20 46  ntly defined.  F
21e10 69 6c 65 6e 61 6d 65 73 20 63 6f 6e 74 61 69 6e  ilenames contain
21e20 69 6e 67 20 69 6e 74 65 72 6e 61 74 69 6f 6e 61  ing internationa
21e30 6c 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20  l.** characters 
21e40 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65  must be converte
21e50 64 20 74 6f 20 55 54 46 2d 38 20 70 72 69 6f 72  d to UTF-8 prior
21e60 20 74 6f 20 70 61 73 73 69 6e 67 20 74 68 65 6d   to passing them
21e70 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33   into.** sqlite3
21e80 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74  _open() or sqlit
21e90 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a  e3_open_v2()..**
21ea0 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57  .** <b>Note to W
21eb0 69 6e 64 6f 77 73 20 52 75 6e 74 69 6d 65 20 75  indows Runtime u
21ec0 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 74  sers:</b>  The t
21ed0 65 6d 70 6f 72 61 72 79 20 64 69 72 65 63 74 6f  emporary directo
21ee0 72 79 20 6d 75 73 74 20 62 65 20 73 65 74 0a 2a  ry must be set.*
21ef0 2a 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69  * prior to calli
21f00 6e 67 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  ng sqlite3_open(
21f10 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65  ) or sqlite3_ope
21f20 6e 5f 76 32 28 29 2e 20 20 4f 74 68 65 72 77 69  n_v2().  Otherwi
21f30 73 65 2c 20 76 61 72 69 6f 75 73 0a 2a 2a 20 66  se, various.** f
21f40 65 61 74 75 72 65 73 20 74 68 61 74 20 72 65 71  eatures that req
21f50 75 69 72 65 20 74 68 65 20 75 73 65 20 6f 66 20  uire the use of 
21f60 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 73 20  temporary files 
21f70 6d 61 79 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20  may fail..**.** 
21f80 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
21f90 65 33 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f 72  e3_temp_director
21fa0 79 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  y].*/.int sqlite
21fb0 33 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e 73 74 20  3_open(.  const 
21fc0 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20  char *filename, 
21fd0 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69    /* Database fi
21fe0 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a  lename (UTF-8) *
21ff0 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70  /.  sqlite3 **pp
22000 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f  Db          /* O
22010 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61  UT: SQLite db ha
22020 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73  ndle */.);.int s
22030 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 0a 20  qlite3_open16(. 
22040 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 66 69 6c   const void *fil
22050 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61  ename,   /* Data
22060 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55  base filename (U
22070 54 46 2d 31 36 29 20 2a 2f 0a 20 20 73 71 6c 69  TF-16) */.  sqli
22080 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20  te3 **ppDb      
22090 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69      /* OUT: SQLi
220a0 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a  te db handle */.
220b0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f  );.int sqlite3_o
220c0 70 65 6e 5f 76 32 28 0a 20 20 63 6f 6e 73 74 20  pen_v2(.  const 
220d0 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20  char *filename, 
220e0 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69    /* Database fi
220f0 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a  lename (UTF-8) *
22100 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70  /.  sqlite3 **pp
22110 44 62 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 4f  Db,         /* O
22120 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61  UT: SQLite db ha
22130 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 66 6c  ndle */.  int fl
22140 61 67 73 2c 20 20 20 20 20 20 20 20 20 20 20 20  ags,            
22150 20 20 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a 20 20    /* Flags */.  
22160 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56 66 73  const char *zVfs
22170 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20          /* Name 
22180 6f 66 20 56 46 53 20 6d 6f 64 75 6c 65 20 74 6f  of VFS module to
22190 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a   use */.);../*.*
221a0 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61  * CAPI3REF: Obta
221b0 69 6e 20 56 61 6c 75 65 73 20 46 6f 72 20 55 52  in Values For UR
221c0 49 20 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a 0a  I Parameters.**.
221d0 2a 2a 20 54 68 65 73 65 20 61 72 65 20 75 74 69  ** These are uti
221e0 6c 69 74 79 20 72 6f 75 74 69 6e 65 73 2c 20 75  lity routines, u
221f0 73 65 66 75 6c 20 74 6f 20 56 46 53 20 69 6d 70  seful to VFS imp
22200 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 2c 20 74 68  lementations, th
22210 61 74 20 63 68 65 63 6b 0a 2a 2a 20 74 6f 20 73  at check.** to s
22220 65 65 20 69 66 20 61 20 64 61 74 61 62 61 73 65  ee if a database
22230 20 66 69 6c 65 20 77 61 73 20 61 20 55 52 49 20   file was a URI 
22240 74 68 61 74 20 63 6f 6e 74 61 69 6e 65 64 20 61  that contained a
22250 20 73 70 65 63 69 66 69 63 20 71 75 65 72 79 20   specific query 
22260 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2c 20 61  .** parameter, a
22270 6e 64 20 69 66 20 73 6f 20 6f 62 74 61 69 6e 73  nd if so obtains
22280 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68   the value of th
22290 61 74 20 71 75 65 72 79 20 70 61 72 61 6d 65 74  at query paramet
222a0 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 46 20 69  er..**.** If F i
222b0 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  s the database f
222c0 69 6c 65 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20  ilename pointer 
222d0 70 61 73 73 65 64 20 69 6e 74 6f 20 74 68 65 20  passed into the 
222e0 78 4f 70 65 6e 28 29 20 6d 65 74 68 6f 64 20 6f  xOpen() method o
222f0 66 20 0a 2a 2a 20 61 20 56 46 53 20 69 6d 70 6c  f .** a VFS impl
22300 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68 65 6e 20  ementation when 
22310 74 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65  the flags parame
22320 74 65 72 20 74 6f 20 78 4f 70 65 6e 28 29 20 68  ter to xOpen() h
22330 61 73 20 6f 6e 65 20 6f 72 20 0a 2a 2a 20 6d 6f  as one or .** mo
22340 72 65 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54  re of the [SQLIT
22350 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 6f 72 20 5b  E_OPEN_URI] or [
22360 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e  SQLITE_OPEN_MAIN
22370 5f 44 42 5d 20 62 69 74 73 20 73 65 74 20 61 6e  _DB] bits set an
22380 64 0a 2a 2a 20 50 20 69 73 20 74 68 65 20 6e 61  d.** P is the na
22390 6d 65 20 6f 66 20 74 68 65 20 71 75 65 72 79 20  me of the query 
223a0 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65 6e 0a  parameter, then.
223b0 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70  ** sqlite3_uri_p
223c0 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65  arameter(F,P) re
223d0 74 75 72 6e 73 20 74 68 65 20 76 61 6c 75 65 20  turns the value 
223e0 6f 66 20 74 68 65 20 50 0a 2a 2a 20 70 61 72 61  of the P.** para
223f0 6d 65 74 65 72 20 69 66 20 69 74 20 65 78 69 73  meter if it exis
22400 74 73 20 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69  ts or a NULL poi
22410 6e 74 65 72 20 69 66 20 50 20 64 6f 65 73 20 6e  nter if P does n
22420 6f 74 20 61 70 70 65 61 72 20 61 73 20 61 20 0a  ot appear as a .
22430 2a 2a 20 71 75 65 72 79 20 70 61 72 61 6d 65 74  ** query paramet
22440 65 72 20 6f 6e 20 46 2e 20 20 49 66 20 50 20 69  er on F.  If P i
22450 73 20 61 20 71 75 65 72 79 20 70 61 72 61 6d 65  s a query parame
22460 74 65 72 20 6f 66 20 46 0a 2a 2a 20 68 61 73 20  ter of F.** has 
22470 6e 6f 20 65 78 70 6c 69 63 69 74 20 76 61 6c 75  no explicit valu
22480 65 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  e, then sqlite3_
22490 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c  uri_parameter(F,
224a0 50 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20  P) returns.** a 
224b0 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 65 6d  pointer to an em
224c0 70 74 79 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a  pty string..**.*
224d0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72  * The sqlite3_ur
224e0 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29  i_boolean(F,P,B)
224f0 20 72 6f 75 74 69 6e 65 20 61 73 73 75 6d 65 73   routine assumes
22500 20 74 68 61 74 20 50 20 69 73 20 61 20 62 6f 6f   that P is a boo
22510 6c 65 61 6e 0a 2a 2a 20 70 61 72 61 6d 65 74 65  lean.** paramete
22520 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20 74 72  r and returns tr
22530 75 65 20 28 31 29 20 6f 72 20 66 61 6c 73 65 20  ue (1) or false 
22540 28 30 29 20 61 63 63 6f 72 64 69 6e 67 20 74 6f  (0) according to
22550 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 6f 66   the value.** of
22560 20 50 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33   P.  The sqlite3
22570 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50  _uri_boolean(F,P
22580 2c 42 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  ,B) routine retu
22590 72 6e 73 20 74 72 75 65 20 28 31 29 20 69 66 20  rns true (1) if 
225a0 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20  the.** value of 
225b0 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 20  query parameter 
225c0 50 20 69 73 20 6f 6e 65 20 6f 66 20 22 79 65 73  P is one of "yes
225d0 22 2c 20 22 74 72 75 65 22 2c 20 6f 72 20 22 6f  ", "true", or "o
225e0 6e 22 20 69 6e 20 61 6e 79 0a 2a 2a 20 63 61 73  n" in any.** cas
225f0 65 20 6f 72 20 69 66 20 74 68 65 20 76 61 6c 75  e or if the valu
22600 65 20 62 65 67 69 6e 73 20 77 69 74 68 20 61 20  e begins with a 
22610 6e 6f 6e 2d 7a 65 72 6f 20 6e 75 6d 62 65 72 2e  non-zero number.
22620 20 20 54 68 65 20 0a 2a 2a 20 73 71 6c 69 74 65    The .** sqlite
22630 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c  3_uri_boolean(F,
22640 50 2c 42 29 20 72 6f 75 74 69 6e 65 73 20 72 65  P,B) routines re
22650 74 75 72 6e 73 20 66 61 6c 73 65 20 28 30 29 20  turns false (0) 
22660 69 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66 0a  if the value of.
22670 2a 2a 20 71 75 65 72 79 20 70 61 72 61 6d 65 74  ** query paramet
22680 65 72 20 50 20 69 73 20 6f 6e 65 20 6f 66 20 22  er P is one of "
22690 6e 6f 22 2c 20 22 66 61 6c 73 65 22 2c 20 6f 72  no", "false", or
226a0 20 22 6f 66 66 22 20 69 6e 20 61 6e 79 20 63 61   "off" in any ca
226b0 73 65 20 6f 72 0a 2a 2a 20 69 66 20 74 68 65 20  se or.** if the 
226c0 76 61 6c 75 65 20 62 65 67 69 6e 73 20 77 69 74  value begins wit
226d0 68 20 61 20 6e 75 6d 65 72 69 63 20 7a 65 72 6f  h a numeric zero
226e0 2e 20 20 49 66 20 50 20 69 73 20 6e 6f 74 20 61  .  If P is not a
226f0 20 71 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65   query.** parame
22700 74 65 72 20 6f 6e 20 46 20 6f 72 20 69 66 20 74  ter on F or if t
22710 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69 73  he value of P is
22720 20 64 6f 65 73 20 6e 6f 74 20 6d 61 74 63 68 20   does not match 
22730 61 6e 79 20 6f 66 20 74 68 65 0a 2a 2a 20 61 62  any of the.** ab
22740 6f 76 65 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  ove, then sqlite
22750 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c  3_uri_boolean(F,
22760 50 2c 42 29 20 72 65 74 75 72 6e 73 20 28 42 21  P,B) returns (B!
22770 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  =0)..**.** The s
22780 71 6c 69 74 65 33 5f 75 72 69 5f 69 6e 74 36 34  qlite3_uri_int64
22790 28 46 2c 50 2c 44 29 20 72 6f 75 74 69 6e 65 20  (F,P,D) routine 
227a0 63 6f 6e 76 65 72 74 73 20 74 68 65 20 76 61 6c  converts the val
227b0 75 65 20 6f 66 20 50 20 69 6e 74 6f 20 61 0a 2a  ue of P into a.*
227c0 2a 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20  * 64-bit signed 
227d0 69 6e 74 65 67 65 72 20 61 6e 64 20 72 65 74 75  integer and retu
227e0 72 6e 73 20 74 68 61 74 20 69 6e 74 65 67 65 72  rns that integer
227f0 2c 20 6f 72 20 44 20 69 66 20 50 20 64 6f 65 73  , or D if P does
22800 20 6e 6f 74 0a 2a 2a 20 65 78 69 73 74 2e 20 20   not.** exist.  
22810 49 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  If the value of 
22820 50 20 69 73 20 73 6f 6d 65 74 68 69 6e 67 20 6f  P is something o
22830 74 68 65 72 20 74 68 61 6e 20 61 6e 20 69 6e 74  ther than an int
22840 65 67 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 7a 65  eger, then.** ze
22850 72 6f 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  ro is returned..
22860 2a 2a 20 0a 2a 2a 20 49 66 20 46 20 69 73 20 61  ** .** If F is a
22870 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74   NULL pointer, t
22880 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  hen sqlite3_uri_
22890 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72  parameter(F,P) r
228a0 65 74 75 72 6e 73 20 4e 55 4c 4c 20 61 6e 64 0a  eturns NULL and.
228b0 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62  ** sqlite3_uri_b
228c0 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 65  oolean(F,P,B) re
228d0 74 75 72 6e 73 20 42 2e 20 20 49 66 20 46 20 69  turns B.  If F i
228e0 73 20 6e 6f 74 20 61 20 4e 55 4c 4c 20 70 6f 69  s not a NULL poi
228f0 6e 74 65 72 20 61 6e 64 0a 2a 2a 20 69 73 20 6e  nter and.** is n
22900 6f 74 20 61 20 64 61 74 61 62 61 73 65 20 66 69  ot a database fi
22910 6c 65 20 70 61 74 68 6e 61 6d 65 20 70 6f 69 6e  le pathname poin
22920 74 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 20  ter that SQLite 
22930 70 61 73 73 65 64 20 69 6e 74 6f 20 74 68 65 20  passed into the 
22940 78 4f 70 65 6e 0a 2a 2a 20 56 46 53 20 6d 65 74  xOpen.** VFS met
22950 68 6f 64 2c 20 74 68 65 6e 20 74 68 65 20 62 65  hod, then the be
22960 68 61 76 69 6f 72 20 6f 66 20 74 68 69 73 20 72  havior of this r
22970 6f 75 74 69 6e 65 20 69 73 20 75 6e 64 65 66 69  outine is undefi
22980 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79  ned and probably
22990 0a 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c 65 2e  .** undesirable.
229a0 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  .*/.const char *
229b0 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61  sqlite3_uri_para
229c0 6d 65 74 65 72 28 63 6f 6e 73 74 20 63 68 61 72  meter(const char
229d0 20 2a 7a 46 69 6c 65 6e 61 6d 65 2c 20 63 6f 6e   *zFilename, con
229e0 73 74 20 63 68 61 72 20 2a 7a 50 61 72 61 6d 29  st char *zParam)
229f0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 75 72  ;.int sqlite3_ur
22a00 69 5f 62 6f 6f 6c 65 61 6e 28 63 6f 6e 73 74 20  i_boolean(const 
22a10 63 68 61 72 20 2a 7a 46 69 6c 65 2c 20 63 6f 6e  char *zFile, con
22a20 73 74 20 63 68 61 72 20 2a 7a 50 61 72 61 6d 2c  st char *zParam,
22a30 20 69 6e 74 20 62 44 65 66 61 75 6c 74 29 3b 0a   int bDefault);.
22a40 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71  sqlite3_int64 sq
22a50 6c 69 74 65 33 5f 75 72 69 5f 69 6e 74 36 34 28  lite3_uri_int64(
22a60 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 63 6f 6e  const char*, con
22a70 73 74 20 63 68 61 72 2a 2c 20 73 71 6c 69 74 65  st char*, sqlite
22a80 33 5f 69 6e 74 36 34 29 3b 0a 0a 0a 2f 2a 0a 2a  3_int64);.../*.*
22a90 2a 20 43 41 50 49 33 52 45 46 3a 20 45 72 72 6f  * CAPI3REF: Erro
22aa0 72 20 43 6f 64 65 73 20 41 6e 64 20 4d 65 73 73  r Codes And Mess
22ab0 61 67 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ages.**.** ^The 
22ac0 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
22ad0 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
22ae0 72 6e 73 20 74 68 65 20 6e 75 6d 65 72 69 63 20  rns the numeric 
22af0 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72  [result code] or
22b00 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65  .** [extended re
22b10 73 75 6c 74 20 63 6f 64 65 5d 20 66 6f 72 20 74  sult code] for t
22b20 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 66  he most recent f
22b30 61 69 6c 65 64 20 73 71 6c 69 74 65 33 5f 2a 20  ailed sqlite3_* 
22b40 41 50 49 20 63 61 6c 6c 0a 2a 2a 20 61 73 73 6f  API call.** asso
22b50 63 69 61 74 65 64 20 77 69 74 68 20 61 20 5b 64  ciated with a [d
22b60 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
22b70 6f 6e 5d 2e 20 49 66 20 61 20 70 72 69 6f 72 20  on]. If a prior 
22b80 41 50 49 20 63 61 6c 6c 20 66 61 69 6c 65 64 0a  API call failed.
22b90 2a 2a 20 62 75 74 20 74 68 65 20 6d 6f 73 74 20  ** but the most 
22ba0 72 65 63 65 6e 74 20 41 50 49 20 63 61 6c 6c 20  recent API call 
22bb0 73 75 63 63 65 65 64 65 64 2c 20 74 68 65 20 72  succeeded, the r
22bc0 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d  eturn value from
22bd0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 72 72 63  .** sqlite3_errc
22be0 6f 64 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e  ode() is undefin
22bf0 65 64 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65  ed.  ^The sqlite
22c00 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f  3_extended_errco
22c10 64 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  de().** interfac
22c20 65 20 69 73 20 74 68 65 20 73 61 6d 65 20 65 78  e is the same ex
22c30 63 65 70 74 20 74 68 61 74 20 69 74 20 61 6c 77  cept that it alw
22c40 61 79 73 20 72 65 74 75 72 6e 73 20 74 68 65 20  ays returns the 
22c50 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65  .** [extended re
22c60 73 75 6c 74 20 63 6f 64 65 5d 20 65 76 65 6e 20  sult code] even 
22c70 77 68 65 6e 20 65 78 74 65 6e 64 65 64 20 72 65  when extended re
22c80 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 0a 2a  sult codes are.*
22c90 2a 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a  * disabled..**.*
22ca0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65  * ^The sqlite3_e
22cb0 72 72 6d 73 67 28 29 20 61 6e 64 20 73 71 6c 69  rrmsg() and sqli
22cc0 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 20 72  te3_errmsg16() r
22cd0 65 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d 6c 61  eturn English-la
22ce0 6e 67 75 61 67 65 0a 2a 2a 20 74 65 78 74 20 74  nguage.** text t
22cf0 68 61 74 20 64 65 73 63 72 69 62 65 73 20 74 68  hat describes th
22d00 65 20 65 72 72 6f 72 2c 20 61 73 20 65 69 74 68  e error, as eith
22d10 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d  er UTF-8 or UTF-
22d20 31 36 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  16 respectively.
22d30 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20  .** ^(Memory to 
22d40 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d  hold the error m
22d50 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73  essage string is
22d60 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61   managed interna
22d70 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c  lly..** The appl
22d80 69 63 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74  ication does not
22d90 20 6e 65 65 64 20 74 6f 20 77 6f 72 72 79 20 61   need to worry a
22da0 62 6f 75 74 20 66 72 65 65 69 6e 67 20 74 68 65  bout freeing the
22db0 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65   result..** Howe
22dc0 76 65 72 2c 20 74 68 65 20 65 72 72 6f 72 20 73  ver, the error s
22dd0 74 72 69 6e 67 20 6d 69 67 68 74 20 62 65 20 6f  tring might be o
22de0 76 65 72 77 72 69 74 74 65 6e 20 6f 72 20 64 65  verwritten or de
22df0 61 6c 6c 6f 63 61 74 65 64 20 62 79 0a 2a 2a 20  allocated by.** 
22e00 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73  subsequent calls
22e10 20 74 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65   to other SQLite
22e20 20 69 6e 74 65 72 66 61 63 65 20 66 75 6e 63 74   interface funct
22e30 69 6f 6e 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54  ions.)^.**.** ^T
22e40 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 73 74  he sqlite3_errst
22e50 72 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  r() interface re
22e60 74 75 72 6e 73 20 74 68 65 20 45 6e 67 6c 69 73  turns the Englis
22e70 68 2d 6c 61 6e 67 75 61 67 65 20 74 65 78 74 0a  h-language text.
22e80 2a 2a 20 74 68 61 74 20 64 65 73 63 72 69 62 65  ** that describe
22e90 73 20 74 68 65 20 5b 72 65 73 75 6c 74 20 63 6f  s the [result co
22ea0 64 65 5d 2c 20 61 73 20 55 54 46 2d 38 2e 0a 2a  de], as UTF-8..*
22eb0 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f  * ^(Memory to ho
22ec0 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73  ld the error mes
22ed0 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 6d  sage string is m
22ee0 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c  anaged internall
22ef0 79 0a 2a 2a 20 61 6e 64 20 6d 75 73 74 20 6e 6f  y.** and must no
22f00 74 20 62 65 20 66 72 65 65 64 20 62 79 20 74 68  t be freed by th
22f10 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 29 5e 2e  e application)^.
22f20 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20  .**.** When the 
22f30 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65  serialized [thre
22f40 61 64 69 6e 67 20 6d 6f 64 65 5d 20 69 73 20 69  ading mode] is i
22f50 6e 20 75 73 65 2c 20 69 74 20 6d 69 67 68 74 20  n use, it might 
22f60 62 65 20 74 68 65 0a 2a 2a 20 63 61 73 65 20 74  be the.** case t
22f70 68 61 74 20 61 20 73 65 63 6f 6e 64 20 65 72 72  hat a second err
22f80 6f 72 20 6f 63 63 75 72 73 20 6f 6e 20 61 20 73  or occurs on a s
22f90 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20 69  eparate thread i
22fa0 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65  n between.** the
22fb0 20 74 69 6d 65 20 6f 66 20 74 68 65 20 66 69 72   time of the fir
22fc0 73 74 20 65 72 72 6f 72 20 61 6e 64 20 74 68 65  st error and the
22fd0 20 63 61 6c 6c 20 74 6f 20 74 68 65 73 65 20 69   call to these i
22fe0 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 57 68  nterfaces..** Wh
22ff0 65 6e 20 74 68 61 74 20 68 61 70 70 65 6e 73 2c  en that happens,
23000 20 74 68 65 20 73 65 63 6f 6e 64 20 65 72 72 6f   the second erro
23010 72 20 77 69 6c 6c 20 62 65 20 72 65 70 6f 72 74  r will be report
23020 65 64 20 73 69 6e 63 65 20 74 68 65 73 65 0a 2a  ed since these.*
23030 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61 6c 77  * interfaces alw
23040 61 79 73 20 72 65 70 6f 72 74 20 74 68 65 20 6d  ays report the m
23050 6f 73 74 20 72 65 63 65 6e 74 20 72 65 73 75 6c  ost recent resul
23060 74 2e 20 20 54 6f 20 61 76 6f 69 64 0a 2a 2a 20  t.  To avoid.** 
23070 74 68 69 73 2c 20 65 61 63 68 20 74 68 72 65 61  this, each threa
23080 64 20 63 61 6e 20 6f 62 74 61 69 6e 20 65 78 63  d can obtain exc
23090 6c 75 73 69 76 65 20 75 73 65 20 6f 66 20 74 68  lusive use of th
230a0 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
230b0 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20 62 79 20  ection] D.** by 
230c0 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65  invoking [sqlite
230d0 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 5d 28 5b  3_mutex_enter]([
230e0 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78  sqlite3_db_mutex
230f0 5d 28 44 29 29 20 62 65 66 6f 72 65 20 62 65 67  ](D)) before beg
23100 69 6e 6e 69 6e 67 0a 2a 2a 20 74 6f 20 75 73 65  inning.** to use
23110 20 44 20 61 6e 64 20 69 6e 76 6f 6b 69 6e 67 20   D and invoking 
23120 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c  [sqlite3_mutex_l
23130 65 61 76 65 5d 28 5b 73 71 6c 69 74 65 33 5f 64  eave]([sqlite3_d
23140 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 61 66 74  b_mutex](D)) aft
23150 65 72 0a 2a 2a 20 61 6c 6c 20 63 61 6c 6c 73 20  er.** all calls 
23160 74 6f 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  to the interface
23170 73 20 6c 69 73 74 65 64 20 68 65 72 65 20 61 72  s listed here ar
23180 65 20 63 6f 6d 70 6c 65 74 65 64 2e 0a 2a 2a 0a  e completed..**.
23190 2a 2a 20 49 66 20 61 6e 20 69 6e 74 65 72 66 61  ** If an interfa
231a0 63 65 20 66 61 69 6c 73 20 77 69 74 68 20 53 51  ce fails with SQ
231b0 4c 49 54 45 5f 4d 49 53 55 53 45 2c 20 74 68 61  LITE_MISUSE, tha
231c0 74 20 6d 65 61 6e 73 20 74 68 65 20 69 6e 74 65  t means the inte
231d0 72 66 61 63 65 0a 2a 2a 20 77 61 73 20 69 6e 76  rface.** was inv
231e0 6f 6b 65 64 20 69 6e 63 6f 72 72 65 63 74 6c 79  oked incorrectly
231f0 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74   by the applicat
23200 69 6f 6e 2e 20 20 49 6e 20 74 68 61 74 20 63 61  ion.  In that ca
23210 73 65 2c 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72  se, the.** error
23220 20 63 6f 64 65 20 61 6e 64 20 6d 65 73 73 61 67   code and messag
23230 65 20 6d 61 79 20 6f 72 20 6d 61 79 20 6e 6f 74  e may or may not
23240 20 62 65 20 73 65 74 2e 0a 2a 2f 0a 69 6e 74 20   be set..*/.int 
23250 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
23260 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 69 6e  sqlite3 *db);.in
23270 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64  t sqlite3_extend
23280 65 64 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74  ed_errcode(sqlit
23290 65 33 20 2a 64 62 29 3b 0a 63 6f 6e 73 74 20 63  e3 *db);.const c
232a0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 72 72  har *sqlite3_err
232b0 6d 73 67 28 73 71 6c 69 74 65 33 2a 29 3b 0a 63  msg(sqlite3*);.c
232c0 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
232d0 65 33 5f 65 72 72 6d 73 67 31 36 28 73 71 6c 69  e3_errmsg16(sqli
232e0 74 65 33 2a 29 3b 0a 63 6f 6e 73 74 20 63 68 61  te3*);.const cha
232f0 72 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 73 74  r *sqlite3_errst
23300 72 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  r(int);../*.** C
23310 41 50 49 33 52 45 46 3a 20 53 51 4c 20 53 74 61  API3REF: SQL Sta
23320 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a  tement Object.**
23330 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 65 70   KEYWORDS: {prep
23340 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 7d 20  ared statement} 
23350 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  {prepared statem
23360 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69  ents}.**.** An i
23370 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20  nstance of this 
23380 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74  object represent
23390 73 20 61 20 73 69 6e 67 6c 65 20 53 51 4c 20 73  s a single SQL s
233a0 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 54 68 69  tatement..** Thi
233b0 73 20 6f 62 6a 65 63 74 20 69 73 20 76 61 72 69  s object is vari
233c0 6f 75 73 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 61  ously known as a
233d0 20 22 70 72 65 70 61 72 65 64 20 73 74 61 74 65   "prepared state
233e0 6d 65 6e 74 22 20 6f 72 20 61 0a 2a 2a 20 22 63  ment" or a.** "c
233f0 6f 6d 70 69 6c 65 64 20 53 51 4c 20 73 74 61 74  ompiled SQL stat
23400 65 6d 65 6e 74 22 20 6f 72 20 73 69 6d 70 6c 79  ement" or simply
23410 20 61 73 20 61 20 22 73 74 61 74 65 6d 65 6e 74   as a "statement
23420 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69 66  "..**.** The lif
23430 65 20 6f 66 20 61 20 73 74 61 74 65 6d 65 6e 74  e of a statement
23440 20 6f 62 6a 65 63 74 20 67 6f 65 73 20 73 6f 6d   object goes som
23450 65 74 68 69 6e 67 20 6c 69 6b 65 20 74 68 69 73  ething like this
23460 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20  :.**.** <ol>.** 
23470 3c 6c 69 3e 20 43 72 65 61 74 65 20 74 68 65 20  <li> Create the 
23480 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71  object using [sq
23490 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
234a0 28 29 5d 20 6f 72 20 61 20 72 65 6c 61 74 65 64  ()] or a related
234b0 0a 2a 2a 20 20 20 20 20 20 66 75 6e 63 74 69 6f  .**      functio
234c0 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e 64 20  n..** <li> Bind 
234d0 76 61 6c 75 65 73 20 74 6f 20 5b 68 6f 73 74 20  values to [host 
234e0 70 61 72 61 6d 65 74 65 72 73 5d 20 75 73 69 6e  parameters] usin
234f0 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69  g the sqlite3_bi
23500 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20 20 20 20 69  nd_*().**      i
23510 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 3c 6c  nterfaces..** <l
23520 69 3e 20 52 75 6e 20 74 68 65 20 53 51 4c 20 62  i> Run the SQL b
23530 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  y calling [sqlit
23540 65 33 5f 73 74 65 70 28 29 5d 20 6f 6e 65 20 6f  e3_step()] one o
23550 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a  r more times..**
23560 20 3c 6c 69 3e 20 52 65 73 65 74 20 74 68 65 20   <li> Reset the 
23570 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20  statement using 
23580 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
23590 5d 20 74 68 65 6e 20 67 6f 20 62 61 63 6b 0a 2a  ] then go back.*
235a0 2a 20 20 20 20 20 20 74 6f 20 73 74 65 70 20 32  *      to step 2
235b0 2e 20 20 44 6f 20 74 68 69 73 20 7a 65 72 6f 20  .  Do this zero 
235c0 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a  or more times..*
235d0 2a 20 3c 6c 69 3e 20 44 65 73 74 72 6f 79 20 74  * <li> Destroy t
235e0 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20  he object using 
235f0 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
23600 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a  e()]..** </ol>.*
23610 2a 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20 64 6f  *.** Refer to do
23620 63 75 6d 65 6e 74 61 74 69 6f 6e 20 6f 6e 20 69  cumentation on i
23630 6e 64 69 76 69 64 75 61 6c 20 6d 65 74 68 6f 64  ndividual method
23640 73 20 61 62 6f 76 65 20 66 6f 72 20 61 64 64 69  s above for addi
23650 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d  tional.** inform
23660 61 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65  ation..*/.typede
23670 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
23680 5f 73 74 6d 74 20 73 71 6c 69 74 65 33 5f 73 74  _stmt sqlite3_st
23690 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  mt;../*.** CAPI3
236a0 52 45 46 3a 20 52 75 6e 2d 74 69 6d 65 20 4c 69  REF: Run-time Li
236b0 6d 69 74 73 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69  mits.**.** ^(Thi
236c0 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f  s interface allo
236d0 77 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 76  ws the size of v
236e0 61 72 69 6f 75 73 20 63 6f 6e 73 74 72 75 63 74  arious construct
236f0 73 20 74 6f 20 62 65 20 6c 69 6d 69 74 65 64 0a  s to be limited.
23700 2a 2a 20 6f 6e 20 61 20 63 6f 6e 6e 65 63 74 69  ** on a connecti
23710 6f 6e 20 62 79 20 63 6f 6e 6e 65 63 74 69 6f 6e  on by connection
23720 20 62 61 73 69 73 2e 20 20 54 68 65 20 66 69 72   basis.  The fir
23730 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  st parameter is 
23740 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  the.** [database
23750 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 68 6f   connection] who
23760 73 65 20 6c 69 6d 69 74 20 69 73 20 74 6f 20 62  se limit is to b
23770 65 20 73 65 74 20 6f 72 20 71 75 65 72 69 65 64  e set or queried
23780 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64  .  The.** second
23790 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6f 6e   parameter is on
237a0 65 20 6f 66 20 74 68 65 20 5b 6c 69 6d 69 74 20  e of the [limit 
237b0 63 61 74 65 67 6f 72 69 65 73 5d 20 74 68 61 74  categories] that
237c0 20 64 65 66 69 6e 65 20 61 0a 2a 2a 20 63 6c 61   define a.** cla
237d0 73 73 20 6f 66 20 63 6f 6e 73 74 72 75 63 74 73  ss of constructs
237e0 20 74 6f 20 62 65 20 73 69 7a 65 20 6c 69 6d 69   to be size limi
237f0 74 65 64 2e 20 20 54 68 65 20 74 68 69 72 64 20  ted.  The third 
23800 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
23810 0a 2a 2a 20 6e 65 77 20 6c 69 6d 69 74 20 66 6f  .** new limit fo
23820 72 20 74 68 61 74 20 63 6f 6e 73 74 72 75 63 74  r that construct
23830 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  .)^.**.** ^If th
23840 65 20 6e 65 77 20 6c 69 6d 69 74 20 69 73 20 61  e new limit is a
23850 20 6e 65 67 61 74 69 76 65 20 6e 75 6d 62 65 72   negative number
23860 2c 20 74 68 65 20 6c 69 6d 69 74 20 69 73 20 75  , the limit is u
23870 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 5e 28 46  nchanged..** ^(F
23880 6f 72 20 65 61 63 68 20 6c 69 6d 69 74 20 63 61  or each limit ca
23890 74 65 67 6f 72 79 20 53 51 4c 49 54 45 5f 4c 49  tegory SQLITE_LI
238a0 4d 49 54 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 20  MIT_<i>NAME</i> 
238b0 74 68 65 72 65 20 69 73 20 61 20 0a 2a 2a 20 5b  there is a .** [
238c0 6c 69 6d 69 74 73 20 7c 20 68 61 72 64 20 75 70  limits | hard up
238d0 70 65 72 20 62 6f 75 6e 64 5d 0a 2a 2a 20 73 65  per bound].** se
238e0 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  t at compile-tim
238f0 65 20 62 79 20 61 20 43 20 70 72 65 70 72 6f 63  e by a C preproc
23900 65 73 73 6f 72 20 6d 61 63 72 6f 20 63 61 6c 6c  essor macro call
23910 65 64 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20  ed.** [limits | 
23920 53 51 4c 49 54 45 5f 4d 41 58 5f 3c 69 3e 4e 41  SQLITE_MAX_<i>NA
23930 4d 45 3c 2f 69 3e 5d 2e 0a 2a 2a 20 28 54 68 65  ME</i>]..** (The
23940 20 22 5f 4c 49 4d 49 54 5f 22 20 69 6e 20 74 68   "_LIMIT_" in th
23950 65 20 6e 61 6d 65 20 69 73 20 63 68 61 6e 67 65  e name is change
23960 64 20 74 6f 20 22 5f 4d 41 58 5f 22 2e 29 29 5e  d to "_MAX_".))^
23970 0a 2a 2a 20 5e 41 74 74 65 6d 70 74 73 20 74 6f  .** ^Attempts to
23980 20 69 6e 63 72 65 61 73 65 20 61 20 6c 69 6d 69   increase a limi
23990 74 20 61 62 6f 76 65 20 69 74 73 20 68 61 72 64  t above its hard
239a0 20 75 70 70 65 72 20 62 6f 75 6e 64 20 61 72 65   upper bound are
239b0 0a 2a 2a 20 73 69 6c 65 6e 74 6c 79 20 74 72 75  .** silently tru
239c0 6e 63 61 74 65 64 20 74 6f 20 74 68 65 20 68 61  ncated to the ha
239d0 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 2e 0a  rd upper bound..
239e0 2a 2a 0a 2a 2a 20 5e 52 65 67 61 72 64 6c 65 73  **.** ^Regardles
239f0 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20  s of whether or 
23a00 6e 6f 74 20 74 68 65 20 6c 69 6d 69 74 20 77 61  not the limit wa
23a10 73 20 63 68 61 6e 67 65 64 2c 20 74 68 65 20 0a  s changed, the .
23a20 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69  ** [sqlite3_limi
23a30 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  t()] interface r
23a40 65 74 75 72 6e 73 20 74 68 65 20 70 72 69 6f 72  eturns the prior
23a50 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 6c 69   value of the li
23a60 6d 69 74 2e 0a 2a 2a 20 5e 48 65 6e 63 65 2c 20  mit..** ^Hence, 
23a70 74 6f 20 66 69 6e 64 20 74 68 65 20 63 75 72 72  to find the curr
23a80 65 6e 74 20 76 61 6c 75 65 20 6f 66 20 61 20 6c  ent value of a l
23a90 69 6d 69 74 20 77 69 74 68 6f 75 74 20 63 68 61  imit without cha
23aa0 6e 67 69 6e 67 20 69 74 2c 0a 2a 2a 20 73 69 6d  nging it,.** sim
23ab0 70 6c 79 20 69 6e 76 6f 6b 65 20 74 68 69 73 20  ply invoke this 
23ac0 69 6e 74 65 72 66 61 63 65 20 77 69 74 68 20 74  interface with t
23ad0 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
23ae0 65 72 20 73 65 74 20 74 6f 20 2d 31 2e 0a 2a 2a  er set to -1..**
23af0 0a 2a 2a 20 52 75 6e 2d 74 69 6d 65 20 6c 69 6d  .** Run-time lim
23b00 69 74 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64  its are intended
23b10 20 66 6f 72 20 75 73 65 20 69 6e 20 61 70 70 6c   for use in appl
23b20 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6d 61  ications that ma
23b30 6e 61 67 65 0a 2a 2a 20 62 6f 74 68 20 74 68 65  nage.** both the
23b40 69 72 20 6f 77 6e 20 69 6e 74 65 72 6e 61 6c 20  ir own internal 
23b50 64 61 74 61 62 61 73 65 20 61 6e 64 20 61 6c 73  database and als
23b60 6f 20 64 61 74 61 62 61 73 65 73 20 74 68 61 74  o databases that
23b70 20 61 72 65 20 63 6f 6e 74 72 6f 6c 6c 65 64 0a   are controlled.
23b80 2a 2a 20 62 79 20 75 6e 74 72 75 73 74 65 64 20  ** by untrusted 
23b90 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73  external sources
23ba0 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 61 70  .  An example ap
23bb0 70 6c 69 63 61 74 69 6f 6e 20 6d 69 67 68 74 20  plication might 
23bc0 62 65 20 61 0a 2a 2a 20 77 65 62 20 62 72 6f 77  be a.** web brow
23bd0 73 65 72 20 74 68 61 74 20 68 61 73 20 69 74 73  ser that has its
23be0 20 6f 77 6e 20 64 61 74 61 62 61 73 65 73 20 66   own databases f
23bf0 6f 72 20 73 74 6f 72 69 6e 67 20 68 69 73 74 6f  or storing histo
23c00 72 79 20 61 6e 64 0a 2a 2a 20 73 65 70 61 72 61  ry and.** separa
23c10 74 65 20 64 61 74 61 62 61 73 65 73 20 63 6f 6e  te databases con
23c20 74 72 6f 6c 6c 65 64 20 62 79 20 4a 61 76 61 53  trolled by JavaS
23c30 63 72 69 70 74 20 61 70 70 6c 69 63 61 74 69 6f  cript applicatio
23c40 6e 73 20 64 6f 77 6e 6c 6f 61 64 65 64 0a 2a 2a  ns downloaded.**
23c50 20 6f 66 66 20 74 68 65 20 49 6e 74 65 72 6e 65   off the Interne
23c60 74 2e 20 20 54 68 65 20 69 6e 74 65 72 6e 61 6c  t.  The internal
23c70 20 64 61 74 61 62 61 73 65 73 20 63 61 6e 20 62   databases can b
23c80 65 20 67 69 76 65 6e 20 74 68 65 0a 2a 2a 20 6c  e given the.** l
23c90 61 72 67 65 2c 20 64 65 66 61 75 6c 74 20 6c 69  arge, default li
23ca0 6d 69 74 73 2e 20 20 44 61 74 61 62 61 73 65 73  mits.  Databases
23cb0 20 6d 61 6e 61 67 65 64 20 62 79 20 65 78 74 65   managed by exte
23cc0 72 6e 61 6c 20 73 6f 75 72 63 65 73 20 63 61 6e  rnal sources can
23cd0 0a 2a 2a 20 62 65 20 67 69 76 65 6e 20 6d 75 63  .** be given muc
23ce0 68 20 73 6d 61 6c 6c 65 72 20 6c 69 6d 69 74 73  h smaller limits
23cf0 20 64 65 73 69 67 6e 65 64 20 74 6f 20 70 72 65   designed to pre
23d00 76 65 6e 74 20 61 20 64 65 6e 69 61 6c 20 6f 66  vent a denial of
23d10 20 73 65 72 76 69 63 65 0a 2a 2a 20 61 74 74 61   service.** atta
23d20 63 6b 2e 20 20 44 65 76 65 6c 6f 70 65 72 73 20  ck.  Developers 
23d30 6d 69 67 68 74 20 61 6c 73 6f 20 77 61 6e 74 20  might also want 
23d40 74 6f 20 75 73 65 20 74 68 65 20 5b 73 71 6c 69  to use the [sqli
23d50 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
23d60 65 72 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61  er()].** interfa
23d70 63 65 20 74 6f 20 66 75 72 74 68 65 72 20 63 6f  ce to further co
23d80 6e 74 72 6f 6c 20 75 6e 74 72 75 73 74 65 64 20  ntrol untrusted 
23d90 53 51 4c 2e 20 20 54 68 65 20 73 69 7a 65 20 6f  SQL.  The size o
23da0 66 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  f the database.*
23db0 2a 20 63 72 65 61 74 65 64 20 62 79 20 61 6e 20  * created by an 
23dc0 75 6e 74 72 75 73 74 65 64 20 73 63 72 69 70 74  untrusted script
23dd0 20 63 61 6e 20 62 65 20 63 6f 6e 74 61 69 6e 65   can be containe
23de0 64 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b  d using the.** [
23df0 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20  max_page_count] 
23e00 5b 50 52 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20  [PRAGMA]..**.** 
23e10 4e 65 77 20 72 75 6e 2d 74 69 6d 65 20 6c 69 6d  New run-time lim
23e20 69 74 20 63 61 74 65 67 6f 72 69 65 73 20 6d 61  it categories ma
23e30 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75  y be added in fu
23e40 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a  ture releases..*
23e50 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c 69  /.int sqlite3_li
23e60 6d 69 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e  mit(sqlite3*, in
23e70 74 20 69 64 2c 20 69 6e 74 20 6e 65 77 56 61 6c  t id, int newVal
23e80 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
23e90 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 6d  EF: Run-Time Lim
23ea0 69 74 20 43 61 74 65 67 6f 72 69 65 73 0a 2a 2a  it Categories.**
23eb0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 6c 69 6d 69   KEYWORDS: {limi
23ec0 74 20 63 61 74 65 67 6f 72 79 7d 20 7b 2a 6c 69  t category} {*li
23ed0 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 7d 0a  mit categories}.
23ee0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
23ef0 74 61 6e 74 73 20 64 65 66 69 6e 65 20 76 61 72  tants define var
23f00 69 6f 75 73 20 70 65 72 66 6f 72 6d 61 6e 63 65  ious performance
23f10 20 6c 69 6d 69 74 73 0a 2a 2a 20 74 68 61 74 20   limits.** that 
23f20 63 61 6e 20 62 65 20 6c 6f 77 65 72 65 64 20 61  can be lowered a
23f30 74 20 72 75 6e 2d 74 69 6d 65 20 75 73 69 6e 67  t run-time using
23f40 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28   [sqlite3_limit(
23f50 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 79 6e 6f 70  )]..** The synop
23f60 73 69 73 20 6f 66 20 74 68 65 20 6d 65 61 6e 69  sis of the meani
23f70 6e 67 73 20 6f 66 20 74 68 65 20 76 61 72 69 6f  ngs of the vario
23f80 75 73 20 6c 69 6d 69 74 73 20 69 73 20 73 68 6f  us limits is sho
23f90 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a 20 41 64 64  wn below..** Add
23fa0 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74  itional informat
23fb0 69 6f 6e 20 69 73 20 61 76 61 69 6c 61 62 6c 65  ion is available
23fc0 20 61 74 20 5b 6c 69 6d 69 74 73 20 7c 20 4c 69   at [limits | Li
23fd0 6d 69 74 73 20 69 6e 20 53 51 4c 69 74 65 5d 2e  mits in SQLite].
23fe0 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b  .**.** <dl>.** [
23ff0 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45  [SQLITE_LIMIT_LE
24000 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  NGTH]] ^(<dt>SQL
24010 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48  ITE_LIMIT_LENGTH
24020 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
24030 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66   maximum size of
24040 20 61 6e 79 20 73 74 72 69 6e 67 20 6f 72 20 42   any string or B
24050 4c 4f 42 20 6f 72 20 74 61 62 6c 65 20 72 6f 77  LOB or table row
24060 2c 20 69 6e 20 62 79 74 65 73 2e 3c 64 64 3e 29  , in bytes.<dd>)
24070 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
24080 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54  _LIMIT_SQL_LENGT
24090 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  H]] ^(<dt>SQLITE
240a0 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54  _LIMIT_SQL_LENGT
240b0 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  H</dt>.** <dd>Th
240c0 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  e maximum length
240d0 20 6f 66 20 61 6e 20 53 51 4c 20 73 74 61 74 65   of an SQL state
240e0 6d 65 6e 74 2c 20 69 6e 20 62 79 74 65 73 2e 3c  ment, in bytes.<
240f0 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  /dd>)^.**.** [[S
24100 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55  QLITE_LIMIT_COLU
24110 4d 4e 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  MN]] ^(<dt>SQLIT
24120 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c 2f  E_LIMIT_COLUMN</
24130 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
24140 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
24150 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 74 61   columns in a ta
24160 62 6c 65 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f  ble definition o
24170 72 20 69 6e 20 74 68 65 0a 2a 2a 20 72 65 73 75  r in the.** resu
24180 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c  lt set of a [SEL
24190 45 43 54 5d 20 6f 72 20 74 68 65 20 6d 61 78 69  ECT] or the maxi
241a0 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  mum number of co
241b0 6c 75 6d 6e 73 20 69 6e 20 61 6e 20 69 6e 64 65  lumns in an inde
241c0 78 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e 20 4f 52  x.** or in an OR
241d0 44 45 52 20 42 59 20 6f 72 20 47 52 4f 55 50 20  DER BY or GROUP 
241e0 42 59 20 63 6c 61 75 73 65 2e 3c 2f 64 64 3e 29  BY clause.</dd>)
241f0 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
24200 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54  _LIMIT_EXPR_DEPT
24210 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  H]] ^(<dt>SQLITE
24220 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54  _LIMIT_EXPR_DEPT
24230 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  H</dt>.** <dd>Th
24240 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20  e maximum depth 
24250 6f 66 20 74 68 65 20 70 61 72 73 65 20 74 72 65  of the parse tre
24260 65 20 6f 6e 20 61 6e 79 20 65 78 70 72 65 73 73  e on any express
24270 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  ion.</dd>)^.**.*
24280 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
24290 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54  _COMPOUND_SELECT
242a0 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
242b0 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53  LIMIT_COMPOUND_S
242c0 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ELECT</dt>.** <d
242d0 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d>The maximum nu
242e0 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20 69 6e  mber of terms in
242f0 20 61 20 63 6f 6d 70 6f 75 6e 64 20 53 45 4c 45   a compound SELE
24300 43 54 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64  CT statement.</d
24310 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d>)^.**.** [[SQL
24320 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f  ITE_LIMIT_VDBE_O
24330 50 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  P]] ^(<dt>SQLITE
24340 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 3c 2f  _LIMIT_VDBE_OP</
24350 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
24360 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
24370 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 20 69 6e   instructions in
24380 20 61 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69   a virtual machi
24390 6e 65 20 70 72 6f 67 72 61 6d 0a 2a 2a 20 75 73  ne program.** us
243a0 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20  ed to implement 
243b0 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  an SQL statement
243c0 2e 20 20 54 68 69 73 20 6c 69 6d 69 74 20 69 73  .  This limit is
243d0 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 0a 2a   not currently.*
243e0 2a 20 65 6e 66 6f 72 63 65 64 2c 20 74 68 6f 75  * enforced, thou
243f0 67 68 20 74 68 61 74 20 6d 69 67 68 74 20 62 65  gh that might be
24400 20 61 64 64 65 64 20 69 6e 20 73 6f 6d 65 20 66   added in some f
24410 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66  uture release of
24420 0a 2a 2a 20 53 51 4c 69 74 65 2e 3c 2f 64 64 3e  .** SQLite.</dd>
24430 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
24440 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e  E_LIMIT_FUNCTION
24450 5f 41 52 47 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  _ARG]] ^(<dt>SQL
24460 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49  ITE_LIMIT_FUNCTI
24470 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20 3c  ON_ARG</dt>.** <
24480 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
24490 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e  umber of argumen
244a0 74 73 20 6f 6e 20 61 20 66 75 6e 63 74 69 6f 6e  ts on a function
244b0 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  .</dd>)^.**.** [
244c0 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54  [SQLITE_LIMIT_AT
244d0 54 41 43 48 45 44 5d 5d 20 5e 28 3c 64 74 3e 53  TACHED]] ^(<dt>S
244e0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41  QLITE_LIMIT_ATTA
244f0 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  CHED</dt>.** <dd
24500 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  >The maximum num
24510 62 65 72 20 6f 66 20 5b 41 54 54 41 43 48 20 7c  ber of [ATTACH |
24520 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61   attached databa
24530 73 65 73 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a  ses].)^</dd>.**.
24540 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
24550 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c  T_LIKE_PATTERN_L
24560 45 4e 47 54 48 5d 5d 0a 2a 2a 20 5e 28 3c 64 74  ENGTH]].** ^(<dt
24570 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49  >SQLITE_LIMIT_LI
24580 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54  KE_PATTERN_LENGT
24590 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  H</dt>.** <dd>Th
245a0 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  e maximum length
245b0 20 6f 66 20 74 68 65 20 70 61 74 74 65 72 6e 20   of the pattern 
245c0 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
245d0 5b 4c 49 4b 45 5d 20 6f 72 0a 2a 2a 20 5b 47 4c  [LIKE] or.** [GL
245e0 4f 42 5d 20 6f 70 65 72 61 74 6f 72 73 2e 3c 2f  OB] operators.</
245f0 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
24600 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41  LITE_LIMIT_VARIA
24610 42 4c 45 5f 4e 55 4d 42 45 52 5d 5d 0a 2a 2a 20  BLE_NUMBER]].** 
24620 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
24630 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42  IT_VARIABLE_NUMB
24640 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  ER</dt>.** <dd>T
24650 68 65 20 6d 61 78 69 6d 75 6d 20 69 6e 64 65 78  he maximum index
24660 20 6e 75 6d 62 65 72 20 6f 66 20 61 6e 79 20 5b   number of any [
24670 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 61 6e  parameter] in an
24680 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 29   SQL statement.)
24690 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
246a0 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44  _LIMIT_TRIGGER_D
246b0 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  EPTH]] ^(<dt>SQL
246c0 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45  ITE_LIMIT_TRIGGE
246d0 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20  R_DEPTH</dt>.** 
246e0 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
246f0 64 65 70 74 68 20 6f 66 20 72 65 63 75 72 73 69  depth of recursi
24700 6f 6e 20 66 6f 72 20 74 72 69 67 67 65 72 73 2e  on for triggers.
24710 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e  </dd>)^.** </dl>
24720 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
24730 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 20  TE_LIMIT_LENGTH 
24740 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
24750 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c     0.#define SQL
24760 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45  ITE_LIMIT_SQL_LE
24770 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 20 20  NGTH            
24780 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51      1.#define SQ
24790 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d  LITE_LIMIT_COLUM
247a0 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  N               
247b0 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53       2.#define S
247c0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52  QLITE_LIMIT_EXPR
247d0 5f 44 45 50 54 48 20 20 20 20 20 20 20 20 20 20  _DEPTH          
247e0 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20        3.#define 
247f0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d  SQLITE_LIMIT_COM
24800 50 4f 55 4e 44 5f 53 45 4c 45 43 54 20 20 20 20  POUND_SELECT    
24810 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65         4.#define
24820 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44   SQLITE_LIMIT_VD
24830 42 45 5f 4f 50 20 20 20 20 20 20 20 20 20 20 20  BE_OP           
24840 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e          5.#defin
24850 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46  e SQLITE_LIMIT_F
24860 55 4e 43 54 49 4f 4e 5f 41 52 47 20 20 20 20 20  UNCTION_ARG     
24870 20 20 20 20 20 20 20 20 20 36 0a 23 64 65 66 69           6.#defi
24880 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
24890 41 54 54 41 43 48 45 44 20 20 20 20 20 20 20 20  ATTACHED        
248a0 20 20 20 20 20 20 20 20 20 20 37 0a 23 64 65 66            7.#def
248b0 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
248c0 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45  _LIKE_PATTERN_LE
248d0 4e 47 54 48 20 20 20 20 20 20 20 38 0a 23 64 65  NGTH       8.#de
248e0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
248f0 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45  T_VARIABLE_NUMBE
24900 52 20 20 20 20 20 20 20 20 20 20 20 39 0a 23 64  R           9.#d
24910 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
24920 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48  IT_TRIGGER_DEPTH
24930 20 20 20 20 20 20 20 20 20 20 20 20 31 30 0a 0a              10..
24940 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
24950 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53 51 4c  Compiling An SQL
24960 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4b 45   Statement.** KE
24970 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 73 74 61  YWORDS: {SQL sta
24980 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72 7d  tement compiler}
24990 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 75 74  .**.** To execut
249a0 65 20 61 6e 20 53 51 4c 20 71 75 65 72 79 2c 20  e an SQL query, 
249b0 69 74 20 6d 75 73 74 20 66 69 72 73 74 20 62 65  it must first be
249c0 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 61   compiled into a
249d0 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70 72   byte-code.** pr
249e0 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65 20  ogram using one 
249f0 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
24a00 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72  s..**.** The fir
24a10 73 74 20 61 72 67 75 6d 65 6e 74 2c 20 22 64 62  st argument, "db
24a20 22 2c 20 69 73 20 61 20 5b 64 61 74 61 62 61 73  ", is a [databas
24a30 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62  e connection] ob
24a40 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 0a 2a 2a  tained from a.**
24a50 20 70 72 69 6f 72 20 73 75 63 63 65 73 73 66 75   prior successfu
24a60 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  l call to [sqlit
24a70 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c  e3_open()], [sql
24a80 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20  ite3_open_v2()] 
24a90 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f  or.** [sqlite3_o
24aa0 70 65 6e 31 36 28 29 5d 2e 20 20 54 68 65 20 64  pen16()].  The d
24ab0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
24ac0 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 68 61 76 65  on must not have
24ad0 20 62 65 65 6e 20 63 6c 6f 73 65 64 2e 0a 2a 2a   been closed..**
24ae0 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61  .** The second a
24af0 72 67 75 6d 65 6e 74 2c 20 22 7a 53 71 6c 22 2c  rgument, "zSql",
24b00 20 69 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e   is the statemen
24b10 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64  t to be compiled
24b20 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20  , encoded.** as 
24b30 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20  either UTF-8 or 
24b40 55 54 46 2d 31 36 2e 20 20 54 68 65 20 73 71 6c  UTF-16.  The sql
24b50 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 20 61  ite3_prepare() a
24b60 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nd sqlite3_prepa
24b70 72 65 5f 76 32 28 29 0a 2a 2a 20 69 6e 74 65 72  re_v2().** inter
24b80 66 61 63 65 73 20 75 73 65 20 55 54 46 2d 38 2c  faces use UTF-8,
24b90 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65   and sqlite3_pre
24ba0 70 61 72 65 31 36 28 29 20 61 6e 64 20 73 71 6c  pare16() and sql
24bb0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
24bc0 32 28 29 0a 2a 2a 20 75 73 65 20 55 54 46 2d 31  2().** use UTF-1
24bd0 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  6..**.** ^If the
24be0 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e 74 20   nByte argument 
24bf0 69 73 20 6c 65 73 73 20 74 68 61 6e 20 7a 65 72  is less than zer
24c00 6f 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69 73 20  o, then zSql is 
24c10 72 65 61 64 20 75 70 20 74 6f 20 74 68 65 0a 2a  read up to the.*
24c20 2a 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72  * first zero ter
24c30 6d 69 6e 61 74 6f 72 2e 20 5e 49 66 20 6e 42 79  minator. ^If nBy
24c40 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69  te is non-negati
24c50 76 65 2c 20 74 68 65 6e 20 69 74 20 69 73 20 74  ve, then it is t
24c60 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 6e 75  he maximum.** nu
24c70 6d 62 65 72 20 6f 66 20 20 62 79 74 65 73 20 72  mber of  bytes r
24c80 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 20 20  ead from zSql.  
24c90 5e 57 68 65 6e 20 6e 42 79 74 65 20 69 73 20 6e  ^When nByte is n
24ca0 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65  on-negative, the
24cb0 0a 2a 2a 20 7a 53 71 6c 20 73 74 72 69 6e 67 20  .** zSql string 
24cc0 65 6e 64 73 20 61 74 20 65 69 74 68 65 72 20 74  ends at either t
24cd0 68 65 20 66 69 72 73 74 20 27 5c 30 30 30 27 20  he first '\000' 
24ce0 6f 72 20 27 5c 75 30 30 30 30 27 20 63 68 61 72  or '\u0000' char
24cf0 61 63 74 65 72 20 6f 72 0a 2a 2a 20 74 68 65 20  acter or.** the 
24d00 6e 42 79 74 65 2d 74 68 20 62 79 74 65 2c 20 77  nByte-th byte, w
24d10 68 69 63 68 65 76 65 72 20 63 6f 6d 65 73 20 66  hichever comes f
24d20 69 72 73 74 2e 20 49 66 20 74 68 65 20 63 61 6c  irst. If the cal
24d30 6c 65 72 20 6b 6e 6f 77 73 0a 2a 2a 20 74 68 61  ler knows.** tha
24d40 74 20 74 68 65 20 73 75 70 70 6c 69 65 64 20 73  t the supplied s
24d50 74 72 69 6e 67 20 69 73 20 6e 75 6c 2d 74 65 72  tring is nul-ter
24d60 6d 69 6e 61 74 65 64 2c 20 74 68 65 6e 20 74 68  minated, then th
24d70 65 72 65 20 69 73 20 61 20 73 6d 61 6c 6c 0a 2a  ere is a small.*
24d80 2a 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 61 64  * performance ad
24d90 76 61 6e 74 61 67 65 20 74 6f 20 62 65 20 67 61  vantage to be ga
24da0 69 6e 65 64 20 62 79 20 70 61 73 73 69 6e 67 20  ined by passing 
24db0 61 6e 20 6e 42 79 74 65 20 70 61 72 61 6d 65 74  an nByte paramet
24dc0 65 72 20 74 68 61 74 0a 2a 2a 20 69 73 20 65 71  er that.** is eq
24dd0 75 61 6c 20 74 6f 20 74 68 65 20 6e 75 6d 62 65  ual to the numbe
24de0 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
24df0 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 20 3c  e input string <
24e00 69 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e 0a  i>including</i>.
24e10 2a 2a 20 74 68 65 20 6e 75 6c 2d 74 65 72 6d 69  ** the nul-termi
24e20 6e 61 74 6f 72 20 62 79 74 65 73 20 61 73 20 74  nator bytes as t
24e30 68 69 73 20 73 61 76 65 73 20 53 51 4c 69 74 65  his saves SQLite
24e40 20 66 72 6f 6d 20 68 61 76 69 6e 67 20 74 6f 0a   from having to.
24e50 2a 2a 20 6d 61 6b 65 20 61 20 63 6f 70 79 20 6f  ** make a copy o
24e60 66 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69  f the input stri
24e70 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 70 7a  ng..**.** ^If pz
24e80 54 61 69 6c 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  Tail is not NULL
24e90 20 74 68 65 6e 20 2a 70 7a 54 61 69 6c 20 69 73   then *pzTail is
24ea0 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74   made to point t
24eb0 6f 20 74 68 65 20 66 69 72 73 74 20 62 79 74 65  o the first byte
24ec0 0a 2a 2a 20 70 61 73 74 20 74 68 65 20 65 6e 64  .** past the end
24ed0 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 53 51   of the first SQ
24ee0 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a  L statement in z
24ef0 53 71 6c 2e 20 20 54 68 65 73 65 20 72 6f 75 74  Sql.  These rout
24f00 69 6e 65 73 20 6f 6e 6c 79 0a 2a 2a 20 63 6f 6d  ines only.** com
24f10 70 69 6c 65 20 74 68 65 20 66 69 72 73 74 20 73  pile the first s
24f20 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c  tatement in zSql
24f30 2c 20 73 6f 20 2a 70 7a 54 61 69 6c 20 69 73 20  , so *pzTail is 
24f40 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f  left pointing to
24f50 0a 2a 2a 20 77 68 61 74 20 72 65 6d 61 69 6e 73  .** what remains
24f60 20 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a   uncompiled..**.
24f70 2a 2a 20 5e 2a 70 70 53 74 6d 74 20 69 73 20 6c  ** ^*ppStmt is l
24f80 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20  eft pointing to 
24f90 61 20 63 6f 6d 70 69 6c 65 64 20 5b 70 72 65 70  a compiled [prep
24fa0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
24fb0 74 68 61 74 20 63 61 6e 20 62 65 0a 2a 2a 20 65  that can be.** e
24fc0 78 65 63 75 74 65 64 20 75 73 69 6e 67 20 5b 73  xecuted using [s
24fd0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 20  qlite3_step()]. 
24fe0 20 5e 49 66 20 74 68 65 72 65 20 69 73 20 61 6e   ^If there is an
24ff0 20 65 72 72 6f 72 2c 20 2a 70 70 53 74 6d 74 20   error, *ppStmt 
25000 69 73 20 73 65 74 0a 2a 2a 20 74 6f 20 4e 55 4c  is set.** to NUL
25010 4c 2e 20 20 5e 49 66 20 74 68 65 20 69 6e 70 75  L.  ^If the inpu
25020 74 20 74 65 78 74 20 63 6f 6e 74 61 69 6e 73 20  t text contains 
25030 6e 6f 20 53 51 4c 20 28 69 66 20 74 68 65 20 69  no SQL (if the i
25040 6e 70 75 74 20 69 73 20 61 6e 20 65 6d 70 74 79  nput is an empty
25050 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 72 20 61 20  .** string or a 
25060 63 6f 6d 6d 65 6e 74 29 20 74 68 65 6e 20 2a 70  comment) then *p
25070 70 53 74 6d 74 20 69 73 20 73 65 74 20 74 6f 20  pStmt is set to 
25080 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65 20 63 61 6c  NULL..** The cal
25090 6c 69 6e 67 20 70 72 6f 63 65 64 75 72 65 20 69  ling procedure i
250a0 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f  s responsible fo
250b0 72 20 64 65 6c 65 74 69 6e 67 20 74 68 65 20 63  r deleting the c
250c0 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53 51 4c 20 73  ompiled.** SQL s
250d0 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b  tatement using [
250e0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
250f0 28 29 5d 20 61 66 74 65 72 20 69 74 20 68 61 73  ()] after it has
25100 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 69   finished with i
25110 74 2e 0a 2a 2a 20 70 70 53 74 6d 74 20 6d 61 79  t..** ppStmt may
25120 20 6e 6f 74 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a   not be NULL..**
25130 0a 2a 2a 20 5e 4f 6e 20 73 75 63 63 65 73 73 2c  .** ^On success,
25140 20 74 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65   the sqlite3_pre
25150 70 61 72 65 28 29 20 66 61 6d 69 6c 79 20 6f 66  pare() family of
25160 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
25170 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 3b 0a 2a 2a   [SQLITE_OK];.**
25180 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65   otherwise an [e
25190 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65  rror code] is re
251a0 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  turned..**.** Th
251b0 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  e sqlite3_prepar
251c0 65 5f 76 32 28 29 20 61 6e 64 20 73 71 6c 69 74  e_v2() and sqlit
251d0 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
251e0 29 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  ) interfaces are
251f0 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20  .** recommended 
25200 66 6f 72 20 61 6c 6c 20 6e 65 77 20 70 72 6f 67  for all new prog
25210 72 61 6d 73 2e 20 54 68 65 20 74 77 6f 20 6f 6c  rams. The two ol
25220 64 65 72 20 69 6e 74 65 72 66 61 63 65 73 20 61  der interfaces a
25230 72 65 20 72 65 74 61 69 6e 65 64 0a 2a 2a 20 66  re retained.** f
25240 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d  or backwards com
25250 70 61 74 69 62 69 6c 69 74 79 2c 20 62 75 74 20  patibility, but 
25260 74 68 65 69 72 20 75 73 65 20 69 73 20 64 69 73  their use is dis
25270 63 6f 75 72 61 67 65 64 2e 0a 2a 2a 20 5e 49 6e  couraged..** ^In
25280 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66   the "v2" interf
25290 61 63 65 73 2c 20 74 68 65 20 70 72 65 70 61 72  aces, the prepar
252a0 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  ed statement.** 
252b0 74 68 61 74 20 69 73 20 72 65 74 75 72 6e 65 64  that is returned
252c0 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73   (the [sqlite3_s
252d0 74 6d 74 5d 20 6f 62 6a 65 63 74 29 20 63 6f 6e  tmt] object) con
252e0 74 61 69 6e 73 20 61 20 63 6f 70 79 20 6f 66 20  tains a copy of 
252f0 74 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20  the.** original 
25300 53 51 4c 20 74 65 78 74 2e 20 54 68 69 73 20 63  SQL text. This c
25310 61 75 73 65 73 20 74 68 65 20 5b 73 71 6c 69 74  auses the [sqlit
25320 65 33 5f 73 74 65 70 28 29 5d 20 69 6e 74 65 72  e3_step()] inter
25330 66 61 63 65 20 74 6f 0a 2a 2a 20 62 65 68 61 76  face to.** behav
25340 65 20 64 69 66 66 65 72 65 6e 74 6c 79 20 69 6e  e differently in
25350 20 74 68 72 65 65 20 77 61 79 73 3a 0a 2a 2a 0a   three ways:.**.
25360 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a  ** <ol>.** <li>.
25370 2a 2a 20 5e 49 66 20 74 68 65 20 64 61 74 61 62  ** ^If the datab
25380 61 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67  ase schema chang
25390 65 73 2c 20 69 6e 73 74 65 61 64 20 6f 66 20 72  es, instead of r
253a0 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45  eturning [SQLITE
253b0 5f 53 43 48 45 4d 41 5d 20 61 73 20 69 74 0a 2a  _SCHEMA] as it.*
253c0 2a 20 61 6c 77 61 79 73 20 75 73 65 64 20 74 6f  * always used to
253d0 20 64 6f 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74   do, [sqlite3_st
253e0 65 70 28 29 5d 20 77 69 6c 6c 20 61 75 74 6f 6d  ep()] will autom
253f0 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69  atically recompi
25400 6c 65 20 74 68 65 20 53 51 4c 0a 2a 2a 20 73 74  le the SQL.** st
25410 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 72 79 20  atement and try 
25420 74 6f 20 72 75 6e 20 69 74 20 61 67 61 69 6e 2e  to run it again.
25430 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20  .** </li>.**.** 
25440 3c 6c 69 3e 0a 2a 2a 20 5e 57 68 65 6e 20 61 6e  <li>.** ^When an
25450 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2c 20 5b   error occurs, [
25460 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
25470 77 69 6c 6c 20 72 65 74 75 72 6e 20 6f 6e 65 20  will return one 
25480 6f 66 20 74 68 65 20 64 65 74 61 69 6c 65 64 0a  of the detailed.
25490 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d  ** [error codes]
254a0 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 65 72   or [extended er
254b0 72 6f 72 20 63 6f 64 65 73 5d 2e 20 20 5e 54 68  ror codes].  ^Th
254c0 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f  e legacy behavio
254d0 72 20 77 61 73 20 74 68 61 74 0a 2a 2a 20 5b 73  r was that.** [s
254e0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77  qlite3_step()] w
254f0 6f 75 6c 64 20 6f 6e 6c 79 20 72 65 74 75 72 6e  ould only return
25500 20 61 20 67 65 6e 65 72 69 63 20 5b 53 51 4c 49   a generic [SQLI
25510 54 45 5f 45 52 52 4f 52 5d 20 72 65 73 75 6c 74  TE_ERROR] result
25520 20 63 6f 64 65 0a 2a 2a 20 61 6e 64 20 74 68 65   code.** and the
25530 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 77 6f 75   application wou
25540 6c 64 20 68 61 76 65 20 74 6f 20 6d 61 6b 65 20  ld have to make 
25550 61 20 73 65 63 6f 6e 64 20 63 61 6c 6c 20 74 6f  a second call to
25560 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
25570 29 5d 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20 74  )].** in order t
25580 6f 20 66 69 6e 64 20 74 68 65 20 75 6e 64 65 72  o find the under
25590 6c 79 69 6e 67 20 63 61 75 73 65 20 6f 66 20 74  lying cause of t
255a0 68 65 20 70 72 6f 62 6c 65 6d 2e 20 57 69 74 68  he problem. With
255b0 20 74 68 65 20 22 76 32 22 20 70 72 65 70 61 72   the "v2" prepar
255c0 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 2c  e.** interfaces,
255d0 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20   the underlying 
255e0 72 65 61 73 6f 6e 20 66 6f 72 20 74 68 65 20 65  reason for the e
255f0 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64  rror is returned
25600 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a   immediately..**
25610 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69   </li>.**.** <li
25620 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73 70 65  >.** ^If the spe
25630 63 69 66 69 63 20 76 61 6c 75 65 20 62 6f 75 6e  cific value boun
25640 64 20 74 6f 20 5b 70 61 72 61 6d 65 74 65 72 20  d to [parameter 
25650 7c 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72  | host parameter
25660 5d 20 69 6e 20 74 68 65 20 0a 2a 2a 20 57 48 45  ] in the .** WHE
25670 52 45 20 63 6c 61 75 73 65 20 6d 69 67 68 74 20  RE clause might 
25680 69 6e 66 6c 75 65 6e 63 65 20 74 68 65 20 63 68  influence the ch
25690 6f 69 63 65 20 6f 66 20 71 75 65 72 79 20 70 6c  oice of query pl
256a0 61 6e 20 66 6f 72 20 61 20 73 74 61 74 65 6d 65  an for a stateme
256b0 6e 74 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  nt,.** then the 
256c0 73 74 61 74 65 6d 65 6e 74 20 77 69 6c 6c 20 62  statement will b
256d0 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  e automatically 
256e0 72 65 63 6f 6d 70 69 6c 65 64 2c 20 61 73 20 69  recompiled, as i
256f0 66 20 74 68 65 72 65 20 68 61 64 20 62 65 65 6e  f there had been
25700 20 0a 2a 2a 20 61 20 73 63 68 65 6d 61 20 63 68   .** a schema ch
25710 61 6e 67 65 2c 20 6f 6e 20 74 68 65 20 66 69 72  ange, on the fir
25720 73 74 20 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  st  [sqlite3_ste
25730 70 28 29 5d 20 63 61 6c 6c 20 66 6f 6c 6c 6f 77  p()] call follow
25740 69 6e 67 20 61 6e 79 20 63 68 61 6e 67 65 0a 2a  ing any change.*
25750 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  * to the [sqlite
25760 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20 62 69  3_bind_text | bi
25770 6e 64 69 6e 67 73 5d 20 6f 66 20 74 68 61 74 20  ndings] of that 
25780 5b 70 61 72 61 6d 65 74 65 72 5d 2e 20 0a 2a 2a  [parameter]. .**
25790 20 5e 54 68 65 20 73 70 65 63 69 66 69 63 20 76   ^The specific v
257a0 61 6c 75 65 20 6f 66 20 57 48 45 52 45 2d 63 6c  alue of WHERE-cl
257b0 61 75 73 65 20 5b 70 61 72 61 6d 65 74 65 72 5d  ause [parameter]
257c0 20 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e 63 65   might influence
257d0 20 74 68 65 20 0a 2a 2a 20 63 68 6f 69 63 65 20   the .** choice 
257e0 6f 66 20 71 75 65 72 79 20 70 6c 61 6e 20 69 66  of query plan if
257f0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69   the parameter i
25800 73 20 74 68 65 20 6c 65 66 74 2d 68 61 6e 64 20  s the left-hand 
25810 73 69 64 65 20 6f 66 20 61 20 5b 4c 49 4b 45 5d  side of a [LIKE]
25820 0a 2a 2a 20 6f 72 20 5b 47 4c 4f 42 5d 20 6f 70  .** or [GLOB] op
25830 65 72 61 74 6f 72 20 6f 72 20 69 66 20 74 68 65  erator or if the
25840 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 63 6f   parameter is co
25850 6d 70 61 72 65 64 20 74 6f 20 61 6e 20 69 6e 64  mpared to an ind
25860 65 78 65 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61  exed column.** a
25870 6e 64 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 45  nd the [SQLITE_E
25880 4e 41 42 4c 45 5f 53 54 41 54 33 5d 20 63 6f 6d  NABLE_STAT3] com
25890 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
258a0 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20   is enabled..** 
258b0 74 68 65 20 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a  the .** </li>.**
258c0 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 69 6e 74 20 73 71   </ol>.*/.int sq
258d0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 0a 20  lite3_prepare(. 
258e0 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
258f0 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
25900 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  base handle */. 
25910 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71   const char *zSq
25920 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20  l,       /* SQL 
25930 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38  statement, UTF-8
25940 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e   encoded */.  in
25950 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20  t nByte,        
25960 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d        /* Maximum
25970 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20   length of zSql 
25980 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73  in bytes. */.  s
25990 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70  qlite3_stmt **pp
259a0 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53  Stmt,  /* OUT: S
259b0 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20  tatement handle 
259c0 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
259d0 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20  **pzTail     /* 
259e0 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20  OUT: Pointer to 
259f0 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f  unused portion o
25a00 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74  f zSql */.);.int
25a10 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
25a20 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  _v2(.  sqlite3 *
25a30 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f  db,            /
25a40 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c  * Database handl
25a50 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
25a60 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f  r *zSql,       /
25a70 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  * SQL statement,
25a80 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a   UTF-8 encoded *
25a90 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20  /.  int nByte,  
25aa0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d              /* M
25ab0 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
25ac0 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20   zSql in bytes. 
25ad0 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d  */.  sqlite3_stm
25ae0 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20  t **ppStmt,  /* 
25af0 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68  OUT: Statement h
25b00 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
25b10 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20   char **pzTail  
25b20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74     /* OUT: Point
25b30 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72  er to unused por
25b40 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a  tion of zSql */.
25b50 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70  );.int sqlite3_p
25b60 72 65 70 61 72 65 31 36 28 0a 20 20 73 71 6c 69  repare16(.  sqli
25b70 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
25b80 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
25b90 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
25ba0 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20  t void *zSql,   
25bb0 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65      /* SQL state
25bc0 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63  ment, UTF-16 enc
25bd0 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42  oded */.  int nB
25be0 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20  yte,            
25bf0 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e    /* Maximum len
25c00 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62  gth of zSql in b
25c10 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74  ytes. */.  sqlit
25c20 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74  e3_stmt **ppStmt
25c30 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65  ,  /* OUT: State
25c40 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  ment handle */. 
25c50 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a   const void **pz
25c60 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a  Tail     /* OUT:
25c70 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73   Pointer to unus
25c80 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53  ed portion of zS
25c90 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c  ql */.);.int sql
25ca0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
25cb0 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  2(.  sqlite3 *db
25cc0 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ,            /* 
25cd0 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  Database handle 
25ce0 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
25cf0 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20  *zSql,       /* 
25d00 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55  SQL statement, U
25d10 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f  TF-16 encoded */
25d20 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20  .  int nByte,   
25d30 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61             /* Ma
25d40 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
25d50 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a  zSql in bytes. *
25d60 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  /.  sqlite3_stmt
25d70 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f   **ppStmt,  /* O
25d80 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61  UT: Statement ha
25d90 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
25da0 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20  void **pzTail   
25db0 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65    /* OUT: Pointe
25dc0 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74  r to unused port
25dd0 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29  ion of zSql */.)
25de0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
25df0 46 3a 20 52 65 74 72 69 65 76 69 6e 67 20 53 74  F: Retrieving St
25e00 61 74 65 6d 65 6e 74 20 53 51 4c 0a 2a 2a 0a 2a  atement SQL.**.*
25e10 2a 20 5e 54 68 69 73 20 69 6e 74 65 72 66 61 63  * ^This interfac
25e20 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  e can be used to
25e30 20 72 65 74 72 69 65 76 65 20 61 20 73 61 76 65   retrieve a save
25e40 64 20 63 6f 70 79 20 6f 66 20 74 68 65 20 6f 72  d copy of the or
25e50 69 67 69 6e 61 6c 0a 2a 2a 20 53 51 4c 20 74 65  iginal.** SQL te
25e60 78 74 20 75 73 65 64 20 74 6f 20 63 72 65 61 74  xt used to creat
25e70 65 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  e a [prepared st
25e80 61 74 65 6d 65 6e 74 5d 20 69 66 20 74 68 61 74  atement] if that
25e90 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 0a 2a   statement was.*
25ea0 2a 20 63 6f 6d 70 69 6c 65 64 20 75 73 69 6e 67  * compiled using
25eb0 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33   either [sqlite3
25ec0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
25ed0 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
25ee0 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 63  re16_v2()]..*/.c
25ef0 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
25f00 65 33 5f 73 71 6c 28 73 71 6c 69 74 65 33 5f 73  e3_sql(sqlite3_s
25f10 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
25f20 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
25f30 74 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51  termine If An SQ
25f40 4c 20 53 74 61 74 65 6d 65 6e 74 20 57 72 69 74  L Statement Writ
25f50 65 73 20 54 68 65 20 44 61 74 61 62 61 73 65 0a  es The Database.
25f60 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
25f70 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79  e3_stmt_readonly
25f80 28 58 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  (X) interface re
25f90 74 75 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d  turns true (non-
25fa0 7a 65 72 6f 29 20 69 66 0a 2a 2a 20 61 6e 64 20  zero) if.** and 
25fb0 6f 6e 6c 79 20 69 66 20 74 68 65 20 5b 70 72 65  only if the [pre
25fc0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
25fd0 20 58 20 6d 61 6b 65 73 20 6e 6f 20 64 69 72 65   X makes no dire
25fe0 63 74 20 63 68 61 6e 67 65 73 20 74 6f 0a 2a 2a  ct changes to.**
25ff0 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20   the content of 
26000 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
26010 65 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68  e..**.** Note th
26020 61 74 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d  at [application-
26030 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
26040 74 69 6f 6e 73 5d 20 6f 72 0a 2a 2a 20 5b 76 69  tions] or.** [vi
26050 72 74 75 61 6c 20 74 61 62 6c 65 73 5d 20 6d 69  rtual tables] mi
26060 67 68 74 20 63 68 61 6e 67 65 20 74 68 65 20 64  ght change the d
26070 61 74 61 62 61 73 65 20 69 6e 64 69 72 65 63 74  atabase indirect
26080 6c 79 20 61 73 20 61 20 73 69 64 65 20 65 66 66  ly as a side eff
26090 65 63 74 2e 20 20 0a 2a 2a 20 5e 28 46 6f 72 20  ect.  .** ^(For 
260a0 65 78 61 6d 70 6c 65 2c 20 69 66 20 61 6e 20 61  example, if an a
260b0 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e  pplication defin
260c0 65 73 20 61 20 66 75 6e 63 74 69 6f 6e 20 22 65  es a function "e
260d0 76 61 6c 28 29 22 20 74 68 61 74 20 0a 2a 2a 20  val()" that .** 
260e0 63 61 6c 6c 73 20 5b 73 71 6c 69 74 65 33 5f 65  calls [sqlite3_e
260f0 78 65 63 28 29 5d 2c 20 74 68 65 6e 20 74 68 65  xec()], then the
26100 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 20 73   following SQL s
26110 74 61 74 65 6d 65 6e 74 20 77 6f 75 6c 64 0a 2a  tatement would.*
26120 2a 20 63 68 61 6e 67 65 20 74 68 65 20 64 61 74  * change the dat
26130 61 62 61 73 65 20 66 69 6c 65 20 74 68 72 6f 75  abase file throu
26140 67 68 20 73 69 64 65 2d 65 66 66 65 63 74 73 3a  gh side-effects:
26150 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
26160 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 53  te><pre>.**    S
26170 45 4c 45 43 54 20 65 76 61 6c 28 27 44 45 4c 45  ELECT eval('DELE
26180 54 45 20 46 52 4f 4d 20 74 31 27 29 20 46 52 4f  TE FROM t1') FRO
26190 4d 20 74 32 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  M t2;.** </pre><
261a0 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
261b0 2a 2a 20 42 75 74 20 62 65 63 61 75 73 65 20 74  ** But because t
261c0 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74  he [SELECT] stat
261d0 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63  ement does not c
261e0 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62 61  hange the databa
261f0 73 65 20 66 69 6c 65 0a 2a 2a 20 64 69 72 65 63  se file.** direc
26200 74 6c 79 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d  tly, sqlite3_stm
26210 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 77 6f 75  t_readonly() wou
26220 6c 64 20 73 74 69 6c 6c 20 72 65 74 75 72 6e 20  ld still return 
26230 74 72 75 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54  true.)^.**.** ^T
26240 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72  ransaction contr
26250 6f 6c 20 73 74 61 74 65 6d 65 6e 74 73 20 73 75  ol statements su
26260 63 68 20 61 73 20 5b 42 45 47 49 4e 5d 2c 20 5b  ch as [BEGIN], [
26270 43 4f 4d 4d 49 54 5d 2c 20 5b 52 4f 4c 4c 42 41  COMMIT], [ROLLBA
26280 43 4b 5d 2c 0a 2a 2a 20 5b 53 41 56 45 50 4f 49  CK],.** [SAVEPOI
26290 4e 54 5d 2c 20 61 6e 64 20 5b 52 45 4c 45 41 53  NT], and [RELEAS
262a0 45 5d 20 63 61 75 73 65 20 73 71 6c 69 74 65 33  E] cause sqlite3
262b0 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29  _stmt_readonly()
262c0 20 74 6f 20 72 65 74 75 72 6e 20 74 72 75 65 2c   to return true,
262d0 0a 2a 2a 20 73 69 6e 63 65 20 74 68 65 20 73 74  .** since the st
262e0 61 74 65 6d 65 6e 74 73 20 74 68 65 6d 73 65 6c  atements themsel
262f0 76 65 73 20 64 6f 20 6e 6f 74 20 61 63 74 75 61  ves do not actua
26300 6c 6c 79 20 6d 6f 64 69 66 79 20 74 68 65 20 64  lly modify the d
26310 61 74 61 62 61 73 65 20 62 75 74 0a 2a 2a 20 72  atabase but.** r
26320 61 74 68 65 72 20 74 68 65 79 20 63 6f 6e 74 72  ather they contr
26330 6f 6c 20 74 68 65 20 74 69 6d 69 6e 67 20 6f 66  ol the timing of
26340 20 77 68 65 6e 20 6f 74 68 65 72 20 73 74 61 74   when other stat
26350 65 6d 65 6e 74 73 20 6d 6f 64 69 66 79 20 74 68  ements modify th
26360 65 20 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20  e .** database. 
26370 20 5e 54 68 65 20 5b 41 54 54 41 43 48 5d 20 61   ^The [ATTACH] a
26380 6e 64 20 5b 44 45 54 41 43 48 5d 20 73 74 61 74  nd [DETACH] stat
26390 65 6d 65 6e 74 73 20 61 6c 73 6f 20 63 61 75 73  ements also caus
263a0 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 6d  e.** sqlite3_stm
263b0 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20  t_readonly() to 
263c0 72 65 74 75 72 6e 20 74 72 75 65 20 73 69 6e 63  return true sinc
263d0 65 2c 20 77 68 69 6c 65 20 74 68 6f 73 65 20 73  e, while those s
263e0 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 63 68 61  tatements.** cha
263f0 6e 67 65 20 74 68 65 20 63 6f 6e 66 69 67 75 72  nge the configur
26400 61 74 69 6f 6e 20 6f 66 20 61 20 64 61 74 61 62  ation of a datab
26410 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20  ase connection, 
26420 74 68 65 79 20 64 6f 20 6e 6f 74 20 6d 61 6b 65  they do not make
26430 20 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20   .** changes to 
26440 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74  the content of t
26450 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
26460 73 20 6f 6e 20 64 69 73 6b 2e 0a 2a 2f 0a 69 6e  s on disk..*/.in
26470 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72  t sqlite3_stmt_r
26480 65 61 64 6f 6e 6c 79 28 73 71 6c 69 74 65 33 5f  eadonly(sqlite3_
26490 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
264a0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
264b0 65 74 65 72 6d 69 6e 65 20 49 66 20 41 20 50 72  etermine If A Pr
264c0 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
264d0 20 48 61 73 20 42 65 65 6e 20 52 65 73 65 74 0a   Has Been Reset.
264e0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
264f0 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 53 29 20  e3_stmt_busy(S) 
26500 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
26510 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f  s true (non-zero
26520 29 20 69 66 20 74 68 65 0a 2a 2a 20 5b 70 72 65  ) if the.** [pre
26530 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
26540 20 53 20 68 61 73 20 62 65 65 6e 20 73 74 65 70   S has been step
26550 70 65 64 20 61 74 20 6c 65 61 73 74 20 6f 6e 63  ped at least onc
26560 65 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c  e using .** [sql
26570 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 62 75  ite3_step(S)] bu
26580 74 20 68 61 73 20 6e 6f 74 20 72 75 6e 20 74 6f  t has not run to
26590 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 6e 64 2f   completion and/
265a0 6f 72 20 68 61 73 20 6e 6f 74 20 0a 2a 2a 20 62  or has not .** b
265b0 65 65 6e 20 72 65 73 65 74 20 75 73 69 6e 67 20  een reset using 
265c0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53  [sqlite3_reset(S
265d0 29 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65  )].  ^The sqlite
265e0 33 5f 73 74 6d 74 5f 62 75 73 79 28 53 29 0a 2a  3_stmt_busy(S).*
265f0 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  * interface retu
26600 72 6e 73 20 66 61 6c 73 65 20 69 66 20 53 20 69  rns false if S i
26610 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
26620 2e 20 20 49 66 20 53 20 69 73 20 6e 6f 74 20 61  .  If S is not a
26630 20 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65   .** NULL pointe
26640 72 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 70  r and is not a p
26650 6f 69 6e 74 65 72 20 74 6f 20 61 20 76 61 6c 69  ointer to a vali
26660 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  d [prepared stat
26670 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74  ement].** object
26680 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  , then the behav
26690 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ior is undefined
266a0 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 75 6e   and probably un
266b0 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a  desirable..**.**
266c0 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   This interface 
266d0 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e 20 63  can be used in c
266e0 6f 6d 62 69 6e 61 74 69 6f 6e 20 5b 73 71 6c 69  ombination [sqli
266f0 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 29 5d  te3_next_stmt()]
26700 0a 2a 2a 20 74 6f 20 6c 6f 63 61 74 65 20 61 6c  .** to locate al
26710 6c 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  l prepared state
26720 6d 65 6e 74 73 20 61 73 73 6f 63 69 61 74 65 64  ments associated
26730 20 77 69 74 68 20 61 20 64 61 74 61 62 61 73 65   with a database
26740 20 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20   .** connection 
26750 74 68 61 74 20 61 72 65 20 69 6e 20 6e 65 65 64  that are in need
26760 20 6f 66 20 62 65 69 6e 67 20 72 65 73 65 74 2e   of being reset.
26770 20 20 54 68 69 73 20 63 61 6e 20 62 65 20 75 73    This can be us
26780 65 64 2c 0a 2a 2a 20 66 6f 72 20 65 78 61 6d 70  ed,.** for examp
26790 6c 65 2c 20 69 6e 20 64 69 61 67 6e 6f 73 74 69  le, in diagnosti
267a0 63 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 73 65  c routines to se
267b0 61 72 63 68 20 66 6f 72 20 70 72 65 70 61 72 65  arch for prepare
267c0 64 20 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73  d .** statements
267d0 20 74 68 61 74 20 61 72 65 20 68 6f 6c 64 69 6e   that are holdin
267e0 67 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  g a transaction 
267f0 6f 70 65 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  open..*/.int sql
26800 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 73  ite3_stmt_busy(s
26810 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a  qlite3_stmt*);..
26820 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
26830 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54 79 70 65  Dynamically Type
26840 64 20 56 61 6c 75 65 20 4f 62 6a 65 63 74 0a 2a  d Value Object.*
26850 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 6f  * KEYWORDS: {pro
26860 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
26870 61 6c 75 65 7d 20 7b 75 6e 70 72 6f 74 65 63 74  alue} {unprotect
26880 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
26890 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75  }.**.** SQLite u
268a0 73 65 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ses the sqlite3_
268b0 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 74 6f 20  value object to 
268c0 72 65 70 72 65 73 65 6e 74 20 61 6c 6c 20 76 61  represent all va
268d0 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e  lues.** that can
268e0 20 62 65 20 73 74 6f 72 65 64 20 69 6e 20 61 20   be stored in a 
268f0 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 2e 20  database table. 
26900 53 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61  SQLite uses dyna
26910 6d 69 63 20 74 79 70 69 6e 67 0a 2a 2a 20 66 6f  mic typing.** fo
26920 72 20 74 68 65 20 76 61 6c 75 65 73 20 69 74 20  r the values it 
26930 73 74 6f 72 65 73 2e 20 20 5e 56 61 6c 75 65 73  stores.  ^Values
26940 20 73 74 6f 72 65 64 20 69 6e 20 73 71 6c 69 74   stored in sqlit
26950 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
26960 0a 2a 2a 20 63 61 6e 20 62 65 20 69 6e 74 65 67  .** can be integ
26970 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67 20 70 6f  ers, floating po
26980 69 6e 74 20 76 61 6c 75 65 73 2c 20 73 74 72 69  int values, stri
26990 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f 72 20 4e  ngs, BLOBs, or N
269a0 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 71  ULL..**.** An sq
269b0 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
269c0 63 74 20 6d 61 79 20 62 65 20 65 69 74 68 65 72  ct may be either
269d0 20 22 70 72 6f 74 65 63 74 65 64 22 20 6f 72 20   "protected" or 
269e0 22 75 6e 70 72 6f 74 65 63 74 65 64 22 2e 0a 2a  "unprotected"..*
269f0 2a 20 53 6f 6d 65 20 69 6e 74 65 72 66 61 63 65  * Some interface
26a00 73 20 72 65 71 75 69 72 65 20 61 20 70 72 6f 74  s require a prot
26a10 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
26a20 6c 75 65 2e 20 20 4f 74 68 65 72 20 69 6e 74 65  lue.  Other inte
26a30 72 66 61 63 65 73 0a 2a 2a 20 77 69 6c 6c 20 61  rfaces.** will a
26a40 63 63 65 70 74 20 65 69 74 68 65 72 20 61 20 70  ccept either a p
26a50 72 6f 74 65 63 74 65 64 20 6f 72 20 61 6e 20 75  rotected or an u
26a60 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
26a70 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45 76 65  e3_value..** Eve
26a80 72 79 20 69 6e 74 65 72 66 61 63 65 20 74 68 61  ry interface tha
26a90 74 20 61 63 63 65 70 74 73 20 73 71 6c 69 74 65  t accepts sqlite
26aa0 33 5f 76 61 6c 75 65 20 61 72 67 75 6d 65 6e 74  3_value argument
26ab0 73 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77  s specifies.** w
26ac0 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 69 74  hether or not it
26ad0 20 72 65 71 75 69 72 65 73 20 61 20 70 72 6f 74   requires a prot
26ae0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
26af0 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74  lue..**.** The t
26b00 65 72 6d 73 20 22 70 72 6f 74 65 63 74 65 64 22  erms "protected"
26b10 20 61 6e 64 20 22 75 6e 70 72 6f 74 65 63 74 65   and "unprotecte
26b20 64 22 20 72 65 66 65 72 20 74 6f 20 77 68 65 74  d" refer to whet
26b30 68 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20  her or not.** a 
26b40 6d 75 74 65 78 20 69 73 20 68 65 6c 64 2e 20 20  mutex is held.  
26b50 41 6e 20 69 6e 74 65 72 6e 61 6c 20 6d 75 74 65  An internal mute
26b60 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61 20  x is held for a 
26b70 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c  protected.** sql
26b80 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
26b90 74 20 62 75 74 20 6e 6f 20 6d 75 74 65 78 20 69  t but no mutex i
26ba0 73 20 68 65 6c 64 20 66 6f 72 20 61 6e 20 75 6e  s held for an un
26bb0 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c  protected.** sql
26bc0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
26bd0 74 2e 20 20 49 66 20 53 51 4c 69 74 65 20 69 73  t.  If SQLite is
26be0 20 63 6f 6d 70 69 6c 65 64 20 74 6f 20 62 65 20   compiled to be 
26bf0 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 65 64 0a  single-threaded.
26c00 2a 2a 20 28 77 69 74 68 20 5b 53 51 4c 49 54 45  ** (with [SQLITE
26c10 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 61  _THREADSAFE=0] a
26c20 6e 64 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33  nd with [sqlite3
26c30 5f 74 68 72 65 61 64 73 61 66 65 28 29 5d 20 72  _threadsafe()] r
26c40 65 74 75 72 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f  eturning 0).** o
26c50 72 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 72  r if SQLite is r
26c60 75 6e 20 69 6e 20 6f 6e 65 20 6f 66 20 72 65 64  un in one of red
26c70 75 63 65 64 20 6d 75 74 65 78 20 6d 6f 64 65 73  uced mutex modes
26c80 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e   .** [SQLITE_CON
26c90 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44  FIG_SINGLETHREAD
26ca0 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  ] or [SQLITE_CON
26cb0 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d  FIG_MULTITHREAD]
26cc0 0a 2a 2a 20 74 68 65 6e 20 74 68 65 72 65 20 69  .** then there i
26cd0 73 20 6e 6f 20 64 69 73 74 69 6e 63 74 69 6f 6e  s no distinction
26ce0 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74   between protect
26cf0 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74  ed and unprotect
26d00 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61  ed.** sqlite3_va
26d10 6c 75 65 20 6f 62 6a 65 63 74 73 20 61 6e 64 20  lue objects and 
26d20 74 68 65 79 20 63 61 6e 20 62 65 20 75 73 65 64  they can be used
26d30 20 69 6e 74 65 72 63 68 61 6e 67 65 61 62 6c 79   interchangeably
26d40 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66  .  However,.** f
26d50 6f 72 20 6d 61 78 69 6d 75 6d 20 63 6f 64 65 20  or maximum code 
26d60 70 6f 72 74 61 62 69 6c 69 74 79 20 69 74 20 69  portability it i
26d70 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68  s recommended th
26d80 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a  at applications.
26d90 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b 65 20 74 68  ** still make th
26da0 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65  e distinction be
26db0 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20  tween protected 
26dc0 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a  and unprotected.
26dd0 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ** sqlite3_value
26de0 20 6f 62 6a 65 63 74 73 20 65 76 65 6e 20 77 68   objects even wh
26df0 65 6e 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20  en not strictly 
26e00 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20  required..**.** 
26e10 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c  ^The sqlite3_val
26e20 75 65 20 6f 62 6a 65 63 74 73 20 74 68 61 74 20  ue objects that 
26e30 61 72 65 20 70 61 73 73 65 64 20 61 73 20 70 61  are passed as pa
26e40 72 61 6d 65 74 65 72 73 20 69 6e 74 6f 20 74 68  rameters into th
26e50 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  e.** implementat
26e60 69 6f 6e 20 6f 66 20 5b 61 70 70 6c 69 63 61 74  ion of [applicat
26e70 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
26e80 66 75 6e 63 74 69 6f 6e 73 5d 20 61 72 65 20 70  functions] are p
26e90 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 5e 54 68  rotected..** ^Th
26ea0 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  e sqlite3_value 
26eb0 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20  object returned 
26ec0 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  by.** [sqlite3_c
26ed0 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69  olumn_value()] i
26ee0 73 20 75 6e 70 72 6f 74 65 63 74 65 64 2e 0a 2a  s unprotected..*
26ef0 2a 20 55 6e 70 72 6f 74 65 63 74 65 64 20 73 71  * Unprotected sq
26f00 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
26f10 63 74 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20  cts may only be 
26f20 75 73 65 64 20 77 69 74 68 0a 2a 2a 20 5b 73 71  used with.** [sq
26f30 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c  lite3_result_val
26f40 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  ue()] and [sqlit
26f50 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d  e3_bind_value()]
26f60 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65  ..** The [sqlite
26f70 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 20 7c 20 73  3_value_blob | s
26f80 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70  qlite3_value_typ
26f90 65 28 29 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a  e()] family of.*
26fa0 2a 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 71  * interfaces req
26fb0 75 69 72 65 20 70 72 6f 74 65 63 74 65 64 20 73  uire protected s
26fc0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
26fd0 65 63 74 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  ects..*/.typedef
26fe0 20 73 74 72 75 63 74 20 4d 65 6d 20 73 71 6c 69   struct Mem sqli
26ff0 74 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a  te3_value;../*.*
27000 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20  * CAPI3REF: SQL 
27010 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74  Function Context
27020 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68   Object.**.** Th
27030 65 20 63 6f 6e 74 65 78 74 20 69 6e 20 77 68 69  e context in whi
27040 63 68 20 61 6e 20 53 51 4c 20 66 75 6e 63 74 69  ch an SQL functi
27050 6f 6e 20 65 78 65 63 75 74 65 73 20 69 73 20 73  on executes is s
27060 74 6f 72 65 64 20 69 6e 20 61 6e 0a 2a 2a 20 73  tored in an.** s
27070 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f  qlite3_context o
27080 62 6a 65 63 74 2e 20 20 5e 41 20 70 6f 69 6e 74  bject.  ^A point
27090 65 72 20 74 6f 20 61 6e 20 73 71 6c 69 74 65 33  er to an sqlite3
270a0 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 0a  _context object.
270b0 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 66 69 72  ** is always fir
270c0 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
270d0 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66  [application-def
270e0 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
270f0 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c  ns]..** The appl
27100 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
27110 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70  SQL function imp
27120 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c  lementation will
27130 20 70 61 73 73 20 74 68 69 73 0a 2a 2a 20 70 6f   pass this.** po
27140 69 6e 74 65 72 20 74 68 72 6f 75 67 68 20 69 6e  inter through in
27150 74 6f 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  to calls to [sql
27160 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 20  ite3_result_int 
27170 7c 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  | sqlite3_result
27180 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
27190 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
271a0 78 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  xt()], [sqlite3_
271b0 75 73 65 72 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a  user_data()],.**
271c0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78   [sqlite3_contex
271d0 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 5d 2c 20  t_db_handle()], 
271e0 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78  [sqlite3_get_aux
271f0 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f  data()],.** and/
27200 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  or [sqlite3_set_
27210 61 75 78 64 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74  auxdata()]..*/.t
27220 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
27230 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 73 71  lite3_context sq
27240 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a  lite3_context;..
27250 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
27260 42 69 6e 64 69 6e 67 20 56 61 6c 75 65 73 20 54  Binding Values T
27270 6f 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  o Prepared State
27280 6d 65 6e 74 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  ments.** KEYWORD
27290 53 3a 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74  S: {host paramet
272a0 65 72 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65  er} {host parame
272b0 74 65 72 73 7d 20 7b 68 6f 73 74 20 70 61 72 61  ters} {host para
272c0 6d 65 74 65 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b  meter name}.** K
272d0 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 70 61  EYWORDS: {SQL pa
272e0 72 61 6d 65 74 65 72 7d 20 7b 53 51 4c 20 70 61  rameter} {SQL pa
272f0 72 61 6d 65 74 65 72 73 7d 20 7b 70 61 72 61 6d  rameters} {param
27300 65 74 65 72 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a  eter binding}.**
27310 0a 2a 2a 20 5e 28 49 6e 20 74 68 65 20 53 51 4c  .** ^(In the SQL
27320 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20   statement text 
27330 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65  input to [sqlite
27340 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
27350 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74 73  and its variants
27360 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c 73 20 6d 61  ,.** literals ma
27370 79 20 62 65 20 72 65 70 6c 61 63 65 64 20 62 79  y be replaced by
27380 20 61 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 74   a [parameter] t
27390 68 61 74 20 6d 61 74 63 68 65 73 20 6f 6e 65 20  hat matches one 
273a0 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20  of following.** 
273b0 74 65 6d 70 6c 61 74 65 73 3a 0a 2a 2a 0a 2a 2a  templates:.**.**
273c0 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f   <ul>.** <li>  ?
273d0 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a  .** <li>  ?NNN.*
273e0 2a 20 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a 20  * <li>  :VVV.** 
273f0 3c 6c 69 3e 20 20 40 56 56 56 0a 2a 2a 20 3c 6c  <li>  @VVV.** <l
27400 69 3e 20 20 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c  i>  $VVV.** </ul
27410 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 74  >.**.** In the t
27420 65 6d 70 6c 61 74 65 73 20 61 62 6f 76 65 2c 20  emplates above, 
27430 4e 4e 4e 20 72 65 70 72 65 73 65 6e 74 73 20 61  NNN represents a
27440 6e 20 69 6e 74 65 67 65 72 20 6c 69 74 65 72 61  n integer litera
27450 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56 56 20 72 65  l,.** and VVV re
27460 70 72 65 73 65 6e 74 73 20 61 6e 20 61 6c 70 68  presents an alph
27470 61 6e 75 6d 65 72 69 63 20 69 64 65 6e 74 69 66  anumeric identif
27480 69 65 72 2e 29 5e 20 20 5e 54 68 65 20 76 61 6c  ier.)^  ^The val
27490 75 65 73 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20  ues of these.** 
274a0 70 61 72 61 6d 65 74 65 72 73 20 28 61 6c 73 6f  parameters (also
274b0 20 63 61 6c 6c 65 64 20 22 68 6f 73 74 20 70 61   called "host pa
274c0 72 61 6d 65 74 65 72 20 6e 61 6d 65 73 22 20 6f  rameter names" o
274d0 72 20 22 53 51 4c 20 70 61 72 61 6d 65 74 65 72  r "SQL parameter
274e0 73 22 29 0a 2a 2a 20 63 61 6e 20 62 65 20 73 65  s").** can be se
274f0 74 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69  t using the sqli
27500 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75  te3_bind_*() rou
27510 74 69 6e 65 73 20 64 65 66 69 6e 65 64 20 68 65  tines defined he
27520 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  re..**.** ^The f
27530 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
27540 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e   the sqlite3_bin
27550 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 69  d_*() routines i
27560 73 20 61 6c 77 61 79 73 0a 2a 2a 20 61 20 70 6f  s always.** a po
27570 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71  inter to the [sq
27580 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65  lite3_stmt] obje
27590 63 74 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d  ct returned from
275a0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
275b0 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 69 74  pare_v2()] or it
275c0 73 20 76 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a 2a  s variants..**.*
275d0 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72  * ^The second ar
275e0 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e  gument is the in
275f0 64 65 78 20 6f 66 20 74 68 65 20 53 51 4c 20 70  dex of the SQL p
27600 61 72 61 6d 65 74 65 72 20 74 6f 20 62 65 20 73  arameter to be s
27610 65 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74  et..** ^The left
27620 6d 6f 73 74 20 53 51 4c 20 70 61 72 61 6d 65 74  most SQL paramet
27630 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20  er has an index 
27640 6f 66 20 31 2e 20 20 5e 57 68 65 6e 20 74 68 65  of 1.  ^When the
27650 20 73 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20 53   same named.** S
27660 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  QL parameter is 
27670 75 73 65 64 20 6d 6f 72 65 20 74 68 61 6e 20 6f  used more than o
27680 6e 63 65 2c 20 73 65 63 6f 6e 64 20 61 6e 64 20  nce, second and 
27690 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 6f 63  subsequent.** oc
276a0 63 75 72 72 65 6e 63 65 73 20 68 61 76 65 20 74  currences have t
276b0 68 65 20 73 61 6d 65 20 69 6e 64 65 78 20 61 73  he same index as
276c0 20 74 68 65 20 66 69 72 73 74 20 6f 63 63 75 72   the first occur
276d0 72 65 6e 63 65 2e 0a 2a 2a 20 5e 54 68 65 20 69  rence..** ^The i
276e0 6e 64 65 78 20 66 6f 72 20 6e 61 6d 65 64 20 70  ndex for named p
276f0 61 72 61 6d 65 74 65 72 73 20 63 61 6e 20 62 65  arameters can be
27700 20 6c 6f 6f 6b 65 64 20 75 70 20 75 73 69 6e 67   looked up using
27710 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
27720 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
27730 69 6e 64 65 78 28 29 5d 20 41 50 49 20 69 66 20  index()] API if 
27740 64 65 73 69 72 65 64 2e 20 20 5e 54 68 65 20 69  desired.  ^The i
27750 6e 64 65 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e  ndex.** for "?NN
27760 4e 22 20 70 61 72 61 6d 65 74 65 72 73 20 69 73  N" parameters is
27770 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 4e 4e   the value of NN
27780 4e 2e 0a 2a 2a 20 5e 54 68 65 20 4e 4e 4e 20 76  N..** ^The NNN v
27790 61 6c 75 65 20 6d 75 73 74 20 62 65 20 62 65 74  alue must be bet
277a0 77 65 65 6e 20 31 20 61 6e 64 20 74 68 65 20 5b  ween 1 and the [
277b0 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d  sqlite3_limit()]
277c0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 5b 53  .** parameter [S
277d0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49  QLITE_LIMIT_VARI
277e0 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 20 28 64 65  ABLE_NUMBER] (de
277f0 66 61 75 6c 74 20 76 61 6c 75 65 3a 20 39 39 39  fault value: 999
27800 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68  )..**.** ^The th
27810 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ird argument is 
27820 74 68 65 20 76 61 6c 75 65 20 74 6f 20 62 69 6e  the value to bin
27830 64 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74  d to the paramet
27840 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74  er..**.** ^(In t
27850 68 6f 73 65 20 72 6f 75 74 69 6e 65 73 20 74 68  hose routines th
27860 61 74 20 68 61 76 65 20 61 20 66 6f 75 72 74 68  at have a fourth
27870 20 61 72 67 75 6d 65 6e 74 2c 20 69 74 73 20 76   argument, its v
27880 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e  alue is the.** n
27890 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
278a0 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e  n the parameter.
278b0 20 20 54 6f 20 62 65 20 63 6c 65 61 72 3a 20 74    To be clear: t
278c0 68 65 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a  he value is the.
278d0 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 3c 75 3e  ** number of <u>
278e0 62 79 74 65 73 3c 2f 75 3e 20 69 6e 20 74 68 65  bytes</u> in the
278f0 20 76 61 6c 75 65 2c 20 6e 6f 74 20 74 68 65 20   value, not the 
27900 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63  number of charac
27910 74 65 72 73 2e 29 5e 0a 2a 2a 20 5e 49 66 20 74  ters.)^.** ^If t
27920 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
27930 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62  ter to sqlite3_b
27940 69 6e 64 5f 74 65 78 74 28 29 20 6f 72 20 73 71  ind_text() or sq
27950 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31  lite3_bind_text1
27960 36 28 29 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69  6().** is negati
27970 76 65 2c 20 74 68 65 6e 20 74 68 65 20 6c 65 6e  ve, then the len
27980 67 74 68 20 6f 66 20 74 68 65 20 73 74 72 69 6e  gth of the strin
27990 67 20 69 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62  g is.** the numb
279a0 65 72 20 6f 66 20 62 79 74 65 73 20 75 70 20 74  er of bytes up t
279b0 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f  o the first zero
279c0 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 20   terminator..** 
279d0 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  If the fourth pa
279e0 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
279f0 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 20 69  e3_bind_blob() i
27a00 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e  s negative, then
27a10 0a 2a 2a 20 74 68 65 20 62 65 68 61 76 69 6f 72  .** the behavior
27a20 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
27a30 2a 20 49 66 20 61 20 6e 6f 6e 2d 6e 65 67 61 74  * If a non-negat
27a40 69 76 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  ive fourth param
27a50 65 74 65 72 20 69 73 20 70 72 6f 76 69 64 65 64  eter is provided
27a60 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   to sqlite3_bind
27a70 5f 74 65 78 74 28 29 0a 2a 2a 20 6f 72 20 73 71  _text().** or sq
27a80 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31  lite3_bind_text1
27a90 36 28 29 20 74 68 65 6e 20 74 68 61 74 20 70 61  6() then that pa
27aa0 72 61 6d 65 74 65 72 20 6d 75 73 74 20 62 65 20  rameter must be 
27ab0 74 68 65 20 62 79 74 65 20 6f 66 66 73 65 74 0a  the byte offset.
27ac0 2a 2a 20 77 68 65 72 65 20 74 68 65 20 4e 55 4c  ** where the NUL
27ad0 20 74 65 72 6d 69 6e 61 74 6f 72 20 77 6f 75 6c   terminator woul
27ae0 64 20 6f 63 63 75 72 20 61 73 73 75 6d 69 6e 67  d occur assuming
27af0 20 74 68 65 20 73 74 72 69 6e 67 20 77 65 72 65   the string were
27b00 20 4e 55 4c 0a 2a 2a 20 74 65 72 6d 69 6e 61 74   NUL.** terminat
27b10 65 64 2e 20 20 49 66 20 61 6e 79 20 4e 55 4c 20  ed.  If any NUL 
27b20 63 68 61 72 61 63 74 65 72 73 20 6f 63 63 75 72  characters occur
27b30 20 61 74 20 62 79 74 65 20 6f 66 66 73 65 74 73   at byte offsets
27b40 20 6c 65 73 73 20 74 68 61 6e 20 0a 2a 2a 20 74   less than .** t
27b50 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  he value of the 
27b60 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
27b70 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74   then the result
27b80 69 6e 67 20 73 74 72 69 6e 67 20 76 61 6c 75 65  ing string value
27b90 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 74 61 69 6e   will.** contain
27ba0 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 2e 20   embedded NULs. 
27bb0 20 54 68 65 20 72 65 73 75 6c 74 20 6f 66 20 65   The result of e
27bc0 78 70 72 65 73 73 69 6f 6e 73 20 69 6e 76 6f 6c  xpressions invol
27bd0 76 69 6e 67 20 73 74 72 69 6e 67 73 0a 2a 2a 20  ving strings.** 
27be0 77 69 74 68 20 65 6d 62 65 64 64 65 64 20 4e 55  with embedded NU
27bf0 4c 73 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  Ls is undefined.
27c00 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 66 74  .**.** ^The fift
27c10 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  h argument to sq
27c20 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28  lite3_bind_blob(
27c30 29 2c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  ), sqlite3_bind_
27c40 74 65 78 74 28 29 2c 20 61 6e 64 0a 2a 2a 20 73  text(), and.** s
27c50 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
27c60 31 36 28 29 20 69 73 20 61 20 64 65 73 74 72 75  16() is a destru
27c70 63 74 6f 72 20 75 73 65 64 20 74 6f 20 64 69 73  ctor used to dis
27c80 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42  pose of the BLOB
27c90 20 6f 72 0a 2a 2a 20 73 74 72 69 6e 67 20 61 66   or.** string af
27ca0 74 65 72 20 53 51 4c 69 74 65 20 68 61 73 20 66  ter SQLite has f
27cb0 69 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 2e  inished with it.
27cc0 20 20 5e 54 68 65 20 64 65 73 74 72 75 63 74 6f    ^The destructo
27cd0 72 20 69 73 20 63 61 6c 6c 65 64 0a 2a 2a 20 74  r is called.** t
27ce0 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65  o dispose of the
27cf0 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 20   BLOB or string 
27d00 65 76 65 6e 20 69 66 20 74 68 65 20 63 61 6c 6c  even if the call
27d10 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   to sqlite3_bind
27d20 5f 62 6c 6f 62 28 29 2c 0a 2a 2a 20 73 71 6c 69  _blob(),.** sqli
27d30 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 2c  te3_bind_text(),
27d40 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   or sqlite3_bind
27d50 5f 74 65 78 74 31 36 28 29 20 66 61 69 6c 73 2e  _text16() fails.
27d60 20 20 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69    .** ^If the fi
27d70 66 74 68 20 61 72 67 75 6d 65 6e 74 20 69 73 0a  fth argument is.
27d80 2a 2a 20 74 68 65 20 73 70 65 63 69 61 6c 20 76  ** the special v
27d90 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 53 54 41  alue [SQLITE_STA
27da0 54 49 43 5d 2c 20 74 68 65 6e 20 53 51 4c 69 74  TIC], then SQLit
27db0 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74  e assumes that t
27dc0 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  he.** informatio
27dd0 6e 20 69 73 20 69 6e 20 73 74 61 74 69 63 2c 20  n is in static, 
27de0 75 6e 6d 61 6e 61 67 65 64 20 73 70 61 63 65 20  unmanaged space 
27df0 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65  and does not nee
27e00 64 20 74 6f 20 62 65 20 66 72 65 65 64 2e 0a 2a  d to be freed..*
27e10 2a 20 5e 49 66 20 74 68 65 20 66 69 66 74 68 20  * ^If the fifth 
27e20 61 72 67 75 6d 65 6e 74 20 68 61 73 20 74 68 65  argument has the
27e30 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 54   value [SQLITE_T
27e40 52 41 4e 53 49 45 4e 54 5d 2c 20 74 68 65 6e 0a  RANSIENT], then.
27e50 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20  ** SQLite makes 
27e60 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20  its own private 
27e70 63 6f 70 79 20 6f 66 20 74 68 65 20 64 61 74 61  copy of the data
27e80 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62 65   immediately, be
27e90 66 6f 72 65 0a 2a 2a 20 74 68 65 20 73 71 6c 69  fore.** the sqli
27ea0 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75  te3_bind_*() rou
27eb0 74 69 6e 65 20 72 65 74 75 72 6e 73 2e 0a 2a 2a  tine returns..**
27ec0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
27ed0 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 29  _bind_zeroblob()
27ee0 20 72 6f 75 74 69 6e 65 20 62 69 6e 64 73 20 61   routine binds a
27ef0 20 42 4c 4f 42 20 6f 66 20 6c 65 6e 67 74 68 20   BLOB of length 
27f00 4e 20 74 68 61 74 0a 2a 2a 20 69 73 20 66 69 6c  N that.** is fil
27f10 6c 65 64 20 77 69 74 68 20 7a 65 72 6f 65 73 2e  led with zeroes.
27f20 20 20 5e 41 20 7a 65 72 6f 62 6c 6f 62 20 75 73    ^A zeroblob us
27f30 65 73 20 61 20 66 69 78 65 64 20 61 6d 6f 75 6e  es a fixed amoun
27f40 74 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28  t of memory.** (
27f50 6a 75 73 74 20 61 6e 20 69 6e 74 65 67 65 72 20  just an integer 
27f60 74 6f 20 68 6f 6c 64 20 69 74 73 20 73 69 7a 65  to hold its size
27f70 29 20 77 68 69 6c 65 20 69 74 20 69 73 20 62 65  ) while it is be
27f80 69 6e 67 20 70 72 6f 63 65 73 73 65 64 2e 0a 2a  ing processed..*
27f90 2a 20 5a 65 72 6f 62 6c 6f 62 73 20 61 72 65 20  * Zeroblobs are 
27fa0 69 6e 74 65 6e 64 65 64 20 74 6f 20 73 65 72 76  intended to serv
27fb0 65 20 61 73 20 70 6c 61 63 65 68 6f 6c 64 65 72  e as placeholder
27fc0 73 20 66 6f 72 20 42 4c 4f 42 73 20 77 68 6f 73  s for BLOBs whos
27fd0 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 69 73 20  e.** content is 
27fe0 6c 61 74 65 72 20 77 72 69 74 74 65 6e 20 75 73  later written us
27ff0 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
28000 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72  blob_open | incr
28010 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20 49 2f 4f  emental BLOB I/O
28020 5d 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 5e  ] routines..** ^
28030 41 20 6e 65 67 61 74 69 76 65 20 76 61 6c 75 65  A negative value
28040 20 66 6f 72 20 74 68 65 20 7a 65 72 6f 62 6c 6f   for the zeroblo
28050 62 20 72 65 73 75 6c 74 73 20 69 6e 20 61 20 7a  b results in a z
28060 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 2e  ero-length BLOB.
28070 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 79 20 6f  .**.** ^If any o
28080 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69  f the sqlite3_bi
28090 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20  nd_*() routines 
280a0 61 72 65 20 63 61 6c 6c 65 64 20 77 69 74 68 20  are called with 
280b0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a  a NULL pointer.*
280c0 2a 20 66 6f 72 20 74 68 65 20 5b 70 72 65 70 61  * for the [prepa
280d0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f  red statement] o
280e0 72 20 77 69 74 68 20 61 20 70 72 65 70 61 72 65  r with a prepare
280f0 64 20 73 74 61 74 65 6d 65 6e 74 20 66 6f 72 20  d statement for 
28100 77 68 69 63 68 0a 2a 2a 20 5b 73 71 6c 69 74 65  which.** [sqlite
28110 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 62 65  3_step()] has be
28120 65 6e 20 63 61 6c 6c 65 64 20 6d 6f 72 65 20 72  en called more r
28130 65 63 65 6e 74 6c 79 20 74 68 61 6e 20 5b 73 71  ecently than [sq
28140 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 2c 0a  lite3_reset()],.
28150 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c  ** then the call
28160 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51   will return [SQ
28170 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 49  LITE_MISUSE].  I
28180 66 20 61 6e 79 20 73 71 6c 69 74 65 33 5f 62 69  f any sqlite3_bi
28190 6e 64 5f 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65  nd_().** routine
281a0 20 69 73 20 70 61 73 73 65 64 20 61 20 5b 70 72   is passed a [pr
281b0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
281c0 5d 20 74 68 61 74 20 68 61 73 20 62 65 65 6e 20  ] that has been 
281d0 66 69 6e 61 6c 69 7a 65 64 2c 20 74 68 65 0a 2a  finalized, the.*
281e0 2a 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65  * result is unde
281f0 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62  fined and probab
28200 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a  ly harmful..**.*
28210 2a 20 5e 42 69 6e 64 69 6e 67 73 20 61 72 65 20  * ^Bindings are 
28220 6e 6f 74 20 63 6c 65 61 72 65 64 20 62 79 20 74  not cleared by t
28230 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  he [sqlite3_rese
28240 74 28 29 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a  t()] routine..**
28250 20 5e 55 6e 62 6f 75 6e 64 20 70 61 72 61 6d 65   ^Unbound parame
28260 74 65 72 73 20 61 72 65 20 69 6e 74 65 72 70 72  ters are interpr
28270 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a  eted as NULL..**
28280 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
28290 5f 62 69 6e 64 5f 2a 20 72 6f 75 74 69 6e 65 73  _bind_* routines
282a0 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
282b0 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 6f  OK] on success o
282c0 72 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20 63  r an.** [error c
282d0 6f 64 65 5d 20 69 66 20 61 6e 79 74 68 69 6e 67  ode] if anything
282e0 20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20   goes wrong..** 
282f0 5e 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45 5d 20  ^[SQLITE_RANGE] 
28300 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 74  is returned if t
28310 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  he parameter.** 
28320 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20  index is out of 
28330 72 61 6e 67 65 2e 20 20 5e 5b 53 51 4c 49 54 45  range.  ^[SQLITE
28340 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72 65 74 75 72  _NOMEM] is retur
28350 6e 65 64 20 69 66 20 6d 61 6c 6c 6f 63 28 29 20  ned if malloc() 
28360 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  fails..**.** See
28370 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
28380 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63  bind_parameter_c
28390 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  ount()],.** [sql
283a0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
283b0 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64  ter_name()], and
283c0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
283d0 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29  arameter_index()
283e0 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  ]..*/.int sqlite
283f0 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 73 71 6c 69  3_bind_blob(sqli
28400 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
28410 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
28420 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64   n, void(*)(void
28430 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  *));.int sqlite3
28440 5f 62 69 6e 64 5f 64 6f 75 62 6c 65 28 73 71 6c  _bind_double(sql
28450 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
28460 20 64 6f 75 62 6c 65 29 3b 0a 69 6e 74 20 73 71   double);.int sq
28470 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 28 73  lite3_bind_int(s
28480 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
28490 74 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c  t, int);.int sql
284a0 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 36 34 28  ite3_bind_int64(
284b0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
284c0 6e 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  nt, sqlite3_int6
284d0 34 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  4);.int sqlite3_
284e0 62 69 6e 64 5f 6e 75 6c 6c 28 73 71 6c 69 74 65  bind_null(sqlite
284f0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 69  3_stmt*, int);.i
28500 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
28510 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  text(sqlite3_stm
28520 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 63  t*, int, const c
28530 68 61 72 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69  har*, int n, voi
28540 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e  d(*)(void*));.in
28550 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  t sqlite3_bind_t
28560 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ext16(sqlite3_st
28570 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20  mt*, int, const 
28580 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64  void*, int, void
28590 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74  (*)(void*));.int
285a0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61   sqlite3_bind_va
285b0 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  lue(sqlite3_stmt
285c0 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 73 71  *, int, const sq
285d0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69  lite3_value*);.i
285e0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
285f0 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33  zeroblob(sqlite3
28600 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74  _stmt*, int, int
28610 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49   n);../*.** CAPI
28620 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20  3REF: Number Of 
28630 53 51 4c 20 50 61 72 61 6d 65 74 65 72 73 0a 2a  SQL Parameters.*
28640 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69  *.** ^This routi
28650 6e 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  ne can be used t
28660 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65  o find the numbe
28670 72 20 6f 66 20 5b 53 51 4c 20 70 61 72 61 6d 65  r of [SQL parame
28680 74 65 72 73 5d 0a 2a 2a 20 69 6e 20 61 20 5b 70  ters].** in a [p
28690 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
286a0 74 5d 2e 20 20 53 51 4c 20 70 61 72 61 6d 65 74  t].  SQL paramet
286b0 65 72 73 20 61 72 65 20 74 6f 6b 65 6e 73 20 6f  ers are tokens o
286c0 66 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 20 22 3f  f the.** form "?
286d0 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41 41 41  ", "?NNN", ":AAA
286e0 22 2c 20 22 24 41 41 41 22 2c 20 6f 72 20 22 40  ", "$AAA", or "@
286f0 41 41 41 22 20 74 68 61 74 20 73 65 72 76 65 20  AAA" that serve 
28700 61 73 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c 64 65  as.** placeholde
28710 72 73 20 66 6f 72 20 76 61 6c 75 65 73 20 74 68  rs for values th
28720 61 74 20 61 72 65 20 5b 73 71 6c 69 74 65 33 5f  at are [sqlite3_
28730 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f 75 6e  bind_blob | boun
28740 64 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 70 61 72  d].** to the par
28750 61 6d 65 74 65 72 73 20 61 74 20 61 20 6c 61 74  ameters at a lat
28760 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e  er time..**.** ^
28770 28 54 68 69 73 20 72 6f 75 74 69 6e 65 20 61 63  (This routine ac
28780 74 75 61 6c 6c 79 20 72 65 74 75 72 6e 73 20 74  tually returns t
28790 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20  he index of the 
287a0 6c 61 72 67 65 73 74 20 28 72 69 67 68 74 6d 6f  largest (rightmo
287b0 73 74 29 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  st).** parameter
287c0 2e 20 46 6f 72 20 61 6c 6c 20 66 6f 72 6d 73 20  . For all forms 
287d0 65 78 63 65 70 74 20 3f 4e 4e 4e 2c 20 74 68 69  except ?NNN, thi
287e0 73 20 77 69 6c 6c 20 63 6f 72 72 65 73 70 6f 6e  s will correspon
287f0 64 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 75 6d 62  d to the.** numb
28800 65 72 20 6f 66 20 75 6e 69 71 75 65 20 70 61 72  er of unique par
28810 61 6d 65 74 65 72 73 2e 20 20 49 66 20 70 61 72  ameters.  If par
28820 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 3f  ameters of the ?
28830 4e 4e 4e 20 66 6f 72 6d 20 61 72 65 20 75 73 65  NNN form are use
28840 64 2c 0a 2a 2a 20 74 68 65 72 65 20 6d 61 79 20  d,.** there may 
28850 62 65 20 67 61 70 73 20 69 6e 20 74 68 65 20 6c  be gaps in the l
28860 69 73 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65  ist.)^.**.** See
28870 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
28880 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65  bind_blob|sqlite
28890 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73  3_bind()],.** [s
288a0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
288b0 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61  meter_name()], a
288c0 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  nd.** [sqlite3_b
288d0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
288e0 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73  dex()]..*/.int s
288f0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
28900 6d 65 74 65 72 5f 63 6f 75 6e 74 28 73 71 6c 69  meter_count(sqli
28910 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a  te3_stmt*);../*.
28920 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d  ** CAPI3REF: Nam
28930 65 20 4f 66 20 41 20 48 6f 73 74 20 50 61 72 61  e Of A Host Para
28940 6d 65 74 65 72 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  meter.**.** ^The
28950 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61   sqlite3_bind_pa
28960 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 50 2c 4e  rameter_name(P,N
28970 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
28980 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20  rns.** the name 
28990 6f 66 20 74 68 65 20 4e 2d 74 68 20 5b 53 51 4c  of the N-th [SQL
289a0 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74   parameter] in t
289b0 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
289c0 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 28  tement] P..** ^(
289d0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 6f  SQL parameters o
289e0 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e  f the form "?NNN
289f0 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22  " or ":AAA" or "
28a00 40 41 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a  @AAA" or "$AAA".
28a10 2a 2a 20 68 61 76 65 20 61 20 6e 61 6d 65 20 77  ** have a name w
28a20 68 69 63 68 20 69 73 20 74 68 65 20 73 74 72 69  hich is the stri
28a30 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41  ng "?NNN" or ":A
28a40 41 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72  AA" or "@AAA" or
28a50 20 22 24 41 41 41 22 0a 2a 2a 20 72 65 73 70 65   "$AAA".** respe
28a60 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f  ctively..** In o
28a70 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20  ther words, the 
28a80 69 6e 69 74 69 61 6c 20 22 3a 22 20 6f 72 20 22  initial ":" or "
28a90 24 22 20 6f 72 20 22 40 22 20 6f 72 20 22 3f 22  $" or "@" or "?"
28aa0 0a 2a 2a 20 69 73 20 69 6e 63 6c 75 64 65 64 20  .** is included 
28ab0 61 73 20 70 61 72 74 20 6f 66 20 74 68 65 20 6e  as part of the n
28ac0 61 6d 65 2e 29 5e 0a 2a 2a 20 5e 50 61 72 61 6d  ame.)^.** ^Param
28ad0 65 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72  eters of the for
28ae0 6d 20 22 3f 22 20 77 69 74 68 6f 75 74 20 61 20  m "?" without a 
28af0 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 67 65  following intege
28b00 72 20 68 61 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a  r have no name.*
28b10 2a 20 61 6e 64 20 61 72 65 20 72 65 66 65 72 72  * and are referr
28b20 65 64 20 74 6f 20 61 73 20 22 6e 61 6d 65 6c 65  ed to as "namele
28b30 73 73 22 20 6f 72 20 22 61 6e 6f 6e 79 6d 6f 75  ss" or "anonymou
28b40 73 20 70 61 72 61 6d 65 74 65 72 73 22 2e 0a 2a  s parameters"..*
28b50 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  *.** ^The first 
28b60 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 68  host parameter h
28b70 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31  as an index of 1
28b80 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e  , not 0..**.** ^
28b90 49 66 20 74 68 65 20 76 61 6c 75 65 20 4e 20 69  If the value N i
28ba0 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 6f  s out of range o
28bb0 72 20 69 66 20 74 68 65 20 4e 2d 74 68 20 70 61  r if the N-th pa
28bc0 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 6e 61  rameter is.** na
28bd0 6d 65 6c 65 73 73 2c 20 74 68 65 6e 20 4e 55 4c  meless, then NUL
28be0 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20  L is returned.  
28bf0 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74  ^The returned st
28c00 72 69 6e 67 20 69 73 0a 2a 2a 20 61 6c 77 61 79  ring is.** alway
28c10 73 20 69 6e 20 55 54 46 2d 38 20 65 6e 63 6f 64  s in UTF-8 encod
28c20 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65 20  ing even if the 
28c30 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72 20  named parameter 
28c40 77 61 73 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c  was.** originall
28c50 79 20 73 70 65 63 69 66 69 65 64 20 61 73 20 55  y specified as U
28c60 54 46 2d 31 36 20 69 6e 20 5b 73 71 6c 69 74 65  TF-16 in [sqlite
28c70 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 6f  3_prepare16()] o
28c80 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  r.** [sqlite3_pr
28c90 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a  epare16_v2()]..*
28ca0 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
28cb0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
28cc0 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29  b|sqlite3_bind()
28cd0 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  ],.** [sqlite3_b
28ce0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f  ind_parameter_co
28cf0 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b  unt()], and.** [
28d00 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
28d10 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e  ameter_index()].
28d20 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  .*/.const char *
28d30 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
28d40 61 6d 65 74 65 72 5f 6e 61 6d 65 28 73 71 6c 69  ameter_name(sqli
28d50 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b  te3_stmt*, int);
28d60 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
28d70 3a 20 49 6e 64 65 78 20 4f 66 20 41 20 50 61 72  : Index Of A Par
28d80 61 6d 65 74 65 72 20 57 69 74 68 20 41 20 47 69  ameter With A Gi
28d90 76 65 6e 20 4e 61 6d 65 0a 2a 2a 0a 2a 2a 20 5e  ven Name.**.** ^
28da0 52 65 74 75 72 6e 20 74 68 65 20 69 6e 64 65 78  Return the index
28db0 20 6f 66 20 61 6e 20 53 51 4c 20 70 61 72 61 6d   of an SQL param
28dc0 65 74 65 72 20 67 69 76 65 6e 20 69 74 73 20 6e  eter given its n
28dd0 61 6d 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 69 6e  ame.  ^The.** in
28de0 64 65 78 20 76 61 6c 75 65 20 72 65 74 75 72 6e  dex value return
28df0 65 64 20 69 73 20 73 75 69 74 61 62 6c 65 20 66  ed is suitable f
28e00 6f 72 20 75 73 65 20 61 73 20 74 68 65 20 73 65  or use as the se
28e10 63 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65  cond.** paramete
28e20 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69  r to [sqlite3_bi
28e30 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f  nd_blob|sqlite3_
28e40 62 69 6e 64 28 29 5d 2e 20 20 5e 41 20 7a 65 72  bind()].  ^A zer
28e50 6f 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64  o.** is returned
28e60 20 69 66 20 6e 6f 20 6d 61 74 63 68 69 6e 67 20   if no matching 
28e70 70 61 72 61 6d 65 74 65 72 20 69 73 20 66 6f 75  parameter is fou
28e80 6e 64 2e 20 20 5e 54 68 65 20 70 61 72 61 6d 65  nd.  ^The parame
28e90 74 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73 74  ter.** name must
28ea0 20 62 65 20 67 69 76 65 6e 20 69 6e 20 55 54 46   be given in UTF
28eb0 2d 38 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f  -8 even if the o
28ec0 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e  riginal statemen
28ed0 74 0a 2a 2a 20 77 61 73 20 70 72 65 70 61 72 65  t.** was prepare
28ee0 64 20 66 72 6f 6d 20 55 54 46 2d 31 36 20 74 65  d from UTF-16 te
28ef0 78 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  xt using [sqlite
28f00 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
28f10 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  ]..**.** See als
28f20 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  o: [sqlite3_bind
28f30 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69  _blob|sqlite3_bi
28f40 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  nd()],.** [sqlit
28f50 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
28f60 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a  r_count()], and.
28f70 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
28f80 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
28f90 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ()]..*/.int sqli
28fa0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
28fb0 65 72 5f 69 6e 64 65 78 28 73 71 6c 69 74 65 33  er_index(sqlite3
28fc0 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73 74 20 63 68  _stmt*, const ch
28fd0 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a  ar *zName);../*.
28fe0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73  ** CAPI3REF: Res
28ff0 65 74 20 41 6c 6c 20 42 69 6e 64 69 6e 67 73 20  et All Bindings 
29000 4f 6e 20 41 20 50 72 65 70 61 72 65 64 20 53 74  On A Prepared St
29010 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 43  atement.**.** ^C
29020 6f 6e 74 72 61 72 79 20 74 6f 20 74 68 65 20 69  ontrary to the i
29030 6e 74 75 69 74 69 6f 6e 20 6f 66 20 6d 61 6e 79  ntuition of many
29040 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  , [sqlite3_reset
29050 28 29 5d 20 64 6f 65 73 20 6e 6f 74 20 72 65 73  ()] does not res
29060 65 74 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74  et.** the [sqlit
29070 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62  e3_bind_blob | b
29080 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 61 20 5b 70  indings] on a [p
29090 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
290a0 74 5d 2e 0a 2a 2a 20 5e 55 73 65 20 74 68 69 73  t]..** ^Use this
290b0 20 72 6f 75 74 69 6e 65 20 74 6f 20 72 65 73 65   routine to rese
290c0 74 20 61 6c 6c 20 68 6f 73 74 20 70 61 72 61 6d  t all host param
290d0 65 74 65 72 73 20 74 6f 20 4e 55 4c 4c 2e 0a 2a  eters to NULL..*
290e0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c  /.int sqlite3_cl
290f0 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c  ear_bindings(sql
29100 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a  ite3_stmt*);../*
29110 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75  .** CAPI3REF: Nu
29120 6d 62 65 72 20 4f 66 20 43 6f 6c 75 6d 6e 73 20  mber Of Columns 
29130 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a  In A Result Set.
29140 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68  **.** ^Return th
29150 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  e number of colu
29160 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c  mns in the resul
29170 74 20 73 65 74 20 72 65 74 75 72 6e 65 64 20 62  t set returned b
29180 79 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  y the.** [prepar
29190 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 5e  ed statement]. ^
291a0 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74  This routine ret
291b0 75 72 6e 73 20 30 20 69 66 20 70 53 74 6d 74 20  urns 0 if pStmt 
291c0 69 73 20 61 6e 20 53 51 4c 0a 2a 2a 20 73 74 61  is an SQL.** sta
291d0 74 65 6d 65 6e 74 20 74 68 61 74 20 64 6f 65 73  tement that does
291e0 20 6e 6f 74 20 72 65 74 75 72 6e 20 64 61 74 61   not return data
291f0 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 61 6e   (for example an
29200 20 5b 55 50 44 41 54 45 5d 29 2e 0a 2a 2a 0a 2a   [UPDATE])..**.*
29210 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
29220 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
29230 29 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  )].*/.int sqlite
29240 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73  3_column_count(s
29250 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
29260 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
29270 33 52 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d  3REF: Column Nam
29280 65 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53  es In A Result S
29290 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  et.**.** ^These 
292a0 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
292b0 74 68 65 20 6e 61 6d 65 20 61 73 73 69 67 6e 65  the name assigne
292c0 64 20 74 6f 20 61 20 70 61 72 74 69 63 75 6c 61  d to a particula
292d0 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74  r column.** in t
292e0 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66  he result set of
292f0 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74   a [SELECT] stat
29300 65 6d 65 6e 74 2e 20 20 5e 54 68 65 20 73 71 6c  ement.  ^The sql
29310 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
29320 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  ().** interface 
29330 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
29340 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d  r to a zero-term
29350 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72  inated UTF-8 str
29360 69 6e 67 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74  ing.** and sqlit
29370 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36  e3_column_name16
29380 28 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  () returns a poi
29390 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74  nter to a zero-t
293a0 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46  erminated.** UTF
293b0 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 68  -16 string.  ^Th
293c0 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
293d0 72 20 69 73 20 74 68 65 20 5b 70 72 65 70 61 72  r is the [prepar
293e0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a  ed statement].**
293f0 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73   that implements
29400 20 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74   the [SELECT] st
29410 61 74 65 6d 65 6e 74 2e 20 5e 54 68 65 20 73 65  atement. ^The se
29420 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69  cond parameter i
29430 73 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20  s the.** column 
29440 6e 75 6d 62 65 72 2e 20 20 5e 54 68 65 20 6c 65  number.  ^The le
29450 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73  ftmost column is
29460 20 6e 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a   number 0..**.**
29470 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73   ^The returned s
29480 74 72 69 6e 67 20 70 6f 69 6e 74 65 72 20 69 73  tring pointer is
29490 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 65 69 74   valid until eit
294a0 68 65 72 20 74 68 65 20 5b 70 72 65 70 61 72 65  her the [prepare
294b0 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20  d statement].** 
294c0 69 73 20 64 65 73 74 72 6f 79 65 64 20 62 79 20  is destroyed by 
294d0 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
294e0 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68  e()] or until th
294f0 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61  e statement is a
29500 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20  utomatically.** 
29510 72 65 70 72 65 70 61 72 65 64 20 62 79 20 74 68  reprepared by th
29520 65 20 66 69 72 73 74 20 63 61 6c 6c 20 74 6f 20  e first call to 
29530 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
29540 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61   for a particula
29550 72 20 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69  r run.** or unti
29560 6c 20 74 68 65 20 6e 65 78 74 20 63 61 6c 6c 20  l the next call 
29570 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  to.** sqlite3_co
29580 6c 75 6d 6e 5f 6e 61 6d 65 28 29 20 6f 72 20 73  lumn_name() or s
29590 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
295a0 6d 65 31 36 28 29 20 6f 6e 20 74 68 65 20 73 61  me16() on the sa
295b0 6d 65 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a  me column..**.**
295c0 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c   ^If sqlite3_mal
295d0 6c 6f 63 28 29 20 66 61 69 6c 73 20 64 75 72 69  loc() fails duri
295e0 6e 67 20 74 68 65 20 70 72 6f 63 65 73 73 69 6e  ng the processin
295f0 67 20 6f 66 20 65 69 74 68 65 72 20 72 6f 75 74  g of either rout
29600 69 6e 65 0a 2a 2a 20 28 66 6f 72 20 65 78 61 6d  ine.** (for exam
29610 70 6c 65 20 64 75 72 69 6e 67 20 61 20 63 6f 6e  ple during a con
29620 76 65 72 73 69 6f 6e 20 66 72 6f 6d 20 55 54 46  version from UTF
29630 2d 38 20 74 6f 20 55 54 46 2d 31 36 29 20 74 68  -8 to UTF-16) th
29640 65 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69  en a.** NULL poi
29650 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 64  nter is returned
29660 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d  ..**.** ^The nam
29670 65 20 6f 66 20 61 20 72 65 73 75 6c 74 20 63 6f  e of a result co
29680 6c 75 6d 6e 20 69 73 20 74 68 65 20 76 61 6c 75  lumn is the valu
29690 65 20 6f 66 20 74 68 65 20 22 41 53 22 20 63 6c  e of the "AS" cl
296a0 61 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68 61 74  ause for.** that
296b0 20 63 6f 6c 75 6d 6e 2c 20 69 66 20 74 68 65 72   column, if ther
296c0 65 20 69 73 20 61 6e 20 41 53 20 63 6c 61 75 73  e is an AS claus
296d0 65 2e 20 20 49 66 20 74 68 65 72 65 20 69 73 20  e.  If there is 
296e0 6e 6f 20 41 53 20 63 6c 61 75 73 65 0a 2a 2a 20  no AS clause.** 
296f0 74 68 65 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66  then the name of
29700 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 75   the column is u
29710 6e 73 70 65 63 69 66 69 65 64 20 61 6e 64 20 6d  nspecified and m
29720 61 79 20 63 68 61 6e 67 65 20 66 72 6f 6d 0a 2a  ay change from.*
29730 2a 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 6f 66  * one release of
29740 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20 6e   SQLite to the n
29750 65 78 74 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68  ext..*/.const ch
29760 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ar *sqlite3_colu
29770 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f  mn_name(sqlite3_
29780 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 63  stmt*, int N);.c
29790 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
297a0 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36  e3_column_name16
297b0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
297c0 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  int N);../*.** C
297d0 41 50 49 33 52 45 46 3a 20 53 6f 75 72 63 65 20  API3REF: Source 
297e0 4f 66 20 44 61 74 61 20 49 6e 20 41 20 51 75 65  Of Data In A Que
297f0 72 79 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20  ry Result.**.** 
29800 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
29810 70 72 6f 76 69 64 65 20 61 20 6d 65 61 6e 73 20  provide a means 
29820 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65  to determine the
29830 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65   database, table
29840 2c 20 61 6e 64 0a 2a 2a 20 74 61 62 6c 65 20 63  , and.** table c
29850 6f 6c 75 6d 6e 20 74 68 61 74 20 69 73 20 74 68  olumn that is th
29860 65 20 6f 72 69 67 69 6e 20 6f 66 20 61 20 70 61  e origin of a pa
29870 72 74 69 63 75 6c 61 72 20 72 65 73 75 6c 74 20  rticular result 
29880 63 6f 6c 75 6d 6e 20 69 6e 0a 2a 2a 20 5b 53 45  column in.** [SE
29890 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e  LECT] statement.
298a0 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66  .** ^The name of
298b0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6f 72   the database or
298c0 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e   table or column
298d0 20 63 61 6e 20 62 65 20 72 65 74 75 72 6e 65 64   can be returned
298e0 20 61 73 0a 2a 2a 20 65 69 74 68 65 72 20 61 20   as.** either a 
298f0 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20  UTF-8 or UTF-16 
29900 73 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 5f 64  string.  ^The _d
29910 61 74 61 62 61 73 65 5f 20 72 6f 75 74 69 6e 65  atabase_ routine
29920 73 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20  s return.** the 
29930 64 61 74 61 62 61 73 65 20 6e 61 6d 65 2c 20 74  database name, t
29940 68 65 20 5f 74 61 62 6c 65 5f 20 72 6f 75 74 69  he _table_ routi
29950 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 74  nes return the t
29960 61 62 6c 65 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a  able name, and.*
29970 2a 20 74 68 65 20 6f 72 69 67 69 6e 5f 20 72 6f  * the origin_ ro
29980 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68  utines return th
29990 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a  e column name..*
299a0 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20  * ^The returned 
299b0 73 74 72 69 6e 67 20 69 73 20 76 61 6c 69 64 20  string is valid 
299c0 75 6e 74 69 6c 20 74 68 65 20 5b 70 72 65 70 61  until the [prepa
299d0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69  red statement] i
299e0 73 20 64 65 73 74 72 6f 79 65 64 0a 2a 2a 20 75  s destroyed.** u
299f0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69  sing [sqlite3_fi
29a00 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74  nalize()] or unt
29a10 69 6c 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  il the statement
29a20 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c   is automaticall
29a30 79 0a 2a 2a 20 72 65 70 72 65 70 61 72 65 64 20  y.** reprepared 
29a40 62 79 20 74 68 65 20 66 69 72 73 74 20 63 61 6c  by the first cal
29a50 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74  l to [sqlite3_st
29a60 65 70 28 29 5d 20 66 6f 72 20 61 20 70 61 72 74  ep()] for a part
29a70 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72  icular run.** or
29a80 20 75 6e 74 69 6c 20 74 68 65 20 73 61 6d 65 20   until the same 
29a90 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 72  information is r
29aa0 65 71 75 65 73 74 65 64 0a 2a 2a 20 61 67 61 69  equested.** agai
29ab0 6e 20 69 6e 20 61 20 64 69 66 66 65 72 65 6e 74  n in a different
29ac0 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a   encoding..**.**
29ad0 20 5e 54 68 65 20 6e 61 6d 65 73 20 72 65 74 75   ^The names retu
29ae0 72 6e 65 64 20 61 72 65 20 74 68 65 20 6f 72 69  rned are the ori
29af0 67 69 6e 61 6c 20 75 6e 2d 61 6c 69 61 73 65 64  ginal un-aliased
29b00 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 0a 2a 2a   names of the.**
29b10 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65   database, table
29b20 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a  , and column..**
29b30 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61  .** ^The first a
29b40 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 73 65  rgument to these
29b50 20 69 6e 74 65 72 66 61 63 65 73 20 69 73 20 61   interfaces is a
29b60 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
29b70 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 54 68 65 73 65  ment]..** ^These
29b80 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72   functions retur
29b90 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62  n information ab
29ba0 6f 75 74 20 74 68 65 20 4e 74 68 20 72 65 73 75  out the Nth resu
29bb0 6c 74 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e  lt column return
29bc0 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 73 74 61  ed by.** the sta
29bd0 74 65 6d 65 6e 74 2c 20 77 68 65 72 65 20 4e 20  tement, where N 
29be0 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 66 75  is the second fu
29bf0 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e  nction argument.
29c00 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74 2d 6d 6f  .** ^The left-mo
29c10 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 63 6f 6c  st column is col
29c20 75 6d 6e 20 30 20 66 6f 72 20 74 68 65 73 65 20  umn 0 for these 
29c30 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20  routines..**.** 
29c40 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75  ^If the Nth colu
29c50 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  mn returned by t
29c60 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
29c70 61 6e 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72  an expression or
29c80 0a 2a 2a 20 73 75 62 71 75 65 72 79 20 61 6e 64  .** subquery and
29c90 20 69 73 20 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e   is not a column
29ca0 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 61 6c 6c   value, then all
29cb0 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74 69   of these functi
29cc0 6f 6e 73 20 72 65 74 75 72 6e 0a 2a 2a 20 4e 55  ons return.** NU
29cd0 4c 4c 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74  LL.  ^These rout
29ce0 69 6e 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 72  ine might also r
29cf0 65 74 75 72 6e 20 4e 55 4c 4c 20 69 66 20 61 20  eturn NULL if a 
29d00 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
29d10 6e 20 65 72 72 6f 72 0a 2a 2a 20 6f 63 63 75 72  n error.** occur
29d20 73 2e 20 20 5e 4f 74 68 65 72 77 69 73 65 2c 20  s.  ^Otherwise, 
29d30 74 68 65 79 20 72 65 74 75 72 6e 20 74 68 65 20  they return the 
29d40 6e 61 6d 65 20 6f 66 20 74 68 65 20 61 74 74 61  name of the atta
29d50 63 68 65 64 20 64 61 74 61 62 61 73 65 2c 20 74  ched database, t
29d60 61 62 6c 65 2c 0a 2a 2a 20 6f 72 20 63 6f 6c 75  able,.** or colu
29d70 6d 6e 20 74 68 61 74 20 71 75 65 72 79 20 72 65  mn that query re
29d80 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 77 61 73 20  sult column was 
29d90 65 78 74 72 61 63 74 65 64 20 66 72 6f 6d 2e 0a  extracted from..
29da0 2a 2a 0a 2a 2a 20 5e 41 73 20 77 69 74 68 20 61  **.** ^As with a
29db0 6c 6c 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20  ll other SQLite 
29dc0 41 50 49 73 2c 20 74 68 6f 73 65 20 77 68 6f 73  APIs, those whos
29dd0 65 20 6e 61 6d 65 73 20 65 6e 64 20 77 69 74 68  e names end with
29de0 20 22 31 36 22 20 72 65 74 75 72 6e 0a 2a 2a 20   "16" return.** 
29df0 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 73  UTF-16 encoded s
29e00 74 72 69 6e 67 73 20 61 6e 64 20 74 68 65 20 6f  trings and the o
29e10 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 73 20 72  ther functions r
29e20 65 74 75 72 6e 20 55 54 46 2d 38 2e 0a 2a 2a 0a  eturn UTF-8..**.
29e30 2a 2a 20 5e 54 68 65 73 65 20 41 50 49 73 20 61  ** ^These APIs a
29e40 72 65 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c  re only availabl
29e50 65 20 69 66 20 74 68 65 20 6c 69 62 72 61 72 79  e if the library
29e60 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69   was compiled wi
29e70 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  th the.** [SQLIT
29e80 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f  E_ENABLE_COLUMN_
29e90 4d 45 54 41 44 41 54 41 5d 20 43 2d 70 72 65 70  METADATA] C-prep
29ea0 72 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c 2e  rocessor symbol.
29eb0 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72  .**.** If two or
29ec0 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63 61   more threads ca
29ed0 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f  ll one or more o
29ee0 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
29ef0 20 61 67 61 69 6e 73 74 20 74 68 65 20 73 61 6d   against the sam
29f00 65 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74  e.** prepared st
29f10 61 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f 6c 75  atement and colu
29f20 6d 6e 20 61 74 20 74 68 65 20 73 61 6d 65 20 74  mn at the same t
29f30 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65 73  ime then the res
29f40 75 6c 74 73 20 61 72 65 0a 2a 2a 20 75 6e 64 65  ults are.** unde
29f50 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  fined..**.** If 
29f60 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65  two or more thre
29f70 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20  ads call one or 
29f80 6d 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  more.** [sqlite3
29f90 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65  _column_database
29fa0 5f 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d  _name | column m
29fb0 65 74 61 64 61 74 61 20 69 6e 74 65 72 66 61 63  etadata interfac
29fc0 65 73 5d 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73  es].** for the s
29fd0 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  ame [prepared st
29fe0 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20 72 65 73  atement] and res
29ff0 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 74  ult column.** at
2a000 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74   the same time t
2a010 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20  hen the results 
2a020 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  are undefined..*
2a030 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  /.const char *sq
2a040 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74  lite3_column_dat
2a050 61 62 61 73 65 5f 6e 61 6d 65 28 73 71 6c 69 74  abase_name(sqlit
2a060 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63  e3_stmt*,int);.c
2a070 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
2a080 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61  e3_column_databa
2a090 73 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65  se_name16(sqlite
2a0a0 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f  3_stmt*,int);.co
2a0b0 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
2a0c0 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e  3_column_table_n
2a0d0 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
2a0e0 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f  *,int);.const vo
2a0f0 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
2a100 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36 28  mn_table_name16(
2a110 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
2a120 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  t);.const char *
2a130 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f  sqlite3_column_o
2a140 72 69 67 69 6e 5f 6e 61 6d 65 28 73 71 6c 69 74  rigin_name(sqlit
2a150 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63  e3_stmt*,int);.c
2a160 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
2a170 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e  e3_column_origin
2a180 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f  _name16(sqlite3_
2a190 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a  stmt*,int);../*.
2a1a0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 63  ** CAPI3REF: Dec
2a1b0 6c 61 72 65 64 20 44 61 74 61 74 79 70 65 20 4f  lared Datatype O
2a1c0 66 20 41 20 51 75 65 72 79 20 52 65 73 75 6c 74  f A Query Result
2a1d0 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69 72  .**.** ^(The fir
2a1e0 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  st parameter is 
2a1f0 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
2a200 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74 68  ement]..** If th
2a210 69 73 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  is statement is 
2a220 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65  a [SELECT] state
2a230 6d 65 6e 74 20 61 6e 64 20 74 68 65 20 4e 74 68  ment and the Nth
2a240 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 0a 2a   column of the.*
2a250 2a 20 72 65 74 75 72 6e 65 64 20 72 65 73 75 6c  * returned resul
2a260 74 20 73 65 74 20 6f 66 20 74 68 61 74 20 5b 53  t set of that [S
2a270 45 4c 45 43 54 5d 20 69 73 20 61 20 74 61 62 6c  ELECT] is a tabl
2a280 65 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20 61 6e  e column (not an
2a290 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f  .** expression o
2a2a0 72 20 73 75 62 71 75 65 72 79 29 20 74 68 65 6e  r subquery) then
2a2b0 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 74 79   the declared ty
2a2c0 70 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 0a  pe of the table.
2a2d0 2a 2a 20 63 6f 6c 75 6d 6e 20 69 73 20 72 65 74  ** column is ret
2a2e0 75 72 6e 65 64 2e 29 5e 20 20 5e 49 66 20 74 68  urned.)^  ^If th
2a2f0 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20  e Nth column of 
2a300 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 69  the result set i
2a310 73 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69  s an.** expressi
2a320 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79 2c 20  on or subquery, 
2a330 74 68 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  then a NULL poin
2a340 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ter is returned.
2a350 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65  .** ^The returne
2a360 64 20 73 74 72 69 6e 67 20 69 73 20 61 6c 77 61  d string is alwa
2a370 79 73 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64  ys UTF-8 encoded
2a380 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 20 65 78  ..**.** ^(For ex
2a390 61 6d 70 6c 65 2c 20 67 69 76 65 6e 20 74 68 65  ample, given the
2a3a0 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61   database schema
2a3b0 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54 45 20 54  :.**.** CREATE T
2a3c0 41 42 4c 45 20 74 31 28 63 31 20 56 41 52 49 41  ABLE t1(c1 VARIA
2a3d0 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64 20 74  NT);.**.** and t
2a3e0 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 61  he following sta
2a3f0 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d  tement to be com
2a400 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c  piled:.**.** SEL
2a410 45 43 54 20 63 31 20 2b 20 31 2c 20 63 31 20 46  ECT c1 + 1, c1 F
2a420 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 74 68  ROM t1;.**.** th
2a430 69 73 20 72 6f 75 74 69 6e 65 20 77 6f 75 6c 64  is routine would
2a440 20 72 65 74 75 72 6e 20 74 68 65 20 73 74 72 69   return the stri
2a450 6e 67 20 22 56 41 52 49 41 4e 54 22 20 66 6f 72  ng "VARIANT" for
2a460 20 74 68 65 20 73 65 63 6f 6e 64 20 72 65 73 75   the second resu
2a470 6c 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 28 69 3d  lt.** column (i=
2a480 3d 31 29 2c 20 61 6e 64 20 61 20 4e 55 4c 4c 20  =1), and a NULL 
2a490 70 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 65 20  pointer for the 
2a4a0 66 69 72 73 74 20 72 65 73 75 6c 74 20 63 6f 6c  first result col
2a4b0 75 6d 6e 20 28 69 3d 3d 30 29 2e 29 5e 0a 2a 2a  umn (i==0).)^.**
2a4c0 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73  .** ^SQLite uses
2a4d0 20 64 79 6e 61 6d 69 63 20 72 75 6e 2d 74 69 6d   dynamic run-tim
2a4e0 65 20 74 79 70 69 6e 67 2e 20 20 5e 53 6f 20 6a  e typing.  ^So j
2a4f0 75 73 74 20 62 65 63 61 75 73 65 20 61 20 63 6f  ust because a co
2a500 6c 75 6d 6e 0a 2a 2a 20 69 73 20 64 65 63 6c 61  lumn.** is decla
2a510 72 65 64 20 74 6f 20 63 6f 6e 74 61 69 6e 20 61  red to contain a
2a520 20 70 61 72 74 69 63 75 6c 61 72 20 74 79 70 65   particular type
2a530 20 64 6f 65 73 20 6e 6f 74 20 6d 65 61 6e 20 74   does not mean t
2a540 68 61 74 20 74 68 65 0a 2a 2a 20 64 61 74 61 20  hat the.** data 
2a550 73 74 6f 72 65 64 20 69 6e 20 74 68 61 74 20 63  stored in that c
2a560 6f 6c 75 6d 6e 20 69 73 20 6f 66 20 74 68 65 20  olumn is of the 
2a570 64 65 63 6c 61 72 65 64 20 74 79 70 65 2e 20 20  declared type.  
2a580 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 73 74 72  SQLite is.** str
2a590 6f 6e 67 6c 79 20 74 79 70 65 64 2c 20 62 75 74  ongly typed, but
2a5a0 20 74 68 65 20 74 79 70 69 6e 67 20 69 73 20 64   the typing is d
2a5b0 79 6e 61 6d 69 63 20 6e 6f 74 20 73 74 61 74 69  ynamic not stati
2a5c0 63 2e 20 20 5e 54 79 70 65 0a 2a 2a 20 69 73 20  c.  ^Type.** is 
2a5d0 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
2a5e0 69 6e 64 69 76 69 64 75 61 6c 20 76 61 6c 75 65  individual value
2a5f0 73 2c 20 6e 6f 74 20 77 69 74 68 20 74 68 65 20  s, not with the 
2a600 63 6f 6e 74 61 69 6e 65 72 73 0a 2a 2a 20 75 73  containers.** us
2a610 65 64 20 74 6f 20 68 6f 6c 64 20 74 68 6f 73 65  ed to hold those
2a620 20 76 61 6c 75 65 73 2e 0a 2a 2f 0a 63 6f 6e 73   values..*/.cons
2a630 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
2a640 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28  column_decltype(
2a650 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
2a660 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  t);.const void *
2a670 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
2a680 65 63 6c 74 79 70 65 31 36 28 73 71 6c 69 74 65  ecltype16(sqlite
2a690 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f  3_stmt*,int);../
2a6a0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45  *.** CAPI3REF: E
2a6b0 76 61 6c 75 61 74 65 20 41 6e 20 53 51 4c 20 53  valuate An SQL S
2a6c0 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 41  tatement.**.** A
2a6d0 66 74 65 72 20 61 20 5b 70 72 65 70 61 72 65 64  fter a [prepared
2a6e0 20 73 74 61 74 65 6d 65 6e 74 5d 20 68 61 73 20   statement] has 
2a6f0 62 65 65 6e 20 70 72 65 70 61 72 65 64 20 75 73  been prepared us
2a700 69 6e 67 20 65 69 74 68 65 72 0a 2a 2a 20 5b 73  ing either.** [s
2a710 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2a720 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  2()] or [sqlite3
2a730 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
2a740 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 20 6c   or one of the l
2a750 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61  egacy.** interfa
2a760 63 65 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  ces [sqlite3_pre
2a770 70 61 72 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69  pare()] or [sqli
2a780 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
2a790 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a  , this function.
2a7a0 2a 2a 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65  ** must be calle
2a7b0 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69  d one or more ti
2a7c0 6d 65 73 20 74 6f 20 65 76 61 6c 75 61 74 65 20  mes to evaluate 
2a7d0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a  the statement..*
2a7e0 2a 0a 2a 2a 20 54 68 65 20 64 65 74 61 69 6c 73  *.** The details
2a7f0 20 6f 66 20 74 68 65 20 62 65 68 61 76 69 6f 72   of the behavior
2a800 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f   of the sqlite3_
2a810 73 74 65 70 28 29 20 69 6e 74 65 72 66 61 63 65  step() interface
2a820 20 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68   depend.** on wh
2a830 65 74 68 65 72 20 74 68 65 20 73 74 61 74 65 6d  ether the statem
2a840 65 6e 74 20 77 61 73 20 70 72 65 70 61 72 65 64  ent was prepared
2a850 20 75 73 69 6e 67 20 74 68 65 20 6e 65 77 65 72   using the newer
2a860 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 0a   "v2" interface.
2a870 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
2a880 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73  are_v2()] and [s
2a890 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
2a8a0 5f 76 32 28 29 5d 20 6f 72 20 74 68 65 20 6f 6c  _v2()] or the ol
2a8b0 64 65 72 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e  der legacy.** in
2a8c0 74 65 72 66 61 63 65 20 5b 73 71 6c 69 74 65 33  terface [sqlite3
2a8d0 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20  _prepare()] and 
2a8e0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2a8f0 31 36 28 29 5d 2e 20 20 54 68 65 20 75 73 65 20  16()].  The use 
2a900 6f 66 20 74 68 65 0a 2a 2a 20 6e 65 77 20 22 76  of the.** new "v
2a910 32 22 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  2" interface is 
2a920 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20  recommended for 
2a930 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  new applications
2a940 20 62 75 74 20 74 68 65 20 6c 65 67 61 63 79 0a   but the legacy.
2a950 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c  ** interface wil
2a960 6c 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65  l continue to be
2a970 20 73 75 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a   supported..**.*
2a980 2a 20 5e 49 6e 20 74 68 65 20 6c 65 67 61 63 79  * ^In the legacy
2a990 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20   interface, the 
2a9a0 72 65 74 75 72 6e 20 76 61 6c 75 65 20 77 69 6c  return value wil
2a9b0 6c 20 62 65 20 65 69 74 68 65 72 20 5b 53 51 4c  l be either [SQL
2a9c0 49 54 45 5f 42 55 53 59 5d 2c 0a 2a 2a 20 5b 53  ITE_BUSY],.** [S
2a9d0 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51  QLITE_DONE], [SQ
2a9e0 4c 49 54 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49  LITE_ROW], [SQLI
2a9f0 54 45 5f 45 52 52 4f 52 5d 2c 20 6f 72 20 5b 53  TE_ERROR], or [S
2aa00 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a  QLITE_MISUSE]..*
2aa10 2a 20 5e 57 69 74 68 20 74 68 65 20 22 76 32 22  * ^With the "v2"
2aa20 20 69 6e 74 65 72 66 61 63 65 2c 20 61 6e 79 20   interface, any 
2aa30 6f 66 20 74 68 65 20 6f 74 68 65 72 20 5b 72 65  of the other [re
2aa40 73 75 6c 74 20 63 6f 64 65 73 5d 20 6f 72 0a 2a  sult codes] or.*
2aa50 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75  * [extended resu
2aa60 6c 74 20 63 6f 64 65 73 5d 20 6d 69 67 68 74 20  lt codes] might 
2aa70 62 65 20 72 65 74 75 72 6e 65 64 20 61 73 20 77  be returned as w
2aa80 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c  ell..**.** ^[SQL
2aa90 49 54 45 5f 42 55 53 59 5d 20 6d 65 61 6e 73 20  ITE_BUSY] means 
2aaa0 74 68 61 74 20 74 68 65 20 64 61 74 61 62 61 73  that the databas
2aab0 65 20 65 6e 67 69 6e 65 20 77 61 73 20 75 6e 61  e engine was una
2aac0 62 6c 65 20 74 6f 20 61 63 71 75 69 72 65 20 74  ble to acquire t
2aad0 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 6c  he.** database l
2aae0 6f 63 6b 73 20 69 74 20 6e 65 65 64 73 20 74 6f  ocks it needs to
2aaf0 20 64 6f 20 69 74 73 20 6a 6f 62 2e 20 20 5e 49   do its job.  ^I
2ab00 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  f the statement 
2ab10 69 73 20 61 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a  is a [COMMIT].**
2ab20 20 6f 72 20 6f 63 63 75 72 73 20 6f 75 74 73 69   or occurs outsi
2ab30 64 65 20 6f 66 20 61 6e 20 65 78 70 6c 69 63 69  de of an explici
2ab40 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74  t transaction, t
2ab50 68 65 6e 20 79 6f 75 20 63 61 6e 20 72 65 74 72  hen you can retr
2ab60 79 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65  y the.** stateme
2ab70 6e 74 2e 20 20 49 66 20 74 68 65 20 73 74 61 74  nt.  If the stat
2ab80 65 6d 65 6e 74 20 69 73 20 6e 6f 74 20 61 20 5b  ement is not a [
2ab90 43 4f 4d 4d 49 54 5d 20 61 6e 64 20 6f 63 63 75  COMMIT] and occu
2aba0 72 73 20 77 69 74 68 69 6e 20 61 6e 0a 2a 2a 20  rs within an.** 
2abb0 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63  explicit transac
2abc0 74 69 6f 6e 20 74 68 65 6e 20 79 6f 75 20 73 68  tion then you sh
2abd0 6f 75 6c 64 20 72 6f 6c 6c 62 61 63 6b 20 74 68  ould rollback th
2abe0 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 62 65  e transaction be
2abf0 66 6f 72 65 0a 2a 2a 20 63 6f 6e 74 69 6e 75 69  fore.** continui
2ac00 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49  ng..**.** ^[SQLI
2ac10 54 45 5f 44 4f 4e 45 5d 20 6d 65 61 6e 73 20 74  TE_DONE] means t
2ac20 68 61 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e  hat the statemen
2ac30 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 65  t has finished e
2ac40 78 65 63 75 74 69 6e 67 0a 2a 2a 20 73 75 63 63  xecuting.** succ
2ac50 65 73 73 66 75 6c 6c 79 2e 20 20 73 71 6c 69 74  essfully.  sqlit
2ac60 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64  e3_step() should
2ac70 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61   not be called a
2ac80 67 61 69 6e 20 6f 6e 20 74 68 69 73 20 76 69 72  gain on this vir
2ac90 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20  tual.** machine 
2aca0 77 69 74 68 6f 75 74 20 66 69 72 73 74 20 63 61  without first ca
2acb0 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72  lling [sqlite3_r
2acc0 65 73 65 74 28 29 5d 20 74 6f 20 72 65 73 65 74  eset()] to reset
2acd0 20 74 68 65 20 76 69 72 74 75 61 6c 0a 2a 2a 20   the virtual.** 
2ace0 6d 61 63 68 69 6e 65 20 62 61 63 6b 20 74 6f 20  machine back to 
2acf0 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74  its initial stat
2ad00 65 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  e..**.** ^If the
2ad10 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 62   SQL statement b
2ad20 65 69 6e 67 20 65 78 65 63 75 74 65 64 20 72 65  eing executed re
2ad30 74 75 72 6e 73 20 61 6e 79 20 64 61 74 61 2c 20  turns any data, 
2ad40 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57  then [SQLITE_ROW
2ad50 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64  ].** is returned
2ad60 20 65 61 63 68 20 74 69 6d 65 20 61 20 6e 65 77   each time a new
2ad70 20 72 6f 77 20 6f 66 20 64 61 74 61 20 69 73 20   row of data is 
2ad80 72 65 61 64 79 20 66 6f 72 20 70 72 6f 63 65 73  ready for proces
2ad90 73 69 6e 67 20 62 79 20 74 68 65 0a 2a 2a 20 63  sing by the.** c
2ada0 61 6c 6c 65 72 2e 20 54 68 65 20 76 61 6c 75 65  aller. The value
2adb0 73 20 6d 61 79 20 62 65 20 61 63 63 65 73 73 65  s may be accesse
2adc0 64 20 75 73 69 6e 67 20 74 68 65 20 5b 63 6f 6c  d using the [col
2add0 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74  umn access funct
2ade0 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65  ions]..** sqlite
2adf0 33 5f 73 74 65 70 28 29 20 69 73 20 63 61 6c 6c  3_step() is call
2ae00 65 64 20 61 67 61 69 6e 20 74 6f 20 72 65 74 72  ed again to retr
2ae10 69 65 76 65 20 74 68 65 20 6e 65 78 74 20 72 6f  ieve the next ro
2ae20 77 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a  w of data..**.**
2ae30 20 5e 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d   ^[SQLITE_ERROR]
2ae40 20 6d 65 61 6e 73 20 74 68 61 74 20 61 20 72 75   means that a ru
2ae50 6e 2d 74 69 6d 65 20 65 72 72 6f 72 20 28 73 75  n-time error (su
2ae60 63 68 20 61 73 20 61 20 63 6f 6e 73 74 72 61 69  ch as a constrai
2ae70 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74 69 6f 6e 29  nt.** violation)
2ae80 20 68 61 73 20 6f 63 63 75 72 72 65 64 2e 20 20   has occurred.  
2ae90 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73  sqlite3_step() s
2aea0 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c  hould not be cal
2aeb0 6c 65 64 20 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20  led again on.** 
2aec0 74 68 65 20 56 4d 2e 20 4d 6f 72 65 20 69 6e 66  the VM. More inf
2aed0 6f 72 6d 61 74 69 6f 6e 20 6d 61 79 20 62 65 20  ormation may be 
2aee0 66 6f 75 6e 64 20 62 79 20 63 61 6c 6c 69 6e 67  found by calling
2aef0 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
2af00 28 29 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68  ()]..** ^With th
2af10 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61  e legacy interfa
2af20 63 65 2c 20 61 20 6d 6f 72 65 20 73 70 65 63 69  ce, a more speci
2af30 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20 28  fic error code (
2af40 66 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20  for example,.** 
2af50 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50  [SQLITE_INTERRUP
2af60 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48 45  T], [SQLITE_SCHE
2af70 4d 41 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 52  MA], [SQLITE_COR
2af80 52 55 50 54 5d 2c 20 61 6e 64 20 73 6f 20 66 6f  RUPT], and so fo
2af90 72 74 68 29 0a 2a 2a 20 63 61 6e 20 62 65 20 6f  rth).** can be o
2afa0 62 74 61 69 6e 65 64 20 62 79 20 63 61 6c 6c 69  btained by calli
2afb0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ng [sqlite3_rese
2afc0 74 28 29 5d 20 6f 6e 20 74 68 65 0a 2a 2a 20 5b  t()] on the.** [
2afd0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2afe0 6e 74 5d 2e 20 20 5e 49 6e 20 74 68 65 20 22 76  nt].  ^In the "v
2aff0 32 22 20 69 6e 74 65 72 66 61 63 65 2c 0a 2a 2a  2" interface,.**
2b000 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66   the more specif
2b010 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73  ic error code is
2b020 20 72 65 74 75 72 6e 65 64 20 64 69 72 65 63 74   returned direct
2b030 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74  ly by sqlite3_st
2b040 65 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c  ep()..**.** [SQL
2b050 49 54 45 5f 4d 49 53 55 53 45 5d 20 6d 65 61 6e  ITE_MISUSE] mean
2b060 73 20 74 68 61 74 20 74 68 65 20 74 68 69 73 20  s that the this 
2b070 72 6f 75 74 69 6e 65 20 77 61 73 20 63 61 6c 6c  routine was call
2b080 65 64 20 69 6e 61 70 70 72 6f 70 72 69 61 74 65  ed inappropriate
2b090 6c 79 2e 0a 2a 2a 20 50 65 72 68 61 70 73 20 69  ly..** Perhaps i
2b0a0 74 20 77 61 73 20 63 61 6c 6c 65 64 20 6f 6e 20  t was called on 
2b0b0 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
2b0c0 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73 0a  ement] that has.
2b0d0 2a 2a 20 61 6c 72 65 61 64 79 20 62 65 65 6e 20  ** already been 
2b0e0 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
2b0f0 65 20 7c 20 66 69 6e 61 6c 69 7a 65 64 5d 20 6f  e | finalized] o
2b100 72 20 6f 6e 20 6f 6e 65 20 74 68 61 74 20 68 61  r on one that ha
2b110 64 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20  d.** previously 
2b120 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45  returned [SQLITE
2b130 5f 45 52 52 4f 52 5d 20 6f 72 20 5b 53 51 4c 49  _ERROR] or [SQLI
2b140 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f 72 20 69 74  TE_DONE].  Or it
2b150 20 63 6f 75 6c 64 0a 2a 2a 20 62 65 20 74 68 65   could.** be the
2b160 20 63 61 73 65 20 74 68 61 74 20 74 68 65 20 73   case that the s
2b170 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ame database con
2b180 6e 65 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67  nection is being
2b190 20 75 73 65 64 20 62 79 20 74 77 6f 20 6f 72 0a   used by two or.
2b1a0 2a 2a 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20  ** more threads 
2b1b0 61 74 20 74 68 65 20 73 61 6d 65 20 6d 6f 6d 65  at the same mome
2b1c0 6e 74 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a  nt in time..**.*
2b1d0 2a 20 46 6f 72 20 61 6c 6c 20 76 65 72 73 69 6f  * For all versio
2b1e0 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 75 70 20  ns of SQLite up 
2b1f0 74 6f 20 61 6e 64 20 69 6e 63 6c 75 64 69 6e 67  to and including
2b200 20 33 2e 36 2e 32 33 2e 31 2c 20 61 20 63 61 6c   3.6.23.1, a cal
2b210 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  l to.** [sqlite3
2b220 5f 72 65 73 65 74 28 29 5d 20 77 61 73 20 72 65  _reset()] was re
2b230 71 75 69 72 65 64 20 61 66 74 65 72 20 73 71 6c  quired after sql
2b240 69 74 65 33 5f 73 74 65 70 28 29 20 72 65 74 75  ite3_step() retu
2b250 72 6e 65 64 20 61 6e 79 74 68 69 6e 67 0a 2a 2a  rned anything.**
2b260 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
2b270 49 54 45 5f 52 4f 57 5d 20 62 65 66 6f 72 65 20  ITE_ROW] before 
2b280 61 6e 79 20 73 75 62 73 65 71 75 65 6e 74 20 69  any subsequent i
2b290 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20  nvocation of.** 
2b2a0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20  sqlite3_step(). 
2b2b0 20 46 61 69 6c 75 72 65 20 74 6f 20 72 65 73 65   Failure to rese
2b2c0 74 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73  t the prepared s
2b2d0 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 0a  tatement using .
2b2e0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ** [sqlite3_rese
2b2f0 74 28 29 5d 20 77 6f 75 6c 64 20 72 65 73 75 6c  t()] would resul
2b300 74 20 69 6e 20 61 6e 20 5b 53 51 4c 49 54 45 5f  t in an [SQLITE_
2b310 4d 49 53 55 53 45 5d 20 72 65 74 75 72 6e 20 66  MISUSE] return f
2b320 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73  rom.** sqlite3_s
2b330 74 65 70 28 29 2e 20 20 42 75 74 20 61 66 74 65  tep().  But afte
2b340 72 20 76 65 72 73 69 6f 6e 20 33 2e 36 2e 32 33  r version 3.6.23
2b350 2e 31 2c 20 73 71 6c 69 74 65 33 5f 73 74 65 70  .1, sqlite3_step
2b360 28 29 20 62 65 67 61 6e 0a 2a 2a 20 63 61 6c 6c  () began.** call
2b370 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ing [sqlite3_res
2b380 65 74 28 29 5d 20 61 75 74 6f 6d 61 74 69 63 61  et()] automatica
2b390 6c 6c 79 20 69 6e 20 74 68 69 73 20 63 69 72 63  lly in this circ
2b3a0 75 6d 73 74 61 6e 63 65 20 72 61 74 68 65 72 0a  umstance rather.
2b3b0 2a 2a 20 74 68 61 6e 20 72 65 74 75 72 6e 69 6e  ** than returnin
2b3c0 67 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  g [SQLITE_MISUSE
2b3d0 5d 2e 20 20 54 68 69 73 20 69 73 20 6e 6f 74 20  ].  This is not 
2b3e0 63 6f 6e 73 69 64 65 72 65 64 20 61 20 63 6f 6d  considered a com
2b3f0 70 61 74 69 62 69 6c 69 74 79 0a 2a 2a 20 62 72  patibility.** br
2b400 65 61 6b 20 62 65 63 61 75 73 65 20 61 6e 79 20  eak because any 
2b410 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 68 61 74  application that
2b420 20 65 76 65 72 20 72 65 63 65 69 76 65 73 20 61   ever receives a
2b430 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20  n SQLITE_MISUSE 
2b440 65 72 72 6f 72 0a 2a 2a 20 69 73 20 62 72 6f 6b  error.** is brok
2b450 65 6e 20 62 79 20 64 65 66 69 6e 69 74 69 6f 6e  en by definition
2b460 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f  .  The [SQLITE_O
2b470 4d 49 54 5f 41 55 54 4f 52 45 53 45 54 5d 20 63  MIT_AUTORESET] c
2b480 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
2b490 6f 6e 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 65  on.** can be use
2b4a0 64 20 74 6f 20 72 65 73 74 6f 72 65 20 74 68 65  d to restore the
2b4b0 20 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f 72   legacy behavior
2b4c0 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79  ..**.** <b>Goofy
2b4d0 20 49 6e 74 65 72 66 61 63 65 20 41 6c 65 72 74   Interface Alert
2b4e0 3a 3c 2f 62 3e 20 49 6e 20 74 68 65 20 6c 65 67  :</b> In the leg
2b4f0 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74  acy interface, t
2b500 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  he sqlite3_step(
2b510 29 0a 2a 2a 20 41 50 49 20 61 6c 77 61 79 73 20  ).** API always 
2b520 72 65 74 75 72 6e 73 20 61 20 67 65 6e 65 72 69  returns a generi
2b530 63 20 65 72 72 6f 72 20 63 6f 64 65 2c 20 5b 53  c error code, [S
2b540 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 66 6f  QLITE_ERROR], fo
2b550 6c 6c 6f 77 69 6e 67 20 61 6e 79 0a 2a 2a 20 65  llowing any.** e
2b560 72 72 6f 72 20 6f 74 68 65 72 20 74 68 61 6e 20  rror other than 
2b570 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 61 6e  [SQLITE_BUSY] an
2b580 64 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  d [SQLITE_MISUSE
2b590 5d 2e 20 20 59 6f 75 20 6d 75 73 74 20 63 61 6c  ].  You must cal
2b5a0 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65  l.** [sqlite3_re
2b5b0 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  set()] or [sqlit
2b5c0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69  e3_finalize()] i
2b5d0 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20  n order to find 
2b5e0 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73 70  one of the.** sp
2b5f0 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f  ecific [error co
2b600 64 65 73 5d 20 74 68 61 74 20 62 65 74 74 65 72  des] that better
2b610 20 64 65 73 63 72 69 62 65 73 20 74 68 65 20 65   describes the e
2b620 72 72 6f 72 2e 0a 2a 2a 20 57 65 20 61 64 6d 69  rror..** We admi
2b630 74 20 74 68 61 74 20 74 68 69 73 20 69 73 20 61  t that this is a
2b640 20 67 6f 6f 66 79 20 64 65 73 69 67 6e 2e 20 20   goofy design.  
2b650 54 68 65 20 70 72 6f 62 6c 65 6d 20 68 61 73 20  The problem has 
2b660 62 65 65 6e 20 66 69 78 65 64 0a 2a 2a 20 77 69  been fixed.** wi
2b670 74 68 20 74 68 65 20 22 76 32 22 20 69 6e 74 65  th the "v2" inte
2b680 72 66 61 63 65 2e 20 20 49 66 20 79 6f 75 20 70  rface.  If you p
2b690 72 65 70 61 72 65 20 61 6c 6c 20 6f 66 20 79 6f  repare all of yo
2b6a0 75 72 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ur SQL statement
2b6b0 73 0a 2a 2a 20 75 73 69 6e 67 20 65 69 74 68 65  s.** using eithe
2b6c0 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
2b6d0 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c  re_v2()] or [sql
2b6e0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
2b6f0 32 28 29 5d 20 69 6e 73 74 65 61 64 0a 2a 2a 20  2()] instead.** 
2b700 6f 66 20 74 68 65 20 6c 65 67 61 63 79 20 5b 73  of the legacy [s
2b710 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
2b720 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70  ] and [sqlite3_p
2b730 72 65 70 61 72 65 31 36 28 29 5d 20 69 6e 74 65  repare16()] inte
2b740 72 66 61 63 65 73 2c 0a 2a 2a 20 74 68 65 6e 20  rfaces,.** then 
2b750 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69  the more specifi
2b760 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20  c [error codes] 
2b770 61 72 65 20 72 65 74 75 72 6e 65 64 20 64 69 72  are returned dir
2b780 65 63 74 6c 79 0a 2a 2a 20 62 79 20 73 71 6c 69  ectly.** by sqli
2b790 74 65 33 5f 73 74 65 70 28 29 2e 20 20 54 68 65  te3_step().  The
2b7a0 20 75 73 65 20 6f 66 20 74 68 65 20 22 76 32 22   use of the "v2"
2b7b0 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 72 65   interface is re
2b7c0 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2f 0a 69 6e  commended..*/.in
2b7d0 74 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 73  t sqlite3_step(s
2b7e0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a  qlite3_stmt*);..
2b7f0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2b800 4e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  Number of column
2b810 73 20 69 6e 20 61 20 72 65 73 75 6c 74 20 73 65  s in a result se
2b820 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  t.**.** ^The sql
2b830 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
2b840 50 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  P) interface ret
2b850 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
2b860 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68  of columns in th
2b870 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 72 6f 77  e.** current row
2b880 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73   of the result s
2b890 65 74 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20  et of [prepared 
2b8a0 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a  statement] P..**
2b8b0 20 5e 49 66 20 70 72 65 70 61 72 65 64 20 73 74   ^If prepared st
2b8c0 61 74 65 6d 65 6e 74 20 50 20 64 6f 65 73 20 6e  atement P does n
2b8d0 6f 74 20 68 61 76 65 20 72 65 73 75 6c 74 73 20  ot have results 
2b8e0 72 65 61 64 79 20 74 6f 20 72 65 74 75 72 6e 0a  ready to return.
2b8f0 2a 2a 20 28 76 69 61 20 63 61 6c 6c 73 20 74 6f  ** (via calls to
2b900 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   the [sqlite3_co
2b910 6c 75 6d 6e 5f 69 6e 74 20 7c 20 73 71 6c 69 74  lumn_int | sqlit
2b920 65 33 5f 63 6f 6c 75 6d 6e 5f 2a 28 29 5d 20 6f  e3_column_*()] o
2b930 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 29  f.** interfaces)
2b940 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 64 61   then sqlite3_da
2b950 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 65 74 75  ta_count(P) retu
2b960 72 6e 73 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 73  rns 0..** ^The s
2b970 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e  qlite3_data_coun
2b980 74 28 50 29 20 72 6f 75 74 69 6e 65 20 61 6c 73  t(P) routine als
2b990 6f 20 72 65 74 75 72 6e 73 20 30 20 69 66 20 50  o returns 0 if P
2b9a0 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
2b9b0 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  er..** ^The sqli
2b9c0 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50  te3_data_count(P
2b9d0 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ) routine return
2b9e0 73 20 30 20 69 66 20 74 68 65 20 70 72 65 76 69  s 0 if the previ
2b9f0 6f 75 73 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b  ous call to.** [
2ba00 73 71 6c 69 74 65 33 5f 73 74 65 70 5d 28 50 29  sqlite3_step](P)
2ba10 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54   returned [SQLIT
2ba20 45 5f 44 4f 4e 45 5d 2e 20 20 5e 54 68 65 20 73  E_DONE].  ^The s
2ba30 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e  qlite3_data_coun
2ba40 74 28 50 29 0a 2a 2a 20 77 69 6c 6c 20 72 65 74  t(P).** will ret
2ba50 75 72 6e 20 6e 6f 6e 2d 7a 65 72 6f 20 69 66 20  urn non-zero if 
2ba60 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f  previous call to
2ba70 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 5d 28   [sqlite3_step](
2ba80 50 29 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b  P) returned.** [
2ba90 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 65 78 63  SQLITE_ROW], exc
2baa0 65 70 74 20 69 6e 20 74 68 65 20 63 61 73 65 20  ept in the case 
2bab0 6f 66 20 74 68 65 20 5b 50 52 41 47 4d 41 20 69  of the [PRAGMA i
2bac0 6e 63 72 65 6d 65 6e 74 61 6c 5f 76 61 63 75 75  ncremental_vacuu
2bad0 6d 5d 0a 2a 2a 20 77 68 65 72 65 20 69 74 20 61  m].** where it a
2bae0 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 7a 65  lways returns ze
2baf0 72 6f 20 73 69 6e 63 65 20 65 61 63 68 20 73 74  ro since each st
2bb00 65 70 20 6f 66 20 74 68 61 74 20 6d 75 6c 74 69  ep of that multi
2bb10 2d 73 74 65 70 0a 2a 2a 20 70 72 61 67 6d 61 20  -step.** pragma 
2bb20 72 65 74 75 72 6e 73 20 30 20 63 6f 6c 75 6d 6e  returns 0 column
2bb30 73 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a  s of data..**.**
2bb40 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
2bb50 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74  te3_column_count
2bb60 28 29 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ()].*/.int sqlit
2bb70 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 73 71  e3_data_count(sq
2bb80 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
2bb90 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
2bba0 52 45 46 3a 20 46 75 6e 64 61 6d 65 6e 74 61 6c  REF: Fundamental
2bbb0 20 44 61 74 61 74 79 70 65 73 0a 2a 2a 20 4b 45   Datatypes.** KE
2bbc0 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 54  YWORDS: SQLITE_T
2bbd0 45 58 54 0a 2a 2a 0a 2a 2a 20 5e 28 45 76 65 72  EXT.**.** ^(Ever
2bbe0 79 20 76 61 6c 75 65 20 69 6e 20 53 51 4c 69 74  y value in SQLit
2bbf0 65 20 68 61 73 20 6f 6e 65 20 6f 66 20 66 69 76  e has one of fiv
2bc00 65 20 66 75 6e 64 61 6d 65 6e 74 61 6c 20 64 61  e fundamental da
2bc10 74 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c  tatypes:.**.** <
2bc20 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62  ul>.** <li> 64-b
2bc30 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65  it signed intege
2bc40 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74  r.** <li> 64-bit
2bc50 20 49 45 45 45 20 66 6c 6f 61 74 69 6e 67 20 70   IEEE floating p
2bc60 6f 69 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c  oint number.** <
2bc70 6c 69 3e 20 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c  li> string.** <l
2bc80 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20  i> BLOB.** <li> 
2bc90 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a  NULL.** </ul>)^.
2bca0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
2bcb0 74 61 6e 74 73 20 61 72 65 20 63 6f 64 65 73 20  tants are codes 
2bcc0 66 6f 72 20 65 61 63 68 20 6f 66 20 74 68 6f 73  for each of thos
2bcd0 65 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e  e types..**.** N
2bce0 6f 74 65 20 74 68 61 74 20 74 68 65 20 53 51 4c  ote that the SQL
2bcf0 49 54 45 5f 54 45 58 54 20 63 6f 6e 73 74 61 6e  ITE_TEXT constan
2bd00 74 20 77 61 73 20 61 6c 73 6f 20 75 73 65 64 20  t was also used 
2bd10 69 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  in SQLite versio
2bd20 6e 20 32 0a 2a 2a 20 66 6f 72 20 61 20 63 6f 6d  n 2.** for a com
2bd30 70 6c 65 74 65 6c 79 20 64 69 66 66 65 72 65 6e  pletely differen
2bd40 74 20 6d 65 61 6e 69 6e 67 2e 20 20 53 6f 66 74  t meaning.  Soft
2bd50 77 61 72 65 20 74 68 61 74 20 6c 69 6e 6b 73 20  ware that links 
2bd60 61 67 61 69 6e 73 74 20 62 6f 74 68 0a 2a 2a 20  against both.** 
2bd70 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32  SQLite version 2
2bd80 20 61 6e 64 20 53 51 4c 69 74 65 20 76 65 72 73   and SQLite vers
2bd90 69 6f 6e 20 33 20 73 68 6f 75 6c 64 20 75 73 65  ion 3 should use
2bda0 20 53 51 4c 49 54 45 33 5f 54 45 58 54 2c 20 6e   SQLITE3_TEXT, n
2bdb0 6f 74 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 45 58  ot.** SQLITE_TEX
2bdc0 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  T..*/.#define SQ
2bdd0 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 20 31 0a  LITE_INTEGER  1.
2bde0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
2bdf0 4c 4f 41 54 20 20 20 20 32 0a 23 64 65 66 69 6e  LOAT    2.#defin
2be00 65 20 53 51 4c 49 54 45 5f 42 4c 4f 42 20 20 20  e SQLITE_BLOB   
2be10 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    4.#define SQLI
2be20 54 45 5f 4e 55 4c 4c 20 20 20 20 20 35 0a 23 69  TE_NULL     5.#i
2be30 66 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54  fdef SQLITE_TEXT
2be40 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f  .# undef SQLITE_
2be50 54 45 58 54 0a 23 65 6c 73 65 0a 23 20 64 65 66  TEXT.#else.# def
2be60 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20  ine SQLITE_TEXT 
2be70 20 20 20 20 33 0a 23 65 6e 64 69 66 0a 23 64 65      3.#endif.#de
2be80 66 69 6e 65 20 53 51 4c 49 54 45 33 5f 54 45 58  fine SQLITE3_TEX
2be90 54 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43  T     3../*.** C
2bea0 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20  API3REF: Result 
2beb0 56 61 6c 75 65 73 20 46 72 6f 6d 20 41 20 51 75  Values From A Qu
2bec0 65 72 79 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ery.** KEYWORDS:
2bed0 20 7b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20   {column access 
2bee0 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a  functions}.**.**
2bef0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
2bf00 66 6f 72 6d 20 74 68 65 20 22 72 65 73 75 6c 74  form the "result
2bf10 20 73 65 74 22 20 69 6e 74 65 72 66 61 63 65 2e   set" interface.
2bf20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
2bf30 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 69 6e  utines return in
2bf40 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20  formation about 
2bf50 61 20 73 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20  a single column 
2bf60 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a  of the current.*
2bf70 2a 20 72 65 73 75 6c 74 20 72 6f 77 20 6f 66 20  * result row of 
2bf80 61 20 71 75 65 72 79 2e 20 20 5e 49 6e 20 65 76  a query.  ^In ev
2bf90 65 72 79 20 63 61 73 65 20 74 68 65 20 66 69 72  ery case the fir
2bfa0 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  st argument is a
2bfb0 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74   pointer.** to t
2bfc0 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
2bfd0 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 73 20  tement] that is 
2bfe0 62 65 69 6e 67 20 65 76 61 6c 75 61 74 65 64 20  being evaluated 
2bff0 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74  (the [sqlite3_st
2c000 6d 74 2a 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73  mt*].** that was
2c010 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b   returned from [
2c020 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
2c030 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20  v2()] or one of 
2c040 69 74 73 20 76 61 72 69 61 6e 74 73 29 0a 2a 2a  its variants).**
2c050 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20   and the second 
2c060 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20  argument is the 
2c070 69 6e 64 65 78 20 6f 66 20 74 68 65 20 63 6f 6c  index of the col
2c080 75 6d 6e 20 66 6f 72 20 77 68 69 63 68 20 69 6e  umn for which in
2c090 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f  formation.** sho
2c0a0 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e  uld be returned.
2c0b0 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63   ^The leftmost c
2c0c0 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73  olumn of the res
2c0d0 75 6c 74 20 73 65 74 20 68 61 73 20 74 68 65 20  ult set has the 
2c0e0 69 6e 64 65 78 20 30 2e 0a 2a 2a 20 5e 54 68 65  index 0..** ^The
2c0f0 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
2c100 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74  ns in the result
2c110 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d 69 6e   can be determin
2c120 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c  ed using.** [sql
2c130 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e  ite3_column_coun
2c140 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  t()]..**.** If t
2c150 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
2c160 20 64 6f 65 73 20 6e 6f 74 20 63 75 72 72 65 6e   does not curren
2c170 74 6c 79 20 70 6f 69 6e 74 20 74 6f 20 61 20 76  tly point to a v
2c180 61 6c 69 64 20 72 6f 77 2c 20 6f 72 20 69 66 20  alid row, or if 
2c190 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e  the.** column in
2c1a0 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61  dex is out of ra
2c1b0 6e 67 65 2c 20 74 68 65 20 72 65 73 75 6c 74 20  nge, the result 
2c1c0 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
2c1d0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
2c1e0 6d 61 79 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c  may only be call
2c1f0 65 64 20 77 68 65 6e 20 74 68 65 20 6d 6f 73 74  ed when the most
2c200 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 0a   recent call to.
2c210 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ** [sqlite3_step
2c220 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64  ()] has returned
2c230 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 61 6e   [SQLITE_ROW] an
2c240 64 20 6e 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71  d neither.** [sq
2c250 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6e  lite3_reset()] n
2c260 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  or [sqlite3_fina
2c270 6c 69 7a 65 28 29 5d 20 68 61 76 65 20 62 65 65  lize()] have bee
2c280 6e 20 63 61 6c 6c 65 64 20 73 75 62 73 65 71 75  n called subsequ
2c290 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e 79  ently..** If any
2c2a0 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
2c2b0 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 61 66  es are called af
2c2c0 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ter [sqlite3_res
2c2d0 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c  et()] or.** [sql
2c2e0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
2c2f0 20 6f 72 20 61 66 74 65 72 20 5b 73 71 6c 69 74   or after [sqlit
2c300 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72  e3_step()] has r
2c310 65 74 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74  eturned.** somet
2c320 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20  hing other than 
2c330 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 68  [SQLITE_ROW], th
2c340 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e  e results are un
2c350 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b  defined..** If [
2c360 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
2c370 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  or [sqlite3_rese
2c380 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  t()] or [sqlite3
2c390 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20  _finalize()].** 
2c3a0 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20  are called from 
2c3b0 61 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65  a different thre
2c3c0 61 64 20 77 68 69 6c 65 20 61 6e 79 20 6f 66 20  ad while any of 
2c3d0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a  these routines.*
2c3e0 2a 20 61 72 65 20 70 65 6e 64 69 6e 67 2c 20 74  * are pending, t
2c3f0 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20  hen the results 
2c400 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  are undefined..*
2c410 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2c420 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20  3_column_type() 
2c430 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
2c440 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49  the.** [SQLITE_I
2c450 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74 79 70  NTEGER | datatyp
2c460 65 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20  e code] for the 
2c470 69 6e 69 74 69 61 6c 20 64 61 74 61 20 74 79 70  initial data typ
2c480 65 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65 73 75  e.** of the resu
2c490 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20 5e 54 68 65  lt column.  ^The
2c4a0 20 72 65 74 75 72 6e 65 64 20 76 61 6c 75 65 20   returned value 
2c4b0 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  is one of [SQLIT
2c4c0 45 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b  E_INTEGER],.** [
2c4d0 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b  SQLITE_FLOAT], [
2c4e0 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20 5b 53  SQLITE_TEXT], [S
2c4f0 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20  QLITE_BLOB], or 
2c500 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 20 20  [SQLITE_NULL].  
2c510 54 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74  The value.** ret
2c520 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
2c530 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69  _column_type() i
2c540 73 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67 66 75  s only meaningfu
2c550 6c 20 69 66 20 6e 6f 20 74 79 70 65 0a 2a 2a 20  l if no type.** 
2c560 63 6f 6e 76 65 72 73 69 6f 6e 73 20 68 61 76 65  conversions have
2c570 20 6f 63 63 75 72 72 65 64 20 61 73 20 64 65 73   occurred as des
2c580 63 72 69 62 65 64 20 62 65 6c 6f 77 2e 20 20 41  cribed below.  A
2c590 66 74 65 72 20 61 20 74 79 70 65 20 63 6f 6e 76  fter a type conv
2c5a0 65 72 73 69 6f 6e 2c 0a 2a 2a 20 74 68 65 20 76  ersion,.** the v
2c5b0 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79  alue returned by
2c5c0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2c5d0 74 79 70 65 28 29 20 69 73 20 75 6e 64 65 66 69  type() is undefi
2c5e0 6e 65 64 2e 20 20 46 75 74 75 72 65 0a 2a 2a 20  ned.  Future.** 
2c5f0 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
2c600 74 65 20 6d 61 79 20 63 68 61 6e 67 65 20 74 68  te may change th
2c610 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 73 71  e behavior of sq
2c620 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70  lite3_column_typ
2c630 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67  e().** following
2c640 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69   a type conversi
2c650 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  on..**.** ^If th
2c660 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c  e result is a BL
2c670 4f 42 20 6f 72 20 55 54 46 2d 38 20 73 74 72 69  OB or UTF-8 stri
2c680 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69  ng then the sqli
2c690 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2c6a0 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65  ().** routine re
2c6b0 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
2c6c0 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61   of bytes in tha
2c6d0 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67  t BLOB or string
2c6e0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73  ..** ^If the res
2c6f0 75 6c 74 20 69 73 20 61 20 55 54 46 2d 31 36 20  ult is a UTF-16 
2c700 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c  string, then sql
2c710 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2c720 73 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20  s() converts.** 
2c730 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54  the string to UT
2c740 46 2d 38 20 61 6e 64 20 74 68 65 6e 20 72 65 74  F-8 and then ret
2c750 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
2c760 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66  of bytes..** ^If
2c770 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61   the result is a
2c780 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74   numeric value t
2c790 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  hen sqlite3_colu
2c7a0 6d 6e 5f 62 79 74 65 73 28 29 20 75 73 65 73 0a  mn_bytes() uses.
2c7b0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72  ** [sqlite3_snpr
2c7c0 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65  intf()] to conve
2c7d0 72 74 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f  rt that value to
2c7e0 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20   a UTF-8 string 
2c7f0 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74  and returns.** t
2c800 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
2c810 65 73 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e  es in that strin
2c820 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  g..** ^If the re
2c830 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68  sult is NULL, th
2c840 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  en sqlite3_colum
2c850 6e 5f 62 79 74 65 73 28 29 20 72 65 74 75 72 6e  n_bytes() return
2c860 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 49  s zero..**.** ^I
2c870 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
2c880 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 31 36  a BLOB or UTF-16
2c890 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65   string then the
2c8a0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2c8b0 62 79 74 65 73 31 36 28 29 0a 2a 2a 20 72 6f 75  bytes16().** rou
2c8c0 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65  tine returns the
2c8d0 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
2c8e0 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72   in that BLOB or
2c8f0 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20   string..** ^If 
2c900 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20  the result is a 
2c910 55 54 46 2d 38 20 73 74 72 69 6e 67 2c 20 74 68  UTF-8 string, th
2c920 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  en sqlite3_colum
2c930 6e 5f 62 79 74 65 73 31 36 28 29 20 63 6f 6e 76  n_bytes16() conv
2c940 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69  erts.** the stri
2c950 6e 67 20 74 6f 20 55 54 46 2d 31 36 20 61 6e 64  ng to UTF-16 and
2c960 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68   then returns th
2c970 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
2c980 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  s..** ^If the re
2c990 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69  sult is a numeri
2c9a0 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c  c value then sql
2c9b0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2c9c0 73 31 36 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73  s16() uses.** [s
2c9d0 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
2c9e0 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68  )] to convert th
2c9f0 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55 54  at value to a UT
2ca00 46 2d 31 36 20 73 74 72 69 6e 67 20 61 6e 64 20  F-16 string and 
2ca10 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e  returns.** the n
2ca20 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
2ca30 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a  n that string..*
2ca40 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
2ca50 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73   is NULL, then s
2ca60 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2ca70 74 65 73 31 36 28 29 20 72 65 74 75 72 6e 73 20  tes16() returns 
2ca80 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  zero..**.** ^The
2ca90 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64   values returned
2caa0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c   by [sqlite3_col
2cab0 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e 64  umn_bytes()] and
2cac0 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f   .** [sqlite3_co
2cad0 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d 20  lumn_bytes16()] 
2cae0 64 6f 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 74  do not include t
2caf0 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  he zero terminat
2cb00 6f 72 73 20 61 74 20 74 68 65 20 65 6e 64 0a 2a  ors at the end.*
2cb10 2a 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67 2e  * of the string.
2cb20 20 20 5e 46 6f 72 20 63 6c 61 72 69 74 79 3a 20    ^For clarity: 
2cb30 74 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72  the values retur
2cb40 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74  ned by.** [sqlit
2cb50 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
2cb60 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
2cb70 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
2cb80 5d 20 61 72 65 20 74 68 65 20 6e 75 6d 62 65 72  ] are the number
2cb90 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e 20   of.** bytes in 
2cba0 74 68 65 20 73 74 72 69 6e 67 2c 20 6e 6f 74 20  the string, not 
2cbb0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68  the number of ch
2cbc0 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  aracters..**.** 
2cbd0 5e 53 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65  ^Strings returne
2cbe0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
2cbf0 75 6d 6e 5f 74 65 78 74 28 29 20 61 6e 64 20 73  umn_text() and s
2cc00 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2cc10 78 74 31 36 28 29 2c 0a 2a 2a 20 65 76 65 6e 20  xt16(),.** even 
2cc20 65 6d 70 74 79 20 73 74 72 69 6e 67 73 2c 20 61  empty strings, a
2cc30 72 65 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74  re always zero-t
2cc40 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 65  erminated.  ^The
2cc50 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65   return.** value
2cc60 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f   from sqlite3_co
2cc70 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 72 20  lumn_blob() for 
2cc80 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c  a zero-length BL
2cc90 4f 42 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  OB is a NULL poi
2cca0 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  nter..**.** ^The
2ccb0 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64   object returned
2ccc0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c   by [sqlite3_col
2ccd0 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20  umn_value()] is 
2cce0 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74  an.** [unprotect
2ccf0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
2cd00 5d 20 6f 62 6a 65 63 74 2e 20 20 41 6e 20 75 6e  ] object.  An un
2cd10 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
2cd20 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 0a 2a  3_value object.*
2cd30 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73  * may only be us
2cd40 65 64 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33  ed with [sqlite3
2cd50 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 20 61  _bind_value()] a
2cd60 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  nd [sqlite3_resu
2cd70 6c 74 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20  lt_value()]..** 
2cd80 49 66 20 74 68 65 20 5b 75 6e 70 72 6f 74 65 63  If the [unprotec
2cd90 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
2cda0 65 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e  e] object return
2cdb0 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65  ed by.** [sqlite
2cdc0 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29  3_column_value()
2cdd0 5d 20 69 73 20 75 73 65 64 20 69 6e 20 61 6e 79  ] is used in any
2cde0 20 6f 74 68 65 72 20 77 61 79 2c 20 69 6e 63 6c   other way, incl
2cdf0 75 64 69 6e 67 20 63 61 6c 6c 73 0a 2a 2a 20 74  uding calls.** t
2ce00 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20  o routines like 
2ce10 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69  [sqlite3_value_i
2ce20 6e 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  nt()], [sqlite3_
2ce30 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a  value_text()],.*
2ce40 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61  * or [sqlite3_va
2ce50 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 74 68  lue_bytes()], th
2ce60 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
2ce70 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
2ce80 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
2ce90 65 73 20 61 74 74 65 6d 70 74 20 74 6f 20 63 6f  es attempt to co
2cea0 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75 65 20  nvert the value 
2ceb0 77 68 65 72 65 20 61 70 70 72 6f 70 72 69 61 74  where appropriat
2cec0 65 2e 20 20 5e 46 6f 72 0a 2a 2a 20 65 78 61 6d  e.  ^For.** exam
2ced0 70 6c 65 2c 20 69 66 20 74 68 65 20 69 6e 74 65  ple, if the inte
2cee0 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74  rnal representat
2cef0 69 6f 6e 20 69 73 20 46 4c 4f 41 54 20 61 6e 64  ion is FLOAT and
2cf00 20 61 20 74 65 78 74 20 72 65 73 75 6c 74 0a 2a   a text result.*
2cf10 2a 20 69 73 20 72 65 71 75 65 73 74 65 64 2c 20  * is requested, 
2cf20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74  [sqlite3_snprint
2cf30 66 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e 74  f()] is used int
2cf40 65 72 6e 61 6c 6c 79 20 74 6f 20 70 65 72 66 6f  ernally to perfo
2cf50 72 6d 20 74 68 65 0a 2a 2a 20 63 6f 6e 76 65 72  rm the.** conver
2cf60 73 69 6f 6e 20 61 75 74 6f 6d 61 74 69 63 61 6c  sion automatical
2cf70 6c 79 2e 20 20 5e 28 54 68 65 20 66 6f 6c 6c 6f  ly.  ^(The follo
2cf80 77 69 6e 67 20 74 61 62 6c 65 20 64 65 74 61 69  wing table detai
2cf90 6c 73 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f  ls the conversio
2cfa0 6e 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 61  ns.** that are a
2cfb0 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62  pplied:.**.** <b
2cfc0 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74  lockquote>.** <t
2cfd0 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 3e  able border="1">
2cfe0 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 49 6e 74  .** <tr><th> Int
2cff0 65 72 6e 61 6c 3c 62 72 3e 54 79 70 65 20 3c 74  ernal<br>Type <t
2d000 68 3e 20 52 65 71 75 65 73 74 65 64 3c 62 72 3e  h> Requested<br>
2d010 54 79 70 65 20 3c 74 68 3e 20 20 43 6f 6e 76 65  Type <th>  Conve
2d020 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e  rsion.**.** <tr>
2d030 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74  <td>  NULL    <t
2d040 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64  d> INTEGER   <td
2d050 3e 20 52 65 73 75 6c 74 20 69 73 20 30 0a 2a 2a  > Result is 0.**
2d060 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20   <tr><td>  NULL 
2d070 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20     <td>  FLOAT  
2d080 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73    <td> Result is
2d090 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e   0.0.** <tr><td>
2d0a0 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20    NULL    <td>  
2d0b0 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 52 65   TEXT    <td> Re
2d0c0 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20 70 6f 69  sult is NULL poi
2d0d0 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  nter.** <tr><td>
2d0e0 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20    NULL    <td>  
2d0f0 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 52 65   BLOB    <td> Re
2d100 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20 70 6f 69  sult is NULL poi
2d110 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  nter.** <tr><td>
2d120 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20   INTEGER  <td>  
2d130 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f  FLOAT    <td> Co
2d140 6e 76 65 72 74 20 66 72 6f 6d 20 69 6e 74 65 67  nvert from integ
2d150 65 72 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c  er to float.** <
2d160 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20  tr><td> INTEGER 
2d170 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20   <td>   TEXT    
2d180 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65  <td> ASCII rende
2d190 72 69 6e 67 20 6f 66 20 74 68 65 20 69 6e 74 65  ring of the inte
2d1a0 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  ger.** <tr><td> 
2d1b0 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20  INTEGER  <td>   
2d1c0 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d  BLOB    <td> Sam
2d1d0 65 20 61 73 20 49 4e 54 45 47 45 52 2d 3e 54 45  e as INTEGER->TE
2d1e0 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  XT.** <tr><td>  
2d1f0 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 49 4e 54  FLOAT   <td> INT
2d200 45 47 45 52 20 20 20 3c 74 64 3e 20 43 6f 6e 76  EGER   <td> Conv
2d210 65 72 74 20 66 72 6f 6d 20 66 6c 6f 61 74 20 74  ert from float t
2d220 6f 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72  o integer.** <tr
2d230 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c  ><td>  FLOAT   <
2d240 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74  td>   TEXT    <t
2d250 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72 69  d> ASCII renderi
2d260 6e 67 20 6f 66 20 74 68 65 20 66 6c 6f 61 74 0a  ng of the float.
2d270 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f  ** <tr><td>  FLO
2d280 41 54 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42  AT   <td>   BLOB
2d290 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20 61 73      <td> Same as
2d2a0 20 46 4c 4f 41 54 2d 3e 54 45 58 54 0a 2a 2a 20   FLOAT->TEXT.** 
2d2b0 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20  <tr><td>  TEXT  
2d2c0 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20    <td> INTEGER  
2d2d0 20 3c 74 64 3e 20 55 73 65 20 61 74 6f 69 28 29   <td> Use atoi()
2d2e0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45  .** <tr><td>  TE
2d2f0 58 54 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41  XT    <td>  FLOA
2d300 54 20 20 20 20 3c 74 64 3e 20 55 73 65 20 61 74  T    <td> Use at
2d310 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  of().** <tr><td>
2d320 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20    TEXT    <td>  
2d330 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 4e 6f   BLOB    <td> No
2d340 20 63 68 61 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c   change.** <tr><
2d350 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  td>  BLOB    <td
2d360 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e  > INTEGER   <td>
2d370 20 43 6f 6e 76 65 72 74 20 74 6f 20 54 45 58 54   Convert to TEXT
2d380 20 74 68 65 6e 20 75 73 65 20 61 74 6f 69 28 29   then use atoi()
2d390 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c  .** <tr><td>  BL
2d3a0 4f 42 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41  OB    <td>  FLOA
2d3b0 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72  T    <td> Conver
2d3c0 74 20 74 6f 20 54 45 58 54 20 74 68 65 6e 20 75  t to TEXT then u
2d3d0 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72  se atof().** <tr
2d3e0 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c  ><td>  BLOB    <
2d3f0 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74  td>   TEXT    <t
2d400 64 3e 20 41 64 64 20 61 20 7a 65 72 6f 20 74 65  d> Add a zero te
2d410 72 6d 69 6e 61 74 6f 72 20 69 66 20 6e 65 65 64  rminator if need
2d420 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a  ed.** </table>.*
2d430 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29  * </blockquote>)
2d440 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c  ^.**.** The tabl
2d450 65 20 61 62 6f 76 65 20 6d 61 6b 65 73 20 72 65  e above makes re
2d460 66 65 72 65 6e 63 65 20 74 6f 20 73 74 61 6e 64  ference to stand
2d470 61 72 64 20 43 20 6c 69 62 72 61 72 79 20 66 75  ard C library fu
2d480 6e 63 74 69 6f 6e 73 20 61 74 6f 69 28 29 0a 2a  nctions atoi().*
2d490 2a 20 61 6e 64 20 61 74 6f 66 28 29 2e 20 20 53  * and atof().  S
2d4a0 51 4c 69 74 65 20 64 6f 65 73 20 6e 6f 74 20 72  QLite does not r
2d4b0 65 61 6c 6c 79 20 75 73 65 20 74 68 65 73 65 20  eally use these 
2d4c0 66 75 6e 63 74 69 6f 6e 73 2e 20 20 49 74 20 68  functions.  It h
2d4d0 61 73 20 69 74 73 0a 2a 2a 20 6f 77 6e 20 65 71  as its.** own eq
2d4e0 75 69 76 61 6c 65 6e 74 20 69 6e 74 65 72 6e 61  uivalent interna
2d4f0 6c 20 72 6f 75 74 69 6e 65 73 2e 20 20 54 68 65  l routines.  The
2d500 20 61 74 6f 69 28 29 20 61 6e 64 20 61 74 6f 66   atoi() and atof
2d510 28 29 20 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20  () names are.** 
2d520 75 73 65 64 20 69 6e 20 74 68 65 20 74 61 62 6c  used in the tabl
2d530 65 20 66 6f 72 20 62 72 65 76 69 74 79 20 61 6e  e for brevity an
2d540 64 20 62 65 63 61 75 73 65 20 74 68 65 79 20 61  d because they a
2d550 72 65 20 66 61 6d 69 6c 69 61 72 20 74 6f 20 6d  re familiar to m
2d560 6f 73 74 0a 2a 2a 20 43 20 70 72 6f 67 72 61 6d  ost.** C program
2d570 6d 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65  mers..**.** Note
2d580 20 74 68 61 74 20 77 68 65 6e 20 74 79 70 65 20   that when type 
2d590 63 6f 6e 76 65 72 73 69 6f 6e 73 20 6f 63 63 75  conversions occu
2d5a0 72 2c 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75  r, pointers retu
2d5b0 72 6e 65 64 20 62 79 20 70 72 69 6f 72 0a 2a 2a  rned by prior.**
2d5c0 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
2d5d0 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c  3_column_blob(),
2d5e0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2d5f0 74 65 78 74 28 29 2c 20 61 6e 64 2f 6f 72 0a 2a  text(), and/or.*
2d600 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  * sqlite3_column
2d610 5f 74 65 78 74 31 36 28 29 20 6d 61 79 20 62 65  _text16() may be
2d620 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a   invalidated..**
2d630 20 54 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e   Type conversion
2d640 73 20 61 6e 64 20 70 6f 69 6e 74 65 72 20 69 6e  s and pointer in
2d650 76 61 6c 69 64 61 74 69 6f 6e 73 20 6d 69 67 68  validations migh
2d660 74 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68  t occur.** in th
2d670 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 73 65  e following case
2d680 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
2d690 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61   <li> The initia
2d6a0 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 61 20 42  l content is a B
2d6b0 4c 4f 42 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  LOB and sqlite3_
2d6c0 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72  column_text() or
2d6d0 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33  .**      sqlite3
2d6e0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
2d6f0 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 41 20 7a   is called.  A z
2d700 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 20 6d  ero-terminator m
2d710 69 67 68 74 0a 2a 2a 20 20 20 20 20 20 6e 65 65  ight.**      nee
2d720 64 20 74 6f 20 62 65 20 61 64 64 65 64 20 74 6f  d to be added to
2d730 20 74 68 65 20 73 74 72 69 6e 67 2e 3c 2f 6c 69   the string.</li
2d740 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e  >.** <li> The in
2d750 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73  itial content is
2d760 20 55 54 46 2d 38 20 74 65 78 74 20 61 6e 64 20   UTF-8 text and 
2d770 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2d780 79 74 65 73 31 36 28 29 20 6f 72 0a 2a 2a 20 20  ytes16() or.**  
2d790 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75      sqlite3_colu
2d7a0 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20 63  mn_text16() is c
2d7b0 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74  alled.  The cont
2d7c0 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76  ent must be conv
2d7d0 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f  erted.**      to
2d7e0 20 55 54 46 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a   UTF-16.</li>.**
2d7f0 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61   <li> The initia
2d800 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46  l content is UTF
2d810 2d 31 36 20 74 65 78 74 20 61 6e 64 20 73 71 6c  -16 text and sql
2d820 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2d830 73 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73  s() or.**      s
2d840 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2d850 78 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20  xt() is called. 
2d860 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73   The content mus
2d870 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a  t be converted.*
2d880 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d 38 2e  *      to UTF-8.
2d890 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  </li>.** </ul>.*
2d8a0 2a 0a 2a 2a 20 5e 43 6f 6e 76 65 72 73 69 6f 6e  *.** ^Conversion
2d8b0 73 20 62 65 74 77 65 65 6e 20 55 54 46 2d 31 36  s between UTF-16
2d8c0 62 65 20 61 6e 64 20 55 54 46 2d 31 36 6c 65 20  be and UTF-16le 
2d8d0 61 72 65 20 61 6c 77 61 79 73 20 64 6f 6e 65 20  are always done 
2d8e0 69 6e 20 70 6c 61 63 65 20 61 6e 64 20 64 6f 0a  in place and do.
2d8f0 2a 2a 20 6e 6f 74 20 69 6e 76 61 6c 69 64 61 74  ** not invalidat
2d900 65 20 61 20 70 72 69 6f 72 20 70 6f 69 6e 74 65  e a prior pointe
2d910 72 2c 20 74 68 6f 75 67 68 20 6f 66 20 63 6f 75  r, though of cou
2d920 72 73 65 20 74 68 65 20 63 6f 6e 74 65 6e 74 20  rse the content 
2d930 6f 66 20 74 68 65 20 62 75 66 66 65 72 0a 2a 2a  of the buffer.**
2d940 20 74 68 61 74 20 74 68 65 20 70 72 69 6f 72 20   that the prior 
2d950 70 6f 69 6e 74 65 72 20 72 65 66 65 72 65 6e 63  pointer referenc
2d960 65 73 20 77 69 6c 6c 20 68 61 76 65 20 62 65 65  es will have bee
2d970 6e 20 6d 6f 64 69 66 69 65 64 2e 20 20 4f 74 68  n modified.  Oth
2d980 65 72 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20 63  er kinds.** of c
2d990 6f 6e 76 65 72 73 69 6f 6e 20 61 72 65 20 64 6f  onversion are do
2d9a0 6e 65 20 69 6e 20 70 6c 61 63 65 20 77 68 65 6e  ne in place when
2d9b0 20 69 74 20 69 73 20 70 6f 73 73 69 62 6c 65 2c   it is possible,
2d9c0 20 62 75 74 20 73 6f 6d 65 74 69 6d 65 73 20 74   but sometimes t
2d9d0 68 65 79 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 70  hey.** are not p
2d9e0 6f 73 73 69 62 6c 65 20 61 6e 64 20 69 6e 20 74  ossible and in t
2d9f0 68 6f 73 65 20 63 61 73 65 73 20 70 72 69 6f 72  hose cases prior
2da00 20 70 6f 69 6e 74 65 72 73 20 61 72 65 20 69 6e   pointers are in
2da10 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 0a 2a 2a  validated..**.**
2da20 20 54 68 65 20 73 61 66 65 73 74 20 61 6e 64 20   The safest and 
2da30 65 61 73 69 65 73 74 20 74 6f 20 72 65 6d 65 6d  easiest to remem
2da40 62 65 72 20 70 6f 6c 69 63 79 20 69 73 20 74 6f  ber policy is to
2da50 20 69 6e 76 6f 6b 65 20 74 68 65 73 65 20 72 6f   invoke these ro
2da60 75 74 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65  utines.** in one
2da70 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e   of the followin
2da80 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75  g ways:.**.** <u
2da90 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74  l>.**  <li>sqlit
2daa0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
2dab0 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c   followed by sql
2dac0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2dad0 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69  s()</li>.**  <li
2dae0 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  >sqlite3_column_
2daf0 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77 65 64 20  blob() followed 
2db00 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
2db10 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a  n_bytes()</li>.*
2db20 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63  *  <li>sqlite3_c
2db30 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66  olumn_text16() f
2db40 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74  ollowed by sqlit
2db50 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
2db60 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c  6()</li>.** </ul
2db70 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65 72  >.**.** In other
2db80 20 77 6f 72 64 73 2c 20 79 6f 75 20 73 68 6f 75   words, you shou
2db90 6c 64 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f  ld call sqlite3_
2dba0 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 0a 2a  column_text(),.*
2dbb0 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  * sqlite3_column
2dbc0 5f 62 6c 6f 62 28 29 2c 20 6f 72 20 73 71 6c 69  _blob(), or sqli
2dbd0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
2dbe0 36 28 29 20 66 69 72 73 74 20 74 6f 20 66 6f 72  6() first to for
2dbf0 63 65 20 74 68 65 20 72 65 73 75 6c 74 0a 2a 2a  ce the result.**
2dc00 20 69 6e 74 6f 20 74 68 65 20 64 65 73 69 72 65   into the desire
2dc10 64 20 66 6f 72 6d 61 74 2c 20 74 68 65 6e 20 69  d format, then i
2dc20 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 6f  nvoke sqlite3_co
2dc30 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a  lumn_bytes() or.
2dc40 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ** sqlite3_colum
2dc50 6e 5f 62 79 74 65 73 31 36 28 29 20 74 6f 20 66  n_bytes16() to f
2dc60 69 6e 64 20 74 68 65 20 73 69 7a 65 20 6f 66 20  ind the size of 
2dc70 74 68 65 20 72 65 73 75 6c 74 2e 20 20 44 6f 20  the result.  Do 
2dc80 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 0a 2a 2a  not mix calls.**
2dc90 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   to sqlite3_colu
2dca0 6d 6e 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c  mn_text() or sql
2dcb0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
2dcc0 28 29 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f  () with calls to
2dcd0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
2dce0 6d 6e 5f 62 79 74 65 73 31 36 28 29 2c 20 61 6e  mn_bytes16(), an
2dcf0 64 20 64 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c  d do not mix cal
2dd00 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ls to sqlite3_co
2dd10 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 0a 2a 2a  lumn_text16().**
2dd20 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 20 73   with calls to s
2dd30 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2dd40 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  tes()..**.** ^Th
2dd50 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72  e pointers retur
2dd60 6e 65 64 20 61 72 65 20 76 61 6c 69 64 20 75 6e  ned are valid un
2dd70 74 69 6c 20 61 20 74 79 70 65 20 63 6f 6e 76 65  til a type conve
2dd80 72 73 69 6f 6e 20 6f 63 63 75 72 73 20 61 73 0a  rsion occurs as.
2dd90 2a 2a 20 64 65 73 63 72 69 62 65 64 20 61 62 6f  ** described abo
2dda0 76 65 2c 20 6f 72 20 75 6e 74 69 6c 20 5b 73 71  ve, or until [sq
2ddb0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72  lite3_step()] or
2ddc0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2ddd0 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  )] or.** [sqlite
2dde0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73  3_finalize()] is
2ddf0 20 63 61 6c 6c 65 64 2e 20 20 5e 54 68 65 20 6d   called.  ^The m
2de00 65 6d 6f 72 79 20 73 70 61 63 65 20 75 73 65 64  emory space used
2de10 20 74 6f 20 68 6f 6c 64 20 73 74 72 69 6e 67 73   to hold strings
2de20 0a 2a 2a 20 61 6e 64 20 42 4c 4f 42 73 20 69 73  .** and BLOBs is
2de30 20 66 72 65 65 64 20 61 75 74 6f 6d 61 74 69 63   freed automatic
2de40 61 6c 6c 79 2e 20 20 44 6f 20 3c 62 3e 6e 6f 74  ally.  Do <b>not
2de50 3c 2f 62 3e 20 70 61 73 73 20 74 68 65 20 70 6f  </b> pass the po
2de60 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 0a  inters returned.
2de70 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
2de80 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c  mn_blob()], [sql
2de90 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2dea0 28 29 5d 2c 20 65 74 63 2e 20 69 6e 74 6f 0a 2a  ()], etc. into.*
2deb0 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  * [sqlite3_free(
2dec0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61  )]..**.** ^(If a
2ded0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
2dee0 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20  on error occurs 
2def0 64 75 72 69 6e 67 20 74 68 65 20 65 76 61 6c 75  during the evalu
2df00 61 74 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20  ation of any.** 
2df10 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
2df20 73 2c 20 61 20 64 65 66 61 75 6c 74 20 76 61 6c  s, a default val
2df30 75 65 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  ue is returned. 
2df40 20 54 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c   The default val
2df50 75 65 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20  ue.** is either 
2df60 74 68 65 20 69 6e 74 65 67 65 72 20 30 2c 20 74  the integer 0, t
2df70 68 65 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e  he floating poin
2df80 74 20 6e 75 6d 62 65 72 20 30 2e 30 2c 20 6f 72  t number 0.0, or
2df90 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74   a NULL.** point
2dfa0 65 72 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20  er.  Subsequent 
2dfb0 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
2dfc0 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 77 69 6c  3_errcode()] wil
2dfd0 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c  l return.** [SQL
2dfe0 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 29 5e 0a 2a 2f  ITE_NOMEM].)^.*/
2dff0 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
2e000 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
2e010 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2e020 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73  int iCol);.int s
2e030 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2e040 74 65 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  tes(sqlite3_stmt
2e050 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e  *, int iCol);.in
2e060 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  t sqlite3_column
2e070 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74 65 33  _bytes16(sqlite3
2e080 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
2e090 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74 65  );.double sqlite
2e0a0 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28  3_column_double(
2e0b0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2e0c0 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71  nt iCol);.int sq
2e0d0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74  lite3_column_int
2e0e0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2e0f0 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74  int iCol);.sqlit
2e100 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
2e110 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28 73 71  _column_int64(sq
2e120 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2e130 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 75 6e   iCol);.const un
2e140 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c  signed char *sql
2e150 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2e160 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2e170 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74  int iCol);.const
2e180 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
2e190 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 73 71 6c  olumn_text16(sql
2e1a0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
2e1b0 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74  iCol);.int sqlit
2e1c0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 73  e3_column_type(s
2e1d0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2e1e0 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33  t iCol);.sqlite3
2e1f0 5f 76 61 6c 75 65 20 2a 73 71 6c 69 74 65 33 5f  _value *sqlite3_
2e200 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 73 71 6c  column_value(sql
2e210 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
2e220 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  iCol);../*.** CA
2e230 50 49 33 52 45 46 3a 20 44 65 73 74 72 6f 79 20  PI3REF: Destroy 
2e240 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  A Prepared State
2e250 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a  ment Object.**.*
2e260 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66  * ^The sqlite3_f
2e270 69 6e 61 6c 69 7a 65 28 29 20 66 75 6e 63 74 69  inalize() functi
2e280 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20  on is called to 
2e290 64 65 6c 65 74 65 20 61 20 5b 70 72 65 70 61 72  delete a [prepar
2e2a0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a  ed statement]..*
2e2b0 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72  * ^If the most r
2e2c0 65 63 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e  ecent evaluation
2e2d0 20 6f 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e   of the statemen
2e2e0 74 20 65 6e 63 6f 75 6e 74 65 72 65 64 20 6e 6f  t encountered no
2e2f0 20 65 72 72 6f 72 73 0a 2a 2a 20 6f 72 20 69 66   errors.** or if
2e300 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
2e310 73 20 6e 65 76 65 72 20 62 65 65 6e 20 65 76 61  s never been eva
2e320 6c 75 61 74 65 64 2c 20 74 68 65 6e 20 73 71 6c  luated, then sql
2e330 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20  ite3_finalize() 
2e340 72 65 74 75 72 6e 73 0a 2a 2a 20 53 51 4c 49 54  returns.** SQLIT
2e350 45 5f 4f 4b 2e 20 20 5e 49 66 20 74 68 65 20 6d  E_OK.  ^If the m
2e360 6f 73 74 20 72 65 63 65 6e 74 20 65 76 61 6c 75  ost recent evalu
2e370 61 74 69 6f 6e 20 6f 66 20 73 74 61 74 65 6d 65  ation of stateme
2e380 6e 74 20 53 20 66 61 69 6c 65 64 2c 20 74 68 65  nt S failed, the
2e390 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 69 6e  n.** sqlite3_fin
2e3a0 61 6c 69 7a 65 28 53 29 20 72 65 74 75 72 6e 73  alize(S) returns
2e3b0 20 74 68 65 20 61 70 70 72 6f 70 72 69 61 74 65   the appropriate
2e3c0 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72   [error code] or
2e3d0 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 65 72  .** [extended er
2e3e0 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a  ror code]..**.**
2e3f0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66 69   ^The sqlite3_fi
2e400 6e 61 6c 69 7a 65 28 53 29 20 72 6f 75 74 69 6e  nalize(S) routin
2e410 65 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20  e can be called 
2e420 61 74 20 61 6e 79 20 70 6f 69 6e 74 20 64 75 72  at any point dur
2e430 69 6e 67 0a 2a 2a 20 74 68 65 20 6c 69 66 65 20  ing.** the life 
2e440 63 79 63 6c 65 20 6f 66 20 5b 70 72 65 70 61 72  cycle of [prepar
2e450 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 3a  ed statement] S:
2e460 0a 2a 2a 20 62 65 66 6f 72 65 20 73 74 61 74 65  .** before state
2e470 6d 65 6e 74 20 53 20 69 73 20 65 76 65 72 20 65  ment S is ever e
2e480 76 61 6c 75 61 74 65 64 2c 20 61 66 74 65 72 0a  valuated, after.
2e490 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 63  ** one or more c
2e4a0 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
2e4b0 5f 72 65 73 65 74 28 29 5d 2c 20 6f 72 20 61 66  _reset()], or af
2e4c0 74 65 72 20 61 6e 79 20 63 61 6c 6c 0a 2a 2a 20  ter any call.** 
2e4d0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
2e4e0 28 29 5d 20 72 65 67 61 72 64 6c 65 73 73 20 6f  ()] regardless o
2e4f0 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  f whether or not
2e500 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68   the statement h
2e510 61 73 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 64 20  as.** completed 
2e520 65 78 65 63 75 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  execution..**.**
2e530 20 5e 49 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74   ^Invoking sqlit
2e540 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 6f 6e  e3_finalize() on
2e550 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
2e560 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f  is a harmless no
2e570 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61  -op..**.** The a
2e580 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
2e590 66 69 6e 61 6c 69 7a 65 20 65 76 65 72 79 20 5b  finalize every [
2e5a0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2e5b0 6e 74 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  nt] in order to 
2e5c0 61 76 6f 69 64 0a 2a 2a 20 72 65 73 6f 75 72 63  avoid.** resourc
2e5d0 65 20 6c 65 61 6b 73 2e 20 20 49 74 20 69 73 20  e leaks.  It is 
2e5e0 61 20 67 72 69 65 76 6f 75 73 20 65 72 72 6f 72  a grievous error
2e5f0 20 66 6f 72 20 74 68 65 20 61 70 70 6c 69 63 61   for the applica
2e600 74 69 6f 6e 20 74 6f 20 74 72 79 20 74 6f 20 75  tion to try to u
2e610 73 65 0a 2a 2a 20 61 20 70 72 65 70 61 72 65 64  se.** a prepared
2e620 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72   statement after
2e630 20 69 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e   it has been fin
2e640 61 6c 69 7a 65 64 2e 20 20 41 6e 79 20 75 73 65  alized.  Any use
2e650 20 6f 66 20 61 20 70 72 65 70 61 72 65 64 0a 2a   of a prepared.*
2e660 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65  * statement afte
2e670 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 66 69  r it has been fi
2e680 6e 61 6c 69 7a 65 64 20 63 61 6e 20 72 65 73 75  nalized can resu
2e690 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20  lt in undefined 
2e6a0 61 6e 64 0a 2a 2a 20 75 6e 64 65 73 69 72 61 62  and.** undesirab
2e6b0 6c 65 20 62 65 68 61 76 69 6f 72 20 73 75 63 68  le behavior such
2e6c0 20 61 73 20 73 65 67 66 61 75 6c 74 73 20 61 6e   as segfaults an
2e6d0 64 20 68 65 61 70 20 63 6f 72 72 75 70 74 69 6f  d heap corruptio
2e6e0 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  n..*/.int sqlite
2e6f0 33 5f 66 69 6e 61 6c 69 7a 65 28 73 71 6c 69 74  3_finalize(sqlit
2e700 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
2e710 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2e720 3a 20 52 65 73 65 74 20 41 20 50 72 65 70 61 72  : Reset A Prepar
2e730 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a  ed Statement Obj
2e740 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ect.**.** The sq
2e750 6c 69 74 65 33 5f 72 65 73 65 74 28 29 20 66 75  lite3_reset() fu
2e760 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64  nction is called
2e770 20 74 6f 20 72 65 73 65 74 20 61 20 5b 70 72 65   to reset a [pre
2e780 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2e790 0a 2a 2a 20 6f 62 6a 65 63 74 20 62 61 63 6b 20  .** object back 
2e7a0 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73  to its initial s
2e7b0 74 61 74 65 2c 20 72 65 61 64 79 20 74 6f 20 62  tate, ready to b
2e7c0 65 20 72 65 2d 65 78 65 63 75 74 65 64 2e 0a 2a  e re-executed..*
2e7d0 2a 20 5e 41 6e 79 20 53 51 4c 20 73 74 61 74 65  * ^Any SQL state
2e7e0 6d 65 6e 74 20 76 61 72 69 61 62 6c 65 73 20 74  ment variables t
2e7f0 68 61 74 20 68 61 64 20 76 61 6c 75 65 73 20 62  hat had values b
2e800 6f 75 6e 64 20 74 6f 20 74 68 65 6d 20 75 73 69  ound to them usi
2e810 6e 67 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74  ng.** the [sqlit
2e820 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73  e3_bind_blob | s
2e830 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20  qlite3_bind_*() 
2e840 41 50 49 5d 20 72 65 74 61 69 6e 20 74 68 65 69  API] retain thei
2e850 72 20 76 61 6c 75 65 73 2e 0a 2a 2a 20 55 73 65  r values..** Use
2e860 20 5b 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f   [sqlite3_clear_
2e870 62 69 6e 64 69 6e 67 73 28 29 5d 20 74 6f 20 72  bindings()] to r
2e880 65 73 65 74 20 74 68 65 20 62 69 6e 64 69 6e 67  eset the binding
2e890 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73  s..**.** ^The [s
2e8a0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d  qlite3_reset(S)]
2e8b0 20 69 6e 74 65 72 66 61 63 65 20 72 65 73 65 74   interface reset
2e8c0 73 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  s the [prepared 
2e8d0 73 74 61 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a 20  statement] S.** 
2e8e0 62 61 63 6b 20 74 6f 20 74 68 65 20 62 65 67 69  back to the begi
2e8f0 6e 6e 69 6e 67 20 6f 66 20 69 74 73 20 70 72 6f  nning of its pro
2e900 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  gram..**.** ^If 
2e910 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
2e920 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
2e930 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68  _step(S)] for th
2e940 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  e.** [prepared s
2e950 74 61 74 65 6d 65 6e 74 5d 20 53 20 72 65 74 75  tatement] S retu
2e960 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57  rned [SQLITE_ROW
2e970 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e  ] or [SQLITE_DON
2e980 45 5d 2c 0a 2a 2a 20 6f 72 20 69 66 20 5b 73 71  E],.** or if [sq
2e990 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 68  lite3_step(S)] h
2e9a0 61 73 20 6e 65 76 65 72 20 62 65 66 6f 72 65 20  as never before 
2e9b0 62 65 65 6e 20 63 61 6c 6c 65 64 20 6f 6e 20 53  been called on S
2e9c0 2c 0a 2a 2a 20 74 68 65 6e 20 5b 73 71 6c 69 74  ,.** then [sqlit
2e9d0 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74  e3_reset(S)] ret
2e9e0 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  urns [SQLITE_OK]
2e9f0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
2ea00 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c  most recent call
2ea10 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   to [sqlite3_ste
2ea20 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a  p(S)] for the.**
2ea30 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2ea40 6d 65 6e 74 5d 20 53 20 69 6e 64 69 63 61 74 65  ment] S indicate
2ea50 64 20 61 6e 20 65 72 72 6f 72 2c 20 74 68 65 6e  d an error, then
2ea60 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  .** [sqlite3_res
2ea70 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20 61  et(S)] returns a
2ea80 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65  n appropriate [e
2ea90 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a  rror code]..**.*
2eaa0 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  * ^The [sqlite3_
2eab0 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66  reset(S)] interf
2eac0 61 63 65 20 64 6f 65 73 20 6e 6f 74 20 63 68 61  ace does not cha
2ead0 6e 67 65 20 74 68 65 20 76 61 6c 75 65 73 0a 2a  nge the values.*
2eae0 2a 20 6f 66 20 61 6e 79 20 5b 73 71 6c 69 74 65  * of any [sqlite
2eaf0 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 62 69 6e 64  3_bind_blob|bind
2eb00 69 6e 67 73 5d 20 6f 6e 20 74 68 65 20 5b 70 72  ings] on the [pr
2eb10 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2eb20 5d 20 53 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ] S..*/.int sqli
2eb30 74 65 33 5f 72 65 73 65 74 28 73 71 6c 69 74 65  te3_reset(sqlite
2eb40 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
2eb50 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2eb60 20 43 72 65 61 74 65 20 4f 72 20 52 65 64 65 66   Create Or Redef
2eb70 69 6e 65 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e  ine SQL Function
2eb80 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  s.** KEYWORDS: {
2eb90 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f  function creatio
2eba0 6e 20 72 6f 75 74 69 6e 65 73 7d 0a 2a 2a 20 4b  n routines}.** K
2ebb0 45 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63  EYWORDS: {applic
2ebc0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
2ebd0 4c 20 66 75 6e 63 74 69 6f 6e 7d 0a 2a 2a 20 4b  L function}.** K
2ebe0 45 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63  EYWORDS: {applic
2ebf0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
2ec00 4c 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a  L functions}.**.
2ec10 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69  ** ^These functi
2ec20 6f 6e 73 20 28 63 6f 6c 6c 65 63 74 69 76 65 6c  ons (collectivel
2ec30 79 20 6b 6e 6f 77 6e 20 61 73 20 22 66 75 6e 63  y known as "func
2ec40 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f  tion creation ro
2ec50 75 74 69 6e 65 73 22 29 0a 2a 2a 20 61 72 65 20  utines").** are 
2ec60 75 73 65 64 20 74 6f 20 61 64 64 20 53 51 4c 20  used to add SQL 
2ec70 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67  functions or agg
2ec80 72 65 67 61 74 65 73 20 6f 72 20 74 6f 20 72 65  regates or to re
2ec90 64 65 66 69 6e 65 20 74 68 65 20 62 65 68 61 76  define the behav
2eca0 69 6f 72 0a 2a 2a 20 6f 66 20 65 78 69 73 74 69  ior.** of existi
2ecb0 6e 67 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ng SQL functions
2ecc0 20 6f 72 20 61 67 67 72 65 67 61 74 65 73 2e 20   or aggregates. 
2ecd0 20 54 68 65 20 6f 6e 6c 79 20 64 69 66 66 65 72   The only differ
2ece0 65 6e 63 65 73 20 62 65 74 77 65 65 6e 0a 2a 2a  ences between.**
2ecf0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
2ed00 61 72 65 20 74 68 65 20 74 65 78 74 20 65 6e 63  are the text enc
2ed10 6f 64 69 6e 67 20 65 78 70 65 63 74 65 64 20 66  oding expected f
2ed20 6f 72 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64  or.** the second
2ed30 20 70 61 72 61 6d 65 74 65 72 20 28 74 68 65 20   parameter (the 
2ed40 6e 61 6d 65 20 6f 66 20 74 68 65 20 66 75 6e 63  name of the func
2ed50 74 69 6f 6e 20 62 65 69 6e 67 20 63 72 65 61 74  tion being creat
2ed60 65 64 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20 70  ed).** and the p
2ed70 72 65 73 65 6e 63 65 20 6f 72 20 61 62 73 65 6e  resence or absen
2ed80 63 65 20 6f 66 20 61 20 64 65 73 74 72 75 63 74  ce of a destruct
2ed90 6f 72 20 63 61 6c 6c 62 61 63 6b 20 66 6f 72 0a  or callback for.
2eda0 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ** the applicati
2edb0 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 2e  on data pointer.
2edc0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
2edd0 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  t parameter is t
2ede0 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
2edf0 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 77 68 69 63  nection] to whic
2ee00 68 20 74 68 65 20 53 51 4c 0a 2a 2a 20 66 75 6e  h the SQL.** fun
2ee10 63 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 20 61  ction is to be a
2ee20 64 64 65 64 2e 20 20 5e 49 66 20 61 6e 20 61 70  dded.  ^If an ap
2ee30 70 6c 69 63 61 74 69 6f 6e 20 75 73 65 73 20 6d  plication uses m
2ee40 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 64 61 74  ore than one dat
2ee50 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74  abase.** connect
2ee60 69 6f 6e 20 74 68 65 6e 20 61 70 70 6c 69 63 61  ion then applica
2ee70 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
2ee80 20 66 75 6e 63 74 69 6f 6e 73 20 6d 75 73 74 20   functions must 
2ee90 62 65 20 61 64 64 65 64 0a 2a 2a 20 74 6f 20 65  be added.** to e
2eea0 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ach database con
2eeb0 6e 65 63 74 69 6f 6e 20 73 65 70 61 72 61 74 65  nection separate
2eec0 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ly..**.** ^The s
2eed0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
2eee0 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  is the name of t
2eef0 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
2ef00 74 6f 20 62 65 20 63 72 65 61 74 65 64 20 6f 72  to be created or
2ef10 0a 2a 2a 20 72 65 64 65 66 69 6e 65 64 2e 20 20  .** redefined.  
2ef20 5e 54 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74  ^The length of t
2ef30 68 65 20 6e 61 6d 65 20 69 73 20 6c 69 6d 69 74  he name is limit
2ef40 65 64 20 74 6f 20 32 35 35 20 62 79 74 65 73 20  ed to 255 bytes 
2ef50 69 6e 20 61 20 55 54 46 2d 38 0a 2a 2a 20 72 65  in a UTF-8.** re
2ef60 70 72 65 73 65 6e 74 61 74 69 6f 6e 2c 20 65 78  presentation, ex
2ef70 63 6c 75 73 69 76 65 20 6f 66 20 74 68 65 20 7a  clusive of the z
2ef80 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 2e 20  ero-terminator. 
2ef90 20 5e 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20   ^Note that the 
2efa0 6e 61 6d 65 0a 2a 2a 20 6c 65 6e 67 74 68 20 6c  name.** length l
2efb0 69 6d 69 74 20 69 73 20 69 6e 20 55 54 46 2d 38  imit is in UTF-8
2efc0 20 62 79 74 65 73 2c 20 6e 6f 74 20 63 68 61 72   bytes, not char
2efd0 61 63 74 65 72 73 20 6e 6f 72 20 55 54 46 2d 31  acters nor UTF-1
2efe0 36 20 62 79 74 65 73 2e 20 20 0a 2a 2a 20 5e 41  6 bytes.  .** ^A
2eff0 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 63 72  ny attempt to cr
2f000 65 61 74 65 20 61 20 66 75 6e 63 74 69 6f 6e 20  eate a function 
2f010 77 69 74 68 20 61 20 6c 6f 6e 67 65 72 20 6e 61  with a longer na
2f020 6d 65 0a 2a 2a 20 77 69 6c 6c 20 72 65 73 75 6c  me.** will resul
2f030 74 20 69 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53  t in [SQLITE_MIS
2f040 55 53 45 5d 20 62 65 69 6e 67 20 72 65 74 75 72  USE] being retur
2f050 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ned..**.** ^The 
2f060 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
2f070 28 6e 41 72 67 29 0a 2a 2a 20 69 73 20 74 68 65  (nArg).** is the
2f080 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d   number of argum
2f090 65 6e 74 73 20 74 68 61 74 20 74 68 65 20 53 51  ents that the SQ
2f0a0 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a  L function or.**
2f0b0 20 61 67 67 72 65 67 61 74 65 20 74 61 6b 65 73   aggregate takes
2f0c0 2e 20 5e 49 66 20 74 68 69 73 20 70 61 72 61 6d  . ^If this param
2f0d0 65 74 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e  eter is -1, then
2f0e0 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
2f0f0 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74  n or.** aggregat
2f100 65 20 6d 61 79 20 74 61 6b 65 20 61 6e 79 20 6e  e may take any n
2f110 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e  umber of argumen
2f120 74 73 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64  ts between 0 and
2f130 20 74 68 65 20 6c 69 6d 69 74 0a 2a 2a 20 73 65   the limit.** se
2f140 74 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 69  t by [sqlite3_li
2f150 6d 69 74 5d 28 5b 53 51 4c 49 54 45 5f 4c 49 4d  mit]([SQLITE_LIM
2f160 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d  IT_FUNCTION_ARG]
2f170 29 2e 20 20 49 66 20 74 68 65 20 74 68 69 72 64  ).  If the third
2f180 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 69 73  .** parameter is
2f190 20 6c 65 73 73 20 74 68 61 6e 20 2d 31 20 6f 72   less than -1 or
2f1a0 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 31 32   greater than 12
2f1b0 37 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  7 then the behav
2f1c0 69 6f 72 20 69 73 0a 2a 2a 20 75 6e 64 65 66 69  ior is.** undefi
2f1d0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ned..**.** ^The 
2f1e0 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
2f1f0 2c 20 65 54 65 78 74 52 65 70 2c 20 73 70 65 63  , eTextRep, spec
2f200 69 66 69 65 73 20 77 68 61 74 0a 2a 2a 20 5b 53  ifies what.** [S
2f210 51 4c 49 54 45 5f 55 54 46 38 20 7c 20 74 65 78  QLITE_UTF8 | tex
2f220 74 20 65 6e 63 6f 64 69 6e 67 5d 20 74 68 69 73  t encoding] this
2f230 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 70 72   SQL function pr
2f240 65 66 65 72 73 20 66 6f 72 0a 2a 2a 20 69 74 73  efers for.** its
2f250 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 45 76   parameters.  Ev
2f260 65 72 79 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ery SQL function
2f270 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
2f280 6d 75 73 74 20 62 65 20 61 62 6c 65 20 74 6f 20  must be able to 
2f290 77 6f 72 6b 0a 2a 2a 20 77 69 74 68 20 55 54 46  work.** with UTF
2f2a0 2d 38 2c 20 55 54 46 2d 31 36 6c 65 2c 20 6f 72  -8, UTF-16le, or
2f2b0 20 55 54 46 2d 31 36 62 65 2e 20 20 42 75 74 20   UTF-16be.  But 
2f2c0 73 6f 6d 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  some implementat
2f2d0 69 6f 6e 73 20 6d 61 79 20 62 65 0a 2a 2a 20 6d  ions may be.** m
2f2e0 6f 72 65 20 65 66 66 69 63 69 65 6e 74 20 77 69  ore efficient wi
2f2f0 74 68 20 6f 6e 65 20 65 6e 63 6f 64 69 6e 67 20  th one encoding 
2f300 74 68 61 6e 20 61 6e 6f 74 68 65 72 2e 20 20 5e  than another.  ^
2f310 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  An application m
2f320 61 79 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c  ay.** invoke sql
2f330 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2f340 74 69 6f 6e 28 29 20 6f 72 20 73 71 6c 69 74 65  tion() or sqlite
2f350 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
2f360 6e 31 36 28 29 20 6d 75 6c 74 69 70 6c 65 0a 2a  n16() multiple.*
2f370 2a 20 74 69 6d 65 73 20 77 69 74 68 20 74 68 65  * times with the
2f380 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 62   same function b
2f390 75 74 20 77 69 74 68 20 64 69 66 66 65 72 65 6e  ut with differen
2f3a0 74 20 76 61 6c 75 65 73 20 6f 66 20 65 54 65 78  t values of eTex
2f3b0 74 52 65 70 2e 0a 2a 2a 20 5e 57 68 65 6e 20 6d  tRep..** ^When m
2f3c0 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e  ultiple implemen
2f3d0 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73  tations of the s
2f3e0 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 61 72 65  ame function are
2f3f0 20 61 76 61 69 6c 61 62 6c 65 2c 20 53 51 4c 69   available, SQLi
2f400 74 65 0a 2a 2a 20 77 69 6c 6c 20 70 69 63 6b 20  te.** will pick 
2f410 74 68 65 20 6f 6e 65 20 74 68 61 74 20 69 6e 76  the one that inv
2f420 6f 6c 76 65 73 20 74 68 65 20 6c 65 61 73 74 20  olves the least 
2f430 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74 61 20 63  amount of data c
2f440 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 20 49 66  onversion..** If
2f450 20 74 68 65 72 65 20 69 73 20 6f 6e 6c 79 20 61   there is only a
2f460 20 73 69 6e 67 6c 65 20 69 6d 70 6c 65 6d 65 6e   single implemen
2f470 74 61 74 69 6f 6e 20 77 68 69 63 68 20 64 6f 65  tation which doe
2f480 73 20 6e 6f 74 20 63 61 72 65 20 77 68 61 74 20  s not care what 
2f490 74 65 78 74 0a 2a 2a 20 65 6e 63 6f 64 69 6e 67  text.** encoding
2f4a0 20 69 73 20 75 73 65 64 2c 20 74 68 65 6e 20 74   is used, then t
2f4b0 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65  he fourth argume
2f4c0 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 5b 53 51  nt should be [SQ
2f4d0 4c 49 54 45 5f 41 4e 59 5d 2e 0a 2a 2a 0a 2a 2a  LITE_ANY]..**.**
2f4e0 20 5e 28 54 68 65 20 66 69 66 74 68 20 70 61 72   ^(The fifth par
2f4f0 61 6d 65 74 65 72 20 69 73 20 61 6e 20 61 72 62  ameter is an arb
2f500 69 74 72 61 72 79 20 70 6f 69 6e 74 65 72 2e 20  itrary pointer. 
2f510 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   The implementat
2f520 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 66 75  ion of the.** fu
2f530 6e 63 74 69 6f 6e 20 63 61 6e 20 67 61 69 6e 20  nction can gain 
2f540 61 63 63 65 73 73 20 74 6f 20 74 68 69 73 20 70  access to this p
2f550 6f 69 6e 74 65 72 20 75 73 69 6e 67 20 5b 73 71  ointer using [sq
2f560 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28  lite3_user_data(
2f570 29 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  )].)^.**.** ^The
2f580 20 73 69 78 74 68 2c 20 73 65 76 65 6e 74 68 20   sixth, seventh 
2f590 61 6e 64 20 65 69 67 68 74 68 20 70 61 72 61 6d  and eighth param
2f5a0 65 74 65 72 73 2c 20 78 46 75 6e 63 2c 20 78 53  eters, xFunc, xS
2f5b0 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 2c 20  tep and xFinal, 
2f5c0 61 72 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20  are.** pointers 
2f5d0 74 6f 20 43 2d 6c 61 6e 67 75 61 67 65 20 66 75  to C-language fu
2f5e0 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 69 6d 70  nctions that imp
2f5f0 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66  lement the SQL f
2f600 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67  unction or.** ag
2f610 67 72 65 67 61 74 65 2e 20 5e 41 20 73 63 61 6c  gregate. ^A scal
2f620 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  ar SQL function 
2f630 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c  requires an impl
2f640 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68  ementation of th
2f650 65 20 78 46 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62  e xFunc.** callb
2f660 61 63 6b 20 6f 6e 6c 79 3b 20 4e 55 4c 4c 20 70  ack only; NULL p
2f670 6f 69 6e 74 65 72 73 20 6d 75 73 74 20 62 65 20  ointers must be 
2f680 70 61 73 73 65 64 20 61 73 20 74 68 65 20 78 53  passed as the xS
2f690 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 0a 2a  tep and xFinal.*
2f6a0 2a 20 70 61 72 61 6d 65 74 65 72 73 2e 20 5e 41  * parameters. ^A
2f6b0 6e 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20  n aggregate SQL 
2f6c0 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65  function require
2f6d0 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  s an implementat
2f6e0 69 6f 6e 20 6f 66 20 78 53 74 65 70 0a 2a 2a 20  ion of xStep.** 
2f6f0 61 6e 64 20 78 46 69 6e 61 6c 20 61 6e 64 20 4e  and xFinal and N
2f700 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6d 75 73 74  ULL pointer must
2f710 20 62 65 20 70 61 73 73 65 64 20 66 6f 72 20 78   be passed for x
2f720 46 75 6e 63 2e 20 5e 54 6f 20 64 65 6c 65 74 65  Func. ^To delete
2f730 20 61 6e 20 65 78 69 73 74 69 6e 67 0a 2a 2a 20   an existing.** 
2f740 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20  SQL function or 
2f750 61 67 67 72 65 67 61 74 65 2c 20 70 61 73 73 20  aggregate, pass 
2f760 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 66 6f  NULL pointers fo
2f770 72 20 61 6c 6c 20 74 68 72 65 65 20 66 75 6e 63  r all three func
2f780 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b  tion.** callback
2f790 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74 68  s..**.** ^(If th
2f7a0 65 20 6e 69 6e 74 68 20 70 61 72 61 6d 65 74 65  e ninth paramete
2f7b0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 65  r to sqlite3_cre
2f7c0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28  ate_function_v2(
2f7d0 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a  ) is not NULL,.*
2f7e0 2a 20 74 68 65 6e 20 69 74 20 69 73 20 64 65 73  * then it is des
2f7f0 74 72 75 63 74 6f 72 20 66 6f 72 20 74 68 65 20  tructor for the 
2f800 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61  application data
2f810 20 70 6f 69 6e 74 65 72 2e 20 0a 2a 2a 20 54 68   pointer. .** Th
2f820 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20  e destructor is 
2f830 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 74 68 65  invoked when the
2f840 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 64 65 6c   function is del
2f850 65 74 65 64 2c 20 65 69 74 68 65 72 20 62 79 20  eted, either by 
2f860 62 65 69 6e 67 0a 2a 2a 20 6f 76 65 72 6c 6f 61  being.** overloa
2f870 64 65 64 20 6f 72 20 77 68 65 6e 20 74 68 65 20  ded or when the 
2f880 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2f890 69 6f 6e 20 63 6c 6f 73 65 73 2e 29 5e 0a 2a 2a  ion closes.)^.**
2f8a0 20 5e 54 68 65 20 64 65 73 74 72 75 63 74 6f 72   ^The destructor
2f8b0 20 69 73 20 61 6c 73 6f 20 69 6e 76 6f 6b 65 64   is also invoked
2f8c0 20 69 66 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a   if the call to.
2f8d0 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  ** sqlite3_creat
2f8e0 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20  e_function_v2() 
2f8f0 66 61 69 6c 73 2e 0a 2a 2a 20 5e 57 68 65 6e 20  fails..** ^When 
2f900 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 63  the destructor c
2f910 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 74  allback of the t
2f920 65 6e 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  enth parameter i
2f930 73 20 69 6e 76 6f 6b 65 64 2c 20 69 74 0a 2a 2a  s invoked, it.**
2f940 20 69 73 20 70 61 73 73 65 64 20 61 20 73 69 6e   is passed a sin
2f950 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69  gle argument whi
2f960 63 68 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20  ch is a copy of 
2f970 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
2f980 64 61 74 61 20 0a 2a 2a 20 70 6f 69 6e 74 65 72  data .** pointer
2f990 20 77 68 69 63 68 20 77 61 73 20 74 68 65 20 66   which was the f
2f9a0 69 66 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  ifth parameter t
2f9b0 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  o sqlite3_create
2f9c0 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 2e 0a  _function_v2()..
2f9d0 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 70 65 72  **.** ^It is per
2f9e0 6d 69 74 74 65 64 20 74 6f 20 72 65 67 69 73 74  mitted to regist
2f9f0 65 72 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c  er multiple impl
2fa00 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74  ementations of t
2fa10 68 65 20 73 61 6d 65 0a 2a 2a 20 66 75 6e 63 74  he same.** funct
2fa20 69 6f 6e 73 20 77 69 74 68 20 74 68 65 20 73 61  ions with the sa
2fa30 6d 65 20 6e 61 6d 65 20 62 75 74 20 77 69 74 68  me name but with
2fa40 20 65 69 74 68 65 72 20 64 69 66 66 65 72 69 6e   either differin
2fa50 67 20 6e 75 6d 62 65 72 73 20 6f 66 0a 2a 2a 20  g numbers of.** 
2fa60 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 64 69 66  arguments or dif
2fa70 66 65 72 69 6e 67 20 70 72 65 66 65 72 72 65 64  fering preferred
2fa80 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 2e   text encodings.
2fa90 20 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75    ^SQLite will u
2faa0 73 65 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d  se.** the implem
2fab0 65 6e 74 61 74 69 6f 6e 20 74 68 61 74 20 6d 6f  entation that mo
2fac0 73 74 20 63 6c 6f 73 65 6c 79 20 6d 61 74 63 68  st closely match
2fad0 65 73 20 74 68 65 20 77 61 79 20 69 6e 20 77 68  es the way in wh
2fae0 69 63 68 20 74 68 65 0a 2a 2a 20 53 51 4c 20 66  ich the.** SQL f
2faf0 75 6e 63 74 69 6f 6e 20 69 73 20 75 73 65 64 2e  unction is used.
2fb00 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 69 6d    ^A function im
2fb10 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74  plementation wit
2fb20 68 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65  h a non-negative
2fb30 0a 2a 2a 20 6e 41 72 67 20 70 61 72 61 6d 65 74  .** nArg paramet
2fb40 65 72 20 69 73 20 61 20 62 65 74 74 65 72 20 6d  er is a better m
2fb50 61 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63  atch than a func
2fb60 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  tion implementat
2fb70 69 6f 6e 20 77 69 74 68 0a 2a 2a 20 61 20 6e 65  ion with.** a ne
2fb80 67 61 74 69 76 65 20 6e 41 72 67 2e 20 20 5e 41  gative nArg.  ^A
2fb90 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20   function where 
2fba0 74 68 65 20 70 72 65 66 65 72 72 65 64 20 74 65  the preferred te
2fbb0 78 74 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 6d  xt encoding.** m
2fbc0 61 74 63 68 65 73 20 74 68 65 20 64 61 74 61 62  atches the datab
2fbd0 61 73 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20  ase encoding is 
2fbe0 61 20 62 65 74 74 65 72 0a 2a 2a 20 6d 61 74 63  a better.** matc
2fbf0 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f  h than a functio
2fc00 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f  n where the enco
2fc10 64 69 6e 67 20 69 73 20 64 69 66 66 65 72 65 6e  ding is differen
2fc20 74 2e 20 20 0a 2a 2a 20 5e 41 20 66 75 6e 63 74  t.  .** ^A funct
2fc30 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e  ion where the en
2fc40 63 6f 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63  coding differenc
2fc50 65 20 69 73 20 62 65 74 77 65 65 6e 20 55 54 46  e is between UTF
2fc60 31 36 6c 65 20 61 6e 64 20 55 54 46 31 36 62 65  16le and UTF16be
2fc70 0a 2a 2a 20 69 73 20 61 20 63 6c 6f 73 65 72 20  .** is a closer 
2fc80 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e  match than a fun
2fc90 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20  ction where the 
2fca0 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 65 72 65  encoding differe
2fcb0 6e 63 65 20 69 73 0a 2a 2a 20 62 65 74 77 65 65  nce is.** betwee
2fcc0 6e 20 55 54 46 38 20 61 6e 64 20 55 54 46 31 36  n UTF8 and UTF16
2fcd0 2e 0a 2a 2a 0a 2a 2a 20 5e 42 75 69 6c 74 2d 69  ..**.** ^Built-i
2fce0 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20  n functions may 
2fcf0 62 65 20 6f 76 65 72 6c 6f 61 64 65 64 20 62 79  be overloaded by
2fd00 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e   new application
2fd10 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
2fd20 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 61 70  ns..**.** ^An ap
2fd30 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
2fd40 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 70 65  d function is pe
2fd50 72 6d 69 74 74 65 64 20 74 6f 20 63 61 6c 6c 20  rmitted to call 
2fd60 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20  other.** SQLite 
2fd70 69 6e 74 65 72 66 61 63 65 73 2e 20 20 48 6f 77  interfaces.  How
2fd80 65 76 65 72 2c 20 73 75 63 68 20 63 61 6c 6c 73  ever, such calls
2fd90 20 6d 75 73 74 20 6e 6f 74 0a 2a 2a 20 63 6c 6f   must not.** clo
2fda0 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  se the database 
2fdb0 63 6f 6e 6e 65 63 74 69 6f 6e 20 6e 6f 72 20 66  connection nor f
2fdc0 69 6e 61 6c 69 7a 65 20 6f 72 20 72 65 73 65 74  inalize or reset
2fdd0 20 74 68 65 20 70 72 65 70 61 72 65 64 0a 2a 2a   the prepared.**
2fde0 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 77 68   statement in wh
2fdf0 69 63 68 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  ich the function
2fe00 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a   is running..*/.
2fe10 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61  int sqlite3_crea
2fe20 74 65 5f 66 75 6e 63 74 69 6f 6e 28 0a 20 20 73  te_function(.  s
2fe30 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f  qlite3 *db,.  co
2fe40 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74  nst char *zFunct
2fe50 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e  ionName,.  int n
2fe60 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74  Arg,.  int eText
2fe70 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70  Rep,.  void *pAp
2fe80 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e  p,.  void (*xFun
2fe90 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  c)(sqlite3_conte
2fea0 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f  xt*,int,sqlite3_
2feb0 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64  value**),.  void
2fec0 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65   (*xStep)(sqlite
2fed0 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73  3_context*,int,s
2fee0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c  qlite3_value**),
2fef0 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c  .  void (*xFinal
2ff00 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
2ff10 74 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  t*).);.int sqlit
2ff20 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
2ff30 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20  on16(.  sqlite3 
2ff40 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 76 6f 69  *db,.  const voi
2ff50 64 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65  d *zFunctionName
2ff60 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20  ,.  int nArg,.  
2ff70 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20  int eTextRep,.  
2ff80 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f  void *pApp,.  vo
2ff90 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69  id (*xFunc)(sqli
2ffa0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74  te3_context*,int
2ffb0 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a  ,sqlite3_value**
2ffc0 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65  ),.  void (*xSte
2ffd0 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  p)(sqlite3_conte
2ffe0 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f  xt*,int,sqlite3_
2fff0 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64  value**),.  void
30000 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74   (*xFinal)(sqlit
30010 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a  e3_context*).);.
30020 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61  int sqlite3_crea
30030 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 0a  te_function_v2(.
30040 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20    sqlite3 *db,. 
30050 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75   const char *zFu
30060 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e  nctionName,.  in
30070 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54  t nArg,.  int eT
30080 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a  extRep,.  void *
30090 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78  pApp,.  void (*x
300a0 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f  Func)(sqlite3_co
300b0 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74  ntext*,int,sqlit
300c0 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76  e3_value**),.  v
300d0 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c  oid (*xStep)(sql
300e0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e  ite3_context*,in
300f0 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t,sqlite3_value*
30100 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69  *),.  void (*xFi
30110 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  nal)(sqlite3_con
30120 74 65 78 74 2a 29 2c 0a 20 20 76 6f 69 64 28 2a  text*),.  void(*
30130 78 44 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29  xDestroy)(void*)
30140 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
30150 52 45 46 3a 20 54 65 78 74 20 45 6e 63 6f 64 69  REF: Text Encodi
30160 6e 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ngs.**.** These 
30170 63 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e 65 20  constant define 
30180 69 6e 74 65 67 65 72 20 63 6f 64 65 73 20 74 68  integer codes th
30190 61 74 20 72 65 70 72 65 73 65 6e 74 20 74 68 65  at represent the
301a0 20 76 61 72 69 6f 75 73 0a 2a 2a 20 74 65 78 74   various.** text
301b0 20 65 6e 63 6f 64 69 6e 67 73 20 73 75 70 70 6f   encodings suppo
301c0 72 74 65 64 20 62 79 20 53 51 4c 69 74 65 2e 0a  rted by SQLite..
301d0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
301e0 45 5f 55 54 46 38 20 20 20 20 20 20 20 20 20 20  E_UTF8          
301f0 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   1.#define SQLIT
30200 45 5f 55 54 46 31 36 4c 45 20 20 20 20 20 20 20  E_UTF16LE       
30210 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   2.#define SQLIT
30220 45 5f 55 54 46 31 36 42 45 20 20 20 20 20 20 20  E_UTF16BE       
30230 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   3.#define SQLIT
30240 45 5f 55 54 46 31 36 20 20 20 20 20 20 20 20 20  E_UTF16         
30250 20 34 20 20 20 20 2f 2a 20 55 73 65 20 6e 61 74   4    /* Use nat
30260 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 2a  ive byte order *
30270 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
30280 5f 41 4e 59 20 20 20 20 20 20 20 20 20 20 20 20  _ANY            
30290 35 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f  5    /* sqlite3_
302a0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 20  create_function 
302b0 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  only */.#define 
302c0 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49  SQLITE_UTF16_ALI
302d0 47 4e 45 44 20 20 38 20 20 20 20 2f 2a 20 73 71  GNED  8    /* sq
302e0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
302f0 6c 61 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a  lation only */..
30300 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
30310 44 65 70 72 65 63 61 74 65 64 20 46 75 6e 63 74  Deprecated Funct
30320 69 6f 6e 73 0a 2a 2a 20 44 45 50 52 45 43 41 54  ions.** DEPRECAT
30330 45 44 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66  ED.**.** These f
30340 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 5b 64 65  unctions are [de
30350 70 72 65 63 61 74 65 64 5d 2e 20 20 49 6e 20 6f  precated].  In o
30360 72 64 65 72 20 74 6f 20 6d 61 69 6e 74 61 69 6e  rder to maintain
30370 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f  .** backwards co
30380 6d 70 61 74 69 62 69 6c 69 74 79 20 77 69 74 68  mpatibility with
30390 20 6f 6c 64 65 72 20 63 6f 64 65 2c 20 74 68 65   older code, the
303a0 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 63 6f 6e  se functions con
303b0 74 69 6e 75 65 20 0a 2a 2a 20 74 6f 20 62 65 20  tinue .** to be 
303c0 73 75 70 70 6f 72 74 65 64 2e 20 20 48 6f 77 65  supported.  Howe
303d0 76 65 72 2c 20 6e 65 77 20 61 70 70 6c 69 63 61  ver, new applica
303e0 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 61 76 6f  tions should avo
303f0 69 64 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f 66  id.** the use of
30400 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   these functions
30410 2e 20 20 54 6f 20 68 65 6c 70 20 65 6e 63 6f 75  .  To help encou
30420 72 61 67 65 20 70 65 6f 70 6c 65 20 74 6f 20 61  rage people to a
30430 76 6f 69 64 0a 2a 2a 20 75 73 69 6e 67 20 74 68  void.** using th
30440 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2c 20 77  ese functions, w
30450 65 20 61 72 65 20 6e 6f 74 20 67 6f 69 6e 67 20  e are not going 
30460 74 6f 20 74 65 6c 6c 20 79 6f 75 20 77 68 61 74  to tell you what
30470 20 74 68 65 79 20 64 6f 2e 0a 2a 2f 0a 23 69 66   they do..*/.#if
30480 6e 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54  ndef SQLITE_OMIT
30490 5f 44 45 50 52 45 43 41 54 45 44 0a 53 51 4c 49  _DEPRECATED.SQLI
304a0 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e  TE_DEPRECATED in
304b0 74 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  t sqlite3_aggreg
304c0 61 74 65 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65  ate_count(sqlite
304d0 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 51 4c  3_context*);.SQL
304e0 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69  ITE_DEPRECATED i
304f0 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 70 69 72  nt sqlite3_expir
30500 65 64 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ed(sqlite3_stmt*
30510 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43  );.SQLITE_DEPREC
30520 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33  ATED int sqlite3
30530 5f 74 72 61 6e 73 66 65 72 5f 62 69 6e 64 69 6e  _transfer_bindin
30540 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  gs(sqlite3_stmt*
30550 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  , sqlite3_stmt*)
30560 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  ;.SQLITE_DEPRECA
30570 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  TED int sqlite3_
30580 67 6c 6f 62 61 6c 5f 72 65 63 6f 76 65 72 28 76  global_recover(v
30590 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50  oid);.SQLITE_DEP
305a0 52 45 43 41 54 45 44 20 76 6f 69 64 20 73 71 6c  RECATED void sql
305b0 69 74 65 33 5f 74 68 72 65 61 64 5f 63 6c 65 61  ite3_thread_clea
305c0 6e 75 70 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54  nup(void);.SQLIT
305d0 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74  E_DEPRECATED int
305e0 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f   sqlite3_memory_
305f0 61 6c 61 72 6d 28 76 6f 69 64 28 2a 29 28 76 6f  alarm(void(*)(vo
30600 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36  id*,sqlite3_int6
30610 34 2c 69 6e 74 29 2c 0a 20 20 20 20 20 20 20 20  4,int),.        
30620 20 20 20 20 20 20 20 20 20 20 20 20 20 20 76 6f                vo
30630 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36  id*,sqlite3_int6
30640 34 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a  4);.#endif../*.*
30650 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61  * CAPI3REF: Obta
30660 69 6e 69 6e 67 20 53 51 4c 20 46 75 6e 63 74 69  ining SQL Functi
30670 6f 6e 20 50 61 72 61 6d 65 74 65 72 20 56 61 6c  on Parameter Val
30680 75 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d  ues.**.** The C-
30690 6c 61 6e 67 75 61 67 65 20 69 6d 70 6c 65 6d 65  language impleme
306a0 6e 74 61 74 69 6f 6e 20 6f 66 20 53 51 4c 20 66  ntation of SQL f
306b0 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67  unctions and agg
306c0 72 65 67 61 74 65 73 20 75 73 65 73 0a 2a 2a 20  regates uses.** 
306d0 74 68 69 73 20 73 65 74 20 6f 66 20 69 6e 74 65  this set of inte
306e0 72 66 61 63 65 20 72 6f 75 74 69 6e 65 73 20 74  rface routines t
306f0 6f 20 61 63 63 65 73 73 20 74 68 65 20 70 61 72  o access the par
30700 61 6d 65 74 65 72 20 76 61 6c 75 65 73 20 6f 6e  ameter values on
30710 0a 2a 2a 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  .** the function
30720 20 6f 72 20 61 67 67 72 65 67 61 74 65 2e 0a 2a   or aggregate..*
30730 2a 0a 2a 2a 20 54 68 65 20 78 46 75 6e 63 20 28  *.** The xFunc (
30740 66 6f 72 20 73 63 61 6c 61 72 20 66 75 6e 63 74  for scalar funct
30750 69 6f 6e 73 29 20 6f 72 20 78 53 74 65 70 20 28  ions) or xStep (
30760 66 6f 72 20 61 67 67 72 65 67 61 74 65 73 29 20  for aggregates) 
30770 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f  parameters.** to
30780 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
30790 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64  _function()] and
307a0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
307b0 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a  _function16()].*
307c0 2a 20 64 65 66 69 6e 65 20 63 61 6c 6c 62 61 63  * define callbac
307d0 6b 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e  ks that implemen
307e0 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  t the SQL functi
307f0 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74  ons and aggregat
30800 65 73 2e 0a 2a 2a 20 54 68 65 20 33 72 64 20 70  es..** The 3rd p
30810 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 73  arameter to thes
30820 65 20 63 61 6c 6c 62 61 63 6b 73 20 69 73 20 61  e callbacks is a
30830 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74  n array of point
30840 65 72 73 20 74 6f 0a 2a 2a 20 5b 70 72 6f 74 65  ers to.** [prote
30850 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
30860 75 65 5d 20 6f 62 6a 65 63 74 73 2e 20 20 54 68  ue] objects.  Th
30870 65 72 65 20 69 73 20 6f 6e 65 20 5b 73 71 6c 69  ere is one [sqli
30880 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
30890 74 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 70 61  t for.** each pa
308a0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 53  rameter to the S
308b0 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 20 20 54 68  QL function.  Th
308c0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
308d0 20 75 73 65 64 20 74 6f 0a 2a 2a 20 65 78 74 72   used to.** extr
308e0 61 63 74 20 76 61 6c 75 65 73 20 66 72 6f 6d 20  act values from 
308f0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  the [sqlite3_val
30900 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a  ue] objects..**.
30910 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
30920 73 20 77 6f 72 6b 20 6f 6e 6c 79 20 77 69 74 68  s work only with
30930 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   [protected sqli
30940 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
30950 74 73 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d  ts..** Any attem
30960 70 74 20 74 6f 20 75 73 65 20 74 68 65 73 65 20  pt to use these 
30970 72 6f 75 74 69 6e 65 73 20 6f 6e 20 61 6e 20 5b  routines on an [
30980 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
30990 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62  te3_value].** ob
309a0 6a 65 63 74 20 72 65 73 75 6c 74 73 20 69 6e 20  ject results in 
309b0 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 69  undefined behavi
309c0 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  or..**.** ^These
309d0 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6a   routines work j
309e0 75 73 74 20 6c 69 6b 65 20 74 68 65 20 63 6f 72  ust like the cor
309f0 72 65 73 70 6f 6e 64 69 6e 67 20 5b 63 6f 6c 75  responding [colu
30a00 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69  mn access functi
30a10 6f 6e 73 5d 0a 2a 2a 20 65 78 63 65 70 74 20 74  ons].** except t
30a20 68 61 74 20 20 74 68 65 73 65 20 72 6f 75 74 69  hat  these routi
30a30 6e 65 73 20 74 61 6b 65 20 61 20 73 69 6e 67 6c  nes take a singl
30a40 65 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c  e [protected sql
30a50 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
30a60 63 74 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e  ct.** pointer in
30a70 73 74 65 61 64 20 6f 66 20 61 20 5b 73 71 6c 69  stead of a [sqli
30a80 74 65 33 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e 74  te3_stmt*] point
30a90 65 72 20 61 6e 64 20 61 6e 20 69 6e 74 65 67 65  er and an intege
30aa0 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e  r column number.
30ab0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
30ac0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
30ad0 28 29 20 69 6e 74 65 72 66 61 63 65 20 65 78 74  () interface ext
30ae0 72 61 63 74 73 20 61 20 55 54 46 2d 31 36 20 73  racts a UTF-16 s
30af0 74 72 69 6e 67 0a 2a 2a 20 69 6e 20 74 68 65 20  tring.** in the 
30b00 6e 61 74 69 76 65 20 62 79 74 65 2d 6f 72 64 65  native byte-orde
30b10 72 20 6f 66 20 74 68 65 20 68 6f 73 74 20 6d 61  r of the host ma
30b20 63 68 69 6e 65 2e 20 20 5e 54 68 65 0a 2a 2a 20  chine.  ^The.** 
30b30 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
30b40 78 74 31 36 62 65 28 29 20 61 6e 64 20 73 71 6c  xt16be() and sql
30b50 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
30b60 36 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 73  6le() interfaces
30b70 0a 2a 2a 20 65 78 74 72 61 63 74 20 55 54 46 2d  .** extract UTF-
30b80 31 36 20 73 74 72 69 6e 67 73 20 61 73 20 62 69  16 strings as bi
30b90 67 2d 65 6e 64 69 61 6e 20 61 6e 64 20 6c 69 74  g-endian and lit
30ba0 74 6c 65 2d 65 6e 64 69 61 6e 20 72 65 73 70 65  tle-endian respe
30bb0 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e  ctively..**.** ^
30bc0 28 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c  (The sqlite3_val
30bd0 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28  ue_numeric_type(
30be0 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65  ) interface atte
30bf0 6d 70 74 73 20 74 6f 20 61 70 70 6c 79 0a 2a 2a  mpts to apply.**
30c00 20 6e 75 6d 65 72 69 63 20 61 66 66 69 6e 69 74   numeric affinit
30c10 79 20 74 6f 20 74 68 65 20 76 61 6c 75 65 2e 20  y to the value. 
30c20 20 54 68 69 73 20 6d 65 61 6e 73 20 74 68 61 74   This means that
30c30 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 0a 2a   an attempt is.*
30c40 2a 20 6d 61 64 65 20 74 6f 20 63 6f 6e 76 65 72  * made to conver
30c50 74 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 61  t the value to a
30c60 6e 20 69 6e 74 65 67 65 72 20 6f 72 20 66 6c 6f  n integer or flo
30c70 61 74 69 6e 67 20 70 6f 69 6e 74 2e 20 20 49 66  ating point.  If
30c80 0a 2a 2a 20 73 75 63 68 20 61 20 63 6f 6e 76 65  .** such a conve
30c90 72 73 69 6f 6e 20 69 73 20 70 6f 73 73 69 62 6c  rsion is possibl
30ca0 65 20 77 69 74 68 6f 75 74 20 6c 6f 73 73 20 6f  e without loss o
30cb0 66 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 28 69  f information (i
30cc0 6e 20 6f 74 68 65 72 0a 2a 2a 20 77 6f 72 64 73  n other.** words
30cd0 2c 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 69  , if the value i
30ce0 73 20 61 20 73 74 72 69 6e 67 20 74 68 61 74 20  s a string that 
30cf0 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61 20 6e 75 6d  looks like a num
30d00 62 65 72 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ber).** then the
30d10 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70   conversion is p
30d20 65 72 66 6f 72 6d 65 64 2e 20 20 4f 74 68 65 72  erformed.  Other
30d30 77 69 73 65 20 6e 6f 20 63 6f 6e 76 65 72 73 69  wise no conversi
30d40 6f 6e 20 6f 63 63 75 72 73 2e 0a 2a 2a 20 54 68  on occurs..** Th
30d50 65 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45  e [SQLITE_INTEGE
30d60 52 20 7c 20 64 61 74 61 74 79 70 65 5d 20 61 66  R | datatype] af
30d70 74 65 72 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69  ter conversion i
30d80 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 0a 2a 2a  s returned.)^.**
30d90 0a 2a 2a 20 50 6c 65 61 73 65 20 70 61 79 20 70  .** Please pay p
30da0 61 72 74 69 63 75 6c 61 72 20 61 74 74 65 6e 74  articular attent
30db0 69 6f 6e 20 74 6f 20 74 68 65 20 66 61 63 74 20  ion to the fact 
30dc0 74 68 61 74 20 74 68 65 20 70 6f 69 6e 74 65 72  that the pointer
30dd0 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f   returned.** fro
30de0 6d 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  m [sqlite3_value
30df0 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74  _blob()], [sqlit
30e00 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d  e3_value_text()]
30e10 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  , or.** [sqlite3
30e20 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d  _value_text16()]
30e30 20 63 61 6e 20 62 65 20 69 6e 76 61 6c 69 64 61   can be invalida
30e40 74 65 64 20 62 79 20 61 20 73 75 62 73 65 71 75  ted by a subsequ
30e50 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b  ent call to.** [
30e60 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
30e70 74 65 73 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  tes()], [sqlite3
30e80 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 29  _value_bytes16()
30e90 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ], [sqlite3_valu
30ea0 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72  e_text()],.** or
30eb0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
30ec0 74 65 78 74 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a  text16()]..**.**
30ed0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
30ee0 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66  must be called f
30ef0 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72  rom the same thr
30f00 65 61 64 20 61 73 0a 2a 2a 20 74 68 65 20 53 51  ead as.** the SQ
30f10 4c 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20  L function that 
30f20 73 75 70 70 6c 69 65 64 20 74 68 65 20 5b 73 71  supplied the [sq
30f30 6c 69 74 65 33 5f 76 61 6c 75 65 2a 5d 20 70 61  lite3_value*] pa
30f40 72 61 6d 65 74 65 72 73 2e 0a 2a 2f 0a 63 6f 6e  rameters..*/.con
30f50 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
30f60 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 73 71 6c 69  _value_blob(sqli
30f70 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74  te3_value*);.int
30f80 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62   sqlite3_value_b
30f90 79 74 65 73 28 73 71 6c 69 74 65 33 5f 76 61 6c  ytes(sqlite3_val
30fa0 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  ue*);.int sqlite
30fb0 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28  3_value_bytes16(
30fc0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
30fd0 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f  .double sqlite3_
30fe0 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28 73 71 6c  value_double(sql
30ff0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e  ite3_value*);.in
31000 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  t sqlite3_value_
31010 69 6e 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  int(sqlite3_valu
31020 65 2a 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74  e*);.sqlite3_int
31030 36 34 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  64 sqlite3_value
31040 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 76  _int64(sqlite3_v
31050 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 75 6e  alue*);.const un
31060 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c  signed char *sql
31070 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28  ite3_value_text(
31080 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
31090 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
310a0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
310b0 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  6(sqlite3_value*
310c0 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
310d0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
310e0 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 76 61  t16le(sqlite3_va
310f0 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  lue*);.const voi
31100 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  d *sqlite3_value
31110 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69 74 65  _text16be(sqlite
31120 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73  3_value*);.int s
31130 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70  qlite3_value_typ
31140 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  e(sqlite3_value*
31150 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76  );.int sqlite3_v
31160 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70  alue_numeric_typ
31170 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  e(sqlite3_value*
31180 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
31190 45 46 3a 20 4f 62 74 61 69 6e 20 41 67 67 72 65  EF: Obtain Aggre
311a0 67 61 74 65 20 46 75 6e 63 74 69 6f 6e 20 43 6f  gate Function Co
311b0 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 49 6d 70 6c  ntext.**.** Impl
311c0 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 61  ementations of a
311d0 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e  ggregate SQL fun
311e0 63 74 69 6f 6e 73 20 75 73 65 20 74 68 69 73 0a  ctions use this.
311f0 2a 2a 20 72 6f 75 74 69 6e 65 20 74 6f 20 61 6c  ** routine to al
31200 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 66 6f  locate memory fo
31210 72 20 73 74 6f 72 69 6e 67 20 74 68 65 69 72 20  r storing their 
31220 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  state..**.** ^Th
31230 65 20 66 69 72 73 74 20 74 69 6d 65 20 74 68 65  e first time the
31240 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
31250 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20  te_context(C,N) 
31260 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65  routine is calle
31270 64 20 0a 2a 2a 20 66 6f 72 20 61 20 70 61 72 74  d .** for a part
31280 69 63 75 6c 61 72 20 61 67 67 72 65 67 61 74 65  icular aggregate
31290 20 66 75 6e 63 74 69 6f 6e 2c 20 53 51 4c 69 74   function, SQLit
312a0 65 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 73 20 4e  e.** allocates N
312b0 20 6f 66 20 6d 65 6d 6f 72 79 2c 20 7a 65 72 6f   of memory, zero
312c0 65 73 20 6f 75 74 20 74 68 61 74 20 6d 65 6d 6f  es out that memo
312d0 72 79 2c 20 61 6e 64 20 72 65 74 75 72 6e 73 20  ry, and returns 
312e0 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20  a pointer.** to 
312f0 74 68 65 20 6e 65 77 20 6d 65 6d 6f 72 79 2e 20  the new memory. 
31300 5e 4f 6e 20 73 65 63 6f 6e 64 20 61 6e 64 20 73  ^On second and s
31310 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20  ubsequent calls 
31320 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67  to.** sqlite3_ag
31330 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
31340 29 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 61  ) for the same a
31350 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f  ggregate functio
31360 6e 20 69 6e 73 74 61 6e 63 65 2c 0a 2a 2a 20 74  n instance,.** t
31370 68 65 20 73 61 6d 65 20 62 75 66 66 65 72 20 69  he same buffer i
31380 73 20 72 65 74 75 72 6e 65 64 2e 20 20 53 71 6c  s returned.  Sql
31390 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
313a0 6f 6e 74 65 78 74 28 29 20 69 73 20 6e 6f 72 6d  ontext() is norm
313b0 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 6f  ally.** called o
313c0 6e 63 65 20 66 6f 72 20 65 61 63 68 20 69 6e 76  nce for each inv
313d0 6f 63 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78  ocation of the x
313e0 53 74 65 70 20 63 61 6c 6c 62 61 63 6b 20 61 6e  Step callback an
313f0 64 20 74 68 65 6e 20 6f 6e 65 0a 2a 2a 20 6c 61  d then one.** la
31400 73 74 20 74 69 6d 65 20 77 68 65 6e 20 74 68 65  st time when the
31410 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b   xFinal callback
31420 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 28   is invoked.  ^(
31430 57 68 65 6e 20 6e 6f 20 72 6f 77 73 20 6d 61 74  When no rows mat
31440 63 68 0a 2a 2a 20 61 6e 20 61 67 67 72 65 67 61  ch.** an aggrega
31450 74 65 20 71 75 65 72 79 2c 20 74 68 65 20 78 53  te query, the xS
31460 74 65 70 28 29 20 63 61 6c 6c 62 61 63 6b 20 6f  tep() callback o
31470 66 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20  f the aggregate 
31480 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 69 6d 70 6c  function.** impl
31490 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6e 65  ementation is ne
314a0 76 65 72 20 63 61 6c 6c 65 64 20 61 6e 64 20 78  ver called and x
314b0 46 69 6e 61 6c 28 29 20 69 73 20 63 61 6c 6c 65  Final() is calle
314c0 64 20 65 78 61 63 74 6c 79 20 6f 6e 63 65 2e 0a  d exactly once..
314d0 2a 2a 20 49 6e 20 74 68 6f 73 65 20 63 61 73 65  ** In those case
314e0 73 2c 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  s, sqlite3_aggre
314f0 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 6d  gate_context() m
31500 69 67 68 74 20 62 65 20 63 61 6c 6c 65 64 20 66  ight be called f
31510 6f 72 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20  or the.** first 
31520 74 69 6d 65 20 66 72 6f 6d 20 77 69 74 68 69 6e  time from within
31530 20 78 46 69 6e 61 6c 28 29 2e 29 5e 0a 2a 2a 0a   xFinal().)^.**.
31540 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
31550 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
31560 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e 65 20 72  t(C,N) routine r
31570 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f  eturns a NULL po
31580 69 6e 74 65 72 20 0a 2a 2a 20 77 68 65 6e 20 66  inter .** when f
31590 69 72 73 74 20 63 61 6c 6c 65 64 20 69 66 20 4e  irst called if N
315a0 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 6f 72   is less than or
315b0 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 20 6f   equal to zero o
315c0 72 20 69 66 20 61 20 6d 65 6d 6f 72 79 0a 2a 2a  r if a memory.**
315d0 20 61 6c 6c 6f 63 61 74 65 20 65 72 72 6f 72 20   allocate error 
315e0 6f 63 63 75 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28  occurs..**.** ^(
315f0 54 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 73 70  The amount of sp
31600 61 63 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79  ace allocated by
31610 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
31620 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20  te_context(C,N) 
31630 69 73 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 65 64  is.** determined
31640 20 62 79 20 74 68 65 20 4e 20 70 61 72 61 6d 65   by the N parame
31650 74 65 72 20 6f 6e 20 66 69 72 73 74 20 73 75 63  ter on first suc
31660 63 65 73 73 66 75 6c 20 63 61 6c 6c 2e 20 20 43  cessful call.  C
31670 68 61 6e 67 69 6e 67 20 74 68 65 0a 2a 2a 20 76  hanging the.** v
31680 61 6c 75 65 20 6f 66 20 4e 20 69 6e 20 73 75 62  alue of N in sub
31690 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20  sequent call to 
316a0 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
316b0 65 5f 63 6f 6e 74 65 78 74 28 29 20 77 69 74 68  e_context() with
316c0 69 6e 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 61  in.** the same a
316d0 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f  ggregate functio
316e0 6e 20 69 6e 73 74 61 6e 63 65 20 77 69 6c 6c 20  n instance will 
316f0 6e 6f 74 20 72 65 73 69 7a 65 20 74 68 65 20 6d  not resize the m
31700 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74  emory.** allocat
31710 69 6f 6e 2e 29 5e 20 20 57 69 74 68 69 6e 20 74  ion.)^  Within t
31720 68 65 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61  he xFinal callba
31730 63 6b 2c 20 69 74 20 69 73 20 63 75 73 74 6f 6d  ck, it is custom
31740 61 72 79 20 74 6f 20 73 65 74 0a 2a 2a 20 4e 3d  ary to set.** N=
31750 30 20 69 6e 20 63 61 6c 6c 73 20 74 6f 20 73 71  0 in calls to sq
31760 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
31770 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 73 6f 20  context(C,N) so 
31780 74 68 61 74 20 6e 6f 20 0a 2a 2a 20 70 6f 69 6e  that no .** poin
31790 74 6c 65 73 73 20 6d 65 6d 6f 72 79 20 61 6c 6c  tless memory all
317a0 6f 63 61 74 69 6f 6e 73 20 6f 63 63 75 72 2e 0a  ocations occur..
317b0 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 61 75  **.** ^SQLite au
317c0 74 6f 6d 61 74 69 63 61 6c 6c 79 20 66 72 65 65  tomatically free
317d0 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  s the memory all
317e0 6f 63 61 74 65 64 20 62 79 20 0a 2a 2a 20 73 71  ocated by .** sq
317f0 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
31800 63 6f 6e 74 65 78 74 28 29 20 77 68 65 6e 20 74  context() when t
31810 68 65 20 61 67 67 72 65 67 61 74 65 20 71 75 65  he aggregate que
31820 72 79 20 63 6f 6e 63 6c 75 64 65 73 2e 0a 2a 2a  ry concludes..**
31830 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 61  .** The first pa
31840 72 61 6d 65 74 65 72 20 6d 75 73 74 20 62 65 20  rameter must be 
31850 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a  a copy of the.**
31860 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78   [sqlite3_contex
31870 74 20 7c 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  t | SQL function
31880 20 63 6f 6e 74 65 78 74 5d 20 74 68 61 74 20 69   context] that i
31890 73 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61  s the first para
318a0 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20  meter.** to the 
318b0 78 53 74 65 70 20 6f 72 20 78 46 69 6e 61 6c 20  xStep or xFinal 
318c0 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65  callback routine
318d0 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73   that implements
318e0 20 74 68 65 20 61 67 67 72 65 67 61 74 65 0a 2a   the aggregate.*
318f0 2a 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a  * function..**.*
31900 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d  * This routine m
31910 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72  ust be called fr
31920 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65  om the same thre
31930 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74  ad in which.** t
31940 68 65 20 61 67 67 72 65 67 61 74 65 20 53 51 4c  he aggregate SQL
31950 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e   function is run
31960 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73  ning..*/.void *s
31970 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
31980 5f 63 6f 6e 74 65 78 74 28 73 71 6c 69 74 65 33  _context(sqlite3
31990 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e  _context*, int n
319a0 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  Bytes);../*.** C
319b0 41 50 49 33 52 45 46 3a 20 55 73 65 72 20 44 61  API3REF: User Da
319c0 74 61 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73  ta For Functions
319d0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
319e0 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 20  te3_user_data() 
319f0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
31a00 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74  s a copy of.** t
31a10 68 65 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20  he pointer that 
31a20 77 61 73 20 74 68 65 20 70 55 73 65 72 44 61 74  was the pUserDat
31a30 61 20 70 61 72 61 6d 65 74 65 72 20 28 74 68 65  a parameter (the
31a40 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 29 0a   5th parameter).
31a50 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ** of the [sqlit
31a60 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
31a70 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71  on()].** and [sq
31a80 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
31a90 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69  ction16()] routi
31aa0 6e 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e 61  nes that origina
31ab0 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65  lly.** registere
31ac0 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  d the applicatio
31ad0 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n defined functi
31ae0 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  on..**.** This r
31af0 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63  outine must be c
31b00 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73  alled from the s
31b10 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68  ame thread in wh
31b20 69 63 68 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69  ich.** the appli
31b30 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
31b40 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69  unction is runni
31b50 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c  ng..*/.void *sql
31b60 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 73  ite3_user_data(s
31b70 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
31b80 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
31b90 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e  F: Database Conn
31ba0 65 63 74 69 6f 6e 20 46 6f 72 20 46 75 6e 63 74  ection For Funct
31bb0 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ions.**.** ^The 
31bc0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f  sqlite3_context_
31bd0 64 62 5f 68 61 6e 64 6c 65 28 29 20 69 6e 74 65  db_handle() inte
31be0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
31bf0 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70  copy of.** the p
31c00 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 64  ointer to the [d
31c10 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
31c20 6f 6e 5d 20 28 74 68 65 20 31 73 74 20 70 61 72  on] (the 1st par
31c30 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68  ameter).** of th
31c40 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  e [sqlite3_creat
31c50 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a  e_function()].**
31c60 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72   and [sqlite3_cr
31c70 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
31c80 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74  )] routines that
31c90 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72   originally.** r
31ca0 65 67 69 73 74 65 72 65 64 20 74 68 65 20 61 70  egistered the ap
31cb0 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65  plication define
31cc0 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2f 0a 73  d function..*/.s
31cd0 71 6c 69 74 65 33 20 2a 73 71 6c 69 74 65 33 5f  qlite3 *sqlite3_
31ce0 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c  context_db_handl
31cf0 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  e(sqlite3_contex
31d00 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
31d10 33 52 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20 41  3REF: Function A
31d20 75 78 69 6c 69 61 72 79 20 44 61 74 61 0a 2a 2a  uxiliary Data.**
31d30 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e  .** The followin
31d40 67 20 74 77 6f 20 66 75 6e 63 74 69 6f 6e 73 20  g two functions 
31d50 6d 61 79 20 62 65 20 75 73 65 64 20 62 79 20 73  may be used by s
31d60 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69  calar SQL functi
31d70 6f 6e 73 20 74 6f 0a 2a 2a 20 61 73 73 6f 63 69  ons to.** associ
31d80 61 74 65 20 6d 65 74 61 64 61 74 61 20 77 69 74  ate metadata wit
31d90 68 20 61 72 67 75 6d 65 6e 74 20 76 61 6c 75 65  h argument value
31da0 73 2e 20 49 66 20 74 68 65 20 73 61 6d 65 20 76  s. If the same v
31db0 61 6c 75 65 20 69 73 20 70 61 73 73 65 64 20 74  alue is passed t
31dc0 6f 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 69 6e  o.** multiple in
31dd0 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65  vocations of the
31de0 20 73 61 6d 65 20 53 51 4c 20 66 75 6e 63 74 69   same SQL functi
31df0 6f 6e 20 64 75 72 69 6e 67 20 71 75 65 72 79 20  on during query 
31e00 65 78 65 63 75 74 69 6f 6e 2c 20 75 6e 64 65 72  execution, under
31e10 0a 2a 2a 20 73 6f 6d 65 20 63 69 72 63 75 6d 73  .** some circums
31e20 74 61 6e 63 65 73 20 74 68 65 20 61 73 73 6f 63  tances the assoc
31e30 69 61 74 65 64 20 6d 65 74 61 64 61 74 61 20 6d  iated metadata m
31e40 61 79 20 62 65 20 70 72 65 73 65 72 76 65 64 2e  ay be preserved.
31e50 20 54 68 69 73 20 6d 61 79 0a 2a 2a 20 62 65 20   This may.** be 
31e60 75 73 65 64 2c 20 66 6f 72 20 65 78 61 6d 70 6c  used, for exampl
31e70 65 2c 20 74 6f 20 61 64 64 20 61 20 72 65 67 75  e, to add a regu
31e80 6c 61 72 2d 65 78 70 72 65 73 73 69 6f 6e 20 6d  lar-expression m
31e90 61 74 63 68 69 6e 67 20 73 63 61 6c 61 72 0a 2a  atching scalar.*
31ea0 2a 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20  * function. The 
31eb0 63 6f 6d 70 69 6c 65 64 20 76 65 72 73 69 6f 6e  compiled version
31ec0 20 6f 66 20 74 68 65 20 72 65 67 75 6c 61 72 20   of the regular 
31ed0 65 78 70 72 65 73 73 69 6f 6e 20 69 73 20 73 74  expression is st
31ee0 6f 72 65 64 20 61 73 0a 2a 2a 20 6d 65 74 61 64  ored as.** metad
31ef0 61 74 61 20 61 73 73 6f 63 69 61 74 65 64 20 77  ata associated w
31f00 69 74 68 20 74 68 65 20 53 51 4c 20 76 61 6c 75  ith the SQL valu
31f10 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  e passed as the 
31f20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73 73 69  regular expressi
31f30 6f 6e 0a 2a 2a 20 70 61 74 74 65 72 6e 2e 20 20  on.** pattern.  
31f40 54 68 65 20 63 6f 6d 70 69 6c 65 64 20 72 65 67  The compiled reg
31f50 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20  ular expression 
31f60 63 61 6e 20 62 65 20 72 65 75 73 65 64 20 6f 6e  can be reused on
31f70 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e 76   multiple.** inv
31f80 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  ocations of the 
31f90 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 73 6f  same function so
31fa0 20 74 68 61 74 20 74 68 65 20 6f 72 69 67 69 6e   that the origin
31fb0 61 6c 20 70 61 74 74 65 72 6e 20 73 74 72 69 6e  al pattern strin
31fc0 67 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 6e 65  g.** does not ne
31fd0 65 64 20 74 6f 20 62 65 20 72 65 63 6f 6d 70 69  ed to be recompi
31fe0 6c 65 64 20 6f 6e 20 65 61 63 68 20 69 6e 76 6f  led on each invo
31ff0 63 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54  cation..**.** ^T
32000 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  he sqlite3_get_a
32010 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 66 61  uxdata() interfa
32020 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ce returns a poi
32030 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65 74 61  nter to the meta
32040 64 61 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74  data.** associat
32050 65 64 20 62 79 20 74 68 65 20 73 71 6c 69 74 65  ed by the sqlite
32060 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20  3_set_auxdata() 
32070 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 74 68  function with th
32080 65 20 4e 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a  e Nth argument.*
32090 2a 20 76 61 6c 75 65 20 74 6f 20 74 68 65 20 61  * value to the a
320a0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
320b0 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 5e 49 66  ed function. ^If
320c0 20 6e 6f 20 6d 65 74 61 64 61 74 61 20 68 61 73   no metadata has
320d0 20 62 65 65 6e 20 65 76 65 72 0a 2a 2a 20 62 65   been ever.** be
320e0 65 6e 20 73 65 74 20 66 6f 72 20 74 68 65 20 4e  en set for the N
320f0 74 68 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74  th argument of t
32100 68 65 20 66 75 6e 63 74 69 6f 6e 2c 20 6f 72 20  he function, or 
32110 69 66 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  if the correspon
32120 64 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  ding.** function
32130 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 63   parameter has c
32140 68 61 6e 67 65 64 20 73 69 6e 63 65 20 74 68 65  hanged since the
32150 20 6d 65 74 61 2d 64 61 74 61 20 77 61 73 20 73   meta-data was s
32160 65 74 2c 0a 2a 2a 20 74 68 65 6e 20 73 71 6c 69  et,.** then sqli
32170 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28  te3_get_auxdata(
32180 29 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c  ) returns a NULL
32190 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
321a0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74  ^The sqlite3_set
321b0 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74 65 72  _auxdata() inter
321c0 66 61 63 65 20 73 61 76 65 73 20 74 68 65 20 6d  face saves the m
321d0 65 74 61 64 61 74 61 0a 2a 2a 20 70 6f 69 6e 74  etadata.** point
321e0 65 64 20 74 6f 20 62 79 20 69 74 73 20 33 72 64  ed to by its 3rd
321f0 20 70 61 72 61 6d 65 74 65 72 20 61 73 20 74 68   parameter as th
32200 65 20 6d 65 74 61 64 61 74 61 20 66 6f 72 20 74  e metadata for t
32210 68 65 20 4e 2d 74 68 0a 2a 2a 20 61 72 67 75 6d  he N-th.** argum
32220 65 6e 74 20 6f 66 20 74 68 65 20 61 70 70 6c 69  ent of the appli
32230 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
32240 75 6e 63 74 69 6f 6e 2e 20 20 53 75 62 73 65 71  unction.  Subseq
32250 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f  uent.** calls to
32260 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78   sqlite3_get_aux
32270 64 61 74 61 28 29 20 6d 69 67 68 74 20 72 65 74  data() might ret
32280 75 72 6e 20 74 68 69 73 20 64 61 74 61 2c 20 69  urn this data, i
32290 66 20 69 74 20 68 61 73 0a 2a 2a 20 6e 6f 74 20  f it has.** not 
322a0 62 65 65 6e 20 64 65 73 74 72 6f 79 65 64 2e 0a  been destroyed..
322b0 2a 2a 20 5e 49 66 20 69 74 20 69 73 20 6e 6f 74  ** ^If it is not
322c0 20 4e 55 4c 4c 2c 20 53 51 4c 69 74 65 20 77 69   NULL, SQLite wi
322d0 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20 64 65  ll invoke the de
322e0 73 74 72 75 63 74 6f 72 0a 2a 2a 20 66 75 6e 63  structor.** func
322f0 74 69 6f 6e 20 67 69 76 65 6e 20 62 79 20 74 68  tion given by th
32300 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 4th parameter 
32310 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  to sqlite3_set_a
32320 75 78 64 61 74 61 28 29 20 6f 6e 0a 2a 2a 20 74  uxdata() on.** t
32330 68 65 20 6d 65 74 61 64 61 74 61 20 77 68 65 6e  he metadata when
32340 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69   the correspondi
32350 6e 67 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61  ng function para
32360 6d 65 74 65 72 20 63 68 61 6e 67 65 73 0a 2a 2a  meter changes.**
32370 20 6f 72 20 77 68 65 6e 20 74 68 65 20 53 51 4c   or when the SQL
32380 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 6c   statement compl
32390 65 74 65 73 2c 20 77 68 69 63 68 65 76 65 72 20  etes, whichever 
323a0 63 6f 6d 65 73 20 66 69 72 73 74 2e 0a 2a 2a 0a  comes first..**.
323b0 2a 2a 20 53 51 4c 69 74 65 20 69 73 20 66 72 65  ** SQLite is fre
323c0 65 20 74 6f 20 63 61 6c 6c 20 74 68 65 20 64 65  e to call the de
323d0 73 74 72 75 63 74 6f 72 20 61 6e 64 20 64 72 6f  structor and dro
323e0 70 20 6d 65 74 61 64 61 74 61 20 6f 6e 20 61 6e  p metadata on an
323f0 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 6f  y.** parameter o
32400 66 20 61 6e 79 20 66 75 6e 63 74 69 6f 6e 20 61  f any function a
32410 74 20 61 6e 79 20 74 69 6d 65 2e 20 20 5e 54 68  t any time.  ^Th
32420 65 20 6f 6e 6c 79 20 67 75 61 72 61 6e 74 65 65  e only guarantee
32430 20 69 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20   is that.** the 
32440 64 65 73 74 72 75 63 74 6f 72 20 77 69 6c 6c 20  destructor will 
32450 62 65 20 63 61 6c 6c 65 64 20 62 65 66 6f 72 65  be called before
32460 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 69 73   the metadata is
32470 20 64 72 6f 70 70 65 64 2e 0a 2a 2a 0a 2a 2a 20   dropped..**.** 
32480 5e 28 49 6e 20 70 72 61 63 74 69 63 65 2c 20 6d  ^(In practice, m
32490 65 74 61 64 61 74 61 20 69 73 20 70 72 65 73 65  etadata is prese
324a0 72 76 65 64 20 62 65 74 77 65 65 6e 20 66 75 6e  rved between fun
324b0 63 74 69 6f 6e 20 63 61 6c 6c 73 20 66 6f 72 0a  ction calls for.
324c0 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 73 20 74  ** expressions t
324d0 68 61 74 20 61 72 65 20 63 6f 6e 73 74 61 6e 74  hat are constant
324e0 20 61 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65   at compile time
324f0 2e 20 54 68 69 73 20 69 6e 63 6c 75 64 65 73 20  . This includes 
32500 6c 69 74 65 72 61 6c 0a 2a 2a 20 76 61 6c 75 65  literal.** value
32510 73 20 61 6e 64 20 5b 70 61 72 61 6d 65 74 65 72  s and [parameter
32520 73 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  s].)^.**.** Thes
32530 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20  e routines must 
32540 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74  be called from t
32550 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69  he same thread i
32560 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 53  n which.** the S
32570 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72  QL function is r
32580 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20  unning..*/.void 
32590 2a 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78  *sqlite3_get_aux
325a0 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e  data(sqlite3_con
325b0 74 65 78 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 76  text*, int N);.v
325c0 6f 69 64 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  oid sqlite3_set_
325d0 61 75 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f  auxdata(sqlite3_
325e0 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 2c  context*, int N,
325f0 20 76 6f 69 64 2a 2c 20 76 6f 69 64 20 28 2a 29   void*, void (*)
32600 28 76 6f 69 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a  (void*));.../*.*
32610 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 73  * CAPI3REF: Cons
32620 74 61 6e 74 73 20 44 65 66 69 6e 69 6e 67 20 53  tants Defining S
32630 70 65 63 69 61 6c 20 44 65 73 74 72 75 63 74 6f  pecial Destructo
32640 72 20 42 65 68 61 76 69 6f 72 0a 2a 2a 0a 2a 2a  r Behavior.**.**
32650 20 54 68 65 73 65 20 61 72 65 20 73 70 65 63 69   These are speci
32660 61 6c 20 76 61 6c 75 65 73 20 66 6f 72 20 74 68  al values for th
32670 65 20 64 65 73 74 72 75 63 74 6f 72 20 74 68 61  e destructor tha
32680 74 20 69 73 20 70 61 73 73 65 64 20 69 6e 20 61  t is passed in a
32690 73 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 61  s the.** final a
326a0 72 67 75 6d 65 6e 74 20 74 6f 20 72 6f 75 74 69  rgument to routi
326b0 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65  nes like [sqlite
326c0 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 5d  3_result_blob()]
326d0 2e 20 20 5e 49 66 20 74 68 65 20 64 65 73 74 72  .  ^If the destr
326e0 75 63 74 6f 72 0a 2a 2a 20 61 72 67 75 6d 65 6e  uctor.** argumen
326f0 74 20 69 73 20 53 51 4c 49 54 45 5f 53 54 41 54  t is SQLITE_STAT
32700 49 43 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61  IC, it means tha
32710 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 70 6f  t the content po
32720 69 6e 74 65 72 20 69 73 20 63 6f 6e 73 74 61 6e  inter is constan
32730 74 0a 2a 2a 20 61 6e 64 20 77 69 6c 6c 20 6e 65  t.** and will ne
32740 76 65 72 20 63 68 61 6e 67 65 2e 20 20 49 74 20  ver change.  It 
32750 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f  does not need to
32760 20 62 65 20 64 65 73 74 72 6f 79 65 64 2e 20 20   be destroyed.  
32770 5e 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 54  ^The.** SQLITE_T
32780 52 41 4e 53 49 45 4e 54 20 76 61 6c 75 65 20 6d  RANSIENT value m
32790 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 63 6f  eans that the co
327a0 6e 74 65 6e 74 20 77 69 6c 6c 20 6c 69 6b 65 6c  ntent will likel
327b0 79 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 74  y change in.** t
327c0 68 65 20 6e 65 61 72 20 66 75 74 75 72 65 20 61  he near future a
327d0 6e 64 20 74 68 61 74 20 53 51 4c 69 74 65 20 73  nd that SQLite s
327e0 68 6f 75 6c 64 20 6d 61 6b 65 20 69 74 73 20 6f  hould make its o
327f0 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20  wn private copy 
32800 6f 66 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e  of.** the conten
32810 74 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e 69  t before returni
32820 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 79  ng..**.** The ty
32830 70 65 64 65 66 20 69 73 20 6e 65 63 65 73 73 61  pedef is necessa
32840 72 79 20 74 6f 20 77 6f 72 6b 20 61 72 6f 75 6e  ry to work aroun
32850 64 20 70 72 6f 62 6c 65 6d 73 20 69 6e 20 63 65  d problems in ce
32860 72 74 61 69 6e 0a 2a 2a 20 43 2b 2b 20 63 6f 6d  rtain.** C++ com
32870 70 69 6c 65 72 73 2e 0a 2a 2f 0a 74 79 70 65 64  pilers..*/.typed
32880 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 74 65  ef void (*sqlite
32890 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70  3_destructor_typ
328a0 65 29 28 76 6f 69 64 2a 29 3b 0a 23 64 65 66 69  e)(void*);.#defi
328b0 6e 65 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43  ne SQLITE_STATIC
328c0 20 20 20 20 20 20 28 28 73 71 6c 69 74 65 33 5f        ((sqlite3_
328d0 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29  destructor_type)
328e0 30 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  0).#define SQLIT
328f0 45 5f 54 52 41 4e 53 49 45 4e 54 20 20 20 28 28  E_TRANSIENT   ((
32900 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74  sqlite3_destruct
32910 6f 72 5f 74 79 70 65 29 2d 31 29 0a 0a 2f 2a 0a  or_type)-1)../*.
32920 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 74  ** CAPI3REF: Set
32930 74 69 6e 67 20 54 68 65 20 52 65 73 75 6c 74 20  ting The Result 
32940 4f 66 20 41 6e 20 53 51 4c 20 46 75 6e 63 74 69  Of An SQL Functi
32950 6f 6e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  on.**.** These r
32960 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 64  outines are used
32970 20 62 79 20 74 68 65 20 78 46 75 6e 63 20 6f 72   by the xFunc or
32980 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b   xFinal callback
32990 73 20 74 68 61 74 0a 2a 2a 20 69 6d 70 6c 65 6d  s that.** implem
329a0 65 6e 74 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ent SQL function
329b0 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73  s and aggregates
329c0 2e 20 20 53 65 65 0a 2a 2a 20 5b 73 71 6c 69 74  .  See.** [sqlit
329d0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
329e0 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  on()] and [sqlit
329f0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
32a00 6f 6e 31 36 28 29 5d 0a 2a 2a 20 66 6f 72 20 61  on16()].** for a
32a10 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d  dditional inform
32a20 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ation..**.** The
32a30 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 77 6f 72  se functions wor
32a40 6b 20 76 65 72 79 20 6d 75 63 68 20 6c 69 6b 65  k very much like
32a50 20 74 68 65 20 5b 70 61 72 61 6d 65 74 65 72 20   the [parameter 
32a60 62 69 6e 64 69 6e 67 5d 20 66 61 6d 69 6c 79 20  binding] family 
32a70 6f 66 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20  of.** functions 
32a80 75 73 65 64 20 74 6f 20 62 69 6e 64 20 76 61 6c  used to bind val
32a90 75 65 73 20 74 6f 20 68 6f 73 74 20 70 61 72 61  ues to host para
32aa0 6d 65 74 65 72 73 20 69 6e 20 70 72 65 70 61 72  meters in prepar
32ab0 65 64 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a  ed statements..*
32ac0 2a 20 52 65 66 65 72 20 74 6f 20 74 68 65 20 5b  * Refer to the [
32ad0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 64  SQL parameter] d
32ae0 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72  ocumentation for
32af0 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f   additional info
32b00 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e  rmation..**.** ^
32b10 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
32b20 6c 74 5f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66  lt_blob() interf
32b30 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73  ace sets the res
32b40 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61  ult from.** an a
32b50 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
32b60 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
32b70 65 20 74 68 65 20 42 4c 4f 42 20 77 68 6f 73 65  e the BLOB whose
32b80 20 63 6f 6e 74 65 6e 74 20 69 73 20 70 6f 69 6e   content is poin
32b90 74 65 64 0a 2a 2a 20 74 6f 20 62 79 20 74 68 65  ted.** to by the
32ba0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
32bb0 72 20 61 6e 64 20 77 68 69 63 68 20 69 73 20 4e  r and which is N
32bc0 20 62 79 74 65 73 20 6c 6f 6e 67 20 77 68 65 72   bytes long wher
32bd0 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20 74 68  e N is the.** th
32be0 69 72 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  ird parameter..*
32bf0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
32c00 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f  3_result_zeroblo
32c10 62 28 29 20 69 6e 74 65 72 66 61 63 65 73 20 73  b() interfaces s
32c20 65 74 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66  et the result of
32c30 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74  .** the applicat
32c40 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
32c50 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 42 4c 4f  tion to be a BLO
32c60 42 20 63 6f 6e 74 61 69 6e 69 6e 67 20 61 6c 6c  B containing all
32c70 20 7a 65 72 6f 0a 2a 2a 20 62 79 74 65 73 20 61   zero.** bytes a
32c80 6e 64 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69  nd N bytes in si
32c90 7a 65 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74  ze, where N is t
32ca0 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  he value of the 
32cb0 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  2nd parameter..*
32cc0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
32cd0 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28  3_result_double(
32ce0 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73  ) interface sets
32cf0 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d   the result from
32d00 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69  .** an applicati
32d10 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
32d20 69 6f 6e 20 74 6f 20 62 65 20 61 20 66 6c 6f 61  ion to be a floa
32d30 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65  ting point value
32d40 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79   specified.** by
32d50 20 69 74 73 20 32 6e 64 20 61 72 67 75 6d 65 6e   its 2nd argumen
32d60 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  t..**.** ^The sq
32d70 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
32d80 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  or() and sqlite3
32d90 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
32da0 29 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 63  ) functions.** c
32db0 61 75 73 65 20 74 68 65 20 69 6d 70 6c 65 6d 65  ause the impleme
32dc0 6e 74 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  nted SQL functio
32dd0 6e 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 78  n to throw an ex
32de0 63 65 70 74 69 6f 6e 2e 0a 2a 2a 20 5e 53 51 4c  ception..** ^SQL
32df0 69 74 65 20 75 73 65 73 20 74 68 65 20 73 74 72  ite uses the str
32e00 69 6e 67 20 70 6f 69 6e 74 65 64 20 74 6f 20 62  ing pointed to b
32e10 79 20 74 68 65 0a 2a 2a 20 32 6e 64 20 70 61 72  y the.** 2nd par
32e20 61 6d 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65  ameter of sqlite
32e30 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
32e40 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75   or sqlite3_resu
32e50 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20  lt_error16().** 
32e60 61 73 20 74 68 65 20 74 65 78 74 20 6f 66 20 61  as the text of a
32e70 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e  n error message.
32e80 20 20 5e 53 51 4c 69 74 65 20 69 6e 74 65 72 70    ^SQLite interp
32e90 72 65 74 73 20 74 68 65 20 65 72 72 6f 72 0a 2a  rets the error.*
32ea0 2a 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67  * message string
32eb0 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65   from sqlite3_re
32ec0 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 73 20  sult_error() as 
32ed0 55 54 46 2d 38 2e 20 5e 53 51 4c 69 74 65 0a 2a  UTF-8. ^SQLite.*
32ee0 2a 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 65  * interprets the
32ef0 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c   string from sql
32f00 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
32f10 72 31 36 28 29 20 61 73 20 55 54 46 2d 31 36 20  r16() as UTF-16 
32f20 69 6e 20 6e 61 74 69 76 65 0a 2a 2a 20 62 79 74  in native.** byt
32f30 65 20 6f 72 64 65 72 2e 20 20 5e 49 66 20 74 68  e order.  ^If th
32f40 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
32f50 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73  r to sqlite3_res
32f60 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f  ult_error().** o
32f70 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  r sqlite3_result
32f80 5f 65 72 72 6f 72 31 36 28 29 20 69 73 20 6e 65  _error16() is ne
32f90 67 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69  gative then SQLi
32fa0 74 65 20 74 61 6b 65 73 20 61 73 20 74 68 65 20  te takes as the 
32fb0 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65  error.** message
32fc0 20 61 6c 6c 20 74 65 78 74 20 75 70 20 74 68 72   all text up thr
32fd0 6f 75 67 68 20 74 68 65 20 66 69 72 73 74 20 7a  ough the first z
32fe0 65 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a  ero character..*
32ff0 2a 20 5e 49 66 20 74 68 65 20 74 68 69 72 64 20  * ^If the third 
33000 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
33010 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
33020 72 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  r() or.** sqlite
33030 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
33040 28 29 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69  () is non-negati
33050 76 65 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74  ve then SQLite t
33060 61 6b 65 73 20 74 68 61 74 20 6d 61 6e 79 0a 2a  akes that many.*
33070 2a 20 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61  * bytes (not cha
33080 72 61 63 74 65 72 73 29 20 66 72 6f 6d 20 74 68  racters) from th
33090 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  e 2nd parameter 
330a0 61 73 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73  as the error mes
330b0 73 61 67 65 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  sage..** ^The sq
330c0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
330d0 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  or() and sqlite3
330e0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
330f0 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 6d 61  ).** routines ma
33100 6b 65 20 61 20 70 72 69 76 61 74 65 20 63 6f 70  ke a private cop
33110 79 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20 6d  y of the error m
33120 65 73 73 61 67 65 20 74 65 78 74 20 62 65 66 6f  essage text befo
33130 72 65 0a 2a 2a 20 74 68 65 79 20 72 65 74 75 72  re.** they retur
33140 6e 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20 63  n.  Hence, the c
33150 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  alling function 
33160 63 61 6e 20 64 65 61 6c 6c 6f 63 61 74 65 20 6f  can deallocate o
33170 72 0a 2a 2a 20 6d 6f 64 69 66 79 20 74 68 65 20  r.** modify the 
33180 74 65 78 74 20 61 66 74 65 72 20 74 68 65 79 20  text after they 
33190 72 65 74 75 72 6e 20 77 69 74 68 6f 75 74 20 68  return without h
331a0 61 72 6d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  arm..** ^The sql
331b0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
331c0 72 5f 63 6f 64 65 28 29 20 66 75 6e 63 74 69 6f  r_code() functio
331d0 6e 20 63 68 61 6e 67 65 73 20 74 68 65 20 65 72  n changes the er
331e0 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 72 65 74 75  ror code.** retu
331f0 72 6e 65 64 20 62 79 20 53 51 4c 69 74 65 20 61  rned by SQLite a
33200 73 20 61 20 72 65 73 75 6c 74 20 6f 66 20 61 6e  s a result of an
33210 20 65 72 72 6f 72 20 69 6e 20 61 20 66 75 6e 63   error in a func
33220 74 69 6f 6e 2e 20 20 5e 42 79 20 64 65 66 61 75  tion.  ^By defau
33230 6c 74 2c 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72  lt,.** the error
33240 20 63 6f 64 65 20 69 73 20 53 51 4c 49 54 45 5f   code is SQLITE_
33250 45 52 52 4f 52 2e 20 20 5e 41 20 73 75 62 73 65  ERROR.  ^A subse
33260 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71  quent call to sq
33270 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
33280 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74  or().** or sqlit
33290 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
332a0 36 28 29 20 72 65 73 65 74 73 20 74 68 65 20 65  6() resets the e
332b0 72 72 6f 72 20 63 6f 64 65 20 74 6f 20 53 51 4c  rror code to SQL
332c0 49 54 45 5f 45 52 52 4f 52 2e 0a 2a 2a 0a 2a 2a  ITE_ERROR..**.**
332d0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
332e0 73 75 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69  sult_error_toobi
332f0 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 63 61  g() interface ca
33300 75 73 65 73 20 53 51 4c 69 74 65 20 74 6f 20 74  uses SQLite to t
33310 68 72 6f 77 20 61 6e 0a 2a 2a 20 65 72 72 6f 72  hrow an.** error
33320 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74   indicating that
33330 20 61 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f   a string or BLO
33340 42 20 69 73 20 74 6f 6f 20 6c 6f 6e 67 20 74 6f  B is too long to
33350 20 72 65 70 72 65 73 65 6e 74 2e 0a 2a 2a 0a 2a   represent..**.*
33360 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
33370 65 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65  esult_error_nome
33380 6d 28 29 20 69 6e 74 65 72 66 61 63 65 20 63 61  m() interface ca
33390 75 73 65 73 20 53 51 4c 69 74 65 20 74 6f 20 74  uses SQLite to t
333a0 68 72 6f 77 20 61 6e 0a 2a 2a 20 65 72 72 6f 72  hrow an.** error
333b0 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74   indicating that
333c0 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
333d0 74 69 6f 6e 20 66 61 69 6c 65 64 2e 0a 2a 2a 0a  tion failed..**.
333e0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
333f0 72 65 73 75 6c 74 5f 69 6e 74 28 29 20 69 6e 74  result_int() int
33400 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20  erface sets the 
33410 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20  return value.** 
33420 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  of the applicati
33430 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
33440 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 33 32  ion to be the 32
33450 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65  -bit signed inte
33460 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76  ger.** value giv
33470 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 20 61 72  en in the 2nd ar
33480 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20  gument..** ^The 
33490 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69  sqlite3_result_i
334a0 6e 74 36 34 28 29 20 69 6e 74 65 72 66 61 63 65  nt64() interface
334b0 20 73 65 74 73 20 74 68 65 20 72 65 74 75 72 6e   sets the return
334c0 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65   value.** of the
334d0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
334e0 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f  ined function to
334f0 20 62 65 20 74 68 65 20 36 34 2d 62 69 74 20 73   be the 64-bit s
33500 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a  igned integer.**
33510 20 76 61 6c 75 65 20 67 69 76 65 6e 20 69 6e 20   value given in 
33520 74 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74  the 2nd argument
33530 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
33540 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c  ite3_result_null
33550 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74  () interface set
33560 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  s the return val
33570 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70  ue.** of the app
33580 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
33590 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
335a0 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  NULL..**.** ^The
335b0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
335c0 74 65 78 74 28 29 2c 20 73 71 6c 69 74 65 33 5f  text(), sqlite3_
335d0 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28 29 2c  result_text16(),
335e0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75  .** sqlite3_resu
335f0 6c 74 5f 74 65 78 74 31 36 6c 65 28 29 2c 20 61  lt_text16le(), a
33600 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  nd sqlite3_resul
33610 74 5f 74 65 78 74 31 36 62 65 28 29 20 69 6e 74  t_text16be() int
33620 65 72 66 61 63 65 73 0a 2a 2a 20 73 65 74 20 74  erfaces.** set t
33630 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
33640 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  of the applicati
33650 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
33660 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 61 20 74  ion to be.** a t
33670 65 78 74 20 73 74 72 69 6e 67 20 77 68 69 63 68  ext string which
33680 20 69 73 20 72 65 70 72 65 73 65 6e 74 65 64 20   is represented 
33690 61 73 20 55 54 46 2d 38 2c 20 55 54 46 2d 31 36  as UTF-8, UTF-16
336a0 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
336b0 65 72 2c 0a 2a 2a 20 55 54 46 2d 31 36 20 6c 69  er,.** UTF-16 li
336c0 74 74 6c 65 20 65 6e 64 69 61 6e 2c 20 6f 72 20  ttle endian, or 
336d0 55 54 46 2d 31 36 20 62 69 67 20 65 6e 64 69 61  UTF-16 big endia
336e0 6e 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  n, respectively.
336f0 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 74 61 6b 65  .** ^SQLite take
33700 73 20 74 68 65 20 74 65 78 74 20 72 65 73 75 6c  s the text resul
33710 74 20 66 72 6f 6d 20 74 68 65 20 61 70 70 6c 69  t from the appli
33720 63 61 74 69 6f 6e 20 66 72 6f 6d 0a 2a 2a 20 74  cation from.** t
33730 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
33740 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f   of the sqlite3_
33750 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74  result_text* int
33760 65 72 66 61 63 65 73 2e 0a 2a 2a 20 5e 49 66 20  erfaces..** ^If 
33770 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65  the 3rd paramete
33780 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  r to the sqlite3
33790 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e  _result_text* in
337a0 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e  terfaces.** is n
337b0 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 53 51  egative, then SQ
337c0 4c 69 74 65 20 74 61 6b 65 73 20 72 65 73 75 6c  Lite takes resul
337d0 74 20 74 65 78 74 20 66 72 6f 6d 20 74 68 65 20  t text from the 
337e0 32 6e 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  2nd parameter.**
337f0 20 74 68 72 6f 75 67 68 20 74 68 65 20 66 69 72   through the fir
33800 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74 65  st zero characte
33810 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 33 72  r..** ^If the 3r
33820 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
33830 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
33840 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63  t_text* interfac
33850 65 73 0a 2a 2a 20 69 73 20 6e 6f 6e 2d 6e 65 67  es.** is non-neg
33860 61 74 69 76 65 2c 20 74 68 65 6e 20 61 73 20 6d  ative, then as m
33870 61 6e 79 20 62 79 74 65 73 20 28 6e 6f 74 20 63  any bytes (not c
33880 68 61 72 61 63 74 65 72 73 29 20 6f 66 20 74 68  haracters) of th
33890 65 20 74 65 78 74 0a 2a 2a 20 70 6f 69 6e 74 65  e text.** pointe
338a0 64 20 74 6f 20 62 79 20 74 68 65 20 32 6e 64 20  d to by the 2nd 
338b0 70 61 72 61 6d 65 74 65 72 20 61 72 65 20 74 61  parameter are ta
338c0 6b 65 6e 20 61 73 20 74 68 65 20 61 70 70 6c 69  ken as the appli
338d0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 0a 2a  cation-defined.*
338e0 2a 20 66 75 6e 63 74 69 6f 6e 20 72 65 73 75 6c  * function resul
338f0 74 2e 20 20 49 66 20 74 68 65 20 33 72 64 20 70  t.  If the 3rd p
33900 61 72 61 6d 65 74 65 72 20 69 73 20 6e 6f 6e 2d  arameter is non-
33910 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 69  negative, then i
33920 74 0a 2a 2a 20 6d 75 73 74 20 62 65 20 74 68 65  t.** must be the
33930 20 62 79 74 65 20 6f 66 66 73 65 74 20 69 6e 74   byte offset int
33940 6f 20 74 68 65 20 73 74 72 69 6e 67 20 77 68 65  o the string whe
33950 72 65 20 74 68 65 20 4e 55 4c 20 74 65 72 6d 69  re the NUL termi
33960 6e 61 74 6f 72 20 77 6f 75 6c 64 0a 2a 2a 20 61  nator would.** a
33970 70 70 65 61 72 20 69 66 20 74 68 65 20 73 74 72  ppear if the str
33980 69 6e 67 20 77 68 65 72 65 20 4e 55 4c 20 74 65  ing where NUL te
33990 72 6d 69 6e 61 74 65 64 2e 20 20 49 66 20 61 6e  rminated.  If an
339a0 79 20 4e 55 4c 20 63 68 61 72 61 63 74 65 72 73  y NUL characters
339b0 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65   occur.** in the
339c0 20 73 74 72 69 6e 67 20 61 74 20 61 20 62 79 74   string at a byt
339d0 65 20 6f 66 66 73 65 74 20 74 68 61 74 20 69 73  e offset that is
339e0 20 6c 65 73 73 20 74 68 61 6e 20 74 68 65 20 76   less than the v
339f0 61 6c 75 65 20 6f 66 20 74 68 65 20 33 72 64 0a  alue of the 3rd.
33a00 2a 2a 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68  ** parameter, th
33a10 65 6e 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67  en the resulting
33a20 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 63 6f 6e   string will con
33a30 74 61 69 6e 20 65 6d 62 65 64 64 65 64 20 4e 55  tain embedded NU
33a40 4c 73 20 61 6e 64 20 74 68 65 0a 2a 2a 20 72 65  Ls and the.** re
33a50 73 75 6c 74 20 6f 66 20 65 78 70 72 65 73 73 69  sult of expressi
33a60 6f 6e 73 20 6f 70 65 72 61 74 69 6e 67 20 6f 6e  ons operating on
33a70 20 73 74 72 69 6e 67 73 20 77 69 74 68 20 65 6d   strings with em
33a80 62 65 64 64 65 64 20 4e 55 4c 73 20 69 73 20 75  bedded NULs is u
33a90 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e 49 66  ndefined..** ^If
33aa0 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74   the 4th paramet
33ab0 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  er to the sqlite
33ac0 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69  3_result_text* i
33ad0 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20  nterfaces.** or 
33ae0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62  sqlite3_result_b
33af0 6c 6f 62 20 69 73 20 61 20 6e 6f 6e 2d 4e 55 4c  lob is a non-NUL
33b00 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20  L pointer, then 
33b10 53 51 4c 69 74 65 20 63 61 6c 6c 73 20 74 68 61  SQLite calls tha
33b20 74 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 61 73  t.** function as
33b30 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20   the destructor 
33b40 6f 6e 20 74 68 65 20 74 65 78 74 20 6f 72 20 42  on the text or B
33b50 4c 4f 42 20 72 65 73 75 6c 74 20 77 68 65 6e 20  LOB result when 
33b60 69 74 20 68 61 73 0a 2a 2a 20 66 69 6e 69 73 68  it has.** finish
33b70 65 64 20 75 73 69 6e 67 20 74 68 61 74 20 72 65  ed using that re
33b80 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  sult..** ^If the
33b90 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   4th parameter t
33ba0 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65  o the sqlite3_re
33bb0 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72  sult_text* inter
33bc0 66 61 63 65 73 20 6f 72 20 74 6f 0a 2a 2a 20 73  faces or to.** s
33bd0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c  qlite3_result_bl
33be0 6f 62 20 69 73 20 74 68 65 20 73 70 65 63 69 61  ob is the specia
33bf0 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54  l constant SQLIT
33c00 45 5f 53 54 41 54 49 43 2c 20 74 68 65 6e 20 53  E_STATIC, then S
33c10 51 4c 69 74 65 0a 2a 2a 20 61 73 73 75 6d 65 73  QLite.** assumes
33c20 20 74 68 61 74 20 74 68 65 20 74 65 78 74 20 6f   that the text o
33c30 72 20 42 4c 4f 42 20 72 65 73 75 6c 74 20 69 73  r BLOB result is
33c40 20 69 6e 20 63 6f 6e 73 74 61 6e 74 20 73 70 61   in constant spa
33c50 63 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 0a  ce and does not.
33c60 2a 2a 20 63 6f 70 79 20 74 68 65 20 63 6f 6e 74  ** copy the cont
33c70 65 6e 74 20 6f 66 20 74 68 65 20 70 61 72 61 6d  ent of the param
33c80 65 74 65 72 20 6e 6f 72 20 63 61 6c 6c 20 61 20  eter nor call a 
33c90 64 65 73 74 72 75 63 74 6f 72 20 6f 6e 20 74 68  destructor on th
33ca0 65 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20 77 68 65  e content.** whe
33cb0 6e 20 69 74 20 68 61 73 20 66 69 6e 69 73 68 65  n it has finishe
33cc0 64 20 75 73 69 6e 67 20 74 68 61 74 20 72 65 73  d using that res
33cd0 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ult..** ^If the 
33ce0 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  4th parameter to
33cf0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   the sqlite3_res
33d00 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66  ult_text* interf
33d10 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74  aces.** or sqlit
33d20 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69  e3_result_blob i
33d30 73 20 74 68 65 20 73 70 65 63 69 61 6c 20 63 6f  s the special co
33d40 6e 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 54 52  nstant SQLITE_TR
33d50 41 4e 53 49 45 4e 54 0a 2a 2a 20 74 68 65 6e 20  ANSIENT.** then 
33d60 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63  SQLite makes a c
33d70 6f 70 79 20 6f 66 20 74 68 65 20 72 65 73 75 6c  opy of the resul
33d80 74 20 69 6e 74 6f 20 73 70 61 63 65 20 6f 62 74  t into space obt
33d90 61 69 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 66 72  ained from.** fr
33da0 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
33db0 6f 63 28 29 5d 20 62 65 66 6f 72 65 20 69 74 20  oc()] before it 
33dc0 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e  returns..**.** ^
33dd0 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
33de0 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e 74 65 72  lt_value() inter
33df0 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65  face sets the re
33e00 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61  sult of.** the a
33e10 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
33e20 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
33e30 65 20 61 20 63 6f 70 79 20 74 68 65 0a 2a 2a 20  e a copy the.** 
33e40 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c  [unprotected sql
33e50 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
33e60 63 74 20 73 70 65 63 69 66 69 65 64 20 62 79 20  ct specified by 
33e70 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
33e80 72 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69  r.  ^The.** sqli
33e90 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65  te3_result_value
33ea0 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d 61 6b  () interface mak
33eb0 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  es a copy of the
33ec0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d   [sqlite3_value]
33ed0 0a 2a 2a 20 73 6f 20 74 68 61 74 20 74 68 65 20  .** so that the 
33ee0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20  [sqlite3_value] 
33ef0 73 70 65 63 69 66 69 65 64 20 69 6e 20 74 68 65  specified in the
33f00 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 63   parameter may c
33f10 68 61 6e 67 65 20 6f 72 0a 2a 2a 20 62 65 20 64  hange or.** be d
33f20 65 61 6c 6c 6f 63 61 74 65 64 20 61 66 74 65 72  eallocated after
33f30 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
33f40 76 61 6c 75 65 28 29 20 72 65 74 75 72 6e 73 20  value() returns 
33f50 77 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a  without harm..**
33f60 20 5e 41 20 5b 70 72 6f 74 65 63 74 65 64 20 73   ^A [protected s
33f70 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
33f80 6a 65 63 74 20 6d 61 79 20 61 6c 77 61 79 73 20  ject may always 
33f90 62 65 20 75 73 65 64 20 77 68 65 72 65 20 61 6e  be used where an
33fa0 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64  .** [unprotected
33fb0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
33fc0 6f 62 6a 65 63 74 20 69 73 20 72 65 71 75 69 72  object is requir
33fd0 65 64 2c 20 73 6f 20 65 69 74 68 65 72 0a 2a 2a  ed, so either.**
33fe0 20 6b 69 6e 64 20 6f 66 20 5b 73 71 6c 69 74 65   kind of [sqlite
33ff0 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
34000 63 61 6e 20 62 65 20 75 73 65 64 20 77 69 74 68  can be used with
34010 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e   this interface.
34020 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 73 65 20  .**.** If these 
34030 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c  routines are cal
34040 6c 65 64 20 66 72 6f 6d 20 77 69 74 68 69 6e 20  led from within 
34050 74 68 65 20 64 69 66 66 65 72 65 6e 74 20 74 68  the different th
34060 72 65 61 64 0a 2a 2a 20 74 68 61 6e 20 74 68 65  read.** than the
34070 20 6f 6e 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20   one containing 
34080 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
34090 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
340a0 20 74 68 61 74 20 72 65 63 65 69 76 65 64 0a 2a   that received.*
340b0 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  * the [sqlite3_c
340c0 6f 6e 74 65 78 74 5d 20 70 6f 69 6e 74 65 72 2c  ontext] pointer,
340d0 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
340e0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 76   undefined..*/.v
340f0 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
34100 6c 74 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f  lt_blob(sqlite3_
34110 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20  context*, const 
34120 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64  void*, int, void
34130 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69  (*)(void*));.voi
34140 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
34150 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f  _double(sqlite3_
34160 63 6f 6e 74 65 78 74 2a 2c 20 64 6f 75 62 6c 65  context*, double
34170 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
34180 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 73 71 6c  result_error(sql
34190 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63  ite3_context*, c
341a0 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 29  onst char*, int)
341b0 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
341c0 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 73 71  esult_error16(sq
341d0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
341e0 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
341f0 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
34200 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f  result_error_too
34210 62 69 67 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  big(sqlite3_cont
34220 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69  ext*);.void sqli
34230 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
34240 5f 6e 6f 6d 65 6d 28 73 71 6c 69 74 65 33 5f 63  _nomem(sqlite3_c
34250 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73  ontext*);.void s
34260 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
34270 72 6f 72 5f 63 6f 64 65 28 73 71 6c 69 74 65 33  ror_code(sqlite3
34280 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b  _context*, int);
34290 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
342a0 73 75 6c 74 5f 69 6e 74 28 73 71 6c 69 74 65 33  sult_int(sqlite3
342b0 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b  _context*, int);
342c0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
342d0 73 75 6c 74 5f 69 6e 74 36 34 28 73 71 6c 69 74  sult_int64(sqlit
342e0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c  e3_context*, sql
342f0 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 76 6f 69  ite3_int64);.voi
34300 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
34310 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 63 6f  _null(sqlite3_co
34320 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71  ntext*);.void sq
34330 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
34340 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  t(sqlite3_contex
34350 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c  t*, const char*,
34360 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f   int, void(*)(vo
34370 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69  id*));.void sqli
34380 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
34390 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  6(sqlite3_contex
343a0 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  t*, const void*,
343b0 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f   int, void(*)(vo
343c0 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69  id*));.void sqli
343d0 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
343e0 36 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  6le(sqlite3_cont
343f0 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64  ext*, const void
34400 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76  *, int,void(*)(v
34410 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c  oid*));.void sql
34420 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
34430 31 36 62 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e  16be(sqlite3_con
34440 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  text*, const voi
34450 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28  d*, int,void(*)(
34460 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71  void*));.void sq
34470 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c  lite3_result_val
34480 75 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ue(sqlite3_conte
34490 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c  xt*, sqlite3_val
344a0 75 65 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  ue*);.void sqlit
344b0 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c  e3_result_zerobl
344c0 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ob(sqlite3_conte
344d0 78 74 2a 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a  xt*, int n);../*
344e0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
344f0 66 69 6e 65 20 4e 65 77 20 43 6f 6c 6c 61 74 69  fine New Collati
34500 6e 67 20 53 65 71 75 65 6e 63 65 73 0a 2a 2a 0a  ng Sequences.**.
34510 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69  ** ^These functi
34520 6f 6e 73 20 61 64 64 2c 20 72 65 6d 6f 76 65 2c  ons add, remove,
34530 20 6f 72 20 6d 6f 64 69 66 79 20 61 20 5b 63 6f   or modify a [co
34540 6c 6c 61 74 69 6f 6e 5d 20 61 73 73 6f 63 69 61  llation] associa
34550 74 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  ted.** with the 
34560 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
34570 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20  tion] specified 
34580 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67  as the first arg
34590 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ument..**.** ^Th
345a0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 6f  e name of the co
345b0 6c 6c 61 74 69 6f 6e 20 69 73 20 61 20 55 54 46  llation is a UTF
345c0 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 66 6f 72  -8 string.** for
345d0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
345e0 63 6f 6c 6c 61 74 69 6f 6e 28 29 20 61 6e 64 20  collation() and 
345f0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
34600 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 0a 2a 2a  ollation_v2().**
34610 20 61 6e 64 20 61 20 55 54 46 2d 31 36 20 73 74   and a UTF-16 st
34620 72 69 6e 67 20 69 6e 20 6e 61 74 69 76 65 20 62  ring in native b
34630 79 74 65 20 6f 72 64 65 72 20 66 6f 72 20 73 71  yte order for sq
34640 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
34650 6c 61 74 69 6f 6e 31 36 28 29 2e 0a 2a 2a 20 5e  lation16()..** ^
34660 43 6f 6c 6c 61 74 69 6f 6e 20 6e 61 6d 65 73 20  Collation names 
34670 74 68 61 74 20 63 6f 6d 70 61 72 65 20 65 71 75  that compare equ
34680 61 6c 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20  al according to 
34690 5b 73 71 6c 69 74 65 33 5f 73 74 72 6e 69 63 6d  [sqlite3_strnicm
346a0 70 28 29 5d 20 61 72 65 0a 2a 2a 20 63 6f 6e 73  p()] are.** cons
346b0 69 64 65 72 65 64 20 74 6f 20 62 65 20 74 68 65  idered to be the
346c0 20 73 61 6d 65 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a   same name..**.*
346d0 2a 20 5e 28 54 68 65 20 74 68 69 72 64 20 61 72  * ^(The third ar
346e0 67 75 6d 65 6e 74 20 28 65 54 65 78 74 52 65 70  gument (eTextRep
346f0 29 20 6d 75 73 74 20 62 65 20 6f 6e 65 20 6f 66  ) must be one of
34700 20 74 68 65 20 63 6f 6e 73 74 61 6e 74 73 3a 0a   the constants:.
34710 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
34720 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 0a 2a  [SQLITE_UTF8],.*
34730 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55  * <li> [SQLITE_U
34740 54 46 31 36 4c 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e  TF16LE],.** <li>
34750 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45   [SQLITE_UTF16BE
34760 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  ],.** <li> [SQLI
34770 54 45 5f 55 54 46 31 36 5d 2c 20 6f 72 0a 2a 2a  TE_UTF16], or.**
34780 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54   <li> [SQLITE_UT
34790 46 31 36 5f 41 4c 49 47 4e 45 44 5d 2e 0a 2a 2a  F16_ALIGNED]..**
347a0 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 54 68 65   </ul>)^.** ^The
347b0 20 65 54 65 78 74 52 65 70 20 61 72 67 75 6d 65   eTextRep argume
347c0 6e 74 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68  nt determines th
347d0 65 20 65 6e 63 6f 64 69 6e 67 20 6f 66 20 73 74  e encoding of st
347e0 72 69 6e 67 73 20 70 61 73 73 65 64 0a 2a 2a 20  rings passed.** 
347f0 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67  to the collating
34800 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61   function callba
34810 63 6b 2c 20 78 43 61 6c 6c 62 61 63 6b 2e 0a 2a  ck, xCallback..*
34820 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 55  * ^The [SQLITE_U
34830 54 46 31 36 5d 20 61 6e 64 20 5b 53 51 4c 49 54  TF16] and [SQLIT
34840 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d  E_UTF16_ALIGNED]
34850 20 76 61 6c 75 65 73 20 66 6f 72 20 65 54 65 78   values for eTex
34860 74 52 65 70 0a 2a 2a 20 66 6f 72 63 65 20 73 74  tRep.** force st
34870 72 69 6e 67 73 20 74 6f 20 62 65 20 55 54 46 31  rings to be UTF1
34880 36 20 77 69 74 68 20 6e 61 74 69 76 65 20 62 79  6 with native by
34890 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 20 5e 54 68  te order..** ^Th
348a0 65 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5f  e [SQLITE_UTF16_
348b0 41 4c 49 47 4e 45 44 5d 20 76 61 6c 75 65 20 66  ALIGNED] value f
348c0 6f 72 20 65 54 65 78 74 52 65 70 20 66 6f 72 63  or eTextRep forc
348d0 65 73 20 73 74 72 69 6e 67 73 20 74 6f 20 62 65  es strings to be
348e0 67 69 6e 0a 2a 2a 20 6f 6e 20 61 6e 20 65 76 65  gin.** on an eve
348f0 6e 20 62 79 74 65 20 61 64 64 72 65 73 73 2e 0a  n byte address..
34900 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74  **.** ^The fourt
34910 68 20 61 72 67 75 6d 65 6e 74 2c 20 70 41 72 67  h argument, pArg
34920 2c 20 69 73 20 61 6e 20 61 70 70 6c 69 63 61 74  , is an applicat
34930 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72  ion data pointer
34940 20 74 68 61 74 20 69 73 20 70 61 73 73 65 64 0a   that is passed.
34950 2a 2a 20 74 68 72 6f 75 67 68 20 61 73 20 74 68  ** through as th
34960 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
34970 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e   to the collatin
34980 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62  g function callb
34990 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ack..**.** ^The 
349a0 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 2c 20  fifth argument, 
349b0 78 43 61 6c 6c 62 61 63 6b 2c 20 69 73 20 61 20  xCallback, is a 
349c0 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 63  pointer to the c
349d0 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
349e0 6e 2e 0a 2a 2a 20 5e 4d 75 6c 74 69 70 6c 65 20  n..** ^Multiple 
349f0 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
34a00 6f 6e 73 20 63 61 6e 20 62 65 20 72 65 67 69 73  ons can be regis
34a10 74 65 72 65 64 20 75 73 69 6e 67 20 74 68 65 20  tered using the 
34a20 73 61 6d 65 20 6e 61 6d 65 20 62 75 74 0a 2a 2a  same name but.**
34a30 20 77 69 74 68 20 64 69 66 66 65 72 65 6e 74 20   with different 
34a40 65 54 65 78 74 52 65 70 20 70 61 72 61 6d 65 74  eTextRep paramet
34a50 65 72 73 20 61 6e 64 20 53 51 4c 69 74 65 20 77  ers and SQLite w
34a60 69 6c 6c 20 75 73 65 20 77 68 69 63 68 65 76 65  ill use whicheve
34a70 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 72 65  r.** function re
34a80 71 75 69 72 65 73 20 74 68 65 20 6c 65 61 73 74  quires the least
34a90 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74 61 20   amount of data 
34aa0 74 72 61 6e 73 66 6f 72 6d 61 74 69 6f 6e 2e 0a  transformation..
34ab0 2a 2a 20 5e 49 66 20 74 68 65 20 78 43 61 6c 6c  ** ^If the xCall
34ac0 62 61 63 6b 20 61 72 67 75 6d 65 6e 74 20 69 73  back argument is
34ad0 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65 20 63   NULL then the c
34ae0 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
34af0 6e 20 69 73 0a 2a 2a 20 64 65 6c 65 74 65 64 2e  n is.** deleted.
34b00 20 20 5e 57 68 65 6e 20 61 6c 6c 20 63 6f 6c 6c    ^When all coll
34b10 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20  ating functions 
34b20 68 61 76 69 6e 67 20 74 68 65 20 73 61 6d 65 20  having the same 
34b30 6e 61 6d 65 20 61 72 65 20 64 65 6c 65 74 65 64  name are deleted
34b40 2c 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 6c 61 74  ,.** that collat
34b50 69 6f 6e 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72  ion is no longer
34b60 20 75 73 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e   usable..**.** ^
34b70 54 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75  The collating fu
34b80 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 20  nction callback 
34b90 69 73 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20  is invoked with 
34ba0 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 70 41  a copy of the pA
34bb0 72 67 20 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69  rg .** applicati
34bc0 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 20  on data pointer 
34bd0 61 6e 64 20 77 69 74 68 20 74 77 6f 20 73 74 72  and with two str
34be0 69 6e 67 73 20 69 6e 20 74 68 65 20 65 6e 63 6f  ings in the enco
34bf0 64 69 6e 67 20 73 70 65 63 69 66 69 65 64 0a 2a  ding specified.*
34c00 2a 20 62 79 20 74 68 65 20 65 54 65 78 74 52 65  * by the eTextRe
34c10 70 20 61 72 67 75 6d 65 6e 74 2e 20 20 54 68 65  p argument.  The
34c20 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
34c30 69 6f 6e 20 6d 75 73 74 20 72 65 74 75 72 6e 20  ion must return 
34c40 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20 74 68  an.** integer th
34c50 61 74 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20  at is negative, 
34c60 7a 65 72 6f 2c 20 6f 72 20 70 6f 73 69 74 69 76  zero, or positiv
34c70 65 0a 2a 2a 20 69 66 20 74 68 65 20 66 69 72 73  e.** if the firs
34c80 74 20 73 74 72 69 6e 67 20 69 73 20 6c 65 73 73  t string is less
34c90 20 74 68 61 6e 2c 20 65 71 75 61 6c 20 74 6f 2c   than, equal to,
34ca0 20 6f 72 20 67 72 65 61 74 65 72 20 74 68 61 6e   or greater than
34cb0 20 74 68 65 20 73 65 63 6f 6e 64 2c 0a 2a 2a 20   the second,.** 
34cc0 72 65 73 70 65 63 74 69 76 65 6c 79 2e 20 20 41  respectively.  A
34cd0 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
34ce0 69 6f 6e 20 6d 75 73 74 20 61 6c 77 61 79 73 20  ion must always 
34cf0 72 65 74 75 72 6e 20 74 68 65 20 73 61 6d 65 20  return the same 
34d00 61 6e 73 77 65 72 0a 2a 2a 20 67 69 76 65 6e 20  answer.** given 
34d10 74 68 65 20 73 61 6d 65 20 69 6e 70 75 74 73 2e  the same inputs.
34d20 20 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65    If two or more
34d30 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
34d40 69 6f 6e 73 20 61 72 65 20 72 65 67 69 73 74 65  ions are registe
34d50 72 65 64 0a 2a 2a 20 74 6f 20 74 68 65 20 73 61  red.** to the sa
34d60 6d 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 6e 61 6d  me collation nam
34d70 65 20 28 75 73 69 6e 67 20 64 69 66 66 65 72 65  e (using differe
34d80 6e 74 20 65 54 65 78 74 52 65 70 20 76 61 6c 75  nt eTextRep valu
34d90 65 73 29 20 74 68 65 6e 20 61 6c 6c 0a 2a 2a 20  es) then all.** 
34da0 6d 75 73 74 20 67 69 76 65 20 61 6e 20 65 71 75  must give an equ
34db0 69 76 61 6c 65 6e 74 20 61 6e 73 77 65 72 20 77  ivalent answer w
34dc0 68 65 6e 20 69 6e 76 6f 6b 65 64 20 77 69 74 68  hen invoked with
34dd0 20 65 71 75 69 76 61 6c 65 6e 74 20 73 74 72 69   equivalent stri
34de0 6e 67 73 2e 0a 2a 2a 20 54 68 65 20 63 6f 6c 6c  ngs..** The coll
34df0 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d  ating function m
34e00 75 73 74 20 6f 62 65 79 20 74 68 65 20 66 6f 6c  ust obey the fol
34e10 6c 6f 77 69 6e 67 20 70 72 6f 70 65 72 74 69 65  lowing propertie
34e20 73 20 66 6f 72 20 61 6c 6c 0a 2a 2a 20 73 74 72  s for all.** str
34e30 69 6e 67 73 20 41 2c 20 42 2c 20 61 6e 64 20 43  ings A, B, and C
34e40 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20  :.**.** <ol>.** 
34e50 3c 6c 69 3e 20 49 66 20 41 3d 3d 42 20 74 68 65  <li> If A==B the
34e60 6e 20 42 3d 3d 41 2e 0a 2a 2a 20 3c 6c 69 3e 20  n B==A..** <li> 
34e70 49 66 20 41 3d 3d 42 20 61 6e 64 20 42 3d 3d 43  If A==B and B==C
34e80 20 74 68 65 6e 20 41 3d 3d 43 2e 0a 2a 2a 20 3c   then A==C..** <
34e90 6c 69 3e 20 49 66 20 41 26 6c 74 3b 42 20 54 48  li> If A&lt;B TH
34ea0 45 4e 20 42 26 67 74 3b 41 2e 0a 2a 2a 20 3c 6c  EN B&gt;A..** <l
34eb0 69 3e 20 49 66 20 41 26 6c 74 3b 42 20 61 6e 64  i> If A&lt;B and
34ec0 20 42 26 6c 74 3b 43 20 74 68 65 6e 20 41 26 6c   B&lt;C then A&l
34ed0 74 3b 43 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a  t;C..** </ol>.**
34ee0 0a 2a 2a 20 49 66 20 61 20 63 6f 6c 6c 61 74 69  .** If a collati
34ef0 6e 67 20 66 75 6e 63 74 69 6f 6e 20 66 61 69 6c  ng function fail
34f00 73 20 61 6e 79 20 6f 66 20 74 68 65 20 61 62 6f  s any of the abo
34f10 76 65 20 63 6f 6e 73 74 72 61 69 6e 74 73 20 61  ve constraints a
34f20 6e 64 20 74 68 61 74 0a 2a 2a 20 63 6f 6c 6c 61  nd that.** colla
34f30 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73  ting function is
34f40 20 20 72 65 67 69 73 74 65 72 65 64 20 61 6e 64    registered and
34f50 20 75 73 65 64 2c 20 74 68 65 6e 20 74 68 65 20   used, then the 
34f60 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69  behavior of SQLi
34f70 74 65 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e  te.** is undefin
34f80 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ed..**.** ^The s
34f90 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
34fa0 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 77 6f 72  llation_v2() wor
34fb0 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f  ks like sqlite3_
34fc0 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
34fd0 28 29 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 61  ().** with the a
34fe0 64 64 69 74 69 6f 6e 20 74 68 61 74 20 74 68 65  ddition that the
34ff0 20 78 44 65 73 74 72 6f 79 20 63 61 6c 6c 62 61   xDestroy callba
35000 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e  ck is invoked on
35010 20 70 41 72 67 20 77 68 65 6e 0a 2a 2a 20 74 68   pArg when.** th
35020 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63  e collating func
35030 74 69 6f 6e 20 69 73 20 64 65 6c 65 74 65 64 2e  tion is deleted.
35040 0a 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6e 67 20 66  .** ^Collating f
35050 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 64 65 6c  unctions are del
35060 65 74 65 64 20 77 68 65 6e 20 74 68 65 79 20 61  eted when they a
35070 72 65 20 6f 76 65 72 72 69 64 64 65 6e 20 62 79  re overridden by
35080 20 6c 61 74 65 72 0a 2a 2a 20 63 61 6c 6c 73 20   later.** calls 
35090 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e  to the collation
350a0 20 63 72 65 61 74 69 6f 6e 20 66 75 6e 63 74 69   creation functi
350b0 6f 6e 73 20 6f 72 20 77 68 65 6e 20 74 68 65 0a  ons or when the.
350c0 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
350d0 6e 65 63 74 69 6f 6e 5d 20 69 73 20 63 6c 6f 73  nection] is clos
350e0 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
350f0 33 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 0a 2a  3_close()]..**.*
35100 2a 20 5e 54 68 65 20 78 44 65 73 74 72 6f 79 20  * ^The xDestroy 
35110 63 61 6c 6c 62 61 63 6b 20 69 73 20 3c 75 3e 6e  callback is <u>n
35120 6f 74 3c 2f 75 3e 20 63 61 6c 6c 65 64 20 69 66  ot</u> called if
35130 20 74 68 65 20 0a 2a 2a 20 73 71 6c 69 74 65 33   the .** sqlite3
35140 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
35150 6e 5f 76 32 28 29 20 66 75 6e 63 74 69 6f 6e 20  n_v2() function 
35160 66 61 69 6c 73 2e 20 20 41 70 70 6c 69 63 61 74  fails.  Applicat
35170 69 6f 6e 73 20 74 68 61 74 20 69 6e 76 6f 6b 65  ions that invoke
35180 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61  .** sqlite3_crea
35190 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28  te_collation_v2(
351a0 29 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c  ) with a non-NUL
351b0 4c 20 78 44 65 73 74 72 6f 79 20 61 72 67 75 6d  L xDestroy argum
351c0 65 6e 74 20 73 68 6f 75 6c 64 20 0a 2a 2a 20 63  ent should .** c
351d0 68 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20  heck the return 
351e0 63 6f 64 65 20 61 6e 64 20 64 69 73 70 6f 73 65  code and dispose
351f0 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74   of the applicat
35200 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72  ion data pointer
35210 0a 2a 2a 20 74 68 65 6d 73 65 6c 76 65 73 20 72  .** themselves r
35220 61 74 68 65 72 20 74 68 61 6e 20 65 78 70 65 63  ather than expec
35230 74 69 6e 67 20 53 51 4c 69 74 65 20 74 6f 20 64  ting SQLite to d
35240 65 61 6c 20 77 69 74 68 20 69 74 20 66 6f 72 20  eal with it for 
35250 74 68 65 6d 2e 0a 2a 2a 20 54 68 69 73 20 69 73  them..** This is
35260 20 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20   different from 
35270 65 76 65 72 79 20 6f 74 68 65 72 20 53 51 4c 69  every other SQLi
35280 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20 54  te interface.  T
35290 68 65 20 69 6e 63 6f 6e 73 69 73 74 65 6e 63 79  he inconsistency
352a0 20 0a 2a 2a 20 69 73 20 75 6e 66 6f 72 74 75 6e   .** is unfortun
352b0 61 74 65 20 62 75 74 20 63 61 6e 6e 6f 74 20 62  ate but cannot b
352c0 65 20 63 68 61 6e 67 65 64 20 77 69 74 68 6f 75  e changed withou
352d0 74 20 62 72 65 61 6b 69 6e 67 20 62 61 63 6b 77  t breaking backw
352e0 61 72 64 73 20 0a 2a 2a 20 63 6f 6d 70 61 74 69  ards .** compati
352f0 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 53 65  bility..**.** Se
35300 65 20 61 6c 73 6f 3a 20 20 5b 73 71 6c 69 74 65  e also:  [sqlite
35310 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
35320 65 64 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  ed()] and [sqlit
35330 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
35340 64 65 64 31 36 28 29 5d 2e 0a 2a 2f 0a 69 6e 74  ded16()]..*/.int
35350 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
35360 63 6f 6c 6c 61 74 69 6f 6e 28 0a 20 20 73 71 6c  collation(.  sql
35370 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20  ite3*, .  const 
35380 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20  char *zName, .  
35390 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20  int eTextRep, . 
353a0 20 76 6f 69 64 20 2a 70 41 72 67 2c 0a 20 20 69   void *pArg,.  i
353b0 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f  nt(*xCompare)(vo
353c0 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f  id*,int,const vo
353d0 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f  id*,int,const vo
353e0 69 64 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  id*).);.int sqli
353f0 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
35400 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74  tion_v2(.  sqlit
35410 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68  e3*, .  const ch
35420 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e  ar *zName, .  in
35430 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76  t eTextRep, .  v
35440 6f 69 64 20 2a 70 41 72 67 2c 0a 20 20 69 6e 74  oid *pArg,.  int
35450 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64  (*xCompare)(void
35460 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64  *,int,const void
35470 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64  *,int,const void
35480 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65 73  *),.  void(*xDes
35490 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a  troy)(void*).);.
354a0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61  int sqlite3_crea
354b0 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 0a  te_collation16(.
354c0 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63    sqlite3*, .  c
354d0 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 4e 61 6d 65  onst void *zName
354e0 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70  ,.  int eTextRep
354f0 2c 20 0a 20 20 76 6f 69 64 20 2a 70 41 72 67 2c  , .  void *pArg,
35500 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65  .  int(*xCompare
35510 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  )(void*,int,cons
35520 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  t void*,int,cons
35530 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a  t void*).);../*.
35540 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c  ** CAPI3REF: Col
35550 6c 61 74 69 6f 6e 20 4e 65 65 64 65 64 20 43 61  lation Needed Ca
35560 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54  llbacks.**.** ^T
35570 6f 20 61 76 6f 69 64 20 68 61 76 69 6e 67 20 74  o avoid having t
35580 6f 20 72 65 67 69 73 74 65 72 20 61 6c 6c 20 63  o register all c
35590 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63  ollation sequenc
355a0 65 73 20 62 65 66 6f 72 65 20 61 20 64 61 74 61  es before a data
355b0 62 61 73 65 0a 2a 2a 20 63 61 6e 20 62 65 20 75  base.** can be u
355c0 73 65 64 2c 20 61 20 73 69 6e 67 6c 65 20 63 61  sed, a single ca
355d0 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
355e0 6d 61 79 20 62 65 20 72 65 67 69 73 74 65 72 65  may be registere
355f0 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 64  d with the.** [d
35600 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
35610 6f 6e 5d 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65  on] to be invoke
35620 64 20 77 68 65 6e 65 76 65 72 20 61 6e 20 75 6e  d whenever an un
35630 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f  defined collatio
35640 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 69 73  n.** sequence is
35650 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a   required..**.**
35660 20 5e 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f   ^If the functio
35670 6e 20 69 73 20 72 65 67 69 73 74 65 72 65 64 20  n is registered 
35680 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65  using the sqlite
35690 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
356a0 65 64 28 29 20 41 50 49 2c 0a 2a 2a 20 74 68 65  ed() API,.** the
356b0 6e 20 69 74 20 69 73 20 70 61 73 73 65 64 20 74  n it is passed t
356c0 68 65 20 6e 61 6d 65 73 20 6f 66 20 75 6e 64 65  he names of unde
356d0 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20  fined collation 
356e0 73 65 71 75 65 6e 63 65 73 20 61 73 20 73 74 72  sequences as str
356f0 69 6e 67 73 0a 2a 2a 20 65 6e 63 6f 64 65 64 20  ings.** encoded 
35700 69 6e 20 55 54 46 2d 38 2e 20 5e 49 66 20 73 71  in UTF-8. ^If sq
35710 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  lite3_collation_
35720 6e 65 65 64 65 64 31 36 28 29 20 69 73 20 75 73  needed16() is us
35730 65 64 2c 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 73  ed,.** the names
35740 20 61 72 65 20 70 61 73 73 65 64 20 61 73 20 55   are passed as U
35750 54 46 2d 31 36 20 69 6e 20 6d 61 63 68 69 6e 65  TF-16 in machine
35760 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
35770 65 72 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74  er..** ^A call t
35780 6f 20 65 69 74 68 65 72 20 66 75 6e 63 74 69 6f  o either functio
35790 6e 20 72 65 70 6c 61 63 65 73 20 74 68 65 20 65  n replaces the e
357a0 78 69 73 74 69 6e 67 20 63 6f 6c 6c 61 74 69 6f  xisting collatio
357b0 6e 2d 6e 65 65 64 65 64 20 63 61 6c 6c 62 61 63  n-needed callbac
357c0 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 28 57 68 65 6e 20  k..**.** ^(When 
357d0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  the callback is 
357e0 69 6e 76 6f 6b 65 64 2c 20 74 68 65 20 66 69 72  invoked, the fir
357f0 73 74 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73  st argument pass
35800 65 64 20 69 73 20 61 20 63 6f 70 79 0a 2a 2a 20  ed is a copy.** 
35810 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  of the second ar
35820 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
35830 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
35840 65 64 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74  ed() or.** sqlit
35850 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
35860 64 65 64 31 36 28 29 2e 20 20 54 68 65 20 73 65  ded16().  The se
35870 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73  cond argument is
35880 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   the database.**
35890 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 54 68   connection.  Th
358a0 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
358b0 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49   is one of [SQLI
358c0 54 45 5f 55 54 46 38 5d 2c 20 5b 53 51 4c 49 54  TE_UTF8], [SQLIT
358d0 45 5f 55 54 46 31 36 42 45 5d 2c 0a 2a 2a 20 6f  E_UTF16BE],.** o
358e0 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c  r [SQLITE_UTF16L
358f0 45 5d 2c 20 69 6e 64 69 63 61 74 69 6e 67 20 74  E], indicating t
35900 68 65 20 6d 6f 73 74 20 64 65 73 69 72 61 62 6c  he most desirabl
35910 65 20 66 6f 72 6d 20 6f 66 20 74 68 65 20 63 6f  e form of the co
35920 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65  llation.** seque
35930 6e 63 65 20 66 75 6e 63 74 69 6f 6e 20 72 65 71  nce function req
35940 75 69 72 65 64 2e 20 20 54 68 65 20 66 6f 75 72  uired.  The four
35950 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  th parameter is 
35960 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a  the name of the.
35970 2a 2a 20 72 65 71 75 69 72 65 64 20 63 6f 6c 6c  ** required coll
35980 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 2e 29  ation sequence.)
35990 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c  ^.**.** The call
359a0 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 73 68  back function sh
359b0 6f 75 6c 64 20 72 65 67 69 73 74 65 72 20 74 68  ould register th
359c0 65 20 64 65 73 69 72 65 64 20 63 6f 6c 6c 61 74  e desired collat
359d0 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71  ion using.** [sq
359e0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
359f0 6c 61 74 69 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69  lation()], [sqli
35a00 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
35a10 74 69 6f 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a  tion16()], or.**
35a20 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
35a30 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 5d  _collation_v2()]
35a40 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
35a50 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
35a60 64 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a  d(.  sqlite3*, .
35a70 20 20 76 6f 69 64 2a 2c 20 0a 20 20 76 6f 69 64    void*, .  void
35a80 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65  (*)(void*,sqlite
35a90 33 2a 2c 69 6e 74 20 65 54 65 78 74 52 65 70 2c  3*,int eTextRep,
35aa0 63 6f 6e 73 74 20 63 68 61 72 2a 29 0a 29 3b 0a  const char*).);.
35ab0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c  int sqlite3_coll
35ac0 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 0a  ation_needed16(.
35ad0 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76    sqlite3*, .  v
35ae0 6f 69 64 2a 2c 0a 20 20 76 6f 69 64 28 2a 29 28  oid*,.  void(*)(
35af0 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69  void*,sqlite3*,i
35b00 6e 74 20 65 54 65 78 74 52 65 70 2c 63 6f 6e 73  nt eTextRep,cons
35b10 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 23 69 66  t void*).);..#if
35b20 64 65 66 20 53 51 4c 49 54 45 5f 48 41 53 5f 43  def SQLITE_HAS_C
35b30 4f 44 45 43 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69  ODEC./*.** Speci
35b40 66 79 20 74 68 65 20 6b 65 79 20 66 6f 72 20 61  fy the key for a
35b50 6e 20 65 6e 63 72 79 70 74 65 64 20 64 61 74 61  n encrypted data
35b60 62 61 73 65 2e 20 20 54 68 69 73 20 72 6f 75 74  base.  This rout
35b70 69 6e 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a  ine should be.**
35b80 20 63 61 6c 6c 65 64 20 72 69 67 68 74 20 61 66   called right af
35b90 74 65 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ter sqlite3_open
35ba0 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f  ()..**.** The co
35bb0 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20  de to implement 
35bc0 74 68 69 73 20 41 50 49 20 69 73 20 6e 6f 74 20  this API is not 
35bd0 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 65  available in the
35be0 20 70 75 62 6c 69 63 20 72 65 6c 65 61 73 65 0a   public release.
35bf0 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f  ** of SQLite..*/
35c00 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6b 65 79  .int sqlite3_key
35c10 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
35c20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
35c30 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74     /* Database t
35c40 6f 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a  o be rekeyed */.
35c50 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b    const void *pK
35c60 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20  ey, int nKey    
35c70 20 2f 2a 20 54 68 65 20 6b 65 79 20 2a 2f 0a 29   /* The key */.)
35c80 3b 0a 0a 2f 2a 0a 2a 2a 20 43 68 61 6e 67 65 20  ;../*.** Change 
35c90 74 68 65 20 6b 65 79 20 6f 6e 20 61 6e 20 6f 70  the key on an op
35ca0 65 6e 20 64 61 74 61 62 61 73 65 2e 20 20 49 66  en database.  If
35cb0 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 61 74   the current dat
35cc0 61 62 61 73 65 20 69 73 20 6e 6f 74 0a 2a 2a 20  abase is not.** 
35cd0 65 6e 63 72 79 70 74 65 64 2c 20 74 68 69 73 20  encrypted, this 
35ce0 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20 65 6e 63  routine will enc
35cf0 72 79 70 74 20 69 74 2e 20 20 49 66 20 70 4e 65  rypt it.  If pNe
35d00 77 3d 3d 30 20 6f 72 20 6e 4e 65 77 3d 3d 30 2c  w==0 or nNew==0,
35d10 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
35d20 20 69 73 20 64 65 63 72 79 70 74 65 64 2e 0a 2a   is decrypted..*
35d30 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 74 6f  *.** The code to
35d40 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73 20   implement this 
35d50 41 50 49 20 69 73 20 6e 6f 74 20 61 76 61 69 6c  API is not avail
35d60 61 62 6c 65 20 69 6e 20 74 68 65 20 70 75 62 6c  able in the publ
35d70 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66  ic release.** of
35d80 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20   SQLite..*/.int 
35d90 73 71 6c 69 74 65 33 5f 72 65 6b 65 79 28 0a 20  sqlite3_rekey(. 
35da0 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
35db0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
35dc0 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20 62  /* Database to b
35dd0 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63  e rekeyed */.  c
35de0 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c  onst void *pKey,
35df0 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a   int nKey     /*
35e00 20 54 68 65 20 6e 65 77 20 6b 65 79 20 2a 2f 0a   The new key */.
35e10 29 3b 0a 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66  );../*.** Specif
35e20 79 20 74 68 65 20 61 63 74 69 76 61 74 69 6f 6e  y the activation
35e30 20 6b 65 79 20 66 6f 72 20 61 20 53 45 45 20 64   key for a SEE d
35e40 61 74 61 62 61 73 65 2e 20 20 55 6e 6c 65 73 73  atabase.  Unless
35e50 20 0a 2a 2a 20 61 63 74 69 76 61 74 65 64 2c 20   .** activated, 
35e60 6e 6f 6e 65 20 6f 66 20 74 68 65 20 53 45 45 20  none of the SEE 
35e70 72 6f 75 74 69 6e 65 73 20 77 69 6c 6c 20 77 6f  routines will wo
35e80 72 6b 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69  rk..*/.void sqli
35e90 74 65 33 5f 61 63 74 69 76 61 74 65 5f 73 65 65  te3_activate_see
35ea0 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  (.  const char *
35eb0 7a 50 61 73 73 50 68 72 61 73 65 20 20 20 20 20  zPassPhrase     
35ec0 20 20 20 2f 2a 20 41 63 74 69 76 61 74 69 6f 6e     /* Activation
35ed0 20 70 68 72 61 73 65 20 2a 2f 0a 29 3b 0a 23 65   phrase */.);.#e
35ee0 6e 64 69 66 0a 0a 23 69 66 64 65 66 20 53 51 4c  ndif..#ifdef SQL
35ef0 49 54 45 5f 45 4e 41 42 4c 45 5f 43 45 52 4f 44  ITE_ENABLE_CEROD
35f00 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20 74  ./*.** Specify t
35f10 68 65 20 61 63 74 69 76 61 74 69 6f 6e 20 6b 65  he activation ke
35f20 79 20 66 6f 72 20 61 20 43 45 52 4f 44 20 64 61  y for a CEROD da
35f30 74 61 62 61 73 65 2e 20 20 55 6e 6c 65 73 73 20  tabase.  Unless 
35f40 0a 2a 2a 20 61 63 74 69 76 61 74 65 64 2c 20 6e  .** activated, n
35f50 6f 6e 65 20 6f 66 20 74 68 65 20 43 45 52 4f 44  one of the CEROD
35f60 20 72 6f 75 74 69 6e 65 73 20 77 69 6c 6c 20 77   routines will w
35f70 6f 72 6b 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c  ork..*/.void sql
35f80 69 74 65 33 5f 61 63 74 69 76 61 74 65 5f 63 65  ite3_activate_ce
35f90 72 6f 64 28 0a 20 20 63 6f 6e 73 74 20 63 68 61  rod(.  const cha
35fa0 72 20 2a 7a 50 61 73 73 50 68 72 61 73 65 20 20  r *zPassPhrase  
35fb0 20 20 20 20 20 20 2f 2a 20 41 63 74 69 76 61 74        /* Activat
35fc0 69 6f 6e 20 70 68 72 61 73 65 20 2a 2f 0a 29 3b  ion phrase */.);
35fd0 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43  .#endif../*.** C
35fe0 41 50 49 33 52 45 46 3a 20 53 75 73 70 65 6e 64  API3REF: Suspend
35ff0 20 45 78 65 63 75 74 69 6f 6e 20 46 6f 72 20 41   Execution For A
36000 20 53 68 6f 72 74 20 54 69 6d 65 0a 2a 2a 0a 2a   Short Time.**.*
36010 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6c  * The sqlite3_sl
36020 65 65 70 28 29 20 66 75 6e 63 74 69 6f 6e 20 63  eep() function c
36030 61 75 73 65 73 20 74 68 65 20 63 75 72 72 65 6e  auses the curren
36040 74 20 74 68 72 65 61 64 20 74 6f 20 73 75 73 70  t thread to susp
36050 65 6e 64 20 65 78 65 63 75 74 69 6f 6e 0a 2a 2a  end execution.**
36060 20 66 6f 72 20 61 74 20 6c 65 61 73 74 20 61 20   for at least a 
36070 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73  number of millis
36080 65 63 6f 6e 64 73 20 73 70 65 63 69 66 69 65 64  econds specified
36090 20 69 6e 20 69 74 73 20 70 61 72 61 6d 65 74 65   in its paramete
360a0 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  r..**.** If the 
360b0 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
360c0 20 64 6f 65 73 20 6e 6f 74 20 73 75 70 70 6f 72   does not suppor
360d0 74 20 73 6c 65 65 70 20 72 65 71 75 65 73 74 73  t sleep requests
360e0 20 77 69 74 68 0a 2a 2a 20 6d 69 6c 6c 69 73 65   with.** millise
360f0 63 6f 6e 64 20 74 69 6d 65 20 72 65 73 6f 6c 75  cond time resolu
36100 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 74  tion, then the t
36110 69 6d 65 20 77 69 6c 6c 20 62 65 20 72 6f 75 6e  ime will be roun
36120 64 65 64 20 75 70 20 74 6f 0a 2a 2a 20 74 68 65  ded up to.** the
36130 20 6e 65 61 72 65 73 74 20 73 65 63 6f 6e 64 2e   nearest second.
36140 20 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d   The number of m
36150 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73  illiseconds of s
36160 6c 65 65 70 20 61 63 74 75 61 6c 6c 79 0a 2a 2a  leep actually.**
36170 20 72 65 71 75 65 73 74 65 64 20 66 72 6f 6d 20   requested from 
36180 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79  the operating sy
36190 73 74 65 6d 20 69 73 20 72 65 74 75 72 6e 65 64  stem is returned
361a0 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ..**.** ^SQLite 
361b0 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 69 73 20  implements this 
361c0 69 6e 74 65 72 66 61 63 65 20 62 79 20 63 61 6c  interface by cal
361d0 6c 69 6e 67 20 74 68 65 20 78 53 6c 65 65 70 28  ling the xSleep(
361e0 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f 66 20 74  ).** method of t
361f0 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69  he default [sqli
36200 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e  te3_vfs] object.
36210 20 20 49 66 20 74 68 65 20 78 53 6c 65 65 70 28    If the xSleep(
36220 29 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66 20 74  ) method.** of t
36230 68 65 20 64 65 66 61 75 6c 74 20 56 46 53 20 69  he default VFS i
36240 73 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74 65  s not implemente
36250 64 20 63 6f 72 72 65 63 74 6c 79 2c 20 6f 72 20  d correctly, or 
36260 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20  not implemented 
36270 61 74 0a 2a 2a 20 61 6c 6c 2c 20 74 68 65 6e 20  at.** all, then 
36280 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20  the behavior of 
36290 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 29 20  sqlite3_sleep() 
362a0 6d 61 79 20 64 65 76 69 61 74 65 20 66 72 6f 6d  may deviate from
362b0 20 74 68 65 20 64 65 73 63 72 69 70 74 69 6f 6e   the description
362c0 0a 2a 2a 20 69 6e 20 74 68 65 20 70 72 65 76 69  .** in the previ
362d0 6f 75 73 20 70 61 72 61 67 72 61 70 68 73 2e 0a  ous paragraphs..
362e0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73  */.int sqlite3_s
362f0 6c 65 65 70 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a  leep(int);../*.*
36300 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d 65  * CAPI3REF: Name
36310 20 4f 66 20 54 68 65 20 46 6f 6c 64 65 72 20 48   Of The Folder H
36320 6f 6c 64 69 6e 67 20 54 65 6d 70 6f 72 61 72 79  olding Temporary
36330 20 46 69 6c 65 73 0a 2a 2a 0a 2a 2a 20 5e 28 49   Files.**.** ^(I
36340 66 20 74 68 69 73 20 67 6c 6f 62 61 6c 20 76 61  f this global va
36350 72 69 61 62 6c 65 20 69 73 20 6d 61 64 65 20 74  riable is made t
36360 6f 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72  o point to a str
36370 69 6e 67 20 77 68 69 63 68 20 69 73 0a 2a 2a 20  ing which is.** 
36380 74 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 66 6f  the name of a fo
36390 6c 64 65 72 20 28 61 2e 6b 2e 61 2e 20 64 69 72  lder (a.k.a. dir
363a0 65 63 74 6f 72 79 29 2c 20 74 68 65 6e 20 61 6c  ectory), then al
363b0 6c 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65  l temporary file
363c0 73 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20  s.** created by 
363d0 53 51 4c 69 74 65 20 77 68 65 6e 20 75 73 69 6e  SQLite when usin
363e0 67 20 61 20 62 75 69 6c 74 2d 69 6e 20 5b 73 71  g a built-in [sq
363f0 6c 69 74 65 33 5f 76 66 73 20 7c 20 56 46 53 5d  lite3_vfs | VFS]
36400 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 70 6c 61 63  .** will be plac
36410 65 64 20 69 6e 20 74 68 61 74 20 64 69 72 65 63  ed in that direc
36420 74 6f 72 79 2e 29 5e 20 20 5e 49 66 20 74 68 69  tory.)^  ^If thi
36430 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 69 73  s variable.** is
36440 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c   a NULL pointer,
36450 20 74 68 65 6e 20 53 51 4c 69 74 65 20 70 65 72   then SQLite per
36460 66 6f 72 6d 73 20 61 20 73 65 61 72 63 68 20 66  forms a search f
36470 6f 72 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74  or an appropriat
36480 65 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20 66  e.** temporary f
36490 69 6c 65 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a  ile directory..*
364a0 2a 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73  *.** It is not s
364b0 61 66 65 20 74 6f 20 72 65 61 64 20 6f 72 20 6d  afe to read or m
364c0 6f 64 69 66 79 20 74 68 69 73 20 76 61 72 69 61  odify this varia
364d0 62 6c 65 20 69 6e 20 6d 6f 72 65 20 74 68 61 6e  ble in more than
364e0 20 6f 6e 65 0a 2a 2a 20 74 68 72 65 61 64 20 61   one.** thread a
364f0 74 20 61 20 74 69 6d 65 2e 20 20 49 74 20 69 73  t a time.  It is
36500 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 72 65 61   not safe to rea
36510 64 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73  d or modify this
36520 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 69 66 20   variable.** if 
36530 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  a [database conn
36540 65 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67  ection] is being
36550 20 75 73 65 64 20 61 74 20 74 68 65 20 73 61 6d   used at the sam
36560 65 20 74 69 6d 65 20 69 6e 20 61 20 73 65 70 61  e time in a sepa
36570 72 61 74 65 0a 2a 2a 20 74 68 72 65 61 64 2e 0a  rate.** thread..
36580 2a 2a 20 49 74 20 69 73 20 69 6e 74 65 6e 64 65  ** It is intende
36590 64 20 74 68 61 74 20 74 68 69 73 20 76 61 72 69  d that this vari
365a0 61 62 6c 65 20 62 65 20 73 65 74 20 6f 6e 63 65  able be set once
365b0 0a 2a 2a 20 61 73 20 70 61 72 74 20 6f 66 20 70  .** as part of p
365c0 72 6f 63 65 73 73 20 69 6e 69 74 69 61 6c 69 7a  rocess initializ
365d0 61 74 69 6f 6e 20 61 6e 64 20 62 65 66 6f 72 65  ation and before
365e0 20 61 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 65   any SQLite inte
365f0 72 66 61 63 65 0a 2a 2a 20 72 6f 75 74 69 6e 65  rface.** routine
36600 73 20 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c  s have been call
36610 65 64 20 61 6e 64 20 74 68 61 74 20 74 68 69 73  ed and that this
36620 20 76 61 72 69 61 62 6c 65 20 72 65 6d 61 69 6e   variable remain
36630 20 75 6e 63 68 61 6e 67 65 64 0a 2a 2a 20 74 68   unchanged.** th
36640 65 72 65 61 66 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  ereafter..**.** 
36650 5e 54 68 65 20 5b 74 65 6d 70 5f 73 74 6f 72 65  ^The [temp_store
36660 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d  _directory pragm
36670 61 5d 20 6d 61 79 20 6d 6f 64 69 66 79 20 74 68  a] may modify th
36680 69 73 20 76 61 72 69 61 62 6c 65 20 61 6e 64 20  is variable and 
36690 63 61 75 73 65 0a 2a 2a 20 69 74 20 74 6f 20 70  cause.** it to p
366a0 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72 79 20 6f  oint to memory o
366b0 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
366c0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 2e 20 20  lite3_malloc].  
366d0 5e 46 75 72 74 68 65 72 6d 6f 72 65 2c 0a 2a 2a  ^Furthermore,.**
366e0 20 74 68 65 20 5b 74 65 6d 70 5f 73 74 6f 72 65   the [temp_store
366f0 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d  _directory pragm
36700 61 5d 20 61 6c 77 61 79 73 20 61 73 73 75 6d 65  a] always assume
36710 73 20 74 68 61 74 20 61 6e 79 20 73 74 72 69 6e  s that any strin
36720 67 0a 2a 2a 20 74 68 61 74 20 74 68 69 73 20 76  g.** that this v
36730 61 72 69 61 62 6c 65 20 70 6f 69 6e 74 73 20 74  ariable points t
36740 6f 20 69 73 20 68 65 6c 64 20 69 6e 20 6d 65 6d  o is held in mem
36750 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ory obtained fro
36760 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  m .** [sqlite3_m
36770 61 6c 6c 6f 63 5d 20 61 6e 64 20 74 68 65 20 70  alloc] and the p
36780 72 61 67 6d 61 20 6d 61 79 20 61 74 74 65 6d 70  ragma may attemp
36790 74 20 74 6f 20 66 72 65 65 20 74 68 61 74 20 6d  t to free that m
367a0 65 6d 6f 72 79 0a 2a 2a 20 75 73 69 6e 67 20 5b  emory.** using [
367b0 73 71 6c 69 74 65 33 5f 66 72 65 65 5d 2e 0a 2a  sqlite3_free]..*
367c0 2a 20 48 65 6e 63 65 2c 20 69 66 20 74 68 69 73  * Hence, if this
367d0 20 76 61 72 69 61 62 6c 65 20 69 73 20 6d 6f 64   variable is mod
367e0 69 66 69 65 64 20 64 69 72 65 63 74 6c 79 2c 20  ified directly, 
367f0 65 69 74 68 65 72 20 69 74 20 73 68 6f 75 6c 64  either it should
36800 20 62 65 0a 2a 2a 20 6d 61 64 65 20 4e 55 4c 4c   be.** made NULL
36810 20 6f 72 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e   or made to poin
36820 74 20 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61  t to memory obta
36830 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  ined from [sqlit
36840 65 33 5f 6d 61 6c 6c 6f 63 5d 0a 2a 2a 20 6f 72  e3_malloc].** or
36850 20 65 6c 73 65 20 74 68 65 20 75 73 65 20 6f 66   else the use of
36860 20 74 68 65 20 5b 74 65 6d 70 5f 73 74 6f 72 65   the [temp_store
36870 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d  _directory pragm
36880 61 5d 20 73 68 6f 75 6c 64 20 62 65 20 61 76 6f  a] should be avo
36890 69 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e  ided..**.** <b>N
368a0 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 52  ote to Windows R
368b0 75 6e 74 69 6d 65 20 75 73 65 72 73 3a 3c 2f 62  untime users:</b
368c0 3e 20 20 54 68 65 20 74 65 6d 70 6f 72 61 72 79  >  The temporary
368d0 20 64 69 72 65 63 74 6f 72 79 20 6d 75 73 74 20   directory must 
368e0 62 65 20 73 65 74 0a 2a 2a 20 70 72 69 6f 72 20  be set.** prior 
368f0 74 6f 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  to calling [sqli
36900 74 65 33 5f 6f 70 65 6e 5d 20 6f 72 20 5b 73 71  te3_open] or [sq
36910 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 5d 2e 20  lite3_open_v2]. 
36920 20 4f 74 68 65 72 77 69 73 65 2c 20 76 61 72 69   Otherwise, vari
36930 6f 75 73 0a 2a 2a 20 66 65 61 74 75 72 65 73 20  ous.** features 
36940 74 68 61 74 20 72 65 71 75 69 72 65 20 74 68 65  that require the
36950 20 75 73 65 20 6f 66 20 74 65 6d 70 6f 72 61 72   use of temporar
36960 79 20 66 69 6c 65 73 20 6d 61 79 20 66 61 69 6c  y files may fail
36970 2e 20 20 48 65 72 65 20 69 73 20 61 6e 0a 2a 2a  .  Here is an.**
36980 20 65 78 61 6d 70 6c 65 20 6f 66 20 68 6f 77 20   example of how 
36990 74 6f 20 64 6f 20 74 68 69 73 20 75 73 69 6e 67  to do this using
369a0 20 43 2b 2b 20 77 69 74 68 20 74 68 65 20 57 69   C++ with the Wi
369b0 6e 64 6f 77 73 20 52 75 6e 74 69 6d 65 3a 0a 2a  ndows Runtime:.*
369c0 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
369d0 3e 3c 70 72 65 3e 0a 2a 2a 20 4c 50 43 57 53 54  ><pre>.** LPCWST
369e0 52 20 7a 50 61 74 68 20 3d 20 57 69 6e 64 6f 77  R zPath = Window
369f0 73 3a 3a 53 74 6f 72 61 67 65 3a 3a 41 70 70 6c  s::Storage::Appl
36a00 69 63 61 74 69 6f 6e 44 61 74 61 3a 3a 43 75 72  icationData::Cur
36a10 72 65 6e 74 2d 3e 0a 2a 2a 20 26 6e 62 73 70 3b  rent->.** &nbsp;
36a20 20 20 20 20 20 54 65 6d 70 6f 72 61 72 79 46 6f       TemporaryFo
36a30 6c 64 65 72 2d 3e 50 61 74 68 2d 3e 44 61 74 61  lder->Path->Data
36a40 28 29 3b 0a 2a 2a 20 63 68 61 72 20 7a 50 61 74  ();.** char zPat
36a50 68 42 75 66 26 23 39 31 3b 4d 41 58 5f 50 41 54  hBuf&#91;MAX_PAT
36a60 48 20 2b 20 31 26 23 39 33 3b 3b 0a 2a 2a 20 6d  H + 1&#93;;.** m
36a70 65 6d 73 65 74 28 7a 50 61 74 68 42 75 66 2c 20  emset(zPathBuf, 
36a80 30 2c 20 73 69 7a 65 6f 66 28 7a 50 61 74 68 42  0, sizeof(zPathB
36a90 75 66 29 29 3b 0a 2a 2a 20 57 69 64 65 43 68 61  uf));.** WideCha
36aa0 72 54 6f 4d 75 6c 74 69 42 79 74 65 28 43 50 5f  rToMultiByte(CP_
36ab0 55 54 46 38 2c 20 30 2c 20 7a 50 61 74 68 2c 20  UTF8, 0, zPath, 
36ac0 2d 31 2c 20 7a 50 61 74 68 42 75 66 2c 20 73 69  -1, zPathBuf, si
36ad0 7a 65 6f 66 28 7a 50 61 74 68 42 75 66 29 2c 0a  zeof(zPathBuf),.
36ae0 2a 2a 20 26 6e 62 73 70 3b 20 20 20 20 20 4e 55  ** &nbsp;     NU
36af0 4c 4c 2c 20 4e 55 4c 4c 29 3b 0a 2a 2a 20 73 71  LL, NULL);.** sq
36b00 6c 69 74 65 33 5f 74 65 6d 70 5f 64 69 72 65 63  lite3_temp_direc
36b10 74 6f 72 79 20 3d 20 73 71 6c 69 74 65 33 5f 6d  tory = sqlite3_m
36b20 70 72 69 6e 74 66 28 22 25 73 22 2c 20 7a 50 61  printf("%s", zPa
36b30 74 68 42 75 66 29 3b 0a 2a 2a 20 3c 2f 70 72 65  thBuf);.** </pre
36b40 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
36b50 2f 0a 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 20  /.SQLITE_EXTERN 
36b60 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 74 65  char *sqlite3_te
36b70 6d 70 5f 64 69 72 65 63 74 6f 72 79 3b 0a 0a 2f  mp_directory;../
36b80 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e  *.** CAPI3REF: N
36b90 61 6d 65 20 4f 66 20 54 68 65 20 46 6f 6c 64 65  ame Of The Folde
36ba0 72 20 48 6f 6c 64 69 6e 67 20 44 61 74 61 62 61  r Holding Databa
36bb0 73 65 20 46 69 6c 65 73 0a 2a 2a 0a 2a 2a 20 5e  se Files.**.** ^
36bc0 28 49 66 20 74 68 69 73 20 67 6c 6f 62 61 6c 20  (If this global 
36bd0 76 61 72 69 61 62 6c 65 20 69 73 20 6d 61 64 65  variable is made
36be0 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 61 20 73   to point to a s
36bf0 74 72 69 6e 67 20 77 68 69 63 68 20 69 73 0a 2a  tring which is.*
36c00 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 61 20  * the name of a 
36c10 66 6f 6c 64 65 72 20 28 61 2e 6b 2e 61 2e 20 64  folder (a.k.a. d
36c20 69 72 65 63 74 6f 72 79 29 2c 20 74 68 65 6e 20  irectory), then 
36c30 61 6c 6c 20 64 61 74 61 62 61 73 65 20 66 69 6c  all database fil
36c40 65 73 0a 2a 2a 20 73 70 65 63 69 66 69 65 64 20  es.** specified 
36c50 77 69 74 68 20 61 20 72 65 6c 61 74 69 76 65 20  with a relative 
36c60 70 61 74 68 6e 61 6d 65 20 61 6e 64 20 63 72 65  pathname and cre
36c70 61 74 65 64 20 6f 72 20 61 63 63 65 73 73 65 64  ated or accessed
36c80 20 62 79 0a 2a 2a 20 53 51 4c 69 74 65 20 77 68   by.** SQLite wh
36c90 65 6e 20 75 73 69 6e 67 20 61 20 62 75 69 6c 74  en using a built
36ca0 2d 69 6e 20 77 69 6e 64 6f 77 73 20 5b 73 71 6c  -in windows [sql
36cb0 69 74 65 33 5f 76 66 73 20 7c 20 56 46 53 5d 20  ite3_vfs | VFS] 
36cc0 77 69 6c 6c 20 62 65 20 61 73 73 75 6d 65 64 0a  will be assumed.
36cd0 2a 2a 20 74 6f 20 62 65 20 72 65 6c 61 74 69 76  ** to be relativ
36ce0 65 20 74 6f 20 74 68 61 74 20 64 69 72 65 63 74  e to that direct
36cf0 6f 72 79 2e 29 5e 20 5e 49 66 20 74 68 69 73 20  ory.)^ ^If this 
36d00 76 61 72 69 61 62 6c 65 20 69 73 20 61 20 4e 55  variable is a NU
36d10 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 2c 20 74  LL.** pointer, t
36d20 68 65 6e 20 53 51 4c 69 74 65 20 61 73 73 75 6d  hen SQLite assum
36d30 65 73 20 74 68 61 74 20 61 6c 6c 20 64 61 74 61  es that all data
36d40 62 61 73 65 20 66 69 6c 65 73 20 73 70 65 63 69  base files speci
36d50 66 69 65 64 0a 2a 2a 20 77 69 74 68 20 61 20 72  fied.** with a r
36d60 65 6c 61 74 69 76 65 20 70 61 74 68 6e 61 6d 65  elative pathname
36d70 20 61 72 65 20 72 65 6c 61 74 69 76 65 20 74 6f   are relative to
36d80 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 69 72   the current dir
36d90 65 63 74 6f 72 79 0a 2a 2a 20 66 6f 72 20 74 68  ectory.** for th
36da0 65 20 70 72 6f 63 65 73 73 2e 20 20 4f 6e 6c 79  e process.  Only
36db0 20 74 68 65 20 77 69 6e 64 6f 77 73 20 56 46 53   the windows VFS
36dc0 20 6d 61 6b 65 73 20 75 73 65 20 6f 66 20 74 68   makes use of th
36dd0 69 73 20 67 6c 6f 62 61 6c 0a 2a 2a 20 76 61 72  is global.** var
36de0 69 61 62 6c 65 3b 20 69 74 20 69 73 20 69 67 6e  iable; it is ign
36df0 6f 72 65 64 20 62 79 20 74 68 65 20 75 6e 69 78  ored by the unix
36e00 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 43 68 61 6e   VFS..**.** Chan
36e10 67 69 6e 67 20 74 68 65 20 76 61 6c 75 65 20 6f  ging the value o
36e20 66 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20  f this variable 
36e30 77 68 69 6c 65 20 61 20 64 61 74 61 62 61 73 65  while a database
36e40 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 0a 2a   connection is.*
36e50 2a 20 6f 70 65 6e 20 63 61 6e 20 72 65 73 75 6c  * open can resul
36e60 74 20 69 6e 20 61 20 63 6f 72 72 75 70 74 20 64  t in a corrupt d
36e70 61 74 61 62 61 73 65 2e 0a 2a 2a 0a 2a 2a 20 49  atabase..**.** I
36e80 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f  t is not safe to
36e90 20 72 65 61 64 20 6f 72 20 6d 6f 64 69 66 79 20   read or modify 
36ea0 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 69 6e  this variable in
36eb0 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 0a 2a   more than one.*
36ec0 2a 20 74 68 72 65 61 64 20 61 74 20 61 20 74 69  * thread at a ti
36ed0 6d 65 2e 20 20 49 74 20 69 73 20 6e 6f 74 20 73  me.  It is not s
36ee0 61 66 65 20 74 6f 20 72 65 61 64 20 6f 72 20 6d  afe to read or m
36ef0 6f 64 69 66 79 20 74 68 69 73 20 76 61 72 69 61  odify this varia
36f00 62 6c 65 0a 2a 2a 20 69 66 20 61 20 5b 64 61 74  ble.** if a [dat
36f10 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
36f20 5d 20 69 73 20 62 65 69 6e 67 20 75 73 65 64 20  ] is being used 
36f30 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65  at the same time
36f40 20 69 6e 20 61 20 73 65 70 61 72 61 74 65 0a 2a   in a separate.*
36f50 2a 20 74 68 72 65 61 64 2e 0a 2a 2a 20 49 74 20  * thread..** It 
36f60 69 73 20 69 6e 74 65 6e 64 65 64 20 74 68 61 74  is intended that
36f70 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 62   this variable b
36f80 65 20 73 65 74 20 6f 6e 63 65 0a 2a 2a 20 61 73  e set once.** as
36f90 20 70 61 72 74 20 6f 66 20 70 72 6f 63 65 73 73   part of process
36fa0 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
36fb0 61 6e 64 20 62 65 66 6f 72 65 20 61 6e 79 20 53  and before any S
36fc0 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 0a  QLite interface.
36fd0 2a 2a 20 72 6f 75 74 69 6e 65 73 20 68 61 76 65  ** routines have
36fe0 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 61 6e 64   been called and
36ff0 20 74 68 61 74 20 74 68 69 73 20 76 61 72 69 61   that this varia
37000 62 6c 65 20 72 65 6d 61 69 6e 20 75 6e 63 68 61  ble remain uncha
37010 6e 67 65 64 0a 2a 2a 20 74 68 65 72 65 61 66 74  nged.** thereaft
37020 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b  er..**.** ^The [
37030 64 61 74 61 5f 73 74 6f 72 65 5f 64 69 72 65 63  data_store_direc
37040 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 6d 61 79  tory pragma] may
37050 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61 72   modify this var
37060 69 61 62 6c 65 20 61 6e 64 20 63 61 75 73 65 0a  iable and cause.
37070 2a 2a 20 69 74 20 74 6f 20 70 6f 69 6e 74 20 74  ** it to point t
37080 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65  o memory obtaine
37090 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
370a0 6d 61 6c 6c 6f 63 5d 2e 20 20 5e 46 75 72 74 68  malloc].  ^Furth
370b0 65 72 6d 6f 72 65 2c 0a 2a 2a 20 74 68 65 20 5b  ermore,.** the [
370c0 64 61 74 61 5f 73 74 6f 72 65 5f 64 69 72 65 63  data_store_direc
370d0 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 61 6c 77  tory pragma] alw
370e0 61 79 73 20 61 73 73 75 6d 65 73 20 74 68 61 74  ays assumes that
370f0 20 61 6e 79 20 73 74 72 69 6e 67 0a 2a 2a 20 74   any string.** t
37100 68 61 74 20 74 68 69 73 20 76 61 72 69 61 62 6c  hat this variabl
37110 65 20 70 6f 69 6e 74 73 20 74 6f 20 69 73 20 68  e points to is h
37120 65 6c 64 20 69 6e 20 6d 65 6d 6f 72 79 20 6f 62  eld in memory ob
37130 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20  tained from .** 
37140 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d  [sqlite3_malloc]
37150 20 61 6e 64 20 74 68 65 20 70 72 61 67 6d 61 20   and the pragma 
37160 6d 61 79 20 61 74 74 65 6d 70 74 20 74 6f 20 66  may attempt to f
37170 72 65 65 20 74 68 61 74 20 6d 65 6d 6f 72 79 0a  ree that memory.
37180 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ** using [sqlite
37190 33 5f 66 72 65 65 5d 2e 0a 2a 2a 20 48 65 6e 63  3_free]..** Henc
371a0 65 2c 20 69 66 20 74 68 69 73 20 76 61 72 69 61  e, if this varia
371b0 62 6c 65 20 69 73 20 6d 6f 64 69 66 69 65 64 20  ble is modified 
371c0 64 69 72 65 63 74 6c 79 2c 20 65 69 74 68 65 72  directly, either
371d0 20 69 74 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a   it should be.**
371e0 20 6d 61 64 65 20 4e 55 4c 4c 20 6f 72 20 6d 61   made NULL or ma
371f0 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 6d  de to point to m
37200 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66  emory obtained f
37210 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
37220 6c 6f 63 5d 0a 2a 2a 20 6f 72 20 65 6c 73 65 20  loc].** or else 
37230 74 68 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b  the use of the [
37240 64 61 74 61 5f 73 74 6f 72 65 5f 64 69 72 65 63  data_store_direc
37250 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 73 68 6f  tory pragma] sho
37260 75 6c 64 20 62 65 20 61 76 6f 69 64 65 64 2e 0a  uld be avoided..
37270 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54 45 52 4e  */.SQLITE_EXTERN
37280 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 64   char *sqlite3_d
37290 61 74 61 5f 64 69 72 65 63 74 6f 72 79 3b 0a 0a  ata_directory;..
372a0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
372b0 54 65 73 74 20 46 6f 72 20 41 75 74 6f 2d 43 6f  Test For Auto-Co
372c0 6d 6d 69 74 20 4d 6f 64 65 0a 2a 2a 20 4b 45 59  mmit Mode.** KEY
372d0 57 4f 52 44 53 3a 20 7b 61 75 74 6f 63 6f 6d 6d  WORDS: {autocomm
372e0 69 74 20 6d 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 5e  it mode}.**.** ^
372f0 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  The sqlite3_get_
37300 61 75 74 6f 63 6f 6d 6d 69 74 28 29 20 69 6e 74  autocommit() int
37310 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 6e  erface returns n
37320 6f 6e 2d 7a 65 72 6f 20 6f 72 0a 2a 2a 20 7a 65  on-zero or.** ze
37330 72 6f 20 69 66 20 74 68 65 20 67 69 76 65 6e 20  ro if the given 
37340 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
37350 69 6f 6e 20 69 73 20 6f 72 20 69 73 20 6e 6f 74  ion is or is not
37360 20 69 6e 20 61 75 74 6f 63 6f 6d 6d 69 74 20 6d   in autocommit m
37370 6f 64 65 2c 0a 2a 2a 20 72 65 73 70 65 63 74 69  ode,.** respecti
37380 76 65 6c 79 2e 20 20 5e 41 75 74 6f 63 6f 6d 6d  vely.  ^Autocomm
37390 69 74 20 6d 6f 64 65 20 69 73 20 6f 6e 20 62 79  it mode is on by
373a0 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 5e 41 75   default..** ^Au
373b0 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73  tocommit mode is
373c0 20 64 69 73 61 62 6c 65 64 20 62 79 20 61 20 5b   disabled by a [
373d0 42 45 47 49 4e 5d 20 73 74 61 74 65 6d 65 6e 74  BEGIN] statement
373e0 2e 0a 2a 2a 20 5e 41 75 74 6f 63 6f 6d 6d 69 74  ..** ^Autocommit
373f0 20 6d 6f 64 65 20 69 73 20 72 65 2d 65 6e 61 62   mode is re-enab
37400 6c 65 64 20 62 79 20 61 20 5b 43 4f 4d 4d 49 54  led by a [COMMIT
37410 5d 20 6f 72 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2e  ] or [ROLLBACK].
37420 0a 2a 2a 0a 2a 2a 20 49 66 20 63 65 72 74 61 69  .**.** If certai
37430 6e 20 6b 69 6e 64 73 20 6f 66 20 65 72 72 6f 72  n kinds of error
37440 73 20 6f 63 63 75 72 20 6f 6e 20 61 20 73 74 61  s occur on a sta
37450 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 61 20  tement within a 
37460 6d 75 6c 74 69 2d 73 74 61 74 65 6d 65 6e 74 0a  multi-statement.
37470 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 28  ** transaction (
37480 65 72 72 6f 72 73 20 69 6e 63 6c 75 64 69 6e 67  errors including
37490 20 5b 53 51 4c 49 54 45 5f 46 55 4c 4c 5d 2c 20   [SQLITE_FULL], 
374a0 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 2c 0a  [SQLITE_IOERR],.
374b0 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  ** [SQLITE_NOMEM
374c0 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  ], [SQLITE_BUSY]
374d0 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 49 4e  , and [SQLITE_IN
374e0 54 45 52 52 55 50 54 5d 29 20 74 68 65 6e 20 74  TERRUPT]) then t
374f0 68 65 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f  he.** transactio
37500 6e 20 6d 69 67 68 74 20 62 65 20 72 6f 6c 6c 65  n might be rolle
37510 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63  d back automatic
37520 61 6c 6c 79 2e 20 20 54 68 65 20 6f 6e 6c 79 20  ally.  The only 
37530 77 61 79 20 74 6f 0a 2a 2a 20 66 69 6e 64 20 6f  way to.** find o
37540 75 74 20 77 68 65 74 68 65 72 20 53 51 4c 69 74  ut whether SQLit
37550 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  e automatically 
37560 72 6f 6c 6c 65 64 20 62 61 63 6b 20 74 68 65 20  rolled back the 
37570 74 72 61 6e 73 61 63 74 69 6f 6e 20 61 66 74 65  transaction afte
37580 72 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20 69 73  r.** an error is
37590 20 74 6f 20 75 73 65 20 74 68 69 73 20 66 75 6e   to use this fun
375a0 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  ction..**.** If 
375b0 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 20 63  another thread c
375c0 68 61 6e 67 65 73 20 74 68 65 20 61 75 74 6f 63  hanges the autoc
375d0 6f 6d 6d 69 74 20 73 74 61 74 75 73 20 6f 66 20  ommit status of 
375e0 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  the database.** 
375f0 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65  connection while
37600 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73   this routine is
37610 20 72 75 6e 6e 69 6e 67 2c 20 74 68 65 6e 20 74   running, then t
37620 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a  he return value.
37630 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  ** is undefined.
37640 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
37650 67 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 73  get_autocommit(s
37660 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
37670 20 43 41 50 49 33 52 45 46 3a 20 46 69 6e 64 20   CAPI3REF: Find 
37680 54 68 65 20 44 61 74 61 62 61 73 65 20 48 61 6e  The Database Han
37690 64 6c 65 20 4f 66 20 41 20 50 72 65 70 61 72 65  dle Of A Prepare
376a0 64 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a  d Statement.**.*
376b0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64  * ^The sqlite3_d
376c0 62 5f 68 61 6e 64 6c 65 20 69 6e 74 65 72 66 61  b_handle interfa
376d0 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 5b  ce returns the [
376e0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
376f0 69 6f 6e 5d 20 68 61 6e 64 6c 65 0a 2a 2a 20 74  ion] handle.** t
37700 6f 20 77 68 69 63 68 20 61 20 5b 70 72 65 70 61  o which a [prepa
37710 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 62  red statement] b
37720 65 6c 6f 6e 67 73 2e 20 20 5e 54 68 65 20 5b 64  elongs.  ^The [d
37730 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
37740 6f 6e 5d 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  on].** returned 
37750 62 79 20 73 71 6c 69 74 65 33 5f 64 62 5f 68 61  by sqlite3_db_ha
37760 6e 64 6c 65 20 69 73 20 74 68 65 20 73 61 6d 65  ndle is the same
37770 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
37780 63 74 69 6f 6e 5d 0a 2a 2a 20 74 68 61 74 20 77  ction].** that w
37790 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67  as the first arg
377a0 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 74 68 65 20  ument.** to the 
377b0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
377c0 5f 76 32 28 29 5d 20 63 61 6c 6c 20 28 6f 72 20  _v2()] call (or 
377d0 69 74 73 20 76 61 72 69 61 6e 74 73 29 20 74 68  its variants) th
377e0 61 74 20 77 61 73 20 75 73 65 64 20 74 6f 0a 2a  at was used to.*
377f0 2a 20 63 72 65 61 74 65 20 74 68 65 20 73 74 61  * create the sta
37800 74 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 66 69  tement in the fi
37810 72 73 74 20 70 6c 61 63 65 2e 0a 2a 2f 0a 73 71  rst place..*/.sq
37820 6c 69 74 65 33 20 2a 73 71 6c 69 74 65 33 5f 64  lite3 *sqlite3_d
37830 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74 65 33  b_handle(sqlite3
37840 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  _stmt*);../*.** 
37850 43 41 50 49 33 52 45 46 3a 20 52 65 74 75 72 6e  CAPI3REF: Return
37860 20 54 68 65 20 46 69 6c 65 6e 61 6d 65 20 46 6f   The Filename Fo
37870 72 20 41 20 44 61 74 61 62 61 73 65 20 43 6f 6e  r A Database Con
37880 6e 65 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54  nection.**.** ^T
37890 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 66 69  he sqlite3_db_fi
378a0 6c 65 6e 61 6d 65 28 44 2c 4e 29 20 69 6e 74 65  lename(D,N) inte
378b0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
378c0 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 66 69 6c  pointer to a fil
378d0 65 6e 61 6d 65 0a 2a 2a 20 61 73 73 6f 63 69 61  ename.** associa
378e0 74 65 64 20 77 69 74 68 20 64 61 74 61 62 61 73  ted with databas
378f0 65 20 4e 20 6f 66 20 63 6f 6e 6e 65 63 74 69 6f  e N of connectio
37900 6e 20 44 2e 20 20 5e 54 68 65 20 6d 61 69 6e 20  n D.  ^The main 
37910 64 61 74 61 62 61 73 65 20 66 69 6c 65 0a 2a 2a  database file.**
37920 20 68 61 73 20 74 68 65 20 6e 61 6d 65 20 22 6d   has the name "m
37930 61 69 6e 22 2e 20 20 49 66 20 74 68 65 72 65 20  ain".  If there 
37940 69 73 20 6e 6f 20 61 74 74 61 63 68 65 64 20 64  is no attached d
37950 61 74 61 62 61 73 65 20 4e 20 6f 6e 20 74 68 65  atabase N on the
37960 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e   database.** con
37970 6e 65 63 74 69 6f 6e 20 44 2c 20 6f 72 20 69 66  nection D, or if
37980 20 64 61 74 61 62 61 73 65 20 4e 20 69 73 20 61   database N is a
37990 20 74 65 6d 70 6f 72 61 72 79 20 6f 72 20 69 6e   temporary or in
379a0 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65  -memory database
379b0 2c 20 74 68 65 6e 0a 2a 2a 20 61 20 4e 55 4c 4c  , then.** a NULL
379c0 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75   pointer is retu
379d0 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  rned..**.** ^The
379e0 20 66 69 6c 65 6e 61 6d 65 20 72 65 74 75 72 6e   filename return
379f0 65 64 20 62 79 20 74 68 69 73 20 66 75 6e 63 74  ed by this funct
37a00 69 6f 6e 20 69 73 20 74 68 65 20 6f 75 74 70 75  ion is the outpu
37a10 74 20 6f 66 20 74 68 65 0a 2a 2a 20 78 46 75 6c  t of the.** xFul
37a20 6c 50 61 74 68 6e 61 6d 65 20 6d 65 74 68 6f 64  lPathname method
37a30 20 6f 66 20 74 68 65 20 5b 56 46 53 5d 2e 20 20   of the [VFS].  
37a40 5e 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c  ^In other words,
37a50 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a   the filename.**
37a60 20 77 69 6c 6c 20 62 65 20 61 6e 20 61 62 73 6f   will be an abso
37a70 6c 75 74 65 20 70 61 74 68 6e 61 6d 65 2c 20 65  lute pathname, e
37a80 76 65 6e 20 69 66 20 74 68 65 20 66 69 6c 65 6e  ven if the filen
37a90 61 6d 65 20 75 73 65 64 0a 2a 2a 20 74 6f 20 6f  ame used.** to o
37aa0 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  pen the database
37ab0 20 6f 72 69 67 69 6e 61 6c 6c 79 20 77 61 73 20   originally was 
37ac0 61 20 55 52 49 20 6f 72 20 72 65 6c 61 74 69 76  a URI or relativ
37ad0 65 20 70 61 74 68 6e 61 6d 65 2e 0a 2a 2f 0a 63  e pathname..*/.c
37ae0 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
37af0 65 33 5f 64 62 5f 66 69 6c 65 6e 61 6d 65 28 73  e3_db_filename(s
37b00 71 6c 69 74 65 33 20 2a 64 62 2c 20 63 6f 6e 73  qlite3 *db, cons
37b10 74 20 63 68 61 72 20 2a 7a 44 62 4e 61 6d 65 29  t char *zDbName)
37b20 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
37b30 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 69 66 20  F: Determine if 
37b40 61 20 64 61 74 61 62 61 73 65 20 69 73 20 72 65  a database is re
37b50 61 64 2d 6f 6e 6c 79 0a 2a 2a 0a 2a 2a 20 5e 54  ad-only.**.** ^T
37b60 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 72 65  he sqlite3_db_re
37b70 61 64 6f 6e 6c 79 28 44 2c 4e 29 20 69 6e 74 65  adonly(D,N) inte
37b80 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 31 20  rface returns 1 
37b90 69 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  if the database 
37ba0 4e 0a 2a 2a 20 6f 66 20 63 6f 6e 6e 65 63 74 69  N.** of connecti
37bb0 6f 6e 20 44 20 69 73 20 72 65 61 64 2d 6f 6e 6c  on D is read-onl
37bc0 79 2c 20 30 20 69 66 20 69 74 20 69 73 20 72 65  y, 0 if it is re
37bd0 61 64 2f 77 72 69 74 65 2c 20 6f 72 20 2d 31 20  ad/write, or -1 
37be0 69 66 20 4e 20 69 73 20 6e 6f 74 0a 2a 2a 20 74  if N is not.** t
37bf0 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 64 61 74  he name of a dat
37c00 61 62 61 73 65 20 6f 6e 20 63 6f 6e 6e 65 63 74  abase on connect
37c10 69 6f 6e 20 44 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ion D..*/.int sq
37c20 6c 69 74 65 33 5f 64 62 5f 72 65 61 64 6f 6e 6c  lite3_db_readonl
37c30 79 28 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 63  y(sqlite3 *db, c
37c40 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44 62 4e 61  onst char *zDbNa
37c50 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  me);../*.** CAPI
37c60 33 52 45 46 3a 20 46 69 6e 64 20 74 68 65 20 6e  3REF: Find the n
37c70 65 78 74 20 70 72 65 70 61 72 65 64 20 73 74 61  ext prepared sta
37c80 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  tement.**.** ^Th
37c90 69 73 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  is interface ret
37ca0 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
37cb0 6f 20 74 68 65 20 6e 65 78 74 20 5b 70 72 65 70  o the next [prep
37cc0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
37cd0 61 66 74 65 72 0a 2a 2a 20 70 53 74 6d 74 20 61  after.** pStmt a
37ce0 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
37cf0 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
37d00 6e 65 63 74 69 6f 6e 5d 20 70 44 62 2e 20 20 5e  nection] pDb.  ^
37d10 49 66 20 70 53 74 6d 74 20 69 73 20 4e 55 4c 4c  If pStmt is NULL
37d20 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 20 69 6e  .** then this in
37d30 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
37d40 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
37d50 20 66 69 72 73 74 20 70 72 65 70 61 72 65 64 20   first prepared 
37d60 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 61 73 73  statement.** ass
37d70 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65  ociated with the
37d80 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
37d90 74 69 6f 6e 20 70 44 62 2e 20 20 5e 49 66 20 6e  tion pDb.  ^If n
37da0 6f 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  o prepared state
37db0 6d 65 6e 74 0a 2a 2a 20 73 61 74 69 73 66 69 65  ment.** satisfie
37dc0 73 20 74 68 65 20 63 6f 6e 64 69 74 69 6f 6e 73  s the conditions
37dd0 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65   of this routine
37de0 2c 20 69 74 20 72 65 74 75 72 6e 73 20 4e 55 4c  , it returns NUL
37df0 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 64 61  L..**.** The [da
37e00 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
37e10 6e 5d 20 70 6f 69 6e 74 65 72 20 44 20 69 6e 20  n] pointer D in 
37e20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71  a call to.** [sq
37e30 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28  lite3_next_stmt(
37e40 44 2c 53 29 5d 20 6d 75 73 74 20 72 65 66 65 72  D,S)] must refer
37e50 20 74 6f 20 61 6e 20 6f 70 65 6e 20 64 61 74 61   to an open data
37e60 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  base.** connecti
37e70 6f 6e 20 61 6e 64 20 69 6e 20 70 61 72 74 69 63  on and in partic
37e80 75 6c 61 72 20 6d 75 73 74 20 6e 6f 74 20 62 65  ular must not be
37e90 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
37ea0 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 73 74 6d 74  .*/.sqlite3_stmt
37eb0 20 2a 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73   *sqlite3_next_s
37ec0 74 6d 74 28 73 71 6c 69 74 65 33 20 2a 70 44 62  tmt(sqlite3 *pDb
37ed0 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  , sqlite3_stmt *
37ee0 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
37ef0 41 50 49 33 52 45 46 3a 20 43 6f 6d 6d 69 74 20  API3REF: Commit 
37f00 41 6e 64 20 52 6f 6c 6c 62 61 63 6b 20 4e 6f 74  And Rollback Not
37f10 69 66 69 63 61 74 69 6f 6e 20 43 61 6c 6c 62 61  ification Callba
37f20 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  cks.**.** ^The s
37f30 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f  qlite3_commit_ho
37f40 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  ok() interface r
37f50 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62  egisters a callb
37f60 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ack.** function 
37f70 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68  to be invoked wh
37f80 65 6e 65 76 65 72 20 61 20 74 72 61 6e 73 61 63  enever a transac
37f90 74 69 6f 6e 20 69 73 20 5b 43 4f 4d 4d 49 54 20  tion is [COMMIT 
37fa0 7c 20 63 6f 6d 6d 69 74 74 65 64 5d 2e 0a 2a 2a  | committed]..**
37fb0 20 5e 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73   ^Any callback s
37fc0 65 74 20 62 79 20 61 20 70 72 65 76 69 6f 75 73  et by a previous
37fd0 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
37fe0 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 0a 2a  _commit_hook().*
37ff0 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 64  * for the same d
38000 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
38010 6f 6e 20 69 73 20 6f 76 65 72 72 69 64 64 65 6e  on is overridden
38020 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
38030 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28  3_rollback_hook(
38040 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69  ) interface regi
38050 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b  sters a callback
38060 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  .** function to 
38070 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65  be invoked whene
38080 76 65 72 20 61 20 74 72 61 6e 73 61 63 74 69 6f  ver a transactio
38090 6e 20 69 73 20 5b 52 4f 4c 4c 42 41 43 4b 20 7c  n is [ROLLBACK |
380a0 20 72 6f 6c 6c 65 64 20 62 61 63 6b 5d 2e 0a 2a   rolled back]..*
380b0 2a 20 5e 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20  * ^Any callback 
380c0 73 65 74 20 62 79 20 61 20 70 72 65 76 69 6f 75  set by a previou
380d0 73 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  s call to sqlite
380e0 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28  3_rollback_hook(
380f0 29 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d  ).** for the sam
38100 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
38110 63 74 69 6f 6e 20 69 73 20 6f 76 65 72 72 69 64  ction is overrid
38120 64 65 6e 2e 0a 2a 2a 20 5e 54 68 65 20 70 41 72  den..** ^The pAr
38130 67 20 61 72 67 75 6d 65 6e 74 20 69 73 20 70 61  g argument is pa
38140 73 73 65 64 20 74 68 72 6f 75 67 68 20 74 6f 20  ssed through to 
38150 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a  the callback..**
38160 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63   ^If the callbac
38170 6b 20 6f 6e 20 61 20 63 6f 6d 6d 69 74 20 68 6f  k on a commit ho
38180 6f 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  ok function retu
38190 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 0a 2a 2a  rns non-zero,.**
381a0 20 74 68 65 6e 20 74 68 65 20 63 6f 6d 6d 69 74   then the commit
381b0 20 69 73 20 63 6f 6e 76 65 72 74 65 64 20 69 6e   is converted in
381c0 74 6f 20 61 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a  to a rollback..*
381d0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
381e0 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 44 2c  3_commit_hook(D,
381f0 43 2c 50 29 20 61 6e 64 20 73 71 6c 69 74 65 33  C,P) and sqlite3
38200 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 44  _rollback_hook(D
38210 2c 43 2c 50 29 20 66 75 6e 63 74 69 6f 6e 73 0a  ,C,P) functions.
38220 2a 2a 20 72 65 74 75 72 6e 20 74 68 65 20 50 20  ** return the P 
38230 61 72 67 75 6d 65 6e 74 20 66 72 6f 6d 20 74 68  argument from th
38240 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20  e previous call 
38250 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63  of the same func
38260 74 69 6f 6e 0a 2a 2a 20 6f 6e 20 74 68 65 20 73  tion.** on the s
38270 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  ame [database co
38280 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c 20 6f 72 20  nnection] D, or 
38290 4e 55 4c 4c 20 66 6f 72 0a 2a 2a 20 74 68 65 20  NULL for.** the 
382a0 66 69 72 73 74 20 63 61 6c 6c 20 66 6f 72 20 65  first call for e
382b0 61 63 68 20 66 75 6e 63 74 69 6f 6e 20 6f 6e 20  ach function on 
382c0 44 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6d  D..**.** The com
382d0 6d 69 74 20 61 6e 64 20 72 6f 6c 6c 62 61 63 6b  mit and rollback
382e0 20 68 6f 6f 6b 20 63 61 6c 6c 62 61 63 6b 73 20   hook callbacks 
382f0 61 72 65 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e  are not reentran
38300 74 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61  t..** The callba
38310 63 6b 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ck implementatio
38320 6e 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e  n must not do an
38330 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c  ything that will
38340 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64   modify.** the d
38350 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
38360 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20  on that invoked 
38370 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 20 20 41  the callback.  A
38380 6e 79 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 74 6f  ny actions.** to
38390 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74 61   modify the data
383a0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
383b0 6d 75 73 74 20 62 65 20 64 65 66 65 72 72 65 64  must be deferred
383c0 20 75 6e 74 69 6c 20 61 66 74 65 72 20 74 68 65   until after the
383d0 0a 2a 2a 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 6f  .** completion o
383e0 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  f the [sqlite3_s
383f0 74 65 70 28 29 5d 20 63 61 6c 6c 20 74 68 61 74  tep()] call that
38400 20 74 72 69 67 67 65 72 65 64 20 74 68 65 20 63   triggered the c
38410 6f 6d 6d 69 74 0a 2a 2a 20 6f 72 20 72 6f 6c 6c  ommit.** or roll
38420 62 61 63 6b 20 68 6f 6f 6b 20 69 6e 20 74 68 65  back hook in the
38430 20 66 69 72 73 74 20 70 6c 61 63 65 2e 0a 2a 2a   first place..**
38440 20 4e 6f 74 65 20 74 68 61 74 20 72 75 6e 6e 69   Note that runni
38450 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c  ng any other SQL
38460 20 73 74 61 74 65 6d 65 6e 74 73 2c 20 69 6e 63   statements, inc
38470 6c 75 64 69 6e 67 20 53 45 4c 45 43 54 20 73 74  luding SELECT st
38480 61 74 65 6d 65 6e 74 73 2c 0a 2a 2a 20 6f 72 20  atements,.** or 
38490 6d 65 72 65 6c 79 20 63 61 6c 6c 69 6e 67 20 5b  merely calling [
384a0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
384b0 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  v2()] and [sqlit
384c0 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20  e3_step()] will 
384d0 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61  modify.** the da
384e0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
384f0 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69  ns for the meani
38500 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69  ng of "modify" i
38510 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70 68  n this paragraph
38520 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 69 73 74 65  ..**.** ^Registe
38530 72 69 6e 67 20 61 20 4e 55 4c 4c 20 66 75 6e 63  ring a NULL func
38540 74 69 6f 6e 20 64 69 73 61 62 6c 65 73 20 74 68  tion disables th
38550 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a  e callback..**.*
38560 2a 20 5e 57 68 65 6e 20 74 68 65 20 63 6f 6d 6d  * ^When the comm
38570 69 74 20 68 6f 6f 6b 20 63 61 6c 6c 62 61 63 6b  it hook callback
38580 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
38590 20 7a 65 72 6f 2c 20 74 68 65 20 5b 43 4f 4d 4d   zero, the [COMM
385a0 49 54 5d 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e  IT].** operation
385b0 20 69 73 20 61 6c 6c 6f 77 65 64 20 74 6f 20 63   is allowed to c
385c0 6f 6e 74 69 6e 75 65 20 6e 6f 72 6d 61 6c 6c 79  ontinue normally
385d0 2e 20 20 5e 49 66 20 74 68 65 20 63 6f 6d 6d 69  .  ^If the commi
385e0 74 20 68 6f 6f 6b 0a 2a 2a 20 72 65 74 75 72 6e  t hook.** return
385f0 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e  s non-zero, then
38600 20 74 68 65 20 5b 43 4f 4d 4d 49 54 5d 20 69 73   the [COMMIT] is
38610 20 63 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f 20   converted into 
38620 61 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a  a [ROLLBACK]..**
38630 20 5e 54 68 65 20 72 6f 6c 6c 62 61 63 6b 20 68   ^The rollback h
38640 6f 6f 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f  ook is invoked o
38650 6e 20 61 20 72 6f 6c 6c 62 61 63 6b 20 74 68 61  n a rollback tha
38660 74 20 72 65 73 75 6c 74 73 20 66 72 6f 6d 20 61  t results from a
38670 20 63 6f 6d 6d 69 74 0a 2a 2a 20 68 6f 6f 6b 20   commit.** hook 
38680 72 65 74 75 72 6e 69 6e 67 20 6e 6f 6e 2d 7a 65  returning non-ze
38690 72 6f 2c 20 6a 75 73 74 20 61 73 20 69 74 20 77  ro, just as it w
386a0 6f 75 6c 64 20 62 65 20 77 69 74 68 20 61 6e 79  ould be with any
386b0 20 6f 74 68 65 72 20 72 6f 6c 6c 62 61 63 6b 2e   other rollback.
386c0 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20  .**.** ^For the 
386d0 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73  purposes of this
386e0 20 41 50 49 2c 20 61 20 74 72 61 6e 73 61 63 74   API, a transact
386f0 69 6f 6e 20 69 73 20 73 61 69 64 20 74 6f 20 68  ion is said to h
38700 61 76 65 20 62 65 65 6e 0a 2a 2a 20 72 6f 6c 6c  ave been.** roll
38710 65 64 20 62 61 63 6b 20 69 66 20 61 6e 20 65 78  ed back if an ex
38720 70 6c 69 63 69 74 20 22 52 4f 4c 4c 42 41 43 4b  plicit "ROLLBACK
38730 22 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 65  " statement is e
38740 78 65 63 75 74 65 64 2c 20 6f 72 0a 2a 2a 20 61  xecuted, or.** a
38750 6e 20 65 72 72 6f 72 20 6f 72 20 63 6f 6e 73 74  n error or const
38760 72 61 69 6e 74 20 63 61 75 73 65 73 20 61 6e 20  raint causes an 
38770 69 6d 70 6c 69 63 69 74 20 72 6f 6c 6c 62 61 63  implicit rollbac
38780 6b 20 74 6f 20 6f 63 63 75 72 2e 0a 2a 2a 20 5e  k to occur..** ^
38790 54 68 65 20 72 6f 6c 6c 62 61 63 6b 20 63 61 6c  The rollback cal
387a0 6c 62 61 63 6b 20 69 73 20 6e 6f 74 20 69 6e 76  lback is not inv
387b0 6f 6b 65 64 20 69 66 20 61 20 74 72 61 6e 73 61  oked if a transa
387c0 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 61 75 74 6f  ction is.** auto
387d0 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64  matically rolled
387e0 20 62 61 63 6b 20 62 65 63 61 75 73 65 20 74 68   back because th
387f0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
38800 63 74 69 6f 6e 20 69 73 20 63 6c