/ Hex Artifact Content
Login

Artifact 592057b6b3881573c2d516bad30fb20171f16b05:


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 74 68  ust not close th
3e90: 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
3ea0: 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65  ection] specifie
3eb0: 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 74 68 65  d by.**      the
3ec0: 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 20 74   1st parameter t
3ed0: 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  o sqlite3_exec()
3ee0: 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 65   while sqlite3_e
3ef0: 78 65 63 28 29 20 69 73 20 72 75 6e 6e 69 6e 67  xec() is running
3f00: 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70  ..** <li> The ap
3f10: 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e  plication must n
3f20: 6f 74 20 6d 6f 64 69 66 79 20 74 68 65 20 53 51  ot modify the SQ
3f30: 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74  L statement text
3f40: 20 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20   passed into.** 
3f50: 20 20 20 20 20 74 68 65 20 32 6e 64 20 70 61 72       the 2nd par
3f60: 61 6d 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65  ameter of sqlite
3f70: 33 5f 65 78 65 63 28 29 20 77 68 69 6c 65 20 73  3_exec() while s
3f80: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73  qlite3_exec() is
3f90: 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 2f 75   running..** </u
3fa0: 6c 3e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  l>.*/.int sqlite
3fb0: 33 5f 65 78 65 63 28 0a 20 20 73 71 6c 69 74 65  3_exec(.  sqlite
3fc0: 33 2a 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  3*,             
3fd0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3fe0: 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20       /* An open 
3ff0: 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f  database */.  co
4000: 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 2c 20 20  nst 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 20 20 20 20 2f 2a 20 53 51 4c 20           /* SQL 
4030: 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64 20  to be evaluated 
4040: 2a 2f 0a 20 20 69 6e 74 20 28 2a 63 61 6c 6c 62  */.  int (*callb
4050: 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63  ack)(void*,int,c
4060: 68 61 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20 20  har**,char**),  
4070: 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 66 75 6e 63  /* Callback func
4080: 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a  tion */.  void *
4090: 2c 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 20 20 20 20 2f 2a 20 31 73 74 20 61 72 67 75       /* 1st argu
40c0: 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 62 61 63 6b  ment to callback
40d0: 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72 72   */.  char **err
40e0: 6d 73 67 20 20 20 20 20 20 20 20 20 20 20 20 20  msg             
40f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4100: 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72   /* Error msg wr
4110: 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b  itten here */.);
4120: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
4130: 3a 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a  : Result Codes.*
4140: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49  * KEYWORDS: SQLI
4150: 54 45 5f 4f 4b 20 7b 65 72 72 6f 72 20 63 6f 64  TE_OK {error cod
4160: 65 7d 20 7b 65 72 72 6f 72 20 63 6f 64 65 73 7d  e} {error codes}
4170: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 72  .** KEYWORDS: {r
4180: 65 73 75 6c 74 20 63 6f 64 65 7d 20 7b 72 65 73  esult code} {res
4190: 75 6c 74 20 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a  ult codes}.**.**
41a0: 20 4d 61 6e 79 20 53 51 4c 69 74 65 20 66 75 6e   Many SQLite fun
41b0: 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 61 6e  ctions return an
41c0: 20 69 6e 74 65 67 65 72 20 72 65 73 75 6c 74 20   integer result 
41d0: 63 6f 64 65 20 66 72 6f 6d 20 74 68 65 20 73 65  code from the se
41e0: 74 20 73 68 6f 77 6e 0a 2a 2a 20 68 65 72 65 20  t shown.** here 
41f0: 69 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e 64 69  in order to indi
4200: 63 61 74 65 20 73 75 63 63 65 73 73 20 6f 72 20  cate success or 
4210: 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 4e  failure..**.** N
4220: 65 77 20 65 72 72 6f 72 20 63 6f 64 65 73 20 6d  ew error codes m
4230: 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66  ay be added in f
4240: 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f  uture versions o
4250: 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20  f SQLite..**.** 
4260: 53 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c 49 54  See also: [SQLIT
4270: 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c 20 65  E_IOERR_READ | e
4280: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
4290: 6f 64 65 73 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  odes],.** [sqlit
42a0: 65 33 5f 76 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c  e3_vtab_on_confl
42b0: 69 63 74 28 29 5d 20 5b 53 51 4c 49 54 45 5f 52  ict()] [SQLITE_R
42c0: 4f 4c 4c 42 41 43 4b 20 7c 20 72 65 73 75 6c 74  OLLBACK | result
42d0: 20 63 6f 64 65 73 5d 2e 0a 2a 2f 0a 23 64 65 66   codes]..*/.#def
42e0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 4b 20 20 20  ine SQLITE_OK   
42f0: 20 20 20 20 20 20 20 20 30 20 20 20 2f 2a 20 53          0   /* S
4300: 75 63 63 65 73 73 66 75 6c 20 72 65 73 75 6c 74  uccessful result
4310: 20 2a 2f 0a 2f 2a 20 62 65 67 69 6e 6e 69 6e 67   */./* beginning
4320: 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20  -of-error-codes 
4330: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4340: 45 5f 45 52 52 4f 52 20 20 20 20 20 20 20 20 31  E_ERROR        1
4350: 20 20 20 2f 2a 20 53 51 4c 20 65 72 72 6f 72 20     /* SQL error 
4360: 6f 72 20 6d 69 73 73 69 6e 67 20 64 61 74 61 62  or missing datab
4370: 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ase */.#define S
4380: 51 4c 49 54 45 5f 49 4e 54 45 52 4e 41 4c 20 20  QLITE_INTERNAL  
4390: 20 20 20 32 20 20 20 2f 2a 20 49 6e 74 65 72 6e     2   /* Intern
43a0: 61 6c 20 6c 6f 67 69 63 20 65 72 72 6f 72 20 69  al logic error i
43b0: 6e 20 53 51 4c 69 74 65 20 2a 2f 0a 23 64 65 66  n SQLite */.#def
43c0: 69 6e 65 20 53 51 4c 49 54 45 5f 50 45 52 4d 20  ine SQLITE_PERM 
43d0: 20 20 20 20 20 20 20 20 33 20 20 20 2f 2a 20 41          3   /* A
43e0: 63 63 65 73 73 20 70 65 72 6d 69 73 73 69 6f 6e  ccess permission
43f0: 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69   denied */.#defi
4400: 6e 65 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 20  ne SQLITE_ABORT 
4410: 20 20 20 20 20 20 20 34 20 20 20 2f 2a 20 43 61         4   /* Ca
4420: 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 72  llback routine r
4430: 65 71 75 65 73 74 65 64 20 61 6e 20 61 62 6f 72  equested an abor
4440: 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  t */.#define SQL
4450: 49 54 45 5f 42 55 53 59 20 20 20 20 20 20 20 20  ITE_BUSY        
4460: 20 35 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61   5   /* The data
4470: 62 61 73 65 20 66 69 6c 65 20 69 73 20 6c 6f 63  base file is loc
4480: 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ked */.#define S
4490: 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 20 20 20  QLITE_LOCKED    
44a0: 20 20 20 36 20 20 20 2f 2a 20 41 20 74 61 62 6c     6   /* A tabl
44b0: 65 20 69 6e 20 74 68 65 20 64 61 74 61 62 61 73  e in the databas
44c0: 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23  e is locked */.#
44d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
44e0: 4d 45 4d 20 20 20 20 20 20 20 20 37 20 20 20 2f  MEM        7   /
44f0: 2a 20 41 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69  * A malloc() fai
4500: 6c 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  led */.#define S
4510: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 20  QLITE_READONLY  
4520: 20 20 20 38 20 20 20 2f 2a 20 41 74 74 65 6d 70     8   /* Attemp
4530: 74 20 74 6f 20 77 72 69 74 65 20 61 20 72 65 61  t to write a rea
4540: 64 6f 6e 6c 79 20 64 61 74 61 62 61 73 65 20 2a  donly database *
4550: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4560: 5f 49 4e 54 45 52 52 55 50 54 20 20 20 20 39 20  _INTERRUPT    9 
4570: 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 74    /* Operation t
4580: 65 72 6d 69 6e 61 74 65 64 20 62 79 20 73 71 6c  erminated by sql
4590: 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
45a0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
45b0: 45 5f 49 4f 45 52 52 20 20 20 20 20 20 20 31 30  E_IOERR       10
45c0: 20 20 20 2f 2a 20 53 6f 6d 65 20 6b 69 6e 64 20     /* Some kind 
45d0: 6f 66 20 64 69 73 6b 20 49 2f 4f 20 65 72 72 6f  of disk I/O erro
45e0: 72 20 6f 63 63 75 72 72 65 64 20 2a 2f 0a 23 64  r occurred */.#d
45f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52  efine SQLITE_COR
4600: 52 55 50 54 20 20 20 20 20 31 31 20 20 20 2f 2a  RUPT     11   /*
4610: 20 54 68 65 20 64 61 74 61 62 61 73 65 20 64 69   The database di
4620: 73 6b 20 69 6d 61 67 65 20 69 73 20 6d 61 6c 66  sk image is malf
4630: 6f 72 6d 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  ormed */.#define
4640: 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44   SQLITE_NOTFOUND
4650: 20 20 20 20 31 32 20 20 20 2f 2a 20 55 6e 6b 6e      12   /* Unkn
4660: 6f 77 6e 20 6f 70 63 6f 64 65 20 69 6e 20 73 71  own opcode in sq
4670: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
4680: 6f 6c 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ol() */.#define 
4690: 53 51 4c 49 54 45 5f 46 55 4c 4c 20 20 20 20 20  SQLITE_FULL     
46a0: 20 20 20 31 33 20 20 20 2f 2a 20 49 6e 73 65 72     13   /* Inser
46b0: 74 69 6f 6e 20 66 61 69 6c 65 64 20 62 65 63 61  tion failed beca
46c0: 75 73 65 20 64 61 74 61 62 61 73 65 20 69 73 20  use database is 
46d0: 66 75 6c 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20  full */.#define 
46e0: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20  SQLITE_CANTOPEN 
46f0: 20 20 20 31 34 20 20 20 2f 2a 20 55 6e 61 62 6c     14   /* Unabl
4700: 65 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 61  e to open the da
4710: 74 61 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23  tabase file */.#
4720: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52  define SQLITE_PR
4730: 4f 54 4f 43 4f 4c 20 20 20 20 31 35 20 20 20 2f  OTOCOL    15   /
4740: 2a 20 44 61 74 61 62 61 73 65 20 6c 6f 63 6b 20  * Database lock 
4750: 70 72 6f 74 6f 63 6f 6c 20 65 72 72 6f 72 20 2a  protocol error *
4760: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4770: 5f 45 4d 50 54 59 20 20 20 20 20 20 20 31 36 20  _EMPTY       16 
4780: 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 69 73    /* Database is
4790: 20 65 6d 70 74 79 20 2a 2f 0a 23 64 65 66 69 6e   empty */.#defin
47a0: 65 20 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 20  e SQLITE_SCHEMA 
47b0: 20 20 20 20 20 31 37 20 20 20 2f 2a 20 54 68 65       17   /* The
47c0: 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61   database schema
47d0: 20 63 68 61 6e 67 65 64 20 2a 2f 0a 23 64 65 66   changed */.#def
47e0: 69 6e 65 20 53 51 4c 49 54 45 5f 54 4f 4f 42 49  ine SQLITE_TOOBI
47f0: 47 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20 53  G      18   /* S
4800: 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 65 78  tring or BLOB ex
4810: 63 65 65 64 73 20 73 69 7a 65 20 6c 69 6d 69 74  ceeds size limit
4820: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4830: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 20 31  TE_CONSTRAINT  1
4840: 39 20 20 20 2f 2a 20 41 62 6f 72 74 20 64 75 65  9   /* Abort due
4850: 20 74 6f 20 63 6f 6e 73 74 72 61 69 6e 74 20 76   to constraint v
4860: 69 6f 6c 61 74 69 6f 6e 20 2a 2f 0a 23 64 65 66  iolation */.#def
4870: 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53 4d 41  ine SQLITE_MISMA
4880: 54 43 48 20 20 20 20 32 30 20 20 20 2f 2a 20 44  TCH    20   /* D
4890: 61 74 61 20 74 79 70 65 20 6d 69 73 6d 61 74 63  ata type mismatc
48a0: 68 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  h */.#define SQL
48b0: 49 54 45 5f 4d 49 53 55 53 45 20 20 20 20 20 20  ITE_MISUSE      
48c0: 32 31 20 20 20 2f 2a 20 4c 69 62 72 61 72 79 20  21   /* Library 
48d0: 75 73 65 64 20 69 6e 63 6f 72 72 65 63 74 6c 79  used incorrectly
48e0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
48f0: 54 45 5f 4e 4f 4c 46 53 20 20 20 20 20 20 20 32  TE_NOLFS       2
4900: 32 20 20 20 2f 2a 20 55 73 65 73 20 4f 53 20 66  2   /* Uses OS f
4910: 65 61 74 75 72 65 73 20 6e 6f 74 20 73 75 70 70  eatures not supp
4920: 6f 72 74 65 64 20 6f 6e 20 68 6f 73 74 20 2a 2f  orted on host */
4930: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4940: 41 55 54 48 20 20 20 20 20 20 20 20 32 33 20 20  AUTH        23  
4950: 20 2f 2a 20 41 75 74 68 6f 72 69 7a 61 74 69 6f   /* Authorizatio
4960: 6e 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66  n denied */.#def
4970: 69 6e 65 20 53 51 4c 49 54 45 5f 46 4f 52 4d 41  ine SQLITE_FORMA
4980: 54 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20 41  T      24   /* A
4990: 75 78 69 6c 69 61 72 79 20 64 61 74 61 62 61 73  uxiliary databas
49a0: 65 20 66 6f 72 6d 61 74 20 65 72 72 6f 72 20 2a  e format error *
49b0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
49c0: 5f 52 41 4e 47 45 20 20 20 20 20 20 20 32 35 20  _RANGE       25 
49d0: 20 20 2f 2a 20 32 6e 64 20 70 61 72 61 6d 65 74    /* 2nd paramet
49e0: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69  er to sqlite3_bi
49f0: 6e 64 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20  nd out of range 
4a00: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4a10: 45 5f 4e 4f 54 41 44 42 20 20 20 20 20 20 32 36  E_NOTADB      26
4a20: 20 20 20 2f 2a 20 46 69 6c 65 20 6f 70 65 6e 65     /* File opene
4a30: 64 20 74 68 61 74 20 69 73 20 6e 6f 74 20 61 20  d that is not a 
4a40: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 2a 2f  database file */
4a50: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4a60: 4e 4f 54 49 43 45 20 20 20 20 20 20 32 37 20 20  NOTICE      27  
4a70: 20 2f 2a 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e   /* Notification
4a80: 73 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6c  s from sqlite3_l
4a90: 6f 67 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  og() */.#define 
4aa0: 53 51 4c 49 54 45 5f 57 41 52 4e 49 4e 47 20 20  SQLITE_WARNING  
4ab0: 20 20 20 32 38 20 20 20 2f 2a 20 57 61 72 6e 69     28   /* Warni
4ac0: 6e 67 73 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  ngs from sqlite3
4ad0: 5f 6c 6f 67 28 29 20 2a 2f 0a 23 64 65 66 69 6e  _log() */.#defin
4ae0: 65 20 53 51 4c 49 54 45 5f 52 4f 57 20 20 20 20  e SQLITE_ROW    
4af0: 20 20 20 20 20 31 30 30 20 20 2f 2a 20 73 71 6c       100  /* sql
4b00: 69 74 65 33 5f 73 74 65 70 28 29 20 68 61 73 20  ite3_step() has 
4b10: 61 6e 6f 74 68 65 72 20 72 6f 77 20 72 65 61 64  another row read
4b20: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
4b30: 49 54 45 5f 44 4f 4e 45 20 20 20 20 20 20 20 20  ITE_DONE        
4b40: 31 30 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f  101  /* sqlite3_
4b50: 73 74 65 70 28 29 20 68 61 73 20 66 69 6e 69 73  step() has finis
4b60: 68 65 64 20 65 78 65 63 75 74 69 6e 67 20 2a 2f  hed executing */
4b70: 0a 2f 2a 20 65 6e 64 2d 6f 66 2d 65 72 72 6f 72  ./* end-of-error
4b80: 2d 63 6f 64 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a  -codes */../*.**
4b90: 20 43 41 50 49 33 52 45 46 3a 20 45 78 74 65 6e   CAPI3REF: Exten
4ba0: 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73  ded Result Codes
4bb0: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 65  .** KEYWORDS: {e
4bc0: 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f  xtended error co
4bd0: 64 65 7d 20 7b 65 78 74 65 6e 64 65 64 20 65 72  de} {extended er
4be0: 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45  ror codes}.** KE
4bf0: 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e 64 65  YWORDS: {extende
4c00: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 7d 20 7b  d result code} {
4c10: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
4c20: 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20  codes}.**.** In 
4c30: 69 74 73 20 64 65 66 61 75 6c 74 20 63 6f 6e 66  its default conf
4c40: 69 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69 74  iguration, SQLit
4c50: 65 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20 72  e API routines r
4c60: 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 32 36 20  eturn one of 26 
4c70: 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 53 51 4c 49  integer.** [SQLI
4c80: 54 45 5f 4f 4b 20 7c 20 72 65 73 75 6c 74 20 63  TE_OK | result c
4c90: 6f 64 65 73 5d 2e 20 20 48 6f 77 65 76 65 72 2c  odes].  However,
4ca0: 20 65 78 70 65 72 69 65 6e 63 65 20 68 61 73 20   experience has 
4cb0: 73 68 6f 77 6e 20 74 68 61 74 20 6d 61 6e 79 20  shown that many 
4cc0: 6f 66 0a 2a 2a 20 74 68 65 73 65 20 72 65 73 75  of.** these resu
4cd0: 6c 74 20 63 6f 64 65 73 20 61 72 65 20 74 6f 6f  lt codes are too
4ce0: 20 63 6f 61 72 73 65 2d 67 72 61 69 6e 65 64 2e   coarse-grained.
4cf0: 20 20 54 68 65 79 20 64 6f 20 6e 6f 74 20 70 72    They do not pr
4d00: 6f 76 69 64 65 20 61 73 0a 2a 2a 20 6d 75 63 68  ovide as.** much
4d10: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f   information abo
4d20: 75 74 20 70 72 6f 62 6c 65 6d 73 20 61 73 20 70  ut problems as p
4d30: 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 68 74  rogrammers might
4d40: 20 6c 69 6b 65 2e 20 20 49 6e 20 61 6e 20 65 66   like.  In an ef
4d50: 66 6f 72 74 20 74 6f 0a 2a 2a 20 61 64 64 72 65  fort to.** addre
4d60: 73 73 20 74 68 69 73 2c 20 6e 65 77 65 72 20 76  ss this, newer v
4d70: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
4d80: 65 20 28 76 65 72 73 69 6f 6e 20 33 2e 33 2e 38  e (version 3.3.8
4d90: 20 61 6e 64 20 6c 61 74 65 72 29 20 69 6e 63 6c   and later) incl
4da0: 75 64 65 0a 2a 2a 20 73 75 70 70 6f 72 74 20 66  ude.** support f
4db0: 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 72 65  or additional re
4dc0: 73 75 6c 74 20 63 6f 64 65 73 20 74 68 61 74 20  sult codes that 
4dd0: 70 72 6f 76 69 64 65 20 6d 6f 72 65 20 64 65 74  provide more det
4de0: 61 69 6c 65 64 20 69 6e 66 6f 72 6d 61 74 69 6f  ailed informatio
4df0: 6e 0a 2a 2a 20 61 62 6f 75 74 20 65 72 72 6f 72  n.** about error
4e00: 73 2e 20 54 68 65 20 65 78 74 65 6e 64 65 64 20  s. The extended 
4e10: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65  result codes are
4e20: 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61   enabled or disa
4e30: 62 6c 65 64 0a 2a 2a 20 6f 6e 20 61 20 70 65 72  bled.** on a per
4e40: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
4e50: 74 69 6f 6e 20 62 61 73 69 73 20 75 73 69 6e 67  tion basis using
4e60: 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
4e70: 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74  _extended_result
4e80: 5f 63 6f 64 65 73 28 29 5d 20 41 50 49 2e 0a 2a  _codes()] API..*
4e90: 2a 0a 2a 2a 20 53 6f 6d 65 20 6f 66 20 74 68 65  *.** Some of the
4ea0: 20 61 76 61 69 6c 61 62 6c 65 20 65 78 74 65 6e   available exten
4eb0: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
4ec0: 20 61 72 65 20 6c 69 73 74 65 64 20 68 65 72 65   are listed here
4ed0: 2e 0a 2a 2a 20 4f 6e 65 20 6d 61 79 20 65 78 70  ..** One may exp
4ee0: 65 63 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  ect the number o
4ef0: 66 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c  f extended resul
4f00: 74 20 63 6f 64 65 73 20 77 69 6c 6c 20 69 6e 63  t codes will inc
4f10: 72 65 61 73 65 0a 2a 2a 20 6f 76 65 72 20 74 69  rease.** over ti
4f20: 6d 65 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68  me.  Software th
4f30: 61 74 20 75 73 65 73 20 65 78 74 65 6e 64 65 64  at uses extended
4f40: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 73 68   result codes sh
4f50: 6f 75 6c 64 20 65 78 70 65 63 74 0a 2a 2a 20 74  ould expect.** t
4f60: 6f 20 73 65 65 20 6e 65 77 20 72 65 73 75 6c 74  o see new result
4f70: 20 63 6f 64 65 73 20 69 6e 20 66 75 74 75 72 65   codes in future
4f80: 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c   releases of SQL
4f90: 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53  ite..**.** The S
4fa0: 51 4c 49 54 45 5f 4f 4b 20 72 65 73 75 6c 74 20  QLITE_OK result 
4fb0: 63 6f 64 65 20 77 69 6c 6c 20 6e 65 76 65 72 20  code will never 
4fc0: 62 65 20 65 78 74 65 6e 64 65 64 2e 20 20 49 74  be extended.  It
4fd0: 20 77 69 6c 6c 20 61 6c 77 61 79 73 0a 2a 2a 20   will always.** 
4fe0: 62 65 20 65 78 61 63 74 6c 79 20 7a 65 72 6f 2e  be exactly zero.
4ff0: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
5000: 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 20 20  TE_IOERR_READ   
5010: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
5020: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 3c 3c 38  TE_IOERR | (1<<8
5030: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5040: 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45  E_IOERR_SHORT_RE
5050: 41 44 20 20 20 20 20 20 20 20 28 53 51 4c 49 54  AD        (SQLIT
5060: 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c 3c 38 29  E_IOERR | (2<<8)
5070: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5080: 5f 49 4f 45 52 52 5f 57 52 49 54 45 20 20 20 20  _IOERR_WRITE    
5090: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
50a0: 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c 38 29 29  _IOERR | (3<<8))
50b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
50c0: 49 4f 45 52 52 5f 46 53 59 4e 43 20 20 20 20 20  IOERR_FSYNC     
50d0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
50e0: 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38 29 29 0a  IOERR | (4<<8)).
50f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5100: 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e 43 20 20  OERR_DIR_FSYNC  
5110: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
5120: 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29 29 0a 23  OERR | (5<<8)).#
5130: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5140: 45 52 52 5f 54 52 55 4e 43 41 54 45 20 20 20 20  ERR_TRUNCATE    
5150: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5160: 45 52 52 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64  ERR | (6<<8)).#d
5170: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5180: 52 52 5f 46 53 54 41 54 20 20 20 20 20 20 20 20  RR_FSTAT        
5190: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
51a0: 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65  RR | (7<<8)).#de
51b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
51c0: 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20  R_UNLOCK        
51d0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
51e0: 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65 66  R | (8<<8)).#def
51f0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5200: 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20 20 20 20  _RDLOCK         
5210: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5220: 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66 69   | (9<<8)).#defi
5230: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5240: 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20 20  DELETE          
5250: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5260: 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64 65 66 69  | (10<<8)).#defi
5270: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5280: 42 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 20 20  BLOCKED         
5290: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
52a0: 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64 65 66 69  | (11<<8)).#defi
52b0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
52c0: 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 20 20 20  NOMEM           
52d0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
52e0: 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64 65 66 69  | (12<<8)).#defi
52f0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5300: 41 43 43 45 53 53 20 20 20 20 20 20 20 20 20 20  ACCESS          
5310: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5320: 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64 65 66 69  | (13<<8)).#defi
5330: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5340: 43 48 45 43 4b 52 45 53 45 52 56 45 44 4c 4f 43  CHECKRESERVEDLOC
5350: 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20  K (SQLITE_IOERR 
5360: 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64 65 66 69  | (14<<8)).#defi
5370: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5380: 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 20  LOCK            
5390: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
53a0: 7c 20 28 31 35 3c 3c 38 29 29 0a 23 64 65 66 69  | (15<<8)).#defi
53b0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
53c0: 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20 20 20  CLOSE           
53d0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
53e0: 7c 20 28 31 36 3c 3c 38 29 29 0a 23 64 65 66 69  | (16<<8)).#defi
53f0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5400: 44 49 52 5f 43 4c 4f 53 45 20 20 20 20 20 20 20  DIR_CLOSE       
5410: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5420: 7c 20 28 31 37 3c 3c 38 29 29 0a 23 64 65 66 69  | (17<<8)).#defi
5430: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5440: 53 48 4d 4f 50 45 4e 20 20 20 20 20 20 20 20 20  SHMOPEN         
5450: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5460: 7c 20 28 31 38 3c 3c 38 29 29 0a 23 64 65 66 69  | (18<<8)).#defi
5470: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5480: 53 48 4d 53 49 5a 45 20 20 20 20 20 20 20 20 20  SHMSIZE         
5490: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
54a0: 7c 20 28 31 39 3c 3c 38 29 29 0a 23 64 65 66 69  | (19<<8)).#defi
54b0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
54c0: 53 48 4d 4c 4f 43 4b 20 20 20 20 20 20 20 20 20  SHMLOCK         
54d0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
54e0: 7c 20 28 32 30 3c 3c 38 29 29 0a 23 64 65 66 69  | (20<<8)).#defi
54f0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5500: 53 48 4d 4d 41 50 20 20 20 20 20 20 20 20 20 20  SHMMAP          
5510: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5520: 7c 20 28 32 31 3c 3c 38 29 29 0a 23 64 65 66 69  | (21<<8)).#defi
5530: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5540: 53 45 45 4b 20 20 20 20 20 20 20 20 20 20 20 20  SEEK            
5550: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5560: 7c 20 28 32 32 3c 3c 38 29 29 0a 23 64 65 66 69  | (22<<8)).#defi
5570: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5580: 44 45 4c 45 54 45 5f 4e 4f 45 4e 54 20 20 20 20  DELETE_NOENT    
5590: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
55a0: 7c 20 28 32 33 3c 3c 38 29 29 0a 23 64 65 66 69  | (23<<8)).#defi
55b0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
55c0: 4d 4d 41 50 20 20 20 20 20 20 20 20 20 20 20 20  MMAP            
55d0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
55e0: 7c 20 28 32 34 3c 3c 38 29 29 0a 23 64 65 66 69  | (24<<8)).#defi
55f0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5600: 47 45 54 54 45 4d 50 50 41 54 48 20 20 20 20 20  GETTEMPPATH     
5610: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5620: 7c 20 28 32 35 3c 3c 38 29 29 0a 23 64 65 66 69  | (25<<8)).#defi
5630: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5640: 43 4f 4e 56 50 41 54 48 20 20 20 20 20 20 20 20  CONVPATH        
5650: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5660: 7c 20 28 32 36 3c 3c 38 29 29 0a 23 64 65 66 69  | (26<<8)).#defi
5670: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44  ne SQLITE_LOCKED
5680: 5f 53 48 41 52 45 44 43 41 43 48 45 20 20 20 20  _SHAREDCACHE    
5690: 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44    (SQLITE_LOCKED
56a0: 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65 66   |  (1<<8)).#def
56b0: 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59 5f  ine SQLITE_BUSY_
56c0: 52 45 43 4f 56 45 52 59 20 20 20 20 20 20 20 20  RECOVERY        
56d0: 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53 59 20     (SQLITE_BUSY 
56e0: 20 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65    |  (1<<8)).#de
56f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59  fine SQLITE_BUSY
5700: 5f 53 4e 41 50 53 48 4f 54 20 20 20 20 20 20 20  _SNAPSHOT       
5710: 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53 59      (SQLITE_BUSY
5720: 20 20 20 7c 20 20 28 32 3c 3c 38 29 29 0a 23 64     |  (2<<8)).#d
5730: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e  efine SQLITE_CAN
5740: 54 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44 49 52 20  TOPEN_NOTEMPDIR 
5750: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e       (SQLITE_CAN
5760: 54 4f 50 45 4e 20 7c 20 28 31 3c 3c 38 29 29 0a  TOPEN | (1<<8)).
5770: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
5780: 41 4e 54 4f 50 45 4e 5f 49 53 44 49 52 20 20 20  ANTOPEN_ISDIR   
5790: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43         (SQLITE_C
57a0: 41 4e 54 4f 50 45 4e 20 7c 20 28 32 3c 3c 38 29  ANTOPEN | (2<<8)
57b0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
57c0: 5f 43 41 4e 54 4f 50 45 4e 5f 46 55 4c 4c 50 41  _CANTOPEN_FULLPA
57d0: 54 48 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  TH       (SQLITE
57e0: 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 33 3c 3c  _CANTOPEN | (3<<
57f0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5800: 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 43 4f 4e 56  TE_CANTOPEN_CONV
5810: 50 41 54 48 20 20 20 20 20 20 20 28 53 51 4c 49  PATH       (SQLI
5820: 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 34  TE_CANTOPEN | (4
5830: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5840: 4c 49 54 45 5f 43 4f 52 52 55 50 54 5f 56 54 41  LITE_CORRUPT_VTA
5850: 42 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51  B            (SQ
5860: 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 7c 20 28  LITE_CORRUPT | (
5870: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
5880: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 52  QLITE_READONLY_R
5890: 45 43 4f 56 45 52 59 20 20 20 20 20 20 20 28 53  ECOVERY       (S
58a0: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c  QLITE_READONLY |
58b0: 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (1<<8)).#define
58c0: 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59   SQLITE_READONLY
58d0: 5f 43 41 4e 54 4c 4f 43 4b 20 20 20 20 20 20 20  _CANTLOCK       
58e0: 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59  (SQLITE_READONLY
58f0: 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69   | (2<<8)).#defi
5900: 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e  ne SQLITE_READON
5910: 4c 59 5f 52 4f 4c 4c 42 41 43 4b 20 20 20 20 20  LY_ROLLBACK     
5920: 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e    (SQLITE_READON
5930: 4c 59 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65  LY | (3<<8)).#de
5940: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44  fine SQLITE_READ
5950: 4f 4e 4c 59 5f 44 42 4d 4f 56 45 44 20 20 20 20  ONLY_DBMOVED    
5960: 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44      (SQLITE_READ
5970: 4f 4e 4c 59 20 7c 20 28 34 3c 3c 38 29 29 0a 23  ONLY | (4<<8)).#
5980: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 42  define SQLITE_AB
5990: 4f 52 54 5f 52 4f 4c 4c 42 41 43 4b 20 20 20 20  ORT_ROLLBACK    
59a0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 41 42        (SQLITE_AB
59b0: 4f 52 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64  ORT | (2<<8)).#d
59c0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
59d0: 53 54 52 41 49 4e 54 5f 43 48 45 43 4b 20 20 20  STRAINT_CHECK   
59e0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e       (SQLITE_CON
59f0: 53 54 52 41 49 4e 54 20 7c 20 28 31 3c 3c 38 29  STRAINT | (1<<8)
5a00: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5a10: 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 43 4f 4d 4d  _CONSTRAINT_COMM
5a20: 49 54 48 4f 4f 4b 20 20 20 28 53 51 4c 49 54 45  ITHOOK   (SQLITE
5a30: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 32  _CONSTRAINT | (2
5a40: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5a50: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  LITE_CONSTRAINT_
5a60: 46 4f 52 45 49 47 4e 4b 45 59 20 20 20 28 53 51  FOREIGNKEY   (SQ
5a70: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20  LITE_CONSTRAINT 
5a80: 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (3<<8)).#defin
5a90: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
5aa0: 49 4e 54 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20  INT_FUNCTION    
5ab0: 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41   (SQLITE_CONSTRA
5ac0: 49 4e 54 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64  INT | (4<<8)).#d
5ad0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
5ae0: 53 54 52 41 49 4e 54 5f 4e 4f 54 4e 55 4c 4c 20  STRAINT_NOTNULL 
5af0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e       (SQLITE_CON
5b00: 53 54 52 41 49 4e 54 20 7c 20 28 35 3c 3c 38 29  STRAINT | (5<<8)
5b10: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5b20: 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 50 52 49 4d  _CONSTRAINT_PRIM
5b30: 41 52 59 4b 45 59 20 20 20 28 53 51 4c 49 54 45  ARYKEY   (SQLITE
5b40: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 36  _CONSTRAINT | (6
5b50: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5b60: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  LITE_CONSTRAINT_
5b70: 54 52 49 47 47 45 52 20 20 20 20 20 20 28 53 51  TRIGGER      (SQ
5b80: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20  LITE_CONSTRAINT 
5b90: 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (7<<8)).#defin
5ba0: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
5bb0: 49 4e 54 5f 55 4e 49 51 55 45 20 20 20 20 20 20  INT_UNIQUE      
5bc0: 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41   (SQLITE_CONSTRA
5bd0: 49 4e 54 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64  INT | (8<<8)).#d
5be0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
5bf0: 53 54 52 41 49 4e 54 5f 56 54 41 42 20 20 20 20  STRAINT_VTAB    
5c00: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e       (SQLITE_CON
5c10: 53 54 52 41 49 4e 54 20 7c 20 28 39 3c 3c 38 29  STRAINT | (9<<8)
5c20: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5c30: 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 52 4f 57 49  _CONSTRAINT_ROWI
5c40: 44 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  D        (SQLITE
5c50: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 28 31 30  _CONSTRAINT |(10
5c60: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5c70: 4c 49 54 45 5f 4e 4f 54 49 43 45 5f 52 45 43 4f  LITE_NOTICE_RECO
5c80: 56 45 52 5f 57 41 4c 20 20 20 20 20 20 28 53 51  VER_WAL      (SQ
5c90: 4c 49 54 45 5f 4e 4f 54 49 43 45 20 7c 20 28 31  LITE_NOTICE | (1
5ca0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5cb0: 4c 49 54 45 5f 4e 4f 54 49 43 45 5f 52 45 43 4f  LITE_NOTICE_RECO
5cc0: 56 45 52 5f 52 4f 4c 4c 42 41 43 4b 20 28 53 51  VER_ROLLBACK (SQ
5cd0: 4c 49 54 45 5f 4e 4f 54 49 43 45 20 7c 20 28 32  LITE_NOTICE | (2
5ce0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5cf0: 4c 49 54 45 5f 57 41 52 4e 49 4e 47 5f 41 55 54  LITE_WARNING_AUT
5d00: 4f 49 4e 44 45 58 20 20 20 20 20 20 20 28 53 51  OINDEX       (SQ
5d10: 4c 49 54 45 5f 57 41 52 4e 49 4e 47 20 7c 20 28  LITE_WARNING | (
5d20: 31 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43 41  1<<8))../*.** CA
5d30: 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 46 6f  PI3REF: Flags Fo
5d40: 72 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65 72  r File Open Oper
5d50: 61 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65  ations.**.** The
5d60: 73 65 20 62 69 74 20 76 61 6c 75 65 73 20 61 72  se bit values ar
5d70: 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75  e intended for u
5d80: 73 65 20 69 6e 20 74 68 65 0a 2a 2a 20 33 72 64  se in the.** 3rd
5d90: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
5da0: 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  e [sqlite3_open_
5db0: 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  v2()] interface 
5dc0: 61 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20 34 74  and.** in the 4t
5dd0: 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
5de0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  he [sqlite3_vfs.
5df0: 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 2e 0a 2a  xOpen] method..*
5e00: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
5e10: 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 20  _OPEN_READONLY  
5e20: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30         0x0000000
5e30: 31 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  1  /* Ok for sql
5e40: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
5e50: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
5e60: 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20  _OPEN_READWRITE 
5e70: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30         0x0000000
5e80: 32 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  2  /* Ok for sql
5e90: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
5ea0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
5eb0: 5f 4f 50 45 4e 5f 43 52 45 41 54 45 20 20 20 20  _OPEN_CREATE    
5ec0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30         0x0000000
5ed0: 34 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  4  /* Ok for sql
5ee0: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
5ef0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
5f00: 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c  _OPEN_DELETEONCL
5f10: 4f 53 45 20 20 20 20 30 78 30 30 30 30 30 30 30  OSE    0x0000000
5f20: 38 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  8  /* VFS only *
5f30: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
5f40: 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20  _OPEN_EXCLUSIVE 
5f50: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 31         0x0000001
5f60: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
5f70: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
5f80: 5f 4f 50 45 4e 5f 41 55 54 4f 50 52 4f 58 59 20  _OPEN_AUTOPROXY 
5f90: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 32         0x0000002
5fa0: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
5fb0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
5fc0: 5f 4f 50 45 4e 5f 55 52 49 20 20 20 20 20 20 20  _OPEN_URI       
5fd0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 34         0x0000004
5fe0: 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  0  /* Ok for sql
5ff0: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
6000: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6010: 5f 4f 50 45 4e 5f 4d 45 4d 4f 52 59 20 20 20 20  _OPEN_MEMORY    
6020: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 38         0x0000008
6030: 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  0  /* Ok for sql
6040: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
6050: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6060: 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20 20 20  _OPEN_MAIN_DB   
6070: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 31 30         0x0000010
6080: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
6090: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
60a0: 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20 20 20  _OPEN_TEMP_DB   
60b0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 32 30         0x0000020
60c0: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
60d0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
60e0: 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f  _OPEN_TRANSIENT_
60f0: 44 42 20 20 20 20 20 30 78 30 30 30 30 30 34 30  DB     0x0000040
6100: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
6110: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6120: 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e  _OPEN_MAIN_JOURN
6130: 41 4c 20 20 20 20 20 30 78 30 30 30 30 30 38 30  AL     0x0000080
6140: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
6150: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6160: 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e  _OPEN_TEMP_JOURN
6170: 41 4c 20 20 20 20 20 30 78 30 30 30 30 31 30 30  AL     0x0000100
6180: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
6190: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
61a0: 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c  _OPEN_SUBJOURNAL
61b0: 20 20 20 20 20 20 20 30 78 30 30 30 30 32 30 30         0x0000200
61c0: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
61d0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
61e0: 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55  _OPEN_MASTER_JOU
61f0: 52 4e 41 4c 20 20 20 30 78 30 30 30 30 34 30 30  RNAL   0x0000400
6200: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
6210: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6220: 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 20 20 20  _OPEN_NOMUTEX   
6230: 20 20 20 20 20 20 20 30 78 30 30 30 30 38 30 30         0x0000800
6240: 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  0  /* Ok for sql
6250: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
6260: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6270: 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 20  _OPEN_FULLMUTEX 
6280: 20 20 20 20 20 20 20 30 78 30 30 30 31 30 30 30         0x0001000
6290: 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  0  /* Ok for sql
62a0: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
62b0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
62c0: 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48  _OPEN_SHAREDCACH
62d0: 45 20 20 20 20 20 20 30 78 30 30 30 32 30 30 30  E      0x0002000
62e0: 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  0  /* Ok for sql
62f0: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
6300: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6310: 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43  _OPEN_PRIVATECAC
6320: 48 45 20 20 20 20 20 30 78 30 30 30 34 30 30 30  HE     0x0004000
6330: 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  0  /* Ok for sql
6340: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
6350: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6360: 5f 4f 50 45 4e 5f 57 41 4c 20 20 20 20 20 20 20  _OPEN_WAL       
6370: 20 20 20 20 20 20 20 30 78 30 30 30 38 30 30 30         0x0008000
6380: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
6390: 2f 0a 0a 2f 2a 20 52 65 73 65 72 76 65 64 3a 20  /../* Reserved: 
63a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
63b0: 20 20 20 20 20 20 20 20 30 78 30 30 46 30 30 30          0x00F000
63c0: 30 30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  00 */../*.** CAP
63d0: 49 33 52 45 46 3a 20 44 65 76 69 63 65 20 43 68  I3REF: Device Ch
63e0: 61 72 61 63 74 65 72 69 73 74 69 63 73 0a 2a 2a  aracteristics.**
63f0: 0a 2a 2a 20 54 68 65 20 78 44 65 76 69 63 65 43  .** The xDeviceC
6400: 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20 6d  haracteristics m
6410: 65 74 68 6f 64 20 6f 66 20 74 68 65 20 5b 73 71  ethod of the [sq
6420: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
6430: 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74 75  ].** object retu
6440: 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77  rns an integer w
6450: 68 69 63 68 20 69 73 20 61 20 76 65 63 74 6f 72  hich is a vector
6460: 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 62 69 74   of these.** bit
6470: 20 76 61 6c 75 65 73 20 65 78 70 72 65 73 73 69   values expressi
6480: 6e 67 20 49 2f 4f 20 63 68 61 72 61 63 74 65 72  ng I/O character
6490: 69 73 74 69 63 73 20 6f 66 20 74 68 65 20 6d 61  istics of the ma
64a0: 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20 64 65  ss storage.** de
64b0: 76 69 63 65 20 74 68 61 74 20 68 6f 6c 64 73 20  vice that holds 
64c0: 74 68 65 20 66 69 6c 65 20 74 68 61 74 20 74 68  the file that th
64d0: 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  e [sqlite3_io_me
64e0: 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65 72 73  thods].** refers
64f0: 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53   to..**.** The S
6500: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
6510: 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e  IC property mean
6520: 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65  s that all write
6530: 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65  s of.** any size
6540: 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68   are atomic.  Th
6550: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
6560: 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a  TOMICnnn values.
6570: 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69  ** mean that wri
6580: 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68  tes of blocks th
6590: 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73  at are nnn bytes
65a0: 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20   in size and.** 
65b0: 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61  are aligned to a
65c0: 6e 20 61 64 64 72 65 73 73 20 77 68 69 63 68 20  n address which 
65d0: 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75  is an integer mu
65e0: 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e  ltiple of.** nnn
65f0: 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68   are atomic.  Th
6600: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53  e SQLITE_IOCAP_S
6610: 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65  AFE_APPEND value
6620: 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77   means.** that w
6630: 68 65 6e 20 64 61 74 61 20 69 73 20 61 70 70 65  hen data is appe
6640: 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20  nded to a file, 
6650: 74 68 65 20 64 61 74 61 20 69 73 20 61 70 70 65  the data is appe
6660: 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68  nded.** first th
6670: 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  en the size of t
6680: 68 65 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e  he file is exten
6690: 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f  ded, never the o
66a0: 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75  ther.** way arou
66b0: 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  nd.  The SQLITE_
66c0: 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c  IOCAP_SEQUENTIAL
66d0: 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20   property means 
66e0: 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74  that.** informat
66f0: 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74  ion is written t
6700: 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61  o disk in the sa
6710: 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c  me order as call
6720: 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29  s.** to xWrite()
6730: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
6740: 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56  CAP_POWERSAFE_OV
6750: 45 52 57 52 49 54 45 20 70 72 6f 70 65 72 74 79  ERWRITE property
6760: 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 61   means that.** a
6770: 66 74 65 72 20 72 65 62 6f 6f 74 20 66 6f 6c 6c  fter reboot foll
6780: 6f 77 69 6e 67 20 61 20 63 72 61 73 68 20 6f 72  owing a crash or
6790: 20 70 6f 77 65 72 20 6c 6f 73 73 2c 20 74 68 65   power loss, the
67a0: 20 6f 6e 6c 79 20 62 79 74 65 73 20 69 6e 20 61   only bytes in a
67b0: 0a 2a 2a 20 66 69 6c 65 20 74 68 61 74 20 77 65  .** file that we
67c0: 72 65 20 77 72 69 74 74 65 6e 20 61 74 20 74 68  re written at th
67d0: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6c 65  e application le
67e0: 76 65 6c 20 6d 69 67 68 74 20 68 61 76 65 20 63  vel might have c
67f0: 68 61 6e 67 65 64 0a 2a 2a 20 61 6e 64 20 74 68  hanged.** and th
6800: 61 74 20 61 64 6a 61 63 65 6e 74 20 62 79 74 65  at adjacent byte
6810: 73 2c 20 65 76 65 6e 20 62 79 74 65 73 20 77 69  s, even bytes wi
6820: 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20 73 65  thin the same se
6830: 63 74 6f 72 20 61 72 65 0a 2a 2a 20 67 75 61 72  ctor are.** guar
6840: 61 6e 74 65 65 64 20 74 6f 20 62 65 20 75 6e 63  anteed to be unc
6850: 68 61 6e 67 65 64 2e 20 20 54 68 65 20 53 51 4c  hanged.  The SQL
6860: 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45  ITE_IOCAP_UNDELE
6870: 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 0a  TABLE_WHEN_OPEN.
6880: 2a 2a 20 66 6c 61 67 20 69 6e 64 69 63 61 74 65  ** flag indicate
6890: 20 74 68 61 74 20 61 20 66 69 6c 65 20 63 61 6e   that a file can
68a0: 6e 6f 74 20 62 65 20 64 65 6c 65 74 65 64 20 77  not be deleted w
68b0: 68 65 6e 20 6f 70 65 6e 2e 0a 2a 2f 0a 23 64 65  hen open..*/.#de
68c0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
68d0: 50 5f 41 54 4f 4d 49 43 20 20 20 20 20 20 20 20  P_ATOMIC        
68e0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
68f0: 30 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  001.#define SQLI
6900: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35  TE_IOCAP_ATOMIC5
6910: 31 32 20 20 20 20 20 20 20 20 20 20 20 20 20 20  12              
6920: 30 78 30 30 30 30 30 30 30 32 0a 23 64 65 66 69  0x00000002.#defi
6930: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
6940: 41 54 4f 4d 49 43 31 4b 20 20 20 20 20 20 20 20  ATOMIC1K        
6950: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30         0x0000000
6960: 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
6970: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 20  _IOCAP_ATOMIC2K 
6980: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
6990: 30 30 30 30 30 30 30 38 0a 23 64 65 66 69 6e 65  00000008.#define
69a0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
69b0: 4f 4d 49 43 34 4b 20 20 20 20 20 20 20 20 20 20  OMIC4K          
69c0: 20 20 20 20 20 30 78 30 30 30 30 30 30 31 30 0a       0x00000010.
69d0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
69e0: 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 20 20 20  OCAP_ATOMIC8K   
69f0: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
6a00: 30 30 30 30 32 30 0a 23 64 65 66 69 6e 65 20 53  000020.#define S
6a10: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
6a20: 49 43 31 36 4b 20 20 20 20 20 20 20 20 20 20 20  IC16K           
6a30: 20 20 20 30 78 30 30 30 30 30 30 34 30 0a 23 64     0x00000040.#d
6a40: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
6a50: 41 50 5f 41 54 4f 4d 49 43 33 32 4b 20 20 20 20  AP_ATOMIC32K    
6a60: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
6a70: 30 30 38 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0080.#define SQL
6a80: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
6a90: 36 34 4b 20 20 20 20 20 20 20 20 20 20 20 20 20  64K             
6aa0: 20 30 78 30 30 30 30 30 31 30 30 0a 23 64 65 66   0x00000100.#def
6ab0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
6ac0: 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 20 20 20  _SAFE_APPEND    
6ad0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 32          0x000002
6ae0: 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  00.#define SQLIT
6af0: 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49  E_IOCAP_SEQUENTI
6b00: 41 4c 20 20 20 20 20 20 20 20 20 20 20 20 20 30  AL             0
6b10: 78 30 30 30 30 30 34 30 30 0a 23 64 65 66 69 6e  x00000400.#defin
6b20: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55  e SQLITE_IOCAP_U
6b30: 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f  NDELETABLE_WHEN_
6b40: 4f 50 45 4e 20 20 30 78 30 30 30 30 30 38 30 30  OPEN  0x00000800
6b50: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6b60: 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f  IOCAP_POWERSAFE_
6b70: 4f 56 45 52 57 52 49 54 45 20 20 20 20 30 78 30  OVERWRITE    0x0
6b80: 30 30 30 31 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 43  0001000../*.** C
6b90: 41 50 49 33 52 45 46 3a 20 46 69 6c 65 20 4c 6f  API3REF: File Lo
6ba0: 63 6b 69 6e 67 20 4c 65 76 65 6c 73 0a 2a 2a 0a  cking Levels.**.
6bb0: 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 6f  ** SQLite uses o
6bc0: 6e 65 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65  ne of these inte
6bd0: 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68  ger values as th
6be0: 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 75  e second.** argu
6bf0: 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73 20 69 74  ment to calls it
6c00: 20 6d 61 6b 65 73 20 74 6f 20 74 68 65 20 78 4c   makes to the xL
6c10: 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63  ock() and xUnloc
6c20: 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f  k() methods.** o
6c30: 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f  f an [sqlite3_io
6c40: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
6c50: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
6c60: 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20  ITE_LOCK_NONE   
6c70: 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65         0.#define
6c80: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41   SQLITE_LOCK_SHA
6c90: 52 45 44 20 20 20 20 20 20 20 20 31 0a 23 64 65  RED        1.#de
6ca0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
6cb0: 5f 52 45 53 45 52 56 45 44 20 20 20 20 20 20 32  _RESERVED      2
6cc0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6cd0: 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 20 20 20  LOCK_PENDING    
6ce0: 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c     3.#define SQL
6cf0: 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49  ITE_LOCK_EXCLUSI
6d00: 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20  VE     4../*.** 
6d10: 43 41 50 49 33 52 45 46 3a 20 53 79 6e 63 68 72  CAPI3REF: Synchr
6d20: 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70 65 20 46  onization Type F
6d30: 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20  lags.**.** When 
6d40: 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20 74  SQLite invokes t
6d50: 68 65 20 78 53 79 6e 63 28 29 20 6d 65 74 68 6f  he xSync() metho
6d60: 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69  d of an.** [sqli
6d70: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
6d80: 6f 62 6a 65 63 74 20 69 74 20 75 73 65 73 20 61  object it uses a
6d90: 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a   combination of.
6da0: 2a 2a 20 74 68 65 73 65 20 69 6e 74 65 67 65 72  ** these integer
6db0: 20 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 73   values as the s
6dc0: 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a  econd argument..
6dd0: 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 53  **.** When the S
6de0: 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f  QLITE_SYNC_DATAO
6df0: 4e 4c 59 20 66 6c 61 67 20 69 73 20 75 73 65 64  NLY flag is used
6e00: 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20  , it means that 
6e10: 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f 70 65 72  the.** sync oper
6e20: 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64 73  ation only needs
6e30: 20 74 6f 20 66 6c 75 73 68 20 64 61 74 61 20 74   to flush data t
6e40: 6f 20 6d 61 73 73 20 73 74 6f 72 61 67 65 2e 20  o mass storage. 
6e50: 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d   Inode.** inform
6e60: 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f 74 20 62  ation need not b
6e70: 65 20 66 6c 75 73 68 65 64 2e 20 49 66 20 74 68  e flushed. If th
6e80: 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74  e lower four bit
6e90: 73 20 6f 66 20 74 68 65 20 66 6c 61 67 0a 2a 2a  s of the flag.**
6ea0: 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59   equal SQLITE_SY
6eb0: 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68 61 74 20  NC_NORMAL, that 
6ec0: 6d 65 61 6e 73 20 74 6f 20 75 73 65 20 6e 6f 72  means to use nor
6ed0: 6d 61 6c 20 66 73 79 6e 63 28 29 20 73 65 6d 61  mal fsync() sema
6ee0: 6e 74 69 63 73 2e 0a 2a 2a 20 49 66 20 74 68 65  ntics..** If the
6ef0: 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74 73   lower four bits
6f00: 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59   equal SQLITE_SY
6f10: 4e 43 5f 46 55 4c 4c 2c 20 74 68 61 74 20 6d 65  NC_FULL, that me
6f20: 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65 20 4d 61  ans.** to use Ma
6f30: 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c  c OS X style ful
6f40: 6c 73 79 6e 63 20 69 6e 73 74 65 61 64 20 6f 66  lsync instead of
6f50: 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a 20   fsync()..**.** 
6f60: 44 6f 20 6e 6f 74 20 63 6f 6e 66 75 73 65 20 74  Do not confuse t
6f70: 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e  he SQLITE_SYNC_N
6f80: 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45  ORMAL and SQLITE
6f90: 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 73  _SYNC_FULL flags
6fa0: 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 50 52  .** with the [PR
6fb0: 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73  AGMA synchronous
6fc0: 5d 3d 4e 4f 52 4d 41 4c 20 61 6e 64 20 5b 50 52  ]=NORMAL and [PR
6fd0: 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73  AGMA synchronous
6fe0: 5d 3d 46 55 4c 4c 0a 2a 2a 20 73 65 74 74 69 6e  ]=FULL.** settin
6ff0: 67 73 2e 20 20 54 68 65 20 5b 73 79 6e 63 68 72  gs.  The [synchr
7000: 6f 6e 6f 75 73 20 70 72 61 67 6d 61 5d 20 64 65  onous pragma] de
7010: 74 65 72 6d 69 6e 65 73 20 77 68 65 6e 20 63 61  termines when ca
7020: 6c 6c 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53  lls to the.** xS
7030: 79 6e 63 20 56 46 53 20 6d 65 74 68 6f 64 20 6f  ync VFS method o
7040: 63 63 75 72 20 61 6e 64 20 61 70 70 6c 69 65 73  ccur and applies
7050: 20 75 6e 69 66 6f 72 6d 6c 79 20 61 63 72 6f 73   uniformly acros
7060: 73 20 61 6c 6c 20 70 6c 61 74 66 6f 72 6d 73 2e  s all platforms.
7070: 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 53  .** The SQLITE_S
7080: 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53  YNC_NORMAL and S
7090: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20  QLITE_SYNC_FULL 
70a0: 66 6c 61 67 73 20 64 65 74 65 72 6d 69 6e 65 20  flags determine 
70b0: 68 6f 77 0a 2a 2a 20 65 6e 65 72 67 65 74 69 63  how.** energetic
70c0: 20 6f 72 20 72 69 67 6f 72 6f 75 73 20 6f 72 20   or rigorous or 
70d0: 66 6f 72 63 65 66 75 6c 20 74 68 65 20 73 79 6e  forceful the syn
70e0: 63 20 6f 70 65 72 61 74 69 6f 6e 73 20 61 72 65  c operations are
70f0: 20 61 6e 64 0a 2a 2a 20 6f 6e 6c 79 20 6d 61 6b   and.** only mak
7100: 65 20 61 20 64 69 66 66 65 72 65 6e 63 65 20 6f  e a difference o
7110: 6e 20 4d 61 63 20 4f 53 58 20 66 6f 72 20 74 68  n Mac OSX for th
7120: 65 20 64 65 66 61 75 6c 74 20 53 51 4c 69 74 65  e default SQLite
7130: 20 63 6f 64 65 2e 0a 2a 2a 20 28 54 68 69 72 64   code..** (Third
7140: 2d 70 61 72 74 79 20 56 46 53 20 69 6d 70 6c 65  -party VFS imple
7150: 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 69 67 68 74  mentations might
7160: 20 61 6c 73 6f 20 6d 61 6b 65 20 74 68 65 20 64   also make the d
7170: 69 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65  istinction.** be
7180: 74 77 65 65 6e 20 53 51 4c 49 54 45 5f 53 59 4e  tween SQLITE_SYN
7190: 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c  C_NORMAL and SQL
71a0: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 62  ITE_SYNC_FULL, b
71b0: 75 74 20 61 6d 6f 6e 67 20 74 68 65 0a 2a 2a 20  ut among the.** 
71c0: 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
71d0: 73 20 6e 61 74 69 76 65 6c 79 20 73 75 70 70 6f  s natively suppo
71e0: 72 74 65 64 20 62 79 20 53 51 4c 69 74 65 2c 20  rted by SQLite, 
71f0: 6f 6e 6c 79 20 4d 61 63 20 4f 53 58 0a 2a 2a 20  only Mac OSX.** 
7200: 63 61 72 65 73 20 61 62 6f 75 74 20 74 68 65 20  cares about the 
7210: 64 69 66 66 65 72 65 6e 63 65 2e 29 0a 2a 2f 0a  difference.).*/.
7220: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
7230: 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20  YNC_NORMAL      
7240: 20 20 30 78 30 30 30 30 32 0a 23 64 65 66 69 6e    0x00002.#defin
7250: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55  e SQLITE_SYNC_FU
7260: 4c 4c 20 20 20 20 20 20 20 20 20 20 30 78 30 30  LL          0x00
7270: 30 30 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  003.#define SQLI
7280: 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59  TE_SYNC_DATAONLY
7290: 20 20 20 20 20 20 30 78 30 30 30 31 30 0a 0a 2f        0x00010../
72a0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
72b0: 53 20 49 6e 74 65 72 66 61 63 65 20 4f 70 65 6e  S Interface Open
72c0: 20 46 69 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a   File Handle.**.
72d0: 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f 66  ** An [sqlite3_f
72e0: 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65 70 72  ile] object repr
72f0: 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20 66  esents an open f
7300: 69 6c 65 20 69 6e 20 74 68 65 20 0a 2a 2a 20 5b  ile in the .** [
7310: 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 4f 53  sqlite3_vfs | OS
7320: 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72   interface layer
7330: 5d 2e 20 20 49 6e 64 69 76 69 64 75 61 6c 20 4f  ].  Individual O
7340: 53 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69  S interface.** i
7350: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77  mplementations w
7360: 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 73  ill.** want to s
7370: 75 62 63 6c 61 73 73 20 74 68 69 73 20 6f 62 6a  ubclass this obj
7380: 65 63 74 20 62 79 20 61 70 70 65 6e 64 69 6e 67  ect by appending
7390: 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c   additional fiel
73a0: 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65 69 72 20  ds.** for their 
73b0: 6f 77 6e 20 75 73 65 2e 20 20 54 68 65 20 70 4d  own use.  The pM
73c0: 65 74 68 6f 64 73 20 65 6e 74 72 79 20 69 73 20  ethods entry is 
73d0: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a  a pointer to an.
73e0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  ** [sqlite3_io_m
73f0: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 74  ethods] object t
7400: 68 61 74 20 64 65 66 69 6e 65 73 20 6d 65 74 68  hat defines meth
7410: 6f 64 73 20 66 6f 72 20 70 65 72 66 6f 72 6d 69  ods for performi
7420: 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72 61 74  ng.** I/O operat
7430: 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70 65 6e  ions on the open
7440: 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 65   file..*/.typede
7450: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
7460: 5f 66 69 6c 65 20 73 71 6c 69 74 65 33 5f 66 69  _file sqlite3_fi
7470: 6c 65 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74  le;.struct sqlit
7480: 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f 6e 73  e3_file {.  cons
7490: 74 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  t struct sqlite3
74a0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70 4d 65  _io_methods *pMe
74b0: 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74 68 6f  thods;  /* Metho
74c0: 64 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e 20 66  ds for an open f
74d0: 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a  ile */.};../*.**
74e0: 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e   CAPI3REF: OS In
74f0: 74 65 72 66 61 63 65 20 46 69 6c 65 20 56 69 72  terface File Vir
7500: 74 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f 62 6a  tual Methods Obj
7510: 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20  ect.**.** Every 
7520: 66 69 6c 65 20 6f 70 65 6e 65 64 20 62 79 20 74  file opened by t
7530: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  he [sqlite3_vfs.
7540: 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20 70 6f  xOpen] method po
7550: 70 75 6c 61 74 65 73 20 61 6e 0a 2a 2a 20 5b 73  pulates an.** [s
7560: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a  qlite3_file] obj
7570: 65 63 74 20 28 6f 72 2c 20 6d 6f 72 65 20 63 6f  ect (or, more co
7580: 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 63 6c 61  mmonly, a subcla
7590: 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71  ss of the.** [sq
75a0: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
75b0: 63 74 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74  ct) with a point
75c0: 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63  er to an instanc
75d0: 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
75e0: 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74  ..** This object
75f0: 20 64 65 66 69 6e 65 73 20 74 68 65 20 6d 65 74   defines the met
7600: 68 6f 64 73 20 75 73 65 64 20 74 6f 20 70 65 72  hods used to per
7610: 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f 70 65  form various ope
7620: 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e  rations.** again
7630: 73 74 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65  st the open file
7640: 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20   represented by 
7650: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  the [sqlite3_fil
7660: 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a  e] object..**.**
7670: 20 49 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   If the [sqlite3
7680: 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68  _vfs.xOpen] meth
7690: 6f 64 20 73 65 74 73 20 74 68 65 20 73 71 6c 69  od sets the sqli
76a0: 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64  te3_file.pMethod
76b0: 73 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20 74 6f  s element .** to
76c0: 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e   a non-NULL poin
76d0: 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20 73 71  ter, then the sq
76e0: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
76f0: 2e 78 43 6c 6f 73 65 20 6d 65 74 68 6f 64 0a 2a  .xClose method.*
7700: 2a 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65 64  * may be invoked
7710: 20 65 76 65 6e 20 69 66 20 74 68 65 20 5b 73 71   even if the [sq
7720: 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d  lite3_vfs.xOpen]
7730: 20 72 65 70 6f 72 74 65 64 20 74 68 61 74 20 69   reported that i
7740: 74 20 66 61 69 6c 65 64 2e 20 20 54 68 65 0a 2a  t failed.  The.*
7750: 2a 20 6f 6e 6c 79 20 77 61 79 20 74 6f 20 70 72  * only way to pr
7760: 65 76 65 6e 74 20 61 20 63 61 6c 6c 20 74 6f 20  event a call to 
7770: 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f 77 69 6e 67  xClose following
7780: 20 61 20 66 61 69 6c 65 64 20 5b 73 71 6c 69 74   a failed [sqlit
7790: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 0a 2a 2a  e3_vfs.xOpen].**
77a0: 20 69 73 20 66 6f 72 20 74 68 65 20 5b 73 71 6c   is for the [sql
77b0: 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20  ite3_vfs.xOpen] 
77c0: 74 6f 20 73 65 74 20 74 68 65 20 73 71 6c 69 74  to set the sqlit
77d0: 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73  e3_file.pMethods
77e0: 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 74 6f 20 4e   element.** to N
77f0: 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  ULL..**.** The f
7800: 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f  lags argument to
7810: 20 78 53 79 6e 63 20 6d 61 79 20 62 65 20 6f 6e   xSync may be on
7820: 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53 59 4e  e of [SQLITE_SYN
7830: 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20  C_NORMAL] or.** 
7840: 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c  [SQLITE_SYNC_FUL
7850: 4c 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20 63  L].  The first c
7860: 68 6f 69 63 65 20 69 73 20 74 68 65 20 6e 6f 72  hoice is the nor
7870: 6d 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 20  mal fsync()..** 
7880: 54 68 65 20 73 65 63 6f 6e 64 20 63 68 6f 69 63  The second choic
7890: 65 20 69 73 20 61 20 4d 61 63 20 4f 53 20 58 20  e is a Mac OS X 
78a0: 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 2e 20  style fullsync. 
78b0: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 53 59 4e   The [SQLITE_SYN
78c0: 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66  C_DATAONLY].** f
78d0: 6c 61 67 20 6d 61 79 20 62 65 20 4f 52 65 64 20  lag may be ORed 
78e0: 69 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74  in to indicate t
78f0: 68 61 74 20 6f 6e 6c 79 20 74 68 65 20 64 61 74  hat only the dat
7900: 61 20 6f 66 20 74 68 65 20 66 69 6c 65 0a 2a 2a  a of the file.**
7910: 20 61 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e 6f   and not its ino
7920: 64 65 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73  de needs to be s
7930: 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ynced..**.** The
7940: 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20   integer values 
7950: 74 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78  to xLock() and x
7960: 55 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f 6e 65  Unlock() are one
7970: 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c   of.** <ul>.** <
7980: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  li> [SQLITE_LOCK
7990: 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20  _NONE],.** <li> 
79a0: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41  [SQLITE_LOCK_SHA
79b0: 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  RED],.** <li> [S
79c0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52  QLITE_LOCK_RESER
79d0: 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  VED],.** <li> [S
79e0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49  QLITE_LOCK_PENDI
79f0: 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20  NG], or.** <li> 
7a00: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43  [SQLITE_LOCK_EXC
7a10: 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c  LUSIVE]..** </ul
7a20: 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 6e 63  >.** xLock() inc
7a30: 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e  reases the lock.
7a40: 20 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63 72 65   xUnlock() decre
7a50: 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a  ases the lock..*
7a60: 2a 20 54 68 65 20 78 43 68 65 63 6b 52 65 73 65  * The xCheckRese
7a70: 72 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74 68 6f  rvedLock() metho
7a80: 64 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72  d checks whether
7a90: 20 61 6e 79 20 64 61 74 61 62 61 73 65 20 63 6f   any database co
7aa0: 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74  nnection,.** eit
7ab0: 68 65 72 20 69 6e 20 74 68 69 73 20 70 72 6f 63  her in this proc
7ac0: 65 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65 20 6f  ess or in some o
7ad0: 74 68 65 72 20 70 72 6f 63 65 73 73 2c 20 69 73  ther process, is
7ae0: 20 68 6f 6c 64 69 6e 67 20 61 20 52 45 53 45 52   holding a RESER
7af0: 56 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c  VED,.** PENDING,
7b00: 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 6c 6f   or EXCLUSIVE lo
7b10: 63 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65 2e 20  ck on the file. 
7b20: 20 49 74 20 72 65 74 75 72 6e 73 20 74 72 75 65   It returns true
7b30: 0a 2a 2a 20 69 66 20 73 75 63 68 20 61 20 6c 6f  .** if such a lo
7b40: 63 6b 20 65 78 69 73 74 73 20 61 6e 64 20 66 61  ck exists and fa
7b50: 6c 73 65 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a  lse otherwise..*
7b60: 2a 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65 43 6f  *.** The xFileCo
7b70: 6e 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64 20 69  ntrol() method i
7b80: 73 20 61 20 67 65 6e 65 72 69 63 20 69 6e 74 65  s a generic inte
7b90: 72 66 61 63 65 20 74 68 61 74 20 61 6c 6c 6f 77  rface that allow
7ba0: 73 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 53 20  s custom.** VFS 
7bb0: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
7bc0: 74 6f 20 64 69 72 65 63 74 6c 79 20 63 6f 6e 74  to directly cont
7bd0: 72 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65  rol an open file
7be0: 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73   using the.** [s
7bf0: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
7c00: 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61 63 65  rol()] interface
7c10: 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 22 6f  .  The second "o
7c20: 70 22 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  p" argument is a
7c30: 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6f 70 63  n.** integer opc
7c40: 6f 64 65 2e 20 20 54 68 65 20 74 68 69 72 64 20  ode.  The third 
7c50: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 67 65  argument is a ge
7c60: 6e 65 72 69 63 20 70 6f 69 6e 74 65 72 20 69 6e  neric pointer in
7c70: 74 65 6e 64 65 64 20 74 6f 0a 2a 2a 20 70 6f 69  tended to.** poi
7c80: 6e 74 20 74 6f 20 61 20 73 74 72 75 63 74 75 72  nt to a structur
7c90: 65 20 74 68 61 74 20 6d 61 79 20 63 6f 6e 74 61  e that may conta
7ca0: 69 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20  in arguments or 
7cb0: 73 70 61 63 65 20 69 6e 20 77 68 69 63 68 20 74  space in which t
7cc0: 6f 0a 2a 2a 20 77 72 69 74 65 20 72 65 74 75 72  o.** write retur
7cd0: 6e 20 76 61 6c 75 65 73 2e 20 20 50 6f 74 65 6e  n values.  Poten
7ce0: 74 69 61 6c 20 75 73 65 73 20 66 6f 72 20 78 46  tial uses for xF
7cf0: 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 67  ileControl() mig
7d00: 68 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74 69 6f  ht be.** functio
7d10: 6e 73 20 74 6f 20 65 6e 61 62 6c 65 20 62 6c 6f  ns to enable blo
7d20: 63 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69 74 68  cking locks with
7d30: 20 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20 63 68   timeouts, to ch
7d40: 61 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b  ange the.** lock
7d50: 69 6e 67 20 73 74 72 61 74 65 67 79 20 28 66 6f  ing strategy (fo
7d60: 72 20 65 78 61 6d 70 6c 65 20 74 6f 20 75 73 65  r example to use
7d70: 20 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 29   dot-file locks)
7d80: 2c 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a 2a 20  , to inquire.** 
7d90: 61 62 6f 75 74 20 74 68 65 20 73 74 61 74 75 73  about the status
7da0: 20 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 74   of a lock, or t
7db0: 6f 20 62 72 65 61 6b 20 73 74 61 6c 65 20 6c 6f  o break stale lo
7dc0: 63 6b 73 2e 20 20 54 68 65 20 53 51 4c 69 74 65  cks.  The SQLite
7dd0: 0a 2a 2a 20 63 6f 72 65 20 72 65 73 65 72 76 65  .** core reserve
7de0: 73 20 61 6c 6c 20 6f 70 63 6f 64 65 73 20 6c 65  s all opcodes le
7df0: 73 73 20 74 68 61 6e 20 31 30 30 20 66 6f 72 20  ss than 100 for 
7e00: 69 74 73 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20  its own use..** 
7e10: 41 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  A [SQLITE_FCNTL_
7e20: 4c 4f 43 4b 53 54 41 54 45 20 7c 20 6c 69 73 74  LOCKSTATE | list
7e30: 20 6f 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65 73   of opcodes] les
7e40: 73 20 74 68 61 6e 20 31 30 30 20 69 73 20 61 76  s than 100 is av
7e50: 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c  ailable..** Appl
7e60: 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 64 65  ications that de
7e70: 66 69 6e 65 20 61 20 63 75 73 74 6f 6d 20 78 46  fine a custom xF
7e80: 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f  ileControl metho
7e90: 64 20 73 68 6f 75 6c 64 20 75 73 65 20 6f 70 63  d should use opc
7ea0: 6f 64 65 73 0a 2a 2a 20 67 72 65 61 74 65 72 20  odes.** greater 
7eb0: 74 68 61 6e 20 31 30 30 20 74 6f 20 61 76 6f 69  than 100 to avoi
7ec0: 64 20 63 6f 6e 66 6c 69 63 74 73 2e 20 20 56 46  d conflicts.  VF
7ed0: 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  S implementation
7ee0: 73 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75  s should.** retu
7ef0: 72 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f  rn [SQLITE_NOTFO
7f00: 55 4e 44 5d 20 66 6f 72 20 66 69 6c 65 20 63 6f  UND] for file co
7f10: 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20 74 68  ntrol opcodes th
7f20: 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a  at they do not.*
7f30: 2a 20 72 65 63 6f 67 6e 69 7a 65 2e 0a 2a 2a 0a  * recognize..**.
7f40: 2a 2a 20 54 68 65 20 78 53 65 63 74 6f 72 53 69  ** The xSectorSi
7f50: 7a 65 28 29 20 6d 65 74 68 6f 64 20 72 65 74 75  ze() method retu
7f60: 72 6e 73 20 74 68 65 20 73 65 63 74 6f 72 20 73  rns the sector s
7f70: 69 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20 64 65  ize of the.** de
7f80: 76 69 63 65 20 74 68 61 74 20 75 6e 64 65 72 6c  vice that underl
7f90: 69 65 73 20 74 68 65 20 66 69 6c 65 2e 20 20 54  ies the file.  T
7fa0: 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20 69  he sector size i
7fb0: 73 20 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d  s the.** minimum
7fc0: 20 77 72 69 74 65 20 74 68 61 74 20 63 61 6e 20   write that can 
7fd0: 62 65 20 70 65 72 66 6f 72 6d 65 64 20 77 69 74  be performed wit
7fe0: 68 6f 75 74 20 64 69 73 74 75 72 62 69 6e 67 0a  hout disturbing.
7ff0: 2a 2a 20 6f 74 68 65 72 20 62 79 74 65 73 20 69  ** other bytes i
8000: 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65  n the file.  The
8010: 20 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65   xDeviceCharacte
8020: 72 69 73 74 69 63 73 28 29 0a 2a 2a 20 6d 65 74  ristics().** met
8030: 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 62 69  hod returns a bi
8040: 74 20 76 65 63 74 6f 72 20 64 65 73 63 72 69 62  t vector describ
8050: 69 6e 67 20 62 65 68 61 76 69 6f 72 73 20 6f 66  ing behaviors of
8060: 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69   the.** underlyi
8070: 6e 67 20 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a  ng device:.**.**
8080: 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53   <ul>.** <li> [S
8090: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
80a0: 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  IC].** <li> [SQL
80b0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
80c0: 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  512].** <li> [SQ
80d0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
80e0: 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  C1K].** <li> [SQ
80f0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
8100: 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  C2K].** <li> [SQ
8110: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
8120: 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  C4K].** <li> [SQ
8130: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
8140: 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  C8K].** <li> [SQ
8150: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
8160: 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  C16K].** <li> [S
8170: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
8180: 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  IC32K].** <li> [
8190: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
81a0: 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  MIC64K].** <li> 
81b0: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41  [SQLITE_IOCAP_SA
81c0: 46 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c  FE_APPEND].** <l
81d0: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
81e0: 5f 53 45 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20  _SEQUENTIAL].** 
81f0: 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  </ul>.**.** The 
8200: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
8210: 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61  MIC property mea
8220: 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74  ns that all writ
8230: 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a  es of.** any siz
8240: 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54  e are atomic.  T
8250: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
8260: 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73  ATOMICnnn values
8270: 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72  .** mean that wr
8280: 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74  ites of blocks t
8290: 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65  hat are nnn byte
82a0: 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a  s in size and.**
82b0: 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20   are aligned to 
82c0: 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63 68  an address which
82d0: 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d   is an integer m
82e0: 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e  ultiple of.** nn
82f0: 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54  n are atomic.  T
8300: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
8310: 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75  SAFE_APPEND valu
8320: 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20  e means.** that 
8330: 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70 70  when data is app
8340: 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c  ended to a file,
8350: 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70 70   the data is app
8360: 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74  ended.** first t
8370: 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20  hen the size of 
8380: 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74 65  the file is exte
8390: 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20  nded, never the 
83a0: 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f  other.** way aro
83b0: 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45  und.  The SQLITE
83c0: 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41  _IOCAP_SEQUENTIA
83d0: 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73  L property means
83e0: 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61   that.** informa
83f0: 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20  tion is written 
8400: 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73  to disk in the s
8410: 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c  ame order as cal
8420: 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28  ls.** to xWrite(
8430: 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 78 52 65 61  )..**.** If xRea
8440: 64 28 29 20 72 65 74 75 72 6e 73 20 53 51 4c 49  d() returns SQLI
8450: 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52  TE_IOERR_SHORT_R
8460: 45 41 44 20 69 74 20 6d 75 73 74 20 61 6c 73 6f  EAD it must also
8470: 20 66 69 6c 6c 0a 2a 2a 20 69 6e 20 74 68 65 20   fill.** in the 
8480: 75 6e 72 65 61 64 20 70 6f 72 74 69 6f 6e 73 20  unread portions 
8490: 6f 66 20 74 68 65 20 62 75 66 66 65 72 20 77 69  of the buffer wi
84a0: 74 68 20 7a 65 72 6f 73 2e 20 20 41 20 56 46 53  th zeros.  A VFS
84b0: 20 74 68 61 74 0a 2a 2a 20 66 61 69 6c 73 20 74   that.** fails t
84c0: 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72  o zero-fill shor
84d0: 74 20 72 65 61 64 73 20 6d 69 67 68 74 20 73 65  t reads might se
84e0: 65 6d 20 74 6f 20 77 6f 72 6b 2e 20 20 48 6f 77  em to work.  How
84f0: 65 76 65 72 2c 0a 2a 2a 20 66 61 69 6c 75 72 65  ever,.** failure
8500: 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68   to zero-fill sh
8510: 6f 72 74 20 72 65 61 64 73 20 77 69 6c 6c 20 65  ort reads will e
8520: 76 65 6e 74 75 61 6c 6c 79 20 6c 65 61 64 20 74  ventually lead t
8530: 6f 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  o.** database co
8540: 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70  rruption..*/.typ
8550: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
8560: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 73  te3_io_methods s
8570: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
8580: 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65  s;.struct sqlite
8590: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a 20  3_io_methods {. 
85a0: 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20   int iVersion;. 
85b0: 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28 73   int (*xClose)(s
85c0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20  qlite3_file*);. 
85d0: 20 69 6e 74 20 28 2a 78 52 65 61 64 29 28 73 71   int (*xRead)(sq
85e0: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 76 6f 69  lite3_file*, voi
85f0: 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71  d*, int iAmt, sq
8600: 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73  lite3_int64 iOfs
8610: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 57 72 69  t);.  int (*xWri
8620: 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  te)(sqlite3_file
8630: 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  *, const void*, 
8640: 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65  int iAmt, sqlite
8650: 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a  3_int64 iOfst);.
8660: 20 20 69 6e 74 20 28 2a 78 54 72 75 6e 63 61 74    int (*xTruncat
8670: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e)(sqlite3_file*
8680: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
8690: 73 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78  size);.  int (*x
86a0: 53 79 6e 63 29 28 73 71 6c 69 74 65 33 5f 66 69  Sync)(sqlite3_fi
86b0: 6c 65 2a 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b  le*, int flags);
86c0: 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 53 69  .  int (*xFileSi
86d0: 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ze)(sqlite3_file
86e0: 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
86f0: 20 2a 70 53 69 7a 65 29 3b 0a 20 20 69 6e 74 20   *pSize);.  int 
8700: 28 2a 78 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33  (*xLock)(sqlite3
8710: 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20  _file*, int);.  
8720: 69 6e 74 20 28 2a 78 55 6e 6c 6f 63 6b 29 28 73  int (*xUnlock)(s
8730: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
8740: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 68 65  t);.  int (*xChe
8750: 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 29 28  ckReservedLock)(
8760: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
8770: 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20  nt *pResOut);.  
8780: 69 6e 74 20 28 2a 78 46 69 6c 65 43 6f 6e 74 72  int (*xFileContr
8790: 6f 6c 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ol)(sqlite3_file
87a0: 2a 2c 20 69 6e 74 20 6f 70 2c 20 76 6f 69 64 20  *, int op, void 
87b0: 2a 70 41 72 67 29 3b 0a 20 20 69 6e 74 20 28 2a  *pArg);.  int (*
87c0: 78 53 65 63 74 6f 72 53 69 7a 65 29 28 73 71 6c  xSectorSize)(sql
87d0: 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69  ite3_file*);.  i
87e0: 6e 74 20 28 2a 78 44 65 76 69 63 65 43 68 61 72  nt (*xDeviceChar
87f0: 61 63 74 65 72 69 73 74 69 63 73 29 28 73 71 6c  acteristics)(sql
8800: 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f  ite3_file*);.  /
8810: 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20  * Methods above 
8820: 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65  are valid for ve
8830: 72 73 69 6f 6e 20 31 20 2a 2f 0a 20 20 69 6e 74  rsion 1 */.  int
8840: 20 28 2a 78 53 68 6d 4d 61 70 29 28 73 71 6c 69   (*xShmMap)(sqli
8850: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 69  te3_file*, int i
8860: 50 67 2c 20 69 6e 74 20 70 67 73 7a 2c 20 69 6e  Pg, int pgsz, in
8870: 74 2c 20 76 6f 69 64 20 76 6f 6c 61 74 69 6c 65  t, void volatile
8880: 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68  **);.  int (*xSh
8890: 6d 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66  mLock)(sqlite3_f
88a0: 69 6c 65 2a 2c 20 69 6e 74 20 6f 66 66 73 65 74  ile*, int offset
88b0: 2c 20 69 6e 74 20 6e 2c 20 69 6e 74 20 66 6c 61  , int n, int fla
88c0: 67 73 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 53  gs);.  void (*xS
88d0: 68 6d 42 61 72 72 69 65 72 29 28 73 71 6c 69 74  hmBarrier)(sqlit
88e0: 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74  e3_file*);.  int
88f0: 20 28 2a 78 53 68 6d 55 6e 6d 61 70 29 28 73 71   (*xShmUnmap)(sq
8900: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
8910: 20 64 65 6c 65 74 65 46 6c 61 67 29 3b 0a 20 20   deleteFlag);.  
8920: 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65  /* Methods above
8930: 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76   are valid for v
8940: 65 72 73 69 6f 6e 20 32 20 2a 2f 0a 20 20 69 6e  ersion 2 */.  in
8950: 74 20 28 2a 78 46 65 74 63 68 29 28 73 71 6c 69  t (*xFetch)(sqli
8960: 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74  te3_file*, sqlit
8970: 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 2c 20  e3_int64 iOfst, 
8980: 69 6e 74 20 69 41 6d 74 2c 20 76 6f 69 64 20 2a  int iAmt, void *
8990: 2a 70 70 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55  *pp);.  int (*xU
89a0: 6e 66 65 74 63 68 29 28 73 71 6c 69 74 65 33 5f  nfetch)(sqlite3_
89b0: 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69  file*, sqlite3_i
89c0: 6e 74 36 34 20 69 4f 66 73 74 2c 20 76 6f 69 64  nt64 iOfst, void
89d0: 20 2a 70 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f   *p);.  /* Metho
89e0: 64 73 20 61 62 6f 76 65 20 61 72 65 20 76 61 6c  ds above are val
89f0: 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 33  id for version 3
8a00: 20 2a 2f 0a 20 20 2f 2a 20 41 64 64 69 74 69 6f   */.  /* Additio
8a10: 6e 61 6c 20 6d 65 74 68 6f 64 73 20 6d 61 79 20  nal methods may 
8a20: 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75  be added in futu
8a30: 72 65 20 72 65 6c 65 61 73 65 73 20 2a 2f 0a 7d  re releases */.}
8a40: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
8a50: 46 3a 20 53 74 61 6e 64 61 72 64 20 46 69 6c 65  F: Standard File
8a60: 20 43 6f 6e 74 72 6f 6c 20 4f 70 63 6f 64 65 73   Control Opcodes
8a70: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74  .**.** These int
8a80: 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 61  eger constants a
8a90: 72 65 20 6f 70 63 6f 64 65 73 20 66 6f 72 20 74  re opcodes for t
8aa0: 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20  he xFileControl 
8ab0: 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 65  method.** of the
8ac0: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
8ad0: 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 61 6e 64  hods] object and
8ae0: 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65   for the [sqlite
8af0: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
8b00: 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e 0a  ].** interface..
8b10: 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  **.** The [SQLIT
8b20: 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54  E_FCNTL_LOCKSTAT
8b30: 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65  E] opcode is use
8b40: 64 20 66 6f 72 20 64 65 62 75 67 67 69 6e 67 2e  d for debugging.
8b50: 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65    This.** opcode
8b60: 20 63 61 75 73 65 73 20 74 68 65 20 78 46 69 6c   causes the xFil
8b70: 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20  eControl method 
8b80: 74 6f 20 77 72 69 74 65 20 74 68 65 20 63 75 72  to write the cur
8b90: 72 65 6e 74 20 73 74 61 74 65 20 6f 66 0a 2a 2a  rent state of.**
8ba0: 20 74 68 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f   the lock (one o
8bb0: 66 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e  f [SQLITE_LOCK_N
8bc0: 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f  ONE], [SQLITE_LO
8bd0: 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b  CK_SHARED],.** [
8be0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45  SQLITE_LOCK_RESE
8bf0: 52 56 45 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c  RVED], [SQLITE_L
8c00: 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72  OCK_PENDING], or
8c10: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58   [SQLITE_LOCK_EX
8c20: 43 4c 55 53 49 56 45 5d 29 0a 2a 2a 20 69 6e 74  CLUSIVE]).** int
8c30: 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 74 68 61  o an integer tha
8c40: 74 20 74 68 65 20 70 41 72 67 20 61 72 67 75 6d  t the pArg argum
8c50: 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 2e 20 54  ent points to. T
8c60: 68 69 73 20 63 61 70 61 62 69 6c 69 74 79 0a 2a  his capability.*
8c70: 2a 20 69 73 20 75 73 65 64 20 64 75 72 69 6e 67  * is used during
8c80: 20 74 65 73 74 69 6e 67 20 61 6e 64 20 6f 6e 6c   testing and onl
8c90: 79 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73 75  y needs to be su
8ca0: 70 70 6f 72 74 65 64 20 77 68 65 6e 20 53 51 4c  pported when SQL
8cb0: 49 54 45 5f 54 45 53 54 0a 2a 2a 20 69 73 20 64  ITE_TEST.** is d
8cc0: 65 66 69 6e 65 64 2e 0a 2a 2a 20 3c 75 6c 3e 0a  efined..** <ul>.
8cd0: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
8ce0: 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d  FCNTL_SIZE_HINT]
8cf0: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
8d00: 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54  _FCNTL_SIZE_HINT
8d10: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64  ] opcode is used
8d20: 20 62 79 20 53 51 4c 69 74 65 20 74 6f 20 67 69   by SQLite to gi
8d30: 76 65 20 74 68 65 20 56 46 53 0a 2a 2a 20 6c 61  ve the VFS.** la
8d40: 79 65 72 20 61 20 68 69 6e 74 20 6f 66 20 68 6f  yer a hint of ho
8d50: 77 20 6c 61 72 67 65 20 74 68 65 20 64 61 74 61  w large the data
8d60: 62 61 73 65 20 66 69 6c 65 20 77 69 6c 6c 20 67  base file will g
8d70: 72 6f 77 20 74 6f 20 62 65 20 64 75 72 69 6e 67  row to be during
8d80: 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20   the.** current 
8d90: 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 20 54 68  transaction.  Th
8da0: 69 73 20 68 69 6e 74 20 69 73 20 6e 6f 74 20 67  is hint is not g
8db0: 75 61 72 61 6e 74 65 65 64 20 74 6f 20 62 65 20  uaranteed to be 
8dc0: 61 63 63 75 72 61 74 65 20 62 75 74 20 69 74 0a  accurate but it.
8dd0: 2a 2a 20 69 73 20 6f 66 74 65 6e 20 63 6c 6f 73  ** is often clos
8de0: 65 2e 20 20 54 68 65 20 75 6e 64 65 72 6c 79 69  e.  The underlyi
8df0: 6e 67 20 56 46 53 20 6d 69 67 68 74 20 63 68 6f  ng VFS might cho
8e00: 6f 73 65 20 74 6f 20 70 72 65 61 6c 6c 6f 63 61  ose to prealloca
8e10: 74 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66  te database.** f
8e20: 69 6c 65 20 73 70 61 63 65 20 62 61 73 65 64 20  ile space based 
8e30: 6f 6e 20 74 68 69 73 20 68 69 6e 74 20 69 6e 20  on this hint in 
8e40: 6f 72 64 65 72 20 74 6f 20 68 65 6c 70 20 77 72  order to help wr
8e50: 69 74 65 73 20 74 6f 20 74 68 65 20 64 61 74 61  ites to the data
8e60: 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 72 75 6e  base.** file run
8e70: 20 66 61 73 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c   faster..**.** <
8e80: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
8e90: 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 5d 0a 2a  L_CHUNK_SIZE]].*
8ea0: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
8eb0: 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 20  NTL_CHUNK_SIZE] 
8ec0: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74  opcode is used t
8ed0: 6f 20 72 65 71 75 65 73 74 20 74 68 61 74 20 74  o request that t
8ee0: 68 65 20 56 46 53 0a 2a 2a 20 65 78 74 65 6e 64  he VFS.** extend
8ef0: 73 20 61 6e 64 20 74 72 75 6e 63 61 74 65 73 20  s and truncates 
8f00: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
8f10: 65 20 69 6e 20 63 68 75 6e 6b 73 20 6f 66 20 61  e in chunks of a
8f20: 20 73 69 7a 65 20 73 70 65 63 69 66 69 65 64 0a   size specified.
8f30: 2a 2a 20 62 79 20 74 68 65 20 75 73 65 72 2e 20  ** by the user. 
8f40: 54 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d  The fourth argum
8f50: 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ent to [sqlite3_
8f60: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20  file_control()] 
8f70: 73 68 6f 75 6c 64 20 0a 2a 2a 20 70 6f 69 6e 74  should .** point
8f80: 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 28   to an integer (
8f90: 74 79 70 65 20 69 6e 74 29 20 63 6f 6e 74 61 69  type int) contai
8fa0: 6e 69 6e 67 20 74 68 65 20 6e 65 77 20 63 68 75  ning the new chu
8fb0: 6e 6b 2d 73 69 7a 65 20 74 6f 20 75 73 65 0a 2a  nk-size to use.*
8fc0: 2a 20 66 6f 72 20 74 68 65 20 6e 6f 6d 69 6e 61  * for the nomina
8fd0: 74 65 64 20 64 61 74 61 62 61 73 65 2e 20 41 6c  ted database. Al
8fe0: 6c 6f 63 61 74 69 6e 67 20 64 61 74 61 62 61 73  locating databas
8ff0: 65 20 66 69 6c 65 20 73 70 61 63 65 20 69 6e 20  e file space in 
9000: 6c 61 72 67 65 0a 2a 2a 20 63 68 75 6e 6b 73 20  large.** chunks 
9010: 28 73 61 79 20 31 4d 42 20 61 74 20 61 20 74 69  (say 1MB at a ti
9020: 6d 65 29 2c 20 6d 61 79 20 72 65 64 75 63 65 20  me), may reduce 
9030: 66 69 6c 65 2d 73 79 73 74 65 6d 20 66 72 61 67  file-system frag
9040: 6d 65 6e 74 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a  mentation and.**
9050: 20 69 6d 70 72 6f 76 65 20 70 65 72 66 6f 72 6d   improve perform
9060: 61 6e 63 65 20 6f 6e 20 73 6f 6d 65 20 73 79 73  ance on some sys
9070: 74 65 6d 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  tems..**.** <li>
9080: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46  [[SQLITE_FCNTL_F
9090: 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a  ILE_POINTER]].**
90a0: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
90b0: 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d  TL_FILE_POINTER]
90c0: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20   opcode is used 
90d0: 74 6f 20 6f 62 74 61 69 6e 20 61 20 70 6f 69 6e  to obtain a poin
90e0: 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73  ter.** to the [s
90f0: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a  qlite3_file] obj
9100: 65 63 74 20 61 73 73 6f 63 69 61 74 65 64 20 77  ect associated w
9110: 69 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72  ith a particular
9120: 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e   database.** con
9130: 6e 65 63 74 69 6f 6e 2e 20 20 53 65 65 20 74 68  nection.  See th
9140: 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  e [sqlite3_file_
9150: 63 6f 6e 74 72 6f 6c 28 29 5d 20 64 6f 63 75 6d  control()] docum
9160: 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20  entation for.** 
9170: 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72  additional infor
9180: 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  mation..**.** <l
9190: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
91a0: 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 5d 5d 0a  _SYNC_OMITTED]].
91b0: 2a 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 69 6e 20  ** No longer in 
91c0: 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  use..**.** <li>[
91d0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59  [SQLITE_FCNTL_SY
91e0: 4e 43 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  NC]].** The [SQL
91f0: 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5d 20  ITE_FCNTL_SYNC] 
9200: 6f 70 63 6f 64 65 20 69 73 20 67 65 6e 65 72 61  opcode is genera
9210: 74 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62  ted internally b
9220: 79 20 53 51 4c 69 74 65 20 61 6e 64 0a 2a 2a 20  y SQLite and.** 
9230: 73 65 6e 74 20 74 6f 20 74 68 65 20 56 46 53 20  sent to the VFS 
9240: 69 6d 6d 65 64 69 61 74 65 6c 79 20 62 65 66 6f  immediately befo
9250: 72 65 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74  re the xSync met
9260: 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f  hod is invoked o
9270: 6e 20 61 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  n a.** database 
9280: 66 69 6c 65 20 64 65 73 63 72 69 70 74 6f 72 2e  file descriptor.
9290: 20 4f 72 2c 20 69 66 20 74 68 65 20 78 53 79 6e   Or, if the xSyn
92a0: 63 20 6d 65 74 68 6f 64 20 69 73 20 6e 6f 74 20  c method is not 
92b0: 69 6e 76 6f 6b 65 64 20 0a 2a 2a 20 62 65 63 61  invoked .** beca
92c0: 75 73 65 20 74 68 65 20 75 73 65 72 20 68 61 73  use the user has
92d0: 20 63 6f 6e 66 69 67 75 72 65 64 20 53 51 4c 69   configured SQLi
92e0: 74 65 20 77 69 74 68 20 0a 2a 2a 20 5b 50 52 41  te with .** [PRA
92f0: 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 20  GMA synchronous 
9300: 7c 20 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f  | PRAGMA synchro
9310: 6e 6f 75 73 3d 4f 46 46 5d 20 69 74 20 69 73 20  nous=OFF] it is 
9320: 69 6e 76 6f 6b 65 64 20 69 6e 20 70 6c 61 63 65  invoked in place
9330: 20 0a 2a 2a 20 6f 66 20 74 68 65 20 78 53 79 6e   .** of the xSyn
9340: 63 20 6d 65 74 68 6f 64 2e 20 49 6e 20 6d 6f 73  c method. In mos
9350: 74 20 63 61 73 65 73 2c 20 74 68 65 20 70 6f 69  t cases, the poi
9360: 6e 74 65 72 20 61 72 67 75 6d 65 6e 74 20 70 61  nter argument pa
9370: 73 73 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 69  ssed with.** thi
9380: 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69  s file-control i
9390: 73 20 4e 55 4c 4c 2e 20 48 6f 77 65 76 65 72 2c  s NULL. However,
93a0: 20 69 66 20 74 68 65 20 64 61 74 61 62 61 73 65   if the database
93b0: 20 66 69 6c 65 20 69 73 20 62 65 69 6e 67 20 73   file is being s
93c0: 79 6e 63 65 64 0a 2a 2a 20 61 73 20 70 61 72 74  ynced.** as part
93d0: 20 6f 66 20 61 20 6d 75 6c 74 69 2d 64 61 74 61   of a multi-data
93e0: 62 61 73 65 20 63 6f 6d 6d 69 74 2c 20 74 68 65  base commit, the
93f0: 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73   argument points
9400: 20 74 6f 20 61 20 6e 75 6c 2d 74 65 72 6d 69 6e   to a nul-termin
9410: 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 63  ated.** string c
9420: 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 74 72  ontaining the tr
9430: 61 6e 73 61 63 74 69 6f 6e 73 20 6d 61 73 74 65  ansactions maste
9440: 72 2d 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 6e  r-journal file n
9450: 61 6d 65 2e 20 56 46 53 65 73 20 74 68 61 74 20  ame. VFSes that 
9460: 0a 2a 2a 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20  .** do not need 
9470: 74 68 69 73 20 73 69 67 6e 61 6c 20 73 68 6f 75  this signal shou
9480: 6c 64 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e 6f  ld silently igno
9490: 72 65 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 20  re this opcode. 
94a0: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 0a 2a 2a  Applications .**
94b0: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c 6c   should not call
94c0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
94d0: 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68 20 74  ontrol()] with t
94e0: 68 69 73 20 6f 70 63 6f 64 65 20 61 73 20 64 6f  his opcode as do
94f0: 69 6e 67 20 73 6f 20 6d 61 79 20 0a 2a 2a 20 64  ing so may .** d
9500: 69 73 72 75 70 74 20 74 68 65 20 6f 70 65 72 61  isrupt the opera
9510: 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 70 65 63  tion of the spec
9520: 69 61 6c 69 7a 65 64 20 56 46 53 65 73 20 74 68  ialized VFSes th
9530: 61 74 20 64 6f 20 72 65 71 75 69 72 65 20 69 74  at do require it
9540: 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  .  .**.** <li>[[
9550: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d  SQLITE_FCNTL_COM
9560: 4d 49 54 5f 50 48 41 53 45 54 57 4f 5d 5d 0a 2a  MIT_PHASETWO]].*
9570: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
9580: 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45  NTL_COMMIT_PHASE
9590: 54 57 4f 5d 20 6f 70 63 6f 64 65 20 69 73 20 67  TWO] opcode is g
95a0: 65 6e 65 72 61 74 65 64 20 69 6e 74 65 72 6e 61  enerated interna
95b0: 6c 6c 79 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a  lly by SQLite.**
95c0: 20 61 6e 64 20 73 65 6e 74 20 74 6f 20 74 68 65   and sent to the
95d0: 20 56 46 53 20 61 66 74 65 72 20 61 20 74 72 61   VFS after a tra
95e0: 6e 73 61 63 74 69 6f 6e 20 68 61 73 20 62 65 65  nsaction has bee
95f0: 6e 20 63 6f 6d 6d 69 74 74 65 64 20 69 6d 6d 65  n committed imme
9600: 64 69 61 74 65 6c 79 0a 2a 2a 20 62 75 74 20 62  diately.** but b
9610: 65 66 6f 72 65 20 74 68 65 20 64 61 74 61 62 61  efore the databa
9620: 73 65 20 69 73 20 75 6e 6c 6f 63 6b 65 64 2e 20  se is unlocked. 
9630: 56 46 53 65 73 20 74 68 61 74 20 64 6f 20 6e 6f  VFSes that do no
9640: 74 20 6e 65 65 64 20 74 68 69 73 20 73 69 67 6e  t need this sign
9650: 61 6c 0a 2a 2a 20 73 68 6f 75 6c 64 20 73 69 6c  al.** should sil
9660: 65 6e 74 6c 79 20 69 67 6e 6f 72 65 20 74 68 69  ently ignore thi
9670: 73 20 6f 70 63 6f 64 65 2e 20 41 70 70 6c 69 63  s opcode. Applic
9680: 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 6e 6f  ations should no
9690: 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74  t call.** [sqlit
96a0: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
96b0: 29 5d 20 77 69 74 68 20 74 68 69 73 20 6f 70 63  )] with this opc
96c0: 6f 64 65 20 61 73 20 64 6f 69 6e 67 20 73 6f 20  ode as doing so 
96d0: 6d 61 79 20 64 69 73 72 75 70 74 20 74 68 65 20  may disrupt the 
96e0: 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66  .** operation of
96f0: 20 74 68 65 20 73 70 65 63 69 61 6c 69 7a 65 64   the specialized
9700: 20 56 46 53 65 73 20 74 68 61 74 20 64 6f 20 72   VFSes that do r
9710: 65 71 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a 0a  equire it.  .**.
9720: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
9730: 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52  FCNTL_WIN32_AV_R
9740: 45 54 52 59 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b  ETRY]].** ^The [
9750: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e  SQLITE_FCNTL_WIN
9760: 33 32 5f 41 56 5f 52 45 54 52 59 5d 20 6f 70 63  32_AV_RETRY] opc
9770: 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 63  ode is used to c
9780: 6f 6e 66 69 67 75 72 65 20 61 75 74 6f 6d 61 74  onfigure automat
9790: 69 63 0a 2a 2a 20 72 65 74 72 79 20 63 6f 75 6e  ic.** retry coun
97a0: 74 73 20 61 6e 64 20 69 6e 74 65 72 76 61 6c 73  ts and intervals
97b0: 20 66 6f 72 20 63 65 72 74 61 69 6e 20 64 69 73   for certain dis
97c0: 6b 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73  k I/O operations
97d0: 20 66 6f 72 20 74 68 65 0a 2a 2a 20 77 69 6e 64   for the.** wind
97e0: 6f 77 73 20 5b 56 46 53 5d 20 69 6e 20 6f 72 64  ows [VFS] in ord
97f0: 65 72 20 74 6f 20 70 72 6f 76 69 64 65 20 72 6f  er to provide ro
9800: 62 75 73 74 6e 65 73 73 20 69 6e 20 74 68 65 20  bustness in the 
9810: 70 72 65 73 65 6e 63 65 20 6f 66 0a 2a 2a 20 61  presence of.** a
9820: 6e 74 69 2d 76 69 72 75 73 20 70 72 6f 67 72 61  nti-virus progra
9830: 6d 73 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c  ms.  By default,
9840: 20 74 68 65 20 77 69 6e 64 6f 77 73 20 56 46 53   the windows VFS
9850: 20 77 69 6c 6c 20 72 65 74 72 79 20 66 69 6c 65   will retry file
9860: 20 72 65 61 64 2c 0a 2a 2a 20 66 69 6c 65 20 77   read,.** file w
9870: 72 69 74 65 2c 20 61 6e 64 20 66 69 6c 65 20 64  rite, and file d
9880: 65 6c 65 74 65 20 6f 70 65 72 61 74 69 6f 6e 73  elete operations
9890: 20 75 70 20 74 6f 20 31 30 20 74 69 6d 65 73 2c   up to 10 times,
98a0: 20 77 69 74 68 20 61 20 64 65 6c 61 79 0a 2a 2a   with a delay.**
98b0: 20 6f 66 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f   of 25 milliseco
98c0: 6e 64 73 20 62 65 66 6f 72 65 20 74 68 65 20 66  nds before the f
98d0: 69 72 73 74 20 72 65 74 72 79 20 61 6e 64 20 77  irst retry and w
98e0: 69 74 68 20 74 68 65 20 64 65 6c 61 79 20 69 6e  ith the delay in
98f0: 63 72 65 61 73 69 6e 67 0a 2a 2a 20 62 79 20 61  creasing.** by a
9900: 6e 20 61 64 64 69 74 69 6f 6e 61 6c 20 32 35 20  n additional 25 
9910: 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 77 69 74  milliseconds wit
9920: 68 20 65 61 63 68 20 73 75 62 73 65 71 75 65 6e  h each subsequen
9930: 74 20 72 65 74 72 79 2e 20 20 54 68 69 73 0a 2a  t retry.  This.*
9940: 2a 20 6f 70 63 6f 64 65 20 61 6c 6c 6f 77 73 20  * opcode allows 
9950: 74 68 65 73 65 20 74 77 6f 20 76 61 6c 75 65 73  these two values
9960: 20 28 31 30 20 72 65 74 72 69 65 73 20 61 6e 64   (10 retries and
9970: 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73   25 milliseconds
9980: 20 6f 66 20 64 65 6c 61 79 29 0a 2a 2a 20 74 6f   of delay).** to
9990: 20 62 65 20 61 64 6a 75 73 74 65 64 2e 20 20 54   be adjusted.  T
99a0: 68 65 20 76 61 6c 75 65 73 20 61 72 65 20 63 68  he values are ch
99b0: 61 6e 67 65 64 20 66 6f 72 20 61 6c 6c 20 64 61  anged for all da
99c0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
99d0: 6e 73 0a 2a 2a 20 77 69 74 68 69 6e 20 74 68 65  ns.** within the
99e0: 20 73 61 6d 65 20 70 72 6f 63 65 73 73 2e 20 20   same process.  
99f0: 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  The argument is 
9a00: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
9a10: 61 72 72 61 79 20 6f 66 20 74 77 6f 0a 2a 2a 20  array of two.** 
9a20: 69 6e 74 65 67 65 72 73 20 77 68 65 72 65 20 74  integers where t
9a30: 68 65 20 66 69 72 73 74 20 69 6e 74 65 67 65 72  he first integer
9a40: 20 69 20 74 68 65 20 6e 65 77 20 72 65 74 72 79   i the new retry
9a50: 20 63 6f 75 6e 74 20 61 6e 64 20 74 68 65 20 73   count and the s
9a60: 65 63 6f 6e 64 0a 2a 2a 20 69 6e 74 65 67 65 72  econd.** integer
9a70: 20 69 73 20 74 68 65 20 64 65 6c 61 79 2e 20 20   is the delay.  
9a80: 49 66 20 65 69 74 68 65 72 20 69 6e 74 65 67 65  If either intege
9a90: 72 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74  r is negative, t
9aa0: 68 65 6e 20 74 68 65 20 73 65 74 74 69 6e 67 0a  hen the setting.
9ab0: 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65  ** is not change
9ac0: 64 20 62 75 74 20 69 6e 73 74 65 61 64 20 74 68  d but instead th
9ad0: 65 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66  e prior value of
9ae0: 20 74 68 61 74 20 73 65 74 74 69 6e 67 20 69 73   that setting is
9af0: 20 77 72 69 74 74 65 6e 0a 2a 2a 20 69 6e 74 6f   written.** into
9b00: 20 74 68 65 20 61 72 72 61 79 20 65 6e 74 72 79   the array entry
9b10: 2c 20 61 6c 6c 6f 77 69 6e 67 20 74 68 65 20 63  , allowing the c
9b20: 75 72 72 65 6e 74 20 72 65 74 72 79 20 73 65 74  urrent retry set
9b30: 74 69 6e 67 73 20 74 6f 20 62 65 0a 2a 2a 20 69  tings to be.** i
9b40: 6e 74 65 72 72 6f 67 61 74 65 64 2e 20 20 54 68  nterrogated.  Th
9b50: 65 20 7a 44 62 4e 61 6d 65 20 70 61 72 61 6d 65  e zDbName parame
9b60: 74 65 72 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a  ter is ignored..
9b70: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
9b80: 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54  TE_FCNTL_PERSIST
9b90: 5f 57 41 4c 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b  _WAL]].** ^The [
9ba0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52  SQLITE_FCNTL_PER
9bb0: 53 49 53 54 5f 57 41 4c 5d 20 6f 70 63 6f 64 65  SIST_WAL] opcode
9bc0: 20 69 73 20 75 73 65 64 20 74 6f 20 73 65 74 20   is used to set 
9bd0: 6f 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a 20  or query the.** 
9be0: 70 65 72 73 69 73 74 65 6e 74 20 5b 57 41 4c 20  persistent [WAL 
9bf0: 7c 20 57 72 69 74 65 20 41 68 65 61 64 20 4c 6f  | Write Ahead Lo
9c00: 67 5d 20 73 65 74 74 69 6e 67 2e 20 20 42 79 20  g] setting.  By 
9c10: 64 65 66 61 75 6c 74 2c 20 74 68 65 20 61 75 78  default, the aux
9c20: 69 6c 69 61 72 79 0a 2a 2a 20 77 72 69 74 65 20  iliary.** write 
9c30: 61 68 65 61 64 20 6c 6f 67 20 61 6e 64 20 73 68  ahead log and sh
9c40: 61 72 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c 65  ared memory file
9c50: 73 20 75 73 65 64 20 66 6f 72 20 74 72 61 6e 73  s used for trans
9c60: 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 0a 2a  action control.*
9c70: 2a 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61  * are automatica
9c80: 6c 6c 79 20 64 65 6c 65 74 65 64 20 77 68 65 6e  lly deleted when
9c90: 20 74 68 65 20 6c 61 74 65 73 74 20 63 6f 6e 6e   the latest conn
9ca0: 65 63 74 69 6f 6e 20 74 6f 20 74 68 65 20 64 61  ection to the da
9cb0: 74 61 62 61 73 65 0a 2a 2a 20 63 6c 6f 73 65 73  tabase.** closes
9cc0: 2e 20 20 53 65 74 74 69 6e 67 20 70 65 72 73 69  .  Setting persi
9cd0: 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 63  stent WAL mode c
9ce0: 61 75 73 65 73 20 74 68 6f 73 65 20 66 69 6c 65  auses those file
9cf0: 73 20 74 6f 20 70 65 72 73 69 73 74 20 61 66 74  s to persist aft
9d00: 65 72 0a 2a 2a 20 63 6c 6f 73 65 2e 20 20 50 65  er.** close.  Pe
9d10: 72 73 69 73 74 69 6e 67 20 74 68 65 20 66 69 6c  rsisting the fil
9d20: 65 73 20 69 73 20 75 73 65 66 75 6c 20 77 68 65  es is useful whe
9d30: 6e 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73 65  n other processe
9d40: 73 20 74 68 61 74 20 64 6f 20 6e 6f 74 0a 2a 2a  s that do not.**
9d50: 20 68 61 76 65 20 77 72 69 74 65 20 70 65 72 6d   have write perm
9d60: 69 73 73 69 6f 6e 20 6f 6e 20 74 68 65 20 64 69  ission on the di
9d70: 72 65 63 74 6f 72 79 20 63 6f 6e 74 61 69 6e 69  rectory containi
9d80: 6e 67 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ng the database 
9d90: 66 69 6c 65 20 77 61 6e 74 0a 2a 2a 20 74 6f 20  file want.** to 
9da0: 72 65 61 64 20 74 68 65 20 64 61 74 61 62 61 73  read the databas
9db0: 65 20 66 69 6c 65 2c 20 61 73 20 74 68 65 20 57  e file, as the W
9dc0: 41 4c 20 61 6e 64 20 73 68 61 72 65 64 20 6d 65  AL and shared me
9dd0: 6d 6f 72 79 20 66 69 6c 65 73 20 6d 75 73 74 20  mory files must 
9de0: 65 78 69 73 74 0a 2a 2a 20 69 6e 20 6f 72 64 65  exist.** in orde
9df0: 72 20 66 6f 72 20 74 68 65 20 64 61 74 61 62 61  r for the databa
9e00: 73 65 20 74 6f 20 62 65 20 72 65 61 64 61 62 6c  se to be readabl
9e10: 65 2e 20 20 54 68 65 20 66 6f 75 72 74 68 20 70  e.  The fourth p
9e20: 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b  arameter to.** [
9e30: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
9e40: 74 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 73  trol()] for this
9e50: 20 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 62   opcode should b
9e60: 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  e a pointer to a
9e70: 6e 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68  n integer..** Th
9e80: 61 74 20 69 6e 74 65 67 65 72 20 69 73 20 30 20  at integer is 0 
9e90: 74 6f 20 64 69 73 61 62 6c 65 20 70 65 72 73 69  to disable persi
9ea0: 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 6f  stent WAL mode o
9eb0: 72 20 31 20 74 6f 20 65 6e 61 62 6c 65 20 70 65  r 1 to enable pe
9ec0: 72 73 69 73 74 65 6e 74 0a 2a 2a 20 57 41 4c 20  rsistent.** WAL 
9ed0: 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e  mode.  If the in
9ee0: 74 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65  teger is -1, the
9ef0: 6e 20 69 74 20 69 73 20 6f 76 65 72 77 72 69 74  n it is overwrit
9f00: 74 65 6e 20 77 69 74 68 20 74 68 65 20 63 75 72  ten with the cur
9f10: 72 65 6e 74 0a 2a 2a 20 57 41 4c 20 70 65 72 73  rent.** WAL pers
9f20: 69 73 74 65 6e 63 65 20 73 65 74 74 69 6e 67 2e  istence setting.
9f30: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
9f40: 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53  ITE_FCNTL_POWERS
9f50: 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a  AFE_OVERWRITE]].
9f60: 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
9f70: 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f  FCNTL_POWERSAFE_
9f80: 4f 56 45 52 57 52 49 54 45 5d 20 6f 70 63 6f 64  OVERWRITE] opcod
9f90: 65 20 69 73 20 75 73 65 64 20 74 6f 20 73 65 74  e is used to set
9fa0: 20 6f 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a   or query the.**
9fb0: 20 70 65 72 73 69 73 74 65 6e 74 20 22 70 6f 77   persistent "pow
9fc0: 65 72 73 61 66 65 2d 6f 76 65 72 77 72 69 74 65  ersafe-overwrite
9fd0: 22 20 6f 72 20 22 50 53 4f 57 22 20 73 65 74 74  " or "PSOW" sett
9fe0: 69 6e 67 2e 20 20 54 68 65 20 50 53 4f 57 20 73  ing.  The PSOW s
9ff0: 65 74 74 69 6e 67 0a 2a 2a 20 64 65 74 65 72 6d  etting.** determ
a000: 69 6e 65 73 20 74 68 65 20 5b 53 51 4c 49 54 45  ines the [SQLITE
a010: 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45  _IOCAP_POWERSAFE
a020: 5f 4f 56 45 52 57 52 49 54 45 5d 20 62 69 74 20  _OVERWRITE] bit 
a030: 6f 66 20 74 68 65 0a 2a 2a 20 78 44 65 76 69 63  of the.** xDevic
a040: 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73  eCharacteristics
a050: 20 6d 65 74 68 6f 64 73 2e 20 54 68 65 20 66 6f   methods. The fo
a060: 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  urth parameter t
a070: 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  o.** [sqlite3_fi
a080: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f  le_control()] fo
a090: 72 20 74 68 69 73 20 6f 70 63 6f 64 65 20 73 68  r this opcode sh
a0a0: 6f 75 6c 64 20 62 65 20 61 20 70 6f 69 6e 74 65  ould be a pointe
a0b0: 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e  r to an integer.
a0c0: 0a 2a 2a 20 54 68 61 74 20 69 6e 74 65 67 65 72  .** That integer
a0d0: 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65   is 0 to disable
a0e0: 20 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64   zero-damage mod
a0f0: 65 20 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c 65  e or 1 to enable
a100: 20 7a 65 72 6f 2d 64 61 6d 61 67 65 0a 2a 2a 20   zero-damage.** 
a110: 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e  mode.  If the in
a120: 74 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65  teger is -1, the
a130: 6e 20 69 74 20 69 73 20 6f 76 65 72 77 72 69 74  n it is overwrit
a140: 74 65 6e 20 77 69 74 68 20 74 68 65 20 63 75 72  ten with the cur
a150: 72 65 6e 74 0a 2a 2a 20 7a 65 72 6f 2d 64 61 6d  rent.** zero-dam
a160: 61 67 65 20 6d 6f 64 65 20 73 65 74 74 69 6e 67  age mode setting
a170: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
a180: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57  LITE_FCNTL_OVERW
a190: 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b  RITE]].** ^The [
a1a0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45  SQLITE_FCNTL_OVE
a1b0: 52 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 69  RWRITE] opcode i
a1c0: 73 20 69 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c  s invoked by SQL
a1d0: 69 74 65 20 61 66 74 65 72 20 6f 70 65 6e 69 6e  ite after openin
a1e0: 67 0a 2a 2a 20 61 20 77 72 69 74 65 20 74 72 61  g.** a write tra
a1f0: 6e 73 61 63 74 69 6f 6e 20 74 6f 20 69 6e 64 69  nsaction to indi
a200: 63 61 74 65 20 74 68 61 74 2c 20 75 6e 6c 65 73  cate that, unles
a210: 73 20 69 74 20 69 73 20 72 6f 6c 6c 65 64 20 62  s it is rolled b
a220: 61 63 6b 20 66 6f 72 20 73 6f 6d 65 0a 2a 2a 20  ack for some.** 
a230: 72 65 61 73 6f 6e 2c 20 74 68 65 20 65 6e 74 69  reason, the enti
a240: 72 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  re database file
a250: 20 77 69 6c 6c 20 62 65 20 6f 76 65 72 77 72 69   will be overwri
a260: 74 74 65 6e 20 62 79 20 74 68 65 20 63 75 72 72  tten by the curr
a270: 65 6e 74 20 0a 2a 2a 20 74 72 61 6e 73 61 63 74  ent .** transact
a280: 69 6f 6e 2e 20 54 68 69 73 20 69 73 20 75 73 65  ion. This is use
a290: 64 20 62 79 20 56 41 43 55 55 4d 20 6f 70 65 72  d by VACUUM oper
a2a0: 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  ations..**.** <l
a2b0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
a2c0: 5f 56 46 53 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 54  _VFSNAME]].** ^T
a2d0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
a2e0: 5f 56 46 53 4e 41 4d 45 5d 20 6f 70 63 6f 64 65  _VFSNAME] opcode
a2f0: 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
a300: 6f 62 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73  obtain the names
a310: 20 6f 66 0a 2a 2a 20 61 6c 6c 20 5b 56 46 53 65   of.** all [VFSe
a320: 73 5d 20 69 6e 20 74 68 65 20 56 46 53 20 73 74  s] in the VFS st
a330: 61 63 6b 2e 20 20 54 68 65 20 6e 61 6d 65 73 20  ack.  The names 
a340: 61 72 65 20 6f 66 20 61 6c 6c 20 56 46 53 20 73  are of all VFS s
a350: 68 69 6d 73 20 61 6e 64 20 74 68 65 0a 2a 2a 20  hims and the.** 
a360: 66 69 6e 61 6c 20 62 6f 74 74 6f 6d 2d 6c 65 76  final bottom-lev
a370: 65 6c 20 56 46 53 20 61 72 65 20 77 72 69 74 74  el VFS are writt
a380: 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f  en into memory o
a390: 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a  btained from .**
a3a0: 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
a3b0: 28 29 5d 20 61 6e 64 20 74 68 65 20 72 65 73 75  ()] and the resu
a3c0: 6c 74 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20  lt is stored in 
a3d0: 74 68 65 20 63 68 61 72 2a 20 76 61 72 69 61 62  the char* variab
a3e0: 6c 65 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 66  le.** that the f
a3f0: 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
a400: 6f 66 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  of [sqlite3_file
a410: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 70 6f 69 6e  _control()] poin
a420: 74 73 20 74 6f 2e 0a 2a 2a 20 54 68 65 20 63 61  ts to..** The ca
a430: 6c 6c 65 72 20 69 73 20 72 65 73 70 6f 6e 73 69  ller is responsi
a440: 62 6c 65 20 66 6f 72 20 66 72 65 65 69 6e 67 20  ble for freeing 
a450: 74 68 65 20 6d 65 6d 6f 72 79 20 77 68 65 6e 20  the memory when 
a460: 64 6f 6e 65 2e 20 20 41 73 20 77 69 74 68 0a 2a  done.  As with.*
a470: 2a 20 61 6c 6c 20 66 69 6c 65 2d 63 6f 6e 74 72  * all file-contr
a480: 6f 6c 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 72  ol actions, ther
a490: 65 20 69 73 20 6e 6f 20 67 75 61 72 61 6e 74 65  e is no guarante
a4a0: 65 20 74 68 61 74 20 74 68 69 73 20 77 69 6c 6c  e that this will
a4b0: 20 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 64 6f 20   actually.** do 
a4c0: 61 6e 79 74 68 69 6e 67 2e 20 20 43 61 6c 6c 65  anything.  Calle
a4d0: 72 73 20 73 68 6f 75 6c 64 20 69 6e 69 74 69 61  rs should initia
a4e0: 6c 69 7a 65 20 74 68 65 20 63 68 61 72 2a 20 76  lize the char* v
a4f0: 61 72 69 61 62 6c 65 20 74 6f 20 61 20 4e 55 4c  ariable to a NUL
a500: 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 20  L.** pointer in 
a510: 63 61 73 65 20 74 68 69 73 20 66 69 6c 65 2d 63  case this file-c
a520: 6f 6e 74 72 6f 6c 20 69 73 20 6e 6f 74 20 69 6d  ontrol is not im
a530: 70 6c 65 6d 65 6e 74 65 64 2e 20 20 54 68 69 73  plemented.  This
a540: 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a   file-control.**
a550: 20 69 73 20 69 6e 74 65 6e 64 65 64 20 66 6f 72   is intended for
a560: 20 64 69 61 67 6e 6f 73 74 69 63 20 75 73 65 20   diagnostic use 
a570: 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  only..**.** <li>
a580: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50  [[SQLITE_FCNTL_P
a590: 52 41 47 4d 41 5d 5d 0a 2a 2a 20 5e 57 68 65 6e  RAGMA]].** ^When
a5a0: 65 76 65 72 20 61 20 5b 50 52 41 47 4d 41 5d 20  ever a [PRAGMA] 
a5b0: 73 74 61 74 65 6d 65 6e 74 20 69 73 20 70 61 72  statement is par
a5c0: 73 65 64 2c 20 61 6e 20 5b 53 51 4c 49 54 45 5f  sed, an [SQLITE_
a5d0: 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 0a 2a  FCNTL_PRAGMA] .*
a5e0: 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69  * file control i
a5f0: 73 20 73 65 6e 74 20 74 6f 20 74 68 65 20 6f 70  s sent to the op
a600: 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  en [sqlite3_file
a610: 5d 20 6f 62 6a 65 63 74 20 63 6f 72 72 65 73 70  ] object corresp
a620: 6f 6e 64 69 6e 67 0a 2a 2a 20 74 6f 20 74 68 65  onding.** to the
a630: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 74   database file t
a640: 6f 20 77 68 69 63 68 20 74 68 65 20 70 72 61 67  o which the prag
a650: 6d 61 20 73 74 61 74 65 6d 65 6e 74 20 72 65 66  ma statement ref
a660: 65 72 73 2e 20 5e 54 68 65 20 61 72 67 75 6d 65  ers. ^The argume
a670: 6e 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 53 51  nt.** to the [SQ
a680: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d  LITE_FCNTL_PRAGM
a690: 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  A] file control 
a6a0: 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 0a 2a  is an array of.*
a6b0: 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74  * pointers to st
a6c0: 72 69 6e 67 73 20 28 63 68 61 72 2a 2a 29 20 69  rings (char**) i
a6d0: 6e 20 77 68 69 63 68 20 74 68 65 20 73 65 63 6f  n which the seco
a6e0: 6e 64 20 65 6c 65 6d 65 6e 74 20 6f 66 20 74 68  nd element of th
a6f0: 65 20 61 72 72 61 79 0a 2a 2a 20 69 73 20 74 68  e array.** is th
a700: 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 70 72  e name of the pr
a710: 61 67 6d 61 20 61 6e 64 20 74 68 65 20 74 68 69  agma and the thi
a720: 72 64 20 65 6c 65 6d 65 6e 74 20 69 73 20 74 68  rd element is th
a730: 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  e argument to th
a740: 65 0a 2a 2a 20 70 72 61 67 6d 61 20 6f 72 20 4e  e.** pragma or N
a750: 55 4c 4c 20 69 66 20 74 68 65 20 70 72 61 67 6d  ULL if the pragm
a760: 61 20 68 61 73 20 6e 6f 20 61 72 67 75 6d 65 6e  a has no argumen
a770: 74 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 72  t.  ^The handler
a780: 20 66 6f 72 20 61 6e 0a 2a 2a 20 5b 53 51 4c 49   for an.** [SQLI
a790: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d  TE_FCNTL_PRAGMA]
a7a0: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 63 61   file control ca
a7b0: 6e 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 6d 61 6b  n optionally mak
a7c0: 65 20 74 68 65 20 66 69 72 73 74 20 65 6c 65 6d  e the first elem
a7d0: 65 6e 74 0a 2a 2a 20 6f 66 20 74 68 65 20 63 68  ent.** of the ch
a7e0: 61 72 2a 2a 20 61 72 67 75 6d 65 6e 74 20 70 6f  ar** argument po
a7f0: 69 6e 74 20 74 6f 20 61 20 73 74 72 69 6e 67 20  int to a string 
a800: 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73  obtained from [s
a810: 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29  qlite3_mprintf()
a820: 5d 0a 2a 2a 20 6f 72 20 74 68 65 20 65 71 75 69  ].** or the equi
a830: 76 61 6c 65 6e 74 20 61 6e 64 20 74 68 61 74 20  valent and that 
a840: 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 63 6f  string will beco
a850: 6d 65 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66  me the result of
a860: 20 74 68 65 20 70 72 61 67 6d 61 20 6f 72 0a 2a   the pragma or.*
a870: 2a 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73  * the error mess
a880: 61 67 65 20 69 66 20 74 68 65 20 70 72 61 67 6d  age if the pragm
a890: 61 20 66 61 69 6c 73 2e 20 5e 49 66 20 74 68 65  a fails. ^If the
a8a0: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  .** [SQLITE_FCNT
a8b0: 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63  L_PRAGMA] file c
a8c0: 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b  ontrol returns [
a8d0: 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d  SQLITE_NOTFOUND]
a8e0: 2c 20 74 68 65 6e 20 6e 6f 72 6d 61 6c 20 0a 2a  , then normal .*
a8f0: 2a 20 5b 50 52 41 47 4d 41 5d 20 70 72 6f 63 65  * [PRAGMA] proce
a900: 73 73 69 6e 67 20 63 6f 6e 74 69 6e 75 65 73 2e  ssing continues.
a910: 20 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54    ^If the [SQLIT
a920: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a  E_FCNTL_PRAGMA].
a930: 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  ** file control 
a940: 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
a950: 4f 4b 5d 2c 20 74 68 65 6e 20 74 68 65 20 70 61  OK], then the pa
a960: 72 73 65 72 20 61 73 73 75 6d 65 73 20 74 68 61  rser assumes tha
a970: 74 20 74 68 65 0a 2a 2a 20 56 46 53 20 68 61 73  t the.** VFS has
a980: 20 68 61 6e 64 6c 65 64 20 74 68 65 20 50 52 41   handled the PRA
a990: 47 4d 41 20 69 74 73 65 6c 66 20 61 6e 64 20 74  GMA itself and t
a9a0: 68 65 20 70 61 72 73 65 72 20 67 65 6e 65 72 61  he parser genera
a9b0: 74 65 73 20 61 20 6e 6f 2d 6f 70 0a 2a 2a 20 70  tes a no-op.** p
a9c0: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
a9d0: 74 2e 20 20 5e 49 66 20 74 68 65 20 5b 53 51 4c  t.  ^If the [SQL
a9e0: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41  ITE_FCNTL_PRAGMA
a9f0: 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72  ] file control r
aa00: 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 72 65  eturns.** any re
aa10: 73 75 6c 74 20 63 6f 64 65 20 6f 74 68 65 72 20  sult code other 
aa20: 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  than [SQLITE_OK]
aa30: 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46   or [SQLITE_NOTF
aa40: 4f 55 4e 44 5d 2c 20 74 68 61 74 20 6d 65 61 6e  OUND], that mean
aa50: 73 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 56 46  s.** that the VF
aa60: 53 20 65 6e 63 6f 75 6e 74 65 72 65 64 20 61 6e  S encountered an
aa70: 20 65 72 72 6f 72 20 77 68 69 6c 65 20 68 61 6e   error while han
aa80: 64 6c 69 6e 67 20 74 68 65 20 5b 50 52 41 47 4d  dling the [PRAGM
aa90: 41 5d 20 61 6e 64 20 74 68 65 0a 2a 2a 20 63 6f  A] and the.** co
aaa0: 6d 70 69 6c 61 74 69 6f 6e 20 6f 66 20 74 68 65  mpilation of the
aab0: 20 50 52 41 47 4d 41 20 66 61 69 6c 73 20 77 69   PRAGMA fails wi
aac0: 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e 54  th an error.  ^T
aad0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
aae0: 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65  _PRAGMA].** file
aaf0: 20 63 6f 6e 74 72 6f 6c 20 6f 63 63 75 72 73 20   control occurs 
ab00: 61 74 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67  at the beginning
ab10: 20 6f 66 20 70 72 61 67 6d 61 20 73 74 61 74 65   of pragma state
ab20: 6d 65 6e 74 20 61 6e 61 6c 79 73 69 73 20 61 6e  ment analysis an
ab30: 64 20 73 6f 0a 2a 2a 20 69 74 20 69 73 20 61 62  d so.** it is ab
ab40: 6c 65 20 74 6f 20 6f 76 65 72 72 69 64 65 20 62  le to override b
ab50: 75 69 6c 74 2d 69 6e 20 5b 50 52 41 47 4d 41 5d  uilt-in [PRAGMA]
ab60: 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a   statements..**.
ab70: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
ab80: 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45  FCNTL_BUSYHANDLE
ab90: 52 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  R]].** ^The [SQL
aba0: 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41  ITE_FCNTL_BUSYHA
abb0: 4e 44 4c 45 52 5d 0a 2a 2a 20 66 69 6c 65 2d 63  NDLER].** file-c
abc0: 6f 6e 74 72 6f 6c 20 6d 61 79 20 62 65 20 69 6e  ontrol may be in
abd0: 76 6f 6b 65 64 20 62 79 20 53 51 4c 69 74 65 20  voked by SQLite 
abe0: 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  on the database 
abf0: 66 69 6c 65 20 68 61 6e 64 6c 65 0a 2a 2a 20 73  file handle.** s
ac00: 68 6f 72 74 6c 79 20 61 66 74 65 72 20 69 74 20  hortly after it 
ac10: 69 73 20 6f 70 65 6e 65 64 20 69 6e 20 6f 72 64  is opened in ord
ac20: 65 72 20 74 6f 20 70 72 6f 76 69 64 65 20 61 20  er to provide a 
ac30: 63 75 73 74 6f 6d 20 56 46 53 20 77 69 74 68 20  custom VFS with 
ac40: 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 74 68 65  access.** to the
ac50: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 62 75 73   connections bus
ac60: 79 2d 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61  y-handler callba
ac70: 63 6b 2e 20 54 68 65 20 61 72 67 75 6d 65 6e 74  ck. The argument
ac80: 20 69 73 20 6f 66 20 74 79 70 65 20 28 76 6f 69   is of type (voi
ac90: 64 20 2a 2a 29 0a 2a 2a 20 2d 20 61 6e 20 61 72  d **).** - an ar
aca0: 72 61 79 20 6f 66 20 74 77 6f 20 28 76 6f 69 64  ray of two (void
acb0: 20 2a 29 20 76 61 6c 75 65 73 2e 20 54 68 65 20   *) values. The 
acc0: 66 69 72 73 74 20 28 76 6f 69 64 20 2a 29 20 61  first (void *) a
acd0: 63 74 75 61 6c 6c 79 20 70 6f 69 6e 74 73 0a 2a  ctually points.*
ace0: 2a 20 74 6f 20 61 20 66 75 6e 63 74 69 6f 6e 20  * to a function 
acf0: 6f 66 20 74 79 70 65 20 28 69 6e 74 20 28 2a 29  of type (int (*)
ad00: 28 76 6f 69 64 20 2a 29 29 2e 20 49 6e 20 6f 72  (void *)). In or
ad10: 64 65 72 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68  der to invoke th
ad20: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a  e connections.**
ad30: 20 62 75 73 79 2d 68 61 6e 64 6c 65 72 2c 20 74   busy-handler, t
ad40: 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f  his function sho
ad50: 75 6c 64 20 62 65 20 69 6e 76 6f 6b 65 64 20 77  uld be invoked w
ad60: 69 74 68 20 74 68 65 20 73 65 63 6f 6e 64 20 28  ith the second (
ad70: 76 6f 69 64 20 2a 29 20 69 6e 0a 2a 2a 20 74 68  void *) in.** th
ad80: 65 20 61 72 72 61 79 20 61 73 20 74 68 65 20 6f  e array as the o
ad90: 6e 6c 79 20 61 72 67 75 6d 65 6e 74 2e 20 49 66  nly argument. If
ada0: 20 69 74 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d   it returns non-
adb0: 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 6f  zero, then the o
adc0: 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75  peration.** shou
add0: 6c 64 20 62 65 20 72 65 74 72 69 65 64 2e 20 49  ld be retried. I
ade0: 66 20 69 74 20 72 65 74 75 72 6e 73 20 7a 65 72  f it returns zer
adf0: 6f 2c 20 74 68 65 20 63 75 73 74 6f 6d 20 56 46  o, the custom VF
ae00: 53 20 73 68 6f 75 6c 64 20 61 62 61 6e 64 6f 6e  S should abandon
ae10: 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20   the.** current 
ae20: 6f 70 65 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  operation..**.**
ae30: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
ae40: 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45  NTL_TEMPFILENAME
ae50: 5d 5d 0a 2a 2a 20 5e 41 70 70 6c 69 63 61 74 69  ]].** ^Applicati
ae60: 6f 6e 20 63 61 6e 20 69 6e 76 6f 6b 65 20 74 68  on can invoke th
ae70: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
ae80: 54 45 4d 50 46 49 4c 45 4e 41 4d 45 5d 20 66 69  TEMPFILENAME] fi
ae90: 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 74 6f  le-control.** to
aea0: 20 68 61 76 65 20 53 51 4c 69 74 65 20 67 65 6e   have SQLite gen
aeb0: 65 72 61 74 65 20 61 0a 2a 2a 20 74 65 6d 70 6f  erate a.** tempo
aec0: 72 61 72 79 20 66 69 6c 65 6e 61 6d 65 20 75 73  rary filename us
aed0: 69 6e 67 20 74 68 65 20 73 61 6d 65 20 61 6c 67  ing the same alg
aee0: 6f 72 69 74 68 6d 20 74 68 61 74 20 69 73 20 66  orithm that is f
aef0: 6f 6c 6c 6f 77 65 64 20 74 6f 20 67 65 6e 65 72  ollowed to gener
af00: 61 74 65 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79  ate.** temporary
af10: 20 66 69 6c 65 6e 61 6d 65 73 20 66 6f 72 20 54   filenames for T
af20: 45 4d 50 20 74 61 62 6c 65 73 20 61 6e 64 20 6f  EMP tables and o
af30: 74 68 65 72 20 69 6e 74 65 72 6e 61 6c 20 75 73  ther internal us
af40: 65 73 2e 20 20 54 68 65 0a 2a 2a 20 61 72 67 75  es.  The.** argu
af50: 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 61  ment should be a
af60: 20 63 68 61 72 2a 2a 20 77 68 69 63 68 20 77 69   char** which wi
af70: 6c 6c 20 62 65 20 66 69 6c 6c 65 64 20 77 69 74  ll be filled wit
af80: 68 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 0a 2a  h the filename.*
af90: 2a 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d  * written into m
afa0: 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66  emory obtained f
afb0: 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
afc0: 6c 6f 63 28 29 5d 2e 20 20 54 68 65 20 63 61 6c  loc()].  The cal
afd0: 6c 65 72 20 73 68 6f 75 6c 64 0a 2a 2a 20 69 6e  ler should.** in
afe0: 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66 72  voke [sqlite3_fr
aff0: 65 65 28 29 5d 20 6f 6e 20 74 68 65 20 72 65 73  ee()] on the res
b000: 75 6c 74 20 74 6f 20 61 76 6f 69 64 20 61 20 6d  ult to avoid a m
b010: 65 6d 6f 72 79 20 6c 65 61 6b 2e 0a 2a 2a 0a 2a  emory leak..**.*
b020: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
b030: 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d  CNTL_MMAP_SIZE]]
b040: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
b050: 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d  FCNTL_MMAP_SIZE]
b060: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73   file control is
b070: 20 75 73 65 64 20 74 6f 20 71 75 65 72 79 20 6f   used to query o
b080: 72 20 73 65 74 20 74 68 65 0a 2a 2a 20 6d 61 78  r set the.** max
b090: 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 62  imum number of b
b0a0: 79 74 65 73 20 74 68 61 74 20 77 69 6c 6c 20 62  ytes that will b
b0b0: 65 20 75 73 65 64 20 66 6f 72 20 6d 65 6d 6f 72  e used for memor
b0c0: 79 2d 6d 61 70 70 65 64 20 49 2f 4f 2e 0a 2a 2a  y-mapped I/O..**
b0d0: 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73   The argument is
b0e0: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
b0f0: 76 61 6c 75 65 20 6f 66 20 74 79 70 65 20 73 71  value of type sq
b100: 6c 69 74 65 33 5f 69 6e 74 36 34 20 74 68 61 74  lite3_int64 that
b110: 0a 2a 2a 20 69 73 20 61 6e 20 61 64 76 69 73 6f  .** is an adviso
b120: 72 79 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  ry maximum numbe
b130: 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
b140: 65 20 66 69 6c 65 20 74 6f 20 6d 65 6d 6f 72 79  e file to memory
b150: 20 6d 61 70 2e 20 20 54 68 65 0a 2a 2a 20 70 6f   map.  The.** po
b160: 69 6e 74 65 72 20 69 73 20 6f 76 65 72 77 72 69  inter is overwri
b170: 74 74 65 6e 20 77 69 74 68 20 74 68 65 20 6f 6c  tten with the ol
b180: 64 20 76 61 6c 75 65 2e 20 20 54 68 65 20 6c 69  d value.  The li
b190: 6d 69 74 20 69 73 20 6e 6f 74 20 63 68 61 6e 67  mit is not chang
b1a0: 65 64 20 69 66 0a 2a 2a 20 74 68 65 20 76 61 6c  ed if.** the val
b1b0: 75 65 20 6f 72 69 67 69 6e 61 6c 6c 79 20 70 6f  ue originally po
b1c0: 69 6e 74 65 64 20 74 6f 20 69 73 20 6e 65 67 61  inted to is nega
b1d0: 74 69 76 65 2c 20 61 6e 64 20 73 6f 20 74 68 65  tive, and so the
b1e0: 20 63 75 72 72 65 6e 74 20 6c 69 6d 69 74 20 0a   current limit .
b1f0: 2a 2a 20 63 61 6e 20 62 65 20 71 75 65 72 69 65  ** can be querie
b200: 64 20 62 79 20 70 61 73 73 69 6e 67 20 69 6e 20  d by passing in 
b210: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6e  a pointer to a n
b220: 65 67 61 74 69 76 65 20 6e 75 6d 62 65 72 2e 20  egative number. 
b230: 20 54 68 69 73 0a 2a 2a 20 66 69 6c 65 2d 63 6f   This.** file-co
b240: 6e 74 72 6f 6c 20 69 73 20 75 73 65 64 20 69 6e  ntrol is used in
b250: 74 65 72 6e 61 6c 6c 79 20 74 6f 20 69 6d 70 6c  ternally to impl
b260: 65 6d 65 6e 74 20 5b 50 52 41 47 4d 41 20 6d 6d  ement [PRAGMA mm
b270: 61 70 5f 73 69 7a 65 5d 2e 0a 2a 2a 0a 2a 2a 20  ap_size]..**.** 
b280: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
b290: 54 4c 5f 54 52 41 43 45 5d 5d 0a 2a 2a 20 54 68  TL_TRACE]].** Th
b2a0: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
b2b0: 54 52 41 43 45 5d 20 66 69 6c 65 20 63 6f 6e 74  TRACE] file cont
b2c0: 72 6f 6c 20 70 72 6f 76 69 64 65 73 20 61 64 76  rol provides adv
b2d0: 69 73 6f 72 79 20 69 6e 66 6f 72 6d 61 74 69 6f  isory informatio
b2e0: 6e 0a 2a 2a 20 74 6f 20 74 68 65 20 56 46 53 20  n.** to the VFS 
b2f0: 61 62 6f 75 74 20 77 68 61 74 20 74 68 65 20 68  about what the h
b300: 69 67 68 65 72 20 6c 61 79 65 72 73 20 6f 66 20  igher layers of 
b310: 74 68 65 20 53 51 4c 69 74 65 20 73 74 61 63 6b  the SQLite stack
b320: 20 61 72 65 20 64 6f 69 6e 67 2e 0a 2a 2a 20 54   are doing..** T
b330: 68 69 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  his file control
b340: 20 69 73 20 75 73 65 64 20 62 79 20 73 6f 6d 65   is used by some
b350: 20 56 46 53 20 61 63 74 69 76 69 74 79 20 74 72   VFS activity tr
b360: 61 63 69 6e 67 20 5b 73 68 69 6d 73 5d 2e 0a 2a  acing [shims]..*
b370: 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69  * The argument i
b380: 73 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  s a zero-termina
b390: 74 65 64 20 73 74 72 69 6e 67 2e 20 20 48 69 67  ted string.  Hig
b3a0: 68 65 72 20 6c 61 79 65 72 73 20 69 6e 20 74 68  her layers in th
b3b0: 65 0a 2a 2a 20 53 51 4c 69 74 65 20 73 74 61 63  e.** SQLite stac
b3c0: 6b 20 6d 61 79 20 67 65 6e 65 72 61 74 65 20 69  k may generate i
b3d0: 6e 73 74 61 6e 63 65 73 20 6f 66 20 74 68 69 73  nstances of this
b3e0: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 66   file control if
b3f0: 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  .** the [SQLITE_
b400: 55 53 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d  USE_FCNTL_TRACE]
b410: 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
b420: 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e  tion is enabled.
b430: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
b440: 49 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f  ITE_FCNTL_HAS_MO
b450: 56 45 44 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  VED]].** The [SQ
b460: 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d  LITE_FCNTL_HAS_M
b470: 4f 56 45 44 5d 20 66 69 6c 65 20 63 6f 6e 74 72  OVED] file contr
b480: 6f 6c 20 69 6e 74 65 72 70 72 65 74 73 20 69 74  ol interprets it
b490: 73 20 61 72 67 75 6d 65 6e 74 20 61 73 20 61 0a  s argument as a.
b4a0: 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e  ** pointer to an
b4b0: 20 69 6e 74 65 67 65 72 20 61 6e 64 20 69 74 20   integer and it 
b4c0: 77 72 69 74 65 73 20 61 20 62 6f 6f 6c 65 61 6e  writes a boolean
b4d0: 20 69 6e 74 6f 20 74 68 61 74 20 69 6e 74 65 67   into that integ
b4e0: 65 72 20 64 65 70 65 6e 64 69 6e 67 0a 2a 2a 20  er depending.** 
b4f0: 6f 6e 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  on whether or no
b500: 74 20 74 68 65 20 66 69 6c 65 20 68 61 73 20 62  t the file has b
b510: 65 65 6e 20 72 65 6e 61 6d 65 64 2c 20 6d 6f 76  een renamed, mov
b520: 65 64 2c 20 6f 72 20 64 65 6c 65 74 65 64 20 73  ed, or deleted s
b530: 69 6e 63 65 20 69 74 0a 2a 2a 20 77 61 73 20 66  ince it.** was f
b540: 69 72 73 74 20 6f 70 65 6e 65 64 2e 0a 2a 2a 0a  irst opened..**.
b550: 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 23 64 65 66  ** </ul>.*/.#def
b560: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
b570: 5f 4c 4f 43 4b 53 54 41 54 45 20 20 20 20 20 20  _LOCKSTATE      
b580: 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69           1.#defi
b590: 6e 65 20 53 51 4c 49 54 45 5f 47 45 54 5f 4c 4f  ne SQLITE_GET_LO
b5a0: 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20  CKPROXYFILE     
b5b0: 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e          2.#defin
b5c0: 65 20 53 51 4c 49 54 45 5f 53 45 54 5f 4c 4f 43  e SQLITE_SET_LOC
b5d0: 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20  KPROXYFILE      
b5e0: 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65         3.#define
b5f0: 20 53 51 4c 49 54 45 5f 4c 41 53 54 5f 45 52 52   SQLITE_LAST_ERR
b600: 4e 4f 20 20 20 20 20 20 20 20 20 20 20 20 20 20  NO              
b610: 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20        4.#define 
b620: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a  SQLITE_FCNTL_SIZ
b630: 45 5f 48 49 4e 54 20 20 20 20 20 20 20 20 20 20  E_HINT          
b640: 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53       5.#define S
b650: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e  QLITE_FCNTL_CHUN
b660: 4b 5f 53 49 5a 45 20 20 20 20 20 20 20 20 20 20  K_SIZE          
b670: 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20 53 51      6.#define SQ
b680: 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f  LITE_FCNTL_FILE_
b690: 50 4f 49 4e 54 45 52 20 20 20 20 20 20 20 20 20  POINTER         
b6a0: 20 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c     7.#define SQL
b6b0: 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f  ITE_FCNTL_SYNC_O
b6c0: 4d 49 54 54 45 44 20 20 20 20 20 20 20 20 20 20  MITTED          
b6d0: 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    8.#define SQLI
b6e0: 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41  TE_FCNTL_WIN32_A
b6f0: 56 5f 52 45 54 52 59 20 20 20 20 20 20 20 20 20  V_RETRY         
b700: 20 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   9.#define SQLIT
b710: 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f  E_FCNTL_PERSIST_
b720: 57 41 4c 20 20 20 20 20 20 20 20 20 20 20 20 31  WAL            1
b730: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
b740: 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45  _FCNTL_OVERWRITE
b750: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 31                11
b760: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
b770: 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 20 20 20  FCNTL_VFSNAME   
b780: 20 20 20 20 20 20 20 20 20 20 20 20 20 31 32 0a               12.
b790: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
b7a0: 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f  CNTL_POWERSAFE_O
b7b0: 56 45 52 57 52 49 54 45 20 20 20 20 31 33 0a 23  VERWRITE    13.#
b7c0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
b7d0: 4e 54 4c 5f 50 52 41 47 4d 41 20 20 20 20 20 20  NTL_PRAGMA      
b7e0: 20 20 20 20 20 20 20 20 20 20 20 31 34 0a 23 64             14.#d
b7f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
b800: 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52 20 20  TL_BUSYHANDLER  
b810: 20 20 20 20 20 20 20 20 20 20 31 35 0a 23 64 65            15.#de
b820: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
b830: 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45 20 20  L_TEMPFILENAME  
b840: 20 20 20 20 20 20 20 20 20 31 36 0a 23 64 65 66           16.#def
b850: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
b860: 5f 4d 4d 41 50 5f 53 49 5a 45 20 20 20 20 20 20  _MMAP_SIZE      
b870: 20 20 20 20 20 20 20 20 31 38 0a 23 64 65 66 69          18.#defi
b880: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
b890: 54 52 41 43 45 20 20 20 20 20 20 20 20 20 20 20  TRACE           
b8a0: 20 20 20 20 20 20 20 31 39 0a 23 64 65 66 69 6e         19.#defin
b8b0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48  e SQLITE_FCNTL_H
b8c0: 41 53 5f 4d 4f 56 45 44 20 20 20 20 20 20 20 20  AS_MOVED        
b8d0: 20 20 20 20 20 20 32 30 0a 23 64 65 66 69 6e 65        20.#define
b8e0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59   SQLITE_FCNTL_SY
b8f0: 4e 43 20 20 20 20 20 20 20 20 20 20 20 20 20 20  NC              
b900: 20 20 20 20 20 32 31 0a 23 64 65 66 69 6e 65 20       21.#define 
b910: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d  SQLITE_FCNTL_COM
b920: 4d 49 54 5f 50 48 41 53 45 54 57 4f 20 20 20 20  MIT_PHASETWO    
b930: 20 20 20 20 32 32 0a 0a 2f 2a 0a 2a 2a 20 43 41      22../*.** CA
b940: 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20 48 61  PI3REF: Mutex Ha
b950: 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d  ndle.**.** The m
b960: 75 74 65 78 20 6d 6f 64 75 6c 65 20 77 69 74 68  utex module with
b970: 69 6e 20 53 51 4c 69 74 65 20 64 65 66 69 6e 65  in SQLite define
b980: 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  s [sqlite3_mutex
b990: 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a 20 61 62  ] to be an.** ab
b9a0: 73 74 72 61 63 74 20 74 79 70 65 20 66 6f 72 20  stract type for 
b9b0: 61 20 6d 75 74 65 78 20 6f 62 6a 65 63 74 2e 20  a mutex object. 
b9c0: 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   The SQLite core
b9d0: 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a 2a 20   never looks.** 
b9e0: 61 74 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20  at the internal 
b9f0: 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 6f  representation o
ba00: 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 6d 75  f an [sqlite3_mu
ba10: 74 65 78 5d 2e 20 20 49 74 20 6f 6e 6c 79 0a 2a  tex].  It only.*
ba20: 2a 20 64 65 61 6c 73 20 77 69 74 68 20 70 6f 69  * deals with poi
ba30: 6e 74 65 72 73 20 74 6f 20 74 68 65 20 5b 73 71  nters to the [sq
ba40: 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 6f 62 6a  lite3_mutex] obj
ba50: 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74 65 78  ect..**.** Mutex
ba60: 65 73 20 61 72 65 20 63 72 65 61 74 65 64 20 75  es are created u
ba70: 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75  sing [sqlite3_mu
ba80: 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f  tex_alloc()]..*/
ba90: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
baa0: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 73 71  sqlite3_mutex sq
bab0: 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a 0a 2f 2a  lite3_mutex;../*
bac0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53  .** CAPI3REF: OS
bad0: 20 49 6e 74 65 72 66 61 63 65 20 4f 62 6a 65 63   Interface Objec
bae0: 74 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61  t.**.** An insta
baf0: 6e 63 65 20 6f 66 20 74 68 65 20 73 71 6c 69 74  nce of the sqlit
bb00: 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 64 65  e3_vfs object de
bb10: 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66  fines the interf
bb20: 61 63 65 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74  ace between.** t
bb30: 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 61  he SQLite core a
bb40: 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e  nd the underlyin
bb50: 67 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  g operating syst
bb60: 65 6d 2e 20 20 54 68 65 20 22 76 66 73 22 0a 2a  em.  The "vfs".*
bb70: 2a 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66  * in the name of
bb80: 20 74 68 65 20 6f 62 6a 65 63 74 20 73 74 61 6e   the object stan
bb90: 64 73 20 66 6f 72 20 22 76 69 72 74 75 61 6c 20  ds for "virtual 
bba0: 66 69 6c 65 20 73 79 73 74 65 6d 22 2e 20 20 53  file system".  S
bbb0: 65 65 0a 2a 2a 20 74 68 65 20 5b 56 46 53 20 7c  ee.** the [VFS |
bbc0: 20 56 46 53 20 64 6f 63 75 6d 65 6e 74 61 74 69   VFS documentati
bbd0: 6f 6e 5d 20 66 6f 72 20 66 75 72 74 68 65 72 20  on] for further 
bbe0: 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a  information..**.
bbf0: 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 6f 66 20  ** The value of 
bc00: 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66 69 65  the iVersion fie
bc10: 6c 64 20 69 73 20 69 6e 69 74 69 61 6c 6c 79 20  ld is initially 
bc20: 31 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72  1 but may be lar
bc30: 67 65 72 20 69 6e 0a 2a 2a 20 66 75 74 75 72 65  ger in.** future
bc40: 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
bc50: 69 74 65 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c  ite.  Additional
bc60: 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61   fields may be a
bc70: 70 70 65 6e 64 65 64 20 74 6f 20 74 68 69 73 0a  ppended to this.
bc80: 2a 2a 20 6f 62 6a 65 63 74 20 77 68 65 6e 20 74  ** object when t
bc90: 68 65 20 69 56 65 72 73 69 6f 6e 20 76 61 6c 75  he iVersion valu
bca0: 65 20 69 73 20 69 6e 63 72 65 61 73 65 64 2e 20  e is increased. 
bcb0: 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 73   Note that the s
bcc0: 74 72 75 63 74 75 72 65 0a 2a 2a 20 6f 66 20 74  tructure.** of t
bcd0: 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f  he sqlite3_vfs o
bce0: 62 6a 65 63 74 20 63 68 61 6e 67 65 73 20 69 6e  bject changes in
bcf0: 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e   the transaction
bd00: 20 62 65 74 77 65 65 6e 0a 2a 2a 20 53 51 4c 69   between.** SQLi
bd10: 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 39  te version 3.5.9
bd20: 20 61 6e 64 20 33 2e 36 2e 30 20 61 6e 64 20 79   and 3.6.0 and y
bd30: 65 74 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20  et the iVersion 
bd40: 66 69 65 6c 64 20 77 61 73 20 6e 6f 74 0a 2a 2a  field was not.**
bd50: 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a 2a 2a   modified..**.**
bd60: 20 54 68 65 20 73 7a 4f 73 46 69 6c 65 20 66 69   The szOsFile fi
bd70: 65 6c 64 20 69 73 20 74 68 65 20 73 69 7a 65 20  eld is the size 
bd80: 6f 66 20 74 68 65 20 73 75 62 63 6c 61 73 73 65  of the subclasse
bd90: 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  d [sqlite3_file]
bda0: 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 75 73  .** structure us
bdb0: 65 64 20 62 79 20 74 68 69 73 20 56 46 53 2e 20  ed by this VFS. 
bdc0: 20 6d 78 50 61 74 68 6e 61 6d 65 20 69 73 20 74   mxPathname is t
bdd0: 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  he maximum lengt
bde0: 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74 68 6e 61  h of.** a pathna
bdf0: 6d 65 20 69 6e 20 74 68 69 73 20 56 46 53 2e 0a  me in this VFS..
be00: 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72 65 64  **.** Registered
be10: 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a   sqlite3_vfs obj
be20: 65 63 74 73 20 61 72 65 20 6b 65 70 74 20 6f 6e  ects are kept on
be30: 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73 74 20 66   a linked list f
be40: 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74 68 65 20  ormed by.** the 
be50: 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 20 20  pNext pointer.  
be60: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  The [sqlite3_vfs
be70: 5f 72 65 67 69 73 74 65 72 28 29 5d 0a 2a 2a 20  _register()].** 
be80: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  and [sqlite3_vfs
be90: 5f 75 6e 72 65 67 69 73 74 65 72 28 29 5d 20 69  _unregister()] i
bea0: 6e 74 65 72 66 61 63 65 73 20 6d 61 6e 61 67 65  nterfaces manage
beb0: 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a 20 69 6e   this list.** in
bec0: 20 61 20 74 68 72 65 61 64 2d 73 61 66 65 20 77   a thread-safe w
bed0: 61 79 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65  ay.  The [sqlite
bee0: 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d 20 69 6e  3_vfs_find()] in
bef0: 74 65 72 66 61 63 65 0a 2a 2a 20 73 65 61 72 63  terface.** searc
bf00: 68 65 73 20 74 68 65 20 6c 69 73 74 2e 20 20 4e  hes the list.  N
bf10: 65 69 74 68 65 72 20 74 68 65 20 61 70 70 6c 69  either the appli
bf20: 63 61 74 69 6f 6e 20 63 6f 64 65 20 6e 6f 72 20  cation code nor 
bf30: 74 68 65 20 56 46 53 0a 2a 2a 20 69 6d 70 6c 65  the VFS.** imple
bf40: 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64  mentation should
bf50: 20 75 73 65 20 74 68 65 20 70 4e 65 78 74 20 70   use the pNext p
bf60: 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  ointer..**.** Th
bf70: 65 20 70 4e 65 78 74 20 66 69 65 6c 64 20 69 73  e pNext field is
bf80: 20 74 68 65 20 6f 6e 6c 79 20 66 69 65 6c 64 20   the only field 
bf90: 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76  in the sqlite3_v
bfa0: 66 73 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20  fs.** structure 
bfb0: 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c  that SQLite will
bfc0: 20 65 76 65 72 20 6d 6f 64 69 66 79 2e 20 20 53   ever modify.  S
bfd0: 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c 79 20  QLite will only 
bfe0: 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20 6d 6f 64  access.** or mod
bff0: 69 66 79 20 74 68 69 73 20 66 69 65 6c 64 20 77  ify this field w
c000: 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20 61 20 70  hile holding a p
c010: 61 72 74 69 63 75 6c 61 72 20 73 74 61 74 69 63  articular static
c020: 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68 65 20 61   mutex..** The a
c030: 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
c040: 64 20 6e 65 76 65 72 20 6d 6f 64 69 66 79 20 61  d never modify a
c050: 6e 79 74 68 69 6e 67 20 77 69 74 68 69 6e 20 74  nything within t
c060: 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a  he sqlite3_vfs.*
c070: 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65 20 74 68  * object once th
c080: 65 20 6f 62 6a 65 63 74 20 68 61 73 20 62 65 65  e object has bee
c090: 6e 20 72 65 67 69 73 74 65 72 65 64 2e 0a 2a 2a  n registered..**
c0a0: 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65 20 66 69  .** The zName fi
c0b0: 65 6c 64 20 68 6f 6c 64 73 20 74 68 65 20 6e 61  eld holds the na
c0c0: 6d 65 20 6f 66 20 74 68 65 20 56 46 53 20 6d 6f  me of the VFS mo
c0d0: 64 75 6c 65 2e 20 20 54 68 65 20 6e 61 6d 65 20  dule.  The name 
c0e0: 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e 69 71 75  must.** be uniqu
c0f0: 65 20 61 63 72 6f 73 73 20 61 6c 6c 20 56 46 53  e across all VFS
c100: 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20   modules..**.** 
c110: 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f  [[sqlite3_vfs.xO
c120: 70 65 6e 5d 5d 0a 2a 2a 20 5e 53 51 4c 69 74 65  pen]].** ^SQLite
c130: 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74   guarantees that
c140: 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70   the zFilename p
c150: 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65  arameter to xOpe
c160: 6e 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20 61  n.** is either a
c170: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72   NULL pointer or
c180: 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64   string obtained
c190: 0a 2a 2a 20 66 72 6f 6d 20 78 46 75 6c 6c 50 61  .** from xFullPa
c1a0: 74 68 6e 61 6d 65 28 29 20 77 69 74 68 20 61 6e  thname() with an
c1b0: 20 6f 70 74 69 6f 6e 61 6c 20 73 75 66 66 69 78   optional suffix
c1c0: 20 61 64 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 61   added..** ^If a
c1d0: 20 73 75 66 66 69 78 20 69 73 20 61 64 64 65 64   suffix is added
c1e0: 20 74 6f 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d   to the zFilenam
c1f0: 65 20 70 61 72 61 6d 65 74 65 72 2c 20 69 74 20  e parameter, it 
c200: 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 73 69 73 74 20  will.** consist 
c210: 6f 66 20 61 20 73 69 6e 67 6c 65 20 22 2d 22 20  of a single "-" 
c220: 63 68 61 72 61 63 74 65 72 20 66 6f 6c 6c 6f 77  character follow
c230: 65 64 20 62 79 20 6e 6f 20 6d 6f 72 65 20 74 68  ed by no more th
c240: 61 6e 0a 2a 2a 20 31 31 20 61 6c 70 68 61 6e 75  an.** 11 alphanu
c250: 6d 65 72 69 63 20 61 6e 64 2f 6f 72 20 22 2d 22  meric and/or "-"
c260: 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 20   characters..** 
c270: 5e 53 51 4c 69 74 65 20 66 75 72 74 68 65 72 20  ^SQLite further 
c280: 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 0a  guarantees that.
c290: 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 77 69  ** the string wi
c2a0: 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 6e 64 20  ll be valid and 
c2b0: 75 6e 63 68 61 6e 67 65 64 20 75 6e 74 69 6c 20  unchanged until 
c2c0: 78 43 6c 6f 73 65 28 29 20 69 73 0a 2a 2a 20 63  xClose() is.** c
c2d0: 61 6c 6c 65 64 2e 20 42 65 63 61 75 73 65 20 6f  alled. Because o
c2e0: 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 73  f the previous s
c2f0: 65 6e 74 65 6e 63 65 2c 0a 2a 2a 20 74 68 65 20  entence,.** the 
c300: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 63  [sqlite3_file] c
c310: 61 6e 20 73 61 66 65 6c 79 20 73 74 6f 72 65 20  an safely store 
c320: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
c330: 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 66 20  .** filename if 
c340: 69 74 20 6e 65 65 64 73 20 74 6f 20 72 65 6d 65  it needs to reme
c350: 6d 62 65 72 20 74 68 65 20 66 69 6c 65 6e 61 6d  mber the filenam
c360: 65 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f  e for some reaso
c370: 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 20 7a 46 69  n..** If the zFi
c380: 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72  lename parameter
c390: 20 74 6f 20 78 4f 70 65 6e 20 69 73 20 61 20 4e   to xOpen is a N
c3a0: 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e  ULL pointer then
c3b0: 20 78 4f 70 65 6e 0a 2a 2a 20 6d 75 73 74 20 69   xOpen.** must i
c3c0: 6e 76 65 6e 74 20 69 74 73 20 6f 77 6e 20 74 65  nvent its own te
c3d0: 6d 70 6f 72 61 72 79 20 6e 61 6d 65 20 66 6f 72  mporary name for
c3e0: 20 74 68 65 20 66 69 6c 65 2e 20 20 5e 57 68 65   the file.  ^Whe
c3f0: 6e 65 76 65 72 20 74 68 65 20 0a 2a 2a 20 78 46  never the .** xF
c400: 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65  ilename paramete
c410: 72 20 69 73 20 4e 55 4c 4c 20 69 74 20 77 69 6c  r is NULL it wil
c420: 6c 20 61 6c 73 6f 20 62 65 20 74 68 65 20 63 61  l also be the ca
c430: 73 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 66  se that the.** f
c440: 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 77  lags parameter w
c450: 69 6c 6c 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c  ill include [SQL
c460: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f  ITE_OPEN_DELETEO
c470: 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a 20 54  NCLOSE]..**.** T
c480: 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e  he flags argumen
c490: 74 20 74 6f 20 78 4f 70 65 6e 28 29 20 69 6e 63  t to xOpen() inc
c4a0: 6c 75 64 65 73 20 61 6c 6c 20 62 69 74 73 20 73  ludes all bits s
c4b0: 65 74 20 69 6e 0a 2a 2a 20 74 68 65 20 66 6c 61  et in.** the fla
c4c0: 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b  gs argument to [
c4d0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
c4e0: 29 5d 2e 20 20 4f 72 20 69 66 20 5b 73 71 6c 69  )].  Or if [sqli
c4f0: 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 6f  te3_open()].** o
c500: 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  r [sqlite3_open1
c510: 36 28 29 5d 20 69 73 20 75 73 65 64 2c 20 74 68  6()] is used, th
c520: 65 6e 20 66 6c 61 67 73 20 69 6e 63 6c 75 64 65  en flags include
c530: 73 20 61 74 20 6c 65 61 73 74 0a 2a 2a 20 5b 53  s at least.** [S
c540: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
c550: 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f  RITE] | [SQLITE_
c560: 4f 50 45 4e 5f 43 52 45 41 54 45 5d 2e 20 0a 2a  OPEN_CREATE]. .*
c570: 2a 20 49 66 20 78 4f 70 65 6e 28 29 20 6f 70 65  * If xOpen() ope
c580: 6e 73 20 61 20 66 69 6c 65 20 72 65 61 64 2d 6f  ns a file read-o
c590: 6e 6c 79 20 74 68 65 6e 20 69 74 20 73 65 74 73  nly then it sets
c5a0: 20 2a 70 4f 75 74 46 6c 61 67 73 20 74 6f 0a 2a   *pOutFlags to.*
c5b0: 2a 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54  * include [SQLIT
c5c0: 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d  E_OPEN_READONLY]
c5d0: 2e 20 20 4f 74 68 65 72 20 62 69 74 73 20 69 6e  .  Other bits in
c5e0: 20 2a 70 4f 75 74 46 6c 61 67 73 20 6d 61 79 20   *pOutFlags may 
c5f0: 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28  be set..**.** ^(
c600: 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 73 6f  SQLite will also
c610: 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20   add one of the 
c620: 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20  following flags 
c630: 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 0a 2a  to the xOpen().*
c640: 2a 20 63 61 6c 6c 2c 20 64 65 70 65 6e 64 69 6e  * call, dependin
c650: 67 20 6f 6e 20 74 68 65 20 6f 62 6a 65 63 74 20  g on the object 
c660: 62 65 69 6e 67 20 6f 70 65 6e 65 64 3a 0a 2a 2a  being opened:.**
c670: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
c680: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d    [SQLITE_OPEN_M
c690: 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20  AIN_DB].** <li> 
c6a0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41   [SQLITE_OPEN_MA
c6b0: 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c  IN_JOURNAL].** <
c6c0: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
c6d0: 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a 2a 20 3c 6c  N_TEMP_DB].** <l
c6e0: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
c6f0: 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a  _TEMP_JOURNAL].*
c700: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
c710: 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44  OPEN_TRANSIENT_D
c720: 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  B].** <li>  [SQL
c730: 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52  ITE_OPEN_SUBJOUR
c740: 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  NAL].** <li>  [S
c750: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45  QLITE_OPEN_MASTE
c760: 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c  R_JOURNAL].** <l
c770: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
c780: 5f 57 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e  _WAL].** </ul>)^
c790: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 6c 65 20  .**.** The file 
c7a0: 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  I/O implementati
c7b0: 6f 6e 20 63 61 6e 20 75 73 65 20 74 68 65 20 6f  on can use the o
c7c0: 62 6a 65 63 74 20 74 79 70 65 20 66 6c 61 67 73  bject type flags
c7d0: 20 74 6f 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68   to.** change th
c7e0: 65 20 77 61 79 20 69 74 20 64 65 61 6c 73 20 77  e way it deals w
c7f0: 69 74 68 20 66 69 6c 65 73 2e 20 20 46 6f 72 20  ith files.  For 
c800: 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c  example, an appl
c810: 69 63 61 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20  ication.** that 
c820: 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 61 62  does not care ab
c830: 6f 75 74 20 63 72 61 73 68 20 72 65 63 6f 76 65  out crash recove
c840: 72 79 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 6d  ry or rollback m
c850: 69 67 68 74 20 6d 61 6b 65 0a 2a 2a 20 74 68 65  ight make.** the
c860: 20 6f 70 65 6e 20 6f 66 20 61 20 6a 6f 75 72 6e   open of a journ
c870: 61 6c 20 66 69 6c 65 20 61 20 6e 6f 2d 6f 70 2e  al file a no-op.
c880: 20 20 57 72 69 74 65 73 20 74 6f 20 74 68 69 73    Writes to this
c890: 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 0a 2a   journal would.*
c8a0: 2a 20 61 6c 73 6f 20 62 65 20 6e 6f 2d 6f 70 73  * also be no-ops
c8b0: 2c 20 61 6e 64 20 61 6e 79 20 61 74 74 65 6d 70  , and any attemp
c8c0: 74 20 74 6f 20 72 65 61 64 20 74 68 65 20 6a 6f  t to read the jo
c8d0: 75 72 6e 61 6c 20 77 6f 75 6c 64 20 72 65 74 75  urnal would retu
c8e0: 72 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 45  rn.** SQLITE_IOE
c8f0: 52 52 2e 20 20 4f 72 20 74 68 65 20 69 6d 70 6c  RR.  Or the impl
c900: 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 67 68 74  ementation might
c910: 20 72 65 63 6f 67 6e 69 7a 65 20 74 68 61 74 20   recognize that 
c920: 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69  a database.** fi
c930: 6c 65 20 77 69 6c 6c 20 62 65 20 64 6f 69 6e 67  le will be doing
c940: 20 70 61 67 65 2d 61 6c 69 67 6e 65 64 20 73 65   page-aligned se
c950: 63 74 6f 72 20 72 65 61 64 73 20 61 6e 64 20 77  ctor reads and w
c960: 72 69 74 65 73 20 69 6e 20 61 20 72 61 6e 64 6f  rites in a rando
c970: 6d 0a 2a 2a 20 6f 72 64 65 72 20 61 6e 64 20 73  m.** order and s
c980: 65 74 20 75 70 20 69 74 73 20 49 2f 4f 20 73 75  et up its I/O su
c990: 62 73 79 73 74 65 6d 20 61 63 63 6f 72 64 69 6e  bsystem accordin
c9a0: 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  gly..**.** SQLit
c9b0: 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 61 64 64  e might also add
c9c0: 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c   one of the foll
c9d0: 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74  owing flags to t
c9e0: 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 3a  he xOpen method:
c9f0: 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
ca00: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  li> [SQLITE_OPEN
ca10: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a  _DELETEONCLOSE].
ca20: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
ca30: 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 0a  OPEN_EXCLUSIVE].
ca40: 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54  ** </ul>.**.** T
ca50: 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
ca60: 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 20 66  DELETEONCLOSE] f
ca70: 6c 61 67 20 6d 65 61 6e 73 20 74 68 65 20 66 69  lag means the fi
ca80: 6c 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20  le should be.** 
ca90: 64 65 6c 65 74 65 64 20 77 68 65 6e 20 69 74 20  deleted when it 
caa0: 69 73 20 63 6c 6f 73 65 64 2e 20 20 5e 54 68 65  is closed.  ^The
cab0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45   [SQLITE_OPEN_DE
cac0: 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20  LETEONCLOSE].** 
cad0: 77 69 6c 6c 20 62 65 20 73 65 74 20 66 6f 72 20  will be set for 
cae0: 54 45 4d 50 20 64 61 74 61 62 61 73 65 73 20 61  TEMP databases a
caf0: 6e 64 20 74 68 65 69 72 20 6a 6f 75 72 6e 61 6c  nd their journal
cb00: 73 2c 20 74 72 61 6e 73 69 65 6e 74 0a 2a 2a 20  s, transient.** 
cb10: 64 61 74 61 62 61 73 65 73 2c 20 61 6e 64 20 73  databases, and s
cb20: 75 62 6a 6f 75 72 6e 61 6c 73 2e 0a 2a 2a 0a 2a  ubjournals..**.*
cb30: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f  * ^The [SQLITE_O
cb40: 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 20 66  PEN_EXCLUSIVE] f
cb50: 6c 61 67 20 69 73 20 61 6c 77 61 79 73 20 75 73  lag is always us
cb60: 65 64 20 69 6e 20 63 6f 6e 6a 75 6e 63 74 69 6f  ed in conjunctio
cb70: 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 53  n.** with the [S
cb80: 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
cb90: 45 5d 20 66 6c 61 67 2c 20 77 68 69 63 68 20 61  E] flag, which a
cba0: 72 65 20 62 6f 74 68 20 64 69 72 65 63 74 6c 79  re both directly
cbb0: 0a 2a 2a 20 61 6e 61 6c 6f 67 6f 75 73 20 74 6f  .** analogous to
cbc0: 20 74 68 65 20 4f 5f 45 58 43 4c 20 61 6e 64 20   the O_EXCL and 
cbd0: 4f 5f 43 52 45 41 54 20 66 6c 61 67 73 20 6f 66  O_CREAT flags of
cbe0: 20 74 68 65 20 50 4f 53 49 58 20 6f 70 65 6e 28   the POSIX open(
cbf0: 29 0a 2a 2a 20 41 50 49 2e 20 20 54 68 65 20 53  ).** API.  The S
cc00: 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55  QLITE_OPEN_EXCLU
cc10: 53 49 56 45 20 66 6c 61 67 2c 20 77 68 65 6e 20  SIVE flag, when 
cc20: 70 61 69 72 65 64 20 77 69 74 68 20 74 68 65 20  paired with the 
cc30: 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  .** SQLITE_OPEN_
cc40: 43 52 45 41 54 45 2c 20 69 73 20 75 73 65 64 20  CREATE, is used 
cc50: 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74  to indicate that
cc60: 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 61 6c 77   file should alw
cc70: 61 79 73 0a 2a 2a 20 62 65 20 63 72 65 61 74 65  ays.** be create
cc80: 64 2c 20 61 6e 64 20 74 68 61 74 20 69 74 20 69  d, and that it i
cc90: 73 20 61 6e 20 65 72 72 6f 72 20 69 66 20 69 74  s an error if it
cca0: 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 73 2e   already exists.
ccb0: 0a 2a 2a 20 49 74 20 69 73 20 3c 69 3e 6e 6f 74  .** It is <i>not
ccc0: 3c 2f 69 3e 20 75 73 65 64 20 74 6f 20 69 6e 64  </i> used to ind
ccd0: 69 63 61 74 65 20 74 68 65 20 66 69 6c 65 20 73  icate the file s
cce0: 68 6f 75 6c 64 20 62 65 20 6f 70 65 6e 65 64 20  hould be opened 
ccf0: 0a 2a 2a 20 66 6f 72 20 65 78 63 6c 75 73 69 76  .** for exclusiv
cd00: 65 20 61 63 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20  e access..**.** 
cd10: 5e 41 74 20 6c 65 61 73 74 20 73 7a 4f 73 46 69  ^At least szOsFi
cd20: 6c 65 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f  le bytes of memo
cd30: 72 79 20 61 72 65 20 61 6c 6c 6f 63 61 74 65 64  ry are allocated
cd40: 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 74 6f   by SQLite.** to
cd50: 20 68 6f 6c 64 20 74 68 65 20 20 5b 73 71 6c 69   hold the  [sqli
cd60: 74 65 33 5f 66 69 6c 65 5d 20 73 74 72 75 63 74  te3_file] struct
cd70: 75 72 65 20 70 61 73 73 65 64 20 61 73 20 74 68  ure passed as th
cd80: 65 20 74 68 69 72 64 0a 2a 2a 20 61 72 67 75 6d  e third.** argum
cd90: 65 6e 74 20 74 6f 20 78 4f 70 65 6e 2e 20 20 54  ent to xOpen.  T
cda0: 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20  he xOpen method 
cdb0: 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 74 6f  does not have to
cdc0: 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 74 68 65  .** allocate the
cdd0: 20 73 74 72 75 63 74 75 72 65 3b 20 69 74 20 73   structure; it s
cde0: 68 6f 75 6c 64 20 6a 75 73 74 20 66 69 6c 6c 20  hould just fill 
cdf0: 69 74 20 69 6e 2e 20 20 4e 6f 74 65 20 74 68 61  it in.  Note tha
ce00: 74 0a 2a 2a 20 74 68 65 20 78 4f 70 65 6e 20 6d  t.** the xOpen m
ce10: 65 74 68 6f 64 20 6d 75 73 74 20 73 65 74 20 74  ethod must set t
ce20: 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e  he sqlite3_file.
ce30: 70 4d 65 74 68 6f 64 73 20 74 6f 20 65 69 74 68  pMethods to eith
ce40: 65 72 0a 2a 2a 20 61 20 76 61 6c 69 64 20 5b 73  er.** a valid [s
ce50: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
ce60: 73 5d 20 6f 62 6a 65 63 74 20 6f 72 20 74 6f 20  s] object or to 
ce70: 4e 55 4c 4c 2e 20 20 78 4f 70 65 6e 20 6d 75 73  NULL.  xOpen mus
ce80: 74 20 64 6f 0a 2a 2a 20 74 68 69 73 20 65 76 65  t do.** this eve
ce90: 6e 20 69 66 20 74 68 65 20 6f 70 65 6e 20 66 61  n if the open fa
cea0: 69 6c 73 2e 20 20 53 51 4c 69 74 65 20 65 78 70  ils.  SQLite exp
ceb0: 65 63 74 73 20 74 68 61 74 20 74 68 65 20 73 71  ects that the sq
cec0: 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68  lite3_file.pMeth
ced0: 6f 64 73 0a 2a 2a 20 65 6c 65 6d 65 6e 74 20 77  ods.** element w
cee0: 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 66 74  ill be valid aft
cef0: 65 72 20 78 4f 70 65 6e 20 72 65 74 75 72 6e 73  er xOpen returns
cf00: 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74   regardless of t
cf10: 68 65 20 73 75 63 63 65 73 73 0a 2a 2a 20 6f 72  he success.** or
cf20: 20 66 61 69 6c 75 72 65 20 6f 66 20 74 68 65 20   failure of the 
cf30: 78 4f 70 65 6e 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a  xOpen call..**.*
cf40: 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  * [[sqlite3_vfs.
cf50: 78 41 63 63 65 73 73 5d 5d 0a 2a 2a 20 5e 54 68  xAccess]].** ^Th
cf60: 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74  e flags argument
cf70: 20 74 6f 20 78 41 63 63 65 73 73 28 29 20 6d 61   to xAccess() ma
cf80: 79 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 43 43  y be [SQLITE_ACC
cf90: 45 53 53 5f 45 58 49 53 54 53 5d 0a 2a 2a 20 74  ESS_EXISTS].** t
cfa0: 6f 20 74 65 73 74 20 66 6f 72 20 74 68 65 20 65  o test for the e
cfb0: 78 69 73 74 65 6e 63 65 20 6f 66 20 61 20 66 69  xistence of a fi
cfc0: 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41  le, or [SQLITE_A
cfd0: 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 5d  CCESS_READWRITE]
cfe0: 20 74 6f 0a 2a 2a 20 74 65 73 74 20 77 68 65 74   to.** test whet
cff0: 68 65 72 20 61 20 66 69 6c 65 20 69 73 20 72 65  her a file is re
d000: 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61  adable and writa
d010: 62 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ble, or [SQLITE_
d020: 41 43 43 45 53 53 5f 52 45 41 44 5d 0a 2a 2a 20  ACCESS_READ].** 
d030: 74 6f 20 74 65 73 74 20 77 68 65 74 68 65 72 20  to test whether 
d040: 61 20 66 69 6c 65 20 69 73 20 61 74 20 6c 65 61  a file is at lea
d050: 73 74 20 72 65 61 64 61 62 6c 65 2e 20 20 20 54  st readable.   T
d060: 68 65 20 66 69 6c 65 20 63 61 6e 20 62 65 20 61  he file can be a
d070: 0a 2a 2a 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a  .** directory..*
d080: 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c  *.** ^SQLite wil
d090: 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f 63 61 74  l always allocat
d0a0: 65 20 61 74 20 6c 65 61 73 74 20 6d 78 50 61 74  e at least mxPat
d0b0: 68 6e 61 6d 65 2b 31 20 62 79 74 65 73 20 66 6f  hname+1 bytes fo
d0c0: 72 20 74 68 65 0a 2a 2a 20 6f 75 74 70 75 74 20  r the.** output 
d0d0: 62 75 66 66 65 72 20 78 46 75 6c 6c 50 61 74 68  buffer xFullPath
d0e0: 6e 61 6d 65 2e 20 20 54 68 65 20 65 78 61 63 74  name.  The exact
d0f0: 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6f 75 74   size of the out
d100: 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69 73  put buffer.** is
d110: 20 61 6c 73 6f 20 70 61 73 73 65 64 20 61 73 20   also passed as 
d120: 61 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62  a parameter to b
d130: 6f 74 68 20 20 6d 65 74 68 6f 64 73 2e 20 49 66  oth  methods. If
d140: 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 66 66   the output buff
d150: 65 72 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c 61 72  er.** is not lar
d160: 67 65 20 65 6e 6f 75 67 68 2c 20 5b 53 51 4c 49  ge enough, [SQLI
d170: 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 73 68 6f  TE_CANTOPEN] sho
d180: 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e  uld be returned.
d190: 20 53 69 6e 63 65 20 74 68 69 73 20 69 73 0a 2a   Since this is.*
d1a0: 2a 20 68 61 6e 64 6c 65 64 20 61 73 20 61 20 66  * handled as a f
d1b0: 61 74 61 6c 20 65 72 72 6f 72 20 62 79 20 53 51  atal error by SQ
d1c0: 4c 69 74 65 2c 20 76 66 73 20 69 6d 70 6c 65 6d  Lite, vfs implem
d1d0: 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64  entations should
d1e0: 20 65 6e 64 65 61 76 6f 72 0a 2a 2a 20 74 6f 20   endeavor.** to 
d1f0: 70 72 65 76 65 6e 74 20 74 68 69 73 20 62 79 20  prevent this by 
d200: 73 65 74 74 69 6e 67 20 6d 78 50 61 74 68 6e 61  setting mxPathna
d210: 6d 65 20 74 6f 20 61 20 73 75 66 66 69 63 69 65  me to a sufficie
d220: 6e 74 6c 79 20 6c 61 72 67 65 20 76 61 6c 75 65  ntly large value
d230: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 61 6e  ..**.** The xRan
d240: 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53 6c 65 65  domness(), xSlee
d250: 70 28 29 2c 20 78 43 75 72 72 65 6e 74 54 69 6d  p(), xCurrentTim
d260: 65 28 29 2c 20 61 6e 64 20 78 43 75 72 72 65 6e  e(), and xCurren
d270: 74 54 69 6d 65 49 6e 74 36 34 28 29 0a 2a 2a 20  tTimeInt64().** 
d280: 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 6e  interfaces are n
d290: 6f 74 20 73 74 72 69 63 74 6c 79 20 61 20 70 61  ot strictly a pa
d2a0: 72 74 20 6f 66 20 74 68 65 20 66 69 6c 65 73 79  rt of the filesy
d2b0: 73 74 65 6d 2c 20 62 75 74 20 74 68 65 79 20 61  stem, but they a
d2c0: 72 65 0a 2a 2a 20 69 6e 63 6c 75 64 65 64 20 69  re.** included i
d2d0: 6e 20 74 68 65 20 56 46 53 20 73 74 72 75 63 74  n the VFS struct
d2e0: 75 72 65 20 66 6f 72 20 63 6f 6d 70 6c 65 74 65  ure for complete
d2f0: 6e 65 73 73 2e 0a 2a 2a 20 54 68 65 20 78 52 61  ness..** The xRa
d300: 6e 64 6f 6d 6e 65 73 73 28 29 20 66 75 6e 63 74  ndomness() funct
d310: 69 6f 6e 20 61 74 74 65 6d 70 74 73 20 74 6f 20  ion attempts to 
d320: 72 65 74 75 72 6e 20 6e 42 79 74 65 73 20 62 79  return nBytes by
d330: 74 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64 2d 71  tes.** of good-q
d340: 75 61 6c 69 74 79 20 72 61 6e 64 6f 6d 6e 65 73  uality randomnes
d350: 73 20 69 6e 74 6f 20 7a 4f 75 74 2e 20 20 54 68  s into zOut.  Th
d360: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 69  e return value i
d370: 73 0a 2a 2a 20 74 68 65 20 61 63 74 75 61 6c 20  s.** the actual 
d380: 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
d390: 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62  of randomness ob
d3a0: 74 61 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 78  tained..** The x
d3b0: 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 20 63  Sleep() method c
d3c0: 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c 69 6e  auses the callin
d3d0: 67 20 74 68 72 65 61 64 20 74 6f 20 73 6c 65 65  g thread to slee
d3e0: 70 20 66 6f 72 20 61 74 0a 2a 2a 20 6c 65 61 73  p for at.** leas
d3f0: 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  t the number of 
d400: 6d 69 63 72 6f 73 65 63 6f 6e 64 73 20 67 69 76  microseconds giv
d410: 65 6e 2e 20 20 5e 54 68 65 20 78 43 75 72 72 65  en.  ^The xCurre
d420: 6e 74 54 69 6d 65 28 29 0a 2a 2a 20 6d 65 74 68  ntTime().** meth
d430: 6f 64 20 72 65 74 75 72 6e 73 20 61 20 4a 75 6c  od returns a Jul
d440: 69 61 6e 20 44 61 79 20 4e 75 6d 62 65 72 20 66  ian Day Number f
d450: 6f 72 20 74 68 65 20 63 75 72 72 65 6e 74 20 64  or the current d
d460: 61 74 65 20 61 6e 64 20 74 69 6d 65 20 61 73 0a  ate and time as.
d470: 2a 2a 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f  ** a floating po
d480: 69 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a 20 5e 54  int value..** ^T
d490: 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49  he xCurrentTimeI
d4a0: 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20 72 65  nt64() method re
d4b0: 74 75 72 6e 73 2c 20 61 73 20 61 6e 20 69 6e 74  turns, as an int
d4c0: 65 67 65 72 2c 20 74 68 65 20 4a 75 6c 69 61 6e  eger, the Julian
d4d0: 0a 2a 2a 20 44 61 79 20 4e 75 6d 62 65 72 20 6d  .** Day Number m
d4e0: 75 6c 74 69 70 6c 69 65 64 20 62 79 20 38 36 34  ultiplied by 864
d4f0: 30 30 30 30 30 20 28 74 68 65 20 6e 75 6d 62 65  00000 (the numbe
d500: 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  r of millisecond
d510: 73 20 69 6e 20 0a 2a 2a 20 61 20 32 34 2d 68 6f  s in .** a 24-ho
d520: 75 72 20 64 61 79 29 2e 20 20 0a 2a 2a 20 5e 53  ur day).  .** ^S
d530: 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 74  QLite will use t
d540: 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49  he xCurrentTimeI
d550: 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20 74 6f  nt64() method to
d560: 20 67 65 74 20 74 68 65 20 63 75 72 72 65 6e 74   get the current
d570: 0a 2a 2a 20 64 61 74 65 20 61 6e 64 20 74 69 6d  .** date and tim
d580: 65 20 69 66 20 74 68 61 74 20 6d 65 74 68 6f 64  e if that method
d590: 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 28 69   is available (i
d5a0: 66 20 69 56 65 72 73 69 6f 6e 20 69 73 20 32 20  f iVersion is 2 
d5b0: 6f 72 20 0a 2a 2a 20 67 72 65 61 74 65 72 20 61  or .** greater a
d5c0: 6e 64 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  nd the function 
d5d0: 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e  pointer is not N
d5e0: 55 4c 4c 29 20 61 6e 64 20 77 69 6c 6c 20 66 61  ULL) and will fa
d5f0: 6c 6c 20 62 61 63 6b 0a 2a 2a 20 74 6f 20 78 43  ll back.** to xC
d600: 75 72 72 65 6e 74 54 69 6d 65 28 29 20 69 66 20  urrentTime() if 
d610: 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36  xCurrentTimeInt6
d620: 34 28 29 20 69 73 20 75 6e 61 76 61 69 6c 61 62  4() is unavailab
d630: 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78  le..**.** ^The x
d640: 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 2c  SetSystemCall(),
d650: 20 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c 28   xGetSystemCall(
d660: 29 2c 20 61 6e 64 20 78 4e 65 73 74 53 79 73 74  ), and xNestSyst
d670: 65 6d 43 61 6c 6c 28 29 20 69 6e 74 65 72 66 61  emCall() interfa
d680: 63 65 73 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 75  ces.** are not u
d690: 73 65 64 20 62 79 20 74 68 65 20 53 51 4c 69 74  sed by the SQLit
d6a0: 65 20 63 6f 72 65 2e 20 20 54 68 65 73 65 20 6f  e core.  These o
d6b0: 70 74 69 6f 6e 61 6c 20 69 6e 74 65 72 66 61 63  ptional interfac
d6c0: 65 73 20 61 72 65 20 70 72 6f 76 69 64 65 64 0a  es are provided.
d6d0: 2a 2a 20 62 79 20 73 6f 6d 65 20 56 46 53 65 73  ** by some VFSes
d6e0: 20 74 6f 20 66 61 63 69 6c 69 74 61 74 65 20 74   to facilitate t
d6f0: 65 73 74 69 6e 67 20 6f 66 20 74 68 65 20 56 46  esting of the VF
d700: 53 20 63 6f 64 65 2e 20 42 79 20 6f 76 65 72 72  S code. By overr
d710: 69 64 69 6e 67 20 0a 2a 2a 20 73 79 73 74 65 6d  iding .** system
d720: 20 63 61 6c 6c 73 20 77 69 74 68 20 66 75 6e 63   calls with func
d730: 74 69 6f 6e 73 20 75 6e 64 65 72 20 69 74 73 20  tions under its 
d740: 63 6f 6e 74 72 6f 6c 2c 20 61 20 74 65 73 74 20  control, a test 
d750: 70 72 6f 67 72 61 6d 20 63 61 6e 0a 2a 2a 20 73  program can.** s
d760: 69 6d 75 6c 61 74 65 20 66 61 75 6c 74 73 20 61  imulate faults a
d770: 6e 64 20 65 72 72 6f 72 20 63 6f 6e 64 69 74 69  nd error conditi
d780: 6f 6e 73 20 74 68 61 74 20 77 6f 75 6c 64 20 6f  ons that would o
d790: 74 68 65 72 77 69 73 65 20 62 65 20 64 69 66 66  therwise be diff
d7a0: 69 63 75 6c 74 0a 2a 2a 20 6f 72 20 69 6d 70 6f  icult.** or impo
d7b0: 73 73 69 62 6c 65 20 74 6f 20 69 6e 64 75 63 65  ssible to induce
d7c0: 2e 20 20 54 68 65 20 73 65 74 20 6f 66 20 73 79  .  The set of sy
d7d0: 73 74 65 6d 20 63 61 6c 6c 73 20 74 68 61 74 20  stem calls that 
d7e0: 63 61 6e 20 62 65 20 6f 76 65 72 72 69 64 64 65  can be overridde
d7f0: 6e 0a 2a 2a 20 76 61 72 69 65 73 20 66 72 6f 6d  n.** varies from
d800: 20 6f 6e 65 20 56 46 53 20 74 6f 20 61 6e 6f 74   one VFS to anot
d810: 68 65 72 2c 20 61 6e 64 20 66 72 6f 6d 20 6f 6e  her, and from on
d820: 65 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65  e version of the
d830: 20 73 61 6d 65 20 56 46 53 20 74 6f 20 74 68 65   same VFS to the
d840: 0a 2a 2a 20 6e 65 78 74 2e 20 20 41 70 70 6c 69  .** next.  Appli
d850: 63 61 74 69 6f 6e 73 20 74 68 61 74 20 75 73 65  cations that use
d860: 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65   these interface
d870: 73 20 6d 75 73 74 20 62 65 20 70 72 65 70 61 72  s must be prepar
d880: 65 64 20 66 6f 72 20 61 6e 79 0a 2a 2a 20 6f 72  ed for any.** or
d890: 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 69 6e   all of these in
d8a0: 74 65 72 66 61 63 65 73 20 74 6f 20 62 65 20 4e  terfaces to be N
d8b0: 55 4c 4c 20 6f 72 20 66 6f 72 20 74 68 65 69 72  ULL or for their
d8c0: 20 62 65 68 61 76 69 6f 72 20 74 6f 20 63 68 61   behavior to cha
d8d0: 6e 67 65 0a 2a 2a 20 66 72 6f 6d 20 6f 6e 65 20  nge.** from one 
d8e0: 72 65 6c 65 61 73 65 20 74 6f 20 74 68 65 20 6e  release to the n
d8f0: 65 78 74 2e 20 20 41 70 70 6c 69 63 61 74 69 6f  ext.  Applicatio
d900: 6e 73 20 6d 75 73 74 20 6e 6f 74 20 61 74 74 65  ns must not atte
d910: 6d 70 74 20 74 6f 20 61 63 63 65 73 73 0a 2a 2a  mpt to access.**
d920: 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 6d 65   any of these me
d930: 74 68 6f 64 73 20 69 66 20 74 68 65 20 69 56 65  thods if the iVe
d940: 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 56 46 53  rsion of the VFS
d950: 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 33 2e   is less than 3.
d960: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
d970: 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20 73  ct sqlite3_vfs s
d980: 71 6c 69 74 65 33 5f 76 66 73 3b 0a 74 79 70 65  qlite3_vfs;.type
d990: 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 74  def void (*sqlit
d9a0: 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 28  e3_syscall_ptr)(
d9b0: 76 6f 69 64 29 3b 0a 73 74 72 75 63 74 20 73 71  void);.struct sq
d9c0: 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20 20 69 6e  lite3_vfs {.  in
d9d0: 74 20 69 56 65 72 73 69 6f 6e 3b 20 20 20 20 20  t iVersion;     
d9e0: 20 20 20 20 20 20 20 2f 2a 20 53 74 72 75 63 74         /* Struct
d9f0: 75 72 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62  ure version numb
da00: 65 72 20 28 63 75 72 72 65 6e 74 6c 79 20 33 29  er (currently 3)
da10: 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73 46 69   */.  int szOsFi
da20: 6c 65 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f  le;            /
da30: 2a 20 53 69 7a 65 20 6f 66 20 73 75 62 63 6c 61  * Size of subcla
da40: 73 73 65 64 20 73 71 6c 69 74 65 33 5f 66 69 6c  ssed sqlite3_fil
da50: 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50 61 74  e */.  int mxPat
da60: 68 6e 61 6d 65 3b 20 20 20 20 20 20 20 20 20 20  hname;          
da70: 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c 65 20  /* Maximum file 
da80: 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74 68 20  pathname length 
da90: 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76 66 73  */.  sqlite3_vfs
daa0: 20 2a 70 4e 65 78 74 3b 20 20 20 20 20 20 2f 2a   *pNext;      /*
dab0: 20 4e 65 78 74 20 72 65 67 69 73 74 65 72 65 64   Next registered
dac0: 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73 74 20   VFS */.  const 
dad0: 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20 20 20  char *zName;    
dae0: 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68     /* Name of th
daf0: 69 73 20 76 69 72 74 75 61 6c 20 66 69 6c 65 20  is virtual file 
db00: 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f 69 64  system */.  void
db10: 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20 20   *pAppData;     
db20: 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65 72 20       /* Pointer 
db30: 74 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73  to application-s
db40: 70 65 63 69 66 69 63 20 64 61 74 61 20 2a 2f 0a  pecific data */.
db50: 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73    int (*xOpen)(s
db60: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
db70: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
db80: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 0a 20  sqlite3_file*,. 
db90: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 69 6e                in
dba0: 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 4f  t flags, int *pO
dbb0: 75 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20  utFlags);.  int 
dbc0: 28 2a 78 44 65 6c 65 74 65 29 28 73 71 6c 69 74  (*xDelete)(sqlit
dbd0: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
dbe0: 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20  har *zName, int 
dbf0: 73 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e 74 20  syncDir);.  int 
dc00: 28 2a 78 41 63 63 65 73 73 29 28 73 71 6c 69 74  (*xAccess)(sqlit
dc10: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
dc20: 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20  har *zName, int 
dc30: 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 52 65 73  flags, int *pRes
dc40: 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46  Out);.  int (*xF
dc50: 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73 71 6c  ullPathname)(sql
dc60: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
dc70: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e   char *zName, in
dc80: 74 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a 7a 4f  t nOut, char *zO
dc90: 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28 2a 78  ut);.  void *(*x
dca0: 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f  DlOpen)(sqlite3_
dcb0: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
dcc0: 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a 20 20   *zFilename);.  
dcd0: 76 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f 72 29  void (*xDlError)
dce0: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69  (sqlite3_vfs*, i
dcf0: 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a  nt nByte, char *
dd00: 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f 69 64  zErrMsg);.  void
dd10: 20 28 2a 28 2a 78 44 6c 53 79 6d 29 28 73 71 6c   (*(*xDlSym)(sql
dd20: 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69 64 2a 2c  ite3_vfs*,void*,
dd30: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 79   const char *zSy
dd40: 6d 62 6f 6c 29 29 28 76 6f 69 64 29 3b 0a 20 20  mbol))(void);.  
dd50: 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73 65 29  void (*xDlClose)
dd60: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 76  (sqlite3_vfs*, v
dd70: 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  oid*);.  int (*x
dd80: 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71 6c 69  Randomness)(sqli
dd90: 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42  te3_vfs*, int nB
dda0: 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29  yte, char *zOut)
ddb0: 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65 65 70  ;.  int (*xSleep
ddc0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
ddd0: 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73  int microseconds
dde0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 72  );.  int (*xCurr
ddf0: 65 6e 74 54 69 6d 65 29 28 73 71 6c 69 74 65 33  entTime)(sqlite3
de00: 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a 29 3b  _vfs*, double*);
de10: 0a 20 20 69 6e 74 20 28 2a 78 47 65 74 4c 61 73  .  int (*xGetLas
de20: 74 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f  tError)(sqlite3_
de30: 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68 61 72 20  vfs*, int, char 
de40: 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68  *);.  /*.  ** Th
de50: 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20  e methods above 
de60: 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 20 31  are in version 1
de70: 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76   of the sqlite_v
de80: 66 73 20 6f 62 6a 65 63 74 0a 20 20 2a 2a 20 64  fs object.  ** d
de90: 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 6f 73  efinition.  Thos
dea0: 65 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 61 72  e that follow ar
deb0: 65 20 61 64 64 65 64 20 69 6e 20 76 65 72 73 69  e added in versi
dec0: 6f 6e 20 32 20 6f 72 20 6c 61 74 65 72 0a 20 20  on 2 or later.  
ded0: 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 72  */.  int (*xCurr
dee0: 65 6e 74 54 69 6d 65 49 6e 74 36 34 29 28 73 71  entTimeInt64)(sq
def0: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 73 71 6c 69  lite3_vfs*, sqli
df00: 74 65 33 5f 69 6e 74 36 34 2a 29 3b 0a 20 20 2f  te3_int64*);.  /
df10: 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f  *.  ** The metho
df20: 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20  ds above are in 
df30: 76 65 72 73 69 6f 6e 73 20 31 20 61 6e 64 20 32  versions 1 and 2
df40: 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76   of the sqlite_v
df50: 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a 20  fs object..  ** 
df60: 54 68 6f 73 65 20 62 65 6c 6f 77 20 61 72 65 20  Those below are 
df70: 66 6f 72 20 76 65 72 73 69 6f 6e 20 33 20 61 6e  for version 3 an
df80: 64 20 67 72 65 61 74 65 72 2e 0a 20 20 2a 2f 0a  d greater..  */.
df90: 20 20 69 6e 74 20 28 2a 78 53 65 74 53 79 73 74    int (*xSetSyst
dfa0: 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f  emCall)(sqlite3_
dfb0: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
dfc0: 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33   *zName, sqlite3
dfd0: 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 3b 0a 20  _syscall_ptr);. 
dfe0: 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c   sqlite3_syscall
dff0: 5f 70 74 72 20 28 2a 78 47 65 74 53 79 73 74 65  _ptr (*xGetSyste
e000: 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76  mCall)(sqlite3_v
e010: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
e020: 2a 7a 4e 61 6d 65 29 3b 0a 20 20 63 6f 6e 73 74  *zName);.  const
e030: 20 63 68 61 72 20 2a 28 2a 78 4e 65 78 74 53 79   char *(*xNextSy
e040: 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65  stemCall)(sqlite
e050: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
e060: 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 2f 2a  ar *zName);.  /*
e070: 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64  .  ** The method
e080: 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76  s above are in v
e090: 65 72 73 69 6f 6e 73 20 31 20 74 68 72 6f 75 67  ersions 1 throug
e0a0: 68 20 33 20 6f 66 20 74 68 65 20 73 71 6c 69 74  h 3 of the sqlit
e0b0: 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20  e_vfs object..  
e0c0: 2a 2a 20 4e 65 77 20 66 69 65 6c 64 73 20 6d 61  ** New fields ma
e0d0: 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 69 6e  y be appended in
e0e0: 20 66 69 67 75 72 65 20 76 65 72 73 69 6f 6e 73   figure versions
e0f0: 2e 20 20 54 68 65 20 69 56 65 72 73 69 6f 6e 0a  .  The iVersion.
e100: 20 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c 6c 20    ** value will 
e110: 69 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e 65 76  increment whenev
e120: 65 72 20 74 68 69 73 20 68 61 70 70 65 6e 73 2e  er this happens.
e130: 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a   .  */.};../*.**
e140: 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73   CAPI3REF: Flags
e150: 20 66 6f 72 20 74 68 65 20 78 41 63 63 65 73 73   for the xAccess
e160: 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a   VFS method.**.*
e170: 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20  * These integer 
e180: 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20 62 65  constants can be
e190: 20 75 73 65 64 20 61 73 20 74 68 65 20 74 68 69   used as the thi
e1a0: 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  rd parameter to.
e1b0: 2a 2a 20 74 68 65 20 78 41 63 63 65 73 73 20 6d  ** the xAccess m
e1c0: 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73 71 6c  ethod of an [sql
e1d0: 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
e1e0: 2e 20 20 54 68 65 79 20 64 65 74 65 72 6d 69 6e  .  They determin
e1f0: 65 0a 2a 2a 20 77 68 61 74 20 6b 69 6e 64 20 6f  e.** what kind o
e200: 66 20 70 65 72 6d 69 73 73 69 6f 6e 73 20 74 68  f permissions th
e210: 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64  e xAccess method
e220: 20 69 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f 72 2e   is looking for.
e230: 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f  .** With SQLITE_
e240: 41 43 43 45 53 53 5f 45 58 49 53 54 53 2c 20 74  ACCESS_EXISTS, t
e250: 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f  he xAccess metho
e260: 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68 65 63  d.** simply chec
e270: 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20 66  ks whether the f
e280: 69 6c 65 20 65 78 69 73 74 73 2e 0a 2a 2a 20 57  ile exists..** W
e290: 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53  ith SQLITE_ACCES
e2a0: 53 5f 52 45 41 44 57 52 49 54 45 2c 20 74 68 65  S_READWRITE, the
e2b0: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a   xAccess method.
e2c0: 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 65  ** checks whethe
e2d0: 72 20 74 68 65 20 6e 61 6d 65 64 20 64 69 72 65  r the named dire
e2e0: 63 74 6f 72 79 20 69 73 20 62 6f 74 68 20 72 65  ctory is both re
e2f0: 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61  adable and writa
e300: 62 6c 65 0a 2a 2a 20 28 69 6e 20 6f 74 68 65 72  ble.** (in other
e310: 20 77 6f 72 64 73 2c 20 69 66 20 66 69 6c 65 73   words, if files
e320: 20 63 61 6e 20 62 65 20 61 64 64 65 64 2c 20 72   can be added, r
e330: 65 6d 6f 76 65 64 2c 20 61 6e 64 20 72 65 6e 61  emoved, and rena
e340: 6d 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68  med within.** th
e350: 65 20 64 69 72 65 63 74 6f 72 79 29 2e 0a 2a 2a  e directory)..**
e360: 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43 45   The SQLITE_ACCE
e370: 53 53 5f 52 45 41 44 57 52 49 54 45 20 63 6f 6e  SS_READWRITE con
e380: 73 74 61 6e 74 20 69 73 20 63 75 72 72 65 6e 74  stant is current
e390: 6c 79 20 75 73 65 64 20 6f 6e 6c 79 20 62 79 20  ly used only by 
e3a0: 74 68 65 0a 2a 2a 20 5b 74 65 6d 70 5f 73 74 6f  the.** [temp_sto
e3b0: 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61  re_directory pra
e3c0: 67 6d 61 5d 2c 20 74 68 6f 75 67 68 20 74 68 69  gma], though thi
e3d0: 73 20 63 6f 75 6c 64 20 63 68 61 6e 67 65 20 69  s could change i
e3e0: 6e 20 61 20 66 75 74 75 72 65 0a 2a 2a 20 72 65  n a future.** re
e3f0: 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e  lease of SQLite.
e400: 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f  .** With SQLITE_
e410: 41 43 43 45 53 53 5f 52 45 41 44 2c 20 74 68 65  ACCESS_READ, the
e420: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a   xAccess method.
e430: 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 65  ** checks whethe
e440: 72 20 74 68 65 20 66 69 6c 65 20 69 73 20 72 65  r the file is re
e450: 61 64 61 62 6c 65 2e 20 20 54 68 65 20 53 51 4c  adable.  The SQL
e460: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20  ITE_ACCESS_READ 
e470: 63 6f 6e 73 74 61 6e 74 20 69 73 0a 2a 2a 20 63  constant is.** c
e480: 75 72 72 65 6e 74 6c 79 20 75 6e 75 73 65 64 2c  urrently unused,
e490: 20 74 68 6f 75 67 68 20 69 74 20 6d 69 67 68 74   though it might
e4a0: 20 62 65 20 75 73 65 64 20 69 6e 20 61 20 66 75   be used in a fu
e4b0: 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66 0a  ture release of.
e4c0: 2a 2a 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64  ** SQLite..*/.#d
e4d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43  efine SQLITE_ACC
e4e0: 45 53 53 5f 45 58 49 53 54 53 20 20 20 20 30 0a  ESS_EXISTS    0.
e4f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
e500: 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 20  CCESS_READWRITE 
e510: 31 20 20 20 2f 2a 20 55 73 65 64 20 62 79 20 50  1   /* Used by P
e520: 52 41 47 4d 41 20 74 65 6d 70 5f 73 74 6f 72 65  RAGMA temp_store
e530: 5f 64 69 72 65 63 74 6f 72 79 20 2a 2f 0a 23 64  _directory */.#d
e540: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43  efine SQLITE_ACC
e550: 45 53 53 5f 52 45 41 44 20 20 20 20 20 20 32 20  ESS_READ      2 
e560: 20 20 2f 2a 20 55 6e 75 73 65 64 20 2a 2f 0a 0a    /* Unused */..
e570: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
e580: 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78 53  Flags for the xS
e590: 68 6d 4c 6f 63 6b 20 56 46 53 20 6d 65 74 68 6f  hmLock VFS metho
e5a0: 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e  d.**.** These in
e5b0: 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20  teger constants 
e5c0: 64 65 66 69 6e 65 20 74 68 65 20 76 61 72 69 6f  define the vario
e5d0: 75 73 20 6c 6f 63 6b 69 6e 67 20 6f 70 65 72 61  us locking opera
e5e0: 74 69 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f 77 65 64  tions.** allowed
e5f0: 20 62 79 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b   by the xShmLock
e600: 20 6d 65 74 68 6f 64 20 6f 66 20 5b 73 71 6c 69   method of [sqli
e610: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 2e  te3_io_methods].
e620: 20 20 54 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69    The.** followi
e630: 6e 67 20 61 72 65 20 74 68 65 20 6f 6e 6c 79 20  ng are the only 
e640: 6c 65 67 61 6c 20 63 6f 6d 62 69 6e 61 74 69 6f  legal combinatio
e650: 6e 73 20 6f 66 20 66 6c 61 67 73 20 74 6f 20 74  ns of flags to t
e660: 68 65 0a 2a 2a 20 78 53 68 6d 4c 6f 63 6b 20 6d  he.** xShmLock m
e670: 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  ethod:.**.** <ul
e680: 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54  >.** <li>  SQLIT
e690: 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c  E_SHM_LOCK | SQL
e6a0: 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a  ITE_SHM_SHARED.*
e6b0: 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53  * <li>  SQLITE_S
e6c0: 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45  HM_LOCK | SQLITE
e6d0: 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a 2a  _SHM_EXCLUSIVE.*
e6e0: 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53  * <li>  SQLITE_S
e6f0: 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49  HM_UNLOCK | SQLI
e700: 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a 2a  TE_SHM_SHARED.**
e710: 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48   <li>  SQLITE_SH
e720: 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 54  M_UNLOCK | SQLIT
e730: 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a  E_SHM_EXCLUSIVE.
e740: 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 57  ** </ul>.**.** W
e750: 68 65 6e 20 75 6e 6c 6f 63 6b 69 6e 67 2c 20 74  hen unlocking, t
e760: 68 65 20 73 61 6d 65 20 53 48 41 52 45 44 20 6f  he same SHARED o
e770: 72 20 45 58 43 4c 55 53 49 56 45 20 66 6c 61 67  r EXCLUSIVE flag
e780: 20 6d 75 73 74 20 62 65 20 73 75 70 70 6c 69 65   must be supplie
e790: 64 20 61 73 0a 2a 2a 20 77 61 73 20 67 69 76 65  d as.** was give
e7a0: 6e 20 6e 6f 20 74 68 65 20 63 6f 72 72 65 73 70  n no the corresp
e7b0: 6f 6e 64 69 6e 67 20 6c 6f 63 6b 2e 20 20 0a 2a  onding lock.  .*
e7c0: 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63  *.** The xShmLoc
e7d0: 6b 20 6d 65 74 68 6f 64 20 63 61 6e 20 74 72 61  k method can tra
e7e0: 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e 20  nsition between 
e7f0: 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 53 48 41  unlocked and SHA
e800: 52 45 44 20 6f 72 0a 2a 2a 20 62 65 74 77 65 65  RED or.** betwee
e810: 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 45  n unlocked and E
e820: 58 43 4c 55 53 49 56 45 2e 20 20 49 74 20 63 61  XCLUSIVE.  It ca
e830: 6e 6e 6f 74 20 74 72 61 6e 73 69 74 69 6f 6e 20  nnot transition 
e840: 62 65 74 77 65 65 6e 20 53 48 41 52 45 44 0a 2a  between SHARED.*
e850: 2a 20 61 6e 64 20 45 58 43 4c 55 53 49 56 45 2e  * and EXCLUSIVE.
e860: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
e870: 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 20 20  TE_SHM_UNLOCK   
e880: 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51      1.#define SQ
e890: 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 20 20  LITE_SHM_LOCK   
e8a0: 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20        2.#define 
e8b0: 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45  SQLITE_SHM_SHARE
e8c0: 44 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e  D       4.#defin
e8d0: 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43  e SQLITE_SHM_EXC
e8e0: 4c 55 53 49 56 45 20 20 20 20 38 0a 0a 2f 2a 0a  LUSIVE    8../*.
e8f0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 61 78  ** CAPI3REF: Max
e900: 69 6d 75 6d 20 78 53 68 6d 4c 6f 63 6b 20 69 6e  imum xShmLock in
e910: 64 65 78 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53  dex.**.** The xS
e920: 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 6e  hmLock method on
e930: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
e940: 68 6f 64 73 5d 20 6d 61 79 20 75 73 65 20 76 61  hods] may use va
e950: 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20  lues.** between 
e960: 30 20 61 6e 64 20 74 68 69 73 20 75 70 70 65 72  0 and this upper
e970: 20 62 6f 75 6e 64 20 61 73 20 69 74 73 20 22 6f   bound as its "o
e980: 66 66 73 65 74 22 20 61 72 67 75 6d 65 6e 74 2e  ffset" argument.
e990: 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63  .** The SQLite c
e9a0: 6f 72 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 61  ore will never a
e9b0: 74 74 65 6d 70 74 20 74 6f 20 61 63 71 75 69 72  ttempt to acquir
e9c0: 65 20 6f 72 20 72 65 6c 65 61 73 65 20 61 0a 2a  e or release a.*
e9d0: 2a 20 6c 6f 63 6b 20 6f 75 74 73 69 64 65 20 6f  * lock outside o
e9e0: 66 20 74 68 69 73 20 72 61 6e 67 65 0a 2a 2f 0a  f this range.*/.
e9f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
ea00: 48 4d 5f 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20  HM_NLOCK        
ea10: 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  8.../*.** CAPI3R
ea20: 45 46 3a 20 49 6e 69 74 69 61 6c 69 7a 65 20 54  EF: Initialize T
ea30: 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72  he SQLite Librar
ea40: 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  y.**.** ^The sql
ea50: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
ea60: 29 20 72 6f 75 74 69 6e 65 20 69 6e 69 74 69 61  ) routine initia
ea70: 6c 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53 51 4c  lizes the.** SQL
ea80: 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 5e 54  ite library.  ^T
ea90: 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  he sqlite3_shutd
eaa0: 6f 77 6e 28 29 20 72 6f 75 74 69 6e 65 0a 2a 2a  own() routine.**
eab0: 20 64 65 61 6c 6c 6f 63 61 74 65 73 20 61 6e 79   deallocates any
eac0: 20 72 65 73 6f 75 72 63 65 73 20 74 68 61 74 20   resources that 
ead0: 77 65 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62  were allocated b
eae0: 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  y sqlite3_initia
eaf0: 6c 69 7a 65 28 29 2e 0a 2a 2a 20 54 68 65 73 65  lize()..** These
eb00: 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 64 65   routines are de
eb10: 73 69 67 6e 65 64 20 74 6f 20 61 69 64 20 69 6e  signed to aid in
eb20: 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61 6c   process initial
eb30: 69 7a 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 73  ization and.** s
eb40: 68 75 74 64 6f 77 6e 20 6f 6e 20 65 6d 62 65 64  hutdown on embed
eb50: 64 65 64 20 73 79 73 74 65 6d 73 2e 20 20 57 6f  ded systems.  Wo
eb60: 72 6b 73 74 61 74 69 6f 6e 20 61 70 70 6c 69 63  rkstation applic
eb70: 61 74 69 6f 6e 73 20 75 73 69 6e 67 0a 2a 2a 20  ations using.** 
eb80: 53 51 4c 69 74 65 20 6e 6f 72 6d 61 6c 6c 79 20  SQLite normally 
eb90: 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 69  do not need to i
eba0: 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 6f 66 20  nvoke either of 
ebb0: 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a  these routines..
ebc0: 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20  **.** A call to 
ebd0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
ebe0: 7a 65 28 29 20 69 73 20 61 6e 20 22 65 66 66 65  ze() is an "effe
ebf0: 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69  ctive" call if i
ec00: 74 20 69 73 0a 2a 2a 20 74 68 65 20 66 69 72 73  t is.** the firs
ec10: 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69  t time sqlite3_i
ec20: 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69  nitialize() is i
ec30: 6e 76 6f 6b 65 64 20 64 75 72 69 6e 67 20 74 68  nvoked during th
ec40: 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 0a 2a 2a  e lifetime of.**
ec50: 20 74 68 65 20 70 72 6f 63 65 73 73 2c 20 6f 72   the process, or
ec60: 20 69 66 20 69 74 20 69 73 20 74 68 65 20 66 69   if it is the fi
ec70: 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33  rst time sqlite3
ec80: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73  _initialize() is
ec90: 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f 6c 6c   invoked.** foll
eca0: 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20  owing a call to 
ecb0: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
ecc0: 28 29 2e 20 20 5e 28 4f 6e 6c 79 20 61 6e 20 65  ().  ^(Only an e
ecd0: 66 66 65 63 74 69 76 65 20 63 61 6c 6c 0a 2a 2a  ffective call.**
ece0: 20 6f 66 20 73 71 6c 69 74 65 33 5f 69 6e 69 74   of sqlite3_init
ecf0: 69 61 6c 69 7a 65 28 29 20 64 6f 65 73 20 61 6e  ialize() does an
ed00: 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  y initialization
ed10: 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 63 61 6c  .  All other cal
ed20: 6c 73 0a 2a 2a 20 61 72 65 20 68 61 72 6d 6c 65  ls.** are harmle
ed30: 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a  ss no-ops.)^.**.
ed40: 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c  ** A call to sql
ed50: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20  ite3_shutdown() 
ed60: 69 73 20 61 6e 20 22 65 66 66 65 63 74 69 76 65  is an "effective
ed70: 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73 20  " call if it is 
ed80: 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 63 61 6c  the first.** cal
ed90: 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75  l to sqlite3_shu
eda0: 74 64 6f 77 6e 28 29 20 73 69 6e 63 65 20 74 68  tdown() since th
edb0: 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33 5f 69  e last sqlite3_i
edc0: 6e 69 74 69 61 6c 69 7a 65 28 29 2e 20 20 5e 28  nitialize().  ^(
edd0: 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66 66 65 63  Only.** an effec
ede0: 74 69 76 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c  tive call to sql
edf0: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20  ite3_shutdown() 
ee00: 64 6f 65 73 20 61 6e 79 20 64 65 69 6e 69 74 69  does any deiniti
ee10: 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 20 41 6c  alization..** Al
ee20: 6c 20 6f 74 68 65 72 20 76 61 6c 69 64 20 63 61  l other valid ca
ee30: 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  lls to sqlite3_s
ee40: 68 75 74 64 6f 77 6e 28 29 20 61 72 65 20 68 61  hutdown() are ha
ee50: 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e  rmless no-ops.)^
ee60: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
ee70: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
ee80: 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 68 72  interface is thr
ee90: 65 61 64 73 61 66 65 2c 20 62 75 74 20 73 71 6c  eadsafe, but sql
eea0: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a  ite3_shutdown().
eeb0: 2a 2a 20 69 73 20 6e 6f 74 2e 20 20 54 68 65 20  ** is not.  The 
eec0: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
eed0: 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d 75 73  () interface mus
eee0: 74 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64  t only be called
eef0: 20 66 72 6f 6d 20 61 0a 2a 2a 20 73 69 6e 67 6c   from a.** singl
ef00: 65 20 74 68 72 65 61 64 2e 20 20 41 6c 6c 20 6f  e thread.  All o
ef10: 70 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f  pen [database co
ef20: 6e 6e 65 63 74 69 6f 6e 73 5d 20 6d 75 73 74 20  nnections] must 
ef30: 62 65 20 63 6c 6f 73 65 64 20 61 6e 64 20 61 6c  be closed and al
ef40: 6c 0a 2a 2a 20 6f 74 68 65 72 20 53 51 4c 69 74  l.** other SQLit
ef50: 65 20 72 65 73 6f 75 72 63 65 73 20 6d 75 73 74  e resources must
ef60: 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20   be deallocated 
ef70: 70 72 69 6f 72 20 74 6f 20 69 6e 76 6f 6b 69 6e  prior to invokin
ef80: 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 68 75  g.** sqlite3_shu
ef90: 74 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 41  tdown()..**.** A
efa0: 6d 6f 6e 67 20 6f 74 68 65 72 20 74 68 69 6e 67  mong other thing
efb0: 73 2c 20 5e 73 71 6c 69 74 65 33 5f 69 6e 69 74  s, ^sqlite3_init
efc0: 69 61 6c 69 7a 65 28 29 20 77 69 6c 6c 20 69 6e  ialize() will in
efd0: 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  voke.** sqlite3_
efe0: 6f 73 5f 69 6e 69 74 28 29 2e 20 20 53 69 6d 69  os_init().  Simi
eff0: 6c 61 72 6c 79 2c 20 5e 73 71 6c 69 74 65 33 5f  larly, ^sqlite3_
f000: 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 77 69  shutdown().** wi
f010: 6c 6c 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65  ll invoke sqlite
f020: 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a 0a 2a  3_os_end()..**.*
f030: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69  * ^The sqlite3_i
f040: 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74  nitialize() rout
f050: 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ine returns [SQL
f060: 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65  ITE_OK] on succe
f070: 73 73 2e 0a 2a 2a 20 5e 49 66 20 66 6f 72 20 73  ss..** ^If for s
f080: 6f 6d 65 20 72 65 61 73 6f 6e 2c 20 73 71 6c 69  ome reason, sqli
f090: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
f0a0: 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 69 6e   is unable to in
f0b0: 69 74 69 61 6c 69 7a 65 0a 2a 2a 20 74 68 65 20  itialize.** the 
f0c0: 6c 69 62 72 61 72 79 20 28 70 65 72 68 61 70 73  library (perhaps
f0d0: 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f   it is unable to
f0e0: 20 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65 65 64   allocate a need
f0f0: 65 64 20 72 65 73 6f 75 72 63 65 20 73 75 63 68  ed resource such
f100: 0a 2a 2a 20 61 73 20 61 20 6d 75 74 65 78 29 20  .** as a mutex) 
f110: 69 74 20 72 65 74 75 72 6e 73 20 61 6e 20 5b 65  it returns an [e
f120: 72 72 6f 72 20 63 6f 64 65 5d 20 6f 74 68 65 72  rror code] other
f130: 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b   than [SQLITE_OK
f140: 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ]..**.** ^The sq
f150: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
f160: 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61  () routine is ca
f170: 6c 6c 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20  lled internally 
f180: 62 79 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a  by many other.**
f190: 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
f1a0: 65 73 20 73 6f 20 74 68 61 74 20 61 6e 20 61 70  es so that an ap
f1b0: 70 6c 69 63 61 74 69 6f 6e 20 75 73 75 61 6c 6c  plication usuall
f1c0: 79 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20  y does not need 
f1d0: 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c  to.** invoke sql
f1e0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
f1f0: 29 20 64 69 72 65 63 74 6c 79 2e 20 20 46 6f 72  ) directly.  For
f200: 20 65 78 61 6d 70 6c 65 2c 20 5b 73 71 6c 69 74   example, [sqlit
f210: 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 63 61  e3_open()].** ca
f220: 6c 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  lls sqlite3_init
f230: 69 61 6c 69 7a 65 28 29 20 73 6f 20 74 68 65 20  ialize() so the 
f240: 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77  SQLite library w
f250: 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63  ill be automatic
f260: 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69 61 6c 69  ally.** initiali
f270: 7a 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65  zed when [sqlite
f280: 33 5f 6f 70 65 6e 28 29 5d 20 69 73 20 63 61 6c  3_open()] is cal
f290: 6c 65 64 20 69 66 20 69 74 20 68 61 73 20 6e 6f  led if it has no
f2a0: 74 20 62 65 20 69 6e 69 74 69 61 6c 69 7a 65 64  t be initialized
f2b0: 0a 2a 2a 20 61 6c 72 65 61 64 79 2e 20 20 5e 48  .** already.  ^H
f2c0: 6f 77 65 76 65 72 2c 20 69 66 20 53 51 4c 69 74  owever, if SQLit
f2d0: 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
f2e0: 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  th the [SQLITE_O
f2f0: 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 0a 2a 2a  MIT_AUTOINIT].**
f300: 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
f310: 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 61  tion, then the a
f320: 75 74 6f 6d 61 74 69 63 20 63 61 6c 6c 73 20 74  utomatic calls t
f330: 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  o sqlite3_initia
f340: 6c 69 7a 65 28 29 0a 2a 2a 20 61 72 65 20 6f 6d  lize().** are om
f350: 69 74 74 65 64 20 61 6e 64 20 74 68 65 20 61 70  itted and the ap
f360: 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 63  plication must c
f370: 61 6c 6c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  all sqlite3_init
f380: 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c  ialize() directl
f390: 79 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 75 73  y.** prior to us
f3a0: 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51  ing any other SQ
f3b0: 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20  Lite interface. 
f3c0: 20 46 6f 72 20 6d 61 78 69 6d 75 6d 20 70 6f 72   For maximum por
f3d0: 74 61 62 69 6c 69 74 79 2c 0a 2a 2a 20 69 74 20  tability,.** it 
f3e0: 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74  is recommended t
f3f0: 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  hat applications
f400: 20 61 6c 77 61 79 73 20 69 6e 76 6f 6b 65 20 73   always invoke s
f410: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
f420: 65 28 29 0a 2a 2a 20 64 69 72 65 63 74 6c 79 20  e().** directly 
f430: 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61  prior to using a
f440: 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20  ny other SQLite 
f450: 69 6e 74 65 72 66 61 63 65 2e 20 20 46 75 74 75  interface.  Futu
f460: 72 65 20 72 65 6c 65 61 73 65 73 0a 2a 2a 20 6f  re releases.** o
f470: 66 20 53 51 4c 69 74 65 20 6d 61 79 20 72 65 71  f SQLite may req
f480: 75 69 72 65 20 74 68 69 73 2e 20 20 49 6e 20 6f  uire this.  In o
f490: 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20  ther words, the 
f4a0: 62 65 68 61 76 69 6f 72 20 65 78 68 69 62 69 74  behavior exhibit
f4b0: 65 64 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74  ed.** when SQLit
f4c0: 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
f4d0: 74 68 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  th [SQLITE_OMIT_
f4e0: 41 55 54 4f 49 4e 49 54 5d 20 6d 69 67 68 74 20  AUTOINIT] might 
f4f0: 62 65 63 6f 6d 65 20 74 68 65 0a 2a 2a 20 64 65  become the.** de
f500: 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20 69  fault behavior i
f510: 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20 72 65  n some future re
f520: 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e  lease of SQLite.
f530: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
f540: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 72 6f 75  e3_os_init() rou
f550: 74 69 6e 65 20 64 6f 65 73 20 6f 70 65 72 61 74  tine does operat
f560: 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69  ing-system speci
f570: 66 69 63 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a  fic.** initializ
f580: 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 53 51 4c  ation of the SQL
f590: 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 54 68  ite library.  Th
f5a0: 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  e sqlite3_os_end
f5b0: 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 75 6e  ().** routine un
f5c0: 64 6f 65 73 20 74 68 65 20 65 66 66 65 63 74 20  does the effect 
f5d0: 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  of sqlite3_os_in
f5e0: 69 74 28 29 2e 20 20 54 79 70 69 63 61 6c 20 74  it().  Typical t
f5f0: 61 73 6b 73 0a 2a 2a 20 70 65 72 66 6f 72 6d 65  asks.** performe
f600: 64 20 62 79 20 74 68 65 73 65 20 72 6f 75 74 69  d by these routi
f610: 6e 65 73 20 69 6e 63 6c 75 64 65 20 61 6c 6c 6f  nes include allo
f620: 63 61 74 69 6f 6e 20 6f 72 20 64 65 61 6c 6c 6f  cation or deallo
f630: 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73 74 61  cation.** of sta
f640: 74 69 63 20 72 65 73 6f 75 72 63 65 73 2c 20 69  tic resources, i
f650: 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66  nitialization of
f660: 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65   global variable
f670: 73 2c 0a 2a 2a 20 73 65 74 74 69 6e 67 20 75 70  s,.** setting up
f680: 20 61 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69   a default [sqli
f690: 74 65 33 5f 76 66 73 5d 20 6d 6f 64 75 6c 65 2c  te3_vfs] module,
f6a0: 20 6f 72 20 73 65 74 74 69 6e 67 20 75 70 0a 2a   or setting up.*
f6b0: 2a 20 61 20 64 65 66 61 75 6c 74 20 63 6f 6e 66  * a default conf
f6c0: 69 67 75 72 61 74 69 6f 6e 20 75 73 69 6e 67 20  iguration using 
f6d0: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
f6e0: 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70  )]..**.** The ap
f6f0: 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64  plication should
f700: 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 65 69   never invoke ei
f710: 74 68 65 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f  ther sqlite3_os_
f720: 69 6e 69 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c  init().** or sql
f730: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 64 69  ite3_os_end() di
f740: 72 65 63 74 6c 79 2e 20 20 54 68 65 20 61 70 70  rectly.  The app
f750: 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  lication should 
f760: 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73  only invoke.** s
f770: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
f780: 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  e() and sqlite3_
f790: 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 54 68 65  shutdown().  The
f7a0: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
f7b0: 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  ().** interface 
f7c0: 69 73 20 63 61 6c 6c 65 64 20 61 75 74 6f 6d 61  is called automa
f7d0: 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74  tically by sqlit
f7e0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
f7f0: 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  and.** sqlite3_o
f800: 73 5f 65 6e 64 28 29 20 69 73 20 63 61 6c 6c 65  s_end() is calle
f810: 64 20 62 79 20 73 71 6c 69 74 65 33 5f 73 68 75  d by sqlite3_shu
f820: 74 64 6f 77 6e 28 29 2e 20 20 41 70 70 72 6f 70  tdown().  Approp
f830: 72 69 61 74 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65  riate.** impleme
f840: 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20 73 71 6c  ntations for sql
f850: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61  ite3_os_init() a
f860: 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  nd sqlite3_os_en
f870: 64 28 29 0a 2a 2a 20 61 72 65 20 62 75 69 6c 74  d().** are built
f880: 20 69 6e 74 6f 20 53 51 4c 69 74 65 20 77 68 65   into SQLite whe
f890: 6e 20 69 74 20 69 73 20 63 6f 6d 70 69 6c 65 64  n it is compiled
f8a0: 20 66 6f 72 20 55 6e 69 78 2c 20 57 69 6e 64 6f   for Unix, Windo
f8b0: 77 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a 2a 2a 20  ws, or OS/2..** 
f8c0: 57 68 65 6e 20 5b 63 75 73 74 6f 6d 20 62 75 69  When [custom bui
f8d0: 6c 64 73 20 7c 20 62 75 69 6c 74 20 66 6f 72 20  lds | built for 
f8e0: 6f 74 68 65 72 20 70 6c 61 74 66 6f 72 6d 73 5d  other platforms]
f8f0: 0a 2a 2a 20 28 75 73 69 6e 67 20 74 68 65 20 5b  .** (using the [
f900: 53 51 4c 49 54 45 5f 4f 53 5f 4f 54 48 45 52 3d  SQLITE_OS_OTHER=
f910: 31 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a  1] compile-time.
f920: 2a 2a 20 6f 70 74 69 6f 6e 29 20 74 68 65 20 61  ** option) the a
f930: 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
f940: 73 75 70 70 6c 79 20 61 20 73 75 69 74 61 62 6c  supply a suitabl
f950: 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
f960: 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   for.** sqlite3_
f970: 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71  os_init() and sq
f980: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 20  lite3_os_end(). 
f990: 20 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   An application-
f9a0: 73 75 70 70 6c 69 65 64 0a 2a 2a 20 69 6d 70 6c  supplied.** impl
f9b0: 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71  ementation of sq
f9c0: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20  lite3_os_init() 
f9d0: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  or sqlite3_os_en
f9e0: 64 28 29 0a 2a 2a 20 6d 75 73 74 20 72 65 74 75  d().** must retu
f9f0: 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f  rn [SQLITE_OK] o
fa00: 6e 20 73 75 63 63 65 73 73 20 61 6e 64 20 73 6f  n success and so
fa10: 6d 65 20 6f 74 68 65 72 20 5b 65 72 72 6f 72 20  me other [error 
fa20: 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20 66 61  code] upon.** fa
fa30: 69 6c 75 72 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ilure..*/.int sq
fa40: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
fa50: 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69  (void);.int sqli
fa60: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 76 6f 69  te3_shutdown(voi
fa70: 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  d);.int sqlite3_
fa80: 6f 73 5f 69 6e 69 74 28 76 6f 69 64 29 3b 0a 69  os_init(void);.i
fa90: 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  nt sqlite3_os_en
faa0: 64 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20  d(void);../*.** 
fab0: 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67  CAPI3REF: Config
fac0: 75 72 69 6e 67 20 54 68 65 20 53 51 4c 69 74 65  uring The SQLite
fad0: 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 54   Library.**.** T
fae0: 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  he sqlite3_confi
faf0: 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  g() interface is
fb00: 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 67 6c   used to make gl
fb10: 6f 62 61 6c 20 63 6f 6e 66 69 67 75 72 61 74 69  obal configurati
fb20: 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f  on.** changes to
fb30: 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72   SQLite in order
fb40: 20 74 6f 20 74 75 6e 65 20 53 51 4c 69 74 65 20   to tune SQLite 
fb50: 74 6f 20 74 68 65 20 73 70 65 63 69 66 69 63 20  to the specific 
fb60: 6e 65 65 64 73 20 6f 66 0a 2a 2a 20 74 68 65 20  needs of.** the 
fb70: 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 54 68  application.  Th
fb80: 65 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67  e default config
fb90: 75 72 61 74 69 6f 6e 20 69 73 20 72 65 63 6f 6d  uration is recom
fba0: 6d 65 6e 64 65 64 20 66 6f 72 20 6d 6f 73 74 0a  mended for most.
fbb0: 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  ** applications 
fbc0: 61 6e 64 20 73 6f 20 74 68 69 73 20 72 6f 75 74  and so this rout
fbd0: 69 6e 65 20 69 73 20 75 73 75 61 6c 6c 79 20 6e  ine is usually n
fbe0: 6f 74 20 6e 65 63 65 73 73 61 72 79 2e 20 20 49  ot necessary.  I
fbf0: 74 20 69 73 0a 2a 2a 20 70 72 6f 76 69 64 65 64  t is.** provided
fc00: 20 74 6f 20 73 75 70 70 6f 72 74 20 72 61 72 65   to support rare
fc10: 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 77 69   applications wi
fc20: 74 68 20 75 6e 75 73 75 61 6c 20 6e 65 65 64 73  th unusual needs
fc30: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
fc40: 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74  te3_config() int
fc50: 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20 74 68  erface is not th
fc60: 72 65 61 64 73 61 66 65 2e 20 20 54 68 65 20 61  readsafe.  The a
fc70: 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75  pplication.** mu
fc80: 73 74 20 69 6e 73 75 72 65 20 74 68 61 74 20 6e  st insure that n
fc90: 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69  o other SQLite i
fca0: 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 69 6e  nterfaces are in
fcb0: 76 6f 6b 65 64 20 62 79 20 6f 74 68 65 72 0a 2a  voked by other.*
fcc0: 2a 20 74 68 72 65 61 64 73 20 77 68 69 6c 65 20  * threads while 
fcd0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
fce0: 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20 20 46 75   is running.  Fu
fcf0: 72 74 68 65 72 6d 6f 72 65 2c 20 73 71 6c 69 74  rthermore, sqlit
fd00: 65 33 5f 63 6f 6e 66 69 67 28 29 0a 2a 2a 20 6d  e3_config().** m
fd10: 61 79 20 6f 6e 6c 79 20 62 65 20 69 6e 76 6f 6b  ay only be invok
fd20: 65 64 20 70 72 69 6f 72 20 74 6f 20 6c 69 62 72  ed prior to libr
fd30: 61 72 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  ary initializati
fd40: 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c  on using.** [sql
fd50: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
fd60: 29 5d 20 6f 72 20 61 66 74 65 72 20 73 68 75 74  )] or after shut
fd70: 64 6f 77 6e 20 62 79 20 5b 73 71 6c 69 74 65 33  down by [sqlite3
fd80: 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a  _shutdown()]..**
fd90: 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6f 6e   ^If sqlite3_con
fda0: 66 69 67 28 29 20 69 73 20 63 61 6c 6c 65 64 20  fig() is called 
fdb0: 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 69  after [sqlite3_i
fdc0: 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 61 6e 64  nitialize()] and
fdd0: 20 62 65 66 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69   before.** [sqli
fde0: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20  te3_shutdown()] 
fdf0: 74 68 65 6e 20 69 74 20 77 69 6c 6c 20 72 65 74  then it will ret
fe00: 75 72 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53  urn SQLITE_MISUS
fe10: 45 2e 0a 2a 2a 20 4e 6f 74 65 2c 20 68 6f 77 65  E..** Note, howe
fe20: 76 65 72 2c 20 74 68 61 74 20 5e 73 71 6c 69 74  ver, that ^sqlit
fe30: 65 33 5f 63 6f 6e 66 69 67 28 29 20 63 61 6e 20  e3_config() can 
fe40: 62 65 20 63 61 6c 6c 65 64 20 61 73 20 70 61 72  be called as par
fe50: 74 20 6f 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c  t of the.** impl
fe60: 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e  ementation of an
fe70: 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
fe80: 69 6e 65 64 20 5b 73 71 6c 69 74 65 33 5f 6f 73  ined [sqlite3_os
fe90: 5f 69 6e 69 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  _init()]..**.** 
fea0: 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
feb0: 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  nt to sqlite3_co
fec0: 6e 66 69 67 28 29 20 69 73 20 61 6e 20 69 6e 74  nfig() is an int
fed0: 65 67 65 72 0a 2a 2a 20 5b 63 6f 6e 66 69 67 75  eger.** [configu
fee0: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 20 74  ration option] t
fef0: 68 61 74 20 64 65 74 65 72 6d 69 6e 65 73 0a 2a  hat determines.*
ff00: 2a 20 77 68 61 74 20 70 72 6f 70 65 72 74 79 20  * what property 
ff10: 6f 66 20 53 51 4c 69 74 65 20 69 73 20 74 6f 20  of SQLite is to 
ff20: 62 65 20 63 6f 6e 66 69 67 75 72 65 64 2e 20 20  be configured.  
ff30: 53 75 62 73 65 71 75 65 6e 74 20 61 72 67 75 6d  Subsequent argum
ff40: 65 6e 74 73 0a 2a 2a 20 76 61 72 79 20 64 65 70  ents.** vary dep
ff50: 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 5b 63  ending on the [c
ff60: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
ff70: 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66  ion].** in the f
ff80: 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  irst argument..*
ff90: 2a 0a 2a 2a 20 5e 57 68 65 6e 20 61 20 63 6f 6e  *.** ^When a con
ffa0: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
ffb0: 6e 20 69 73 20 73 65 74 2c 20 73 71 6c 69 74 65  n is set, sqlite
ffc0: 33 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 75 72  3_config() retur
ffd0: 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a  ns [SQLITE_OK]..
ffe0: 2a 2a 20 5e 49 66 20 74 68 65 20 6f 70 74 69 6f  ** ^If the optio
fff0: 6e 20 69 73 20 75 6e 6b 6e 6f 77 6e 20 6f 72 20  n is unknown or 
10000 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65  SQLite is unable
10010 20 74 6f 20 73 65 74 20 74 68 65 20 6f 70 74 69   to set the opti
10020 6f 6e 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 20  on.** then this 
10030 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
10040 61 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f  a non-zero [erro
10050 72 20 63 6f 64 65 5d 2e 0a 2a 2f 0a 69 6e 74 20  r code]..*/.int 
10060 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 69  sqlite3_config(i
10070 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a  nt, ...);../*.**
10080 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69   CAPI3REF: Confi
10090 67 75 72 65 20 64 61 74 61 62 61 73 65 20 63 6f  gure database co
100a0 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20  nnections.**.** 
100b0 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 63  The sqlite3_db_c
100c0 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63  onfig() interfac
100d0 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b  e is used to mak
100e0 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a  e configuration.
100f0 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 61 20  ** changes to a 
10100 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
10110 74 69 6f 6e 5d 2e 20 20 54 68 65 20 69 6e 74 65  tion].  The inte
10120 72 66 61 63 65 20 69 73 20 73 69 6d 69 6c 61 72  rface is similar
10130 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
10140 63 6f 6e 66 69 67 28 29 5d 20 65 78 63 65 70 74  config()] except
10150 20 74 68 61 74 20 74 68 65 20 63 68 61 6e 67 65   that the change
10160 73 20 61 70 70 6c 79 20 74 6f 20 61 20 73 69 6e  s apply to a sin
10170 67 6c 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  gle.** [database
10180 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 73 70   connection] (sp
10190 65 63 69 66 69 65 64 20 69 6e 20 74 68 65 20 66  ecified in the f
101a0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 29 2e 0a  irst argument)..
101b0 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  **.** The second
101c0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
101d0 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 44  ite3_db_config(D
101e0 2c 56 2c 2e 2e 2e 29 20 20 69 73 20 74 68 65 0a  ,V,...)  is the.
101f0 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e  ** [SQLITE_DBCON
10200 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 7c 20  FIG_LOOKASIDE | 
10210 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65  configuration ve
10220 72 62 5d 20 2d 20 61 6e 20 69 6e 74 65 67 65 72  rb] - an integer
10230 20 63 6f 64 65 20 0a 2a 2a 20 74 68 61 74 20 69   code .** that i
10240 6e 64 69 63 61 74 65 73 20 77 68 61 74 20 61 73  ndicates what as
10250 70 65 63 74 20 6f 66 20 74 68 65 20 5b 64 61 74  pect of the [dat
10260 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
10270 5d 20 69 73 20 62 65 69 6e 67 20 63 6f 6e 66 69  ] is being confi
10280 67 75 72 65 64 2e 0a 2a 2a 20 53 75 62 73 65 71  gured..** Subseq
10290 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 20 76  uent arguments v
102a0 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  ary depending on
102b0 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69   the configurati
102c0 6f 6e 20 76 65 72 62 2e 0a 2a 2a 0a 2a 2a 20 5e  on verb..**.** ^
102d0 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  Calls to sqlite3
102e0 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 72 65 74  _db_config() ret
102f0 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66  urn SQLITE_OK if
10300 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20   and only if.** 
10310 74 68 65 20 63 61 6c 6c 20 69 73 20 63 6f 6e 73  the call is cons
10320 69 64 65 72 65 64 20 73 75 63 63 65 73 73 66 75  idered successfu
10330 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  l..*/.int sqlite
10340 33 5f 64 62 5f 63 6f 6e 66 69 67 28 73 71 6c 69  3_db_config(sqli
10350 74 65 33 2a 2c 20 69 6e 74 20 6f 70 2c 20 2e 2e  te3*, int op, ..
10360 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
10370 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f  REF: Memory Allo
10380 63 61 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73 0a  cation Routines.
10390 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63  **.** An instanc
103a0 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
103b0 20 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74   defines the int
103c0 65 72 66 61 63 65 20 62 65 74 77 65 65 6e 20 53  erface between S
103d0 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 6c 6f 77  QLite.** and low
103e0 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c  -level memory al
103f0 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  location routine
10400 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 6f 62  s..**.** This ob
10410 6a 65 63 74 20 69 73 20 75 73 65 64 20 69 6e 20  ject is used in 
10420 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61 63 65 20 69  only one place i
10430 6e 20 74 68 65 20 53 51 4c 69 74 65 20 69 6e 74  n the SQLite int
10440 65 72 66 61 63 65 2e 0a 2a 2a 20 41 20 70 6f 69  erface..** A poi
10450 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61  nter to an insta
10460 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65  nce of this obje
10470 63 74 20 69 73 20 74 68 65 20 61 72 67 75 6d 65  ct is the argume
10480 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  nt to.** [sqlite
10490 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 68 65 6e  3_config()] when
104a0 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69   the configurati
104b0 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20  on option is.** 
104c0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
104d0 41 4c 4c 4f 43 5d 20 6f 72 20 5b 53 51 4c 49 54  ALLOC] or [SQLIT
104e0 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c  E_CONFIG_GETMALL
104f0 4f 43 5d 2e 20 20 0a 2a 2a 20 42 79 20 63 72 65  OC].  .** By cre
10500 61 74 69 6e 67 20 61 6e 20 69 6e 73 74 61 6e 63  ating an instanc
10510 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
10520 0a 2a 2a 20 61 6e 64 20 70 61 73 73 69 6e 67 20  .** and passing 
10530 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  it to [sqlite3_c
10540 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43  onfig]([SQLITE_C
10550 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 29 0a 2a  ONFIG_MALLOC]).*
10560 2a 20 64 75 72 69 6e 67 20 63 6f 6e 66 69 67 75  * during configu
10570 72 61 74 69 6f 6e 2c 20 61 6e 20 61 70 70 6c 69  ration, an appli
10580 63 61 74 69 6f 6e 20 63 61 6e 20 73 70 65 63 69  cation can speci
10590 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76  fy an alternativ
105a0 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  e.** memory allo
105b0 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d  cation subsystem
105c0 20 66 6f 72 20 53 51 4c 69 74 65 20 74 6f 20 75   for SQLite to u
105d0 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74  se for all of it
105e0 73 0a 2a 2a 20 64 79 6e 61 6d 69 63 20 6d 65 6d  s.** dynamic mem
105f0 6f 72 79 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a  ory needs..**.**
10600 20 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 69 74   Note that SQLit
10610 65 20 63 6f 6d 65 73 20 77 69 74 68 20 73 65 76  e comes with sev
10620 65 72 61 6c 20 5b 62 75 69 6c 74 2d 69 6e 20 6d  eral [built-in m
10630 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73  emory allocators
10640 5d 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 70 65  ].** that are pe
10650 72 66 65 63 74 6c 79 20 61 64 65 71 75 61 74 65  rfectly adequate
10660 20 66 6f 72 20 74 68 65 20 6f 76 65 72 77 68 65   for the overwhe
10670 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69 74 79 20 6f  lming majority o
10680 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a  f applications.*
10690 2a 20 61 6e 64 20 74 68 61 74 20 74 68 69 73 20  * and that this 
106a0 6f 62 6a 65 63 74 20 69 73 20 6f 6e 6c 79 20 75  object is only u
106b0 73 65 66 75 6c 20 74 6f 20 61 20 74 69 6e 79 20  seful to a tiny 
106c0 6d 69 6e 6f 72 69 74 79 20 6f 66 20 61 70 70 6c  minority of appl
106d0 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68  ications.** with
106e0 20 73 70 65 63 69 61 6c 69 7a 65 64 20 6d 65 6d   specialized mem
106f0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ory allocation r
10700 65 71 75 69 72 65 6d 65 6e 74 73 2e 20 20 54 68  equirements.  Th
10710 69 73 20 6f 62 6a 65 63 74 20 69 73 0a 2a 2a 20  is object is.** 
10720 61 6c 73 6f 20 75 73 65 64 20 64 75 72 69 6e 67  also used during
10730 20 74 65 73 74 69 6e 67 20 6f 66 20 53 51 4c 69   testing of SQLi
10740 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 73  te in order to s
10750 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e  pecify an altern
10760 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20  ative.** memory 
10770 61 6c 6c 6f 63 61 74 6f 72 20 74 68 61 74 20 73  allocator that s
10780 69 6d 75 6c 61 74 65 73 20 6d 65 6d 6f 72 79 20  imulates memory 
10790 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20 63 6f  out-of-memory co
107a0 6e 64 69 74 69 6f 6e 73 20 69 6e 0a 2a 2a 20 6f  nditions in.** o
107b0 72 64 65 72 20 74 6f 20 76 65 72 69 66 79 20 74  rder to verify t
107c0 68 61 74 20 53 51 4c 69 74 65 20 72 65 63 6f 76  hat SQLite recov
107d0 65 72 73 20 67 72 61 63 65 66 75 6c 6c 79 20 66  ers gracefully f
107e0 72 6f 6d 20 73 75 63 68 0a 2a 2a 20 63 6f 6e 64  rom such.** cond
107f0 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  itions..**.** Th
10800 65 20 78 4d 61 6c 6c 6f 63 2c 20 78 52 65 61 6c  e xMalloc, xReal
10810 6c 6f 63 2c 20 61 6e 64 20 78 46 72 65 65 20 6d  loc, and xFree m
10820 65 74 68 6f 64 73 20 6d 75 73 74 20 77 6f 72 6b  ethods must work
10830 20 6c 69 6b 65 20 74 68 65 0a 2a 2a 20 6d 61 6c   like the.** mal
10840 6c 6f 63 28 29 2c 20 72 65 61 6c 6c 6f 63 28 29  loc(), realloc()
10850 20 61 6e 64 20 66 72 65 65 28 29 20 66 75 6e 63   and free() func
10860 74 69 6f 6e 73 20 66 72 6f 6d 20 74 68 65 20 73  tions from the s
10870 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72  tandard C librar
10880 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75  y..** ^SQLite gu
10890 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 68  arantees that th
108a0 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
108b0 74 20 74 6f 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63  t to.** xRealloc
108c0 20 69 73 20 61 6c 77 61 79 73 20 61 20 76 61 6c   is always a val
108d0 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 61  ue returned by a
108e0 20 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f 20 78   prior call to x
108f0 52 6f 75 6e 64 75 70 2e 0a 2a 2a 0a 2a 2a 20 78  Roundup..**.** x
10900 53 69 7a 65 20 73 68 6f 75 6c 64 20 72 65 74 75  Size should retu
10910 72 6e 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64  rn the allocated
10920 20 73 69 7a 65 20 6f 66 20 61 20 6d 65 6d 6f 72   size of a memor
10930 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  y allocation.** 
10940 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69  previously obtai
10950 6e 65 64 20 66 72 6f 6d 20 78 4d 61 6c 6c 6f 63  ned from xMalloc
10960 20 6f 72 20 78 52 65 61 6c 6c 6f 63 2e 20 20 54   or xRealloc.  T
10970 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a  he allocated siz
10980 65 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61  e.** is always a
10990 74 20 6c 65 61 73 74 20 61 73 20 62 69 67 20 61  t least as big a
109a0 73 20 74 68 65 20 72 65 71 75 65 73 74 65 64 20  s the requested 
109b0 73 69 7a 65 20 62 75 74 20 6d 61 79 20 62 65 20  size but may be 
109c0 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  larger..**.** Th
109d0 65 20 78 52 6f 75 6e 64 75 70 20 6d 65 74 68 6f  e xRoundup metho
109e0 64 20 72 65 74 75 72 6e 73 20 77 68 61 74 20 77  d returns what w
109f0 6f 75 6c 64 20 62 65 20 74 68 65 20 61 6c 6c 6f  ould be the allo
10a00 63 61 74 65 64 20 73 69 7a 65 20 6f 66 0a 2a 2a  cated size of.**
10a10 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
10a20 74 69 6f 6e 20 67 69 76 65 6e 20 61 20 70 61 72  tion given a par
10a30 74 69 63 75 6c 61 72 20 72 65 71 75 65 73 74 65  ticular requeste
10a40 64 20 73 69 7a 65 2e 20 20 4d 6f 73 74 20 6d 65  d size.  Most me
10a50 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f  mory.** allocato
10a60 72 73 20 72 6f 75 6e 64 20 75 70 20 6d 65 6d 6f  rs round up memo
10a70 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 61  ry allocations a
10a80 74 20 6c 65 61 73 74 20 74 6f 20 74 68 65 20 6e  t least to the n
10a90 65 78 74 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20  ext multiple.** 
10aa0 6f 66 20 38 2e 20 20 53 6f 6d 65 20 61 6c 6c 6f  of 8.  Some allo
10ab0 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20  cators round up 
10ac0 74 6f 20 61 20 6c 61 72 67 65 72 20 6d 75 6c 74  to a larger mult
10ad0 69 70 6c 65 20 6f 72 20 74 6f 20 61 20 70 6f 77  iple or to a pow
10ae0 65 72 20 6f 66 20 32 2e 0a 2a 2a 20 45 76 65 72  er of 2..** Ever
10af0 79 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  y memory allocat
10b00 69 6f 6e 20 72 65 71 75 65 73 74 20 63 6f 6d 69  ion request comi
10b10 6e 67 20 69 6e 20 74 68 72 6f 75 67 68 20 5b 73  ng in through [s
10b20 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
10b30 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  .** or [sqlite3_
10b40 72 65 61 6c 6c 6f 63 28 29 5d 20 66 69 72 73 74  realloc()] first
10b50 20 63 61 6c 6c 73 20 78 52 6f 75 6e 64 75 70 2e   calls xRoundup.
10b60 20 20 49 66 20 78 52 6f 75 6e 64 75 70 20 72 65    If xRoundup re
10b70 74 75 72 6e 73 20 30 2c 20 0a 2a 2a 20 74 68 61  turns 0, .** tha
10b80 74 20 63 61 75 73 65 73 20 74 68 65 20 63 6f 72  t causes the cor
10b90 72 65 73 70 6f 6e 64 69 6e 67 20 6d 65 6d 6f 72  responding memor
10ba0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20  y allocation to 
10bb0 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  fail..**.** The 
10bc0 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 69 6e 69  xInit method ini
10bd0 74 69 61 6c 69 7a 65 73 20 74 68 65 20 6d 65 6d  tializes the mem
10be0 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 2e 20 20  ory allocator.  
10bf0 46 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20  For example,.** 
10c00 69 74 20 6d 69 67 68 74 20 61 6c 6c 6f 63 61 74  it might allocat
10c10 65 20 61 6e 79 20 72 65 71 75 69 72 65 20 6d 75  e any require mu
10c20 74 65 78 65 73 20 6f 72 20 69 6e 69 74 69 61 6c  texes or initial
10c30 69 7a 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74  ize internal dat
10c40 61 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 73 2e  a.** structures.
10c50 20 20 54 68 65 20 78 53 68 75 74 64 6f 77 6e 20    The xShutdown 
10c60 6d 65 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65  method is invoke
10c70 64 20 28 69 6e 64 69 72 65 63 74 6c 79 29 20 62  d (indirectly) b
10c80 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68  y.** [sqlite3_sh
10c90 75 74 64 6f 77 6e 28 29 5d 20 61 6e 64 20 73 68  utdown()] and sh
10ca0 6f 75 6c 64 20 64 65 61 6c 6c 6f 63 61 74 65 20  ould deallocate 
10cb0 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20 61 63  any resources ac
10cc0 71 75 69 72 65 64 0a 2a 2a 20 62 79 20 78 49 6e  quired.** by xIn
10cd0 69 74 2e 20 20 54 68 65 20 70 41 70 70 44 61 74  it.  The pAppDat
10ce0 61 20 70 6f 69 6e 74 65 72 20 69 73 20 75 73 65  a pointer is use
10cf0 64 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 61  d as the only pa
10d00 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 78 49  rameter to.** xI
10d10 6e 69 74 20 61 6e 64 20 78 53 68 75 74 64 6f 77  nit and xShutdow
10d20 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  n..**.** SQLite 
10d30 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 54  holds the [SQLIT
10d40 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d  E_MUTEX_STATIC_M
10d50 41 53 54 45 52 5d 20 6d 75 74 65 78 20 77 68 65  ASTER] mutex whe
10d60 6e 20 69 74 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20  n it invokes.** 
10d70 74 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64  the xInit method
10d80 2c 20 73 6f 20 74 68 65 20 78 49 6e 69 74 20 6d  , so the xInit m
10d90 65 74 68 6f 64 20 6e 65 65 64 20 6e 6f 74 20 62  ethod need not b
10da0 65 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 54  e threadsafe.  T
10db0 68 65 0a 2a 2a 20 78 53 68 75 74 64 6f 77 6e 20  he.** xShutdown 
10dc0 6d 65 74 68 6f 64 20 69 73 20 6f 6e 6c 79 20 63  method is only c
10dd0 61 6c 6c 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  alled from [sqli
10de0 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20  te3_shutdown()] 
10df0 73 6f 20 69 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f  so it does.** no
10e00 74 20 6e 65 65 64 20 74 6f 20 62 65 20 74 68 72  t need to be thr
10e10 65 61 64 73 61 66 65 20 65 69 74 68 65 72 2e 20  eadsafe either. 
10e20 20 46 6f 72 20 61 6c 6c 20 6f 74 68 65 72 20 6d   For all other m
10e30 65 74 68 6f 64 73 2c 20 53 51 4c 69 74 65 0a 2a  ethods, SQLite.*
10e40 2a 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c  * holds the [SQL
10e50 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43  ITE_MUTEX_STATIC
10e60 5f 4d 45 4d 5d 20 6d 75 74 65 78 20 61 73 20 6c  _MEM] mutex as l
10e70 6f 6e 67 20 61 73 20 74 68 65 0a 2a 2a 20 5b 53  ong as the.** [S
10e80 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d  QLITE_CONFIG_MEM
10e90 53 54 41 54 55 53 5d 20 63 6f 6e 66 69 67 75 72  STATUS] configur
10ea0 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20  ation option is 
10eb0 74 75 72 6e 65 64 20 6f 6e 20 28 77 68 69 63 68  turned on (which
10ec0 0a 2a 2a 20 69 74 20 69 73 20 62 79 20 64 65 66  .** it is by def
10ed0 61 75 6c 74 29 20 61 6e 64 20 73 6f 20 74 68 65  ault) and so the
10ee0 20 6d 65 74 68 6f 64 73 20 61 72 65 20 61 75 74   methods are aut
10ef0 6f 6d 61 74 69 63 61 6c 6c 79 20 73 65 72 69 61  omatically seria
10f00 6c 69 7a 65 64 2e 0a 2a 2a 20 48 6f 77 65 76 65  lized..** Howeve
10f10 72 2c 20 69 66 20 5b 53 51 4c 49 54 45 5f 43 4f  r, if [SQLITE_CO
10f20 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20  NFIG_MEMSTATUS] 
10f30 69 73 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65  is disabled, the
10f40 6e 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 6d  n the other.** m
10f50 65 74 68 6f 64 73 20 6d 75 73 74 20 62 65 20 74  ethods must be t
10f60 68 72 65 61 64 73 61 66 65 20 6f 72 20 65 6c 73  hreadsafe or els
10f70 65 20 6d 61 6b 65 20 74 68 65 69 72 20 6f 77 6e  e make their own
10f80 20 61 72 72 61 6e 67 65 6d 65 6e 74 73 20 66 6f   arrangements fo
10f90 72 0a 2a 2a 20 73 65 72 69 61 6c 69 7a 61 74 69  r.** serializati
10fa0 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  on..**.** SQLite
10fb0 20 77 69 6c 6c 20 6e 65 76 65 72 20 69 6e 76 6f   will never invo
10fc0 6b 65 20 78 49 6e 69 74 28 29 20 6d 6f 72 65 20  ke xInit() more 
10fd0 74 68 61 6e 20 6f 6e 63 65 20 77 69 74 68 6f 75  than once withou
10fe0 74 20 61 6e 20 69 6e 74 65 72 76 65 6e 69 6e 67  t an intervening
10ff0 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 78 53 68 75  .** call to xShu
11000 74 64 6f 77 6e 28 29 2e 0a 2a 2f 0a 74 79 70 65  tdown()..*/.type
11010 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
11020 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 73  e3_mem_methods s
11030 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
11040 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74  ds;.struct sqlit
11050 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 7b  e3_mem_methods {
11060 0a 20 20 76 6f 69 64 20 2a 28 2a 78 4d 61 6c 6c  .  void *(*xMall
11070 6f 63 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20  oc)(int);       
11080 20 20 2f 2a 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f    /* Memory allo
11090 63 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 20  cation function 
110a0 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 46 72 65  */.  void (*xFre
110b0 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20  e)(void*);      
110c0 20 20 20 20 2f 2a 20 46 72 65 65 20 61 20 70 72      /* Free a pr
110d0 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a  ior allocation *
110e0 2f 0a 20 20 76 6f 69 64 20 2a 28 2a 78 52 65 61  /.  void *(*xRea
110f0 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c 69 6e 74 29  lloc)(void*,int)
11100 3b 20 20 2f 2a 20 52 65 73 69 7a 65 20 61 6e 20  ;  /* Resize an 
11110 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20  allocation */.  
11120 69 6e 74 20 28 2a 78 53 69 7a 65 29 28 76 6f 69  int (*xSize)(voi
11130 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f  d*);           /
11140 2a 20 52 65 74 75 72 6e 20 74 68 65 20 73 69 7a  * Return the siz
11150 65 20 6f 66 20 61 6e 20 61 6c 6c 6f 63 61 74 69  e of an allocati
11160 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 52  on */.  int (*xR
11170 6f 75 6e 64 75 70 29 28 69 6e 74 29 3b 20 20 20  oundup)(int);   
11180 20 20 20 20 20 20 20 2f 2a 20 52 6f 75 6e 64 20         /* Round 
11190 75 70 20 72 65 71 75 65 73 74 20 73 69 7a 65 20  up request size 
111a0 74 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69  to allocation si
111b0 7a 65 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 49  ze */.  int (*xI
111c0 6e 69 74 29 28 76 6f 69 64 2a 29 3b 20 20 20 20  nit)(void*);    
111d0 20 20 20 20 20 20 20 2f 2a 20 49 6e 69 74 69 61         /* Initia
111e0 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20  lize the memory 
111f0 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76  allocator */.  v
11200 6f 69 64 20 28 2a 78 53 68 75 74 64 6f 77 6e 29  oid (*xShutdown)
11210 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 2f 2a  (void*);      /*
11220 20 44 65 69 6e 69 74 69 61 6c 69 7a 65 20 74 68   Deinitialize th
11230 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
11240 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41  or */.  void *pA
11250 70 70 44 61 74 61 3b 20 20 20 20 20 20 20 20 20  ppData;         
11260 20 20 20 20 20 20 20 2f 2a 20 41 72 67 75 6d 65         /* Argume
11270 6e 74 20 74 6f 20 78 49 6e 69 74 28 29 20 61 6e  nt to xInit() an
11280 64 20 78 53 68 75 74 64 6f 77 6e 28 29 20 2a 2f  d xShutdown() */
11290 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .};../*.** CAPI3
112a0 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 61 74 69  REF: Configurati
112b0 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 20 4b 45  on Options.** KE
112c0 59 57 4f 52 44 53 3a 20 7b 63 6f 6e 66 69 67 75  YWORDS: {configu
112d0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 7d 0a 2a  ration option}.*
112e0 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74  *.** These const
112f0 61 6e 74 73 20 61 72 65 20 74 68 65 20 61 76 61  ants are the ava
11300 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63  ilable integer c
11310 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
11320 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e  ions that.** can
11330 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68   be passed as th
11340 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
11350 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
11360 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72  _config()] inter
11370 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20  face..**.** New 
11380 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
11390 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64  tions may be add
113a0 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  ed in future rel
113b0 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e  eases of SQLite.
113c0 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e  .** Existing con
113d0 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
113e0 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69 73 63  ns might be disc
113f0 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69  ontinued.  Appli
11400 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c  cations.** shoul
11410 64 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75  d check the retu
11420 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71  rn code from [sq
11430 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
11440 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61  to make sure tha
11450 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f  t.** the call wo
11460 72 6b 65 64 2e 20 20 54 68 65 20 5b 73 71 6c 69  rked.  The [sqli
11470 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e  te3_config()] in
11480 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74  terface will ret
11490 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72  urn a.** non-zer
114a0 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  o [error code] i
114b0 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64  f a discontinued
114c0 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20   or unsupported 
114d0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
114e0 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b  tion.** is invok
114f0 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a  ed..**.** <dl>.*
11500 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
11510 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 5d  G_SINGLETHREAD]]
11520 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
11530 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 3c  IG_SINGLETHREAD<
11540 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72  /dt>.** <dd>Ther
11550 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e  e are no argumen
11560 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f  ts to this optio
11570 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  n.  ^This option
11580 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68   sets the.** [th
11590 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f  reading mode] to
115a0 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 2e 20   Single-thread. 
115b0 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
115c0 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20   it disables.** 
115d0 61 6c 6c 20 6d 75 74 65 78 69 6e 67 20 61 6e 64  all mutexing and
115e0 20 70 75 74 73 20 53 51 4c 69 74 65 20 69 6e 74   puts SQLite int
115f0 6f 20 61 20 6d 6f 64 65 20 77 68 65 72 65 20 69  o a mode where i
11600 74 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 75 73  t can only be us
11610 65 64 0a 2a 2a 20 62 79 20 61 20 73 69 6e 67 6c  ed.** by a singl
11620 65 20 74 68 72 65 61 64 2e 20 20 20 5e 49 66 20  e thread.   ^If 
11630 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
11640 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b  ed with.** the [
11650 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
11660 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41  E | SQLITE_THREA
11670 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65  DSAFE=0] compile
11680 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65  -time option the
11690 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70  n.** it is not p
116a0 6f 73 73 69 62 6c 65 20 74 6f 20 63 68 61 6e 67  ossible to chang
116b0 65 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e 67  e the [threading
116c0 20 6d 6f 64 65 5d 20 66 72 6f 6d 20 69 74 73 20   mode] from its 
116d0 64 65 66 61 75 6c 74 0a 2a 2a 20 76 61 6c 75 65  default.** value
116e0 20 6f 66 20 53 69 6e 67 6c 65 2d 74 68 72 65 61   of Single-threa
116f0 64 20 61 6e 64 20 73 6f 20 5b 73 71 6c 69 74 65  d and so [sqlite
11700 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c  3_config()] will
11710 20 72 65 74 75 72 6e 20 0a 2a 2a 20 5b 53 51 4c   return .** [SQL
11720 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61  ITE_ERROR] if ca
11730 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 53 51  lled with the SQ
11740 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
11750 4c 45 54 48 52 45 41 44 0a 2a 2a 20 63 6f 6e 66  LETHREAD.** conf
11760 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
11770 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  .</dd>.**.** [[S
11780 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c  QLITE_CONFIG_MUL
11790 54 49 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53  TITHREAD]] <dt>S
117a0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c  QLITE_CONFIG_MUL
117b0 54 49 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a  TITHREAD</dt>.**
117c0 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e   <dd>There are n
117d0 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74  o arguments to t
117e0 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68  his option.  ^Th
117f0 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74  is option sets t
11800 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67  he.** [threading
11810 20 6d 6f 64 65 5d 20 74 6f 20 4d 75 6c 74 69 2d   mode] to Multi-
11820 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68 65  thread.  In othe
11830 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73 61  r words, it disa
11840 62 6c 65 73 0a 2a 2a 20 6d 75 74 65 78 69 6e 67  bles.** mutexing
11850 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f   on [database co
11860 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70  nnection] and [p
11870 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
11880 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 54  t] objects..** T
11890 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69  he application i
118a0 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f  s responsible fo
118b0 72 20 73 65 72 69 61 6c 69 7a 69 6e 67 20 61 63  r serializing ac
118c0 63 65 73 73 20 74 6f 0a 2a 2a 20 5b 64 61 74 61  cess to.** [data
118d0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
118e0 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20  ] and [prepared 
118f0 73 74 61 74 65 6d 65 6e 74 73 5d 2e 20 20 42 75  statements].  Bu
11900 74 20 6f 74 68 65 72 20 6d 75 74 65 78 65 73 0a  t other mutexes.
11910 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20 73  ** are enabled s
11920 6f 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69  o that SQLite wi
11930 6c 6c 20 62 65 20 73 61 66 65 20 74 6f 20 75 73  ll be safe to us
11940 65 20 69 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72  e in a multi-thr
11950 65 61 64 65 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e  eaded.** environ
11960 6d 65 6e 74 20 61 73 20 6c 6f 6e 67 20 61 73 20  ment as long as 
11970 6e 6f 20 74 77 6f 20 74 68 72 65 61 64 73 20 61  no two threads a
11980 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68  ttempt to use th
11990 65 20 73 61 6d 65 0a 2a 2a 20 5b 64 61 74 61 62  e same.** [datab
119a0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
119b0 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65  at the same time
119c0 2e 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73  .  ^If SQLite is
119d0 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
119e0 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48  * the [SQLITE_TH
119f0 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54  READSAFE | SQLIT
11a00 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20  E_THREADSAFE=0] 
11a10 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
11a20 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69  ion then.** it i
11a30 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74  s not possible t
11a40 6f 20 73 65 74 20 74 68 65 20 4d 75 6c 74 69 2d  o set the Multi-
11a50 74 68 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e  thread [threadin
11a60 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b  g mode] and.** [
11a70 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
11a80 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53  ] will return [S
11a90 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20  QLITE_ERROR] if 
11aa0 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a  called with the.
11ab0 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ** SQLITE_CONFIG
11ac0 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 63 6f 6e  _MULTITHREAD con
11ad0 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
11ae0 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  n.</dd>.**.** [[
11af0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45  SQLITE_CONFIG_SE
11b00 52 49 41 4c 49 5a 45 44 5d 5d 20 3c 64 74 3e 53  RIALIZED]] <dt>S
11b10 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52  QLITE_CONFIG_SER
11b20 49 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a 2a 2a 20  IALIZED</dt>.** 
11b30 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f  <dd>There are no
11b40 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68   arguments to th
11b50 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69  is option.  ^Thi
11b60 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68  s option sets th
11b70 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20  e.** [threading 
11b80 6d 6f 64 65 5d 20 74 6f 20 53 65 72 69 61 6c 69  mode] to Seriali
11b90 7a 65 64 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f  zed. In other wo
11ba0 72 64 73 2c 20 74 68 69 73 20 6f 70 74 69 6f 6e  rds, this option
11bb0 20 65 6e 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20   enables.** all 
11bc0 6d 75 74 65 78 65 73 20 69 6e 63 6c 75 64 69 6e  mutexes includin
11bd0 67 20 74 68 65 20 72 65 63 75 72 73 69 76 65 0a  g the recursive.
11be0 2a 2a 20 6d 75 74 65 78 65 73 20 6f 6e 20 5b 64  ** mutexes on [d
11bf0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
11c00 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65  on] and [prepare
11c10 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a  d statement] obj
11c20 65 63 74 73 2e 0a 2a 2a 20 49 6e 20 74 68 69 73  ects..** In this
11c30 20 6d 6f 64 65 20 28 77 68 69 63 68 20 69 73 20   mode (which is 
11c40 74 68 65 20 64 65 66 61 75 6c 74 20 77 68 65 6e  the default when
11c50 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
11c60 6c 65 64 20 77 69 74 68 0a 2a 2a 20 5b 53 51 4c  led with.** [SQL
11c70 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31  ITE_THREADSAFE=1
11c80 5d 29 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69  ]) the SQLite li
11c90 62 72 61 72 79 20 77 69 6c 6c 20 69 74 73 65 6c  brary will itsel
11ca0 66 20 73 65 72 69 61 6c 69 7a 65 20 61 63 63 65  f serialize acce
11cb0 73 73 0a 2a 2a 20 74 6f 20 5b 64 61 74 61 62 61  ss.** to [databa
11cc0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20  se connections] 
11cd0 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  and [prepared st
11ce0 61 74 65 6d 65 6e 74 73 5d 20 73 6f 20 74 68 61  atements] so tha
11cf0 74 20 74 68 65 0a 2a 2a 20 61 70 70 6c 69 63 61  t the.** applica
11d00 74 69 6f 6e 20 69 73 20 66 72 65 65 20 74 6f 20  tion is free to 
11d10 75 73 65 20 74 68 65 20 73 61 6d 65 20 5b 64 61  use the same [da
11d20 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
11d30 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a 20 73 61 6d  n] or the.** sam
11d40 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
11d50 65 6d 65 6e 74 5d 20 69 6e 20 64 69 66 66 65 72  ement] in differ
11d60 65 6e 74 20 74 68 72 65 61 64 73 20 61 74 20 74  ent threads at t
11d70 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 0a 2a 2a  he same time..**
11d80 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63   ^If SQLite is c
11d90 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
11da0 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
11db0 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f  ADSAFE | SQLITE_
11dc0 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f  THREADSAFE=0] co
11dd0 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
11de0 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20  n then.** it is 
11df0 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20  not possible to 
11e00 73 65 74 20 74 68 65 20 53 65 72 69 61 6c 69 7a  set the Serializ
11e10 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ed [threading mo
11e20 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  de] and.** [sqli
11e30 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69  te3_config()] wi
11e40 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ll return [SQLIT
11e50 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c  E_ERROR] if call
11e60 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53  ed with the.** S
11e70 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52  QLITE_CONFIG_SER
11e80 49 41 4c 49 5a 45 44 20 63 6f 6e 66 69 67 75 72  IALIZED configur
11e90 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64  ation option.</d
11ea0 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
11eb0 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d  E_CONFIG_MALLOC]
11ec0 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
11ed0 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a  FIG_MALLOC</dt>.
11ee0 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f  ** <dd> ^(This o
11ef0 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
11f00 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
11f10 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ich is a pointer
11f20 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e   to an.** instan
11f30 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ce of the [sqlit
11f40 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20  e3_mem_methods] 
11f50 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 20  structure.  The 
11f60 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69  argument specifi
11f70 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76  es.** alternativ
11f80 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f  e low-level memo
11f90 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f  ry allocation ro
11fa0 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65  utines to be use
11fb0 64 20 69 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a  d in place of.**
11fc0 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   the memory allo
11fd0 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20  cation routines 
11fe0 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74  built into SQLit
11ff0 65 2e 29 5e 20 5e 53 51 4c 69 74 65 20 6d 61 6b  e.)^ ^SQLite mak
12000 65 73 0a 2a 2a 20 69 74 73 20 6f 77 6e 20 70 72  es.** its own pr
12010 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68  ivate copy of th
12020 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65  e content of the
12030 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65   [sqlite3_mem_me
12040 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65  thods] structure
12050 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68 65 20 5b  .** before the [
12060 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
12070 5d 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e 3c  ] call returns.<
12080 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
12090 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41  ITE_CONFIG_GETMA
120a0 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  LLOC]] <dt>SQLIT
120b0 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c  E_CONFIG_GETMALL
120c0 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  OC</dt>.** <dd> 
120d0 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61  ^(This option ta
120e0 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
120f0 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61  ument which is a
12100 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a   pointer to an.*
12110 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  * instance of th
12120 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  e [sqlite3_mem_m
12130 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72  ethods] structur
12140 65 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33  e.  The [sqlite3
12150 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a  _mem_methods].**
12160 20 73 74 72 75 63 74 75 72 65 20 69 73 20 66 69   structure is fi
12170 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 63 75  lled with the cu
12180 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20  rrently defined 
12190 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
121a0 6e 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a  n routines.)^.**
121b0 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e   This option can
121c0 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72   be used to over
121d0 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c 74  load the default
121e0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
121f0 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77  on.** routines w
12200 69 74 68 20 61 20 77 72 61 70 70 65 72 20 74 68  ith a wrapper th
12210 61 74 20 73 69 6d 75 6c 61 74 69 6f 6e 73 20 6d  at simulations m
12220 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
12230 20 66 61 69 6c 75 72 65 20 6f 72 0a 2a 2a 20 74   failure or.** t
12240 72 61 63 6b 73 20 6d 65 6d 6f 72 79 20 75 73 61  racks memory usa
12250 67 65 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e  ge, for example.
12260 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53   </dd>.**.** [[S
12270 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d  QLITE_CONFIG_MEM
12280 53 54 41 54 55 53 5d 5d 20 3c 64 74 3e 53 51 4c  STATUS]] <dt>SQL
12290 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54  ITE_CONFIG_MEMST
122a0 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  ATUS</dt>.** <dd
122b0 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74  > ^This option t
122c0 61 6b 65 73 20 73 69 6e 67 6c 65 20 61 72 67 75  akes single argu
122d0 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e 74  ment of type int
122e0 2c 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  , interpreted as
122f0 20 61 20 0a 2a 2a 20 62 6f 6f 6c 65 61 6e 2c 20   a .** boolean, 
12300 77 68 69 63 68 20 65 6e 61 62 6c 65 73 20 6f 72  which enables or
12310 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 63 6f   disables the co
12320 6c 6c 65 63 74 69 6f 6e 20 6f 66 20 6d 65 6d 6f  llection of memo
12330 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 0a 2a  ry allocation .*
12340 2a 20 73 74 61 74 69 73 74 69 63 73 2e 20 5e 28  * statistics. ^(
12350 57 68 65 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  When memory allo
12360 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63  cation statistic
12370 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 2c 20  s are disabled, 
12380 74 68 65 20 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e  the .** followin
12390 67 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  g SQLite interfa
123a0 63 65 73 20 62 65 63 6f 6d 65 20 6e 6f 6e 2d 6f  ces become non-o
123b0 70 65 72 61 74 69 6f 6e 61 6c 3a 0a 2a 2a 20 20  perational:.**  
123c0 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20   <ul>.**   <li> 
123d0 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
123e0 75 73 65 64 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69  used()].**   <li
123f0 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  > [sqlite3_memor
12400 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 0a 2a  y_highwater()].*
12410 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65  *   <li> [sqlite
12420 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69  3_soft_heap_limi
12430 74 36 34 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e  t64()].**   <li>
12440 20 5b 73 71 6c 69 74 65 33 5f 73 74 61 74 75 73   [sqlite3_status
12450 28 29 5d 0a 2a 2a 20 20 20 3c 2f 75 6c 3e 29 5e  ()].**   </ul>)^
12460 0a 2a 2a 20 5e 4d 65 6d 6f 72 79 20 61 6c 6c 6f  .** ^Memory allo
12470 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63  cation statistic
12480 73 20 61 72 65 20 65 6e 61 62 6c 65 64 20 62 79  s are enabled by
12490 20 64 65 66 61 75 6c 74 20 75 6e 6c 65 73 73 20   default unless 
124a0 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 63 6f 6d  SQLite is.** com
124b0 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c 49  piled with [SQLI
124c0 54 45 5f 44 45 46 41 55 4c 54 5f 4d 45 4d 53 54  TE_DEFAULT_MEMST
124d0 41 54 55 53 5d 3d 30 20 69 6e 20 77 68 69 63 68  ATUS]=0 in which
124e0 20 63 61 73 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20   case memory.** 
124f0 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69  allocation stati
12500 73 74 69 63 73 20 61 72 65 20 64 69 73 61 62 6c  stics are disabl
12510 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a  ed by default..*
12520 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  * </dd>.**.** [[
12530 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43  SQLITE_CONFIG_SC
12540 52 41 54 43 48 5d 5d 20 3c 64 74 3e 53 51 4c 49  RATCH]] <dt>SQLI
12550 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43  TE_CONFIG_SCRATC
12560 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  H</dt>.** <dd> ^
12570 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63  This option spec
12580 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d  ifies a static m
12590 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68 61  emory buffer tha
125a0 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65  t SQLite can use
125b0 20 66 6f 72 0a 2a 2a 20 73 63 72 61 74 63 68 20   for.** scratch 
125c0 6d 65 6d 6f 72 79 2e 20 20 54 68 65 72 65 20 61  memory.  There a
125d0 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e  re three argumen
125e0 74 73 3a 20 20 41 20 70 6f 69 6e 74 65 72 20 61  ts:  A pointer a
125f0 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 61 6c 69 67  n 8-byte.** alig
12600 6e 65 64 20 6d 65 6d 6f 72 79 20 62 75 66 66 65  ned memory buffe
12610 72 20 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65  r from which the
12620 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74   scratch allocat
12630 69 6f 6e 73 20 77 69 6c 6c 20 62 65 0a 2a 2a 20  ions will be.** 
12640 64 72 61 77 6e 2c 20 74 68 65 20 73 69 7a 65 20  drawn, the size 
12650 6f 66 20 65 61 63 68 20 73 63 72 61 74 63 68 20  of each scratch 
12660 61 6c 6c 6f 63 61 74 69 6f 6e 20 28 73 7a 29 2c  allocation (sz),
12670 0a 2a 2a 20 61 6e 64 20 74 68 65 20 6d 61 78 69  .** and the maxi
12680 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 73 63  mum number of sc
12690 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e  ratch allocation
126a0 73 20 28 4e 29 2e 20 20 54 68 65 20 73 7a 0a 2a  s (N).  The sz.*
126b0 2a 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20  * argument must 
126c0 62 65 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66  be a multiple of
126d0 20 31 36 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73   16..** The firs
126e0 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20  t argument must 
126f0 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  be a pointer to 
12700 61 6e 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65  an 8-byte aligne
12710 64 20 62 75 66 66 65 72 0a 2a 2a 20 6f 66 20 61  d buffer.** of a
12720 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74  t least sz*N byt
12730 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a  es of memory..**
12740 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73   ^SQLite will us
12750 65 20 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 20 74  e no more than t
12760 77 6f 20 73 63 72 61 74 63 68 20 62 75 66 66 65  wo scratch buffe
12770 72 73 20 70 65 72 20 74 68 72 65 61 64 2e 20 20  rs per thread.  
12780 53 6f 0a 2a 2a 20 4e 20 73 68 6f 75 6c 64 20 62  So.** N should b
12790 65 20 73 65 74 20 74 6f 20 74 77 69 63 65 20 74  e set to twice t
127a0 68 65 20 65 78 70 65 63 74 65 64 20 6d 61 78 69  he expected maxi
127b0 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 68  mum number of th
127c0 72 65 61 64 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74  reads..** ^SQLit
127d0 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 72 65 71  e will never req
127e0 75 69 72 65 20 61 20 73 63 72 61 74 63 68 20 62  uire a scratch b
127f0 75 66 66 65 72 20 74 68 61 74 20 69 73 20 6d 6f  uffer that is mo
12800 72 65 20 74 68 61 6e 20 36 0a 2a 2a 20 74 69 6d  re than 6.** tim
12810 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  es the database 
12820 70 61 67 65 20 73 69 7a 65 2e 20 5e 49 66 20 53  page size. ^If S
12830 51 4c 69 74 65 20 6e 65 65 64 73 20 6e 65 65 64  QLite needs need
12840 73 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  s additional.** 
12850 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 20 62  scratch memory b
12860 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72  eyond what is pr
12870 6f 76 69 64 65 64 20 62 79 20 74 68 69 73 20 63  ovided by this c
12880 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
12890 69 6f 6e 2c 20 74 68 65 6e 20 0a 2a 2a 20 5b 73  ion, then .** [s
128a0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
128b0 20 77 69 6c 6c 20 62 65 20 75 73 65 64 20 74 6f   will be used to
128c0 20 6f 62 74 61 69 6e 20 74 68 65 20 6d 65 6d 6f   obtain the memo
128d0 72 79 20 6e 65 65 64 65 64 2e 3c 2f 64 64 3e 0a  ry needed.</dd>.
128e0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
128f0 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d  ONFIG_PAGECACHE]
12900 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
12910 46 49 47 5f 50 41 47 45 43 41 43 48 45 3c 2f 64  FIG_PAGECACHE</d
12920 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73  t>.** <dd> ^This
12930 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65   option specifie
12940 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72  s a static memor
12950 79 20 62 75 66 66 65 72 20 74 68 61 74 20 53 51  y buffer that SQ
12960 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72  Lite can use for
12970 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65  .** the database
12980 20 70 61 67 65 20 63 61 63 68 65 20 77 69 74 68   page cache with
12990 20 74 68 65 20 64 65 66 61 75 6c 74 20 70 61 67   the default pag
129a0 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e  e cache implemen
129b0 74 61 74 69 6f 6e 2e 20 20 0a 2a 2a 20 54 68 69  tation.  .** Thi
129c0 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  s configuration 
129d0 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75 73  should not be us
129e0 65 64 20 69 66 20 61 6e 20 61 70 70 6c 69 63 61  ed if an applica
129f0 74 69 6f 6e 2d 64 65 66 69 6e 65 20 70 61 67 65  tion-define page
12a00 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70 6c 65 6d  .** cache implem
12a10 65 6e 74 61 74 69 6f 6e 20 69 73 20 6c 6f 61 64  entation is load
12a20 65 64 20 75 73 69 6e 67 20 74 68 65 20 53 51 4c  ed using the SQL
12a30 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48  ITE_CONFIG_PCACH
12a40 45 32 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 54 68  E2 option..** Th
12a50 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72  ere are three ar
12a60 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20  guments to this 
12a70 6f 70 74 69 6f 6e 3a 20 41 20 70 6f 69 6e 74 65  option: A pointe
12a80 72 20 74 6f 20 38 2d 62 79 74 65 20 61 6c 69 67  r to 8-byte alig
12a90 6e 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 74  ned.** memory, t
12aa0 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20  he size of each 
12ab0 70 61 67 65 20 62 75 66 66 65 72 20 28 73 7a 29  page buffer (sz)
12ac0 2c 20 61 6e 64 20 74 68 65 20 6e 75 6d 62 65 72  , and the number
12ad0 20 6f 66 20 70 61 67 65 73 20 28 4e 29 2e 0a 2a   of pages (N)..*
12ae0 2a 20 54 68 65 20 73 7a 20 61 72 67 75 6d 65 6e  * The sz argumen
12af0 74 20 73 68 6f 75 6c 64 20 62 65 20 74 68 65 20  t should be the 
12b00 73 69 7a 65 20 6f 66 20 74 68 65 20 6c 61 72 67  size of the larg
12b10 65 73 74 20 64 61 74 61 62 61 73 65 20 70 61 67  est database pag
12b20 65 0a 2a 2a 20 28 61 20 70 6f 77 65 72 20 6f 66  e.** (a power of
12b30 20 74 77 6f 20 62 65 74 77 65 65 6e 20 35 31 32   two between 512
12b40 20 61 6e 64 20 33 32 37 36 38 29 20 70 6c 75 73   and 32768) plus
12b50 20 61 20 6c 69 74 74 6c 65 20 65 78 74 72 61 20   a little extra 
12b60 66 6f 72 20 65 61 63 68 0a 2a 2a 20 70 61 67 65  for each.** page
12b70 20 68 65 61 64 65 72 2e 20 20 5e 54 68 65 20 70   header.  ^The p
12b80 61 67 65 20 68 65 61 64 65 72 20 73 69 7a 65 20  age header size 
12b90 69 73 20 32 30 20 74 6f 20 34 30 20 62 79 74 65  is 20 to 40 byte
12ba0 73 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 0a 2a  s depending on.*
12bb0 2a 20 74 68 65 20 68 6f 73 74 20 61 72 63 68 69  * the host archi
12bc0 74 65 63 74 75 72 65 2e 20 20 5e 49 74 20 69 73  tecture.  ^It is
12bd0 20 68 61 72 6d 6c 65 73 73 2c 20 61 70 61 72 74   harmless, apart
12be0 20 66 72 6f 6d 20 74 68 65 20 77 61 73 74 65 64   from the wasted
12bf0 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74 6f 20 6d   memory,.** to m
12c00 61 6b 65 20 73 7a 20 61 20 6c 69 74 74 6c 65 20  ake sz a little 
12c10 74 6f 6f 20 6c 61 72 67 65 2e 20 20 54 68 65 20  too large.  The 
12c20 66 69 72 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e  first.** argumen
12c30 74 20 73 68 6f 75 6c 64 20 70 6f 69 6e 74 20 74  t should point t
12c40 6f 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  o an allocation 
12c50 6f 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e  of at least sz*N
12c60 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79   bytes of memory
12c70 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c  ..** ^SQLite wil
12c80 6c 20 75 73 65 20 74 68 65 20 6d 65 6d 6f 72 79  l use the memory
12c90 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 65   provided by the
12ca0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
12cb0 74 6f 20 73 61 74 69 73 66 79 20 69 74 73 0a 2a  to satisfy its.*
12cc0 2a 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 20 66  * memory needs f
12cd0 6f 72 20 74 68 65 20 66 69 72 73 74 20 4e 20 70  or the first N p
12ce0 61 67 65 73 20 74 68 61 74 20 69 74 20 61 64 64  ages that it add
12cf0 73 20 74 6f 20 63 61 63 68 65 2e 20 20 5e 49 66  s to cache.  ^If
12d00 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 70   additional.** p
12d10 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79  age cache memory
12d20 20 69 73 20 6e 65 65 64 65 64 20 62 65 79 6f 6e   is needed beyon
12d30 64 20 77 68 61 74 20 69 73 20 70 72 6f 76 69 64  d what is provid
12d40 65 64 20 62 79 20 74 68 69 73 20 6f 70 74 69 6f  ed by this optio
12d50 6e 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74  n, then.** SQLit
12d60 65 20 67 6f 65 73 20 74 6f 20 5b 73 71 6c 69 74  e goes to [sqlit
12d70 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 66 6f 72  e3_malloc()] for
12d80 20 74 68 65 20 61 64 64 69 74 69 6f 6e 61 6c 20   the additional 
12d90 73 74 6f 72 61 67 65 20 73 70 61 63 65 2e 0a 2a  storage space..*
12da0 2a 20 54 68 65 20 70 6f 69 6e 74 65 72 20 69 6e  * The pointer in
12db0 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
12dc0 65 6e 74 20 6d 75 73 74 0a 2a 2a 20 62 65 20 61  ent must.** be a
12dd0 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62  ligned to an 8-b
12de0 79 74 65 20 62 6f 75 6e 64 61 72 79 20 6f 72 20  yte boundary or 
12df0 73 75 62 73 65 71 75 65 6e 74 20 62 65 68 61 76  subsequent behav
12e00 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a  ior of SQLite.**
12e10 20 77 69 6c 6c 20 62 65 20 75 6e 64 65 66 69 6e   will be undefin
12e20 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  ed.</dd>.**.** [
12e30 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48  [SQLITE_CONFIG_H
12e40 45 41 50 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  EAP]] <dt>SQLITE
12e50 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3c 2f 64 74  _CONFIG_HEAP</dt
12e60 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20  >.** <dd> ^This 
12e70 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73  option specifies
12e80 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79   a static memory
12e90 20 62 75 66 66 65 72 20 74 68 61 74 20 53 51 4c   buffer that SQL
12ea0 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20  ite will use.** 
12eb0 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 64  for all of its d
12ec0 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 61 6c  ynamic memory al
12ed0 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 20 62  location needs b
12ee0 65 79 6f 6e 64 20 74 68 6f 73 65 20 70 72 6f 76  eyond those prov
12ef0 69 64 65 64 0a 2a 2a 20 66 6f 72 20 62 79 20 5b  ided.** for by [
12f00 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43  SQLITE_CONFIG_SC
12f10 52 41 54 43 48 5d 20 61 6e 64 20 5b 53 51 4c 49  RATCH] and [SQLI
12f20 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41  TE_CONFIG_PAGECA
12f30 43 48 45 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 61  CHE]..** There a
12f40 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e  re three argumen
12f50 74 73 3a 20 41 6e 20 38 2d 62 79 74 65 20 61 6c  ts: An 8-byte al
12f60 69 67 6e 65 64 20 70 6f 69 6e 74 65 72 20 74 6f  igned pointer to
12f70 20 74 68 65 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20   the memory,.** 
12f80 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
12f90 74 65 73 20 69 6e 20 74 68 65 20 6d 65 6d 6f 72  tes in the memor
12fa0 79 20 62 75 66 66 65 72 2c 20 61 6e 64 20 74 68  y buffer, and th
12fb0 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61  e minimum alloca
12fc0 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49  tion size..** ^I
12fd0 66 20 74 68 65 20 66 69 72 73 74 20 70 6f 69 6e  f the first poin
12fe0 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20  ter (the memory 
12ff0 70 6f 69 6e 74 65 72 29 20 69 73 20 4e 55 4c 4c  pointer) is NULL
13000 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 72 65  , then SQLite re
13010 76 65 72 74 73 0a 2a 2a 20 74 6f 20 75 73 69 6e  verts.** to usin
13020 67 20 69 74 73 20 64 65 66 61 75 6c 74 20 6d 65  g its default me
13030 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 28  mory allocator (
13040 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f  the system mallo
13050 63 28 29 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  c() implementati
13060 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f 69 6e 67 20  on),.** undoing 
13070 61 6e 79 20 70 72 69 6f 72 20 69 6e 76 6f 63 61  any prior invoca
13080 74 69 6f 6e 20 6f 66 20 5b 53 51 4c 49 54 45 5f  tion of [SQLITE_
13090 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 2e 20  CONFIG_MALLOC]. 
130a0 20 5e 49 66 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f   ^If the.** memo
130b0 72 79 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f  ry pointer is no
130c0 74 20 4e 55 4c 4c 20 61 6e 64 20 65 69 74 68 65  t NULL and eithe
130d0 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  r [SQLITE_ENABLE
130e0 5f 4d 45 4d 53 59 53 33 5d 20 6f 72 0a 2a 2a 20  _MEMSYS3] or.** 
130f0 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d  [SQLITE_ENABLE_M
13100 45 4d 53 59 53 35 5d 20 61 72 65 20 64 65 66 69  EMSYS5] are defi
13110 6e 65 64 2c 20 74 68 65 6e 20 74 68 65 20 61 6c  ned, then the al
13120 74 65 72 6e 61 74 69 76 65 20 6d 65 6d 6f 72 79  ternative memory
13130 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 20 69 73  .** allocator is
13140 20 65 6e 67 61 67 65 64 20 74 6f 20 68 61 6e 64   engaged to hand
13150 6c 65 20 61 6c 6c 20 6f 66 20 53 51 4c 69 74 65  le all of SQLite
13160 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  s memory allocat
13170 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a 2a 20 54 68  ion needs..** Th
13180 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20  e first pointer 
13190 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e  (the memory poin
131a0 74 65 72 29 20 6d 75 73 74 20 62 65 20 61 6c 69  ter) must be ali
131b0 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74  gned to an 8-byt
131c0 65 0a 2a 2a 20 62 6f 75 6e 64 61 72 79 20 6f 72  e.** boundary or
131d0 20 73 75 62 73 65 71 75 65 6e 74 20 62 65 68 61   subsequent beha
131e0 76 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 20 77  vior of SQLite w
131f0 69 6c 6c 20 62 65 20 75 6e 64 65 66 69 6e 65 64  ill be undefined
13200 2e 0a 2a 2a 20 54 68 65 20 6d 69 6e 69 6d 75 6d  ..** The minimum
13210 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65   allocation size
13220 20 69 73 20 63 61 70 70 65 64 20 61 74 20 32 2a   is capped at 2*
13230 2a 31 32 2e 20 52 65 61 73 6f 6e 61 62 6c 65 20  *12. Reasonable 
13240 76 61 6c 75 65 73 0a 2a 2a 20 66 6f 72 20 74 68  values.** for th
13250 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61  e minimum alloca
13260 74 69 6f 6e 20 73 69 7a 65 20 61 72 65 20 32 2a  tion size are 2*
13270 2a 35 20 74 68 72 6f 75 67 68 20 32 2a 2a 38 2e  *5 through 2**8.
13280 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
13290 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45  LITE_CONFIG_MUTE
132a0 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  X]] <dt>SQLITE_C
132b0 4f 4e 46 49 47 5f 4d 55 54 45 58 3c 2f 64 74 3e  ONFIG_MUTEX</dt>
132c0 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20  .** <dd> ^(This 
132d0 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
132e0 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77  ingle argument w
132f0 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65  hich is a pointe
13300 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61  r to an.** insta
13310 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  nce of the [sqli
13320 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64  te3_mutex_method
13330 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54  s] structure.  T
13340 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63  he argument spec
13350 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61  ifies.** alterna
13360 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d  tive low-level m
13370 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20 74 6f  utex routines to
13380 20 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61 63   be used in plac
13390 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 20 72  e.** the mutex r
133a0 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e  outines built in
133b0 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 20 5e 53  to SQLite.)^  ^S
133c0 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f  QLite makes a co
133d0 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6e  py of the.** con
133e0 74 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c  tent of the [sql
133f0 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
13400 64 73 5d 20 73 74 72 75 63 74 75 72 65 20 62 65  ds] structure be
13410 66 6f 72 65 20 74 68 65 20 63 61 6c 6c 20 74 6f  fore the call to
13420 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
13430 66 69 67 28 29 5d 20 72 65 74 75 72 6e 73 2e 20  fig()] returns. 
13440 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f  ^If SQLite is co
13450 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74  mpiled with.** t
13460 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  he [SQLITE_THREA
13470 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54  DSAFE | SQLITE_T
13480 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d  HREADSAFE=0] com
13490 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
134a0 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74   then.** the ent
134b0 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62  ire mutexing sub
134c0 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65  system is omitte
134d0 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64  d from the build
134e0 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73   and hence calls
134f0 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
13500 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74  config()] with t
13510 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
13520 5f 4d 55 54 45 58 20 63 6f 6e 66 69 67 75 72 61  _MUTEX configura
13530 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c  tion option will
13540 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  .** return [SQLI
13550 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a  TE_ERROR].</dd>.
13560 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
13570 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 5d 5d  ONFIG_GETMUTEX]]
13580 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
13590 49 47 5f 47 45 54 4d 55 54 45 58 3c 2f 64 74 3e  IG_GETMUTEX</dt>
135a0 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20  .** <dd> ^(This 
135b0 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
135c0 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77  ingle argument w
135d0 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65  hich is a pointe
135e0 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61  r to an.** insta
135f0 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  nce of the [sqli
13600 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64  te3_mutex_method
13610 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54  s] structure.  T
13620 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  he.** [sqlite3_m
13630 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a  utex_methods].**
13640 20 73 74 72 75 63 74 75 72 65 20 69 73 20 66 69   structure is fi
13650 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 63 75  lled with the cu
13660 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20  rrently defined 
13670 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 2e 29  mutex routines.)
13680 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e  ^.** This option
13690 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
136a0 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66  overload the def
136b0 61 75 6c 74 20 6d 75 74 65 78 20 61 6c 6c 6f 63  ault mutex alloc
136c0 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65  ation.** routine
136d0 73 20 77 69 74 68 20 61 20 77 72 61 70 70 65 72  s with a wrapper
136e0 20 75 73 65 64 20 74 6f 20 74 72 61 63 6b 20 6d   used to track m
136f0 75 74 65 78 20 75 73 61 67 65 20 66 6f 72 20 70  utex usage for p
13700 65 72 66 6f 72 6d 61 6e 63 65 0a 2a 2a 20 70 72  erformance.** pr
13710 6f 66 69 6c 69 6e 67 20 6f 72 20 74 65 73 74 69  ofiling or testi
13720 6e 67 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e  ng, for example.
13730 20 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73     ^If SQLite is
13740 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
13750 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48  * the [SQLITE_TH
13760 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54  READSAFE | SQLIT
13770 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20  E_THREADSAFE=0] 
13780 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
13790 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20  ion then.** the 
137a0 65 6e 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20  entire mutexing 
137b0 73 75 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69  subsystem is omi
137c0 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75  tted from the bu
137d0 69 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61  ild and hence ca
137e0 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  lls to.** [sqlit
137f0 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74  e3_config()] wit
13800 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  h the SQLITE_CON
13810 46 49 47 5f 47 45 54 4d 55 54 45 58 20 63 6f 6e  FIG_GETMUTEX con
13820 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
13830 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e  n will.** return
13840 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e   [SQLITE_ERROR].
13850 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
13860 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  LITE_CONFIG_LOOK
13870 41 53 49 44 45 5d 5d 20 3c 64 74 3e 53 51 4c 49  ASIDE]] <dt>SQLI
13880 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  TE_CONFIG_LOOKAS
13890 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  IDE</dt>.** <dd>
138a0 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74   ^(This option t
138b0 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e  akes two argumen
138c0 74 73 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e  ts that determin
138d0 65 20 74 68 65 20 64 65 66 61 75 6c 74 0a 2a 2a  e the default.**
138e0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
138f0 6f 6e 20 66 6f 72 20 74 68 65 20 6c 6f 6f 6b 61  on for the looka
13900 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  side memory allo
13910 63 61 74 6f 72 20 6f 6e 20 65 61 63 68 0a 2a 2a  cator on each.**
13920 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
13930 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20 66 69 72  ction].  The fir
13940 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  st argument is t
13950 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61  he.** size of ea
13960 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66  ch lookaside buf
13970 66 65 72 20 73 6c 6f 74 20 61 6e 64 20 74 68 65  fer slot and the
13980 20 73 65 63 6f 6e 64 20 69 73 20 74 68 65 20 6e   second is the n
13990 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74  umber of.** slot
139a0 73 20 61 6c 6c 6f 63 61 74 65 64 20 74 6f 20 65  s allocated to e
139b0 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ach database con
139c0 6e 65 63 74 69 6f 6e 2e 29 5e 20 20 5e 28 54 68  nection.)^  ^(Th
139d0 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74  is option sets t
139e0 68 65 0a 2a 2a 20 3c 69 3e 64 65 66 61 75 6c 74  he.** <i>default
139f0 3c 2f 69 3e 20 6c 6f 6f 6b 61 73 69 64 65 20 73  </i> lookaside s
13a00 69 7a 65 2e 20 54 68 65 20 5b 53 51 4c 49 54 45  ize. The [SQLITE
13a10 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  _DBCONFIG_LOOKAS
13a20 49 44 45 5d 0a 2a 2a 20 76 65 72 62 20 74 6f 20  IDE].** verb to 
13a30 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66  [sqlite3_db_conf
13a40 69 67 28 29 5d 20 63 61 6e 20 62 65 20 75 73 65  ig()] can be use
13a50 64 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20  d to change the 
13a60 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 63 6f 6e  lookaside.** con
13a70 66 69 67 75 72 61 74 69 6f 6e 20 6f 6e 20 69 6e  figuration on in
13a80 64 69 76 69 64 75 61 6c 20 63 6f 6e 6e 65 63 74  dividual connect
13a90 69 6f 6e 73 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a  ions.)^ </dd>.**
13aa0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
13ab0 46 49 47 5f 50 43 41 43 48 45 32 5d 5d 20 3c 64  FIG_PCACHE2]] <d
13ac0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
13ad0 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20  PCACHE2</dt>.** 
13ae0 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69  <dd> ^(This opti
13af0 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
13b00 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
13b10 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
13b20 0a 2a 2a 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f  .** an [sqlite3_
13b30 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d  pcache_methods2]
13b40 20 6f 62 6a 65 63 74 2e 20 20 54 68 69 73 20 6f   object.  This o
13b50 62 6a 65 63 74 20 73 70 65 63 69 66 69 65 73 20  bject specifies 
13b60 74 68 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  the interface.**
13b70 20 74 6f 20 61 20 63 75 73 74 6f 6d 20 70 61 67   to a custom pag
13b80 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e  e cache implemen
13b90 74 61 74 69 6f 6e 2e 29 5e 20 20 5e 53 51 4c 69  tation.)^  ^SQLi
13ba0 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20  te makes a copy 
13bb0 6f 66 20 74 68 65 0a 2a 2a 20 6f 62 6a 65 63 74  of the.** object
13bc0 20 61 6e 64 20 75 73 65 73 20 69 74 20 66 6f 72   and uses it for
13bd0 20 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f   page cache memo
13be0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 3c  ry allocations.<
13bf0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
13c00 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43  ITE_CONFIG_GETPC
13c10 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53 51 4c 49  ACHE2]] <dt>SQLI
13c20 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41  TE_CONFIG_GETPCA
13c30 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  CHE2</dt>.** <dd
13c40 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20  > ^(This option 
13c50 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
13c60 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
13c70 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
13c80 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 63 61  .** [sqlite3_pca
13c90 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62  che_methods2] ob
13ca0 6a 65 63 74 2e 20 20 53 51 4c 69 74 65 20 63 6f  ject.  SQLite co
13cb0 70 69 65 73 20 6f 66 20 74 68 65 20 63 75 72 72  pies of the curr
13cc0 65 6e 74 0a 2a 2a 20 70 61 67 65 20 63 61 63 68  ent.** page cach
13cd0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
13ce0 20 69 6e 74 6f 20 74 68 61 74 20 6f 62 6a 65 63   into that objec
13cf0 74 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  t.)^ </dd>.**.**
13d00 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
13d10 5f 4c 4f 47 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  _LOG]] <dt>SQLIT
13d20 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 3c 2f 64 74  E_CONFIG_LOG</dt
13d30 3e 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 20 53 51  >.** <dd> The SQ
13d40 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20  LITE_CONFIG_LOG 
13d50 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74  option is used t
13d60 6f 20 63 6f 6e 66 69 67 75 72 65 20 74 68 65 20  o configure the 
13d70 53 51 4c 69 74 65 0a 2a 2a 20 67 6c 6f 62 61 6c  SQLite.** global
13d80 20 5b 65 72 72 6f 72 20 6c 6f 67 5d 2e 0a 2a 2a   [error log]..**
13d90 20 28 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f   (^The SQLITE_CO
13da0 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20  NFIG_LOG option 
13db0 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65  takes two argume
13dc0 6e 74 73 3a 20 61 20 70 6f 69 6e 74 65 72 20 74  nts: a pointer t
13dd0 6f 20 61 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  o a.** function 
13de0 77 69 74 68 20 61 20 63 61 6c 6c 20 73 69 67 6e  with a call sign
13df0 61 74 75 72 65 20 6f 66 20 76 6f 69 64 28 2a 29  ature of void(*)
13e00 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74  (void*,int,const
13e10 20 63 68 61 72 2a 29 2c 20 0a 2a 2a 20 61 6e 64   char*), .** and
13e20 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 76 6f   a pointer to vo
13e30 69 64 2e 20 5e 49 66 20 74 68 65 20 66 75 6e 63  id. ^If the func
13e40 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20  tion pointer is 
13e50 6e 6f 74 20 4e 55 4c 4c 2c 20 69 74 20 69 73 0a  not NULL, it is.
13e60 2a 2a 20 69 6e 76 6f 6b 65 64 20 62 79 20 5b 73  ** invoked by [s
13e70 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 74 6f  qlite3_log()] to
13e80 20 70 72 6f 63 65 73 73 20 65 61 63 68 20 6c 6f   process each lo
13e90 67 67 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49  gging event.  ^I
13ea0 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f  f the.** functio
13eb0 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 4e 55 4c  n pointer is NUL
13ec0 4c 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  L, the [sqlite3_
13ed0 6c 6f 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65  log()] interface
13ee0 20 62 65 63 6f 6d 65 73 20 61 20 6e 6f 2d 6f 70   becomes a no-op
13ef0 2e 0a 2a 2a 20 5e 54 68 65 20 76 6f 69 64 20 70  ..** ^The void p
13f00 6f 69 6e 74 65 72 20 74 68 61 74 20 69 73 20 74  ointer that is t
13f10 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
13f20 6e 74 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e  nt to SQLITE_CON
13f30 46 49 47 5f 4c 4f 47 20 69 73 0a 2a 2a 20 70 61  FIG_LOG is.** pa
13f40 73 73 65 64 20 74 68 72 6f 75 67 68 20 61 73 20  ssed through as 
13f50 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
13f60 74 65 72 20 74 6f 20 74 68 65 20 61 70 70 6c 69  ter to the appli
13f70 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c  cation-defined l
13f80 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f  ogger.** functio
13f90 6e 20 77 68 65 6e 65 76 65 72 20 74 68 61 74 20  n whenever that 
13fa0 66 75 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f  function is invo
13fb0 6b 65 64 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e  ked.  ^The secon
13fc0 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  d parameter to.*
13fd0 2a 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e  * the logger fun
13fe0 63 74 69 6f 6e 20 69 73 20 61 20 63 6f 70 79 20  ction is a copy 
13ff0 6f 66 20 74 68 65 20 66 69 72 73 74 20 70 61 72  of the first par
14000 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 6f  ameter to the co
14010 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 5b  rresponding.** [
14020 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 63  sqlite3_log()] c
14030 61 6c 6c 20 61 6e 64 20 69 73 20 69 6e 74 65 6e  all and is inten
14040 64 65 64 20 74 6f 20 62 65 20 61 20 5b 72 65 73  ded to be a [res
14050 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20 61 6e 0a  ult code] or an.
14060 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  ** [extended res
14070 75 6c 74 20 63 6f 64 65 5d 2e 20 20 5e 54 68 65  ult code].  ^The
14080 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
14090 20 70 61 73 73 65 64 20 74 6f 20 74 68 65 20 6c   passed to the l
140a0 6f 67 67 65 72 20 69 73 0a 2a 2a 20 6c 6f 67 20  ogger is.** log 
140b0 6d 65 73 73 61 67 65 20 61 66 74 65 72 20 66 6f  message after fo
140c0 72 6d 61 74 74 69 6e 67 20 76 69 61 20 5b 73 71  rmatting via [sq
140d0 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
140e0 5d 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65  ]..** The SQLite
140f0 20 6c 6f 67 67 69 6e 67 20 69 6e 74 65 72 66 61   logging interfa
14100 63 65 20 69 73 20 6e 6f 74 20 72 65 65 6e 74 72  ce is not reentr
14110 61 6e 74 3b 20 74 68 65 20 6c 6f 67 67 65 72 20  ant; the logger 
14120 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73 75 70 70  function.** supp
14130 6c 69 65 64 20 62 79 20 74 68 65 20 61 70 70 6c  lied by the appl
14140 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  ication must not
14150 20 69 6e 76 6f 6b 65 20 61 6e 79 20 53 51 4c 69   invoke any SQLi
14160 74 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  te interface..**
14170 20 49 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65   In a multi-thre
14180 61 64 65 64 20 61 70 70 6c 69 63 61 74 69 6f 6e  aded application
14190 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  , the applicatio
141a0 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72  n-defined logger
141b0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73  .** function mus
141c0 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65 2e  t be threadsafe.
141d0 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53   </dd>.**.** [[S
141e0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49  QLITE_CONFIG_URI
141f0 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
14200 4e 46 49 47 5f 55 52 49 0a 2a 2a 20 3c 64 64 3e  NFIG_URI.** <dd>
14210 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61  ^(This option ta
14220 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
14230 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e  ument of type in
14240 74 2e 20 49 66 20 6e 6f 6e 2d 7a 65 72 6f 2c 20  t. If non-zero, 
14250 74 68 65 6e 0a 2a 2a 20 55 52 49 20 68 61 6e 64  then.** URI hand
14260 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79  ling is globally
14270 20 65 6e 61 62 6c 65 64 2e 20 49 66 20 74 68 65   enabled. If the
14280 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 7a 65   parameter is ze
14290 72 6f 2c 20 74 68 65 6e 20 55 52 49 20 68 61 6e  ro, then URI han
142a0 64 6c 69 6e 67 0a 2a 2a 20 69 73 20 67 6c 6f 62  dling.** is glob
142b0 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 2e 29 5e  ally disabled.)^
142c0 20 5e 49 66 20 55 52 49 20 68 61 6e 64 6c 69 6e   ^If URI handlin
142d0 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 65 6e  g is globally en
142e0 61 62 6c 65 64 2c 20 61 6c 6c 20 66 69 6c 65 6e  abled, all filen
142f0 61 6d 65 73 0a 2a 2a 20 70 61 73 73 65 64 20 74  ames.** passed t
14300 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  o [sqlite3_open(
14310 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  )], [sqlite3_ope
14320 6e 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65  n_v2()], [sqlite
14330 33 5f 6f 70 65 6e 31 36 28 29 5d 20 6f 72 0a 2a  3_open16()] or.*
14340 2a 20 73 70 65 63 69 66 69 65 64 20 61 73 20 70  * specified as p
14350 61 72 74 20 6f 66 20 5b 41 54 54 41 43 48 5d 20  art of [ATTACH] 
14360 63 6f 6d 6d 61 6e 64 73 20 61 72 65 20 69 6e 74  commands are int
14370 65 72 70 72 65 74 65 64 20 61 73 20 55 52 49 73  erpreted as URIs
14380 2c 20 72 65 67 61 72 64 6c 65 73 73 0a 2a 2a 20  , regardless.** 
14390 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  of whether or no
143a0 74 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  t the [SQLITE_OP
143b0 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69 73 20  EN_URI] flag is 
143c0 73 65 74 20 77 68 65 6e 20 74 68 65 20 64 61 74  set when the dat
143d0 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74  abase.** connect
143e0 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20 5e  ion is opened. ^
143f0 49 66 20 69 74 20 69 73 20 67 6c 6f 62 61 6c 6c  If it is globall
14400 79 20 64 69 73 61 62 6c 65 64 2c 20 66 69 6c 65  y disabled, file
14410 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20 6f 6e 6c  names are.** onl
14420 79 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  y interpreted as
14430 20 55 52 49 73 20 69 66 20 74 68 65 20 53 51 4c   URIs if the SQL
14440 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20 66 6c 61  ITE_OPEN_URI fla
14450 67 20 69 73 20 73 65 74 20 77 68 65 6e 20 74 68  g is set when th
14460 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  e.** database co
14470 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e  nnection is open
14480 65 64 2e 20 5e 28 42 79 20 64 65 66 61 75 6c 74  ed. ^(By default
14490 2c 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69  , URI handling i
144a0 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 64 69  s globally.** di
144b0 73 61 62 6c 65 64 2e 20 54 68 65 20 64 65 66 61  sabled. The defa
144c0 75 6c 74 20 76 61 6c 75 65 20 6d 61 79 20 62 65  ult value may be
144d0 20 63 68 61 6e 67 65 64 20 62 79 20 63 6f 6d 70   changed by comp
144e0 69 6c 69 6e 67 20 77 69 74 68 20 74 68 65 0a 2a  iling with the.*
144f0 2a 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55 52  * [SQLITE_USE_UR
14500 49 5d 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65  I] symbol define
14510 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d.)^.**.** [[SQL
14520 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52  ITE_CONFIG_COVER
14530 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d 5d  ING_INDEX_SCAN]]
14540 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
14550 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45  IG_COVERING_INDE
14560 58 5f 53 43 41 4e 0a 2a 2a 20 3c 64 64 3e 5e 54  X_SCAN.** <dd>^T
14570 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
14580 20 61 20 73 69 6e 67 6c 65 20 69 6e 74 65 67 65   a single intege
14590 72 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  r argument which
145a0 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20   is interpreted 
145b0 61 73 0a 2a 2a 20 61 20 62 6f 6f 6c 65 61 6e 20  as.** a boolean 
145c0 69 6e 20 6f 72 64 65 72 20 74 6f 20 65 6e 61 62  in order to enab
145d0 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 74 68  le or disable th
145e0 65 20 75 73 65 20 6f 66 20 63 6f 76 65 72 69 6e  e use of coverin
145f0 67 20 69 6e 64 69 63 65 73 20 66 6f 72 0a 2a 2a  g indices for.**
14600 20 66 75 6c 6c 20 74 61 62 6c 65 20 73 63 61 6e   full table scan
14610 73 20 69 6e 20 74 68 65 20 71 75 65 72 79 20 6f  s in the query o
14620 70 74 69 6d 69 7a 65 72 2e 20 20 5e 54 68 65 20  ptimizer.  ^The 
14630 64 65 66 61 75 6c 74 20 73 65 74 74 69 6e 67 20  default setting 
14640 69 73 20 64 65 74 65 72 6d 69 6e 65 64 0a 2a 2a  is determined.**
14650 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   by the [SQLITE_
14660 41 4c 4c 4f 57 5f 43 4f 56 45 52 49 4e 47 5f 49  ALLOW_COVERING_I
14670 4e 44 45 58 5f 53 43 41 4e 5d 20 63 6f 6d 70 69  NDEX_SCAN] compi
14680 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20  le-time option, 
14690 6f 72 20 69 73 20 22 6f 6e 22 0a 2a 2a 20 69 66  or is "on".** if
146a0 20 74 68 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69   that compile-ti
146b0 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6d 69  me option is omi
146c0 74 74 65 64 2e 0a 2a 2a 20 54 68 65 20 61 62 69  tted..** The abi
146d0 6c 69 74 79 20 74 6f 20 64 69 73 61 62 6c 65 20  lity to disable 
146e0 74 68 65 20 75 73 65 20 6f 66 20 63 6f 76 65 72  the use of cover
146f0 69 6e 67 20 69 6e 64 69 63 65 73 20 66 6f 72 20  ing indices for 
14700 66 75 6c 6c 20 74 61 62 6c 65 20 73 63 61 6e 73  full table scans
14710 0a 2a 2a 20 69 73 20 62 65 63 61 75 73 65 20 73  .** is because s
14720 6f 6d 65 20 69 6e 63 6f 72 72 65 63 74 6c 79 20  ome incorrectly 
14730 63 6f 64 65 64 20 6c 65 67 61 63 79 20 61 70 70  coded legacy app
14740 6c 69 63 61 74 69 6f 6e 73 20 6d 69 67 68 74 20  lications might 
14750 6d 61 6c 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77  malfunction.** w
14760 68 65 6e 20 74 68 65 20 6f 70 74 69 6d 69 7a 61  hen the optimiza
14770 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e  tion is enabled.
14780 20 20 50 72 6f 76 69 64 69 6e 67 20 74 68 65 20    Providing the 
14790 61 62 69 6c 69 74 79 20 74 6f 0a 2a 2a 20 64 69  ability to.** di
147a0 73 61 62 6c 65 20 74 68 65 20 6f 70 74 69 6d 69  sable the optimi
147b0 7a 61 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 74 68  zation allows th
147c0 65 20 6f 6c 64 65 72 2c 20 62 75 67 67 79 20 61  e older, buggy a
147d0 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20  pplication code 
147e0 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 69 74 68 6f  to work.** witho
147f0 75 74 20 63 68 61 6e 67 65 20 65 76 65 6e 20 77  ut change even w
14800 69 74 68 20 6e 65 77 65 72 20 76 65 72 73 69 6f  ith newer versio
14810 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  ns of SQLite..**
14820 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
14830 46 49 47 5f 50 43 41 43 48 45 5d 5d 20 5b 5b 53  FIG_PCACHE]] [[S
14840 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
14850 50 43 41 43 48 45 5d 5d 0a 2a 2a 20 3c 64 74 3e  PCACHE]].** <dt>
14860 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
14870 41 43 48 45 20 61 6e 64 20 53 51 4c 49 54 45 5f  ACHE and SQLITE_
14880 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45  CONFIG_GETPCACHE
14890 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 73 65 20 6f  .** <dd> These o
148a0 70 74 69 6f 6e 73 20 61 72 65 20 6f 62 73 6f 6c  ptions are obsol
148b0 65 74 65 20 61 6e 64 20 73 68 6f 75 6c 64 20 6e  ete and should n
148c0 6f 74 20 62 65 20 75 73 65 64 20 62 79 20 6e 65  ot be used by ne
148d0 77 20 63 6f 64 65 2e 0a 2a 2a 20 54 68 65 79 20  w code..** They 
148e0 61 72 65 20 72 65 74 61 69 6e 65 64 20 66 6f 72  are retained for
148f0 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61   backwards compa
14900 74 69 62 69 6c 69 74 79 20 62 75 74 20 61 72 65  tibility but are
14910 20 6e 6f 77 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 20   now no-ops..** 
14920 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
14930 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c  LITE_CONFIG_SQLL
14940 4f 47 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  OG]].** <dt>SQLI
14950 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47  TE_CONFIG_SQLLOG
14960 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74  .** <dd>This opt
14970 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69  ion is only avai
14980 6c 61 62 6c 65 20 69 66 20 73 71 6c 69 74 65 20  lable if sqlite 
14990 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
149a0 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
149b0 45 4e 41 42 4c 45 5f 53 51 4c 4c 4f 47 5d 20 70  ENABLE_SQLLOG] p
149c0 72 65 2d 70 72 6f 63 65 73 73 6f 72 20 6d 61 63  re-processor mac
149d0 72 6f 20 64 65 66 69 6e 65 64 2e 20 54 68 65 20  ro defined. The 
149e0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 73  first argument s
149f0 68 6f 75 6c 64 0a 2a 2a 20 62 65 20 61 20 70 6f  hould.** be a po
14a00 69 6e 74 65 72 20 74 6f 20 61 20 66 75 6e 63 74  inter to a funct
14a10 69 6f 6e 20 6f 66 20 74 79 70 65 20 76 6f 69 64  ion of type void
14a20 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65  (*)(void*,sqlite
14a30 33 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  3*,const char*, 
14a40 69 6e 74 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63  int)..** The sec
14a50 6f 6e 64 20 73 68 6f 75 6c 64 20 62 65 20 6f 66  ond should be of
14a60 20 74 79 70 65 20 28 76 6f 69 64 2a 29 2e 20 54   type (void*). T
14a70 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  he callback is i
14a80 6e 76 6f 6b 65 64 20 62 79 20 74 68 65 20 6c 69  nvoked by the li
14a90 62 72 61 72 79 0a 2a 2a 20 69 6e 20 74 68 72 65  brary.** in thre
14aa0 65 20 73 65 70 61 72 61 74 65 20 63 69 72 63 75  e separate circu
14ab0 6d 73 74 61 6e 63 65 73 2c 20 69 64 65 6e 74 69  mstances, identi
14ac0 66 69 65 64 20 62 79 20 74 68 65 20 76 61 6c 75  fied by the valu
14ad0 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 0a  e passed as the.
14ae0 2a 2a 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  ** fourth parame
14af0 74 65 72 2e 20 49 66 20 74 68 65 20 66 6f 75 72  ter. If the four
14b00 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  th parameter is 
14b10 30 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61  0, then the data
14b20 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
14b30 2a 2a 20 70 61 73 73 65 64 20 61 73 20 74 68 65  ** passed as the
14b40 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
14b50 20 68 61 73 20 6a 75 73 74 20 62 65 65 6e 20 6f   has just been o
14b60 70 65 6e 65 64 2e 20 54 68 65 20 74 68 69 72 64  pened. The third
14b70 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 70 6f 69   argument.** poi
14b80 6e 74 73 20 74 6f 20 61 20 62 75 66 66 65 72 20  nts to a buffer 
14b90 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 6e  containing the n
14ba0 61 6d 65 20 6f 66 20 74 68 65 20 6d 61 69 6e 20  ame of the main 
14bb0 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e 20 49  database file. I
14bc0 66 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20  f the.** fourth 
14bd0 70 61 72 61 6d 65 74 65 72 20 69 73 20 31 2c 20  parameter is 1, 
14be0 74 68 65 6e 20 74 68 65 20 53 51 4c 20 73 74 61  then the SQL sta
14bf0 74 65 6d 65 6e 74 20 74 68 61 74 20 74 68 65 20  tement that the 
14c00 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 0a  third parameter.
14c10 2a 2a 20 70 6f 69 6e 74 73 20 74 6f 20 68 61 73  ** points to has
14c20 20 6a 75 73 74 20 62 65 65 6e 20 65 78 65 63 75   just been execu
14c30 74 65 64 2e 20 4f 72 2c 20 69 66 20 74 68 65 20  ted. Or, if the 
14c40 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
14c50 20 69 73 20 32 2c 20 74 68 65 6e 0a 2a 2a 20 74   is 2, then.** t
14c60 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 65  he connection be
14c70 69 6e 67 20 70 61 73 73 65 64 20 61 73 20 74 68  ing passed as th
14c80 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
14c90 65 72 20 69 73 20 62 65 69 6e 67 20 63 6c 6f 73  er is being clos
14ca0 65 64 2e 20 54 68 65 0a 2a 2a 20 74 68 69 72 64  ed. The.** third
14cb0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 70 61   parameter is pa
14cc0 73 73 65 64 20 4e 55 4c 4c 20 49 6e 20 74 68 69  ssed NULL In thi
14cd0 73 20 63 61 73 65 2e 20 20 41 6e 20 65 78 61 6d  s case.  An exam
14ce0 70 6c 65 20 6f 66 20 75 73 69 6e 67 20 74 68 69  ple of using thi
14cf0 73 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69  s.** configurati
14d00 6f 6e 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65  on option can be
14d10 20 73 65 65 6e 20 69 6e 20 74 68 65 20 22 74 65   seen in the "te
14d20 73 74 5f 73 71 6c 6c 6f 67 2e 63 22 20 73 6f 75  st_sqllog.c" sou
14d30 72 63 65 20 66 69 6c 65 20 69 6e 0a 2a 2a 20 74  rce file in.** t
14d40 68 65 20 63 61 6e 6f 6e 69 63 61 6c 20 53 51 4c  he canonical SQL
14d50 69 74 65 20 73 6f 75 72 63 65 20 74 72 65 65 2e  ite source tree.
14d60 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
14d70 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50  LITE_CONFIG_MMAP
14d80 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53  _SIZE]].** <dt>S
14d90 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41  QLITE_CONFIG_MMA
14da0 50 5f 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e 5e 53  P_SIZE.** <dd>^S
14db0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41  QLITE_CONFIG_MMA
14dc0 50 5f 53 49 5a 45 20 74 61 6b 65 73 20 74 77 6f  P_SIZE takes two
14dd0 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20   64-bit integer 
14de0 28 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 20  (sqlite3_int64) 
14df0 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 61  values.** that a
14e00 72 65 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d  re the default m
14e10 6d 61 70 20 73 69 7a 65 20 6c 69 6d 69 74 20 28  map size limit (
14e20 74 68 65 20 64 65 66 61 75 6c 74 20 73 65 74 74  the default sett
14e30 69 6e 67 20 66 6f 72 0a 2a 2a 20 5b 50 52 41 47  ing for.** [PRAG
14e40 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 29 20 61  MA mmap_size]) a
14e50 6e 64 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 61  nd the maximum a
14e60 6c 6c 6f 77 65 64 20 6d 6d 61 70 20 73 69 7a 65  llowed mmap size
14e70 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 54 68 65 20   limit..** ^The 
14e80 64 65 66 61 75 6c 74 20 73 65 74 74 69 6e 67 20  default setting 
14e90 63 61 6e 20 62 65 20 6f 76 65 72 72 69 64 64 65  can be overridde
14ea0 6e 20 62 79 20 65 61 63 68 20 64 61 74 61 62 61  n by each databa
14eb0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 75 73  se connection us
14ec0 69 6e 67 0a 2a 2a 20 65 69 74 68 65 72 20 74 68  ing.** either th
14ed0 65 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73  e [PRAGMA mmap_s
14ee0 69 7a 65 5d 20 63 6f 6d 6d 61 6e 64 2c 20 6f 72  ize] command, or
14ef0 20 62 79 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a   by using the.**
14f00 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d   [SQLITE_FCNTL_M
14f10 4d 41 50 5f 53 49 5a 45 5d 20 66 69 6c 65 20 63  MAP_SIZE] file c
14f20 6f 6e 74 72 6f 6c 2e 20 20 5e 28 54 68 65 20 6d  ontrol.  ^(The m
14f30 61 78 69 6d 75 6d 20 61 6c 6c 6f 77 65 64 20 6d  aximum allowed m
14f40 6d 61 70 20 73 69 7a 65 0a 2a 2a 20 63 61 6e 6e  map size.** cann
14f50 6f 74 20 62 65 20 63 68 61 6e 67 65 64 20 61 74  ot be changed at
14f60 20 72 75 6e 2d 74 69 6d 65 2e 20 20 4e 6f 72 20   run-time.  Nor 
14f70 6d 61 79 20 74 68 65 20 6d 61 78 69 6d 75 6d 20  may the maximum 
14f80 61 6c 6c 6f 77 65 64 20 6d 6d 61 70 20 73 69 7a  allowed mmap siz
14f90 65 0a 2a 2a 20 65 78 63 65 65 64 20 74 68 65 20  e.** exceed the 
14fa0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 61 78  compile-time max
14fb0 69 6d 75 6d 20 6d 6d 61 70 20 73 69 7a 65 20 73  imum mmap size s
14fc0 65 74 20 62 79 20 74 68 65 0a 2a 2a 20 5b 53 51  et by the.** [SQ
14fd0 4c 49 54 45 5f 4d 41 58 5f 4d 4d 41 50 5f 53 49  LITE_MAX_MMAP_SI
14fe0 5a 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  ZE] compile-time
14ff0 20 6f 70 74 69 6f 6e 2e 29 5e 0a 2a 2a 20 5e 49   option.)^.** ^I
15000 66 20 65 69 74 68 65 72 20 61 72 67 75 6d 65 6e  f either argumen
15010 74 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e  t to this option
15020 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68   is negative, th
15030 65 6e 20 74 68 61 74 20 61 72 67 75 6d 65 6e 74  en that argument
15040 20 69 73 0a 2a 2a 20 63 68 61 6e 67 65 64 20 74   is.** changed t
15050 6f 20 69 74 73 20 63 6f 6d 70 69 6c 65 2d 74 69  o its compile-ti
15060 6d 65 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a  me default..**.*
15070 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
15080 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45  G_WIN32_HEAPSIZE
15090 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  ]].** <dt>SQLITE
150a0 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45  _CONFIG_WIN32_HE
150b0 41 50 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e 5e 54  APSIZE.** <dd>^T
150c0 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e  his option is on
150d0 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20  ly available if 
150e0 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
150f0 65 64 20 66 6f 72 20 57 69 6e 64 6f 77 73 0a 2a  ed for Windows.*
15100 2a 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49  * with the [SQLI
15110 54 45 5f 57 49 4e 33 32 5f 4d 41 4c 4c 4f 43 5d  TE_WIN32_MALLOC]
15120 20 70 72 65 2d 70 72 6f 63 65 73 73 6f 72 20 6d   pre-processor m
15130 61 63 72 6f 20 64 65 66 69 6e 65 64 2e 0a 2a 2a  acro defined..**
15140 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57   SQLITE_CONFIG_W
15150 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 20 74 61  IN32_HEAPSIZE ta
15160 6b 65 73 20 61 20 33 32 2d 62 69 74 20 75 6e 73  kes a 32-bit uns
15170 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 76 61  igned integer va
15180 6c 75 65 0a 2a 2a 20 74 68 61 74 20 73 70 65 63  lue.** that spec
15190 69 66 69 65 73 20 74 68 65 20 6d 61 78 69 6d 75  ifies the maximu
151a0 6d 20 73 69 7a 65 20 6f 66 20 74 68 65 20 63 72  m size of the cr
151b0 65 61 74 65 64 20 68 65 61 70 2e 0a 2a 2a 20 3c  eated heap..** <
151c0 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  /dl>.*/.#define 
151d0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49  SQLITE_CONFIG_SI
151e0 4e 47 4c 45 54 48 52 45 41 44 20 20 31 20 20 2f  NGLETHREAD  1  /
151f0 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65  * nil */.#define
15200 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
15210 55 4c 54 49 54 48 52 45 41 44 20 20 20 32 20 20  ULTITHREAD   2  
15220 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e  /* nil */.#defin
15230 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
15240 53 45 52 49 41 4c 49 5a 45 44 20 20 20 20 33 20  SERIALIZED    3 
15250 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69   /* nil */.#defi
15260 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
15270 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20 20 34  _MALLOC        4
15280 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d    /* sqlite3_mem
15290 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65  _methods* */.#de
152a0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
152b0 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 20 20 20  IG_GETMALLOC    
152c0 20 35 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d   5  /* sqlite3_m
152d0 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23  em_methods* */.#
152e0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
152f0 4e 46 49 47 5f 53 43 52 41 54 43 48 20 20 20 20  NFIG_SCRATCH    
15300 20 20 20 36 20 20 2f 2a 20 76 6f 69 64 2a 2c 20     6  /* void*, 
15310 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f  int sz, int N */
15320 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
15330 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45  CONFIG_PAGECACHE
15340 20 20 20 20 20 37 20 20 2f 2a 20 76 6f 69 64 2a       7  /* void*
15350 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20  , int sz, int N 
15360 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
15370 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 20 20  E_CONFIG_HEAP   
15380 20 20 20 20 20 20 20 38 20 20 2f 2a 20 76 6f 69         8  /* voi
15390 64 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 69  d*, int nByte, i
153a0 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64 65 66 69 6e  nt min */.#defin
153b0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
153c0 4d 45 4d 53 54 41 54 55 53 20 20 20 20 20 39 20  MEMSTATUS     9 
153d0 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 23   /* boolean */.#
153e0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
153f0 4e 46 49 47 5f 4d 55 54 45 58 20 20 20 20 20 20  NFIG_MUTEX      
15400 20 20 31 30 20 20 2f 2a 20 73 71 6c 69 74 65 33    10  /* sqlite3
15410 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20  _mutex_methods* 
15420 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
15430 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45  E_CONFIG_GETMUTE
15440 58 20 20 20 20 20 31 31 20 20 2f 2a 20 73 71 6c  X     11  /* sql
15450 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
15460 64 73 2a 20 2a 2f 0a 2f 2a 20 70 72 65 76 69 6f  ds* */./* previo
15470 75 73 6c 79 20 53 51 4c 49 54 45 5f 43 4f 4e 46  usly SQLITE_CONF
15480 49 47 5f 43 48 55 4e 4b 41 4c 4c 4f 43 20 31 32  IG_CHUNKALLOC 12
15490 20 77 68 69 63 68 20 69 73 20 6e 6f 77 20 75 6e   which is now un
154a0 75 73 65 64 2e 20 2a 2f 20 0a 23 64 65 66 69 6e  used. */ .#defin
154b0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
154c0 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 31 33 20  LOOKASIDE    13 
154d0 20 2f 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23   /* int int */.#
154e0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
154f0 4e 46 49 47 5f 50 43 41 43 48 45 20 20 20 20 20  NFIG_PCACHE     
15500 20 20 31 34 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a    14  /* no-op *
15510 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
15520 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48  _CONFIG_GETPCACH
15530 45 20 20 20 20 31 35 20 20 2f 2a 20 6e 6f 2d 6f  E    15  /* no-o
15540 70 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  p */.#define SQL
15550 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 20  ITE_CONFIG_LOG  
15560 20 20 20 20 20 20 20 20 31 36 20 20 2f 2a 20 78          16  /* x
15570 46 75 6e 63 2c 20 76 6f 69 64 2a 20 2a 2f 0a 23  Func, void* */.#
15580 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
15590 4e 46 49 47 5f 55 52 49 20 20 20 20 20 20 20 20  NFIG_URI        
155a0 20 20 31 37 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a    17  /* int */.
155b0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
155c0 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 20 20 20  ONFIG_PCACHE2   
155d0 20 20 20 31 38 20 20 2f 2a 20 73 71 6c 69 74 65     18  /* sqlite
155e0 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73  3_pcache_methods
155f0 32 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  2* */.#define SQ
15600 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50  LITE_CONFIG_GETP
15610 43 41 43 48 45 32 20 20 20 31 39 20 20 2f 2a 20  CACHE2   19  /* 
15620 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d  sqlite3_pcache_m
15630 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23 64 65 66  ethods2* */.#def
15640 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
15650 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58  G_COVERING_INDEX
15660 5f 53 43 41 4e 20 32 30 20 20 2f 2a 20 69 6e 74  _SCAN 20  /* int
15670 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
15680 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47  TE_CONFIG_SQLLOG
15690 20 20 20 20 20 20 20 32 31 20 20 2f 2a 20 78 53         21  /* xS
156a0 71 6c 6c 6f 67 2c 20 76 6f 69 64 2a 20 2a 2f 0a  qllog, void* */.
156b0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
156c0 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 20  ONFIG_MMAP_SIZE 
156d0 20 20 20 32 32 20 20 2f 2a 20 73 71 6c 69 74 65     22  /* sqlite
156e0 33 5f 69 6e 74 36 34 2c 20 73 71 6c 69 74 65 33  3_int64, sqlite3
156f0 5f 69 6e 74 36 34 20 2a 2f 0a 23 64 65 66 69 6e  _int64 */.#defin
15700 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
15710 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 20 20  WIN32_HEAPSIZE  
15720 20 20 20 20 32 33 20 20 2f 2a 20 69 6e 74 20 6e      23  /* int n
15730 42 79 74 65 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  Byte */../*.** C
15740 41 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73  API3REF: Databas
15750 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 43 6f 6e  e Connection Con
15760 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f  figuration Optio
15770 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63  ns.**.** These c
15780 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68 65  onstants are the
15790 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67   available integ
157a0 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  er configuration
157b0 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a   options that.**
157c0 20 63 61 6e 20 62 65 20 70 61 73 73 65 64 20 61   can be passed a
157d0 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  s the second arg
157e0 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71  ument to the [sq
157f0 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
15800 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  )] interface..**
15810 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75 72  .** New configur
15820 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61  ation options ma
15830 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75  y be added in fu
15840 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66  ture releases of
15850 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73   SQLite..** Exis
15860 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69  ting configurati
15870 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74  on options might
15880 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65 64   be discontinued
15890 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a  .  Applications.
158a0 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b 20  ** should check 
158b0 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20  the return code 
158c0 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 64 62  from [sqlite3_db
158d0 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61  _config()] to ma
158e0 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20  ke sure that.** 
158f0 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e  the call worked.
15900 20 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f    ^The [sqlite3_
15910 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74  db_config()] int
15920 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74 75  erface will retu
15930 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f  rn a.** non-zero
15940 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66   [error code] if
15950 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 20   a discontinued 
15960 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20 63  or unsupported c
15970 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
15980 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65  ion.** is invoke
15990 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a  d..**.** <dl>.**
159a0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f   <dt>SQLITE_DBCO
159b0 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f  NFIG_LOOKASIDE</
159c0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69  dt>.** <dd> ^Thi
159d0 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74  s option takes t
159e0 68 72 65 65 20 61 64 64 69 74 69 6f 6e 61 6c 20  hree additional 
159f0 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64  arguments that d
15a00 65 74 65 72 6d 69 6e 65 20 74 68 65 20 0a 2a 2a  etermine the .**
15a10 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f   [lookaside memo
15a20 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 20 63 6f  ry allocator] co
15a30 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f 72 20  nfiguration for 
15a40 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
15a50 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 5e 54  nnection]..** ^T
15a60 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
15a70 74 20 28 74 68 65 20 74 68 69 72 64 20 70 61 72  t (the third par
15a80 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74  ameter to [sqlit
15a90 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20  e3_db_config()] 
15aa0 69 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  is a.** pointer 
15ab0 74 6f 20 61 20 6d 65 6d 6f 72 79 20 62 75 66 66  to a memory buff
15ac0 65 72 20 74 6f 20 75 73 65 20 66 6f 72 20 6c 6f  er to use for lo
15ad0 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 2e 0a  okaside memory..
15ae0 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72  ** ^The first ar
15af0 67 75 6d 65 6e 74 20 61 66 74 65 72 20 74 68 65  gument after the
15b00 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47   SQLITE_DBCONFIG
15b10 5f 4c 4f 4f 4b 41 53 49 44 45 20 76 65 72 62 0a  _LOOKASIDE verb.
15b20 2a 2a 20 6d 61 79 20 62 65 20 4e 55 4c 4c 20 69  ** may be NULL i
15b30 6e 20 77 68 69 63 68 20 63 61 73 65 20 53 51 4c  n which case SQL
15b40 69 74 65 20 77 69 6c 6c 20 61 6c 6c 6f 63 61 74  ite will allocat
15b50 65 20 74 68 65 0a 2a 2a 20 6c 6f 6f 6b 61 73 69  e the.** lookasi
15b60 64 65 20 62 75 66 66 65 72 20 69 74 73 65 6c 66  de buffer itself
15b70 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
15b80 6d 61 6c 6c 6f 63 28 29 5d 2e 20 5e 54 68 65 20  malloc()]. ^The 
15b90 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
15ba0 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f  is the.** size o
15bb0 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65  f each lookaside
15bc0 20 62 75 66 66 65 72 20 73 6c 6f 74 2e 20 20 5e   buffer slot.  ^
15bd0 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  The third argume
15be0 6e 74 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72  nt is the number
15bf0 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 2e 20 20 54   of.** slots.  T
15c00 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62  he size of the b
15c10 75 66 66 65 72 20 69 6e 20 74 68 65 20 66 69 72  uffer in the fir
15c20 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74  st argument must
15c30 20 62 65 20 67 72 65 61 74 65 72 20 74 68 61 6e   be greater than
15c40 0a 2a 2a 20 6f 72 20 65 71 75 61 6c 20 74 6f 20  .** or equal to 
15c50 74 68 65 20 70 72 6f 64 75 63 74 20 6f 66 20 74  the product of t
15c60 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68  he second and th
15c70 69 72 64 20 61 72 67 75 6d 65 6e 74 73 2e 20 20  ird arguments.  
15c80 54 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 6d 75  The buffer.** mu
15c90 73 74 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f  st be aligned to
15ca0 20 61 6e 20 38 2d 62 79 74 65 20 62 6f 75 6e 64   an 8-byte bound
15cb0 61 72 79 2e 20 20 5e 49 66 20 74 68 65 20 73 65  ary.  ^If the se
15cc0 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
15cd0 0a 2a 2a 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  .** SQLITE_DBCON
15ce0 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 69 73  FIG_LOOKASIDE is
15cf0 20 6e 6f 74 20 61 20 6d 75 6c 74 69 70 6c 65 20   not a multiple 
15d00 6f 66 20 38 2c 20 69 74 20 69 73 20 69 6e 74 65  of 8, it is inte
15d10 72 6e 61 6c 6c 79 0a 2a 2a 20 72 6f 75 6e 64 65  rnally.** rounde
15d20 64 20 64 6f 77 6e 20 74 6f 20 74 68 65 20 6e 65  d down to the ne
15d30 78 74 20 73 6d 61 6c 6c 65 72 20 6d 75 6c 74 69  xt smaller multi
15d40 70 6c 65 20 6f 66 20 38 2e 20 20 5e 28 54 68 65  ple of 8.  ^(The
15d50 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72   lookaside memor
15d60 79 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69  y.** configurati
15d70 6f 6e 20 66 6f 72 20 61 20 64 61 74 61 62 61 73  on for a databas
15d80 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 61 6e  e connection can
15d90 20 6f 6e 6c 79 20 62 65 20 63 68 61 6e 67 65 64   only be changed
15da0 20 77 68 65 6e 20 74 68 61 74 0a 2a 2a 20 63 6f   when that.** co
15db0 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6e 6f 74 20  nnection is not 
15dc0 63 75 72 72 65 6e 74 6c 79 20 75 73 69 6e 67 20  currently using 
15dd0 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79  lookaside memory
15de0 2c 20 6f 72 20 69 6e 20 6f 74 68 65 72 20 77 6f  , or in other wo
15df0 72 64 73 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20  rds.** when the 
15e00 22 63 75 72 72 65 6e 74 20 76 61 6c 75 65 22 20  "current value" 
15e10 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b  returned by.** [
15e20 73 71 6c 69 74 65 33 5f 64 62 5f 73 74 61 74 75  sqlite3_db_statu
15e30 73 5d 28 44 2c 5b 53 51 4c 49 54 45 5f 43 4f 4e  s](D,[SQLITE_CON
15e40 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 2c 2e  FIG_LOOKASIDE],.
15e50 2e 2e 29 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a 20  ..) is zero..** 
15e60 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 63  Any attempt to c
15e70 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73  hange the lookas
15e80 69 64 65 20 6d 65 6d 6f 72 79 20 63 6f 6e 66 69  ide memory confi
15e90 67 75 72 61 74 69 6f 6e 20 77 68 65 6e 20 6c 6f  guration when lo
15ea0 6f 6b 61 73 69 64 65 0a 2a 2a 20 6d 65 6d 6f 72  okaside.** memor
15eb0 79 20 69 73 20 69 6e 20 75 73 65 20 6c 65 61 76  y is in use leav
15ec0 65 73 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61  es the configura
15ed0 74 69 6f 6e 20 75 6e 63 68 61 6e 67 65 64 20 61  tion unchanged a
15ee0 6e 64 20 72 65 74 75 72 6e 73 20 0a 2a 2a 20 5b  nd returns .** [
15ef0 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 29 5e 3c  SQLITE_BUSY].)^<
15f00 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
15f10 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45  QLITE_DBCONFIG_E
15f20 4e 41 42 4c 45 5f 46 4b 45 59 3c 2f 64 74 3e 0a  NABLE_FKEY</dt>.
15f30 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70  ** <dd> ^This op
15f40 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20  tion is used to 
15f50 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c  enable or disabl
15f60 65 20 74 68 65 20 65 6e 66 6f 72 63 65 6d 65 6e  e the enforcemen
15f70 74 20 6f 66 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e  t of.** [foreign
15f80 20 6b 65 79 20 63 6f 6e 73 74 72 61 69 6e 74 73   key constraints
15f90 5d 2e 20 20 54 68 65 72 65 20 73 68 6f 75 6c 64  ].  There should
15fa0 20 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e   be two addition
15fb0 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a  al arguments..**
15fc0 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
15fd0 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ent is an intege
15fe0 72 20 77 68 69 63 68 20 69 73 20 30 20 74 6f 20  r which is 0 to 
15ff0 64 69 73 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72  disable FK enfor
16000 63 65 6d 65 6e 74 2c 0a 2a 2a 20 70 6f 73 69 74  cement,.** posit
16010 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 46 4b  ive to enable FK
16020 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 72 20   enforcement or 
16030 6e 65 67 61 74 69 76 65 20 74 6f 20 6c 65 61 76  negative to leav
16040 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74  e FK enforcement
16050 0a 2a 2a 20 75 6e 63 68 61 6e 67 65 64 2e 20 20  .** unchanged.  
16060 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
16070 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65  eter is a pointe
16080 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20  r to an integer 
16090 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73  into which.** is
160a0 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20   written 0 or 1 
160b0 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65 74  to indicate whet
160c0 68 65 72 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65  her FK enforceme
160d0 6e 74 20 69 73 20 6f 66 66 20 6f 72 20 6f 6e 0a  nt is off or on.
160e0 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69  ** following thi
160f0 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 63  s call.  The sec
16100 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d 61  ond parameter ma
16110 79 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  y be a NULL poin
16120 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68  ter, in.** which
16130 20 63 61 73 65 20 74 68 65 20 46 4b 20 65 6e 66   case the FK enf
16140 6f 72 63 65 6d 65 6e 74 20 73 65 74 74 69 6e 67  orcement setting
16150 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 64   is not reported
16160 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a   back. </dd>.**.
16170 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42  ** <dt>SQLITE_DB
16180 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52  CONFIG_ENABLE_TR
16190 49 47 47 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  IGGER</dt>.** <d
161a0 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  d> ^This option 
161b0 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c  is used to enabl
161c0 65 20 6f 72 20 64 69 73 61 62 6c 65 20 5b 43 52  e or disable [CR
161d0 45 41 54 45 20 54 52 49 47 47 45 52 20 7c 20 74  EATE TRIGGER | t
161e0 72 69 67 67 65 72 73 5d 2e 0a 2a 2a 20 54 68 65  riggers]..** The
161f0 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f  re should be two
16200 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75   additional argu
16210 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69  ments..** The fi
16220 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20  rst argument is 
16230 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68  an integer which
16240 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65   is 0 to disable
16250 20 74 72 69 67 67 65 72 73 2c 0a 2a 2a 20 70 6f   triggers,.** po
16260 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65  sitive to enable
16270 20 74 72 69 67 67 65 72 73 20 6f 72 20 6e 65 67   triggers or neg
16280 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20 74  ative to leave t
16290 68 65 20 73 65 74 74 69 6e 67 20 75 6e 63 68 61  he setting uncha
162a0 6e 67 65 64 2e 0a 2a 2a 20 54 68 65 20 73 65 63  nged..** The sec
162b0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
162c0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
162d0 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68   integer into wh
162e0 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65  ich.** is writte
162f0 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69  n 0 or 1 to indi
16300 63 61 74 65 20 77 68 65 74 68 65 72 20 74 72 69  cate whether tri
16310 67 67 65 72 73 20 61 72 65 20 64 69 73 61 62 6c  ggers are disabl
16320 65 64 20 6f 72 20 65 6e 61 62 6c 65 64 0a 2a 2a  ed or enabled.**
16330 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20   following this 
16340 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e  call.  The secon
16350 64 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20  d parameter may 
16360 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  be a NULL pointe
16370 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63  r, in.** which c
16380 61 73 65 20 74 68 65 20 74 72 69 67 67 65 72 20  ase the trigger 
16390 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72  setting is not r
163a0 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f  eported back. </
163b0 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a  dd>.**.** </dl>.
163c0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
163d0 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  E_DBCONFIG_LOOKA
163e0 53 49 44 45 20 20 20 20 20 20 20 31 30 30 31 20  SIDE       1001 
163f0 20 2f 2a 20 76 6f 69 64 2a 20 69 6e 74 20 69 6e   /* void* int in
16400 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  t */.#define SQL
16410 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41  ITE_DBCONFIG_ENA
16420 42 4c 45 5f 46 4b 45 59 20 20 20 20 20 31 30 30  BLE_FKEY     100
16430 32 20 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a  2  /* int int* *
16440 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
16450 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45  _DBCONFIG_ENABLE
16460 5f 54 52 49 47 47 45 52 20 20 31 30 30 33 20 20  _TRIGGER  1003  
16470 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 0a  /* int int* */..
16480 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
16490 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62   Enable Or Disab
164a0 6c 65 20 45 78 74 65 6e 64 65 64 20 52 65 73 75  le Extended Resu
164b0 6c 74 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 5e  lt Codes.**.** ^
164c0 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65  The sqlite3_exte
164d0 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65  nded_result_code
164e0 73 28 29 20 72 6f 75 74 69 6e 65 20 65 6e 61 62  s() routine enab
164f0 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20  les or disables 
16500 74 68 65 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64  the.** [extended
16510 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 66   result codes] f
16520 65 61 74 75 72 65 20 6f 66 20 53 51 4c 69 74 65  eature of SQLite
16530 2e 20 5e 54 68 65 20 65 78 74 65 6e 64 65 64 20  . ^The extended 
16540 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 64 65 73 20  result.** codes 
16550 61 72 65 20 64 69 73 61 62 6c 65 64 20 62 79 20  are disabled by 
16560 64 65 66 61 75 6c 74 20 66 6f 72 20 68 69 73 74  default for hist
16570 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74 69 62 69  orical compatibi
16580 6c 69 74 79 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  lity..*/.int sql
16590 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65  ite3_extended_re
165a0 73 75 6c 74 5f 63 6f 64 65 73 28 73 71 6c 69 74  sult_codes(sqlit
165b0 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b  e3*, int onoff);
165c0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
165d0 3a 20 4c 61 73 74 20 49 6e 73 65 72 74 20 52 6f  : Last Insert Ro
165e0 77 69 64 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20  wid.**.** ^Each 
165f0 65 6e 74 72 79 20 69 6e 20 6d 6f 73 74 20 53 51  entry in most SQ
16600 4c 69 74 65 20 74 61 62 6c 65 73 20 28 65 78 63  Lite tables (exc
16610 65 70 74 20 66 6f 72 20 5b 57 49 54 48 4f 55 54  ept for [WITHOUT
16620 20 52 4f 57 49 44 5d 20 74 61 62 6c 65 73 29 0a   ROWID] tables).
16630 2a 2a 20 68 61 73 20 61 20 75 6e 69 71 75 65 20  ** has a unique 
16640 36 34 2d 62 69 74 20 73 69 67 6e 65 64 0a 2a 2a  64-bit signed.**
16650 20 69 6e 74 65 67 65 72 20 6b 65 79 20 63 61 6c   integer key cal
16660 6c 65 64 20 74 68 65 20 5b 52 4f 57 49 44 20 7c  led the [ROWID |
16670 20 22 72 6f 77 69 64 22 5d 2e 20 5e 54 68 65 20   "rowid"]. ^The 
16680 72 6f 77 69 64 20 69 73 20 61 6c 77 61 79 73 20  rowid is always 
16690 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 61 73 20  available.** as 
166a0 61 6e 20 75 6e 64 65 63 6c 61 72 65 64 20 63 6f  an undeclared co
166b0 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f 57 49 44  lumn named ROWID
166c0 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f 57 49 44  , OID, or _ROWID
166d0 5f 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 6f  _ as long as tho
166e0 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 61 72 65 20  se.** names are 
166f0 6e 6f 74 20 61 6c 73 6f 20 75 73 65 64 20 62 79  not also used by
16700 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c   explicitly decl
16710 61 72 65 64 20 63 6f 6c 75 6d 6e 73 2e 20 5e 49  ared columns. ^I
16720 66 0a 2a 2a 20 74 68 65 20 74 61 62 6c 65 20 68  f.** the table h
16730 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74  as a column of t
16740 79 70 65 20 5b 49 4e 54 45 47 45 52 20 50 52 49  ype [INTEGER PRI
16750 4d 41 52 59 20 4b 45 59 5d 20 74 68 65 6e 20 74  MARY KEY] then t
16760 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73  hat column.** is
16770 20 61 6e 6f 74 68 65 72 20 61 6c 69 61 73 20 66   another alias f
16780 6f 72 20 74 68 65 20 72 6f 77 69 64 2e 0a 2a 2a  or the rowid..**
16790 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
167a0 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  _last_insert_row
167b0 69 64 28 44 29 20 69 6e 74 65 72 66 61 63 65 20  id(D) interface 
167c0 72 65 74 75 72 6e 73 20 74 68 65 20 5b 72 6f 77  returns the [row
167d0 69 64 5d 20 6f 66 20 74 68 65 20 0a 2a 2a 20 6d  id] of the .** m
167e0 6f 73 74 20 72 65 63 65 6e 74 20 73 75 63 63 65  ost recent succe
167f0 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 69  ssful [INSERT] i
16800 6e 74 6f 20 61 20 72 6f 77 69 64 20 74 61 62 6c  nto a rowid tabl
16810 65 20 6f 72 20 5b 76 69 72 74 75 61 6c 20 74 61  e or [virtual ta
16820 62 6c 65 5d 0a 2a 2a 20 6f 6e 20 64 61 74 61 62  ble].** on datab
16830 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44  ase connection D
16840 2e 0a 2a 2a 20 5e 49 6e 73 65 72 74 73 20 69 6e  ..** ^Inserts in
16850 74 6f 20 5b 57 49 54 48 4f 55 54 20 52 4f 57 49  to [WITHOUT ROWI
16860 44 5d 20 74 61 62 6c 65 73 20 61 72 65 20 6e 6f  D] tables are no
16870 74 20 72 65 63 6f 72 64 65 64 2e 0a 2a 2a 20 5e  t recorded..** ^
16880 49 66 20 6e 6f 20 73 75 63 63 65 73 73 66 75 6c  If no successful
16890 20 5b 49 4e 53 45 52 54 5d 73 20 69 6e 74 6f 20   [INSERT]s into 
168a0 72 6f 77 69 64 20 74 61 62 6c 65 73 0a 2a 2a 20  rowid tables.** 
168b0 68 61 76 65 20 65 76 65 72 20 6f 63 63 75 72 72  have ever occurr
168c0 65 64 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61  ed on the databa
168d0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2c  se connection D,
168e0 20 0a 2a 2a 20 74 68 65 6e 20 73 71 6c 69 74 65   .** then sqlite
168f0 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f  3_last_insert_ro
16900 77 69 64 28 44 29 20 72 65 74 75 72 6e 73 20 7a  wid(D) returns z
16910 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20  ero..**.** ^(If 
16920 61 6e 20 5b 49 4e 53 45 52 54 5d 20 6f 63 63 75  an [INSERT] occu
16930 72 73 20 77 69 74 68 69 6e 20 61 20 74 72 69 67  rs within a trig
16940 67 65 72 20 6f 72 20 77 69 74 68 69 6e 20 61 20  ger or within a 
16950 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 0a  [virtual table].
16960 2a 2a 20 6d 65 74 68 6f 64 2c 20 74 68 65 6e 20  ** method, then 
16970 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 6c  this routine wil
16980 6c 20 72 65 74 75 72 6e 20 74 68 65 20 5b 72 6f  l return the [ro
16990 77 69 64 5d 20 6f 66 20 74 68 65 20 69 6e 73 65  wid] of the inse
169a0 72 74 65 64 0a 2a 2a 20 72 6f 77 20 61 73 20 6c  rted.** row as l
169b0 6f 6e 67 20 61 73 20 74 68 65 20 74 72 69 67 67  ong as the trigg
169c0 65 72 20 6f 72 20 76 69 72 74 75 61 6c 20 74 61  er or virtual ta
169d0 62 6c 65 20 6d 65 74 68 6f 64 20 69 73 20 72 75  ble method is ru
169e0 6e 6e 69 6e 67 2e 0a 2a 2a 20 42 75 74 20 6f 6e  nning..** But on
169f0 63 65 20 74 68 65 20 74 72 69 67 67 65 72 20 6f  ce the trigger o
16a00 72 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20  r virtual table 
16a10 6d 65 74 68 6f 64 20 65 6e 64 73 2c 20 74 68 65  method ends, the
16a20 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
16a30 0a 2a 2a 20 62 79 20 74 68 69 73 20 72 6f 75 74  .** by this rout
16a40 69 6e 65 20 72 65 76 65 72 74 73 20 74 6f 20 77  ine reverts to w
16a50 68 61 74 20 69 74 20 77 61 73 20 62 65 66 6f 72  hat it was befor
16a60 65 20 74 68 65 20 74 72 69 67 67 65 72 20 6f 72  e the trigger or
16a70 20 76 69 72 74 75 61 6c 0a 2a 2a 20 74 61 62 6c   virtual.** tabl
16a80 65 20 6d 65 74 68 6f 64 20 62 65 67 61 6e 2e 29  e method began.)
16a90 5e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b 49 4e 53  ^.**.** ^An [INS
16aa0 45 52 54 5d 20 74 68 61 74 20 66 61 69 6c 73 20  ERT] that fails 
16ab0 64 75 65 20 74 6f 20 61 20 63 6f 6e 73 74 72 61  due to a constra
16ac0 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 69 73  int violation is
16ad0 20 6e 6f 74 20 61 0a 2a 2a 20 73 75 63 63 65 73   not a.** succes
16ae0 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 61 6e  sful [INSERT] an
16af0 64 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67  d does not chang
16b00 65 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  e the value retu
16b10 72 6e 65 64 20 62 79 20 74 68 69 73 0a 2a 2a 20  rned by this.** 
16b20 72 6f 75 74 69 6e 65 2e 20 20 5e 54 68 75 73 20  routine.  ^Thus 
16b30 49 4e 53 45 52 54 20 4f 52 20 46 41 49 4c 2c 20  INSERT OR FAIL, 
16b40 49 4e 53 45 52 54 20 4f 52 20 49 47 4e 4f 52 45  INSERT OR IGNORE
16b50 2c 20 49 4e 53 45 52 54 20 4f 52 20 52 4f 4c 4c  , INSERT OR ROLL
16b60 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53  BACK,.** and INS
16b70 45 52 54 20 4f 52 20 41 42 4f 52 54 20 6d 61 6b  ERT OR ABORT mak
16b80 65 20 6e 6f 20 63 68 61 6e 67 65 73 20 74 6f 20  e no changes to 
16b90 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
16ba0 20 6f 66 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74   of this.** rout
16bb0 69 6e 65 20 77 68 65 6e 20 74 68 65 69 72 20 69  ine when their i
16bc0 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 73 2e 20  nsertion fails. 
16bd0 20 5e 28 57 68 65 6e 20 49 4e 53 45 52 54 20 4f   ^(When INSERT O
16be0 52 20 52 45 50 4c 41 43 45 0a 2a 2a 20 65 6e 63  R REPLACE.** enc
16bf0 6f 75 6e 74 65 72 73 20 61 20 63 6f 6e 73 74 72  ounters a constr
16c00 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 2c 20  aint violation, 
16c10 69 74 20 64 6f 65 73 20 6e 6f 74 20 66 61 69 6c  it does not fail
16c20 2e 20 20 54 68 65 0a 2a 2a 20 49 4e 53 45 52 54  .  The.** INSERT
16c30 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63 6f   continues to co
16c40 6d 70 6c 65 74 69 6f 6e 20 61 66 74 65 72 20 64  mpletion after d
16c50 65 6c 65 74 69 6e 67 20 72 6f 77 73 20 74 68 61  eleting rows tha
16c60 74 20 63 61 75 73 65 64 0a 2a 2a 20 74 68 65 20  t caused.** the 
16c70 63 6f 6e 73 74 72 61 69 6e 74 20 70 72 6f 62 6c  constraint probl
16c80 65 6d 20 73 6f 20 49 4e 53 45 52 54 20 4f 52 20  em so INSERT OR 
16c90 52 45 50 4c 41 43 45 20 77 69 6c 6c 20 61 6c 77  REPLACE will alw
16ca0 61 79 73 20 63 68 61 6e 67 65 0a 2a 2a 20 74 68  ays change.** th
16cb0 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f  e return value o
16cc0 66 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65  f this interface
16cd0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74  .)^.**.** ^For t
16ce0 68 65 20 70 75 72 70 6f 73 65 73 20 6f 66 20 74  he purposes of t
16cf0 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 61 6e 20  his routine, an 
16d00 5b 49 4e 53 45 52 54 5d 20 69 73 20 63 6f 6e 73  [INSERT] is cons
16d10 69 64 65 72 65 64 20 74 6f 0a 2a 2a 20 62 65 20  idered to.** be 
16d20 73 75 63 63 65 73 73 66 75 6c 20 65 76 65 6e 20  successful even 
16d30 69 66 20 69 74 20 69 73 20 73 75 62 73 65 71 75  if it is subsequ
16d40 65 6e 74 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63  ently rolled bac
16d50 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75  k..**.** This fu
16d60 6e 63 74 69 6f 6e 20 69 73 20 61 63 63 65 73 73  nction is access
16d70 69 62 6c 65 20 74 6f 20 53 51 4c 20 73 74 61 74  ible to SQL stat
16d80 65 6d 65 6e 74 73 20 76 69 61 20 74 68 65 0a 2a  ements via the.*
16d90 2a 20 5b 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72  * [last_insert_r
16da0 6f 77 69 64 28 29 20 53 51 4c 20 66 75 6e 63 74  owid() SQL funct
16db0 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61  ion]..**.** If a
16dc0 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64   separate thread
16dd0 20 70 65 72 66 6f 72 6d 73 20 61 20 6e 65 77 20   performs a new 
16de0 5b 49 4e 53 45 52 54 5d 20 6f 6e 20 74 68 65 20  [INSERT] on the 
16df0 73 61 6d 65 0a 2a 2a 20 64 61 74 61 62 61 73 65  same.** database
16e00 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c   connection whil
16e10 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c  e the [sqlite3_l
16e20 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
16e30 28 29 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ()].** function 
16e40 69 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20 74  is running and t
16e50 68 75 73 20 63 68 61 6e 67 65 73 20 74 68 65 20  hus changes the 
16e60 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77  last insert [row
16e70 69 64 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65  id],.** then the
16e80 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
16e90 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74  by [sqlite3_last
16ea0 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d  _insert_rowid()]
16eb0 20 69 73 0a 2a 2a 20 75 6e 70 72 65 64 69 63 74   is.** unpredict
16ec0 61 62 6c 65 20 61 6e 64 20 6d 69 67 68 74 20 6e  able and might n
16ed0 6f 74 20 65 71 75 61 6c 20 65 69 74 68 65 72 20  ot equal either 
16ee0 74 68 65 20 6f 6c 64 20 6f 72 20 74 68 65 20 6e  the old or the n
16ef0 65 77 0a 2a 2a 20 6c 61 73 74 20 69 6e 73 65 72  ew.** last inser
16f00 74 20 5b 72 6f 77 69 64 5d 2e 0a 2a 2f 0a 73 71  t [rowid]..*/.sq
16f10 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69  lite3_int64 sqli
16f20 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f  te3_last_insert_
16f30 72 6f 77 69 64 28 73 71 6c 69 74 65 33 2a 29 3b  rowid(sqlite3*);
16f40 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
16f50 3a 20 43 6f 75 6e 74 20 54 68 65 20 4e 75 6d 62  : Count The Numb
16f60 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66  er Of Rows Modif
16f70 69 65 64 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  ied.**.** ^This 
16f80 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
16f90 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 64   the number of d
16fa0 61 74 61 62 61 73 65 20 72 6f 77 73 20 74 68 61  atabase rows tha
16fb0 74 20 77 65 72 65 20 63 68 61 6e 67 65 64 0a 2a  t were changed.*
16fc0 2a 20 6f 72 20 69 6e 73 65 72 74 65 64 20 6f 72  * or inserted or
16fd0 20 64 65 6c 65 74 65 64 20 62 79 20 74 68 65 20   deleted by the 
16fe0 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f  most recently co
16ff0 6d 70 6c 65 74 65 64 20 53 51 4c 20 73 74 61 74  mpleted SQL stat
17000 65 6d 65 6e 74 0a 2a 2a 20 6f 6e 20 74 68 65 20  ement.** on the 
17010 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
17020 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20  tion] specified 
17030 62 79 20 74 68 65 20 66 69 72 73 74 20 70 61 72  by the first par
17040 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 28 4f 6e 6c  ameter..** ^(Onl
17050 79 20 63 68 61 6e 67 65 73 20 74 68 61 74 20 61  y changes that a
17060 72 65 20 64 69 72 65 63 74 6c 79 20 73 70 65 63  re directly spec
17070 69 66 69 65 64 20 62 79 20 74 68 65 20 5b 49 4e  ified by the [IN
17080 53 45 52 54 5d 2c 20 5b 55 50 44 41 54 45 5d 2c  SERT], [UPDATE],
17090 0a 2a 2a 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20  .** or [DELETE] 
170a0 73 74 61 74 65 6d 65 6e 74 20 61 72 65 20 63 6f  statement are co
170b0 75 6e 74 65 64 2e 20 20 41 75 78 69 6c 69 61 72  unted.  Auxiliar
170c0 79 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 64  y changes caused
170d0 20 62 79 0a 2a 2a 20 74 72 69 67 67 65 72 73 20   by.** triggers 
170e0 6f 72 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20  or [foreign key 
170f0 61 63 74 69 6f 6e 73 5d 20 61 72 65 20 6e 6f 74  actions] are not
17100 20 63 6f 75 6e 74 65 64 2e 29 5e 20 55 73 65 20   counted.)^ Use 
17110 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
17120 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d  total_changes()]
17130 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 66 69 6e   function to fin
17140 64 20 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62  d the total numb
17150 65 72 20 6f 66 20 63 68 61 6e 67 65 73 0a 2a 2a  er of changes.**
17160 20 69 6e 63 6c 75 64 69 6e 67 20 63 68 61 6e 67   including chang
17170 65 73 20 63 61 75 73 65 64 20 62 79 20 74 72 69  es caused by tri
17180 67 67 65 72 73 20 61 6e 64 20 66 6f 72 65 69 67  ggers and foreig
17190 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 2e 0a 2a  n key actions..*
171a0 2a 0a 2a 2a 20 5e 43 68 61 6e 67 65 73 20 74 6f  *.** ^Changes to
171b0 20 61 20 76 69 65 77 20 74 68 61 74 20 61 72 65   a view that are
171c0 20 73 69 6d 75 6c 61 74 65 64 20 62 79 20 61 6e   simulated by an
171d0 20 5b 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69   [INSTEAD OF tri
171e0 67 67 65 72 5d 0a 2a 2a 20 61 72 65 20 6e 6f 74  gger].** are not
171f0 20 63 6f 75 6e 74 65 64 2e 20 20 4f 6e 6c 79 20   counted.  Only 
17200 72 65 61 6c 20 74 61 62 6c 65 20 63 68 61 6e 67  real table chang
17210 65 73 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 0a  es are counted..
17220 2a 2a 0a 2a 2a 20 5e 28 41 20 22 72 6f 77 20 63  **.** ^(A "row c
17230 68 61 6e 67 65 22 20 69 73 20 61 20 63 68 61 6e  hange" is a chan
17240 67 65 20 74 6f 20 61 20 73 69 6e 67 6c 65 20 72  ge to a single r
17250 6f 77 20 6f 66 20 61 20 73 69 6e 67 6c 65 20 74  ow of a single t
17260 61 62 6c 65 0a 2a 2a 20 63 61 75 73 65 64 20 62  able.** caused b
17270 79 20 61 6e 20 49 4e 53 45 52 54 2c 20 44 45 4c  y an INSERT, DEL
17280 45 54 45 2c 20 6f 72 20 55 50 44 41 54 45 20 73  ETE, or UPDATE s
17290 74 61 74 65 6d 65 6e 74 2e 20 20 52 6f 77 73 20  tatement.  Rows 
172a0 74 68 61 74 0a 2a 2a 20 61 72 65 20 63 68 61 6e  that.** are chan
172b0 67 65 64 20 61 73 20 73 69 64 65 20 65 66 66 65  ged as side effe
172c0 63 74 73 20 6f 66 20 5b 52 45 50 4c 41 43 45 5d  cts of [REPLACE]
172d0 20 63 6f 6e 73 74 72 61 69 6e 74 20 72 65 73 6f   constraint reso
172e0 6c 75 74 69 6f 6e 2c 0a 2a 2a 20 72 6f 6c 6c 62  lution,.** rollb
172f0 61 63 6b 2c 20 41 42 4f 52 54 20 70 72 6f 63 65  ack, ABORT proce
17300 73 73 69 6e 67 2c 20 5b 44 52 4f 50 20 54 41 42  ssing, [DROP TAB
17310 4c 45 5d 2c 20 6f 72 20 62 79 20 61 6e 79 20 6f  LE], or by any o
17320 74 68 65 72 0a 2a 2a 20 6d 65 63 68 61 6e 69 73  ther.** mechanis
17330 6d 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20  ms do not count 
17340 61 73 20 64 69 72 65 63 74 20 72 6f 77 20 63 68  as direct row ch
17350 61 6e 67 65 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41  anges.)^.**.** A
17360 20 22 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78   "trigger contex
17370 74 22 20 69 73 20 61 20 73 63 6f 70 65 20 6f 66  t" is a scope of
17380 20 65 78 65 63 75 74 69 6f 6e 20 74 68 61 74 20   execution that 
17390 62 65 67 69 6e 73 20 61 6e 64 0a 2a 2a 20 65 6e  begins and.** en
173a0 64 73 20 77 69 74 68 20 74 68 65 20 73 63 72 69  ds with the scri
173b0 70 74 20 6f 66 20 61 20 5b 43 52 45 41 54 45 20  pt of a [CREATE 
173c0 54 52 49 47 47 45 52 20 7c 20 74 72 69 67 67 65  TRIGGER | trigge
173d0 72 5d 2e 20 0a 2a 2a 20 4d 6f 73 74 20 53 51 4c  r]. .** Most SQL
173e0 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 0a   statements are.
173f0 2a 2a 20 65 76 61 6c 75 61 74 65 64 20 6f 75 74  ** evaluated out
17400 73 69 64 65 20 6f 66 20 61 6e 79 20 74 72 69 67  side of any trig
17410 67 65 72 2e 20 20 54 68 69 73 20 69 73 20 74 68  ger.  This is th
17420 65 20 22 74 6f 70 20 6c 65 76 65 6c 22 0a 2a 2a  e "top level".**
17430 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74   trigger context
17440 2e 20 20 49 66 20 61 20 74 72 69 67 67 65 72 20  .  If a trigger 
17450 66 69 72 65 73 20 66 72 6f 6d 20 74 68 65 20 74  fires from the t
17460 6f 70 20 6c 65 76 65 6c 2c 20 61 0a 2a 2a 20 6e  op level, a.** n
17470 65 77 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65  ew trigger conte
17480 78 74 20 69 73 20 65 6e 74 65 72 65 64 20 66 6f  xt is entered fo
17490 72 20 74 68 65 20 64 75 72 61 74 69 6f 6e 20 6f  r the duration o
174a0 66 20 74 68 61 74 20 6f 6e 65 0a 2a 2a 20 74 72  f that one.** tr
174b0 69 67 67 65 72 2e 20 20 53 75 62 74 72 69 67 67  igger.  Subtrigg
174c0 65 72 73 20 63 72 65 61 74 65 20 73 75 62 63 6f  ers create subco
174d0 6e 74 65 78 74 73 20 66 6f 72 20 74 68 65 69 72  ntexts for their
174e0 20 64 75 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a   duration..**.**
174f0 20 5e 43 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74   ^Calling [sqlit
17500 65 33 5f 65 78 65 63 28 29 5d 20 6f 72 20 5b 73  e3_exec()] or [s
17510 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 72  qlite3_step()] r
17520 65 63 75 72 73 69 76 65 6c 79 20 64 6f 65 73 0a  ecursively does.
17530 2a 2a 20 6e 6f 74 20 63 72 65 61 74 65 20 61 20  ** not create a 
17540 6e 65 77 20 74 72 69 67 67 65 72 20 63 6f 6e 74  new trigger cont
17550 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  ext..**.** ^This
17560 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
17570 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
17580 64 69 72 65 63 74 20 72 6f 77 20 63 68 61 6e 67  direct row chang
17590 65 73 20 69 6e 20 74 68 65 0a 2a 2a 20 6d 6f 73  es in the.** mos
175a0 74 20 72 65 63 65 6e 74 20 49 4e 53 45 52 54 2c  t recent INSERT,
175b0 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45   UPDATE, or DELE
175c0 54 45 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74  TE statement wit
175d0 68 69 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20  hin the same.** 
175e0 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e  trigger context.
175f0 0a 2a 2a 0a 2a 2a 20 5e 54 68 75 73 2c 20 77 68  .**.** ^Thus, wh
17600 65 6e 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74  en called from t
17610 68 65 20 74 6f 70 20 6c 65 76 65 6c 2c 20 74 68  he top level, th
17620 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  is function retu
17630 72 6e 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65  rns the.** numbe
17640 72 20 6f 66 20 63 68 61 6e 67 65 73 20 69 6e 20  r of changes in 
17650 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
17660 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20  INSERT, UPDATE, 
17670 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61  or DELETE.** tha
17680 74 20 61 6c 73 6f 20 6f 63 63 75 72 72 65 64 20  t also occurred 
17690 61 74 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c  at the top level
176a0 2e 20 20 5e 28 57 69 74 68 69 6e 20 74 68 65 20  .  ^(Within the 
176b0 62 6f 64 79 20 6f 66 20 61 20 74 72 69 67 67 65  body of a trigge
176c0 72 2c 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65  r,.** the sqlite
176d0 33 5f 63 68 61 6e 67 65 73 28 29 20 69 6e 74 65  3_changes() inte
176e0 72 66 61 63 65 20 63 61 6e 20 62 65 20 63 61 6c  rface can be cal
176f0 6c 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20  led to find the 
17700 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61  number of.** cha
17710 6e 67 65 73 20 69 6e 20 74 68 65 20 6d 6f 73 74  nges in the most
17720 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65   recently comple
17730 74 65 64 20 49 4e 53 45 52 54 2c 20 55 50 44 41  ted INSERT, UPDA
17740 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a  TE, or DELETE.**
17750 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69   statement withi
17760 6e 20 74 68 65 20 62 6f 64 79 20 6f 66 20 74 68  n the body of th
17770 65 20 73 61 6d 65 20 74 72 69 67 67 65 72 2e 0a  e same trigger..
17780 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20  ** However, the 
17790 6e 75 6d 62 65 72 20 72 65 74 75 72 6e 65 64 20  number returned 
177a0 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65  does not include
177b0 20 63 68 61 6e 67 65 73 0a 2a 2a 20 63 61 75 73   changes.** caus
177c0 65 64 20 62 79 20 73 75 62 74 72 69 67 67 65 72  ed by subtrigger
177d0 73 20 73 69 6e 63 65 20 74 68 6f 73 65 20 68 61  s since those ha
177e0 76 65 20 74 68 65 69 72 20 6f 77 6e 20 63 6f 6e  ve their own con
177f0 74 65 78 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65  text.)^.**.** Se
17800 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69  e also the [sqli
17810 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
17820 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2c 20  s()] interface, 
17830 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68  the.** [count_ch
17840 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c 20 61  anges pragma], a
17850 6e 64 20 74 68 65 20 5b 63 68 61 6e 67 65 73 28  nd the [changes(
17860 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e  ) SQL function].
17870 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61  .**.** If a sepa
17880 72 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65  rate thread make
17890 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65  s changes on the
178a0 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63   same database c
178b0 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69  onnection.** whi
178c0 6c 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e  le [sqlite3_chan
178d0 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e  ges()] is runnin
178e0 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65  g then the value
178f0 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 69 73 20   returned.** is 
17900 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e  unpredictable an
17910 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c  d not meaningful
17920 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
17930 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33  _changes(sqlite3
17940 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
17950 52 45 46 3a 20 54 6f 74 61 6c 20 4e 75 6d 62 65  REF: Total Numbe
17960 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69  r Of Rows Modifi
17970 65 64 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66  ed.**.** ^This f
17980 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
17990 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f  the number of ro
179a0 77 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 64  w changes caused
179b0 20 62 79 20 5b 49 4e 53 45 52 54 5d 2c 0a 2a 2a   by [INSERT],.**
179c0 20 5b 55 50 44 41 54 45 5d 20 6f 72 20 5b 44 45   [UPDATE] or [DE
179d0 4c 45 54 45 5d 20 73 74 61 74 65 6d 65 6e 74 73  LETE] statements
179e0 20 73 69 6e 63 65 20 74 68 65 20 5b 64 61 74 61   since the [data
179f0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
17a00 20 77 61 73 20 6f 70 65 6e 65 64 2e 0a 2a 2a 20   was opened..** 
17a10 5e 28 54 68 65 20 63 6f 75 6e 74 20 72 65 74 75  ^(The count retu
17a20 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
17a30 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 20  total_changes() 
17a40 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 63 68 61  includes all cha
17a50 6e 67 65 73 0a 2a 2a 20 66 72 6f 6d 20 61 6c 6c  nges.** from all
17a60 20 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 52   [CREATE TRIGGER
17a70 20 7c 20 74 72 69 67 67 65 72 5d 20 63 6f 6e 74   | trigger] cont
17a80 65 78 74 73 20 61 6e 64 20 63 68 61 6e 67 65 73  exts and changes
17a90 20 6d 61 64 65 20 62 79 0a 2a 2a 20 5b 66 6f 72   made by.** [for
17aa0 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73  eign key actions
17ab0 5d 2e 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 74  ]. However,.** t
17ac0 68 65 20 63 6f 75 6e 74 20 64 6f 65 73 20 6e 6f  he count does no
17ad0 74 20 69 6e 63 6c 75 64 65 20 63 68 61 6e 67 65  t include change
17ae0 73 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d  s used to implem
17af0 65 6e 74 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f  ent [REPLACE] co
17b00 6e 73 74 72 61 69 6e 74 73 2c 0a 2a 2a 20 64 6f  nstraints,.** do
17b10 20 72 6f 6c 6c 62 61 63 6b 73 20 6f 72 20 41 42   rollbacks or AB
17b20 4f 52 54 20 70 72 6f 63 65 73 73 69 6e 67 2c 20  ORT processing, 
17b30 6f 72 20 5b 44 52 4f 50 20 54 41 42 4c 45 5d 20  or [DROP TABLE] 
17b40 70 72 6f 63 65 73 73 69 6e 67 2e 20 20 54 68 65  processing.  The
17b50 0a 2a 2a 20 63 6f 75 6e 74 20 64 6f 65 73 20 6e  .** count does n
17b60 6f 74 20 69 6e 63 6c 75 64 65 20 72 6f 77 73 20  ot include rows 
17b70 6f 66 20 76 69 65 77 73 20 74 68 61 74 20 66 69  of views that fi
17b80 72 65 20 61 6e 20 5b 49 4e 53 54 45 41 44 20 4f  re an [INSTEAD O
17b90 46 20 74 72 69 67 67 65 72 5d 2c 0a 2a 2a 20 74  F trigger],.** t
17ba0 68 6f 75 67 68 20 69 66 20 74 68 65 20 49 4e 53  hough if the INS
17bb0 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 72 20  TEAD OF trigger 
17bc0 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 66  makes changes of
17bd0 20 69 74 73 20 6f 77 6e 2c 20 74 68 6f 73 65 20   its own, those 
17be0 63 68 61 6e 67 65 73 20 0a 2a 2a 20 61 72 65 20  changes .** are 
17bf0 63 6f 75 6e 74 65 64 2e 29 5e 0a 2a 2a 20 5e 54  counted.)^.** ^T
17c00 68 65 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c  he sqlite3_total
17c10 5f 63 68 61 6e 67 65 73 28 29 20 66 75 6e 63 74  _changes() funct
17c20 69 6f 6e 20 63 6f 75 6e 74 73 20 74 68 65 20 63  ion counts the c
17c30 68 61 6e 67 65 73 20 61 73 20 73 6f 6f 6e 20 61  hanges as soon a
17c40 73 0a 2a 2a 20 74 68 65 20 73 74 61 74 65 6d 65  s.** the stateme
17c50 6e 74 20 74 68 61 74 20 6d 61 6b 65 73 20 74 68  nt that makes th
17c60 65 6d 20 69 73 20 63 6f 6d 70 6c 65 74 65 64 20  em is completed 
17c70 28 77 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d  (when the statem
17c80 65 6e 74 20 68 61 6e 64 6c 65 0a 2a 2a 20 69 73  ent handle.** is
17c90 20 70 61 73 73 65 64 20 74 6f 20 5b 73 71 6c 69   passed to [sqli
17ca0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20  te3_reset()] or 
17cb0 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
17cc0 65 28 29 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  e()])..**.** See
17cd0 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74   also the [sqlit
17ce0 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e  e3_changes()] in
17cf0 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20  terface, the.** 
17d00 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70  [count_changes p
17d10 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20  ragma], and the 
17d20 5b 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29  [total_changes()
17d30 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a   SQL function]..
17d40 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72  **.** If a separ
17d50 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73  ate thread makes
17d60 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20   changes on the 
17d70 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f  same database co
17d80 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c  nnection.** whil
17d90 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c  e [sqlite3_total
17da0 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72  _changes()] is r
17db0 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20  unning then the 
17dc0 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65  value.** returne
17dd0 64 20 69 73 20 75 6e 70 72 65 64 69 63 74 61 62  d is unpredictab
17de0 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69  le and not meani
17df0 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ngful..*/.int sq
17e00 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e  lite3_total_chan
17e10 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  ges(sqlite3*);..
17e20 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
17e30 49 6e 74 65 72 72 75 70 74 20 41 20 4c 6f 6e 67  Interrupt A Long
17e40 2d 52 75 6e 6e 69 6e 67 20 51 75 65 72 79 0a 2a  -Running Query.*
17e50 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74  *.** ^This funct
17e60 69 6f 6e 20 63 61 75 73 65 73 20 61 6e 79 20 70  ion causes any p
17e70 65 6e 64 69 6e 67 20 64 61 74 61 62 61 73 65 20  ending database 
17e80 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 61 62 6f  operation to abo
17e90 72 74 20 61 6e 64 0a 2a 2a 20 72 65 74 75 72 6e  rt and.** return
17ea0 20 61 74 20 69 74 73 20 65 61 72 6c 69 65 73 74   at its earliest
17eb0 20 6f 70 70 6f 72 74 75 6e 69 74 79 2e 20 54 68   opportunity. Th
17ec0 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 74 79  is routine is ty
17ed0 70 69 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65  pically.** calle
17ee0 64 20 69 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f  d in response to
17ef0 20 61 20 75 73 65 72 20 61 63 74 69 6f 6e 20 73   a user action s
17f00 75 63 68 20 61 73 20 70 72 65 73 73 69 6e 67 20  uch as pressing 
17f10 22 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43  "Cancel".** or C
17f20 74 72 6c 2d 43 20 77 68 65 72 65 20 74 68 65 20  trl-C where the 
17f30 75 73 65 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e  user wants a lon
17f40 67 20 71 75 65 72 79 20 6f 70 65 72 61 74 69 6f  g query operatio
17f50 6e 20 74 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d  n to halt.** imm
17f60 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20  ediately..**.** 
17f70 5e 49 74 20 69 73 20 73 61 66 65 20 74 6f 20 63  ^It is safe to c
17f80 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65  all this routine
17f90 20 66 72 6f 6d 20 61 20 74 68 72 65 61 64 20 64   from a thread d
17fa0 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 74 68  ifferent from th
17fb0 65 0a 2a 2a 20 74 68 72 65 61 64 20 74 68 61 74  e.** thread that
17fc0 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 72 75   is currently ru
17fd0 6e 6e 69 6e 67 20 74 68 65 20 64 61 74 61 62 61  nning the databa
17fe0 73 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20 42  se operation.  B
17ff0 75 74 20 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 20  ut it.** is not 
18000 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69  safe to call thi
18010 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61  s routine with a
18020 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
18030 63 74 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20 69  ction] that.** i
18040 73 20 63 6c 6f 73 65 64 20 6f 72 20 6d 69 67 68  s closed or migh
18050 74 20 63 6c 6f 73 65 20 62 65 66 6f 72 65 20 73  t close before s
18060 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
18070 28 29 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a  () returns..**.*
18080 2a 20 5e 49 66 20 61 6e 20 53 51 4c 20 6f 70 65  * ^If an SQL ope
18090 72 61 74 69 6f 6e 20 69 73 20 76 65 72 79 20 6e  ration is very n
180a0 65 61 72 6c 79 20 66 69 6e 69 73 68 65 64 20 61  early finished a
180b0 74 20 74 68 65 20 74 69 6d 65 20 77 68 65 6e 0a  t the time when.
180c0 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  ** sqlite3_inter
180d0 72 75 70 74 28 29 20 69 73 20 63 61 6c 6c 65 64  rupt() is called
180e0 2c 20 74 68 65 6e 20 69 74 20 6d 69 67 68 74 20  , then it might 
180f0 6e 6f 74 20 68 61 76 65 20 61 6e 20 6f 70 70 6f  not have an oppo
18100 72 74 75 6e 69 74 79 0a 2a 2a 20 74 6f 20 62 65  rtunity.** to be
18110 20 69 6e 74 65 72 72 75 70 74 65 64 20 61 6e 64   interrupted and
18120 20 6d 69 67 68 74 20 63 6f 6e 74 69 6e 75 65 20   might continue 
18130 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a  to completion..*
18140 2a 0a 2a 2a 20 5e 41 6e 20 53 51 4c 20 6f 70 65  *.** ^An SQL ope
18150 72 61 74 69 6f 6e 20 74 68 61 74 20 69 73 20 69  ration that is i
18160 6e 74 65 72 72 75 70 74 65 64 20 77 69 6c 6c 20  nterrupted will 
18170 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49  return [SQLITE_I
18180 4e 54 45 52 52 55 50 54 5d 2e 0a 2a 2a 20 5e 49  NTERRUPT]..** ^I
18190 66 20 74 68 65 20 69 6e 74 65 72 72 75 70 74 65  f the interrupte
181a0 64 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20  d SQL operation 
181b0 69 73 20 61 6e 20 49 4e 53 45 52 54 2c 20 55 50  is an INSERT, UP
181c0 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a  DATE, or DELETE.
181d0 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 73 69 64  ** that is insid
181e0 65 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72  e an explicit tr
181f0 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20  ansaction, then 
18200 74 68 65 20 65 6e 74 69 72 65 20 74 72 61 6e 73  the entire trans
18210 61 63 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62  action.** will b
18220 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75  e rolled back au
18230 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a  tomatically..**.
18240 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
18250 69 6e 74 65 72 72 75 70 74 28 44 29 20 63 61 6c  interrupt(D) cal
18260 6c 20 69 73 20 69 6e 20 65 66 66 65 63 74 20 75  l is in effect u
18270 6e 74 69 6c 20 61 6c 6c 20 63 75 72 72 65 6e 74  ntil all current
18280 6c 79 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51  ly running.** SQ
18290 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 6e 20  L statements on 
182a0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
182b0 74 69 6f 6e 5d 20 44 20 63 6f 6d 70 6c 65 74 65  tion] D complete
182c0 2e 20 20 5e 41 6e 79 20 6e 65 77 20 53 51 4c 20  .  ^Any new SQL 
182d0 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68  statements.** th
182e0 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61  at are started a
182f0 66 74 65 72 20 74 68 65 20 73 71 6c 69 74 65 33  fter the sqlite3
18300 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c  _interrupt() cal
18310 6c 20 61 6e 64 20 62 65 66 6f 72 65 20 74 68 65  l and before the
18320 20 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 73 74 61   .** running sta
18330 74 65 6d 65 6e 74 73 20 72 65 61 63 68 65 73 20  tements reaches 
18340 7a 65 72 6f 20 61 72 65 20 69 6e 74 65 72 72 75  zero are interru
18350 70 74 65 64 20 61 73 20 69 66 20 74 68 65 79 20  pted as if they 
18360 68 61 64 20 62 65 65 6e 0a 2a 2a 20 72 75 6e 6e  had been.** runn
18370 69 6e 67 20 70 72 69 6f 72 20 74 6f 20 74 68 65  ing prior to the
18380 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
18390 70 74 28 29 20 63 61 6c 6c 2e 20 20 5e 4e 65 77  pt() call.  ^New
183a0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a   SQL statements.
183b0 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72  ** that are star
183c0 74 65 64 20 61 66 74 65 72 20 74 68 65 20 72 75  ted after the ru
183d0 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20  nning statement 
183e0 63 6f 75 6e 74 20 72 65 61 63 68 65 73 20 7a 65  count reaches ze
183f0 72 6f 20 61 72 65 0a 2a 2a 20 6e 6f 74 20 65 66  ro are.** not ef
18400 66 65 63 74 65 64 20 62 79 20 74 68 65 20 73 71  fected by the sq
18410 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
18420 29 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f  )..** ^A call to
18430 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
18440 70 74 28 44 29 20 74 68 61 74 20 6f 63 63 75 72  pt(D) that occur
18450 73 20 77 68 65 6e 20 74 68 65 72 65 20 61 72 65  s when there are
18460 20 6e 6f 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53   no running.** S
18470 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69 73  QL statements is
18480 20 61 20 6e 6f 2d 6f 70 20 61 6e 64 20 68 61 73   a no-op and has
18490 20 6e 6f 20 65 66 66 65 63 74 20 6f 6e 20 53 51   no effect on SQ
184a0 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  L statements.** 
184b0 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64  that are started
184c0 20 61 66 74 65 72 20 74 68 65 20 73 71 6c 69 74   after the sqlit
184d0 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63  e3_interrupt() c
184e0 61 6c 6c 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a  all returns..**.
184f0 2a 2a 20 49 66 20 74 68 65 20 64 61 74 61 62 61  ** If the databa
18500 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c  se connection cl
18510 6f 73 65 73 20 77 68 69 6c 65 20 5b 73 71 6c 69  oses while [sqli
18520 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 5d  te3_interrupt()]
18530 0a 2a 2a 20 69 73 20 72 75 6e 6e 69 6e 67 20 74  .** is running t
18540 68 65 6e 20 62 61 64 20 74 68 69 6e 67 73 20 77  hen bad things w
18550 69 6c 6c 20 6c 69 6b 65 6c 79 20 68 61 70 70 65  ill likely happe
18560 6e 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74  n..*/.void sqlit
18570 65 33 5f 69 6e 74 65 72 72 75 70 74 28 73 71 6c  e3_interrupt(sql
18580 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
18590 41 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69  API3REF: Determi
185a0 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61  ne If An SQL Sta
185b0 74 65 6d 65 6e 74 20 49 73 20 43 6f 6d 70 6c 65  tement Is Comple
185c0 74 65 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  te.**.** These r
185d0 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 66  outines are usef
185e0 75 6c 20 64 75 72 69 6e 67 20 63 6f 6d 6d 61 6e  ul during comman
185f0 64 2d 6c 69 6e 65 20 69 6e 70 75 74 20 74 6f 20  d-line input to 
18600 64 65 74 65 72 6d 69 6e 65 20 69 66 20 74 68 65  determine if the
18610 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 65 6e  .** currently en
18620 74 65 72 65 64 20 74 65 78 74 20 73 65 65 6d 73  tered text seems
18630 20 74 6f 20 66 6f 72 6d 20 61 20 63 6f 6d 70 6c   to form a compl
18640 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ete SQL statemen
18650 74 20 6f 72 0a 2a 2a 20 69 66 20 61 64 64 69 74  t or.** if addit
18660 69 6f 6e 61 6c 20 69 6e 70 75 74 20 69 73 20 6e  ional input is n
18670 65 65 64 65 64 20 62 65 66 6f 72 65 20 73 65 6e  eeded before sen
18680 64 69 6e 67 20 74 68 65 20 74 65 78 74 20 69 6e  ding the text in
18690 74 6f 0a 2a 2a 20 53 51 4c 69 74 65 20 66 6f 72  to.** SQLite for
186a0 20 70 61 72 73 69 6e 67 2e 20 20 5e 54 68 65 73   parsing.  ^Thes
186b0 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  e routines retur
186c0 6e 20 31 20 69 66 20 74 68 65 20 69 6e 70 75 74  n 1 if the input
186d0 20 73 74 72 69 6e 67 0a 2a 2a 20 61 70 70 65 61   string.** appea
186e0 72 73 20 74 6f 20 62 65 20 61 20 63 6f 6d 70 6c  rs to be a compl
186f0 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ete SQL statemen
18700 74 2e 20 20 5e 41 20 73 74 61 74 65 6d 65 6e 74  t.  ^A statement
18710 20 69 73 20 6a 75 64 67 65 64 20 74 6f 20 62 65   is judged to be
18720 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 69 66 20  .** complete if 
18730 69 74 20 65 6e 64 73 20 77 69 74 68 20 61 20 73  it ends with a s
18740 65 6d 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61  emicolon token a
18750 6e 64 20 69 73 20 6e 6f 74 20 61 20 70 72 65 66  nd is not a pref
18760 69 78 20 6f 66 20 61 0a 2a 2a 20 77 65 6c 6c 2d  ix of a.** well-
18770 66 6f 72 6d 65 64 20 43 52 45 41 54 45 20 54 52  formed CREATE TR
18780 49 47 47 45 52 20 73 74 61 74 65 6d 65 6e 74 2e  IGGER statement.
18790 20 20 5e 53 65 6d 69 63 6f 6c 6f 6e 73 20 74 68    ^Semicolons th
187a0 61 74 20 61 72 65 20 65 6d 62 65 64 64 65 64 20  at are embedded 
187b0 77 69 74 68 69 6e 0a 2a 2a 20 73 74 72 69 6e 67  within.** string
187c0 20 6c 69 74 65 72 61 6c 73 20 6f 72 20 71 75 6f   literals or quo
187d0 74 65 64 20 69 64 65 6e 74 69 66 69 65 72 20 6e  ted identifier n
187e0 61 6d 65 73 20 6f 72 20 63 6f 6d 6d 65 6e 74 73  ames or comments
187f0 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65   are not.** inde
18800 70 65 6e 64 65 6e 74 20 74 6f 6b 65 6e 73 20 28  pendent tokens (
18810 74 68 65 79 20 61 72 65 20 70 61 72 74 20 6f 66  they are part of
18820 20 74 68 65 20 74 6f 6b 65 6e 20 69 6e 20 77 68   the token in wh
18830 69 63 68 20 74 68 65 79 20 61 72 65 0a 2a 2a 20  ich they are.** 
18840 65 6d 62 65 64 64 65 64 29 20 61 6e 64 20 74 68  embedded) and th
18850 75 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20  us do not count 
18860 61 73 20 61 20 73 74 61 74 65 6d 65 6e 74 20 74  as a statement t
18870 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 57 68 69  erminator.  ^Whi
18880 74 65 73 70 61 63 65 0a 2a 2a 20 61 6e 64 20 63  tespace.** and c
18890 6f 6d 6d 65 6e 74 73 20 74 68 61 74 20 66 6f 6c  omments that fol
188a0 6c 6f 77 20 74 68 65 20 66 69 6e 61 6c 20 73 65  low the final se
188b0 6d 69 63 6f 6c 6f 6e 20 61 72 65 20 69 67 6e 6f  micolon are igno
188c0 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  red..**.** ^Thes
188d0 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  e routines retur
188e0 6e 20 30 20 69 66 20 74 68 65 20 73 74 61 74 65  n 0 if the state
188f0 6d 65 6e 74 20 69 73 20 69 6e 63 6f 6d 70 6c 65  ment is incomple
18900 74 65 2e 20 20 5e 49 66 20 61 0a 2a 2a 20 6d 65  te.  ^If a.** me
18910 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
18920 66 61 69 6c 73 2c 20 74 68 65 6e 20 53 51 4c 49  fails, then SQLI
18930 54 45 5f 4e 4f 4d 45 4d 20 69 73 20 72 65 74 75  TE_NOMEM is retu
18940 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  rned..**.** ^The
18950 73 65 20 72 6f 75 74 69 6e 65 73 20 64 6f 20 6e  se routines do n
18960 6f 74 20 70 61 72 73 65 20 74 68 65 20 53 51 4c  ot parse the SQL
18970 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 75 73   statements thus
18980 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20 64 65 74  .** will not det
18990 65 63 74 20 73 79 6e 74 61 63 74 69 63 61 6c 6c  ect syntacticall
189a0 79 20 69 6e 63 6f 72 72 65 63 74 20 53 51 4c 2e  y incorrect SQL.
189b0 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 53 51 4c 69  .**.** ^(If SQLi
189c0 74 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20  te has not been 
189d0 69 6e 69 74 69 61 6c 69 7a 65 64 20 75 73 69 6e  initialized usin
189e0 67 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  g [sqlite3_initi
189f0 61 6c 69 7a 65 28 29 5d 20 70 72 69 6f 72 20 0a  alize()] prior .
18a00 2a 2a 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 20 73  ** to invoking s
18a10 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31  qlite3_complete1
18a20 36 28 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33  6() then sqlite3
18a30 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73  _initialize() is
18a40 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 75 74 6f   invoked.** auto
18a50 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c  matically by sql
18a60 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28  ite3_complete16(
18a70 29 2e 20 20 49 66 20 74 68 61 74 20 69 6e 69 74  ).  If that init
18a80 69 61 6c 69 7a 61 74 69 6f 6e 20 66 61 69 6c 73  ialization fails
18a90 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 72 65  ,.** then the re
18aa0 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20  turn value from 
18ab0 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
18ac0 31 36 28 29 20 77 69 6c 6c 20 62 65 20 6e 6f 6e  16() will be non
18ad0 2d 7a 65 72 6f 0a 2a 2a 20 72 65 67 61 72 64 6c  -zero.** regardl
18ae0 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f  ess of whether o
18af0 72 20 6e 6f 74 20 74 68 65 20 69 6e 70 75 74 20  r not the input 
18b00 53 51 4c 20 69 73 20 63 6f 6d 70 6c 65 74 65 2e  SQL is complete.
18b10 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70  )^.**.** The inp
18b20 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ut to [sqlite3_c
18b30 6f 6d 70 6c 65 74 65 28 29 5d 20 6d 75 73 74 20  omplete()] must 
18b40 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  be a zero-termin
18b50 61 74 65 64 0a 2a 2a 20 55 54 46 2d 38 20 73 74  ated.** UTF-8 st
18b60 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ring..**.** The 
18b70 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65  input to [sqlite
18b80 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 5d 20  3_complete16()] 
18b90 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74  must be a zero-t
18ba0 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46  erminated.** UTF
18bb0 2d 31 36 20 73 74 72 69 6e 67 20 69 6e 20 6e 61  -16 string in na
18bc0 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e  tive byte order.
18bd0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
18be0 63 6f 6d 70 6c 65 74 65 28 63 6f 6e 73 74 20 63  complete(const c
18bf0 68 61 72 20 2a 73 71 6c 29 3b 0a 69 6e 74 20 73  har *sql);.int s
18c00 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31  qlite3_complete1
18c10 36 28 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  6(const void *sq
18c20 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  l);../*.** CAPI3
18c30 52 45 46 3a 20 52 65 67 69 73 74 65 72 20 41 20  REF: Register A 
18c40 43 61 6c 6c 62 61 63 6b 20 54 6f 20 48 61 6e 64  Callback To Hand
18c50 6c 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 45  le SQLITE_BUSY E
18c60 72 72 6f 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  rrors.**.** ^Thi
18c70 73 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61  s routine sets a
18c80 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
18c90 6f 6e 20 74 68 61 74 20 6d 69 67 68 74 20 62 65  on that might be
18ca0 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65   invoked wheneve
18cb0 72 0a 2a 2a 20 61 6e 20 61 74 74 65 6d 70 74 20  r.** an attempt 
18cc0 69 73 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20  is made to open 
18cd0 61 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65  a database table
18ce0 20 74 68 61 74 20 61 6e 6f 74 68 65 72 20 74 68   that another th
18cf0 72 65 61 64 0a 2a 2a 20 6f 72 20 70 72 6f 63 65  read.** or proce
18d00 73 73 20 68 61 73 20 6c 6f 63 6b 65 64 2e 0a 2a  ss has locked..*
18d10 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 62 75 73  *.** ^If the bus
18d20 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55  y callback is NU
18d30 4c 4c 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45  LL, then [SQLITE
18d40 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54  _BUSY] or [SQLIT
18d50 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d  E_IOERR_BLOCKED]
18d60 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20  .** is returned 
18d70 69 6d 6d 65 64 69 61 74 65 6c 79 20 75 70 6f 6e  immediately upon
18d80 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20 74 68   encountering th
18d90 65 20 6c 6f 63 6b 2e 20 20 5e 49 66 20 74 68 65  e lock.  ^If the
18da0 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 0a 2a   busy callback.*
18db0 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74  * is not NULL, t
18dc0 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  hen the callback
18dd0 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65   might be invoke
18de0 64 20 77 69 74 68 20 74 77 6f 20 61 72 67 75 6d  d with two argum
18df0 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ents..**.** ^The
18e00 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
18e10 74 6f 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  to the busy hand
18e20 6c 65 72 20 69 73 20 61 20 63 6f 70 79 20 6f 66  ler is a copy of
18e30 20 74 68 65 20 76 6f 69 64 2a 20 70 6f 69 6e 74   the void* point
18e40 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 74  er which.** is t
18e50 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
18e60 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 75 73  t to sqlite3_bus
18e70 79 5f 68 61 6e 64 6c 65 72 28 29 2e 20 20 5e 54  y_handler().  ^T
18e80 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
18e90 6e 74 20 74 6f 0a 2a 2a 20 74 68 65 20 62 75 73  nt to.** the bus
18ea0 79 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61  y handler callba
18eb0 63 6b 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72  ck is the number
18ec0 20 6f 66 20 74 69 6d 65 73 20 74 68 61 74 20 74   of times that t
18ed0 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  he busy handler 
18ee0 68 61 73 0a 2a 2a 20 62 65 65 6e 20 69 6e 76 6f  has.** been invo
18ef0 6b 65 64 20 66 6f 72 20 74 68 69 73 20 6c 6f 63  ked for this loc
18f00 6b 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66  king event.  ^If
18f10 20 74 68 65 0a 2a 2a 20 62 75 73 79 20 63 61 6c   the.** busy cal
18f20 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 30 2c  lback returns 0,
18f30 20 74 68 65 6e 20 6e 6f 20 61 64 64 69 74 69 6f   then no additio
18f40 6e 61 6c 20 61 74 74 65 6d 70 74 73 20 61 72 65  nal attempts are
18f50 20 6d 61 64 65 20 74 6f 0a 2a 2a 20 61 63 63 65   made to.** acce
18f60 73 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ss the database 
18f70 61 6e 64 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  and [SQLITE_BUSY
18f80 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45  ] or [SQLITE_IOE
18f90 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 73 20 72  RR_BLOCKED] is r
18fa0 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 49 66 20  eturned..** ^If 
18fb0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  the callback ret
18fc0 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74  urns non-zero, t
18fd0 68 65 6e 20 61 6e 6f 74 68 65 72 20 61 74 74 65  hen another atte
18fe0 6d 70 74 0a 2a 2a 20 69 73 20 6d 61 64 65 20 74  mpt.** is made t
18ff0 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62  o open the datab
19000 61 73 65 20 66 6f 72 20 72 65 61 64 69 6e 67 20  ase for reading 
19010 61 6e 64 20 74 68 65 20 63 79 63 6c 65 20 72 65  and the cycle re
19020 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  peats..**.** The
19030 20 70 72 65 73 65 6e 63 65 20 6f 66 20 61 20 62   presence of a b
19040 75 73 79 20 68 61 6e 64 6c 65 72 20 64 6f 65 73  usy handler does
19050 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 20 74   not guarantee t
19060 68 61 74 20 69 74 20 77 69 6c 6c 20 62 65 20 69  hat it will be i
19070 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e 20 74  nvoked.** when t
19080 68 65 72 65 20 69 73 20 6c 6f 63 6b 20 63 6f 6e  here is lock con
19090 74 65 6e 74 69 6f 6e 2e 20 5e 49 66 20 53 51 4c  tention. ^If SQL
190a0 69 74 65 20 64 65 74 65 72 6d 69 6e 65 73 20 74  ite determines t
190b0 68 61 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65  hat invoking the
190c0 20 62 75 73 79 0a 2a 2a 20 68 61 6e 64 6c 65 72   busy.** handler
190d0 20 63 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e   could result in
190e0 20 61 20 64 65 61 64 6c 6f 63 6b 2c 20 69 74 20   a deadlock, it 
190f0 77 69 6c 6c 20 67 6f 20 61 68 65 61 64 20 61 6e  will go ahead an
19100 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  d return [SQLITE
19110 5f 42 55 53 59 5d 0a 2a 2a 20 6f 72 20 5b 53 51  _BUSY].** or [SQ
19120 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b  LITE_IOERR_BLOCK
19130 45 44 5d 20 69 6e 73 74 65 61 64 20 6f 66 20 69  ED] instead of i
19140 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79  nvoking the busy
19150 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e   handler..** Con
19160 73 69 64 65 72 20 61 20 73 63 65 6e 61 72 69 6f  sider a scenario
19170 20 77 68 65 72 65 20 6f 6e 65 20 70 72 6f 63 65   where one proce
19180 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20  ss is holding a 
19190 72 65 61 64 20 6c 6f 63 6b 20 74 68 61 74 0a 2a  read lock that.*
191a0 2a 20 69 74 20 69 73 20 74 72 79 69 6e 67 20 74  * it is trying t
191b0 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 20 72  o promote to a r
191c0 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 61 6e 64  eserved lock and
191d0 0a 2a 2a 20 61 20 73 65 63 6f 6e 64 20 70 72 6f  .** a second pro
191e0 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20  cess is holding 
191f0 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20  a reserved lock 
19200 74 68 61 74 20 69 74 20 69 73 20 74 72 79 69 6e  that it is tryin
19210 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20  g.** to promote 
19220 74 6f 20 61 6e 20 65 78 63 6c 75 73 69 76 65 20  to an exclusive 
19230 6c 6f 63 6b 2e 20 20 54 68 65 20 66 69 72 73 74  lock.  The first
19240 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 20   process cannot 
19250 70 72 6f 63 65 65 64 0a 2a 2a 20 62 65 63 61 75  proceed.** becau
19260 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64  se it is blocked
19270 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 61   by the second a
19280 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72  nd the second pr
19290 6f 63 65 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20  ocess cannot.** 
192a0 70 72 6f 63 65 65 64 20 62 65 63 61 75 73 65 20  proceed because 
192b0 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79  it is blocked by
192c0 20 74 68 65 20 66 69 72 73 74 2e 20 20 49 66 20   the first.  If 
192d0 62 6f 74 68 20 70 72 6f 63 65 73 73 65 73 0a 2a  both processes.*
192e0 2a 20 69 6e 76 6f 6b 65 20 74 68 65 20 62 75 73  * invoke the bus
192f0 79 20 68 61 6e 64 6c 65 72 73 2c 20 6e 65 69 74  y handlers, neit
19300 68 65 72 20 77 69 6c 6c 20 6d 61 6b 65 20 61 6e  her will make an
19310 79 20 70 72 6f 67 72 65 73 73 2e 20 20 54 68 65  y progress.  The
19320 72 65 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69 74  refore,.** SQLit
19330 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  e returns [SQLIT
19340 45 5f 42 55 53 59 5d 20 66 6f 72 20 74 68 65 20  E_BUSY] for the 
19350 66 69 72 73 74 20 70 72 6f 63 65 73 73 2c 20 68  first process, h
19360 6f 70 69 6e 67 20 74 68 61 74 20 74 68 69 73 0a  oping that this.
19370 2a 2a 20 77 69 6c 6c 20 69 6e 64 75 63 65 20 74  ** will induce t
19380 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73  he first process
19390 20 74 6f 20 72 65 6c 65 61 73 65 20 69 74 73 20   to release its 
193a0 72 65 61 64 20 6c 6f 63 6b 20 61 6e 64 20 61 6c  read lock and al
193b0 6c 6f 77 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e  low.** the secon
193c0 64 20 70 72 6f 63 65 73 73 20 74 6f 20 70 72 6f  d process to pro
193d0 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ceed..**.** ^The
193e0 20 64 65 66 61 75 6c 74 20 62 75 73 79 20 63 61   default busy ca
193f0 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a  llback is NULL..
19400 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  **.** ^The [SQLI
19410 54 45 5f 42 55 53 59 5d 20 65 72 72 6f 72 20 69  TE_BUSY] error i
19420 73 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 5b  s converted to [
19430 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f  SQLITE_IOERR_BLO
19440 43 4b 45 44 5d 0a 2a 2a 20 77 68 65 6e 20 53 51  CKED].** when SQ
19450 4c 69 74 65 20 69 73 20 69 6e 20 74 68 65 20 6d  Lite is in the m
19460 69 64 64 6c 65 20 6f 66 20 61 20 6c 61 72 67 65  iddle of a large
19470 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 77 68 65   transaction whe
19480 72 65 20 61 6c 6c 20 74 68 65 0a 2a 2a 20 63 68  re all the.** ch
19490 61 6e 67 65 73 20 77 69 6c 6c 20 6e 6f 74 20 66  anges will not f
194a0 69 74 20 69 6e 74 6f 20 74 68 65 20 69 6e 2d 6d  it into the in-m
194b0 65 6d 6f 72 79 20 63 61 63 68 65 2e 20 20 53 51  emory cache.  SQ
194c0 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a 20 61 6c 72  Lite will.** alr
194d0 65 61 64 79 20 68 6f 6c 64 20 61 20 52 45 53 45  eady hold a RESE
194e0 52 56 45 44 20 6c 6f 63 6b 20 6f 6e 20 74 68 65  RVED lock on the
194f0 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20   database file, 
19500 62 75 74 20 69 74 20 6e 65 65 64 73 0a 2a 2a 20  but it needs.** 
19510 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68 69 73 20  to promote this 
19520 6c 6f 63 6b 20 74 6f 20 45 58 43 4c 55 53 49 56  lock to EXCLUSIV
19530 45 20 73 6f 20 74 68 61 74 20 69 74 20 63 61 6e  E so that it can
19540 20 73 70 69 6c 6c 20 63 61 63 68 65 0a 2a 2a 20   spill cache.** 
19550 70 61 67 65 73 20 69 6e 74 6f 20 74 68 65 20 64  pages into the d
19560 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 69 74  atabase file wit
19570 68 6f 75 74 20 68 61 72 6d 20 74 6f 20 63 6f 6e  hout harm to con
19580 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65 61 64 65  current.** reade
19590 72 73 2e 20 20 5e 49 66 20 69 74 20 69 73 20 75  rs.  ^If it is u
195a0 6e 61 62 6c 65 20 74 6f 20 70 72 6f 6d 6f 74 65  nable to promote
195b0 20 74 68 65 20 6c 6f 63 6b 2c 20 74 68 65 6e 20   the lock, then 
195c0 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 0a 2a 2a  the in-memory.**
195d0 20 63 61 63 68 65 20 77 69 6c 6c 20 62 65 20 6c   cache will be l
195e0 65 66 74 20 69 6e 20 61 6e 20 69 6e 63 6f 6e 73  eft in an incons
195f0 69 73 74 65 6e 74 20 73 74 61 74 65 20 61 6e 64  istent state and
19600 20 73 6f 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a   so the error.**
19610 20 63 6f 64 65 20 69 73 20 70 72 6f 6d 6f 74 65   code is promote
19620 64 20 66 72 6f 6d 20 74 68 65 20 72 65 6c 61 74  d from the relat
19630 69 76 65 6c 79 20 62 65 6e 69 67 6e 20 5b 53 51  ively benign [SQ
19640 4c 49 54 45 5f 42 55 53 59 5d 20 74 6f 0a 2a 2a  LITE_BUSY] to.**
19650 20 74 68 65 20 6d 6f 72 65 20 73 65 76 65 72 65   the more severe
19660 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42   [SQLITE_IOERR_B
19670 4c 4f 43 4b 45 44 5d 2e 20 20 5e 54 68 69 73 20  LOCKED].  ^This 
19680 65 72 72 6f 72 20 63 6f 64 65 20 70 72 6f 6d 6f  error code promo
19690 74 69 6f 6e 0a 2a 2a 20 66 6f 72 63 65 73 20 61  tion.** forces a
196a0 6e 20 61 75 74 6f 6d 61 74 69 63 20 72 6f 6c 6c  n automatic roll
196b0 62 61 63 6b 20 6f 66 20 74 68 65 20 63 68 61 6e  back of the chan
196c0 67 65 73 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a  ges.  See the.**
196d0 20 3c 61 20 68 72 65 66 3d 22 2f 63 76 73 74 72   <a href="/cvstr
196e0 61 63 2f 77 69 6b 69 3f 70 3d 43 6f 72 72 75 70  ac/wiki?p=Corrup
196f0 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73  tionFollowingBus
19700 79 45 72 72 6f 72 22 3e 0a 2a 2a 20 43 6f 72 72  yError">.** Corr
19710 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42  uptionFollowingB
19720 75 73 79 45 72 72 6f 72 3c 2f 61 3e 20 77 69 6b  usyError</a> wik
19730 69 20 70 61 67 65 20 66 6f 72 20 61 20 64 69 73  i page for a dis
19740 63 75 73 73 69 6f 6e 20 6f 66 20 77 68 79 0a 2a  cussion of why.*
19750 2a 20 74 68 69 73 20 69 73 20 69 6d 70 6f 72 74  * this is import
19760 61 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ant..**.** ^(The
19770 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61  re can only be a
19780 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e   single busy han
19790 64 6c 65 72 20 64 65 66 69 6e 65 64 20 66 6f 72  dler defined for
197a0 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61   each.** [databa
197b0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20  se connection]. 
197c0 20 53 65 74 74 69 6e 67 20 61 20 6e 65 77 20 62   Setting a new b
197d0 75 73 79 20 68 61 6e 64 6c 65 72 20 63 6c 65 61  usy handler clea
197e0 72 73 20 61 6e 79 0a 2a 2a 20 70 72 65 76 69 6f  rs any.** previo
197f0 75 73 6c 79 20 73 65 74 20 68 61 6e 64 6c 65 72  usly set handler
19800 2e 29 5e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20  .)^  ^Note that 
19810 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
19820 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d  _busy_timeout()]
19830 0a 2a 2a 20 77 69 6c 6c 20 61 6c 73 6f 20 73 65  .** will also se
19840 74 20 6f 72 20 63 6c 65 61 72 20 74 68 65 20 62  t or clear the b
19850 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a  usy handler..**.
19860 2a 2a 20 54 68 65 20 62 75 73 79 20 63 61 6c 6c  ** The busy call
19870 62 61 63 6b 20 73 68 6f 75 6c 64 20 6e 6f 74 20  back should not 
19880 74 61 6b 65 20 61 6e 79 20 61 63 74 69 6f 6e 73  take any actions
19890 20 77 68 69 63 68 20 6d 6f 64 69 66 79 20 74 68   which modify th
198a0 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  e.** database co
198b0 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e  nnection that in
198c0 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20 68  voked the busy h
198d0 61 6e 64 6c 65 72 2e 20 20 41 6e 79 20 73 75 63  andler.  Any suc
198e0 68 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 73  h actions.** res
198f0 75 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 64  ult in undefined
19900 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 20 0a 2a   behavior..** .*
19910 2a 20 41 20 62 75 73 79 20 68 61 6e 64 6c 65 72  * A busy handler
19920 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20   must not close 
19930 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
19940 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 72 20 5b 70  nection.** or [p
19950 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
19960 74 5d 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20  t] that invoked 
19970 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
19980 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
19990 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 73 71  _busy_handler(sq
199a0 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28 76  lite3*, int(*)(v
199b0 6f 69 64 2a 2c 69 6e 74 29 2c 20 76 6f 69 64 2a  oid*,int), void*
199c0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
199d0 45 46 3a 20 53 65 74 20 41 20 42 75 73 79 20 54  EF: Set A Busy T
199e0 69 6d 65 6f 75 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  imeout.**.** ^Th
199f0 69 73 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20  is routine sets 
19a00 61 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  a [sqlite3_busy_
19a10 68 61 6e 64 6c 65 72 20 7c 20 62 75 73 79 20 68  handler | busy h
19a20 61 6e 64 6c 65 72 5d 20 74 68 61 74 20 73 6c 65  andler] that sle
19a30 65 70 73 0a 2a 2a 20 66 6f 72 20 61 20 73 70 65  eps.** for a spe
19a40 63 69 66 69 65 64 20 61 6d 6f 75 6e 74 20 6f 66  cified amount of
19a50 20 74 69 6d 65 20 77 68 65 6e 20 61 20 74 61 62   time when a tab
19a60 6c 65 20 69 73 20 6c 6f 63 6b 65 64 2e 20 20 5e  le is locked.  ^
19a70 54 68 65 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77  The handler.** w
19a80 69 6c 6c 20 73 6c 65 65 70 20 6d 75 6c 74 69 70  ill sleep multip
19a90 6c 65 20 74 69 6d 65 73 20 75 6e 74 69 6c 20 61  le times until a
19aa0 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c  t least "ms" mil
19ab0 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65  liseconds of sle
19ac0 65 70 69 6e 67 0a 2a 2a 20 68 61 76 65 20 61 63  eping.** have ac
19ad0 63 75 6d 75 6c 61 74 65 64 2e 20 20 5e 41 66 74  cumulated.  ^Aft
19ae0 65 72 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22  er at least "ms"
19af0 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66   milliseconds of
19b00 20 73 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20 74 68   sleeping,.** th
19b10 65 20 68 61 6e 64 6c 65 72 20 72 65 74 75 72 6e  e handler return
19b20 73 20 30 20 77 68 69 63 68 20 63 61 75 73 65 73  s 0 which causes
19b30 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
19b40 5d 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 5b  ] to return.** [
19b50 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20  SQLITE_BUSY] or 
19b60 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c  [SQLITE_IOERR_BL
19b70 4f 43 4b 45 44 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43  OCKED]..**.** ^C
19b80 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 74  alling this rout
19b90 69 6e 65 20 77 69 74 68 20 61 6e 20 61 72 67 75  ine with an argu
19ba0 6d 65 6e 74 20 6c 65 73 73 20 74 68 61 6e 20 6f  ment less than o
19bb0 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 0a  r equal to zero.
19bc0 2a 2a 20 74 75 72 6e 73 20 6f 66 66 20 61 6c 6c  ** turns off all
19bd0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2e 0a   busy handlers..
19be0 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61  **.** ^(There ca
19bf0 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67  n only be a sing
19c00 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  le busy handler 
19c10 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72  for a particular
19c20 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
19c30 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 79 20 61 6e  nnection] any an
19c40 79 20 67 69 76 65 6e 20 6d 6f 6d 65 6e 74 2e 20  y given moment. 
19c50 20 49 66 20 61 6e 6f 74 68 65 72 20 62 75 73 79   If another busy
19c60 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 61 73 20   handler.** was 
19c70 64 65 66 69 6e 65 64 20 20 28 75 73 69 6e 67 20  defined  (using 
19c80 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61  [sqlite3_busy_ha
19c90 6e 64 6c 65 72 28 29 5d 29 20 70 72 69 6f 72 20  ndler()]) prior 
19ca0 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68  to calling.** th
19cb0 69 73 20 72 6f 75 74 69 6e 65 2c 20 74 68 61 74  is routine, that
19cc0 20 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e 64   other busy hand
19cd0 6c 65 72 20 69 73 20 63 6c 65 61 72 65 64 2e 29  ler is cleared.)
19ce0 5e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ^.*/.int sqlite3
19cf0 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 73 71  _busy_timeout(sq
19d00 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6d 73 29 3b  lite3*, int ms);
19d10 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
19d20 3a 20 43 6f 6e 76 65 6e 69 65 6e 63 65 20 52 6f  : Convenience Ro
19d30 75 74 69 6e 65 73 20 46 6f 72 20 52 75 6e 6e 69  utines For Runni
19d40 6e 67 20 51 75 65 72 69 65 73 0a 2a 2a 0a 2a 2a  ng Queries.**.**
19d50 20 54 68 69 73 20 69 73 20 61 20 6c 65 67 61 63   This is a legac
19d60 79 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74  y interface that
19d70 20 69 73 20 70 72 65 73 65 72 76 65 64 20 66 6f   is preserved fo
19d80 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70  r backwards comp
19d90 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 20 55 73  atibility..** Us
19da0 65 20 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66  e of this interf
19db0 61 63 65 20 69 73 20 6e 6f 74 20 72 65 63 6f 6d  ace is not recom
19dc0 6d 65 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 44 65  mended..**.** De
19dd0 66 69 6e 69 74 69 6f 6e 3a 20 41 20 3c 62 3e 72  finition: A <b>r
19de0 65 73 75 6c 74 20 74 61 62 6c 65 3c 2f 62 3e 20  esult table</b> 
19df0 69 73 20 6d 65 6d 6f 72 79 20 64 61 74 61 20 73  is memory data s
19e00 74 72 75 63 74 75 72 65 20 63 72 65 61 74 65 64  tructure created
19e10 20 62 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69   by the.** [sqli
19e20 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d  te3_get_table()]
19e30 20 69 6e 74 65 72 66 61 63 65 2e 20 20 41 20 72   interface.  A r
19e40 65 73 75 6c 74 20 74 61 62 6c 65 20 72 65 63 6f  esult table reco
19e50 72 64 73 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c  rds the.** compl
19e60 65 74 65 20 71 75 65 72 79 20 72 65 73 75 6c 74  ete query result
19e70 73 20 66 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f  s from one or mo
19e80 72 65 20 71 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a  re queries..**.*
19e90 2a 20 54 68 65 20 74 61 62 6c 65 20 63 6f 6e 63  * The table conc
19ea0 65 70 74 75 61 6c 6c 79 20 68 61 73 20 61 20 6e  eptually has a n
19eb0 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 61 6e  umber of rows an
19ec0 64 20 63 6f 6c 75 6d 6e 73 2e 20 20 42 75 74 0a  d columns.  But.
19ed0 2a 2a 20 74 68 65 73 65 20 6e 75 6d 62 65 72 73  ** these numbers
19ee0 20 61 72 65 20 6e 6f 74 20 70 61 72 74 20 6f 66   are not part of
19ef0 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c   the result tabl
19f00 65 20 69 74 73 65 6c 66 2e 20 20 54 68 65 73 65  e itself.  These
19f10 0a 2a 2a 20 6e 75 6d 62 65 72 73 20 61 72 65 20  .** numbers are 
19f20 6f 62 74 61 69 6e 65 64 20 73 65 70 61 72 61 74  obtained separat
19f30 65 6c 79 2e 20 20 4c 65 74 20 4e 20 62 65 20 74  ely.  Let N be t
19f40 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77  he number of row
19f50 73 0a 2a 2a 20 61 6e 64 20 4d 20 62 65 20 74 68  s.** and M be th
19f60 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  e number of colu
19f70 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73  mns..**.** A res
19f80 75 6c 74 20 74 61 62 6c 65 20 69 73 20 61 6e 20  ult table is an 
19f90 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72  array of pointer
19fa0 73 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  s to zero-termin
19fb0 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e  ated UTF-8 strin
19fc0 67 73 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65  gs..** There are
19fd0 20 28 4e 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e 74   (N+1)*M element
19fe0 73 20 69 6e 20 74 68 65 20 61 72 72 61 79 2e 20  s in the array. 
19ff0 20 54 68 65 20 66 69 72 73 74 20 4d 20 70 6f 69   The first M poi
1a000 6e 74 65 72 73 20 70 6f 69 6e 74 0a 2a 2a 20 74  nters point.** t
1a010 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  o zero-terminate
1a020 64 20 73 74 72 69 6e 67 73 20 74 68 61 74 20 20  d strings that  
1a030 63 6f 6e 74 61 69 6e 20 74 68 65 20 6e 61 6d 65  contain the name
1a040 73 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73  s of the columns
1a050 2e 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e 69  ..** The remaini
1a060 6e 67 20 65 6e 74 72 69 65 73 20 61 6c 6c 20 70  ng entries all p
1a070 6f 69 6e 74 20 74 6f 20 71 75 65 72 79 20 72 65  oint to query re
1a080 73 75 6c 74 73 2e 20 20 4e 55 4c 4c 20 76 61 6c  sults.  NULL val
1a090 75 65 73 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e  ues result.** in
1a0a0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 2e 20   NULL pointers. 
1a0b0 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 75 65   All other value
1a0c0 73 20 61 72 65 20 69 6e 20 74 68 65 69 72 20 55  s are in their U
1a0d0 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  TF-8 zero-termin
1a0e0 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 72  ated.** string r
1a0f0 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 61 73  epresentation as
1a100 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71   returned by [sq
1a110 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
1a120 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65  t()]..**.** A re
1a130 73 75 6c 74 20 74 61 62 6c 65 20 6d 69 67 68 74  sult table might
1a140 20 63 6f 6e 73 69 73 74 20 6f 66 20 6f 6e 65 20   consist of one 
1a150 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f 72 79 20 61  or more memory a
1a160 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49  llocations..** I
1a170 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f  t is not safe to
1a180 20 70 61 73 73 20 61 20 72 65 73 75 6c 74 20 74   pass a result t
1a190 61 62 6c 65 20 64 69 72 65 63 74 6c 79 20 74 6f  able directly to
1a1a0 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
1a1b0 5d 2e 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74  ]..** A result t
1a1c0 61 62 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 64  able should be d
1a1d0 65 61 6c 6c 6f 63 61 74 65 64 20 75 73 69 6e 67  eallocated using
1a1e0 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74   [sqlite3_free_t
1a1f0 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  able()]..**.** ^
1a200 28 41 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f  (As an example o
1a210 66 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62  f the result tab
1a220 6c 65 20 66 6f 72 6d 61 74 2c 20 73 75 70 70 6f  le format, suppo
1a230 73 65 20 61 20 71 75 65 72 79 20 72 65 73 75 6c  se a query resul
1a240 74 0a 2a 2a 20 69 73 20 61 73 20 66 6f 6c 6c 6f  t.** is as follo
1a250 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ws:.**.** <block
1a260 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
1a270 20 20 20 20 20 20 4e 61 6d 65 20 20 20 20 20 20        Name      
1a280 20 20 7c 20 41 67 65 0a 2a 2a 20 20 20 20 20 20    | Age.**      
1a290 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d    --------------
1a2a0 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20  ---------.**    
1a2b0 20 20 20 20 41 6c 69 63 65 20 20 20 20 20 20 20      Alice       
1a2c0 7c 20 34 33 0a 2a 2a 20 20 20 20 20 20 20 20 42  | 43.**        B
1a2d0 6f 62 20 20 20 20 20 20 20 20 20 7c 20 32 38 0a  ob         | 28.
1a2e0 2a 2a 20 20 20 20 20 20 20 20 43 69 6e 64 79 20  **        Cindy 
1a2f0 20 20 20 20 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f        | 21.** </
1a300 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
1a310 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 61 72  >.**.** There ar
1a320 65 20 74 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d  e two column (M=
1a330 3d 32 29 20 61 6e 64 20 74 68 72 65 65 20 72 6f  =2) and three ro
1a340 77 73 20 28 4e 3d 3d 33 29 2e 20 20 54 68 75 73  ws (N==3).  Thus
1a350 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 74   the.** result t
1a360 61 62 6c 65 20 68 61 73 20 38 20 65 6e 74 72 69  able has 8 entri
1a370 65 73 2e 20 20 53 75 70 70 6f 73 65 20 74 68 65  es.  Suppose the
1a380 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73   result table is
1a390 20 73 74 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 6e   stored.** in an
1a3a0 20 61 72 72 61 79 20 6e 61 6d 65 73 20 61 7a 52   array names azR
1a3b0 65 73 75 6c 74 2e 20 20 54 68 65 6e 20 61 7a 52  esult.  Then azR
1a3c0 65 73 75 6c 74 20 68 6f 6c 64 73 20 74 68 69 73  esult holds this
1a3d0 20 63 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20   content:.**.** 
1a3e0 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
1a3f0 3e 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  >.**        azRe
1a400 73 75 6c 74 26 23 39 31 3b 30 5d 20 3d 20 22 4e  sult&#91;0] = "N
1a410 61 6d 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  ame";.**        
1a420 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 31 5d 20  azResult&#91;1] 
1a430 3d 20 22 41 67 65 22 3b 0a 2a 2a 20 20 20 20 20  = "Age";.**     
1a440 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
1a450 32 5d 20 3d 20 22 41 6c 69 63 65 22 3b 0a 2a 2a  2] = "Alice";.**
1a460 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
1a470 26 23 39 31 3b 33 5d 20 3d 20 22 34 33 22 3b 0a  &#91;3] = "43";.
1a480 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
1a490 6c 74 26 23 39 31 3b 34 5d 20 3d 20 22 42 6f 62  lt&#91;4] = "Bob
1a4a0 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
1a4b0 65 73 75 6c 74 26 23 39 31 3b 35 5d 20 3d 20 22  esult&#91;5] = "
1a4c0 32 38 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  28";.**        a
1a4d0 7a 52 65 73 75 6c 74 26 23 39 31 3b 36 5d 20 3d  zResult&#91;6] =
1a4e0 20 22 43 69 6e 64 79 22 3b 0a 2a 2a 20 20 20 20   "Cindy";.**    
1a4f0 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
1a500 3b 37 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c  ;7] = "21";.** <
1a510 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
1a520 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  e>)^.**.** ^The 
1a530 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
1a540 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 65 76 61  e() function eva
1a550 6c 75 61 74 65 73 20 6f 6e 65 20 6f 72 20 6d 6f  luates one or mo
1a560 72 65 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d  re.** semicolon-
1a570 73 65 70 61 72 61 74 65 64 20 53 51 4c 20 73 74  separated SQL st
1a580 61 74 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20  atements in the 
1a590 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
1a5a0 55 54 46 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20  UTF-8.** string 
1a5b0 6f 66 20 69 74 73 20 32 6e 64 20 70 61 72 61 6d  of its 2nd param
1a5c0 65 74 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73  eter and returns
1a5d0 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   a result table 
1a5e0 74 6f 20 74 68 65 0a 2a 2a 20 70 6f 69 6e 74 65  to the.** pointe
1a5f0 72 20 67 69 76 65 6e 20 69 6e 20 69 74 73 20 33  r given in its 3
1a600 72 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  rd parameter..**
1a610 0a 2a 2a 20 41 66 74 65 72 20 74 68 65 20 61 70  .** After the ap
1a620 70 6c 69 63 61 74 69 6f 6e 20 68 61 73 20 66 69  plication has fi
1a630 6e 69 73 68 65 64 20 77 69 74 68 20 74 68 65 20  nished with the 
1a640 72 65 73 75 6c 74 20 66 72 6f 6d 20 73 71 6c 69  result from sqli
1a650 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c  te3_get_table(),
1a660 0a 2a 2a 20 69 74 20 6d 75 73 74 20 70 61 73 73  .** it must pass
1a670 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c   the result tabl
1a680 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c  e pointer to sql
1a690 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28  ite3_free_table(
1a6a0 29 20 69 6e 20 6f 72 64 65 72 20 74 6f 0a 2a 2a  ) in order to.**
1a6b0 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d   release the mem
1a6c0 6f 72 79 20 74 68 61 74 20 77 61 73 20 6d 61 6c  ory that was mal
1a6d0 6c 6f 63 65 64 2e 20 20 42 65 63 61 75 73 65 20  loced.  Because 
1a6e0 6f 66 20 74 68 65 20 77 61 79 20 74 68 65 0a 2a  of the way the.*
1a6f0 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  * [sqlite3_mallo
1a700 63 28 29 5d 20 68 61 70 70 65 6e 73 20 77 69 74  c()] happens wit
1a710 68 69 6e 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  hin sqlite3_get_
1a720 74 61 62 6c 65 28 29 2c 20 74 68 65 20 63 61 6c  table(), the cal
1a730 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  ling.** function
1a740 20 6d 75 73 74 20 6e 6f 74 20 74 72 79 20 74 6f   must not try to
1a750 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66   call [sqlite3_f
1a760 72 65 65 28 29 5d 20 64 69 72 65 63 74 6c 79 2e  ree()] directly.
1a770 20 20 4f 6e 6c 79 0a 2a 2a 20 5b 73 71 6c 69 74    Only.** [sqlit
1a780 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d  e3_free_table()]
1a790 20 69 73 20 61 62 6c 65 20 74 6f 20 72 65 6c 65   is able to rele
1a7a0 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70  ase the memory p
1a7b0 72 6f 70 65 72 6c 79 20 61 6e 64 20 73 61 66 65  roperly and safe
1a7c0 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ly..**.** The sq
1a7d0 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
1a7e0 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 69  ) interface is i
1a7f0 6d 70 6c 65 6d 65 6e 74 65 64 20 61 73 20 61 20  mplemented as a 
1a800 77 72 61 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a  wrapper around.*
1a810 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  * [sqlite3_exec(
1a820 29 5d 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33  )].  The sqlite3
1a830 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 72 6f 75  _get_table() rou
1a840 74 69 6e 65 20 64 6f 65 73 20 6e 6f 74 20 68 61  tine does not ha
1a850 76 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20  ve access.** to 
1a860 61 6e 79 20 69 6e 74 65 72 6e 61 6c 20 64 61 74  any internal dat
1a870 61 20 73 74 72 75 63 74 75 72 65 73 20 6f 66 20  a structures of 
1a880 53 51 4c 69 74 65 2e 20 20 49 74 20 75 73 65 73  SQLite.  It uses
1a890 20 6f 6e 6c 79 20 74 68 65 20 70 75 62 6c 69 63   only the public
1a8a0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 64 65  .** interface de
1a8b0 66 69 6e 65 64 20 68 65 72 65 2e 20 20 41 73 20  fined here.  As 
1a8c0 61 20 63 6f 6e 73 65 71 75 65 6e 63 65 2c 20 65  a consequence, e
1a8d0 72 72 6f 72 73 20 74 68 61 74 20 6f 63 63 75 72  rrors that occur
1a8e0 20 69 6e 20 74 68 65 0a 2a 2a 20 77 72 61 70 70   in the.** wrapp
1a8f0 65 72 20 6c 61 79 65 72 20 6f 75 74 73 69 64 65  er layer outside
1a900 20 6f 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c   of the internal
1a910 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
1a920 5d 20 63 61 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a  ] call are not.*
1a930 2a 20 72 65 66 6c 65 63 74 65 64 20 69 6e 20 73  * reflected in s
1a940 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20  ubsequent calls 
1a950 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63  to [sqlite3_errc
1a960 6f 64 65 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  ode()] or.** [sq
1a970 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e  lite3_errmsg()].
1a980 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
1a990 67 65 74 5f 74 61 62 6c 65 28 0a 20 20 73 71 6c  get_table(.  sql
1a9a0 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
1a9b0 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61     /* An open da
1a9c0 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73  tabase */.  cons
1a9d0 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20  t char *zSql,   
1a9e0 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65    /* SQL to be e
1a9f0 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 63 68  valuated */.  ch
1aa00 61 72 20 2a 2a 2a 70 61 7a 52 65 73 75 6c 74 2c  ar ***pazResult,
1aa10 20 20 20 20 2f 2a 20 52 65 73 75 6c 74 73 20 6f      /* Results o
1aa20 66 20 74 68 65 20 71 75 65 72 79 20 2a 2f 0a 20  f the query */. 
1aa30 20 69 6e 74 20 2a 70 6e 52 6f 77 2c 20 20 20 20   int *pnRow,    
1aa40 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72         /* Number
1aa50 20 6f 66 20 72 65 73 75 6c 74 20 72 6f 77 73 20   of result rows 
1aa60 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a  written here */.
1aa70 20 20 69 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e 2c    int *pnColumn,
1aa80 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65          /* Numbe
1aa90 72 20 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c 75  r of result colu
1aaa0 6d 6e 73 20 77 72 69 74 74 65 6e 20 68 65 72 65  mns written here
1aab0 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45   */.  char **pzE
1aac0 72 72 6d 73 67 20 20 20 20 20 20 20 2f 2a 20 45  rrmsg       /* E
1aad0 72 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e  rror msg written
1aae0 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 76 6f 69 64   here */.);.void
1aaf0 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61   sqlite3_free_ta
1ab00 62 6c 65 28 63 68 61 72 20 2a 2a 72 65 73 75 6c  ble(char **resul
1ab10 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
1ab20 52 45 46 3a 20 46 6f 72 6d 61 74 74 65 64 20 53  REF: Formatted S
1ab30 74 72 69 6e 67 20 50 72 69 6e 74 69 6e 67 20 46  tring Printing F
1ab40 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54  unctions.**.** T
1ab50 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
1ab60 65 20 77 6f 72 6b 2d 61 6c 69 6b 65 73 20 6f 66  e work-alikes of
1ab70 20 74 68 65 20 22 70 72 69 6e 74 66 28 29 22 20   the "printf()" 
1ab80 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e 63 74 69  family of functi
1ab90 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20  ons.** from the 
1aba0 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61  standard C libra
1abb0 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ry..**.** ^The s
1abc0 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29  qlite3_mprintf()
1abd0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 6d 70   and sqlite3_vmp
1abe0 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 73  rintf() routines
1abf0 20 77 72 69 74 65 20 74 68 65 69 72 0a 2a 2a 20   write their.** 
1ac00 72 65 73 75 6c 74 73 20 69 6e 74 6f 20 6d 65 6d  results into mem
1ac10 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ory obtained fro
1ac20 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
1ac30 63 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 74 72  c()]..** The str
1ac40 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79  ings returned by
1ac50 20 74 68 65 73 65 20 74 77 6f 20 72 6f 75 74 69   these two routi
1ac60 6e 65 73 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a  nes should be.**
1ac70 20 72 65 6c 65 61 73 65 64 20 62 79 20 5b 73 71   released by [sq
1ac80 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 20 20  lite3_free()].  
1ac90 5e 42 6f 74 68 20 72 6f 75 74 69 6e 65 73 20 72  ^Both routines r
1aca0 65 74 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20  eturn a.** NULL 
1acb0 70 6f 69 6e 74 65 72 20 69 66 20 5b 73 71 6c 69  pointer if [sqli
1acc0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 73  te3_malloc()] is
1acd0 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63   unable to alloc
1ace0 61 74 65 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65  ate enough.** me
1acf0 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65  mory to hold the
1ad00 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e   resulting strin
1ad10 67 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73  g..**.** ^(The s
1ad20 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
1ad30 29 20 72 6f 75 74 69 6e 65 20 69 73 20 73 69 6d  ) routine is sim
1ad40 69 6c 61 72 20 74 6f 20 22 73 6e 70 72 69 6e 74  ilar to "snprint
1ad50 66 28 29 22 20 66 72 6f 6d 0a 2a 2a 20 74 68 65  f()" from.** the
1ad60 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72   standard C libr
1ad70 61 72 79 2e 20 20 54 68 65 20 72 65 73 75 6c 74  ary.  The result
1ad80 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f   is written into
1ad90 20 74 68 65 0a 2a 2a 20 62 75 66 66 65 72 20 73   the.** buffer s
1ada0 75 70 70 6c 69 65 64 20 61 73 20 74 68 65 20 73  upplied as the s
1adb0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
1adc0 77 68 6f 73 65 20 73 69 7a 65 20 69 73 20 67 69  whose size is gi
1add0 76 65 6e 20 62 79 0a 2a 2a 20 74 68 65 20 66 69  ven by.** the fi
1ade0 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e 20 4e  rst parameter. N
1adf0 6f 74 65 20 74 68 61 74 20 74 68 65 20 6f 72 64  ote that the ord
1ae00 65 72 20 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72  er of the.** fir
1ae10 73 74 20 74 77 6f 20 70 61 72 61 6d 65 74 65 72  st two parameter
1ae20 73 20 69 73 20 72 65 76 65 72 73 65 64 20 66 72  s is reversed fr
1ae30 6f 6d 20 73 6e 70 72 69 6e 74 66 28 29 2e 29 5e  om snprintf().)^
1ae40 20 20 54 68 69 73 20 69 73 20 61 6e 0a 2a 2a 20    This is an.** 
1ae50 68 69 73 74 6f 72 69 63 61 6c 20 61 63 63 69 64  historical accid
1ae60 65 6e 74 20 74 68 61 74 20 63 61 6e 6e 6f 74 20  ent that cannot 
1ae70 62 65 20 66 69 78 65 64 20 77 69 74 68 6f 75 74  be fixed without
1ae80 20 62 72 65 61 6b 69 6e 67 0a 2a 2a 20 62 61 63   breaking.** bac
1ae90 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69  kwards compatibi
1aea0 6c 69 74 79 2e 20 20 5e 28 4e 6f 74 65 20 61 6c  lity.  ^(Note al
1aeb0 73 6f 20 74 68 61 74 20 73 71 6c 69 74 65 33 5f  so that sqlite3_
1aec0 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 72 65  snprintf().** re
1aed0 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
1aee0 74 6f 20 69 74 73 20 62 75 66 66 65 72 20 69 6e  to its buffer in
1aef0 73 74 65 61 64 20 6f 66 20 74 68 65 20 6e 75 6d  stead of the num
1af00 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 72 61 63  ber of.** charac
1af10 74 65 72 73 20 61 63 74 75 61 6c 6c 79 20 77 72  ters actually wr
1af20 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 20 62  itten into the b
1af30 75 66 66 65 72 2e 29 5e 20 20 57 65 20 61 64 6d  uffer.)^  We adm
1af40 69 74 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e  it that.** the n
1af50 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74  umber of charact
1af60 65 72 73 20 77 72 69 74 74 65 6e 20 77 6f 75 6c  ers written woul
1af70 64 20 62 65 20 61 20 6d 6f 72 65 20 75 73 65 66  d be a more usef
1af80 75 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c  ul return.** val
1af90 75 65 20 62 75 74 20 77 65 20 63 61 6e 6e 6f 74  ue but we cannot
1afa0 20 63 68 61 6e 67 65 20 74 68 65 20 69 6d 70 6c   change the impl
1afb0 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71  ementation of sq
1afc0 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
1afd0 0a 2a 2a 20 6e 6f 77 20 77 69 74 68 6f 75 74 20  .** now without 
1afe0 62 72 65 61 6b 69 6e 67 20 63 6f 6d 70 61 74 69  breaking compati
1aff0 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41  bility..**.** ^A
1b000 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 62 75  s long as the bu
1b010 66 66 65 72 20 73 69 7a 65 20 69 73 20 67 72 65  ffer size is gre
1b020 61 74 65 72 20 74 68 61 6e 20 7a 65 72 6f 2c 20  ater than zero, 
1b030 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
1b040 28 29 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 73  ().** guarantees
1b050 20 74 68 61 74 20 74 68 65 20 62 75 66 66 65 72   that the buffer
1b060 20 69 73 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d   is always zero-
1b070 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68  terminated.  ^Th
1b080 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d  e first.** param
1b090 65 74 65 72 20 22 6e 22 20 69 73 20 74 68 65 20  eter "n" is the 
1b0a0 74 6f 74 61 6c 20 73 69 7a 65 20 6f 66 20 74 68  total size of th
1b0b0 65 20 62 75 66 66 65 72 2c 20 69 6e 63 6c 75 64  e buffer, includ
1b0c0 69 6e 67 20 73 70 61 63 65 20 66 6f 72 0a 2a 2a  ing space for.**
1b0d0 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e   the zero termin
1b0e0 61 74 6f 72 2e 20 20 53 6f 20 74 68 65 20 6c 6f  ator.  So the lo
1b0f0 6e 67 65 73 74 20 73 74 72 69 6e 67 20 74 68 61  ngest string tha
1b100 74 20 63 61 6e 20 62 65 20 63 6f 6d 70 6c 65 74  t can be complet
1b110 65 6c 79 0a 2a 2a 20 77 72 69 74 74 65 6e 20 77  ely.** written w
1b120 69 6c 6c 20 62 65 20 6e 2d 31 20 63 68 61 72 61  ill be n-1 chara
1b130 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  cters..**.** ^Th
1b140 65 20 73 71 6c 69 74 65 33 5f 76 73 6e 70 72 69  e sqlite3_vsnpri
1b150 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73  ntf() routine is
1b160 20 61 20 76 61 72 61 72 67 73 20 76 65 72 73 69   a varargs versi
1b170 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e  on of sqlite3_sn
1b180 70 72 69 6e 74 66 28 29 2e 0a 2a 2a 0a 2a 2a 20  printf()..**.** 
1b190 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
1b1a0 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d  ll implement som
1b1b0 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 6f 72  e additional for
1b1c0 6d 61 74 74 69 6e 67 0a 2a 2a 20 6f 70 74 69 6f  matting.** optio
1b1d0 6e 73 20 74 68 61 74 20 61 72 65 20 75 73 65 66  ns that are usef
1b1e0 75 6c 20 66 6f 72 20 63 6f 6e 73 74 72 75 63 74  ul for construct
1b1f0 69 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ing SQL statemen
1b200 74 73 2e 0a 2a 2a 20 41 6c 6c 20 6f 66 20 74 68  ts..** All of th
1b210 65 20 75 73 75 61 6c 20 70 72 69 6e 74 66 28 29  e usual printf()
1b220 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69   formatting opti
1b230 6f 6e 73 20 61 70 70 6c 79 2e 20 20 49 6e 20 61  ons apply.  In a
1b240 64 64 69 74 69 6f 6e 2c 20 74 68 65 72 65 0a 2a  ddition, there.*
1b250 2a 20 69 73 20 61 72 65 20 22 25 71 22 2c 20 22  * is are "%q", "
1b260 25 51 22 2c 20 61 6e 64 20 22 25 7a 22 20 6f 70  %Q", and "%z" op
1b270 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  tions..**.** ^(T
1b280 68 65 20 25 71 20 6f 70 74 69 6f 6e 20 77 6f 72  he %q option wor
1b290 6b 73 20 6c 69 6b 65 20 25 73 20 69 6e 20 74 68  ks like %s in th
1b2a0 61 74 20 69 74 20 73 75 62 73 74 69 74 75 74 65  at it substitute
1b2b0 73 20 61 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74  s a nul-terminat
1b2c0 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 66 72 6f  ed.** string fro
1b2d0 6d 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 6c  m the argument l
1b2e0 69 73 74 2e 20 20 42 75 74 20 25 71 20 61 6c 73  ist.  But %q als
1b2f0 6f 20 64 6f 75 62 6c 65 73 20 65 76 65 72 79 20  o doubles every 
1b300 27 5c 27 27 20 63 68 61 72 61 63 74 65 72 2e 0a  '\'' character..
1b310 2a 2a 20 25 71 20 69 73 20 64 65 73 69 67 6e 65  ** %q is designe
1b320 64 20 66 6f 72 20 75 73 65 20 69 6e 73 69 64 65  d for use inside
1b330 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61   a string litera
1b340 6c 2e 29 5e 20 20 42 79 20 64 6f 75 62 6c 69 6e  l.)^  By doublin
1b350 67 20 65 61 63 68 20 27 5c 27 27 0a 2a 2a 20 63  g each '\''.** c
1b360 68 61 72 61 63 74 65 72 20 69 74 20 65 73 63 61  haracter it esca
1b370 70 65 73 20 74 68 61 74 20 63 68 61 72 61 63 74  pes that charact
1b380 65 72 20 61 6e 64 20 61 6c 6c 6f 77 73 20 69 74  er and allows it
1b390 20 74 6f 20 62 65 20 69 6e 73 65 72 74 65 64 20   to be inserted 
1b3a0 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 73 74 72 69  into.** the stri
1b3b0 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78  ng..**.** For ex
1b3c0 61 6d 70 6c 65 2c 20 61 73 73 75 6d 65 20 74 68  ample, assume th
1b3d0 65 20 73 74 72 69 6e 67 20 76 61 72 69 61 62 6c  e string variabl
1b3e0 65 20 7a 54 65 78 74 20 63 6f 6e 74 61 69 6e 73  e zText contains
1b3f0 20 74 65 78 74 20 61 73 20 66 6f 6c 6c 6f 77 73   text as follows
1b400 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
1b410 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68  ote><pre>.**  ch
1b420 61 72 20 2a 7a 54 65 78 74 20 3d 20 22 49 74 27  ar *zText = "It'
1b430 73 20 61 20 68 61 70 70 79 20 64 61 79 21 22 3b  s a happy day!";
1b440 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
1b450 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e  kquote>.**.** On
1b460 65 20 63 61 6e 20 75 73 65 20 74 68 69 73 20 74  e can use this t
1b470 65 78 74 20 69 6e 20 61 6e 20 53 51 4c 20 73 74  ext in an SQL st
1b480 61 74 65 6d 65 6e 74 20 61 73 20 66 6f 6c 6c 6f  atement as follo
1b490 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ws:.**.** <block
1b4a0 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
1b4b0 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c  char *zSQL = sql
1b4c0 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e  ite3_mprintf("IN
1b4d0 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20  SERT INTO table 
1b4e0 56 41 4c 55 45 53 28 27 25 71 27 29 22 2c 20 7a  VALUES('%q')", z
1b4f0 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74  Text);.**  sqlit
1b500 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c  e3_exec(db, zSQL
1b510 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20  , 0, 0, 0);.**  
1b520 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51  sqlite3_free(zSQ
1b530 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  L);.** </pre></b
1b540 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
1b550 20 42 65 63 61 75 73 65 20 74 68 65 20 25 71 20   Because the %q 
1b560 66 6f 72 6d 61 74 20 73 74 72 69 6e 67 20 69 73  format string is
1b570 20 75 73 65 64 2c 20 74 68 65 20 27 5c 27 27 20   used, the '\'' 
1b580 63 68 61 72 61 63 74 65 72 20 69 6e 20 7a 54 65  character in zTe
1b590 78 74 0a 2a 2a 20 69 73 20 65 73 63 61 70 65 64  xt.** is escaped
1b5a0 20 61 6e 64 20 74 68 65 20 53 51 4c 20 67 65 6e   and the SQL gen
1b5b0 65 72 61 74 65 64 20 69 73 20 61 73 20 66 6f 6c  erated is as fol
1b5c0 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  lows:.**.** <blo
1b5d0 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
1b5e0 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61    INSERT INTO ta
1b5f0 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74 27  ble1 VALUES('It'
1b600 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21 27  's a happy day!'
1b610 29 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ).** </pre></blo
1b620 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54  ckquote>.**.** T
1b630 68 69 73 20 69 73 20 63 6f 72 72 65 63 74 2e 20  his is correct. 
1b640 20 48 61 64 20 77 65 20 75 73 65 64 20 25 73 20   Had we used %s 
1b650 69 6e 73 74 65 61 64 20 6f 66 20 25 71 2c 20 74  instead of %q, t
1b660 68 65 20 67 65 6e 65 72 61 74 65 64 20 53 51 4c  he generated SQL
1b670 0a 2a 2a 20 77 6f 75 6c 64 20 68 61 76 65 20 6c  .** would have l
1b680 6f 6f 6b 65 64 20 6c 69 6b 65 20 74 68 69 73 3a  ooked like this:
1b690 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
1b6a0 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53  te><pre>.**  INS
1b6b0 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20  ERT INTO table1 
1b6c0 56 41 4c 55 45 53 28 27 49 74 27 73 20 61 20 68  VALUES('It's a h
1b6d0 61 70 70 79 20 64 61 79 21 27 29 3b 0a 2a 2a 20  appy day!');.** 
1b6e0 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
1b6f0 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73  te>.**.** This s
1b700 65 63 6f 6e 64 20 65 78 61 6d 70 6c 65 20 69 73  econd example is
1b710 20 61 6e 20 53 51 4c 20 73 79 6e 74 61 78 20 65   an SQL syntax e
1b720 72 72 6f 72 2e 20 20 41 73 20 61 20 67 65 6e 65  rror.  As a gene
1b730 72 61 6c 20 72 75 6c 65 20 79 6f 75 20 73 68 6f  ral rule you sho
1b740 75 6c 64 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73  uld.** always us
1b750 65 20 25 71 20 69 6e 73 74 65 61 64 20 6f 66 20  e %q instead of 
1b760 25 73 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e  %s when insertin
1b770 67 20 74 65 78 74 20 69 6e 74 6f 20 61 20 73 74  g text into a st
1b780 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a  ring literal..**
1b790 0a 2a 2a 20 5e 28 54 68 65 20 25 51 20 6f 70 74  .** ^(The %Q opt
1b7a0 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25  ion works like %
1b7b0 71 20 65 78 63 65 70 74 20 69 74 20 61 6c 73 6f  q except it also
1b7c0 20 61 64 64 73 20 73 69 6e 67 6c 65 20 71 75 6f   adds single quo
1b7d0 74 65 73 20 61 72 6f 75 6e 64 0a 2a 2a 20 74 68  tes around.** th
1b7e0 65 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65  e outside of the
1b7f0 20 74 6f 74 61 6c 20 73 74 72 69 6e 67 2e 20 20   total string.  
1b800 41 64 64 69 74 69 6f 6e 61 6c 6c 79 2c 20 69 66  Additionally, if
1b810 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69   the parameter i
1b820 6e 20 74 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e  n the.** argumen
1b830 74 20 6c 69 73 74 20 69 73 20 61 20 4e 55 4c 4c  t list is a NULL
1b840 20 70 6f 69 6e 74 65 72 2c 20 25 51 20 73 75 62   pointer, %Q sub
1b850 73 74 69 74 75 74 65 73 20 74 68 65 20 74 65 78  stitutes the tex
1b860 74 20 22 4e 55 4c 4c 22 20 28 77 69 74 68 6f 75  t "NULL" (withou
1b870 74 0a 2a 2a 20 73 69 6e 67 6c 65 20 71 75 6f 74  t.** single quot
1b880 65 73 29 2e 29 5e 20 20 53 6f 2c 20 66 6f 72 20  es).)^  So, for 
1b890 65 78 61 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f 75  example, one cou
1b8a0 6c 64 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ld say:.**.** <b
1b8b0 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
1b8c0 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d  **  char *zSQL =
1b8d0 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66   sqlite3_mprintf
1b8e0 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61  ("INSERT INTO ta
1b8f0 62 6c 65 20 56 41 4c 55 45 53 28 25 51 29 22 2c  ble VALUES(%Q)",
1b900 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c   zText);.**  sql
1b910 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53  ite3_exec(db, zS
1b920 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a  QL, 0, 0, 0);.**
1b930 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a    sqlite3_free(z
1b940 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  SQL);.** </pre><
1b950 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
1b960 2a 2a 20 54 68 65 20 63 6f 64 65 20 61 62 6f 76  ** The code abov
1b970 65 20 77 69 6c 6c 20 72 65 6e 64 65 72 20 61 20  e will render a 
1b980 63 6f 72 72 65 63 74 20 53 51 4c 20 73 74 61 74  correct SQL stat
1b990 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 7a 53 51  ement in the zSQ
1b9a0 4c 0a 2a 2a 20 76 61 72 69 61 62 6c 65 20 65 76  L.** variable ev
1b9b0 65 6e 20 69 66 20 74 68 65 20 7a 54 65 78 74 20  en if the zText 
1b9c0 76 61 72 69 61 62 6c 65 20 69 73 20 61 20 4e 55  variable is a NU
1b9d0 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  LL pointer..**.*
1b9e0 2a 20 5e 28 54 68 65 20 22 25 7a 22 20 66 6f 72  * ^(The "%z" for
1b9f0 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20 77  matting option w
1ba00 6f 72 6b 73 20 6c 69 6b 65 20 22 25 73 22 20 62  orks like "%s" b
1ba10 75 74 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 61  ut with the.** a
1ba20 64 64 69 74 69 6f 6e 20 74 68 61 74 20 61 66 74  ddition that aft
1ba30 65 72 20 74 68 65 20 73 74 72 69 6e 67 20 68 61  er the string ha
1ba40 73 20 62 65 65 6e 20 72 65 61 64 20 61 6e 64 20  s been read and 
1ba50 63 6f 70 69 65 64 20 69 6e 74 6f 0a 2a 2a 20 74  copied into.** t
1ba60 68 65 20 72 65 73 75 6c 74 2c 20 5b 73 71 6c 69  he result, [sqli
1ba70 74 65 33 5f 66 72 65 65 28 29 5d 20 69 73 20 63  te3_free()] is c
1ba80 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20 69 6e 70  alled on the inp
1ba90 75 74 20 73 74 72 69 6e 67 2e 29 5e 0a 2a 2f 0a  ut string.)^.*/.
1baa0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 6d 70  char *sqlite3_mp
1bab0 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72  rintf(const char
1bac0 2a 2c 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71  *,...);.char *sq
1bad0 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 63  lite3_vmprintf(c
1bae0 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c  onst char*, va_l
1baf0 69 73 74 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69  ist);.char *sqli
1bb00 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 69 6e 74  te3_snprintf(int
1bb10 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61  ,char*,const cha
1bb20 72 2a 2c 20 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a  r*, ...);.char *
1bb30 73 71 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e 74  sqlite3_vsnprint
1bb40 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73  f(int,char*,cons
1bb50 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74  t char*, va_list
1bb60 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1bb70 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63  EF: Memory Alloc
1bb80 61 74 69 6f 6e 20 53 75 62 73 79 73 74 65 6d 0a  ation Subsystem.
1bb90 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65  **.** The SQLite
1bba0 20 63 6f 72 65 20 75 73 65 73 20 74 68 65 73 65   core uses these
1bbb0 20 74 68 72 65 65 20 72 6f 75 74 69 6e 65 73 20   three routines 
1bbc0 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 6f  for all of its o
1bbd0 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 20 6d  wn.** internal m
1bbe0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
1bbf0 20 6e 65 65 64 73 2e 20 22 43 6f 72 65 22 20 69   needs. "Core" i
1bc00 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 73  n the previous s
1bc10 65 6e 74 65 6e 63 65 0a 2a 2a 20 64 6f 65 73 20  entence.** does 
1bc20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 6f 70 65 72  not include oper
1bc30 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65  ating-system spe
1bc40 63 69 66 69 63 20 56 46 53 20 69 6d 70 6c 65 6d  cific VFS implem
1bc50 65 6e 74 61 74 69 6f 6e 2e 20 20 54 68 65 0a 2a  entation.  The.*
1bc60 2a 20 57 69 6e 64 6f 77 73 20 56 46 53 20 75 73  * Windows VFS us
1bc70 65 73 20 6e 61 74 69 76 65 20 6d 61 6c 6c 6f 63  es native malloc
1bc80 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 66 6f  () and free() fo
1bc90 72 20 73 6f 6d 65 20 6f 70 65 72 61 74 69 6f 6e  r some operation
1bca0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  s..**.** ^The sq
1bcb0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72  lite3_malloc() r
1bcc0 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61  outine returns a
1bcd0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 62 6c   pointer to a bl
1bce0 6f 63 6b 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79  ock.** of memory
1bcf0 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65   at least N byte
1bd00 73 20 69 6e 20 6c 65 6e 67 74 68 2c 20 77 68 65  s in length, whe
1bd10 72 65 20 4e 20 69 73 20 74 68 65 20 70 61 72 61  re N is the para
1bd20 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 73 71  meter..** ^If sq
1bd30 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69  lite3_malloc() i
1bd40 73 20 75 6e 61 62 6c 65 20 74 6f 20 6f 62 74 61  s unable to obta
1bd50 69 6e 20 73 75 66 66 69 63 69 65 6e 74 20 66 72  in sufficient fr
1bd60 65 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 69 74  ee.** memory, it
1bd70 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20   returns a NULL 
1bd80 70 6f 69 6e 74 65 72 2e 20 20 5e 49 66 20 74 68  pointer.  ^If th
1bd90 65 20 70 61 72 61 6d 65 74 65 72 20 4e 20 74 6f  e parameter N to
1bda0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  .** sqlite3_mall
1bdb0 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 20  oc() is zero or 
1bdc0 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 73 71  negative then sq
1bdd0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72  lite3_malloc() r
1bde0 65 74 75 72 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c  eturns.** a NULL
1bdf0 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
1be00 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33  ^Calling sqlite3
1be10 5f 66 72 65 65 28 29 20 77 69 74 68 20 61 20 70  _free() with a p
1be20 6f 69 6e 74 65 72 20 70 72 65 76 69 6f 75 73 6c  ointer previousl
1be30 79 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79  y returned.** by
1be40 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
1be50 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61  ) or sqlite3_rea
1be60 6c 6c 6f 63 28 29 20 72 65 6c 65 61 73 65 73 20  lloc() releases 
1be70 74 68 61 74 20 6d 65 6d 6f 72 79 20 73 6f 0a 2a  that memory so.*
1be80 2a 20 74 68 61 74 20 69 74 20 6d 69 67 68 74 20  * that it might 
1be90 62 65 20 72 65 75 73 65 64 2e 20 20 5e 54 68 65  be reused.  ^The
1bea0 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20   sqlite3_free() 
1beb0 72 6f 75 74 69 6e 65 20 69 73 0a 2a 2a 20 61 20  routine is.** a 
1bec0 6e 6f 2d 6f 70 20 69 66 20 69 73 20 63 61 6c 6c  no-op if is call
1bed0 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70  ed with a NULL p
1bee0 6f 69 6e 74 65 72 2e 20 20 50 61 73 73 69 6e 67  ointer.  Passing
1bef0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a   a NULL pointer.
1bf00 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72  ** to sqlite3_fr
1bf10 65 65 28 29 20 69 73 20 68 61 72 6d 6c 65 73 73  ee() is harmless
1bf20 2e 20 20 41 66 74 65 72 20 62 65 69 6e 67 20 66  .  After being f
1bf30 72 65 65 64 2c 20 6d 65 6d 6f 72 79 0a 2a 2a 20  reed, memory.** 
1bf40 73 68 6f 75 6c 64 20 6e 65 69 74 68 65 72 20 62  should neither b
1bf50 65 20 72 65 61 64 20 6e 6f 72 20 77 72 69 74 74  e read nor writt
1bf60 65 6e 2e 20 20 45 76 65 6e 20 72 65 61 64 69 6e  en.  Even readin
1bf70 67 20 70 72 65 76 69 6f 75 73 6c 79 20 66 72 65  g previously fre
1bf80 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6d 69 67  ed.** memory mig
1bf90 68 74 20 72 65 73 75 6c 74 20 69 6e 20 61 20 73  ht result in a s
1bfa0 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c  egmentation faul
1bfb0 74 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72  t or other sever
1bfc0 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f  e error..** Memo
1bfd0 72 79 20 63 6f 72 72 75 70 74 69 6f 6e 2c 20 61  ry corruption, a
1bfe0 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61   segmentation fa
1bff0 75 6c 74 2c 20 6f 72 20 6f 74 68 65 72 20 73 65  ult, or other se
1c000 76 65 72 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 69  vere error.** mi
1c010 67 68 74 20 72 65 73 75 6c 74 20 69 66 20 73 71  ght result if sq
1c020 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 73 20  lite3_free() is 
1c030 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 6e 6f  called with a no
1c040 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74  n-NULL pointer t
1c050 68 61 74 0a 2a 2a 20 77 61 73 20 6e 6f 74 20 6f  hat.** was not o
1c060 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c  btained from sql
1c070 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72  ite3_malloc() or
1c080 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
1c090 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  ()..**.** ^(The 
1c0a0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1c0b0 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65  ) interface atte
1c0c0 6d 70 74 73 20 74 6f 20 72 65 73 69 7a 65 20 61  mpts to resize a
1c0d0 0a 2a 2a 20 70 72 69 6f 72 20 6d 65 6d 6f 72 79  .** prior memory
1c0e0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 62   allocation to b
1c0f0 65 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74  e at least N byt
1c100 65 73 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74  es, where N is t
1c110 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72  he.** second par
1c120 61 6d 65 74 65 72 2e 20 20 54 68 65 20 6d 65 6d  ameter.  The mem
1c130 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74  ory allocation t
1c140 6f 20 62 65 20 72 65 73 69 7a 65 64 20 69 73 20  o be resized is 
1c150 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72  the first.** par
1c160 61 6d 65 74 65 72 2e 29 5e 20 5e 20 49 66 20 74  ameter.)^ ^ If t
1c170 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
1c180 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65  er to sqlite3_re
1c190 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61 20  alloc().** is a 
1c1a0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65  NULL pointer the
1c1b0 6e 20 69 74 73 20 62 65 68 61 76 69 6f 72 20 69  n its behavior i
1c1c0 73 20 69 64 65 6e 74 69 63 61 6c 20 74 6f 20 63  s identical to c
1c1d0 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65  alling.** sqlite
1c1e0 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20 77 68 65 72  3_malloc(N) wher
1c1f0 65 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e  e N is the secon
1c200 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
1c210 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
1c220 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73 65 63  ..** ^If the sec
1c230 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ond parameter to
1c240 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
1c250 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 0a 2a 2a  () is zero or.**
1c260 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 74   negative then t
1c270 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 65  he behavior is e
1c280 78 61 63 74 6c 79 20 74 68 65 20 73 61 6d 65 20  xactly the same 
1c290 61 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71  as calling.** sq
1c2a0 6c 69 74 65 33 5f 66 72 65 65 28 50 29 20 77 68  lite3_free(P) wh
1c2b0 65 72 65 20 50 20 69 73 20 74 68 65 20 66 69 72  ere P is the fir
1c2c0 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
1c2d0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1c2e0 29 2e 0a 2a 2a 20 5e 73 71 6c 69 74 65 33 5f 72  )..** ^sqlite3_r
1c2f0 65 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73  ealloc() returns
1c300 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
1c310 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
1c320 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74  n.** of at least
1c330 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65   N bytes in size
1c340 20 6f 72 20 4e 55 4c 4c 20 69 66 20 73 75 66 66   or NULL if suff
1c350 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20 69 73  icient memory is
1c360 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a   unavailable..**
1c370 20 5e 49 66 20 4d 20 69 73 20 74 68 65 20 73 69   ^If M is the si
1c380 7a 65 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20  ze of the prior 
1c390 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e  allocation, then
1c3a0 20 6d 69 6e 28 4e 2c 4d 29 20 62 79 74 65 73 0a   min(N,M) bytes.
1c3b0 2a 2a 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20  ** of the prior 
1c3c0 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 72 65 20 63  allocation are c
1c3d0 6f 70 69 65 64 20 69 6e 74 6f 20 74 68 65 20 62  opied into the b
1c3e0 65 67 69 6e 6e 69 6e 67 20 6f 66 20 62 75 66 66  eginning of buff
1c3f0 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62  er returned.** b
1c400 79 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  y sqlite3_reallo
1c410 63 28 29 20 61 6e 64 20 74 68 65 20 70 72 69 6f  c() and the prio
1c420 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20  r allocation is 
1c430 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 73 71  freed..** ^If sq
1c440 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20  lite3_realloc() 
1c450 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2c 20 74 68  returns NULL, th
1c460 65 6e 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c  en the prior all
1c470 6f 63 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6e 6f  ocation.** is no
1c480 74 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  t freed..**.** ^
1c490 54 68 65 20 6d 65 6d 6f 72 79 20 72 65 74 75 72  The memory retur
1c4a0 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d  ned by sqlite3_m
1c4b0 61 6c 6c 6f 63 28 29 20 61 6e 64 20 73 71 6c 69  alloc() and sqli
1c4c0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a  te3_realloc().**
1c4d0 20 69 73 20 61 6c 77 61 79 73 20 61 6c 69 67 6e   is always align
1c4e0 65 64 20 74 6f 20 61 74 20 6c 65 61 73 74 20 61  ed to at least a
1c4f0 6e 20 38 20 62 79 74 65 20 62 6f 75 6e 64 61 72  n 8 byte boundar
1c500 79 2c 20 6f 72 20 74 6f 20 61 0a 2a 2a 20 34 20  y, or to a.** 4 
1c510 62 79 74 65 20 62 6f 75 6e 64 61 72 79 20 69 66  byte boundary if
1c520 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 34 5f 42   the [SQLITE_4_B
1c530 59 54 45 5f 41 4c 49 47 4e 45 44 5f 4d 41 4c 4c  YTE_ALIGNED_MALL
1c540 4f 43 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  OC] compile-time
1c550 0a 2a 2a 20 6f 70 74 69 6f 6e 20 69 73 20 75 73  .** option is us
1c560 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51 4c  ed..**.** In SQL
1c570 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e  ite version 3.5.
1c580 30 20 61 6e 64 20 33 2e 35 2e 31 2c 20 69 74 20  0 and 3.5.1, it 
1c590 77 61 73 20 70 6f 73 73 69 62 6c 65 20 74 6f 20  was possible to 
1c5a0 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20 53 51  define.** the SQ
1c5b0 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59  LITE_OMIT_MEMORY
1c5c0 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20 77 68 69 63  _ALLOCATION whic
1c5d0 68 20 77 6f 75 6c 64 20 63 61 75 73 65 20 74 68  h would cause th
1c5e0 65 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69 6d  e built-in.** im
1c5f0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
1c600 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74  these routines t
1c610 6f 20 62 65 20 6f 6d 69 74 74 65 64 2e 20 20 54  o be omitted.  T
1c620 68 61 74 20 63 61 70 61 62 69 6c 69 74 79 0a 2a  hat capability.*
1c630 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 70  * is no longer p
1c640 72 6f 76 69 64 65 64 2e 20 20 4f 6e 6c 79 20 62  rovided.  Only b
1c650 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61  uilt-in memory a
1c660 6c 6c 6f 63 61 74 6f 72 73 20 63 61 6e 20 62 65  llocators can be
1c670 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 50 72 69   used..**.** Pri
1c680 6f 72 20 74 6f 20 53 51 4c 69 74 65 20 76 65 72  or to SQLite ver
1c690 73 69 6f 6e 20 33 2e 37 2e 31 30 2c 20 74 68 65  sion 3.7.10, the
1c6a0 20 57 69 6e 64 6f 77 73 20 4f 53 20 69 6e 74 65   Windows OS inte
1c6b0 72 66 61 63 65 20 6c 61 79 65 72 20 63 61 6c 6c  rface layer call
1c6c0 65 64 0a 2a 2a 20 74 68 65 20 73 79 73 74 65 6d  ed.** the system
1c6d0 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72   malloc() and fr
1c6e0 65 65 28 29 20 64 69 72 65 63 74 6c 79 20 77 68  ee() directly wh
1c6f0 65 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a  en converting.**
1c700 20 66 69 6c 65 6e 61 6d 65 73 20 62 65 74 77 65   filenames betwe
1c710 65 6e 20 74 68 65 20 55 54 46 2d 38 20 65 6e 63  en the UTF-8 enc
1c720 6f 64 69 6e 67 20 75 73 65 64 20 62 79 20 53 51  oding used by SQ
1c730 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68 61 74  Lite.** and what
1c740 65 76 65 72 20 66 69 6c 65 6e 61 6d 65 20 65 6e  ever filename en
1c750 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64 20 62  coding is used b
1c760 79 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72  y the particular
1c770 20 57 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73 74   Windows.** inst
1c780 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72  allation.  Memor
1c790 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72  y allocation err
1c7a0 6f 72 73 20 77 65 72 65 20 64 65 74 65 63 74 65  ors were detecte
1c7b0 64 2c 20 62 75 74 0a 2a 2a 20 74 68 65 79 20 77  d, but.** they w
1c7c0 65 72 65 20 72 65 70 6f 72 74 65 64 20 62 61 63  ere reported bac
1c7d0 6b 20 61 73 20 5b 53 51 4c 49 54 45 5f 43 41 4e  k as [SQLITE_CAN
1c7e0 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51  TOPEN] or.** [SQ
1c7f0 4c 49 54 45 5f 49 4f 45 52 52 5d 20 72 61 74 68  LITE_IOERR] rath
1c800 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
1c810 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68  NOMEM]..**.** Th
1c820 65 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d 65  e pointer argume
1c830 6e 74 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  nts to [sqlite3_
1c840 66 72 65 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  free()] and [sql
1c850 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a  ite3_realloc()].
1c860 2a 2a 20 6d 75 73 74 20 62 65 20 65 69 74 68 65  ** must be eithe
1c870 72 20 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 20 70  r NULL or else p
1c880 6f 69 6e 74 65 72 73 20 6f 62 74 61 69 6e 65 64  ointers obtained
1c890 20 66 72 6f 6d 20 61 20 70 72 69 6f 72 0a 2a 2a   from a prior.**
1c8a0 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b   invocation of [
1c8b0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1c8c0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  ] or [sqlite3_re
1c8d0 61 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20 68 61  alloc()] that ha
1c8e0 76 65 0a 2a 2a 20 6e 6f 74 20 79 65 74 20 62 65  ve.** not yet be
1c8f0 65 6e 20 72 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a  en released..**.
1c900 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
1c910 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 72 65 61 64  on must not read
1c920 20 6f 72 20 77 72 69 74 65 20 61 6e 79 20 70 61   or write any pa
1c930 72 74 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f 63 6b  rt of.** a block
1c940 20 6f 66 20 6d 65 6d 6f 72 79 20 61 66 74 65 72   of memory after
1c950 20 69 74 20 68 61 73 20 62 65 65 6e 20 72 65 6c   it has been rel
1c960 65 61 73 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b  eased using.** [
1c970 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20  sqlite3_free()] 
1c980 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  or [sqlite3_real
1c990 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 76 6f 69 64 20  loc()]..*/.void 
1c9a0 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  *sqlite3_malloc(
1c9b0 69 6e 74 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69  int);.void *sqli
1c9c0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 76 6f 69 64  te3_realloc(void
1c9d0 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71  *, int);.void sq
1c9e0 6c 69 74 65 33 5f 66 72 65 65 28 76 6f 69 64 2a  lite3_free(void*
1c9f0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1ca00 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63  EF: Memory Alloc
1ca10 61 74 6f 72 20 53 74 61 74 69 73 74 69 63 73 0a  ator Statistics.
1ca20 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 70 72 6f  **.** SQLite pro
1ca30 76 69 64 65 73 20 74 68 65 73 65 20 74 77 6f 20  vides these two 
1ca40 69 6e 74 65 72 66 61 63 65 73 20 66 6f 72 20 72  interfaces for r
1ca50 65 70 6f 72 74 69 6e 67 20 6f 6e 20 74 68 65 20  eporting on the 
1ca60 73 74 61 74 75 73 0a 2a 2a 20 6f 66 20 74 68 65  status.** of the
1ca70 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
1ca80 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72  ()], [sqlite3_fr
1ca90 65 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69  ee()], and [sqli
1caa0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a  te3_realloc()].*
1cab0 2a 20 72 6f 75 74 69 6e 65 73 2c 20 77 68 69 63  * routines, whic
1cac0 68 20 66 6f 72 6d 20 74 68 65 20 62 75 69 6c 74  h form the built
1cad0 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  -in memory alloc
1cae0 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 2e  ation subsystem.
1caf0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c  .**.** ^The [sql
1cb00 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64  ite3_memory_used
1cb10 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75  ()] routine retu
1cb20 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
1cb30 66 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 6d 65  f bytes.** of me
1cb40 6d 6f 72 79 20 63 75 72 72 65 6e 74 6c 79 20 6f  mory currently o
1cb50 75 74 73 74 61 6e 64 69 6e 67 20 28 6d 61 6c 6c  utstanding (mall
1cb60 6f 63 65 64 20 62 75 74 20 6e 6f 74 20 66 72 65  oced but not fre
1cb70 65 64 29 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73 71  ed)..** ^The [sq
1cb80 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67  lite3_memory_hig
1cb90 68 77 61 74 65 72 28 29 5d 20 72 6f 75 74 69 6e  hwater()] routin
1cba0 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6d 61  e returns the ma
1cbb0 78 69 6d 75 6d 0a 2a 2a 20 76 61 6c 75 65 20 6f  ximum.** value o
1cbc0 66 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  f [sqlite3_memor
1cbd0 79 5f 75 73 65 64 28 29 5d 20 73 69 6e 63 65 20  y_used()] since 
1cbe0 74 68 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d  the high-water m
1cbf0 61 72 6b 0a 2a 2a 20 77 61 73 20 6c 61 73 74 20  ark.** was last 
1cc00 72 65 73 65 74 2e 20 20 5e 54 68 65 20 76 61 6c  reset.  ^The val
1cc10 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ues returned by 
1cc20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
1cc30 75 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b  used()] and.** [
1cc40 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68  sqlite3_memory_h
1cc50 69 67 68 77 61 74 65 72 28 29 5d 20 69 6e 63 6c  ighwater()] incl
1cc60 75 64 65 20 61 6e 79 20 6f 76 65 72 68 65 61 64  ude any overhead
1cc70 0a 2a 2a 20 61 64 64 65 64 20 62 79 20 53 51 4c  .** added by SQL
1cc80 69 74 65 20 69 6e 20 69 74 73 20 69 6d 70 6c 65  ite in its imple
1cc90 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 73 71  mentation of [sq
1cca0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c  lite3_malloc()],
1ccb0 0a 2a 2a 20 62 75 74 20 6e 6f 74 20 6f 76 65 72  .** but not over
1ccc0 68 65 61 64 20 61 64 64 65 64 20 62 79 20 74 68  head added by th
1ccd0 65 20 61 6e 79 20 75 6e 64 65 72 6c 79 69 6e 67  e any underlying
1cce0 20 73 79 73 74 65 6d 20 6c 69 62 72 61 72 79 0a   system library.
1ccf0 2a 2a 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74  ** routines that
1cd00 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
1cd10 28 29 5d 20 6d 61 79 20 63 61 6c 6c 2e 0a 2a 2a  ()] may call..**
1cd20 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20  .** ^The memory 
1cd30 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 20  high-water mark 
1cd40 69 73 20 72 65 73 65 74 20 74 6f 20 74 68 65 20  is reset to the 
1cd50 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66  current value of
1cd60 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  .** [sqlite3_mem
1cd70 6f 72 79 5f 75 73 65 64 28 29 5d 20 69 66 20 61  ory_used()] if a
1cd80 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 70  nd only if the p
1cd90 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b  arameter to.** [
1cda0 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68  sqlite3_memory_h
1cdb0 69 67 68 77 61 74 65 72 28 29 5d 20 69 73 20 74  ighwater()] is t
1cdc0 72 75 65 2e 20 20 5e 54 68 65 20 76 61 6c 75 65  rue.  ^The value
1cdd0 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20   returned.** by 
1cde0 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
1cdf0 68 69 67 68 77 61 74 65 72 28 31 29 5d 20 69 73  highwater(1)] is
1ce00 20 74 68 65 20 68 69 67 68 2d 77 61 74 65 72 20   the high-water 
1ce10 6d 61 72 6b 0a 2a 2a 20 70 72 69 6f 72 20 74 6f  mark.** prior to
1ce20 20 74 68 65 20 72 65 73 65 74 2e 0a 2a 2f 0a 73   the reset..*/.s
1ce30 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
1ce40 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64  ite3_memory_used
1ce50 28 76 6f 69 64 29 3b 0a 73 71 6c 69 74 65 33 5f  (void);.sqlite3_
1ce60 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65  int64 sqlite3_me
1ce70 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 69  mory_highwater(i
1ce80 6e 74 20 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a  nt resetFlag);..
1ce90 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1cea0 50 73 65 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75  Pseudo-Random Nu
1ceb0 6d 62 65 72 20 47 65 6e 65 72 61 74 6f 72 0a 2a  mber Generator.*
1cec0 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 6f 6e 74  *.** SQLite cont
1ced0 61 69 6e 73 20 61 20 68 69 67 68 2d 71 75 61 6c  ains a high-qual
1cee0 69 74 79 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f  ity pseudo-rando
1cef0 6d 20 6e 75 6d 62 65 72 20 67 65 6e 65 72 61 74  m number generat
1cf00 6f 72 20 28 50 52 4e 47 29 20 75 73 65 64 20 74  or (PRNG) used t
1cf10 6f 0a 2a 2a 20 73 65 6c 65 63 74 20 72 61 6e 64  o.** select rand
1cf20 6f 6d 20 5b 52 4f 57 49 44 20 7c 20 52 4f 57 49  om [ROWID | ROWI
1cf30 44 73 5d 20 77 68 65 6e 20 69 6e 73 65 72 74 69  Ds] when inserti
1cf40 6e 67 20 6e 65 77 20 72 65 63 6f 72 64 73 20 69  ng new records i
1cf50 6e 74 6f 20 61 20 74 61 62 6c 65 20 74 68 61 74  nto a table that
1cf60 0a 2a 2a 20 61 6c 72 65 61 64 79 20 75 73 65 73  .** already uses
1cf70 20 74 68 65 20 6c 61 72 67 65 73 74 20 70 6f 73   the largest pos
1cf80 73 69 62 6c 65 20 5b 52 4f 57 49 44 5d 2e 20 20  sible [ROWID].  
1cf90 54 68 65 20 50 52 4e 47 20 69 73 20 61 6c 73 6f  The PRNG is also
1cfa0 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65   used for.** the
1cfb0 20 62 75 69 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d   build-in random
1cfc0 28 29 20 61 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f  () and randomblo
1cfd0 62 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  b() SQL function
1cfe0 73 2e 20 20 54 68 69 73 20 69 6e 74 65 72 66 61  s.  This interfa
1cff0 63 65 20 61 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70  ce allows.** app
1d000 6c 69 63 61 74 69 6f 6e 73 20 74 6f 20 61 63 63  lications to acc
1d010 65 73 73 20 74 68 65 20 73 61 6d 65 20 50 52 4e  ess the same PRN
1d020 47 20 66 6f 72 20 6f 74 68 65 72 20 70 75 72 70  G for other purp
1d030 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 63  oses..**.** ^A c
1d040 61 6c 6c 20 74 6f 20 74 68 69 73 20 72 6f 75 74  all to this rout
1d050 69 6e 65 20 73 74 6f 72 65 73 20 4e 20 62 79 74  ine stores N byt
1d060 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73  es of randomness
1d070 20 69 6e 74 6f 20 62 75 66 66 65 72 20 50 2e 0a   into buffer P..
1d080 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
1d090 20 74 69 6d 65 20 74 68 69 73 20 72 6f 75 74 69   time this routi
1d0a0 6e 65 20 69 73 20 69 6e 76 6f 6b 65 64 20 28 65  ne is invoked (e
1d0b0 69 74 68 65 72 20 69 6e 74 65 72 6e 61 6c 6c 79  ither internally
1d0c0 20 6f 72 20 62 79 0a 2a 2a 20 74 68 65 20 61 70   or by.** the ap
1d0d0 70 6c 69 63 61 74 69 6f 6e 29 20 74 68 65 20 50  plication) the P
1d0e0 52 4e 47 20 69 73 20 73 65 65 64 65 64 20 75 73  RNG is seeded us
1d0f0 69 6e 67 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f  ing randomness o
1d100 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  btained.** from 
1d110 74 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 20  the xRandomness 
1d120 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 64 65  method of the de
1d130 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76  fault [sqlite3_v
1d140 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e  fs] object..** ^
1d150 4f 6e 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e  On all subsequen
1d160 74 20 69 6e 76 6f 63 61 74 69 6f 6e 73 2c 20 74  t invocations, t
1d170 68 65 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d  he pseudo-random
1d180 6e 65 73 73 20 69 73 20 67 65 6e 65 72 61 74 65  ness is generate
1d190 64 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c 79 20  d.** internally 
1d1a0 61 6e 64 20 77 69 74 68 6f 75 74 20 72 65 63 6f  and without reco
1d1b0 75 72 73 65 20 74 6f 20 74 68 65 20 5b 73 71 6c  urse to the [sql
1d1c0 69 74 65 33 5f 76 66 73 5d 20 78 52 61 6e 64 6f  ite3_vfs] xRando
1d1d0 6d 6e 65 73 73 0a 2a 2a 20 6d 65 74 68 6f 64 2e  mness.** method.
1d1e0 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  .*/.void sqlite3
1d1f0 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 69 6e 74 20  _randomness(int 
1d200 4e 2c 20 76 6f 69 64 20 2a 50 29 3b 0a 0a 2f 2a  N, void *P);../*
1d210 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
1d220 6d 70 69 6c 65 2d 54 69 6d 65 20 41 75 74 68 6f  mpile-Time Autho
1d230 72 69 7a 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63  rization Callbac
1d240 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72  ks.**.** ^This r
1d250 6f 75 74 69 6e 65 20 72 65 67 69 73 74 65 72 73  outine registers
1d260 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 63   an authorizer c
1d270 61 6c 6c 62 61 63 6b 20 77 69 74 68 20 61 20 70  allback with a p
1d280 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61  articular.** [da
1d290 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1d2a0 6e 5d 2c 20 73 75 70 70 6c 69 65 64 20 69 6e 20  n], supplied in 
1d2b0 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
1d2c0 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 61 75 74 68  nt..** ^The auth
1d2d0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
1d2e0 69 73 20 69 6e 76 6f 6b 65 64 20 61 73 20 53 51  is invoked as SQ
1d2f0 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65  L statements are
1d300 20 62 65 69 6e 67 20 63 6f 6d 70 69 6c 65 64 0a   being compiled.
1d310 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70  ** by [sqlite3_p
1d320 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73  repare()] or its
1d330 20 76 61 72 69 61 6e 74 73 20 5b 73 71 6c 69 74   variants [sqlit
1d340 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
1d350 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  ,.** [sqlite3_pr
1d360 65 70 61 72 65 31 36 28 29 5d 20 61 6e 64 20 5b  epare16()] and [
1d370 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
1d380 36 5f 76 32 28 29 5d 2e 20 20 5e 41 74 20 76 61  6_v2()].  ^At va
1d390 72 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74 73 20  rious.** points 
1d3a0 64 75 72 69 6e 67 20 74 68 65 20 63 6f 6d 70 69  during the compi
1d3b0 6c 61 74 69 6f 6e 20 70 72 6f 63 65 73 73 2c 20  lation process, 
1d3c0 61 73 20 6c 6f 67 69 63 20 69 73 20 62 65 69 6e  as logic is bein
1d3d0 67 20 63 72 65 61 74 65 64 0a 2a 2a 20 74 6f 20  g created.** to 
1d3e0 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20  perform various 
1d3f0 61 63 74 69 6f 6e 73 2c 20 74 68 65 20 61 75 74  actions, the aut
1d400 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1d410 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a   is invoked to.*
1d420 2a 20 73 65 65 20 69 66 20 74 68 6f 73 65 20 61  * see if those a
1d430 63 74 69 6f 6e 73 20 61 72 65 20 61 6c 6c 6f 77  ctions are allow
1d440 65 64 2e 20 20 5e 54 68 65 20 61 75 74 68 6f 72  ed.  ^The author
1d450 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 73 68  izer callback sh
1d460 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b  ould.** return [
1d470 53 51 4c 49 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c  SQLITE_OK] to al
1d480 6c 6f 77 20 74 68 65 20 61 63 74 69 6f 6e 2c 20  low the action, 
1d490 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20  [SQLITE_IGNORE] 
1d4a0 74 6f 20 64 69 73 61 6c 6c 6f 77 20 74 68 65 0a  to disallow the.
1d4b0 2a 2a 20 73 70 65 63 69 66 69 63 20 61 63 74 69  ** specific acti
1d4c0 6f 6e 20 62 75 74 20 61 6c 6c 6f 77 20 74 68 65  on but allow the
1d4d0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
1d4e0 6f 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65  o continue to be
1d4f0 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c 20 6f 72  .** compiled, or
1d500 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20 74   [SQLITE_DENY] t
1d510 6f 20 63 61 75 73 65 20 74 68 65 20 65 6e 74 69  o cause the enti
1d520 72 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  re SQL statement
1d530 20 74 6f 20 62 65 0a 2a 2a 20 72 65 6a 65 63 74   to be.** reject
1d540 65 64 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72  ed with an error
1d550 2e 20 20 5e 49 66 20 74 68 65 20 61 75 74 68 6f  .  ^If the autho
1d560 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72  rizer callback r
1d570 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 76 61  eturns.** any va
1d580 6c 75 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b  lue other than [
1d590 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20  SQLITE_IGNORE], 
1d5a0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20  [SQLITE_OK], or 
1d5b0 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a  [SQLITE_DENY].**
1d5c0 20 74 68 65 6e 20 74 68 65 20 5b 73 71 6c 69 74   then the [sqlit
1d5d0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
1d5e0 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63   or equivalent c
1d5f0 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72  all that trigger
1d600 65 64 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72  ed.** the author
1d610 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77  izer will fail w
1d620 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73  ith an error mes
1d630 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  sage..**.** When
1d640 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65   the callback re
1d650 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
1d660 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68  ], that means th
1d670 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 72  e operation.** r
1d680 65 71 75 65 73 74 65 64 20 69 73 20 6f 6b 2e 20  equested is ok. 
1d690 20 5e 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62   ^When the callb
1d6a0 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ack returns [SQL
1d6b0 49 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65 0a 2a  ITE_DENY], the.*
1d6c0 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
1d6d0 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69  re_v2()] or equi
1d6e0 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74  valent call that
1d6f0 20 74 72 69 67 67 65 72 65 64 20 74 68 65 0a 2a   triggered the.*
1d700 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c  * authorizer wil
1d710 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65  l fail with an e
1d720 72 72 6f 72 20 6d 65 73 73 61 67 65 20 65 78 70  rror message exp
1d730 6c 61 69 6e 69 6e 67 20 74 68 61 74 0a 2a 2a 20  laining that.** 
1d740 61 63 63 65 73 73 20 69 73 20 64 65 6e 69 65 64  access is denied
1d750 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  . .**.** ^The fi
1d760 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rst parameter to
1d770 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
1d780 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f  callback is a co
1d790 70 79 20 6f 66 20 74 68 65 20 74 68 69 72 64 0a  py of the third.
1d7a0 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  ** parameter to 
1d7b0 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  the sqlite3_set_
1d7c0 61 75 74 68 6f 72 69 7a 65 72 28 29 20 69 6e 74  authorizer() int
1d7d0 65 72 66 61 63 65 2e 20 5e 54 68 65 20 73 65 63  erface. ^The sec
1d7e0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  ond parameter.**
1d7f0 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
1d800 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 5b   is an integer [
1d810 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61 63  SQLITE_COPY | ac
1d820 74 69 6f 6e 20 63 6f 64 65 5d 20 74 68 61 74 20  tion code] that 
1d830 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 74 68 65  specifies.** the
1d840 20 70 61 72 74 69 63 75 6c 61 72 20 61 63 74 69   particular acti
1d850 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69  on to be authori
1d860 7a 65 64 2e 20 5e 54 68 65 20 74 68 69 72 64 20  zed. ^The third 
1d870 74 68 72 6f 75 67 68 20 73 69 78 74 68 20 70 61  through sixth pa
1d880 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 74  rameters.** to t
1d890 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 72 65 20  he callback are 
1d8a0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
1d8b0 73 74 72 69 6e 67 73 20 74 68 61 74 20 63 6f 6e  strings that con
1d8c0 74 61 69 6e 20 61 64 64 69 74 69 6f 6e 61 6c 0a  tain additional.
1d8d0 2a 2a 20 64 65 74 61 69 6c 73 20 61 62 6f 75 74  ** details about
1d8e0 20 74 68 65 20 61 63 74 69 6f 6e 20 74 6f 20 62   the action to b
1d8f0 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a  e authorized..**
1d900 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74 69  .** ^If the acti
1d910 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49  on code is [SQLI
1d920 54 45 5f 52 45 41 44 5d 0a 2a 2a 20 61 6e 64 20  TE_READ].** and 
1d930 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  the callback ret
1d940 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 49 47 4e  urns [SQLITE_IGN
1d950 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 0a 2a 2a  ORE] then the.**
1d960 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
1d970 6d 65 6e 74 5d 20 73 74 61 74 65 6d 65 6e 74 20  ment] statement 
1d980 69 73 20 63 6f 6e 73 74 72 75 63 74 65 64 20 74  is constructed t
1d990 6f 20 73 75 62 73 74 69 74 75 74 65 0a 2a 2a 20  o substitute.** 
1d9a0 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20 69 6e 20  a NULL value in 
1d9b0 70 6c 61 63 65 20 6f 66 20 74 68 65 20 74 61 62  place of the tab
1d9c0 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 77  le column that w
1d9d0 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20 62 65 65  ould have.** bee
1d9e0 6e 20 72 65 61 64 20 69 66 20 5b 53 51 4c 49 54  n read if [SQLIT
1d9f0 45 5f 4f 4b 5d 20 68 61 64 20 62 65 65 6e 20 72  E_OK] had been r
1da00 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 5b 53  eturned.  The [S
1da10 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a  QLITE_IGNORE].**
1da20 20 72 65 74 75 72 6e 20 63 61 6e 20 62 65 20 75   return can be u
1da30 73 65 64 20 74 6f 20 64 65 6e 79 20 61 6e 20 75  sed to deny an u
1da40 6e 74 72 75 73 74 65 64 20 75 73 65 72 20 61 63  ntrusted user ac
1da50 63 65 73 73 20 74 6f 20 69 6e 64 69 76 69 64 75  cess to individu
1da60 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66  al.** columns of
1da70 20 61 20 74 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66   a table..** ^If
1da80 20 74 68 65 20 61 63 74 69 6f 6e 20 63 6f 64 65   the action code
1da90 20 69 73 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45   is [SQLITE_DELE
1daa0 54 45 5d 20 61 6e 64 20 74 68 65 20 63 61 6c 6c  TE] and the call
1dab0 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20  back returns.** 
1dac0 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20  [SQLITE_IGNORE] 
1dad0 74 68 65 6e 20 74 68 65 20 5b 44 45 4c 45 54 45  then the [DELETE
1dae0 5d 20 6f 70 65 72 61 74 69 6f 6e 20 70 72 6f 63  ] operation proc
1daf0 65 65 64 73 20 62 75 74 20 74 68 65 0a 2a 2a 20  eeds but the.** 
1db00 5b 74 72 75 6e 63 61 74 65 20 6f 70 74 69 6d 69  [truncate optimi
1db10 7a 61 74 69 6f 6e 5d 20 69 73 20 64 69 73 61 62  zation] is disab
1db20 6c 65 64 20 61 6e 64 20 61 6c 6c 20 72 6f 77 73  led and all rows
1db30 20 61 72 65 20 64 65 6c 65 74 65 64 20 69 6e 64   are deleted ind
1db40 69 76 69 64 75 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a  ividually..**.**
1db50 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 69   An authorizer i
1db60 73 20 75 73 65 64 20 77 68 65 6e 20 5b 73 71 6c  s used when [sql
1db70 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70  ite3_prepare | p
1db80 72 65 70 61 72 69 6e 67 5d 0a 2a 2a 20 53 51 4c  reparing].** SQL
1db90 20 73 74 61 74 65 6d 65 6e 74 73 20 66 72 6f 6d   statements from
1dba0 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73 6f   an untrusted so
1dbb0 75 72 63 65 2c 20 74 6f 20 65 6e 73 75 72 65 20  urce, to ensure 
1dbc0 74 68 61 74 20 74 68 65 20 53 51 4c 20 73 74 61  that the SQL sta
1dbd0 74 65 6d 65 6e 74 73 0a 2a 2a 20 64 6f 20 6e 6f  tements.** do no
1dbe0 74 20 74 72 79 20 74 6f 20 61 63 63 65 73 73 20  t try to access 
1dbf0 64 61 74 61 20 74 68 65 79 20 61 72 65 20 6e 6f  data they are no
1dc00 74 20 61 6c 6c 6f 77 65 64 20 74 6f 20 73 65 65  t allowed to see
1dc10 2c 20 6f 72 20 74 68 61 74 20 74 68 65 79 20 64  , or that they d
1dc20 6f 20 6e 6f 74 0a 2a 2a 20 74 72 79 20 74 6f 20  o not.** try to 
1dc30 65 78 65 63 75 74 65 20 6d 61 6c 69 63 69 6f 75  execute maliciou
1dc40 73 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 61  s statements tha
1dc50 74 20 64 61 6d 61 67 65 20 74 68 65 20 64 61 74  t damage the dat
1dc60 61 62 61 73 65 2e 20 20 46 6f 72 0a 2a 2a 20 65  abase.  For.** e
1dc70 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69  xample, an appli
1dc80 63 61 74 69 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77  cation may allow
1dc90 20 61 20 75 73 65 72 20 74 6f 20 65 6e 74 65 72   a user to enter
1dca0 20 61 72 62 69 74 72 61 72 79 0a 2a 2a 20 53 51   arbitrary.** SQ
1dcb0 4c 20 71 75 65 72 69 65 73 20 66 6f 72 20 65 76  L queries for ev
1dcc0 61 6c 75 61 74 69 6f 6e 20 62 79 20 61 20 64 61  aluation by a da
1dcd0 74 61 62 61 73 65 2e 20 20 42 75 74 20 74 68 65  tabase.  But the
1dce0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65   application doe
1dcf0 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 20 74 68  s.** not want th
1dd00 65 20 75 73 65 72 20 74 6f 20 62 65 20 61 62 6c  e user to be abl
1dd10 65 20 74 6f 20 6d 61 6b 65 20 61 72 62 69 74 72  e to make arbitr
1dd20 61 72 79 20 63 68 61 6e 67 65 73 20 74 6f 20 74  ary changes to t
1dd30 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20  he.** database. 
1dd40 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 63   An authorizer c
1dd50 6f 75 6c 64 20 74 68 65 6e 20 62 65 20 70 75 74  ould then be put
1dd60 20 69 6e 20 70 6c 61 63 65 20 77 68 69 6c 65 20   in place while 
1dd70 74 68 65 0a 2a 2a 20 75 73 65 72 2d 65 6e 74 65  the.** user-ente
1dd80 72 65 64 20 53 51 4c 20 69 73 20 62 65 69 6e 67  red SQL is being
1dd90 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1dda0 65 20 7c 20 70 72 65 70 61 72 65 64 5d 20 74 68  e | prepared] th
1ddb0 61 74 0a 2a 2a 20 64 69 73 61 6c 6c 6f 77 73 20  at.** disallows 
1ddc0 65 76 65 72 79 74 68 69 6e 67 20 65 78 63 65 70  everything excep
1ddd0 74 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65  t [SELECT] state
1dde0 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 41 70 70  ments..**.** App
1ddf0 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6e  lications that n
1de00 65 65 64 20 74 6f 20 70 72 6f 63 65 73 73 20 53  eed to process S
1de10 51 4c 20 66 72 6f 6d 20 75 6e 74 72 75 73 74 65  QL from untruste
1de20 64 20 73 6f 75 72 63 65 73 0a 2a 2a 20 6d 69 67  d sources.** mig
1de30 68 74 20 61 6c 73 6f 20 63 6f 6e 73 69 64 65 72  ht also consider
1de40 20 6c 6f 77 65 72 69 6e 67 20 72 65 73 6f 75 72   lowering resour
1de50 63 65 20 6c 69 6d 69 74 73 20 75 73 69 6e 67 20  ce limits using 
1de60 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29  [sqlite3_limit()
1de70 5d 0a 2a 2a 20 61 6e 64 20 6c 69 6d 69 74 69 6e  ].** and limitin
1de80 67 20 64 61 74 61 62 61 73 65 20 73 69 7a 65 20  g database size 
1de90 75 73 69 6e 67 20 74 68 65 20 5b 6d 61 78 5f 70  using the [max_p
1dea0 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47  age_count] [PRAG
1deb0 4d 41 5d 0a 2a 2a 20 69 6e 20 61 64 64 69 74 69  MA].** in additi
1dec0 6f 6e 20 74 6f 20 75 73 69 6e 67 20 61 6e 20 61  on to using an a
1ded0 75 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a  uthorizer..**.**
1dee0 20 5e 28 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65   ^(Only a single
1def0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6e 20   authorizer can 
1df00 62 65 20 69 6e 20 70 6c 61 63 65 20 6f 6e 20 61  be in place on a
1df10 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1df20 74 69 6f 6e 0a 2a 2a 20 61 74 20 61 20 74 69 6d  tion.** at a tim
1df30 65 2e 20 20 45 61 63 68 20 63 61 6c 6c 20 74 6f  e.  Each call to
1df40 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74   sqlite3_set_aut
1df50 68 6f 72 69 7a 65 72 20 6f 76 65 72 72 69 64 65  horizer override
1df60 73 20 74 68 65 0a 2a 2a 20 70 72 65 76 69 6f 75  s the.** previou
1df70 73 20 63 61 6c 6c 2e 29 5e 20 20 5e 44 69 73 61  s call.)^  ^Disa
1df80 62 6c 65 20 74 68 65 20 61 75 74 68 6f 72 69 7a  ble the authoriz
1df90 65 72 20 62 79 20 69 6e 73 74 61 6c 6c 69 6e 67  er by installing
1dfa0 20 61 20 4e 55 4c 4c 20 63 61 6c 6c 62 61 63 6b   a NULL callback
1dfb0 2e 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69  ..** The authori
1dfc0 7a 65 72 20 69 73 20 64 69 73 61 62 6c 65 64 20  zer is disabled 
1dfd0 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a  by default..**.*
1dfe0 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72  * The authorizer
1dff0 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e   callback must n
1e000 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74  ot do anything t
1e010 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a  hat will modify.
1e020 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ** the database 
1e030 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20  connection that 
1e040 69 6e 76 6f 6b 65 64 20 74 68 65 20 61 75 74 68  invoked the auth
1e050 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 2e  orizer callback.
1e060 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73  .** Note that [s
1e070 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
1e080 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  2()] and [sqlite
1e090 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d  3_step()] both m
1e0a0 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64  odify their.** d
1e0b0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1e0c0 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e  ons for the mean
1e0d0 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20  ing of "modify" 
1e0e0 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70  in this paragrap
1e0f0 68 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 5b  h..**.** ^When [
1e100 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
1e110 76 32 28 29 5d 20 69 73 20 75 73 65 64 20 74 6f  v2()] is used to
1e120 20 70 72 65 70 61 72 65 20 61 20 73 74 61 74 65   prepare a state
1e130 6d 65 6e 74 2c 20 74 68 65 0a 2a 2a 20 73 74 61  ment, the.** sta
1e140 74 65 6d 65 6e 74 20 6d 69 67 68 74 20 62 65 20  tement might be 
1e150 72 65 2d 70 72 65 70 61 72 65 64 20 64 75 72 69  re-prepared duri
1e160 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ng [sqlite3_step
1e170 28 29 5d 20 64 75 65 20 74 6f 20 61 20 0a 2a 2a  ()] due to a .**
1e180 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 20   schema change. 
1e190 20 48 65 6e 63 65 2c 20 74 68 65 20 61 70 70 6c   Hence, the appl
1e1a0 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 65  ication should e
1e1b0 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 0a 2a  nsure that the.*
1e1c0 2a 20 63 6f 72 72 65 63 74 20 61 75 74 68 6f 72  * correct author
1e1d0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65  izer callback re
1e1e0 6d 61 69 6e 73 20 69 6e 20 70 6c 61 63 65 20 64  mains in place d
1e1f0 75 72 69 6e 67 20 74 68 65 20 5b 73 71 6c 69 74  uring the [sqlit
1e200 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a  e3_step()]..**.*
1e210 2a 20 5e 4e 6f 74 65 20 74 68 61 74 20 74 68 65  * ^Note that the
1e220 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
1e230 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
1e240 6f 6e 6c 79 20 64 75 72 69 6e 67 0a 2a 2a 20 5b  only during.** [
1e250 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
1e260 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e  )] or its varian
1e270 74 73 2e 20 20 41 75 74 68 6f 72 69 7a 61 74 69  ts.  Authorizati
1e280 6f 6e 20 69 73 20 6e 6f 74 0a 2a 2a 20 70 65 72  on is not.** per
1e290 66 6f 72 6d 65 64 20 64 75 72 69 6e 67 20 73 74  formed during st
1e2a0 61 74 65 6d 65 6e 74 20 65 76 61 6c 75 61 74 69  atement evaluati
1e2b0 6f 6e 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 73  on in [sqlite3_s
1e2c0 74 65 70 28 29 5d 2c 20 75 6e 6c 65 73 73 0a 2a  tep()], unless.*
1e2d0 2a 20 61 73 20 73 74 61 74 65 64 20 69 6e 20 74  * as stated in t
1e2e0 68 65 20 70 72 65 76 69 6f 75 73 20 70 61 72 61  he previous para
1e2f0 67 72 61 70 68 2c 20 73 71 6c 69 74 65 33 5f 73  graph, sqlite3_s
1e300 74 65 70 28 29 20 69 6e 76 6f 6b 65 73 0a 2a 2a  tep() invokes.**
1e310 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
1e320 5f 76 32 28 29 20 74 6f 20 72 65 70 72 65 70 61  _v2() to reprepa
1e330 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74 20 61  re a statement a
1e340 66 74 65 72 20 61 20 73 63 68 65 6d 61 20 63 68  fter a schema ch
1e350 61 6e 67 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  ange..*/.int sql
1e360 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
1e370 7a 65 72 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c  zer(.  sqlite3*,
1e380 0a 20 20 69 6e 74 20 28 2a 78 41 75 74 68 29 28  .  int (*xAuth)(
1e390 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
1e3a0 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72  char*,const char
1e3b0 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f  *,const char*,co
1e3c0 6e 73 74 20 63 68 61 72 2a 29 2c 0a 20 20 76 6f  nst char*),.  vo
1e3d0 69 64 20 2a 70 55 73 65 72 44 61 74 61 0a 29 3b  id *pUserData.);
1e3e0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1e3f0 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 52 65 74  : Authorizer Ret
1e400 75 72 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20  urn Codes.**.** 
1e410 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  The [sqlite3_set
1e420 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75  _authorizer | au
1e430 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1e440 6b 20 66 75 6e 63 74 69 6f 6e 5d 20 6d 75 73 74  k function] must
1e450 0a 2a 2a 20 72 65 74 75 72 6e 20 65 69 74 68 65  .** return eithe
1e460 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72  r [SQLITE_OK] or
1e470 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 74 77   one of these tw
1e480 6f 20 63 6f 6e 73 74 61 6e 74 73 20 69 6e 20 6f  o constants in o
1e490 72 64 65 72 0a 2a 2a 20 74 6f 20 73 69 67 6e 61  rder.** to signa
1e4a0 6c 20 53 51 4c 69 74 65 20 77 68 65 74 68 65 72  l SQLite whether
1e4b0 20 6f 72 20 6e 6f 74 20 74 68 65 20 61 63 74 69   or not the acti
1e4c0 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64 2e  on is permitted.
1e4d0 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 5b 73 71    See the.** [sq
1e4e0 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
1e4f0 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65  izer | authorize
1e500 72 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d  r documentation]
1e510 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a   for additional.
1e520 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  ** information..
1e530 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  **.** Note that 
1e540 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 69 73  SQLITE_IGNORE is
1e550 20 61 6c 73 6f 20 75 73 65 64 20 61 73 20 61 20   also used as a 
1e560 5b 53 51 4c 49 54 45 5f 52 4f 4c 4c 42 41 43 4b  [SQLITE_ROLLBACK
1e570 20 7c 20 72 65 74 75 72 6e 20 63 6f 64 65 5d 0a   | return code].
1e580 2a 2a 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c  ** from the [sql
1e590 69 74 65 33 5f 76 74 61 62 5f 6f 6e 5f 63 6f 6e  ite3_vtab_on_con
1e5a0 66 6c 69 63 74 28 29 5d 20 69 6e 74 65 72 66 61  flict()] interfa
1e5b0 63 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ce..*/.#define S
1e5c0 51 4c 49 54 45 5f 44 45 4e 59 20 20 20 31 20 20  QLITE_DENY   1  
1e5d0 20 2f 2a 20 41 62 6f 72 74 20 74 68 65 20 53 51   /* Abort the SQ
1e5e0 4c 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68  L statement with
1e5f0 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65   an error */.#de
1e600 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 47 4e 4f  fine SQLITE_IGNO
1e610 52 45 20 32 20 20 20 2f 2a 20 44 6f 6e 27 74 20  RE 2   /* Don't 
1e620 61 6c 6c 6f 77 20 61 63 63 65 73 73 2c 20 62 75  allow access, bu
1e630 74 20 64 6f 6e 27 74 20 67 65 6e 65 72 61 74 65  t don't generate
1e640 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a   an error */../*
1e650 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75  .** CAPI3REF: Au
1e660 74 68 6f 72 69 7a 65 72 20 41 63 74 69 6f 6e 20  thorizer Action 
1e670 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20  Codes.**.** The 
1e680 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74  [sqlite3_set_aut
1e690 68 6f 72 69 7a 65 72 28 29 5d 20 69 6e 74 65 72  horizer()] inter
1e6a0 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61  face registers a
1e6b0 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
1e6c0 6f 6e 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e  on.** that is in
1e6d0 76 6f 6b 65 64 20 74 6f 20 61 75 74 68 6f 72 69  voked to authori
1e6e0 7a 65 20 63 65 72 74 61 69 6e 20 53 51 4c 20 73  ze certain SQL s
1e6f0 74 61 74 65 6d 65 6e 74 20 61 63 74 69 6f 6e 73  tatement actions
1e700 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64  .  The.** second
1e710 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
1e720 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e  e callback is an
1e730 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20 74 68   integer code th
1e740 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20  at specifies.** 
1e750 77 68 61 74 20 61 63 74 69 6f 6e 20 69 73 20 62  what action is b
1e760 65 69 6e 67 20 61 75 74 68 6f 72 69 7a 65 64 2e  eing authorized.
1e770 20 20 54 68 65 73 65 20 61 72 65 20 74 68 65 20    These are the 
1e780 69 6e 74 65 67 65 72 20 61 63 74 69 6f 6e 20 63  integer action c
1e790 6f 64 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65  odes that.** the
1e7a0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
1e7b0 62 61 63 6b 20 6d 61 79 20 62 65 20 70 61 73 73  back may be pass
1e7c0 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ed..**.** These 
1e7d0 61 63 74 69 6f 6e 20 63 6f 64 65 20 76 61 6c 75  action code valu
1e7e0 65 73 20 73 69 67 6e 69 66 79 20 77 68 61 74 20  es signify what 
1e7f0 6b 69 6e 64 20 6f 66 20 6f 70 65 72 61 74 69 6f  kind of operatio
1e800 6e 20 69 73 20 74 6f 20 62 65 0a 2a 2a 20 61 75  n is to be.** au
1e810 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 20 33  thorized.  The 3
1e820 72 64 20 61 6e 64 20 34 74 68 20 70 61 72 61 6d  rd and 4th param
1e830 65 74 65 72 73 20 74 6f 20 74 68 65 20 61 75 74  eters to the aut
1e840 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61  horization.** ca
1e850 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
1e860 77 69 6c 6c 20 62 65 20 70 61 72 61 6d 65 74 65  will be paramete
1e870 72 73 20 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e  rs or NULL depen
1e880 64 69 6e 67 20 6f 6e 20 77 68 69 63 68 20 6f 66  ding on which of
1e890 20 74 68 65 73 65 0a 2a 2a 20 63 6f 64 65 73 20   these.** codes 
1e8a0 69 73 20 75 73 65 64 20 61 73 20 74 68 65 20 73  is used as the s
1e8b0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e  econd parameter.
1e8c0 20 20 5e 28 54 68 65 20 35 74 68 20 70 61 72 61    ^(The 5th para
1e8d0 6d 65 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20  meter to the.** 
1e8e0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
1e8f0 61 63 6b 20 69 73 20 74 68 65 20 6e 61 6d 65 20  ack is the name 
1e900 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  of the database 
1e910 28 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c  ("main", "temp",
1e920 0a 2a 2a 20 65 74 63 2e 29 20 69 66 20 61 70 70  .** etc.) if app
1e930 6c 69 63 61 62 6c 65 2e 29 5e 20 20 5e 54 68 65  licable.)^  ^The
1e940 20 36 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   6th parameter t
1e950 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  o the authorizer
1e960 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20   callback.** is 
1e970 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
1e980 69 6e 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67 67  inner-most trigg
1e990 65 72 20 6f 72 20 76 69 65 77 20 74 68 61 74 20  er or view that 
1e9a0 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66  is responsible f
1e9b0 6f 72 0a 2a 2a 20 74 68 65 20 61 63 63 65 73 73  or.** the access
1e9c0 20 61 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c 4c   attempt or NULL
1e9d0 20 69 66 20 74 68 69 73 20 61 63 63 65 73 73 20   if this access 
1e9e0 61 74 74 65 6d 70 74 20 69 73 20 64 69 72 65 63  attempt is direc
1e9f0 74 6c 79 20 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d  tly from.** top-
1ea00 6c 65 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a  level SQL code..
1ea10 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  */./************
1ea20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1ea30 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20  *************** 
1ea40 33 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  3rd ************
1ea50 20 34 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a   4th ***********
1ea60 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1ea70 5f 43 52 45 41 54 45 5f 49 4e 44 45 58 20 20 20  _CREATE_INDEX   
1ea80 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20 49 6e         1   /* In
1ea90 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61  dex Name      Ta
1eaa0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
1eab0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1eac0 43 52 45 41 54 45 5f 54 41 42 4c 45 20 20 20 20  CREATE_TABLE    
1ead0 20 20 20 20 20 20 32 20 20 20 2f 2a 20 54 61 62        2   /* Tab
1eae0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
1eaf0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
1eb00 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
1eb10 52 45 41 54 45 5f 54 45 4d 50 5f 49 4e 44 45 58  REATE_TEMP_INDEX
1eb20 20 20 20 20 20 33 20 20 20 2f 2a 20 49 6e 64 65       3   /* Inde
1eb30 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c  x Name      Tabl
1eb40 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
1eb50 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
1eb60 45 41 54 45 5f 54 45 4d 50 5f 54 41 42 4c 45 20  EATE_TEMP_TABLE 
1eb70 20 20 20 20 34 20 20 20 2f 2a 20 54 61 62 6c 65      4   /* Table
1eb80 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
1eb90 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
1eba0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
1ebb0 41 54 45 5f 54 45 4d 50 5f 54 52 49 47 47 45 52  ATE_TEMP_TRIGGER
1ebc0 20 20 20 35 20 20 20 2f 2a 20 54 72 69 67 67 65     5   /* Trigge
1ebd0 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20  r Name    Table 
1ebe0 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
1ebf0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
1ec00 54 45 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20  TE_TEMP_VIEW    
1ec10 20 20 36 20 20 20 2f 2a 20 56 69 65 77 20 4e 61    6   /* View Na
1ec20 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  me       NULL   
1ec30 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1ec40 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
1ec50 45 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 20  E_TRIGGER       
1ec60 20 37 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20   7   /* Trigger 
1ec70 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61  Name    Table Na
1ec80 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
1ec90 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
1eca0 5f 56 49 45 57 20 20 20 20 20 20 20 20 20 20 20  _VIEW           
1ecb0 38 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65  8   /* View Name
1ecc0 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
1ecd0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
1ece0 65 20 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 20  e SQLITE_DELETE 
1ecf0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 39                 9
1ed00 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
1ed10 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1ed20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1ed30 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 49 4e 44   SQLITE_DROP_IND
1ed40 45 58 20 20 20 20 20 20 20 20 20 20 20 31 30 20  EX           10 
1ed50 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20    /* Index Name 
1ed60 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20       Table Name 
1ed70 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1ed80 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 41 42 4c  SQLITE_DROP_TABL
1ed90 45 20 20 20 20 20 20 20 20 20 20 20 31 31 20 20  E           11  
1eda0 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
1edb0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
1edc0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1edd0 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f  QLITE_DROP_TEMP_
1ede0 49 4e 44 45 58 20 20 20 20 20 20 31 32 20 20 20  INDEX      12   
1edf0 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20  /* Index Name   
1ee00 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
1ee10 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1ee20 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54  LITE_DROP_TEMP_T
1ee30 41 42 4c 45 20 20 20 20 20 20 31 33 20 20 20 2f  ABLE      13   /
1ee40 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
1ee50 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1ee60 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1ee70 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 52  ITE_DROP_TEMP_TR
1ee80 49 47 47 45 52 20 20 20 20 31 34 20 20 20 2f 2a  IGGER    14   /*
1ee90 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20   Trigger Name   
1eea0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1eeb0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1eec0 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 56 49 45  TE_DROP_TEMP_VIE
1eed0 57 20 20 20 20 20 20 20 31 35 20 20 20 2f 2a 20  W       15   /* 
1eee0 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20  View Name       
1eef0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1ef00 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1ef10 45 5f 44 52 4f 50 5f 54 52 49 47 47 45 52 20 20  E_DROP_TRIGGER  
1ef20 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20 54         16   /* T
1ef30 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54  rigger Name    T
1ef40 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
1ef50 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1ef60 5f 44 52 4f 50 5f 56 49 45 57 20 20 20 20 20 20  _DROP_VIEW      
1ef70 20 20 20 20 20 20 31 37 20 20 20 2f 2a 20 56 69        17   /* Vi
1ef80 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55  ew Name       NU
1ef90 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
1efa0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1efb0 49 4e 53 45 52 54 20 20 20 20 20 20 20 20 20 20  INSERT          
1efc0 20 20 20 20 20 31 38 20 20 20 2f 2a 20 54 61 62       18   /* Tab
1efd0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
1efe0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
1eff0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50  #define SQLITE_P
1f000 52 41 47 4d 41 20 20 20 20 20 20 20 20 20 20 20  RAGMA           
1f010 20 20 20 20 31 39 20 20 20 2f 2a 20 50 72 61 67      19   /* Prag
1f020 6d 61 20 4e 61 6d 65 20 20 20 20 20 31 73 74 20  ma Name     1st 
1f030 61 72 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23  arg or NULL */.#
1f040 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45  define SQLITE_RE
1f050 41 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20  AD              
1f060 20 20 20 32 30 20 20 20 2f 2a 20 54 61 62 6c 65     20   /* Table
1f070 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d   Name      Colum
1f080 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64  n Name     */.#d
1f090 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 4c  efine SQLITE_SEL
1f0a0 45 43 54 20 20 20 20 20 20 20 20 20 20 20 20 20  ECT             
1f0b0 20 20 32 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20    21   /* NULL  
1f0c0 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20            NULL  
1f0d0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
1f0e0 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e  fine SQLITE_TRAN
1f0f0 53 41 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20  SACTION         
1f100 20 32 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69   22   /* Operati
1f110 6f 6e 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  on       NULL   
1f120 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1f130 69 6e 65 20 53 51 4c 49 54 45 5f 55 50 44 41 54  ine SQLITE_UPDAT
1f140 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  E               
1f150 32 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  23   /* Table Na
1f160 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e  me      Column N
1f170 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  ame     */.#defi
1f180 6e 65 20 53 51 4c 49 54 45 5f 41 54 54 41 43 48  ne SQLITE_ATTACH
1f190 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
1f1a0 34 20 20 20 2f 2a 20 46 69 6c 65 6e 61 6d 65 20  4   /* Filename 
1f1b0 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
1f1c0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
1f1d0 65 20 53 51 4c 49 54 45 5f 44 45 54 41 43 48 20  e SQLITE_DETACH 
1f1e0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 35                25
1f1f0 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e     /* Database N
1f200 61 6d 65 20 20 20 4e 55 4c 4c 20 20 20 20 20 20  ame   NULL      
1f210 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1f220 20 53 51 4c 49 54 45 5f 41 4c 54 45 52 5f 54 41   SQLITE_ALTER_TA
1f230 42 4c 45 20 20 20 20 20 20 20 20 20 20 32 36 20  BLE          26 
1f240 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61    /* Database Na
1f250 6d 65 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20  me   Table Name 
1f260 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1f270 53 51 4c 49 54 45 5f 52 45 49 4e 44 45 58 20 20  SQLITE_REINDEX  
1f280 20 20 20 20 20 20 20 20 20 20 20 20 32 37 20 20              27  
1f290 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20   /* Index Name  
1f2a0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
1f2b0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1f2c0 51 4c 49 54 45 5f 41 4e 41 4c 59 5a 45 20 20 20  QLITE_ANALYZE   
1f2d0 20 20 20 20 20 20 20 20 20 20 20 32 38 20 20 20             28   
1f2e0 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
1f2f0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1f300 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1f310 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 54 41 42  LITE_CREATE_VTAB
1f320 4c 45 20 20 20 20 20 20 20 20 32 39 20 20 20 2f  LE        29   /
1f330 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
1f340 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20    Module Name   
1f350 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1f360 49 54 45 5f 44 52 4f 50 5f 56 54 41 42 4c 45 20  ITE_DROP_VTABLE 
1f370 20 20 20 20 20 20 20 20 20 33 30 20 20 20 2f 2a           30   /*
1f380 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1f390 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20   Module Name    
1f3a0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1f3b0 54 45 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20 20  TE_FUNCTION     
1f3c0 20 20 20 20 20 20 20 20 33 31 20 20 20 2f 2a 20          31   /* 
1f3d0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1f3e0 46 75 6e 63 74 69 6f 6e 20 4e 61 6d 65 20 20 20  Function Name   
1f3f0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1f400 45 5f 53 41 56 45 50 4f 49 4e 54 20 20 20 20 20  E_SAVEPOINT     
1f410 20 20 20 20 20 20 20 33 32 20 20 20 2f 2a 20 4f         32   /* O
1f420 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20 53  peration       S
1f430 61 76 65 70 6f 69 6e 74 20 4e 61 6d 65 20 20 2a  avepoint Name  *
1f440 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1f450 5f 43 4f 50 59 20 20 20 20 20 20 20 20 20 20 20  _COPY           
1f460 20 20 20 20 20 20 20 30 20 20 20 2f 2a 20 4e 6f         0   /* No
1f470 20 6c 6f 6e 67 65 72 20 75 73 65 64 20 2a 2f 0a   longer used */.
1f480 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1f490 20 54 72 61 63 69 6e 67 20 41 6e 64 20 50 72 6f   Tracing And Pro
1f4a0 66 69 6c 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73  filing Functions
1f4b0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
1f4c0 74 69 6e 65 73 20 72 65 67 69 73 74 65 72 20 63  tines register c
1f4d0 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
1f4e0 73 20 74 68 61 74 20 63 61 6e 20 62 65 20 75 73  s that can be us
1f4f0 65 64 20 66 6f 72 0a 2a 2a 20 74 72 61 63 69 6e  ed for.** tracin
1f500 67 20 61 6e 64 20 70 72 6f 66 69 6c 69 6e 67 20  g and profiling 
1f510 74 68 65 20 65 78 65 63 75 74 69 6f 6e 20 6f 66  the execution of
1f520 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e   SQL statements.
1f530 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c  .**.** ^The call
1f540 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65  back function re
1f550 67 69 73 74 65 72 65 64 20 62 79 20 73 71 6c 69  gistered by sqli
1f560 74 65 33 5f 74 72 61 63 65 28 29 20 69 73 20 69  te3_trace() is i
1f570 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a 20 76 61 72  nvoked at.** var
1f580 69 6f 75 73 20 74 69 6d 65 73 20 77 68 65 6e 20  ious times when 
1f590 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  an SQL statement
1f5a0 20 69 73 20 62 65 69 6e 67 20 72 75 6e 20 62 79   is being run by
1f5b0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
1f5c0 5d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  ]..** ^The sqlit
1f5d0 65 33 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62  e3_trace() callb
1f5e0 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77  ack is invoked w
1f5f0 69 74 68 20 61 20 55 54 46 2d 38 20 72 65 6e 64  ith a UTF-8 rend
1f600 65 72 69 6e 67 20 6f 66 20 74 68 65 0a 2a 2a 20  ering of the.** 
1f610 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65  SQL statement te
1f620 78 74 20 61 73 20 74 68 65 20 73 74 61 74 65 6d  xt as the statem
1f630 65 6e 74 20 66 69 72 73 74 20 62 65 67 69 6e 73  ent first begins
1f640 20 65 78 65 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e   executing..** ^
1f650 28 41 64 64 69 74 69 6f 6e 61 6c 20 73 71 6c 69  (Additional sqli
1f660 74 65 33 5f 74 72 61 63 65 28 29 20 63 61 6c 6c  te3_trace() call
1f670 62 61 63 6b 73 20 6d 69 67 68 74 20 6f 63 63 75  backs might occu
1f680 72 0a 2a 2a 20 61 73 20 65 61 63 68 20 74 72 69  r.** as each tri
1f690 67 67 65 72 65 64 20 73 75 62 70 72 6f 67 72 61  ggered subprogra
1f6a0 6d 20 69 73 20 65 6e 74 65 72 65 64 2e 20 20 54  m is entered.  T
1f6b0 68 65 20 63 61 6c 6c 62 61 63 6b 73 20 66 6f 72  he callbacks for
1f6c0 20 74 72 69 67 67 65 72 73 0a 2a 2a 20 63 6f 6e   triggers.** con
1f6d0 74 61 69 6e 20 61 20 55 54 46 2d 38 20 53 51 4c  tain a UTF-8 SQL
1f6e0 20 63 6f 6d 6d 65 6e 74 20 74 68 61 74 20 69 64   comment that id
1f6f0 65 6e 74 69 66 69 65 73 20 74 68 65 20 74 72 69  entifies the tri
1f700 67 67 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  gger.)^.**.** Th
1f710 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5f  e [SQLITE_TRACE_
1f720 53 49 5a 45 5f 4c 49 4d 49 54 5d 20 63 6f 6d 70  SIZE_LIMIT] comp
1f730 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
1f740 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6c  can be used to l
1f750 69 6d 69 74 0a 2a 2a 20 74 68 65 20 6c 65 6e 67  imit.** the leng
1f760 74 68 20 6f 66 20 5b 62 6f 75 6e 64 20 70 61 72  th of [bound par
1f770 61 6d 65 74 65 72 5d 20 65 78 70 61 6e 73 69 6f  ameter] expansio
1f780 6e 20 69 6e 20 74 68 65 20 6f 75 74 70 75 74 20  n in the output 
1f790 6f 66 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65  of sqlite3_trace
1f7a0 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63  ()..**.** ^The c
1f7b0 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
1f7c0 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20 73   registered by s
1f7d0 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29  qlite3_profile()
1f7e0 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61   is invoked.** a
1f7f0 73 20 65 61 63 68 20 53 51 4c 20 73 74 61 74 65  s each SQL state
1f800 6d 65 6e 74 20 66 69 6e 69 73 68 65 73 2e 20 20  ment finishes.  
1f810 5e 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c  ^The profile cal
1f820 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a  lback contains.*
1f830 2a 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73  * the original s
1f840 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61 6e  tatement text an
1f850 64 20 61 6e 20 65 73 74 69 6d 61 74 65 20 6f 66  d an estimate of
1f860 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65   wall-clock time
1f870 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e 67 20  .** of how long 
1f880 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20 74  that statement t
1f890 6f 6f 6b 20 74 6f 20 72 75 6e 2e 20 20 5e 54 68  ook to run.  ^Th
1f8a0 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61  e profile callba
1f8b0 63 6b 0a 2a 2a 20 74 69 6d 65 20 69 73 20 69 6e  ck.** time is in
1f8c0 20 75 6e 69 74 73 20 6f 66 20 6e 61 6e 6f 73 65   units of nanose
1f8d0 63 6f 6e 64 73 2c 20 68 6f 77 65 76 65 72 20 74  conds, however t
1f8e0 68 65 20 63 75 72 72 65 6e 74 20 69 6d 70 6c 65  he current imple
1f8f0 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69 73 20  mentation.** is 
1f900 6f 6e 6c 79 20 63 61 70 61 62 6c 65 20 6f 66 20  only capable of 
1f910 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 72 65 73 6f  millisecond reso
1f920 6c 75 74 69 6f 6e 20 73 6f 20 74 68 65 20 73 69  lution so the si
1f930 78 20 6c 65 61 73 74 20 73 69 67 6e 69 66 69 63  x least signific
1f940 61 6e 74 0a 2a 2a 20 64 69 67 69 74 73 20 69 6e  ant.** digits in
1f950 20 74 68 65 20 74 69 6d 65 20 61 72 65 20 6d 65   the time are me
1f960 61 6e 69 6e 67 6c 65 73 73 2e 20 20 46 75 74 75  aningless.  Futu
1f970 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  re versions of S
1f980 51 4c 69 74 65 0a 2a 2a 20 6d 69 67 68 74 20 70  QLite.** might p
1f990 72 6f 76 69 64 65 20 67 72 65 61 74 65 72 20 72  rovide greater r
1f9a0 65 73 6f 6c 75 74 69 6f 6e 20 6f 6e 20 74 68 65  esolution on the
1f9b0 20 70 72 6f 66 69 6c 65 72 20 63 61 6c 6c 62 61   profiler callba
1f9c0 63 6b 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69  ck.  The.** sqli
1f9d0 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 66 75  te3_profile() fu
1f9e0 6e 63 74 69 6f 6e 20 69 73 20 63 6f 6e 73 69 64  nction is consid
1f9f0 65 72 65 64 20 65 78 70 65 72 69 6d 65 6e 74 61  ered experimenta
1fa00 6c 20 61 6e 64 20 69 73 0a 2a 2a 20 73 75 62 6a  l and is.** subj
1fa10 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 69 6e  ect to change in
1fa20 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   future versions
1fa30 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 76   of SQLite..*/.v
1fa40 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 74 72 61  oid *sqlite3_tra
1fa50 63 65 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69  ce(sqlite3*, voi
1fa60 64 28 2a 78 54 72 61 63 65 29 28 76 6f 69 64 2a  d(*xTrace)(void*
1fa70 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20 76  ,const char*), v
1fa80 6f 69 64 2a 29 3b 0a 53 51 4c 49 54 45 5f 45 58  oid*);.SQLITE_EX
1fa90 50 45 52 49 4d 45 4e 54 41 4c 20 76 6f 69 64 20  PERIMENTAL void 
1faa0 2a 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65  *sqlite3_profile
1fab0 28 73 71 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f  (sqlite3*,.   vo
1fac0 69 64 28 2a 78 50 72 6f 66 69 6c 65 29 28 76 6f  id(*xProfile)(vo
1fad0 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  id*,const char*,
1fae0 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 2c  sqlite3_uint64),
1faf0 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20   void*);../*.** 
1fb00 43 41 50 49 33 52 45 46 3a 20 51 75 65 72 79 20  CAPI3REF: Query 
1fb10 50 72 6f 67 72 65 73 73 20 43 61 6c 6c 62 61 63  Progress Callbac
1fb20 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ks.**.** ^The sq
1fb30 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68  lite3_progress_h
1fb40 61 6e 64 6c 65 72 28 44 2c 4e 2c 58 2c 50 29 20  andler(D,N,X,P) 
1fb50 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73  interface causes
1fb60 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a   the callback.**
1fb70 20 66 75 6e 63 74 69 6f 6e 20 58 20 74 6f 20 62   function X to b
1fb80 65 20 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64  e invoked period
1fb90 69 63 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f  ically during lo
1fba0 6e 67 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73  ng running calls
1fbb0 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
1fbc0 65 78 65 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65  exec()], [sqlite
1fbd0 33 5f 73 74 65 70 28 29 5d 20 61 6e 64 20 5b 73  3_step()] and [s
1fbe0 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
1fbf0 28 29 5d 20 66 6f 72 0a 2a 2a 20 64 61 74 61 62  ()] for.** datab
1fc00 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44  ase connection D
1fc10 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 75 73  .  An example us
1fc20 65 20 66 6f 72 20 74 68 69 73 0a 2a 2a 20 69 6e  e for this.** in
1fc30 74 65 72 66 61 63 65 20 69 73 20 74 6f 20 6b 65  terface is to ke
1fc40 65 70 20 61 20 47 55 49 20 75 70 64 61 74 65 64  ep a GUI updated
1fc50 20 64 75 72 69 6e 67 20 61 20 6c 61 72 67 65 20   during a large 
1fc60 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  query..**.** ^Th
1fc70 65 20 70 61 72 61 6d 65 74 65 72 20 50 20 69 73  e parameter P is
1fc80 20 70 61 73 73 65 64 20 74 68 72 6f 75 67 68 20   passed through 
1fc90 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61  as the only para
1fca0 6d 65 74 65 72 20 74 6f 20 74 68 65 20 0a 2a 2a  meter to the .**
1fcb0 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
1fcc0 6f 6e 20 58 2e 20 20 5e 54 68 65 20 70 61 72 61  on X.  ^The para
1fcd0 6d 65 74 65 72 20 4e 20 69 73 20 74 68 65 20 61  meter N is the a
1fce0 70 70 72 6f 78 69 6d 61 74 65 20 6e 75 6d 62 65  pproximate numbe
1fcf0 72 20 6f 66 20 0a 2a 2a 20 5b 76 69 72 74 75 61  r of .** [virtua
1fd00 6c 20 6d 61 63 68 69 6e 65 20 69 6e 73 74 72 75  l machine instru
1fd10 63 74 69 6f 6e 73 5d 20 74 68 61 74 20 61 72 65  ctions] that are
1fd20 20 65 76 61 6c 75 61 74 65 64 20 62 65 74 77 65   evaluated betwe
1fd30 65 6e 20 73 75 63 63 65 73 73 69 76 65 0a 2a 2a  en successive.**
1fd40 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20   invocations of 
1fd50 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 58 2e 20  the callback X. 
1fd60 20 5e 49 66 20 4e 20 69 73 20 6c 65 73 73 20 74   ^If N is less t
1fd70 68 61 6e 20 6f 6e 65 20 74 68 65 6e 20 74 68 65  han one then the
1fd80 20 70 72 6f 67 72 65 73 73 0a 2a 2a 20 68 61 6e   progress.** han
1fd90 64 6c 65 72 20 69 73 20 64 69 73 61 62 6c 65 64  dler is disabled
1fda0 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 61 20  ..**.** ^Only a 
1fdb0 73 69 6e 67 6c 65 20 70 72 6f 67 72 65 73 73 20  single progress 
1fdc0 68 61 6e 64 6c 65 72 20 6d 61 79 20 62 65 20 64  handler may be d
1fdd0 65 66 69 6e 65 64 20 61 74 20 6f 6e 65 20 74 69  efined at one ti
1fde0 6d 65 20 70 65 72 0a 2a 2a 20 5b 64 61 74 61 62  me per.** [datab
1fdf0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 3b  ase connection];
1fe00 20 73 65 74 74 69 6e 67 20 61 20 6e 65 77 20 70   setting a new p
1fe10 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20  rogress handler 
1fe20 63 61 6e 63 65 6c 73 20 74 68 65 0a 2a 2a 20 6f  cancels the.** o
1fe30 6c 64 20 6f 6e 65 2e 20 20 5e 53 65 74 74 69 6e  ld one.  ^Settin
1fe40 67 20 70 61 72 61 6d 65 74 65 72 20 58 20 74 6f  g parameter X to
1fe50 20 4e 55 4c 4c 20 64 69 73 61 62 6c 65 73 20 74   NULL disables t
1fe60 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64  he progress hand
1fe70 6c 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 70 72 6f  ler..** ^The pro
1fe80 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 69 73  gress handler is
1fe90 20 61 6c 73 6f 20 64 69 73 61 62 6c 65 64 20 62   also disabled b
1fea0 79 20 73 65 74 74 69 6e 67 20 4e 20 74 6f 20 61  y setting N to a
1feb0 20 76 61 6c 75 65 20 6c 65 73 73 0a 2a 2a 20 74   value less.** t
1fec0 68 61 6e 20 31 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  han 1..**.** ^If
1fed0 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 63 61   the progress ca
1fee0 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e  llback returns n
1fef0 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 6f 70 65  on-zero, the ope
1ff00 72 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74  ration is.** int
1ff10 65 72 72 75 70 74 65 64 2e 20 20 54 68 69 73 20  errupted.  This 
1ff20 66 65 61 74 75 72 65 20 63 61 6e 20 62 65 20 75  feature can be u
1ff30 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74  sed to implement
1ff40 20 61 0a 2a 2a 20 22 43 61 6e 63 65 6c 22 20 62   a.** "Cancel" b
1ff50 75 74 74 6f 6e 20 6f 6e 20 61 20 47 55 49 20 70  utton on a GUI p
1ff60 72 6f 67 72 65 73 73 20 64 69 61 6c 6f 67 20 62  rogress dialog b
1ff70 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72  ox..**.** The pr
1ff80 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63  ogress handler c
1ff90 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74  allback must not
1ffa0 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61   do anything tha
1ffb0 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a  t will modify.**
1ffc0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
1ffd0 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e  nnection that in
1ffe0 76 6f 6b 65 64 20 74 68 65 20 70 72 6f 67 72 65  voked the progre
1fff0 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 4e  ss handler..** N
20000 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65  ote that [sqlite
20010 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
20020 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  and [sqlite3_ste
20030 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79  p()] both modify
20040 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61   their.** databa
20050 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66  se connections f
20060 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f  or the meaning o
20070 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68  f "modify" in th
20080 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a  is paragraph..**
20090 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  .*/.void sqlite3
200a0 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65  _progress_handle
200b0 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 2c  r(sqlite3*, int,
200c0 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20   int(*)(void*), 
200d0 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  void*);../*.** C
200e0 41 50 49 33 52 45 46 3a 20 4f 70 65 6e 69 6e 67  API3REF: Opening
200f0 20 41 20 4e 65 77 20 44 61 74 61 62 61 73 65 20   A New Database 
20100 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a  Connection.**.**
20110 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73   ^These routines
20120 20 6f 70 65 6e 20 61 6e 20 53 51 4c 69 74 65 20   open an SQLite 
20130 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 61 73  database file as
20140 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68   specified by th
20150 65 20 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 61  e .** filename a
20160 72 67 75 6d 65 6e 74 2e 20 5e 54 68 65 20 66 69  rgument. ^The fi
20170 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20  lename argument 
20180 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  is interpreted a
20190 73 20 55 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 73  s UTF-8 for.** s
201a0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e  qlite3_open() an
201b0 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  d sqlite3_open_v
201c0 32 28 29 20 61 6e 64 20 61 73 20 55 54 46 2d 31  2() and as UTF-1
201d0 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20  6 in the native 
201e0 62 79 74 65 0a 2a 2a 20 6f 72 64 65 72 20 66 6f  byte.** order fo
201f0 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36  r sqlite3_open16
20200 28 29 2e 20 5e 28 41 20 5b 64 61 74 61 62 61 73  (). ^(A [databas
20210 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61  e connection] ha
20220 6e 64 6c 65 20 69 73 20 75 73 75 61 6c 6c 79 0a  ndle is usually.
20230 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 6e 20 2a  ** returned in *
20240 70 70 44 62 2c 20 65 76 65 6e 20 69 66 20 61 6e  ppDb, even if an
20250 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 20 20   error occurs.  
20260 54 68 65 20 6f 6e 6c 79 20 65 78 63 65 70 74 69  The only excepti
20270 6f 6e 20 69 73 20 74 68 61 74 0a 2a 2a 20 69 66  on is that.** if
20280 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c   SQLite is unabl
20290 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65  e to allocate me
202a0 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65  mory to hold the
202b0 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63   [sqlite3] objec
202c0 74 2c 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77 69 6c  t,.** a NULL wil
202d0 6c 20 62 65 20 77 72 69 74 74 65 6e 20 69 6e 74  l be written int
202e0 6f 20 2a 70 70 44 62 20 69 6e 73 74 65 61 64 20  o *ppDb instead 
202f0 6f 66 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  of a pointer to 
20300 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a  the [sqlite3].**
20310 20 6f 62 6a 65 63 74 2e 29 5e 20 5e 28 49 66 20   object.)^ ^(If 
20320 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  the database is 
20330 6f 70 65 6e 65 64 20 28 61 6e 64 2f 6f 72 20 63  opened (and/or c
20340 72 65 61 74 65 64 29 20 73 75 63 63 65 73 73 66  reated) successf
20350 75 6c 6c 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53  ully, then.** [S
20360 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74  QLITE_OK] is ret
20370 75 72 6e 65 64 2e 20 20 4f 74 68 65 72 77 69 73  urned.  Otherwis
20380 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65  e an [error code
20390 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e  ] is returned.)^
203a0 20 5e 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65   ^The.** [sqlite
203b0 33 5f 65 72 72 6d 73 67 28 29 5d 20 6f 72 20 5b  3_errmsg()] or [
203c0 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36  sqlite3_errmsg16
203d0 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 63 61 6e  ()] routines can
203e0 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61   be used to obta
203f0 69 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69 73 68  in.** an English
20400 20 6c 61 6e 67 75 61 67 65 20 64 65 73 63 72 69   language descri
20410 70 74 69 6f 6e 20 6f 66 20 74 68 65 20 65 72 72  ption of the err
20420 6f 72 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66  or following a f
20430 61 69 6c 75 72 65 20 6f 66 20 61 6e 79 0a 2a 2a  ailure of any.**
20440 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f   of the sqlite3_
20450 6f 70 65 6e 28 29 20 72 6f 75 74 69 6e 65 73 2e  open() routines.
20460 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61  .**.** ^The defa
20470 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72  ult encoding for
20480 20 74 68 65 20 64 61 74 61 62 61 73 65 20 77 69   the database wi
20490 6c 6c 20 62 65 20 55 54 46 2d 38 20 69 66 0a 2a  ll be UTF-8 if.*
204a0 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  * sqlite3_open()
204b0 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   or sqlite3_open
204c0 5f 76 32 28 29 20 69 73 20 63 61 6c 6c 65 64 20  _v2() is called 
204d0 61 6e 64 0a 2a 2a 20 55 54 46 2d 31 36 20 69 6e  and.** UTF-16 in
204e0 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65   the native byte
204f0 20 6f 72 64 65 72 20 69 66 20 73 71 6c 69 74 65   order if sqlite
20500 33 5f 6f 70 65 6e 31 36 28 29 20 69 73 20 75 73  3_open16() is us
20510 65 64 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68 65  ed..**.** Whethe
20520 72 20 6f 72 20 6e 6f 74 20 61 6e 20 65 72 72 6f  r or not an erro
20530 72 20 6f 63 63 75 72 73 20 77 68 65 6e 20 69 74  r occurs when it
20540 20 69 73 20 6f 70 65 6e 65 64 2c 20 72 65 73 6f   is opened, reso
20550 75 72 63 65 73 0a 2a 2a 20 61 73 73 6f 63 69 61  urces.** associa
20560 74 65 64 20 77 69 74 68 20 74 68 65 20 5b 64 61  ted with the [da
20570 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
20580 6e 5d 20 68 61 6e 64 6c 65 20 73 68 6f 75 6c 64  n] handle should
20590 20 62 65 20 72 65 6c 65 61 73 65 64 20 62 79 0a   be released by.
205a0 2a 2a 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f  ** passing it to
205b0 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28   [sqlite3_close(
205c0 29 5d 20 77 68 65 6e 20 69 74 20 69 73 20 6e 6f  )] when it is no
205d0 20 6c 6f 6e 67 65 72 20 72 65 71 75 69 72 65 64   longer required
205e0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
205f0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 6e  te3_open_v2() in
20600 74 65 72 66 61 63 65 20 77 6f 72 6b 73 20 6c 69  terface works li
20610 6b 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  ke sqlite3_open(
20620 29 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74  ).** except that
20630 20 69 74 20 61 63 63 65 70 74 73 20 74 77 6f 20   it accepts two 
20640 61 64 64 69 74 69 6f 6e 61 6c 20 70 61 72 61 6d  additional param
20650 65 74 65 72 73 20 66 6f 72 20 61 64 64 69 74 69  eters for additi
20660 6f 6e 61 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20  onal control.** 
20670 6f 76 65 72 20 74 68 65 20 6e 65 77 20 64 61 74  over the new dat
20680 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
20690 2e 20 20 5e 28 54 68 65 20 66 6c 61 67 73 20 70  .  ^(The flags p
206a0 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 73  arameter to.** s
206b0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
206c0 20 63 61 6e 20 74 61 6b 65 20 6f 6e 65 20 6f 66   can take one of
206d0 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e  .** the followin
206e0 67 20 74 68 72 65 65 20 76 61 6c 75 65 73 2c 20  g three values, 
206f0 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69  optionally combi
20700 6e 65 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a  ned with the .**
20710 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f   [SQLITE_OPEN_NO
20720 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f  MUTEX], [SQLITE_
20730 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 2c  OPEN_FULLMUTEX],
20740 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48   [SQLITE_OPEN_SH
20750 41 52 45 44 43 41 43 48 45 5d 2c 0a 2a 2a 20 5b  AREDCACHE],.** [
20760 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56  SQLITE_OPEN_PRIV
20770 41 54 45 43 41 43 48 45 5d 2c 20 61 6e 64 2f 6f  ATECACHE], and/o
20780 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55  r [SQLITE_OPEN_U
20790 52 49 5d 20 66 6c 61 67 73 3a 29 5e 0a 2a 2a 0a  RI] flags:)^.**.
207a0 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c 64 74  ** <dl>.** ^(<dt
207b0 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45  >[SQLITE_OPEN_RE
207c0 41 44 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a 20  ADONLY]</dt>.** 
207d0 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65  <dd>The database
207e0 20 69 73 20 6f 70 65 6e 65 64 20 69 6e 20 72 65   is opened in re
207f0 61 64 2d 6f 6e 6c 79 20 6d 6f 64 65 2e 20 20 49  ad-only mode.  I
20800 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 64  f the database d
20810 6f 65 73 20 6e 6f 74 0a 2a 2a 20 61 6c 72 65 61  oes not.** alrea
20820 64 79 20 65 78 69 73 74 2c 20 61 6e 20 65 72 72  dy exist, an err
20830 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c  or is returned.<
20840 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c  /dd>)^.**.** ^(<
20850 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  dt>[SQLITE_OPEN_
20860 52 45 41 44 57 52 49 54 45 5d 3c 2f 64 74 3e 0a  READWRITE]</dt>.
20870 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62  ** <dd>The datab
20880 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f  ase is opened fo
20890 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72  r reading and wr
208a0 69 74 69 6e 67 20 69 66 20 70 6f 73 73 69 62 6c  iting if possibl
208b0 65 2c 20 6f 72 20 72 65 61 64 69 6e 67 0a 2a 2a  e, or reading.**
208c0 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 66 69 6c   only if the fil
208d0 65 20 69 73 20 77 72 69 74 65 20 70 72 6f 74 65  e is write prote
208e0 63 74 65 64 20 62 79 20 74 68 65 20 6f 70 65 72  cted by the oper
208f0 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 49  ating system.  I
20900 6e 20 65 69 74 68 65 72 0a 2a 2a 20 63 61 73 65  n either.** case
20910 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6d 75   the database mu
20920 73 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74  st already exist
20930 2c 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20 65  , otherwise an e
20940 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64  rror is returned
20950 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  .</dd>)^.**.** ^
20960 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45  (<dt>[SQLITE_OPE
20970 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b  N_READWRITE] | [
20980 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
20990 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TE]</dt>.** <dd>
209a0 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  The database is 
209b0 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69  opened for readi
209c0 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 2c 20  ng and writing, 
209d0 61 6e 64 20 69 73 20 63 72 65 61 74 65 64 20 69  and is created i
209e0 66 0a 2a 2a 20 69 74 20 64 6f 65 73 20 6e 6f 74  f.** it does not
209f0 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2e 20   already exist. 
20a00 54 68 69 73 20 69 73 20 74 68 65 20 62 65 68 61  This is the beha
20a10 76 69 6f 72 20 74 68 61 74 20 69 73 20 61 6c 77  vior that is alw
20a20 61 79 73 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20  ays used for.** 
20a30 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61  sqlite3_open() a
20a40 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  nd sqlite3_open1
20a50 36 28 29 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c  6().</dd>)^.** <
20a60 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  /dl>.**.** If th
20a70 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  e 3rd parameter 
20a80 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  to sqlite3_open_
20a90 76 32 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20  v2() is not one 
20aa0 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e  of the.** combin
20ab0 61 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f  ations shown abo
20ac0 76 65 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f  ve optionally co
20ad0 6d 62 69 6e 65 64 20 77 69 74 68 20 6f 74 68 65  mbined with othe
20ae0 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45  r.** [SQLITE_OPE
20af0 4e 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 53 51 4c  N_READONLY | SQL
20b00 49 54 45 5f 4f 50 45 4e 5f 2a 20 62 69 74 73 5d  ITE_OPEN_* bits]
20b10 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 62 65 68  .** then the beh
20b20 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e  avior is undefin
20b30 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  ed..**.** ^If th
20b40 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e  e [SQLITE_OPEN_N
20b50 4f 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20  OMUTEX] flag is 
20b60 73 65 74 2c 20 74 68 65 6e 20 74 68 65 20 64 61  set, then the da
20b70 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
20b80 6e 0a 2a 2a 20 6f 70 65 6e 73 20 69 6e 20 74 68  n.** opens in th
20b90 65 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b  e multi-thread [
20ba0 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
20bb0 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 73  as long as the s
20bc0 69 6e 67 6c 65 2d 74 68 72 65 61 64 0a 2a 2a 20  ingle-thread.** 
20bd0 6d 6f 64 65 20 68 61 73 20 6e 6f 74 20 62 65 65  mode has not bee
20be0 6e 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65  n set at compile
20bf0 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74  -time or start-t
20c00 69 6d 65 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a  ime.  ^If the.**
20c10 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55   [SQLITE_OPEN_FU
20c20 4c 4c 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73  LLMUTEX] flag is
20c30 20 73 65 74 20 74 68 65 6e 20 74 68 65 20 64 61   set then the da
20c40 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
20c50 6e 20 6f 70 65 6e 73 0a 2a 2a 20 69 6e 20 74 68  n opens.** in th
20c60 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68  e serialized [th
20c70 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 75 6e  reading mode] un
20c80 6c 65 73 73 20 73 69 6e 67 6c 65 2d 74 68 72 65  less single-thre
20c90 61 64 20 77 61 73 0a 2a 2a 20 70 72 65 76 69 6f  ad was.** previo
20ca0 75 73 6c 79 20 73 65 6c 65 63 74 65 64 20 61 74  usly selected at
20cb0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72   compile-time or
20cc0 20 73 74 61 72 74 2d 74 69 6d 65 2e 0a 2a 2a 20   start-time..** 
20cd0 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45  ^The [SQLITE_OPE
20ce0 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d 20 66  N_SHAREDCACHE] f
20cf0 6c 61 67 20 63 61 75 73 65 73 20 74 68 65 20 64  lag causes the d
20d00 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
20d10 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 65 6c 69 67  on to be.** elig
20d20 69 62 6c 65 20 74 6f 20 75 73 65 20 5b 73 68 61  ible to use [sha
20d30 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 2c  red cache mode],
20d40 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77   regardless of w
20d50 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 73 68  hether or not sh
20d60 61 72 65 64 0a 2a 2a 20 63 61 63 68 65 20 69 73  ared.** cache is
20d70 20 65 6e 61 62 6c 65 64 20 75 73 69 6e 67 20 5b   enabled using [
20d80 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73  sqlite3_enable_s
20d90 68 61 72 65 64 5f 63 61 63 68 65 28 29 5d 2e 20  hared_cache()]. 
20da0 20 5e 54 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45   ^The.** [SQLITE
20db0 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43  _OPEN_PRIVATECAC
20dc0 48 45 5d 20 66 6c 61 67 20 63 61 75 73 65 73 20  HE] flag causes 
20dd0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
20de0 6e 65 63 74 69 6f 6e 20 74 6f 20 6e 6f 74 0a 2a  nection to not.*
20df0 2a 20 70 61 72 74 69 63 69 70 61 74 65 20 69 6e  * participate in
20e00 20 5b 73 68 61 72 65 64 20 63 61 63 68 65 20 6d   [shared cache m
20e10 6f 64 65 5d 20 65 76 65 6e 20 69 66 20 69 74 20  ode] even if it 
20e20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a  is enabled..**.*
20e30 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61  * ^The fourth pa
20e40 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
20e50 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20  e3_open_v2() is 
20e60 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a  the name of the.
20e70 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  ** [sqlite3_vfs]
20e80 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65 66   object that def
20e90 69 6e 65 73 20 74 68 65 20 6f 70 65 72 61 74 69  ines the operati
20ea0 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66  ng system interf
20eb0 61 63 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  ace that.** the 
20ec0 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e  new database con
20ed0 6e 65 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75  nection should u
20ee0 73 65 2e 20 20 5e 49 66 20 74 68 65 20 66 6f 75  se.  ^If the fou
20ef0 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  rth parameter is
20f00 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  .** a NULL point
20f10 65 72 20 74 68 65 6e 20 74 68 65 20 64 65 66 61  er then the defa
20f20 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  ult [sqlite3_vfs
20f30 5d 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64  ] object is used
20f40 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
20f50 66 69 6c 65 6e 61 6d 65 20 69 73 20 22 3a 6d 65  filename is ":me
20f60 6d 6f 72 79 3a 22 2c 20 74 68 65 6e 20 61 20 70  mory:", then a p
20f70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72  rivate, temporar
20f80 79 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61  y in-memory data
20f90 62 61 73 65 0a 2a 2a 20 69 73 20 63 72 65 61 74  base.** is creat
20fa0 65 64 20 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65  ed for the conne
20fb0 63 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 69 6e  ction.  ^This in
20fc0 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65  -memory database
20fd0 20 77 69 6c 6c 20 76 61 6e 69 73 68 20 77 68 65   will vanish whe
20fe0 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73  n.** the databas
20ff0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
21000 63 6c 6f 73 65 64 2e 20 20 46 75 74 75 72 65 20  closed.  Future 
21010 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
21020 74 65 20 6d 69 67 68 74 0a 2a 2a 20 6d 61 6b 65  te might.** make
21030 20 75 73 65 20 6f 66 20 61 64 64 69 74 69 6f 6e   use of addition
21040 61 6c 20 73 70 65 63 69 61 6c 20 66 69 6c 65 6e  al special filen
21050 61 6d 65 73 20 74 68 61 74 20 62 65 67 69 6e 20  ames that begin 
21060 77 69 74 68 20 74 68 65 20 22 3a 22 20 63 68 61  with the ":" cha
21070 72 61 63 74 65 72 2e 0a 2a 2a 20 49 74 20 69 73  racter..** It is
21080 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61   recommended tha
21090 74 20 77 68 65 6e 20 61 20 64 61 74 61 62 61 73  t when a databas
210a0 65 20 66 69 6c 65 6e 61 6d 65 20 61 63 74 75 61  e filename actua
210b0 6c 6c 79 20 64 6f 65 73 20 62 65 67 69 6e 20 77  lly does begin w
210c0 69 74 68 0a 2a 2a 20 61 20 22 3a 22 20 63 68 61  ith.** a ":" cha
210d0 72 61 63 74 65 72 20 79 6f 75 20 73 68 6f 75 6c  racter you shoul
210e0 64 20 70 72 65 66 69 78 20 74 68 65 20 66 69 6c  d prefix the fil
210f0 65 6e 61 6d 65 20 77 69 74 68 20 61 20 70 61 74  ename with a pat
21100 68 6e 61 6d 65 20 73 75 63 68 20 61 73 0a 2a 2a  hname such as.**
21110 20 22 2e 2f 22 20 74 6f 20 61 76 6f 69 64 20 61   "./" to avoid a
21120 6d 62 69 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20  mbiguity..**.** 
21130 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  ^If the filename
21140 20 69 73 20 61 6e 20 65 6d 70 74 79 20 73 74 72   is an empty str
21150 69 6e 67 2c 20 74 68 65 6e 20 61 20 70 72 69 76  ing, then a priv
21160 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 0a 2a  ate, temporary.*
21170 2a 20 6f 6e 2d 64 69 73 6b 20 64 61 74 61 62 61  * on-disk databa
21180 73 65 20 77 69 6c 6c 20 62 65 20 63 72 65 61 74  se will be creat
21190 65 64 2e 20 20 5e 54 68 69 73 20 70 72 69 76 61  ed.  ^This priva
211a0 74 65 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c  te database will
211b0 20 62 65 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63   be.** automatic
211c0 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 61 73 20  ally deleted as 
211d0 73 6f 6f 6e 20 61 73 20 74 68 65 20 64 61 74 61  soon as the data
211e0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
211f0 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a  is closed..**.**
21200 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 73   [[URI filenames
21210 20 69 6e 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   in sqlite3_open
21220 28 29 5d 5d 20 3c 68 33 3e 55 52 49 20 46 69 6c  ()]] <h3>URI Fil
21230 65 6e 61 6d 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a  enames</h3>.**.*
21240 2a 20 5e 49 66 20 5b 55 52 49 20 66 69 6c 65 6e  * ^If [URI filen
21250 61 6d 65 5d 20 69 6e 74 65 72 70 72 65 74 61 74  ame] interpretat
21260 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2c 20  ion is enabled, 
21270 61 6e 64 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  and the filename
21280 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 62 65 67   argument.** beg
21290 69 6e 73 20 77 69 74 68 20 22 66 69 6c 65 3a 22  ins with "file:"
212a0 2c 20 74 68 65 6e 20 74 68 65 20 66 69 6c 65 6e  , then the filen
212b0 61 6d 65 20 69 73 20 69 6e 74 65 72 70 72 65 74  ame is interpret
212c0 65 64 20 61 73 20 61 20 55 52 49 2e 20 5e 55 52  ed as a URI. ^UR
212d0 49 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 6e  I.** filename in
212e0 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20  terpretation is 
212f0 65 6e 61 62 6c 65 64 20 69 66 20 74 68 65 20 5b  enabled if the [
21300 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d  SQLITE_OPEN_URI]
21310 20 66 6c 61 67 20 69 73 0a 2a 2a 20 73 65 74 20   flag is.** set 
21320 69 6e 20 74 68 65 20 66 6f 75 72 74 68 20 61 72  in the fourth ar
21330 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
21340 33 5f 6f 70 65 6e 5f 76 32 28 29 2c 20 6f 72 20  3_open_v2(), or 
21350 69 66 20 69 74 20 68 61 73 0a 2a 2a 20 62 65 65  if it has.** bee
21360 6e 20 65 6e 61 62 6c 65 64 20 67 6c 6f 62 61 6c  n enabled global
21370 6c 79 20 75 73 69 6e 67 20 74 68 65 20 5b 53 51  ly using the [SQ
21380 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d  LITE_CONFIG_URI]
21390 20 6f 70 74 69 6f 6e 20 77 69 74 68 20 74 68 65   option with the
213a0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
213b0 66 69 67 28 29 5d 20 6d 65 74 68 6f 64 20 6f 72  fig()] method or
213c0 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   by the [SQLITE_
213d0 55 53 45 5f 55 52 49 5d 20 63 6f 6d 70 69 6c 65  USE_URI] compile
213e0 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a  -time option..**
213f0 20 41 73 20 6f 66 20 53 51 4c 69 74 65 20 76 65   As of SQLite ve
21400 72 73 69 6f 6e 20 33 2e 37 2e 37 2c 20 55 52 49  rsion 3.7.7, URI
21410 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70   filename interp
21420 72 65 74 61 74 69 6f 6e 20 69 73 20 74 75 72 6e  retation is turn
21430 65 64 20 6f 66 66 0a 2a 2a 20 62 79 20 64 65 66  ed off.** by def
21440 61 75 6c 74 2c 20 62 75 74 20 66 75 74 75 72 65  ault, but future
21450 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c   releases of SQL
21460 69 74 65 20 6d 69 67 68 74 20 65 6e 61 62 6c 65  ite might enable
21470 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a   URI filename.**
21480 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20   interpretation 
21490 62 79 20 64 65 66 61 75 6c 74 2e 20 20 53 65 65  by default.  See
214a0 20 22 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 73   "[URI filenames
214b0 5d 22 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  ]" for additiona
214c0 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  l.** information
214d0 2e 0a 2a 2a 0a 2a 2a 20 55 52 49 20 66 69 6c 65  ..**.** URI file
214e0 6e 61 6d 65 73 20 61 72 65 20 70 61 72 73 65 64  names are parsed
214f0 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 52 46   according to RF
21500 43 20 33 39 38 36 2e 20 5e 49 66 20 74 68 65 20  C 3986. ^If the 
21510 55 52 49 20 63 6f 6e 74 61 69 6e 73 20 61 6e 0a  URI contains an.
21520 2a 2a 20 61 75 74 68 6f 72 69 74 79 2c 20 74 68  ** authority, th
21530 65 6e 20 69 74 20 6d 75 73 74 20 62 65 20 65 69  en it must be ei
21540 74 68 65 72 20 61 6e 20 65 6d 70 74 79 20 73 74  ther an empty st
21550 72 69 6e 67 20 6f 72 20 74 68 65 20 73 74 72 69  ring or the stri
21560 6e 67 20 0a 2a 2a 20 22 6c 6f 63 61 6c 68 6f 73  ng .** "localhos
21570 74 22 2e 20 5e 49 66 20 74 68 65 20 61 75 74 68  t". ^If the auth
21580 6f 72 69 74 79 20 69 73 20 6e 6f 74 20 61 6e 20  ority is not an 
21590 65 6d 70 74 79 20 73 74 72 69 6e 67 20 6f 72 20  empty string or 
215a0 22 6c 6f 63 61 6c 68 6f 73 74 22 2c 20 61 6e 20  "localhost", an 
215b0 0a 2a 2a 20 65 72 72 6f 72 20 69 73 20 72 65 74  .** error is ret
215c0 75 72 6e 65 64 20 74 6f 20 74 68 65 20 63 61 6c  urned to the cal
215d0 6c 65 72 2e 20 5e 54 68 65 20 66 72 61 67 6d 65  ler. ^The fragme
215e0 6e 74 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20  nt component of 
215f0 61 20 55 52 49 2c 20 69 66 20 0a 2a 2a 20 70 72  a URI, if .** pr
21600 65 73 65 6e 74 2c 20 69 73 20 69 67 6e 6f 72 65  esent, is ignore
21610 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65  d..**.** ^SQLite
21620 20 75 73 65 73 20 74 68 65 20 70 61 74 68 20 63   uses the path c
21630 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 74 68 65 20  omponent of the 
21640 55 52 49 20 61 73 20 74 68 65 20 6e 61 6d 65 20  URI as the name 
21650 6f 66 20 74 68 65 20 64 69 73 6b 20 66 69 6c 65  of the disk file
21660 0a 2a 2a 20 77 68 69 63 68 20 63 6f 6e 74 61 69  .** which contai
21670 6e 73 20 74 68 65 20 64 61 74 61 62 61 73 65 2e  ns the database.
21680 20 5e 49 66 20 74 68 65 20 70 61 74 68 20 62 65   ^If the path be
21690 67 69 6e 73 20 77 69 74 68 20 61 20 27 2f 27 20  gins with a '/' 
216a0 63 68 61 72 61 63 74 65 72 2c 20 0a 2a 2a 20 74  character, .** t
216b0 68 65 6e 20 69 74 20 69 73 20 69 6e 74 65 72 70  hen it is interp
216c0 72 65 74 65 64 20 61 73 20 61 6e 20 61 62 73 6f  reted as an abso
216d0 6c 75 74 65 20 70 61 74 68 2e 20 5e 49 66 20 74  lute path. ^If t
216e0 68 65 20 70 61 74 68 20 64 6f 65 73 20 6e 6f 74  he path does not
216f0 20 62 65 67 69 6e 20 0a 2a 2a 20 77 69 74 68 20   begin .** with 
21700 61 20 27 2f 27 20 28 6d 65 61 6e 69 6e 67 20 74  a '/' (meaning t
21710 68 61 74 20 74 68 65 20 61 75 74 68 6f 72 69 74  hat the authorit
21720 79 20 73 65 63 74 69 6f 6e 20 69 73 20 6f 6d 69  y section is omi
21730 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 55 52  tted from the UR
21740 49 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 70  I).** then the p
21750 61 74 68 20 69 73 20 69 6e 74 65 72 70 72 65 74  ath is interpret
21760 65 64 20 61 73 20 61 20 72 65 6c 61 74 69 76 65  ed as a relative
21770 20 70 61 74 68 2e 20 0a 2a 2a 20 5e 4f 6e 20 77   path. .** ^On w
21780 69 6e 64 6f 77 73 2c 20 74 68 65 20 66 69 72 73  indows, the firs
21790 74 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61  t component of a
217a0 6e 20 61 62 73 6f 6c 75 74 65 20 70 61 74 68 20  n absolute path 
217b0 0a 2a 2a 20 69 73 20 61 20 64 72 69 76 65 20 73  .** is a drive s
217c0 70 65 63 69 66 69 63 61 74 69 6f 6e 20 28 65 2e  pecification (e.
217d0 67 2e 20 22 43 3a 22 29 2e 0a 2a 2a 0a 2a 2a 20  g. "C:")..**.** 
217e0 5b 5b 63 6f 72 65 20 55 52 49 20 71 75 65 72 79  [[core URI query
217f0 20 70 61 72 61 6d 65 74 65 72 73 5d 5d 0a 2a 2a   parameters]].**
21800 20 54 68 65 20 71 75 65 72 79 20 63 6f 6d 70 6f   The query compo
21810 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 20 6d 61  nent of a URI ma
21820 79 20 63 6f 6e 74 61 69 6e 20 70 61 72 61 6d 65  y contain parame
21830 74 65 72 73 20 74 68 61 74 20 61 72 65 20 69 6e  ters that are in
21840 74 65 72 70 72 65 74 65 64 0a 2a 2a 20 65 69 74  terpreted.** eit
21850 68 65 72 20 62 79 20 53 51 4c 69 74 65 20 69 74  her by SQLite it
21860 73 65 6c 66 2c 20 6f 72 20 62 79 20 61 20 5b 56  self, or by a [V
21870 46 53 20 7c 20 63 75 73 74 6f 6d 20 56 46 53 20  FS | custom VFS 
21880 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 5d 2e  implementation].
21890 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72  .** SQLite inter
218a0 70 72 65 74 73 20 74 68 65 20 66 6f 6c 6c 6f 77  prets the follow
218b0 69 6e 67 20 74 68 72 65 65 20 71 75 65 72 79 20  ing three query 
218c0 70 61 72 61 6d 65 74 65 72 73 3a 0a 2a 2a 0a 2a  parameters:.**.*
218d0 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e  * <ul>.**   <li>
218e0 20 3c 62 3e 76 66 73 3c 2f 62 3e 3a 20 5e 54 68   <b>vfs</b>: ^Th
218f0 65 20 22 76 66 73 22 20 70 61 72 61 6d 65 74 65  e "vfs" paramete
21900 72 20 6d 61 79 20 62 65 20 75 73 65 64 20 74 6f  r may be used to
21910 20 73 70 65 63 69 66 79 20 74 68 65 20 6e 61 6d   specify the nam
21920 65 20 6f 66 0a 2a 2a 20 20 20 20 20 61 20 56 46  e of.**     a VF
21930 53 20 6f 62 6a 65 63 74 20 74 68 61 74 20 70 72  S object that pr
21940 6f 76 69 64 65 73 20 74 68 65 20 6f 70 65 72 61  ovides the opera
21950 74 69 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 65  ting system inte
21960 72 66 61 63 65 20 74 68 61 74 20 73 68 6f 75 6c  rface that shoul
21970 64 0a 2a 2a 20 20 20 20 20 62 65 20 75 73 65 64  d.**     be used
21980 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 64   to access the d
21990 61 74 61 62 61 73 65 20 66 69 6c 65 20 6f 6e 20  atabase file on 
219a0 64 69 73 6b 2e 20 5e 49 66 20 74 68 69 73 20 6f  disk. ^If this o
219b0 70 74 69 6f 6e 20 69 73 20 73 65 74 20 74 6f 0a  ption is set to.
219c0 2a 2a 20 20 20 20 20 61 6e 20 65 6d 70 74 79 20  **     an empty 
219d0 73 74 72 69 6e 67 20 74 68 65 20 64 65 66 61 75  string the defau
219e0 6c 74 20 56 46 53 20 6f 62 6a 65 63 74 20 69 73  lt VFS object is
219f0 20 75 73 65 64 2e 20 5e 53 70 65 63 69 66 79 69   used. ^Specifyi
21a00 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 0a 2a 2a  ng an unknown.**
21a10 20 20 20 20 20 56 46 53 20 69 73 20 61 6e 20 65       VFS is an e
21a20 72 72 6f 72 2e 20 5e 49 66 20 73 71 6c 69 74 65  rror. ^If sqlite
21a30 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 75  3_open_v2() is u
21a40 73 65 64 20 61 6e 64 20 74 68 65 20 76 66 73 20  sed and the vfs 
21a50 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20  option is.**    
21a60 20 70 72 65 73 65 6e 74 2c 20 74 68 65 6e 20 74   present, then t
21a70 68 65 20 56 46 53 20 73 70 65 63 69 66 69 65 64  he VFS specified
21a80 20 62 79 20 74 68 65 20 6f 70 74 69 6f 6e 20 74   by the option t
21a90 61 6b 65 73 20 70 72 65 63 65 64 65 6e 63 65 20  akes precedence 
21aa0 6f 76 65 72 0a 2a 2a 20 20 20 20 20 74 68 65 20  over.**     the 
21ab0 76 61 6c 75 65 20 70 61 73 73 65 64 20 61 73 20  value passed as 
21ac0 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
21ad0 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
21ae0 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a  open_v2()..**.**
21af0 20 20 20 3c 6c 69 3e 20 3c 62 3e 6d 6f 64 65 3c     <li> <b>mode<
21b00 2f 62 3e 3a 20 5e 28 54 68 65 20 6d 6f 64 65 20  /b>: ^(The mode 
21b10 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65  parameter may be
21b20 20 73 65 74 20 74 6f 20 65 69 74 68 65 72 20 22   set to either "
21b30 72 6f 22 2c 20 22 72 77 22 2c 0a 2a 2a 20 20 20  ro", "rw",.**   
21b40 20 20 22 72 77 63 22 2c 20 6f 72 20 22 6d 65 6d    "rwc", or "mem
21b50 6f 72 79 22 2e 20 41 74 74 65 6d 70 74 69 6e 67  ory". Attempting
21b60 20 74 6f 20 73 65 74 20 69 74 20 74 6f 20 61 6e   to set it to an
21b70 79 20 6f 74 68 65 72 20 76 61 6c 75 65 20 69 73  y other value is
21b80 0a 2a 2a 20 20 20 20 20 61 6e 20 65 72 72 6f 72  .**     an error
21b90 29 5e 2e 20 0a 2a 2a 20 20 20 20 20 5e 49 66 20  )^. .**     ^If 
21ba0 22 72 6f 22 20 69 73 20 73 70 65 63 69 66 69 65  "ro" is specifie
21bb0 64 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61  d, then the data
21bc0 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66  base is opened f
21bd0 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20 0a 2a 2a  or read-only .**
21be0 20 20 20 20 20 61 63 63 65 73 73 2c 20 6a 75 73       access, jus
21bf0 74 20 61 73 20 69 66 20 74 68 65 20 5b 53 51 4c  t as if the [SQL
21c00 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c  ITE_OPEN_READONL
21c10 59 5d 20 66 6c 61 67 20 68 61 64 20 62 65 65 6e  Y] flag had been
21c20 20 73 65 74 20 69 6e 20 74 68 65 20 0a 2a 2a 20   set in the .** 
21c30 20 20 20 20 74 68 69 72 64 20 61 72 67 75 6d 65      third argume
21c40 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70  nt to sqlite3_op
21c50 65 6e 5f 76 32 28 29 2e 20 5e 49 66 20 74 68 65  en_v2(). ^If the
21c60 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 69 73 20   mode option is 
21c70 73 65 74 20 74 6f 20 0a 2a 2a 20 20 20 20 20 22  set to .**     "
21c80 72 77 22 2c 20 74 68 65 6e 20 74 68 65 20 64 61  rw", then the da
21c90 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
21ca0 20 66 6f 72 20 72 65 61 64 2d 77 72 69 74 65 20   for read-write 
21cb0 28 62 75 74 20 6e 6f 74 20 63 72 65 61 74 65 29  (but not create)
21cc0 20 0a 2a 2a 20 20 20 20 20 61 63 63 65 73 73 2c   .**     access,
21cd0 20 61 73 20 69 66 20 53 51 4c 49 54 45 5f 4f 50   as if SQLITE_OP
21ce0 45 4e 5f 52 45 41 44 57 52 49 54 45 20 28 62 75  EN_READWRITE (bu
21cf0 74 20 6e 6f 74 20 53 51 4c 49 54 45 5f 4f 50 45  t not SQLITE_OPE
21d00 4e 5f 43 52 45 41 54 45 29 20 68 61 64 20 0a 2a  N_CREATE) had .*
21d10 2a 20 20 20 20 20 62 65 65 6e 20 73 65 74 2e 20  *     been set. 
21d20 5e 56 61 6c 75 65 20 22 72 77 63 22 20 69 73 20  ^Value "rwc" is 
21d30 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65  equivalent to se
21d40 74 74 69 6e 67 20 62 6f 74 68 20 0a 2a 2a 20 20  tting both .**  
21d50 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52     SQLITE_OPEN_R
21d60 45 41 44 57 52 49 54 45 20 61 6e 64 20 53 51 4c  EADWRITE and SQL
21d70 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2e  ITE_OPEN_CREATE.
21d80 20 20 5e 49 66 20 74 68 65 20 6d 6f 64 65 20 6f    ^If the mode o
21d90 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20  ption is.**     
21da0 73 65 74 20 74 6f 20 22 6d 65 6d 6f 72 79 22 20  set to "memory" 
21db0 74 68 65 6e 20 61 20 70 75 72 65 20 5b 69 6e 2d  then a pure [in-
21dc0 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 5d  memory database]
21dd0 20 74 68 61 74 20 6e 65 76 65 72 20 72 65 61 64   that never read
21de0 73 0a 2a 2a 20 20 20 20 20 6f 72 20 77 72 69 74  s.**     or writ
21df0 65 73 20 66 72 6f 6d 20 64 69 73 6b 20 69 73 20  es from disk is 
21e00 75 73 65 64 2e 20 5e 49 74 20 69 73 20 61 6e 20  used. ^It is an 
21e10 65 72 72 6f 72 20 74 6f 20 73 70 65 63 69 66 79  error to specify
21e20 20 61 20 76 61 6c 75 65 20 66 6f 72 0a 2a 2a 20   a value for.** 
21e30 20 20 20 20 74 68 65 20 6d 6f 64 65 20 70 61 72      the mode par
21e40 61 6d 65 74 65 72 20 74 68 61 74 20 69 73 20 6c  ameter that is l
21e50 65 73 73 20 72 65 73 74 72 69 63 74 69 76 65 20  ess restrictive 
21e60 74 68 61 6e 20 74 68 61 74 20 73 70 65 63 69 66  than that specif
21e70 69 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 74 68  ied by.**     th
21e80 65 20 66 6c 61 67 73 20 70 61 73 73 65 64 20 69  e flags passed i
21e90 6e 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  n the third para
21ea0 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
21eb0 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a  _open_v2()..**.*
21ec0 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 63 61 63 68  *   <li> <b>cach
21ed0 65 3c 2f 62 3e 3a 20 5e 54 68 65 20 63 61 63 68  e</b>: ^The cach
21ee0 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20  e parameter may 
21ef0 62 65 20 73 65 74 20 74 6f 20 65 69 74 68 65 72  be set to either
21f00 20 22 73 68 61 72 65 64 22 20 6f 72 0a 2a 2a 20   "shared" or.** 
21f10 20 20 20 20 22 70 72 69 76 61 74 65 22 2e 20 5e      "private". ^
21f20 53 65 74 74 69 6e 67 20 69 74 20 74 6f 20 22 73  Setting it to "s
21f30 68 61 72 65 64 22 20 69 73 20 65 71 75 69 76 61  hared" is equiva
21f40 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20  lent to setting 
21f50 74 68 65 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54  the.**     SQLIT
21f60 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43  E_OPEN_SHAREDCAC
21f70 48 45 20 62 69 74 20 69 6e 20 74 68 65 20 66 6c  HE bit in the fl
21f80 61 67 73 20 61 72 67 75 6d 65 6e 74 20 70 61 73  ags argument pas
21f90 73 65 64 20 74 6f 0a 2a 2a 20 20 20 20 20 73 71  sed to.**     sq
21fa0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e  lite3_open_v2().
21fb0 20 5e 53 65 74 74 69 6e 67 20 74 68 65 20 63 61   ^Setting the ca
21fc0 63 68 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f  che parameter to
21fd0 20 22 70 72 69 76 61 74 65 22 20 69 73 20 0a 2a   "private" is .*
21fe0 2a 20 20 20 20 20 65 71 75 69 76 61 6c 65 6e 74  *     equivalent
21ff0 20 74 6f 20 73 65 74 74 69 6e 67 20 74 68 65 20   to setting the 
22000 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56  SQLITE_OPEN_PRIV
22010 41 54 45 43 41 43 48 45 20 62 69 74 2e 0a 2a 2a  ATECACHE bit..**
22020 20 20 20 20 20 5e 49 66 20 73 71 6c 69 74 65 33       ^If sqlite3
22030 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 75 73  _open_v2() is us
22040 65 64 20 61 6e 64 20 74 68 65 20 22 63 61 63 68  ed and the "cach
22050 65 22 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  e" parameter is 
22060 70 72 65 73 65 6e 74 20 69 6e 0a 2a 2a 20 20 20  present in.**   
22070 20 20 61 20 55 52 49 20 66 69 6c 65 6e 61 6d 65    a URI filename
22080 2c 20 69 74 73 20 76 61 6c 75 65 20 6f 76 65 72  , its value over
22090 72 69 64 65 73 20 61 6e 79 20 62 65 68 61 76 69  rides any behavi
220a0 6f 72 20 72 65 71 75 65 73 74 65 64 20 62 79 20  or requested by 
220b0 73 65 74 74 69 6e 67 0a 2a 2a 20 20 20 20 20 53  setting.**     S
220c0 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41  QLITE_OPEN_PRIVA
220d0 54 45 43 41 43 48 45 20 6f 72 20 53 51 4c 49 54  TECACHE or SQLIT
220e0 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43  E_OPEN_SHAREDCAC
220f0 48 45 20 66 6c 61 67 2e 0a 2a 2a 20 3c 2f 75 6c  HE flag..** </ul
22100 3e 0a 2a 2a 0a 2a 2a 20 5e 53 70 65 63 69 66 79  >.**.** ^Specify
22110 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 20 70  ing an unknown p
22120 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65 20  arameter in the 
22130 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20  query component 
22140 6f 66 20 61 20 55 52 49 20 69 73 20 6e 6f 74 20  of a URI is not 
22150 61 6e 0a 2a 2a 20 65 72 72 6f 72 2e 20 20 46 75  an.** error.  Fu
22160 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66  ture versions of
22170 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 75 6e   SQLite might un
22180 64 65 72 73 74 61 6e 64 20 61 64 64 69 74 69 6f  derstand additio
22190 6e 61 6c 20 71 75 65 72 79 0a 2a 2a 20 70 61 72  nal query.** par
221a0 61 6d 65 74 65 72 73 2e 20 20 53 65 65 20 22 5b  ameters.  See "[
221b0 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 73  query parameters
221c0 20 77 69 74 68 20 73 70 65 63 69 61 6c 20 6d 65   with special me
221d0 61 6e 69 6e 67 20 74 6f 20 53 51 4c 69 74 65 5d  aning to SQLite]
221e0 22 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f  " for.** additio
221f0 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  nal information.
22200 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c  .**.** [[URI fil
22210 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73 5d 5d  ename examples]]
22220 20 3c 68 33 3e 55 52 49 20 66 69 6c 65 6e 61 6d   <h3>URI filenam
22230 65 20 65 78 61 6d 70 6c 65 73 3c 2f 68 33 3e 0a  e examples</h3>.
22240 2a 2a 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72  **.** <table bor
22250 64 65 72 3d 22 31 22 20 61 6c 69 67 6e 3d 63 65  der="1" align=ce
22260 6e 74 65 72 20 63 65 6c 6c 70 61 64 64 69 6e 67  nter cellpadding
22270 3d 35 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20  =5>.** <tr><th> 
22280 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 3c 74  URI filenames <t
22290 68 3e 20 52 65 73 75 6c 74 73 0a 2a 2a 20 3c 74  h> Results.** <t
222a0 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61  r><td> file:data
222b0 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20  .db <td> .**    
222c0 20 20 20 20 20 20 4f 70 65 6e 20 74 68 65 20 66        Open the f
222d0 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20 69 6e  ile "data.db" in
222e0 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 69 72   the current dir
222f0 65 63 74 6f 72 79 2e 0a 2a 2a 20 3c 74 72 3e 3c  ectory..** <tr><
22300 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66  td> file:/home/f
22310 72 65 64 2f 64 61 74 61 2e 64 62 3c 62 72 3e 0a  red/data.db<br>.
22320 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c 65  **          file
22330 3a 2f 2f 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61  :///home/fred/da
22340 74 61 2e 64 62 20 3c 62 72 3e 20 0a 2a 2a 20 20  ta.db <br> .**  
22350 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 6c          file://l
22360 6f 63 61 6c 68 6f 73 74 2f 68 6f 6d 65 2f 66 72  ocalhost/home/fr
22370 65 64 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e 20  ed/data.db <br> 
22380 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20  <td> .**        
22390 20 20 4f 70 65 6e 20 74 68 65 20 64 61 74 61 62    Open the datab
223a0 61 73 65 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f  ase file "/home/
223b0 66 72 65 64 2f 64 61 74 61 2e 64 62 22 2e 0a 2a  fred/data.db"..*
223c0 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a  * <tr><td> file:
223d0 2f 2f 64 61 72 6b 73 74 61 72 2f 68 6f 6d 65 2f  //darkstar/home/
223e0 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 74 64  fred/data.db <td
223f0 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 41  > .**          A
22400 6e 20 65 72 72 6f 72 2e 20 22 64 61 72 6b 73 74  n error. "darkst
22410 61 72 22 20 69 73 20 6e 6f 74 20 61 20 72 65 63  ar" is not a rec
22420 6f 67 6e 69 7a 65 64 20 61 75 74 68 6f 72 69 74  ognized authorit
22430 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 20 73 74  y..** <tr><td st
22440 79 6c 65 3d 22 77 68 69 74 65 2d 73 70 61 63 65  yle="white-space
22450 3a 6e 6f 77 72 61 70 22 3e 20 0a 2a 2a 20 20 20  :nowrap"> .**   
22460 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 43         file:///C
22470 3a 2f 44 6f 63 75 6d 65 6e 74 73 25 32 30 61 6e  :/Documents%20an
22480 64 25 32 30 53 65 74 74 69 6e 67 73 2f 66 72 65  d%20Settings/fre
22490 64 2f 44 65 73 6b 74 6f 70 2f 64 61 74 61 2e 64  d/Desktop/data.d
224a0 62 0a 2a 2a 20 20 20 20 20 3c 74 64 3e 20 57 69  b.**     <td> Wi
224b0 6e 64 6f 77 73 20 6f 6e 6c 79 3a 20 4f 70 65 6e  ndows only: Open
224c0 20 74 68 65 20 66 69 6c 65 20 22 64 61 74 61 2e   the file "data.
224d0 64 62 22 20 6f 6e 20 66 72 65 64 27 73 20 64 65  db" on fred's de
224e0 73 6b 74 6f 70 20 6f 6e 20 64 72 69 76 65 0a 2a  sktop on drive.*
224f0 2a 20 20 20 20 20 20 20 20 20 20 43 3a 2e 20 4e  *          C:. N
22500 6f 74 65 20 74 68 61 74 20 74 68 65 20 25 32 30  ote that the %20
22510 20 65 73 63 61 70 69 6e 67 20 69 6e 20 74 68 69   escaping in thi
22520 73 20 65 78 61 6d 70 6c 65 20 69 73 20 6e 6f 74  s example is not
22530 20 73 74 72 69 63 74 6c 79 20 0a 2a 2a 20 20 20   strictly .**   
22540 20 20 20 20 20 20 20 6e 65 63 65 73 73 61 72 79         necessary
22550 20 2d 20 73 70 61 63 65 20 63 68 61 72 61 63 74   - space charact
22560 65 72 73 20 63 61 6e 20 62 65 20 75 73 65 64 20  ers can be used 
22570 6c 69 74 65 72 61 6c 6c 79 0a 2a 2a 20 20 20 20  literally.**    
22580 20 20 20 20 20 20 69 6e 20 55 52 49 20 66 69 6c        in URI fil
22590 65 6e 61 6d 65 73 2e 0a 2a 2a 20 3c 74 72 3e 3c  enames..** <tr><
225a0 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62  td> file:data.db
225b0 3f 6d 6f 64 65 3d 72 6f 26 63 61 63 68 65 3d 70  ?mode=ro&cache=p
225c0 72 69 76 61 74 65 20 3c 74 64 3e 20 0a 2a 2a 20  rivate <td> .** 
225d0 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 66 69           Open fi
225e0 6c 65 20 22 64 61 74 61 2e 64 62 22 20 69 6e 20  le "data.db" in 
225f0 74 68 65 20 63 75 72 72 65 6e 74 20 64 69 72 65  the current dire
22600 63 74 6f 72 79 20 66 6f 72 20 72 65 61 64 2d 6f  ctory for read-o
22610 6e 6c 79 20 61 63 63 65 73 73 2e 0a 2a 2a 20 20  nly access..**  
22620 20 20 20 20 20 20 20 20 52 65 67 61 72 64 6c 65          Regardle
22630 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72  ss of whether or
22640 20 6e 6f 74 20 73 68 61 72 65 64 2d 63 61 63 68   not shared-cach
22650 65 20 6d 6f 64 65 20 69 73 20 65 6e 61 62 6c 65  e mode is enable
22660 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 20 20 20  d by.**         
22670 20 64 65 66 61 75 6c 74 2c 20 75 73 65 20 61 20   default, use a 
22680 70 72 69 76 61 74 65 20 63 61 63 68 65 2e 0a 2a  private cache..*
22690 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a  * <tr><td> file:
226a0 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e  /home/fred/data.
226b0 64 62 3f 76 66 73 3d 75 6e 69 78 2d 6e 6f 6c 6f  db?vfs=unix-nolo
226c0 63 6b 20 3c 74 64 3e 0a 2a 2a 20 20 20 20 20 20  ck <td>.**      
226d0 20 20 20 20 4f 70 65 6e 20 66 69 6c 65 20 22 2f      Open file "/
226e0 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64  home/fred/data.d
226f0 62 22 2e 20 55 73 65 20 74 68 65 20 73 70 65 63  b". Use the spec
22700 69 61 6c 20 56 46 53 20 22 75 6e 69 78 2d 6e 6f  ial VFS "unix-no
22710 6c 6f 63 6b 22 2e 0a 2a 2a 20 3c 74 72 3e 3c 74  lock"..** <tr><t
22720 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f  d> file:data.db?
22730 6d 6f 64 65 3d 72 65 61 64 6f 6e 6c 79 20 3c 74  mode=readonly <t
22740 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  d> .**          
22750 41 6e 20 65 72 72 6f 72 2e 20 22 72 65 61 64 6f  An error. "reado
22760 6e 6c 79 22 20 69 73 20 6e 6f 74 20 61 20 76 61  nly" is not a va
22770 6c 69 64 20 6f 70 74 69 6f 6e 20 66 6f 72 20 74  lid option for t
22780 68 65 20 22 6d 6f 64 65 22 20 70 61 72 61 6d 65  he "mode" parame
22790 74 65 72 2e 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e  ter..** </table>
227a0 0a 2a 2a 0a 2a 2a 20 5e 55 52 49 20 68 65 78 61  .**.** ^URI hexa
227b0 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73  decimal escape s
227c0 65 71 75 65 6e 63 65 73 20 28 25 48 48 29 20 61  equences (%HH) a
227d0 72 65 20 73 75 70 70 6f 72 74 65 64 20 77 69 74  re supported wit
227e0 68 69 6e 20 74 68 65 20 70 61 74 68 20 61 6e 64  hin the path and
227f0 0a 2a 2a 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e  .** query compon
22800 65 6e 74 73 20 6f 66 20 61 20 55 52 49 2e 20 41  ents of a URI. A
22810 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63   hexadecimal esc
22820 61 70 65 20 73 65 71 75 65 6e 63 65 20 63 6f 6e  ape sequence con
22830 73 69 73 74 73 20 6f 66 20 61 0a 2a 2a 20 70 65  sists of a.** pe
22840 72 63 65 6e 74 20 73 69 67 6e 20 2d 20 22 25 22  rcent sign - "%"
22850 20 2d 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 65   - followed by e
22860 78 61 63 74 6c 79 20 74 77 6f 20 68 65 78 61 64  xactly two hexad
22870 65 63 69 6d 61 6c 20 64 69 67 69 74 73 20 0a 2a  ecimal digits .*
22880 2a 20 73 70 65 63 69 66 79 69 6e 67 20 61 6e 20  * specifying an 
22890 6f 63 74 65 74 20 76 61 6c 75 65 2e 20 5e 42 65  octet value. ^Be
228a0 66 6f 72 65 20 74 68 65 20 70 61 74 68 20 6f 72  fore the path or
228b0 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74   query component
228c0 73 20 6f 66 20 61 0a 2a 2a 20 55 52 49 20 66 69  s of a.** URI fi
228d0 6c 65 6e 61 6d 65 20 61 72 65 20 69 6e 74 65 72  lename are inter
228e0 70 72 65 74 65 64 2c 20 74 68 65 79 20 61 72 65  preted, they are
228f0 20 65 6e 63 6f 64 65 64 20 75 73 69 6e 67 20 55   encoded using U
22900 54 46 2d 38 20 61 6e 64 20 61 6c 6c 20 0a 2a 2a  TF-8 and all .**
22910 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63   hexadecimal esc
22920 61 70 65 20 73 65 71 75 65 6e 63 65 73 20 72 65  ape sequences re
22930 70 6c 61 63 65 64 20 62 79 20 61 20 73 69 6e 67  placed by a sing
22940 6c 65 20 62 79 74 65 20 63 6f 6e 74 61 69 6e 69  le byte containi
22950 6e 67 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 73  ng the.** corres
22960 70 6f 6e 64 69 6e 67 20 6f 63 74 65 74 2e 20 49  ponding octet. I
22970 66 20 74 68 69 73 20 70 72 6f 63 65 73 73 20 67  f this process g
22980 65 6e 65 72 61 74 65 73 20 61 6e 20 69 6e 76 61  enerates an inva
22990 6c 69 64 20 55 54 46 2d 38 20 65 6e 63 6f 64 69  lid UTF-8 encodi
229a0 6e 67 2c 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c  ng,.** the resul
229b0 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64  ts are undefined
229c0 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20  ..**.** <b>Note 
229d0 74 6f 20 57 69 6e 64 6f 77 73 20 75 73 65 72 73  to Windows users
229e0 3a 3c 2f 62 3e 20 20 54 68 65 20 65 6e 63 6f 64  :</b>  The encod
229f0 69 6e 67 20 75 73 65 64 20 66 6f 72 20 74 68 65  ing used for the
22a00 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65   filename argume
22a10 6e 74 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33  nt.** of sqlite3
22a20 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69  _open() and sqli
22a30 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 6d 75  te3_open_v2() mu
22a40 73 74 20 62 65 20 55 54 46 2d 38 2c 20 6e 6f 74  st be UTF-8, not
22a50 20 77 68 61 74 65 76 65 72 0a 2a 2a 20 63 6f 64   whatever.** cod
22a60 65 70 61 67 65 20 69 73 20 63 75 72 72 65 6e 74  epage is current
22a70 6c 79 20 64 65 66 69 6e 65 64 2e 20 20 46 69 6c  ly defined.  Fil
22a80 65 6e 61 6d 65 73 20 63 6f 6e 74 61 69 6e 69 6e  enames containin
22a90 67 20 69 6e 74 65 72 6e 61 74 69 6f 6e 61 6c 0a  g international.
22aa0 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20 6d 75  ** characters mu
22ab0 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 20  st be converted 
22ac0 74 6f 20 55 54 46 2d 38 20 70 72 69 6f 72 20 74  to UTF-8 prior t
22ad0 6f 20 70 61 73 73 69 6e 67 20 74 68 65 6d 20 69  o passing them i
22ae0 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  nto.** sqlite3_o
22af0 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33  pen() or sqlite3
22b00 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a  _open_v2()..**.*
22b10 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e  * <b>Note to Win
22b20 64 6f 77 73 20 52 75 6e 74 69 6d 65 20 75 73 65  dows Runtime use
22b30 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 74 65 6d  rs:</b>  The tem
22b40 70 6f 72 61 72 79 20 64 69 72 65 63 74 6f 72 79  porary directory
22b50 20 6d 75 73 74 20 62 65 20 73 65 74 0a 2a 2a 20   must be set.** 
22b60 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67  prior to calling
22b70 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
22b80 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
22b90 76 32 28 29 2e 20 20 4f 74 68 65 72 77 69 73 65  v2().  Otherwise
22ba0 2c 20 76 61 72 69 6f 75 73 0a 2a 2a 20 66 65 61  , various.** fea
22bb0 74 75 72 65 73 20 74 68 61 74 20 72 65 71 75 69  tures that requi
22bc0 72 65 20 74 68 65 20 75 73 65 20 6f 66 20 74 65  re the use of te
22bd0 6d 70 6f 72 61 72 79 20 66 69 6c 65 73 20 6d 61  mporary files ma
22be0 79 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 53 65  y fail..**.** Se
22bf0 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
22c00 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f 72 79 5d  _temp_directory]
22c10 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
22c20 6f 70 65 6e 28 0a 20 20 63 6f 6e 73 74 20 63 68  open(.  const ch
22c30 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20  ar *filename,   
22c40 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65  /* Database file
22c50 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a  name (UTF-8) */.
22c60 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62    sqlite3 **ppDb
22c70 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54            /* OUT
22c80 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64  : SQLite db hand
22c90 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c  le */.);.int sql
22ca0 69 74 65 33 5f 6f 70 65 6e 31 36 28 0a 20 20 63  ite3_open16(.  c
22cb0 6f 6e 73 74 20 76 6f 69 64 20 2a 66 69 6c 65 6e  onst void *filen
22cc0 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61  ame,   /* Databa
22cd0 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46  se filename (UTF
22ce0 2d 31 36 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65  -16) */.  sqlite
22cf0 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20  3 **ppDb        
22d00 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65    /* OUT: SQLite
22d10 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b   db handle */.);
22d20 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65  .int sqlite3_ope
22d30 6e 5f 76 32 28 0a 20 20 63 6f 6e 73 74 20 63 68  n_v2(.  const ch
22d40 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20  ar *filename,   
22d50 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65  /* Database file
22d60 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a  name (UTF-8) */.
22d70 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62    sqlite3 **ppDb
22d80 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54  ,         /* OUT
22d90 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64  : SQLite db hand
22da0 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 66 6c 61 67  le */.  int flag
22db0 73 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  s,              
22dc0 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a 20 20 63 6f  /* Flags */.  co
22dd0 6e 73 74 20 63 68 61 72 20 2a 7a 56 66 73 20 20  nst char *zVfs  
22de0 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66        /* Name of
22df0 20 56 46 53 20 6d 6f 64 75 6c 65 20 74 6f 20 75   VFS module to u
22e00 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  se */.);../*.** 
22e10 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e  CAPI3REF: Obtain
22e20 20 56 61 6c 75 65 73 20 46 6f 72 20 55 52 49 20   Values For URI 
22e30 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a  Parameters.**.**
22e40 20 54 68 65 73 65 20 61 72 65 20 75 74 69 6c 69   These are utili
22e50 74 79 20 72 6f 75 74 69 6e 65 73 2c 20 75 73 65  ty routines, use
22e60 66 75 6c 20 74 6f 20 56 46 53 20 69 6d 70 6c 65  ful to VFS imple
22e70 6d 65 6e 74 61 74 69 6f 6e 73 2c 20 74 68 61 74  mentations, that
22e80 20 63 68 65 63 6b 0a 2a 2a 20 74 6f 20 73 65 65   check.** to see
22e90 20 69 66 20 61 20 64 61 74 61 62 61 73 65 20 66   if a database f
22ea0 69 6c 65 20 77 61 73 20 61 20 55 52 49 20 74 68  ile was a URI th
22eb0 61 74 20 63 6f 6e 74 61 69 6e 65 64 20 61 20 73  at contained a s
22ec0 70 65 63 69 66 69 63 20 71 75 65 72 79 20 0a 2a  pecific query .*
22ed0 2a 20 70 61 72 61 6d 65 74 65 72 2c 20 61 6e 64  * parameter, and
22ee0 20 69 66 20 73 6f 20 6f 62 74 61 69 6e 73 20 74   if so obtains t
22ef0 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 61 74  he value of that
22f00 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72   query parameter
22f10 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 46 20 69 73 20  ..**.** If F is 
22f20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
22f30 65 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20 70 61  ename pointer pa
22f40 73 73 65 64 20 69 6e 74 6f 20 74 68 65 20 78 4f  ssed into the xO
22f50 70 65 6e 28 29 20 6d 65 74 68 6f 64 20 6f 66 20  pen() method of 
22f60 0a 2a 2a 20 61 20 56 46 53 20 69 6d 70 6c 65 6d  .** a VFS implem
22f70 65 6e 74 61 74 69 6f 6e 20 77 68 65 6e 20 74 68  entation when th
22f80 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65  e flags paramete
22f90 72 20 74 6f 20 78 4f 70 65 6e 28 29 20 68 61 73  r to xOpen() has
22fa0 20 6f 6e 65 20 6f 72 20 0a 2a 2a 20 6d 6f 72 65   one or .** more
22fb0 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   of the [SQLITE_
22fc0 4f 50 45 4e 5f 55 52 49 5d 20 6f 72 20 5b 53 51  OPEN_URI] or [SQ
22fd0 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44  LITE_OPEN_MAIN_D
22fe0 42 5d 20 62 69 74 73 20 73 65 74 20 61 6e 64 0a  B] bits set and.
22ff0 2a 2a 20 50 20 69 73 20 74 68 65 20 6e 61 6d 65  ** P is the name
23000 20 6f 66 20 74 68 65 20 71 75 65 72 79 20 70 61   of the query pa
23010 72 61 6d 65 74 65 72 2c 20 74 68 65 6e 0a 2a 2a  rameter, then.**
23020 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72   sqlite3_uri_par
23030 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74 75  ameter(F,P) retu
23040 72 6e 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66  rns the value of
23050 20 74 68 65 20 50 0a 2a 2a 20 70 61 72 61 6d 65   the P.** parame
23060 74 65 72 20 69 66 20 69 74 20 65 78 69 73 74 73  ter if it exists
23070 20 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   or a NULL point
23080 65 72 20 69 66 20 50 20 64 6f 65 73 20 6e 6f 74  er if P does not
23090 20 61 70 70 65 61 72 20 61 73 20 61 20 0a 2a 2a   appear as a .**
230a0 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72   query parameter
230b0 20 6f 6e 20 46 2e 20 20 49 66 20 50 20 69 73 20   on F.  If P is 
230c0 61 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  a query paramete
230d0 72 20 6f 66 20 46 0a 2a 2a 20 68 61 73 20 6e 6f  r of F.** has no
230e0 20 65 78 70 6c 69 63 69 74 20 76 61 6c 75 65 2c   explicit value,
230f0 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72   then sqlite3_ur
23100 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29  i_parameter(F,P)
23110 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 70 6f   returns.** a po
23120 69 6e 74 65 72 20 74 6f 20 61 6e 20 65 6d 70 74  inter to an empt
23130 79 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  y string..**.** 
23140 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  The sqlite3_uri_
23150 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72  boolean(F,P,B) r
23160 6f 75 74 69 6e 65 20 61 73 73 75 6d 65 73 20 74  outine assumes t
23170 68 61 74 20 50 20 69 73 20 61 20 62 6f 6f 6c 65  hat P is a boole
23180 61 6e 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  an.** parameter 
23190 61 6e 64 20 72 65 74 75 72 6e 73 20 74 72 75 65  and returns true
231a0 20 28 31 29 20 6f 72 20 66 61 6c 73 65 20 28 30   (1) or false (0
231b0 29 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 74  ) according to t
231c0 68 65 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 50  he value.** of P
231d0 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75  .  The sqlite3_u
231e0 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42  ri_boolean(F,P,B
231f0 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ) routine return
23200 73 20 74 72 75 65 20 28 31 29 20 69 66 20 74 68  s true (1) if th
23210 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 71 75  e.** value of qu
23220 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 50 20  ery parameter P 
23230 69 73 20 6f 6e 65 20 6f 66 20 22 79 65 73 22 2c  is one of "yes",
23240 20 22 74 72 75 65 22 2c 20 6f 72 20 22 6f 6e 22   "true", or "on"
23250 20 69 6e 20 61 6e 79 0a 2a 2a 20 63 61 73 65 20   in any.** case 
23260 6f 72 20 69 66 20 74 68 65 20 76 61 6c 75 65 20  or if the value 
23270 62 65 67 69 6e 73 20 77 69 74 68 20 61 20 6e 6f  begins with a no
23280 6e 2d 7a 65 72 6f 20 6e 75 6d 62 65 72 2e 20 20  n-zero number.  
23290 54 68 65 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  The .** sqlite3_
232a0 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c  uri_boolean(F,P,
232b0 42 29 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  B) routines retu
232c0 72 6e 73 20 66 61 6c 73 65 20 28 30 29 20 69 66  rns false (0) if
232d0 20 74 68 65 20 76 61 6c 75 65 20 6f 66 0a 2a 2a   the value of.**
232e0 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72   query parameter
232f0 20 50 20 69 73 20 6f 6e 65 20 6f 66 20 22 6e 6f   P is one of "no
23300 22 2c 20 22 66 61 6c 73 65 22 2c 20 6f 72 20 22  ", "false", or "
23310 6f 66 66 22 20 69 6e 20 61 6e 79 20 63 61 73 65  off" in any case
23320 20 6f 72 0a 2a 2a 20 69 66 20 74 68 65 20 76 61   or.** if the va
23330 6c 75 65 20 62 65 67 69 6e 73 20 77 69 74 68 20  lue begins with 
23340 61 20 6e 75 6d 65 72 69 63 20 7a 65 72 6f 2e 20  a numeric zero. 
23350 20 49 66 20 50 20 69 73 20 6e 6f 74 20 61 20 71   If P is not a q
23360 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65  uery.** paramete
23370 72 20 6f 6e 20 46 20 6f 72 20 69 66 20 74 68 65  r on F or if the
23380 20 76 61 6c 75 65 20 6f 66 20 50 20 69 73 20 64   value of P is d
23390 6f 65 73 20 6e 6f 74 20 6d 61 74 63 68 20 61 6e  oes not match an
233a0 79 20 6f 66 20 74 68 65 0a 2a 2a 20 61 62 6f 76  y of the.** abov
233b0 65 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  e, then sqlite3_
233c0 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c  uri_boolean(F,P,
233d0 42 29 20 72 65 74 75 72 6e 73 20 28 42 21 3d 30  B) returns (B!=0
233e0 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  )..**.** The sql
233f0 69 74 65 33 5f 75 72 69 5f 69 6e 74 36 34 28 46  ite3_uri_int64(F
23400 2c 50 2c 44 29 20 72 6f 75 74 69 6e 65 20 63 6f  ,P,D) routine co
23410 6e 76 65 72 74 73 20 74 68 65 20 76 61 6c 75 65  nverts the value
23420 20 6f 66 20 50 20 69 6e 74 6f 20 61 0a 2a 2a 20   of P into a.** 
23430 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e  64-bit signed in
23440 74 65 67 65 72 20 61 6e 64 20 72 65 74 75 72 6e  teger and return
23450 73 20 74 68 61 74 20 69 6e 74 65 67 65 72 2c 20  s that integer, 
23460 6f 72 20 44 20 69 66 20 50 20 64 6f 65 73 20 6e  or D if P does n
23470 6f 74 0a 2a 2a 20 65 78 69 73 74 2e 20 20 49 66  ot.** exist.  If
23480 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20   the value of P 
23490 69 73 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68  is something oth
234a0 65 72 20 74 68 61 6e 20 61 6e 20 69 6e 74 65 67  er than an integ
234b0 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 7a 65 72 6f  er, then.** zero
234c0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
234d0 20 0a 2a 2a 20 49 66 20 46 20 69 73 20 61 20 4e   .** If F is a N
234e0 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65  ULL pointer, the
234f0 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61  n sqlite3_uri_pa
23500 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74  rameter(F,P) ret
23510 75 72 6e 73 20 4e 55 4c 4c 20 61 6e 64 0a 2a 2a  urns NULL and.**
23520 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f   sqlite3_uri_boo
23530 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 65 74 75  lean(F,P,B) retu
23540 72 6e 73 20 42 2e 20 20 49 66 20 46 20 69 73 20  rns B.  If F is 
23550 6e 6f 74 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  not a NULL point
23560 65 72 20 61 6e 64 0a 2a 2a 20 69 73 20 6e 6f 74  er and.** is not
23570 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65   a database file
23580 20 70 61 74 68 6e 61 6d 65 20 70 6f 69 6e 74 65   pathname pointe
23590 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 70 61  r that SQLite pa
235a0 73 73 65 64 20 69 6e 74 6f 20 74 68 65 20 78 4f  ssed into the xO
235b0 70 65 6e 0a 2a 2a 20 56 46 53 20 6d 65 74 68 6f  pen.** VFS metho
235c0 64 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  d, then the beha
235d0 76 69 6f 72 20 6f 66 20 74 68 69 73 20 72 6f 75  vior of this rou
235e0 74 69 6e 65 20 69 73 20 75 6e 64 65 66 69 6e 65  tine is undefine
235f0 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 0a 2a  d and probably.*
23600 2a 20 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a  * undesirable..*
23610 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  /.const char *sq
23620 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65  lite3_uri_parame
23630 74 65 72 28 63 6f 6e 73 74 20 63 68 61 72 20 2a  ter(const char *
23640 7a 46 69 6c 65 6e 61 6d 65 2c 20 63 6f 6e 73 74  zFilename, const
23650 20 63 68 61 72 20 2a 7a 50 61 72 61 6d 29 3b 0a   char *zParam);.
23660 69 6e 74 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  int sqlite3_uri_
23670 62 6f 6f 6c 65 61 6e 28 63 6f 6e 73 74 20 63 68  boolean(const ch
23680 61 72 20 2a 7a 46 69 6c 65 2c 20 63 6f 6e 73 74  ar *zFile, const
23690 20 63 68 61 72 20 2a 7a 50 61 72 61 6d 2c 20 69   char *zParam, i
236a0 6e 74 20 62 44 65 66 61 75 6c 74 29 3b 0a 73 71  nt bDefault);.sq
236b0 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69  lite3_int64 sqli
236c0 74 65 33 5f 75 72 69 5f 69 6e 74 36 34 28 63 6f  te3_uri_int64(co
236d0 6e 73 74 20 63 68 61 72 2a 2c 20 63 6f 6e 73 74  nst char*, const
236e0 20 63 68 61 72 2a 2c 20 73 71 6c 69 74 65 33 5f   char*, sqlite3_
236f0 69 6e 74 36 34 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20  int64);.../*.** 
23700 43 41 50 49 33 52 45 46 3a 20 45 72 72 6f 72 20  CAPI3REF: Error 
23710 43 6f 64 65 73 20 41 6e 64 20 4d 65 73 73 61 67  Codes And Messag
23720 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  es.**.** ^The sq
23730 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20  lite3_errcode() 
23740 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
23750 73 20 74 68 65 20 6e 75 6d 65 72 69 63 20 5b 72  s the numeric [r
23760 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 0a 2a  esult code] or.*
23770 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75  * [extended resu
23780 6c 74 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65  lt code] for the
23790 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 66 61 69   most recent fai
237a0 6c 65 64 20 73 71 6c 69 74 65 33 5f 2a 20 41 50  led sqlite3_* AP
237b0 49 20 63 61 6c 6c 0a 2a 2a 20 61 73 73 6f 63 69  I call.** associ
237c0 61 74 65 64 20 77 69 74 68 20 61 20 5b 64 61 74  ated with a [dat
237d0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
237e0 5d 2e 20 49 66 20 61 20 70 72 69 6f 72 20 41 50  ]. If a prior AP
237f0 49 20 63 61 6c 6c 20 66 61 69 6c 65 64 0a 2a 2a  I call failed.**
23800 20 62 75 74 20 74 68 65 20 6d 6f 73 74 20 72 65   but the most re
23810 63 65 6e 74 20 41 50 49 20 63 61 6c 6c 20 73 75  cent API call su
23820 63 63 65 65 64 65 64 2c 20 74 68 65 20 72 65 74  cceeded, the ret
23830 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 0a 2a  urn value from.*
23840 2a 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64  * sqlite3_errcod
23850 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64  e() is undefined
23860 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
23870 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65  extended_errcode
23880 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  ().** interface 
23890 69 73 20 74 68 65 20 73 61 6d 65 20 65 78 63 65  is the same exce
238a0 70 74 20 74 68 61 74 20 69 74 20 61 6c 77 61 79  pt that it alway
238b0 73 20 72 65 74 75 72 6e 73 20 74 68 65 20 0a 2a  s returns the .*
238c0 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75  * [extended resu
238d0 6c 74 20 63 6f 64 65 5d 20 65 76 65 6e 20 77 68  lt code] even wh
238e0 65 6e 20 65 78 74 65 6e 64 65 64 20 72 65 73 75  en extended resu
238f0 6c 74 20 63 6f 64 65 73 20 61 72 65 0a 2a 2a 20  lt codes are.** 
23900 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20  disabled..**.** 
23910 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72  ^The sqlite3_err
23920 6d 73 67 28 29 20 61 6e 64 20 73 71 6c 69 74 65  msg() and sqlite
23930 33 5f 65 72 72 6d 73 67 31 36 28 29 20 72 65 74  3_errmsg16() ret
23940 75 72 6e 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67  urn English-lang
23950 75 61 67 65 0a 2a 2a 20 74 65 78 74 20 74 68 61  uage.** text tha
23960 74 20 64 65 73 63 72 69 62 65 73 20 74 68 65 20  t describes the 
23970 65 72 72 6f 72 2c 20 61 73 20 65 69 74 68 65 72  error, as either
23980 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36   UTF-8 or UTF-16
23990 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a   respectively..*
239a0 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f  * ^(Memory to ho
239b0 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73  ld the error mes
239c0 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 6d  sage string is m
239d0 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c  anaged internall
239e0 79 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63  y..** The applic
239f0 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e  ation does not n
23a00 65 65 64 20 74 6f 20 77 6f 72 72 79 20 61 62 6f  eed to worry abo
23a10 75 74 20 66 72 65 65 69 6e 67 20 74 68 65 20 72  ut freeing the r
23a20 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76 65  esult..** Howeve
23a30 72 2c 20 74 68 65 20 65 72 72 6f 72 20 73 74 72  r, the error str
23a40 69 6e 67 20 6d 69 67 68 74 20 62 65 20 6f 76 65  ing might be ove
23a50 72 77 72 69 74 74 65 6e 20 6f 72 20 64 65 61 6c  rwritten or deal
23a60 6c 6f 63 61 74 65 64 20 62 79 0a 2a 2a 20 73 75  located by.** su
23a70 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74  bsequent calls t
23a80 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69  o other SQLite i
23a90 6e 74 65 72 66 61 63 65 20 66 75 6e 63 74 69 6f  nterface functio
23aa0 6e 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ns.)^.**.** ^The
23ab0 20 73 71 6c 69 74 65 33 5f 65 72 72 73 74 72 28   sqlite3_errstr(
23ac0 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
23ad0 72 6e 73 20 74 68 65 20 45 6e 67 6c 69 73 68 2d  rns the English-
23ae0 6c 61 6e 67 75 61 67 65 20 74 65 78 74 0a 2a 2a  language text.**
23af0 20 74 68 61 74 20 64 65 73 63 72 69 62 65 73 20   that describes 
23b00 74 68 65 20 5b 72 65 73 75 6c 74 20 63 6f 64 65  the [result code
23b10 5d 2c 20 61 73 20 55 54 46 2d 38 2e 0a 2a 2a 20  ], as UTF-8..** 
23b20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64  ^(Memory to hold
23b30 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61   the error messa
23b40 67 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e  ge string is man
23b50 61 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 0a  aged internally.
23b60 2a 2a 20 61 6e 64 20 6d 75 73 74 20 6e 6f 74 20  ** and must not 
23b70 62 65 20 66 72 65 65 64 20 62 79 20 74 68 65 20  be freed by the 
23b80 61 70 70 6c 69 63 61 74 69 6f 6e 29 5e 2e 0a 2a  application)^..*
23b90 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 73 65  *.** When the se
23ba0 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64  rialized [thread
23bb0 69 6e 67 20 6d 6f 64 65 5d 20 69 73 20 69 6e 20  ing mode] is in 
23bc0 75 73 65 2c 20 69 74 20 6d 69 67 68 74 20 62 65  use, it might be
23bd0 20 74 68 65 0a 2a 2a 20 63 61 73 65 20 74 68 61   the.** case tha
23be0 74 20 61 20 73 65 63 6f 6e 64 20 65 72 72 6f 72  t a second error
23bf0 20 6f 63 63 75 72 73 20 6f 6e 20 61 20 73 65 70   occurs on a sep
23c00 61 72 61 74 65 20 74 68 72 65 61 64 20 69 6e 20  arate thread in 
23c10 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 74  between.** the t
23c20 69 6d 65 20 6f 66 20 74 68 65 20 66 69 72 73 74  ime of the first
23c30 20 65 72 72 6f 72 20 61 6e 64 20 74 68 65 20 63   error and the c
23c40 61 6c 6c 20 74 6f 20 74 68 65 73 65 20 69 6e 74  all to these int
23c50 65 72 66 61 63 65 73 2e 0a 2a 2a 20 57 68 65 6e  erfaces..** When
23c60 20 74 68 61 74 20 68 61 70 70 65 6e 73 2c 20 74   that happens, t
23c70 68 65 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20  he second error 
23c80 77 69 6c 6c 20 62 65 20 72 65 70 6f 72 74 65 64  will be reported
23c90 20 73 69 6e 63 65 20 74 68 65 73 65 0a 2a 2a 20   since these.** 
23ca0 69 6e 74 65 72 66 61 63 65 73 20 61 6c 77 61 79  interfaces alway
23cb0 73 20 72 65 70 6f 72 74 20 74 68 65 20 6d 6f 73  s report the mos
23cc0 74 20 72 65 63 65 6e 74 20 72 65 73 75 6c 74 2e  t recent result.
23cd0 20 20 54 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68    To avoid.** th
23ce0 69 73 2c 20 65 61 63 68 20 74 68 72 65 61 64 20  is, each thread 
23cf0 63 61 6e 20 6f 62 74 61 69 6e 20 65 78 63 6c 75  can obtain exclu
23d00 73 69 76 65 20 75 73 65 20 6f 66 20 74 68 65 20  sive use of the 
23d10 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
23d20 74 69 6f 6e 5d 20 44 0a 2a 2a 20 62 79 20 69 6e  tion] D.** by in
23d30 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  voking [sqlite3_
23d40 6d 75 74 65 78 5f 65 6e 74 65 72 5d 28 5b 73 71  mutex_enter]([sq
23d50 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28  lite3_db_mutex](
23d60 44 29 29 20 62 65 66 6f 72 65 20 62 65 67 69 6e  D)) before begin
23d70 6e 69 6e 67 0a 2a 2a 20 74 6f 20 75 73 65 20 44  ning.** to use D
23d80 20 61 6e 64 20 69 6e 76 6f 6b 69 6e 67 20 5b 73   and invoking [s
23d90 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61  qlite3_mutex_lea
23da0 76 65 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f  ve]([sqlite3_db_
23db0 6d 75 74 65 78 5d 28 44 29 29 20 61 66 74 65 72  mutex](D)) after
23dc0 0a 2a 2a 20 61 6c 6c 20 63 61 6c 6c 73 20 74 6f  .** all calls to
23dd0 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 73 20   the interfaces 
23de0 6c 69 73 74 65 64 20 68 65 72 65 20 61 72 65 20  listed here are 
23df0 63 6f 6d 70 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a  completed..**.**
23e00 20 49 66 20 61 6e 20 69 6e 74 65 72 66 61 63 65   If an interface
23e10 20 66 61 69 6c 73 20 77 69 74 68 20 53 51 4c 49   fails with SQLI
23e20 54 45 5f 4d 49 53 55 53 45 2c 20 74 68 61 74 20  TE_MISUSE, that 
23e30 6d 65 61 6e 73 20 74 68 65 20 69 6e 74 65 72 66  means the interf
23e40 61 63 65 0a 2a 2a 20 77 61 73 20 69 6e 76 6f 6b  ace.** was invok
23e50 65 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 62  ed incorrectly b
23e60 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  y the applicatio
23e70 6e 2e 20 20 49 6e 20 74 68 61 74 20 63 61 73 65  n.  In that case
23e80 2c 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20 63  , the.** error c
23e90 6f 64 65 20 61 6e 64 20 6d 65 73 73 61 67 65 20  ode and message 
23ea0 6d 61 79 20 6f 72 20 6d 61 79 20 6e 6f 74 20 62  may or may not b
23eb0 65 20 73 65 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71  e set..*/.int sq
23ec0 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 73 71  lite3_errcode(sq
23ed0 6c 69 74 65 33 20 2a 64 62 29 3b 0a 69 6e 74 20  lite3 *db);.int 
23ee0 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64  sqlite3_extended
23ef0 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33  _errcode(sqlite3
23f00 20 2a 64 62 29 3b 0a 63 6f 6e 73 74 20 63 68 61   *db);.const cha
23f10 72 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  r *sqlite3_errms
23f20 67 28 73 71 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e  g(sqlite3*);.con
23f30 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
23f40 5f 65 72 72 6d 73 67 31 36 28 73 71 6c 69 74 65  _errmsg16(sqlite
23f50 33 2a 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20  3*);.const char 
23f60 2a 73 71 6c 69 74 65 33 5f 65 72 72 73 74 72 28  *sqlite3_errstr(
23f70 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  int);../*.** CAP
23f80 49 33 52 45 46 3a 20 53 51 4c 20 53 74 61 74 65  I3REF: SQL State
23f90 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b  ment Object.** K
23fa0 45 59 57 4f 52 44 53 3a 20 7b 70 72 65 70 61 72  EYWORDS: {prepar
23fb0 65 64 20 73 74 61 74 65 6d 65 6e 74 7d 20 7b 70  ed statement} {p
23fc0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
23fd0 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73  ts}.**.** An ins
23fe0 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62  tance of this ob
23ff0 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74 73 20  ject represents 
24000 61 20 73 69 6e 67 6c 65 20 53 51 4c 20 73 74 61  a single SQL sta
24010 74 65 6d 65 6e 74 2e 0a 2a 2a 20 54 68 69 73 20  tement..** This 
24020 6f 62 6a 65 63 74 20 69 73 20 76 61 72 69 6f 75  object is variou
24030 73 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 61 20 22  sly known as a "
24040 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
24050 6e 74 22 20 6f 72 20 61 0a 2a 2a 20 22 63 6f 6d  nt" or a.** "com
24060 70 69 6c 65 64 20 53 51 4c 20 73 74 61 74 65 6d  piled SQL statem
24070 65 6e 74 22 20 6f 72 20 73 69 6d 70 6c 79 20 61  ent" or simply a
24080 73 20 61 20 22 73 74 61 74 65 6d 65 6e 74 22 2e  s a "statement".
24090 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69 66 65 20  .**.** The life 
240a0 6f 66 20 61 20 73 74 61 74 65 6d 65 6e 74 20 6f  of a statement o
240b0 62 6a 65 63 74 20 67 6f 65 73 20 73 6f 6d 65 74  bject goes somet
240c0 68 69 6e 67 20 6c 69 6b 65 20 74 68 69 73 3a 0a  hing like this:.
240d0 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c  **.** <ol>.** <l
240e0 69 3e 20 43 72 65 61 74 65 20 74 68 65 20 6f 62  i> Create the ob
240f0 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69  ject using [sqli
24100 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
24110 5d 20 6f 72 20 61 20 72 65 6c 61 74 65 64 0a 2a  ] or a related.*
24120 2a 20 20 20 20 20 20 66 75 6e 63 74 69 6f 6e 2e  *      function.
24130 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e 64 20 76 61  .** <li> Bind va
24140 6c 75 65 73 20 74 6f 20 5b 68 6f 73 74 20 70 61  lues to [host pa
24150 72 61 6d 65 74 65 72 73 5d 20 75 73 69 6e 67 20  rameters] using 
24160 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  the sqlite3_bind
24170 5f 2a 28 29 0a 2a 2a 20 20 20 20 20 20 69 6e 74  _*().**      int
24180 65 72 66 61 63 65 73 2e 0a 2a 2a 20 3c 6c 69 3e  erfaces..** <li>
24190 20 52 75 6e 20 74 68 65 20 53 51 4c 20 62 79 20   Run the SQL by 
241a0 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
241b0 5f 73 74 65 70 28 29 5d 20 6f 6e 65 20 6f 72 20  _step()] one or 
241c0 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c  more times..** <
241d0 6c 69 3e 20 52 65 73 65 74 20 74 68 65 20 73 74  li> Reset the st
241e0 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73  atement using [s
241f0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
24200 74 68 65 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a 20  then go back.** 
24210 20 20 20 20 20 74 6f 20 73 74 65 70 20 32 2e 20       to step 2. 
24220 20 44 6f 20 74 68 69 73 20 7a 65 72 6f 20 6f 72   Do this zero or
24230 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20   more times..** 
24240 3c 6c 69 3e 20 44 65 73 74 72 6f 79 20 74 68 65  <li> Destroy the
24250 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73   object using [s
24260 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
24270 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a  )]..** </ol>.**.
24280 2a 2a 20 52 65 66 65 72 20 74 6f 20 64 6f 63 75  ** Refer to docu
24290 6d 65 6e 74 61 74 69 6f 6e 20 6f 6e 20 69 6e 64  mentation on ind
242a0 69 76 69 64 75 61 6c 20 6d 65 74 68 6f 64 73 20  ividual methods 
242b0 61 62 6f 76 65 20 66 6f 72 20 61 64 64 69 74 69  above for additi
242c0 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74  onal.** informat
242d0 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ion..*/.typedef 
242e0 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 73  struct sqlite3_s
242f0 74 6d 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  tmt sqlite3_stmt
24300 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
24310 46 3a 20 52 75 6e 2d 74 69 6d 65 20 4c 69 6d 69  F: Run-time Limi
24320 74 73 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20  ts.**.** ^(This 
24330 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73  interface allows
24340 20 74 68 65 20 73 69 7a 65 20 6f 66 20 76 61 72   the size of var
24350 69 6f 75 73 20 63 6f 6e 73 74 72 75 63 74 73 20  ious constructs 
24360 74 6f 20 62 65 20 6c 69 6d 69 74 65 64 0a 2a 2a  to be limited.**
24370 20 6f 6e 20 61 20 63 6f 6e 6e 65 63 74 69 6f 6e   on a connection
24380 20 62 79 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62   by connection b
24390 61 73 69 73 2e 20 20 54 68 65 20 66 69 72 73 74  asis.  The first
243a0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
243b0 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  e.** [database c
243c0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 68 6f 73 65  onnection] whose
243d0 20 6c 69 6d 69 74 20 69 73 20 74 6f 20 62 65 20   limit is to be 
243e0 73 65 74 20 6f 72 20 71 75 65 72 69 65 64 2e 20  set or queried. 
243f0 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70   The.** second p
24400 61 72 61 6d 65 74 65 72 20 69 73 20 6f 6e 65 20  arameter is one 
24410 6f 66 20 74 68 65 20 5b 6c 69 6d 69 74 20 63 61  of the [limit ca
24420 74 65 67 6f 72 69 65 73 5d 20 74 68 61 74 20 64  tegories] that d
24430 65 66 69 6e 65 20 61 0a 2a 2a 20 63 6c 61 73 73  efine a.** class
24440 20 6f 66 20 63 6f 6e 73 74 72 75 63 74 73 20 74   of constructs t
24450 6f 20 62 65 20 73 69 7a 65 20 6c 69 6d 69 74 65  o be size limite
24460 64 2e 20 20 54 68 65 20 74 68 69 72 64 20 70 61  d.  The third pa
24470 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a  rameter is the.*
24480 2a 20 6e 65 77 20 6c 69 6d 69 74 20 66 6f 72 20  * new limit for 
24490 74 68 61 74 20 63 6f 6e 73 74 72 75 63 74 2e 29  that construct.)
244a0 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ^.**.** ^If the 
244b0 6e 65 77 20 6c 69 6d 69 74 20 69 73 20 61 20 6e  new limit is a n
244c0 65 67 61 74 69 76 65 20 6e 75 6d 62 65 72 2c 20  egative number, 
244d0 74 68 65 20 6c 69 6d 69 74 20 69 73 20 75 6e 63  the limit is unc
244e0 68 61 6e 67 65 64 2e 0a 2a 2a 20 5e 28 46 6f 72  hanged..** ^(For
244f0 20 65 61 63 68 20 6c 69 6d 69 74 20 63 61 74 65   each limit cate
24500 67 6f 72 79 20 53 51 4c 49 54 45 5f 4c 49 4d 49  gory SQLITE_LIMI
24510 54 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 20 74 68  T_<i>NAME</i> th
24520 65 72 65 20 69 73 20 61 20 0a 2a 2a 20 5b 6c 69  ere is a .** [li
24530 6d 69 74 73 20 7c 20 68 61 72 64 20 75 70 70 65  mits | hard uppe
24540 72 20 62 6f 75 6e 64 5d 0a 2a 2a 20 73 65 74 20  r bound].** set 
24550 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  at compile-time 
24560 62 79 20 61 20 43 20 70 72 65 70 72 6f 63 65 73  by a C preproces
24570 73 6f 72 20 6d 61 63 72 6f 20 63 61 6c 6c 65 64  sor macro called
24580 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 53 51  .** [limits | SQ
24590 4c 49 54 45 5f 4d 41 58 5f 3c 69 3e 4e 41 4d 45  LITE_MAX_<i>NAME
245a0 3c 2f 69 3e 5d 2e 0a 2a 2a 20 28 54 68 65 20 22  </i>]..** (The "
245b0 5f 4c 49 4d 49 54 5f 22 20 69 6e 20 74 68 65 20  _LIMIT_" in the 
245c0 6e 61 6d 65 20 69 73 20 63 68 61 6e 67 65 64 20  name is changed 
245d0 74 6f 20 22 5f 4d 41 58 5f 22 2e 29 29 5e 0a 2a  to "_MAX_".))^.*
245e0 2a 20 5e 41 74 74 65 6d 70 74 73 20 74 6f 20 69  * ^Attempts to i
245f0 6e 63 72 65 61 73 65 20 61 20 6c 69 6d 69 74 20  ncrease a limit 
24600 61 62 6f 76 65 20 69 74 73 20 68 61 72 64 20 75  above its hard u
24610 70 70 65 72 20 62 6f 75 6e 64 20 61 72 65 0a 2a  pper bound are.*
24620 2a 20 73 69 6c 65 6e 74 6c 79 20 74 72 75 6e 63  * silently trunc
24630 61 74 65 64 20 74 6f 20 74 68 65 20 68 61 72 64  ated to the hard
24640 20 75 70 70 65 72 20 62 6f 75 6e 64 2e 0a 2a 2a   upper bound..**
24650 0a 2a 2a 20 5e 52 65 67 61 72 64 6c 65 73 73 20  .** ^Regardless 
24660 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  of whether or no
24670 74 20 74 68 65 20 6c 69 6d 69 74 20 77 61 73 20  t the limit was 
24680 63 68 61 6e 67 65 64 2c 20 74 68 65 20 0a 2a 2a  changed, the .**
24690 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28   [sqlite3_limit(
246a0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
246b0 75 72 6e 73 20 74 68 65 20 70 72 69 6f 72 20 76  urns the prior v
246c0 61 6c 75 65 20 6f 66 20 74 68 65 20 6c 69 6d 69  alue of the limi
246d0 74 2e 0a 2a 2a 20 5e 48 65 6e 63 65 2c 20 74 6f  t..** ^Hence, to
246e0 20 66 69 6e 64 20 74 68 65 20 63 75 72 72 65 6e   find the curren
246f0 74 20 76 61 6c 75 65 20 6f 66 20 61 20 6c 69 6d  t value of a lim
24700 69 74 20 77 69 74 68 6f 75 74 20 63 68 61 6e 67  it without chang
24710 69 6e 67 20 69 74 2c 0a 2a 2a 20 73 69 6d 70 6c  ing it,.** simpl
24720 79 20 69 6e 76 6f 6b 65 20 74 68 69 73 20 69 6e  y invoke this in
24730 74 65 72 66 61 63 65 20 77 69 74 68 20 74 68 65  terface with the
24740 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
24750 20 73 65 74 20 74 6f 20 2d 31 2e 0a 2a 2a 0a 2a   set to -1..**.*
24760 2a 20 52 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74  * Run-time limit
24770 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66  s are intended f
24780 6f 72 20 75 73 65 20 69 6e 20 61 70 70 6c 69 63  or use in applic
24790 61 74 69 6f 6e 73 20 74 68 61 74 20 6d 61 6e 61  ations that mana
247a0 67 65 0a 2a 2a 20 62 6f 74 68 20 74 68 65 69 72  ge.** both their
247b0 20 6f 77 6e 20 69 6e 74 65 72 6e 61 6c 20 64 61   own internal da
247c0 74 61 62 61 73 65 20 61 6e 64 20 61 6c 73 6f 20  tabase and also 
247d0 64 61 74 61 62 61 73 65 73 20 74 68 61 74 20 61  databases that a
247e0 72 65 20 63 6f 6e 74 72 6f 6c 6c 65 64 0a 2a 2a  re controlled.**
247f0 20 62 79 20 75 6e 74 72 75 73 74 65 64 20 65 78   by untrusted ex
24800 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 2e 20  ternal sources. 
24810 20 41 6e 20 65 78 61 6d 70 6c 65 20 61 70 70 6c   An example appl
24820 69 63 61 74 69 6f 6e 20 6d 69 67 68 74 20 62 65  ication might be
24830 20 61 0a 2a 2a 20 77 65 62 20 62 72 6f 77 73 65   a.** web browse
24840 72 20 74 68 61 74 20 68 61 73 20 69 74 73 20 6f  r that has its o
24850 77 6e 20 64 61 74 61 62 61 73 65 73 20 66 6f 72  wn databases for
24860 20 73 74 6f 72 69 6e 67 20 68 69 73 74 6f 72 79   storing history
24870 20 61 6e 64 0a 2a 2a 20 73 65 70 61 72 61 74 65   and.** separate
24880 20 64 61 74 61 62 61 73 65 73 20 63 6f 6e 74 72   databases contr
24890 6f 6c 6c 65 64 20 62 79 20 4a 61 76 61 53 63 72  olled by JavaScr
248a0 69 70 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  ipt applications
248b0 20 64 6f 77 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f   downloaded.** o
248c0 66 66 20 74 68 65 20 49 6e 74 65 72 6e 65 74 2e  ff the Internet.
248d0 20 20 54 68 65 20 69 6e 74 65 72 6e 61 6c 20 64    The internal d
248e0 61 74 61 62 61 73 65 73 20 63 61 6e 20 62 65 20  atabases can be 
248f0 67 69 76 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 72  given the.** lar
24900 67 65 2c 20 64 65 66 61 75 6c 74 20 6c 69 6d 69  ge, default limi
24910 74 73 2e 20 20 44 61 74 61 62 61 73 65 73 20 6d  ts.  Databases m
24920 61 6e 61 67 65 64 20 62 79 20 65 78 74 65 72 6e  anaged by extern
24930 61 6c 20 73 6f 75 72 63 65 73 20 63 61 6e 0a 2a  al sources can.*
24940 2a 20 62 65 20 67 69 76 65 6e 20 6d 75 63 68 20  * be given much 
24950 73 6d 61 6c 6c 65 72 20 6c 69 6d 69 74 73 20 64  smaller limits d
24960 65 73 69 67 6e 65 64 20 74 6f 20 70 72 65 76 65  esigned to preve
24970 6e 74 20 61 20 64 65 6e 69 61 6c 20 6f 66 20 73  nt a denial of s
24980 65 72 76 69 63 65 0a 2a 2a 20 61 74 74 61 63 6b  ervice.** attack
24990 2e 20 20 44 65 76 65 6c 6f 70 65 72 73 20 6d 69  .  Developers mi
249a0 67 68 74 20 61 6c 73 6f 20 77 61 6e 74 20 74 6f  ght also want to
249b0 20 75 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65   use the [sqlite
249c0 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
249d0 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  ()].** interface
249e0 20 74 6f 20 66 75 72 74 68 65 72 20 63 6f 6e 74   to further cont
249f0 72 6f 6c 20 75 6e 74 72 75 73 74 65 64 20 53 51  rol untrusted SQ
24a00 4c 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20  L.  The size of 
24a10 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  the database.** 
24a20 63 72 65 61 74 65 64 20 62 79 20 61 6e 20 75 6e  created by an un
24a30 74 72 75 73 74 65 64 20 73 63 72 69 70 74 20 63  trusted script c
24a40 61 6e 20 62 65 20 63 6f 6e 74 61 69 6e 65 64 20  an be contained 
24a50 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 6d 61  using the.** [ma
24a60 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50  x_page_count] [P
24a70 52 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65  RAGMA]..**.** Ne
24a80 77 20 72 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74  w run-time limit
24a90 20 63 61 74 65 67 6f 72 69 65 73 20 6d 61 79 20   categories may 
24aa0 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75  be added in futu
24ab0 72 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2f 0a  re releases..*/.
24ac0 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c 69 6d 69  int sqlite3_limi
24ad0 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20  t(sqlite3*, int 
24ae0 69 64 2c 20 69 6e 74 20 6e 65 77 56 61 6c 29 3b  id, int newVal);
24af0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
24b00 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 6d 69 74  : Run-Time Limit
24b10 20 43 61 74 65 67 6f 72 69 65 73 0a 2a 2a 20 4b   Categories.** K
24b20 45 59 57 4f 52 44 53 3a 20 7b 6c 69 6d 69 74 20  EYWORDS: {limit 
24b30 63 61 74 65 67 6f 72 79 7d 20 7b 2a 6c 69 6d 69  category} {*limi
24b40 74 20 63 61 74 65 67 6f 72 69 65 73 7d 0a 2a 2a  t categories}.**
24b50 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61  .** These consta
24b60 6e 74 73 20 64 65 66 69 6e 65 20 76 61 72 69 6f  nts define vario
24b70 75 73 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 6c  us performance l
24b80 69 6d 69 74 73 0a 2a 2a 20 74 68 61 74 20 63 61  imits.** that ca
24b90 6e 20 62 65 20 6c 6f 77 65 72 65 64 20 61 74 20  n be lowered at 
24ba0 72 75 6e 2d 74 69 6d 65 20 75 73 69 6e 67 20 5b  run-time using [
24bb0 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d  sqlite3_limit()]
24bc0 2e 0a 2a 2a 20 54 68 65 20 73 79 6e 6f 70 73 69  ..** The synopsi
24bd0 73 20 6f 66 20 74 68 65 20 6d 65 61 6e 69 6e 67  s of the meaning
24be0 73 20 6f 66 20 74 68 65 20 76 61 72 69 6f 75 73  s of the various
24bf0 20 6c 69 6d 69 74 73 20 69 73 20 73 68 6f 77 6e   limits is shown
24c00 20 62 65 6c 6f 77 2e 0a 2a 2a 20 41 64 64 69 74   below..** Addit
24c10 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f  ional informatio
24c20 6e 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 61  n is available a
24c30 74 20 5b 6c 69 6d 69 74 73 20 7c 20 4c 69 6d 69  t [limits | Limi
24c40 74 73 20 69 6e 20 53 51 4c 69 74 65 5d 2e 0a 2a  ts in SQLite]..*
24c50 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53  *.** <dl>.** [[S
24c60 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47  QLITE_LIMIT_LENG
24c70 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  TH]] ^(<dt>SQLIT
24c80 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 3c 2f  E_LIMIT_LENGTH</
24c90 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
24ca0 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20 61  aximum size of a
24cb0 6e 79 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f  ny string or BLO
24cc0 42 20 6f 72 20 74 61 62 6c 65 20 72 6f 77 2c 20  B or table row, 
24cd0 69 6e 20 62 79 74 65 73 2e 3c 64 64 3e 29 5e 0a  in bytes.<dd>)^.
24ce0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
24cf0 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 5d  IMIT_SQL_LENGTH]
24d00 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  ] ^(<dt>SQLITE_L
24d10 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 3c  IMIT_SQL_LENGTH<
24d20 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
24d30 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  maximum length o
24d40 66 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  f an SQL stateme
24d50 6e 74 2c 20 69 6e 20 62 79 74 65 73 2e 3c 2f 64  nt, in bytes.</d
24d60 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d>)^.**.** [[SQL
24d70 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e  ITE_LIMIT_COLUMN
24d80 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
24d90 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c 2f 64 74  LIMIT_COLUMN</dt
24da0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
24db0 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63  imum number of c
24dc0 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 74 61 62 6c  olumns in a tabl
24dd0 65 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f 72 20  e definition or 
24de0 69 6e 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74  in the.** result
24df0 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43   set of a [SELEC
24e00 54 5d 20 6f 72 20 74 68 65 20 6d 61 78 69 6d 75  T] or the maximu
24e10 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  m number of colu
24e20 6d 6e 73 20 69 6e 20 61 6e 20 69 6e 64 65 78 0a  mns in an index.
24e30 2a 2a 20 6f 72 20 69 6e 20 61 6e 20 4f 52 44 45  ** or in an ORDE
24e40 52 20 42 59 20 6f 72 20 47 52 4f 55 50 20 42 59  R BY or GROUP BY
24e50 20 63 6c 61 75 73 65 2e 3c 2f 64 64 3e 29 5e 0a   clause.</dd>)^.
24e60 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
24e70 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 5d  IMIT_EXPR_DEPTH]
24e80 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  ] ^(<dt>SQLITE_L
24e90 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 3c  IMIT_EXPR_DEPTH<
24ea0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
24eb0 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66  maximum depth of
24ec0 20 74 68 65 20 70 61 72 73 65 20 74 72 65 65 20   the parse tree 
24ed0 6f 6e 20 61 6e 79 20 65 78 70 72 65 73 73 69 6f  on any expressio
24ee0 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  n.</dd>)^.**.** 
24ef0 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43  [[SQLITE_LIMIT_C
24f00 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 5d 5d  OMPOUND_SELECT]]
24f10 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
24f20 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c  MIT_COMPOUND_SEL
24f30 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  ECT</dt>.** <dd>
24f40 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
24f50 65 72 20 6f 66 20 74 65 72 6d 73 20 69 6e 20 61  er of terms in a
24f60 20 63 6f 6d 70 6f 75 6e 64 20 53 45 4c 45 43 54   compound SELECT
24f70 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e   statement.</dd>
24f80 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
24f90 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 5d  E_LIMIT_VDBE_OP]
24fa0 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  ] ^(<dt>SQLITE_L
24fb0 49 4d 49 54 5f 56 44 42 45 5f 4f 50 3c 2f 64 74  IMIT_VDBE_OP</dt
24fc0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
24fd0 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 69  imum number of i
24fe0 6e 73 74 72 75 63 74 69 6f 6e 73 20 69 6e 20 61  nstructions in a
24ff0 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65   virtual machine
25000 20 70 72 6f 67 72 61 6d 0a 2a 2a 20 75 73 65 64   program.** used
25010 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 6e   to implement an
25020 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20   SQL statement. 
25030 20 54 68 69 73 20 6c 69 6d 69 74 20 69 73 20 6e   This limit is n
25040 6f 74 20 63 75 72 72 65 6e 74 6c 79 0a 2a 2a 20  ot currently.** 
25050 65 6e 66 6f 72 63 65 64 2c 20 74 68 6f 75 67 68  enforced, though
25060 20 74 68 61 74 20 6d 69 67 68 74 20 62 65 20 61   that might be a
25070 64 64 65 64 20 69 6e 20 73 6f 6d 65 20 66 75 74  dded in some fut
25080 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66 0a 2a  ure release of.*
25090 2a 20 53 51 4c 69 74 65 2e 3c 2f 64 64 3e 29 5e  * SQLite.</dd>)^
250a0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
250b0 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41  LIMIT_FUNCTION_A
250c0 52 47 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  RG]] ^(<dt>SQLIT
250d0 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e  E_LIMIT_FUNCTION
250e0 5f 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  _ARG</dt>.** <dd
250f0 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  >The maximum num
25100 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73  ber of arguments
25110 20 6f 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 3c   on a function.<
25120 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  /dd>)^.**.** [[S
25130 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41  QLITE_LIMIT_ATTA
25140 43 48 45 44 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  CHED]] ^(<dt>SQL
25150 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48  ITE_LIMIT_ATTACH
25160 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  ED</dt>.** <dd>T
25170 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
25180 72 20 6f 66 20 5b 41 54 54 41 43 48 20 7c 20 61  r of [ATTACH | a
25190 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65  ttached database
251a0 73 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  s].)^</dd>.**.**
251b0 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
251c0 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e  LIKE_PATTERN_LEN
251d0 47 54 48 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53  GTH]].** ^(<dt>S
251e0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45  QLITE_LIMIT_LIKE
251f0 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 3c  _PATTERN_LENGTH<
25200 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
25210 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  maximum length o
25220 66 20 74 68 65 20 70 61 74 74 65 72 6e 20 61 72  f the pattern ar
25230 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 4c  gument to the [L
25240 49 4b 45 5d 20 6f 72 0a 2a 2a 20 5b 47 4c 4f 42  IKE] or.** [GLOB
25250 5d 20 6f 70 65 72 61 74 6f 72 73 2e 3c 2f 64 64  ] operators.</dd
25260 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
25270 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c  TE_LIMIT_VARIABL
25280 45 5f 4e 55 4d 42 45 52 5d 5d 0a 2a 2a 20 5e 28  E_NUMBER]].** ^(
25290 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
252a0 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52  _VARIABLE_NUMBER
252b0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
252c0 20 6d 61 78 69 6d 75 6d 20 69 6e 64 65 78 20 6e   maximum index n
252d0 75 6d 62 65 72 20 6f 66 20 61 6e 79 20 5b 70 61  umber of any [pa
252e0 72 61 6d 65 74 65 72 5d 20 69 6e 20 61 6e 20 53  rameter] in an S
252f0 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 29 5e 0a  QL statement.)^.
25300 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
25310 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50  IMIT_TRIGGER_DEP
25320 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  TH]] ^(<dt>SQLIT
25330 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f  E_LIMIT_TRIGGER_
25340 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  DEPTH</dt>.** <d
25350 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65  d>The maximum de
25360 70 74 68 20 6f 66 20 72 65 63 75 72 73 69 6f 6e  pth of recursion
25370 20 66 6f 72 20 74 72 69 67 67 65 72 73 2e 3c 2f   for triggers.</
25380 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a  dd>)^.** </dl>.*
25390 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
253a0 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 20 20 20  _LIMIT_LENGTH   
253b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
253c0 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   0.#define SQLIT
253d0 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47  E_LIMIT_SQL_LENG
253e0 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TH              
253f0 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    1.#define SQLI
25400 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 20  TE_LIMIT_COLUMN 
25410 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
25420 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c     2.#define SQL
25430 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44  ITE_LIMIT_EXPR_D
25440 45 50 54 48 20 20 20 20 20 20 20 20 20 20 20 20  EPTH            
25450 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51      3.#define SQ
25460 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f  LITE_LIMIT_COMPO
25470 55 4e 44 5f 53 45 4c 45 43 54 20 20 20 20 20 20  UND_SELECT      
25480 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53       4.#define S
25490 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45  QLITE_LIMIT_VDBE
254a0 5f 4f 50 20 20 20 20 20 20 20 20 20 20 20 20 20  _OP             
254b0 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20        5.#define 
254c0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e  SQLITE_LIMIT_FUN
254d0 43 54 49 4f 4e 5f 41 52 47 20 20 20 20 20 20 20  CTION_ARG       
254e0 20 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65         6.#define
254f0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54   SQLITE_LIMIT_AT
25500 54 41 43 48 45 44 20 20 20 20 20 20 20 20 20 20  TACHED          
25510 20 20 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e          7.#defin
25520 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  e SQLITE_LIMIT_L
25530 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47  IKE_PATTERN_LENG
25540 54 48 20 20 20 20 20 20 20 38 0a 23 64 65 66 69  TH       8.#defi
25550 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
25560 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 20  VARIABLE_NUMBER 
25570 20 20 20 20 20 20 20 20 20 20 39 0a 23 64 65 66            9.#def
25580 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
25590 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 20 20  _TRIGGER_DEPTH  
255a0 20 20 20 20 20 20 20 20 20 20 31 30 0a 0a 2f 2a            10../*
255b0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
255c0 6d 70 69 6c 69 6e 67 20 41 6e 20 53 51 4c 20 53  mpiling An SQL S
255d0 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4b 45 59 57  tatement.** KEYW
255e0 4f 52 44 53 3a 20 7b 53 51 4c 20 73 74 61 74 65  ORDS: {SQL state
255f0 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72 7d 0a 2a  ment compiler}.*
25600 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 75 74 65 20  *.** To execute 
25610 61 6e 20 53 51 4c 20 71 75 65 72 79 2c 20 69 74  an SQL query, it
25620 20 6d 75 73 74 20 66 69 72 73 74 20 62 65 20 63   must first be c
25630 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 61 20 62  ompiled into a b
25640 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f 67  yte-code.** prog
25650 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65 20 6f 66  ram using one of
25660 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e   these routines.
25670 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  .**.** The first
25680 20 61 72 67 75 6d 65 6e 74 2c 20 22 64 62 22 2c   argument, "db",
25690 20 69 73 20 61 20 5b 64 61 74 61 62 61 73 65 20   is a [database 
256a0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 74 61  connection] obta
256b0 69 6e 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 70  ined from a.** p
256c0 72 69 6f 72 20 73 75 63 63 65 73 73 66 75 6c 20  rior successful 
256d0 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
256e0 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  _open()], [sqlit
256f0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 6f 72  e3_open_v2()] or
25700 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  .** [sqlite3_ope
25710 6e 31 36 28 29 5d 2e 20 20 54 68 65 20 64 61 74  n16()].  The dat
25720 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
25730 20 6d 75 73 74 20 6e 6f 74 20 68 61 76 65 20 62   must not have b
25740 65 65 6e 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a  een closed..**.*
25750 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67  * The second arg
25760 75 6d 65 6e 74 2c 20 22 7a 53 71 6c 22 2c 20 69  ument, "zSql", i
25770 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  s the statement 
25780 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 2c 20  to be compiled, 
25790 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20 65 69  encoded.** as ei
257a0 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54  ther UTF-8 or UT
257b0 46 2d 31 36 2e 20 20 54 68 65 20 73 71 6c 69 74  F-16.  The sqlit
257c0 65 33 5f 70 72 65 70 61 72 65 28 29 20 61 6e 64  e3_prepare() and
257d0 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
257e0 5f 76 32 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61  _v2().** interfa
257f0 63 65 73 20 75 73 65 20 55 54 46 2d 38 2c 20 61  ces use UTF-8, a
25800 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nd sqlite3_prepa
25810 72 65 31 36 28 29 20 61 6e 64 20 73 71 6c 69 74  re16() and sqlit
25820 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
25830 29 0a 2a 2a 20 75 73 65 20 55 54 46 2d 31 36 2e  ).** use UTF-16.
25840 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e  .**.** ^If the n
25850 42 79 74 65 20 61 72 67 75 6d 65 6e 74 20 69 73  Byte argument is
25860 20 6c 65 73 73 20 74 68 61 6e 20 7a 65 72 6f 2c   less than zero,
25870 20 74 68 65 6e 20 7a 53 71 6c 20 69 73 20 72 65   then zSql is re
25880 61 64 20 75 70 20 74 6f 20 74 68 65 0a 2a 2a 20  ad up to the.** 
25890 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69  first zero termi
258a0 6e 61 74 6f 72 2e 20 5e 49 66 20 6e 42 79 74 65  nator. ^If nByte
258b0 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65   is non-negative
258c0 2c 20 74 68 65 6e 20 69 74 20 69 73 20 74 68 65  , then it is the
258d0 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 6e 75 6d 62   maximum.** numb
258e0 65 72 20 6f 66 20 20 62 79 74 65 73 20 72 65 61  er of  bytes rea
258f0 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 20 20 5e 57  d from zSql.  ^W
25900 68 65 6e 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e  hen nByte is non
25910 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 0a 2a  -negative, the.*
25920 2a 20 7a 53 71 6c 20 73 74 72 69 6e 67 20 65 6e  * zSql string en
25930 64 73 20 61 74 20 65 69 74 68 65 72 20 74 68 65  ds at either the
25940 20 66 69 72 73 74 20 27 5c 30 30 30 27 20 6f 72   first '\000' or
25950 20 27 5c 75 30 30 30 30 27 20 63 68 61 72 61 63   '\u0000' charac
25960 74 65 72 20 6f 72 0a 2a 2a 20 74 68 65 20 6e 42  ter or.** the nB
25970 79 74 65 2d 74 68 20 62 79 74 65 2c 20 77 68 69  yte-th byte, whi
25980 63 68 65 76 65 72 20 63 6f 6d 65 73 20 66 69 72  chever comes fir
25990 73 74 2e 20 49 66 20 74 68 65 20 63 61 6c 6c 65  st. If the calle
259a0 72 20 6b 6e 6f 77 73 0a 2a 2a 20 74 68 61 74 20  r knows.** that 
259b0 74 68 65 20 73 75 70 70 6c 69 65 64 20 73 74 72  the supplied str
259c0 69 6e 67 20 69 73 20 6e 75 6c 2d 74 65 72 6d 69  ing is nul-termi
259d0 6e 61 74 65 64 2c 20 74 68 65 6e 20 74 68 65 72  nated, then ther
259e0 65 20 69 73 20 61 20 73 6d 61 6c 6c 0a 2a 2a 20  e is a small.** 
259f0 70 65 72 66 6f 72 6d 61 6e 63 65 20 61 64 76 61  performance adva
25a00 6e 74 61 67 65 20 74 6f 20 62 65 20 67 61 69 6e  ntage to be gain
25a10 65 64 20 62 79 20 70 61 73 73 69 6e 67 20 61 6e  ed by passing an
25a20 20 6e 42 79 74 65 20 70 61 72 61 6d 65 74 65 72   nByte parameter
25a30 20 74 68 61 74 0a 2a 2a 20 69 73 20 65 71 75 61   that.** is equa
25a40 6c 20 74 6f 20 74 68 65 20 6e 75 6d 62 65 72 20  l to the number 
25a50 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  of bytes in the 
25a60 69 6e 70 75 74 20 73 74 72 69 6e 67 20 3c 69 3e  input string <i>
25a70 69 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e 0a 2a 2a  including</i>.**
25a80 20 74 68 65 20 6e 75 6c 2d 74 65 72 6d 69 6e 61   the nul-termina
25a90 74 6f 72 20 62 79 74 65 73 20 61 73 20 74 68 69  tor bytes as thi
25aa0 73 20 73 61 76 65 73 20 53 51 4c 69 74 65 20 66  s saves SQLite f
25ab0 72 6f 6d 20 68 61 76 69 6e 67 20 74 6f 0a 2a 2a  rom having to.**
25ac0 20 6d 61 6b 65 20 61 20 63 6f 70 79 20 6f 66 20   make a copy of 
25ad0 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67  the input string
25ae0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 70 7a 54 61  ..**.** ^If pzTa
25af0 69 6c 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74  il is not NULL t
25b00 68 65 6e 20 2a 70 7a 54 61 69 6c 20 69 73 20 6d  hen *pzTail is m
25b10 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20  ade to point to 
25b20 74 68 65 20 66 69 72 73 74 20 62 79 74 65 0a 2a  the first byte.*
25b30 2a 20 70 61 73 74 20 74 68 65 20 65 6e 64 20 6f  * past the end o
25b40 66 20 74 68 65 20 66 69 72 73 74 20 53 51 4c 20  f the first SQL 
25b50 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71  statement in zSq
25b60 6c 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e  l.  These routin
25b70 65 73 20 6f 6e 6c 79 0a 2a 2a 20 63 6f 6d 70 69  es only.** compi
25b80 6c 65 20 74 68 65 20 66 69 72 73 74 20 73 74 61  le the first sta
25b90 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2c 20  tement in zSql, 
25ba0 73 6f 20 2a 70 7a 54 61 69 6c 20 69 73 20 6c 65  so *pzTail is le
25bb0 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 0a 2a  ft pointing to.*
25bc0 2a 20 77 68 61 74 20 72 65 6d 61 69 6e 73 20 75  * what remains u
25bd0 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a  ncompiled..**.**
25be0 20 5e 2a 70 70 53 74 6d 74 20 69 73 20 6c 65 66   ^*ppStmt is lef
25bf0 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20 61 20  t pointing to a 
25c00 63 6f 6d 70 69 6c 65 64 20 5b 70 72 65 70 61 72  compiled [prepar
25c10 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68  ed statement] th
25c20 61 74 20 63 61 6e 20 62 65 0a 2a 2a 20 65 78 65  at can be.** exe
25c30 63 75 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  cuted using [sql
25c40 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 20 20 5e  ite3_step()].  ^
25c50 49 66 20 74 68 65 72 65 20 69 73 20 61 6e 20 65  If there is an e
25c60 72 72 6f 72 2c 20 2a 70 70 53 74 6d 74 20 69 73  rror, *ppStmt is
25c70 20 73 65 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e   set.** to NULL.
25c80 20 20 5e 49 66 20 74 68 65 20 69 6e 70 75 74 20    ^If the input 
25c90 74 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 6e 6f  text contains no
25ca0 20 53 51 4c 20 28 69 66 20 74 68 65 20 69 6e 70   SQL (if the inp
25cb0 75 74 20 69 73 20 61 6e 20 65 6d 70 74 79 0a 2a  ut is an empty.*
25cc0 2a 20 73 74 72 69 6e 67 20 6f 72 20 61 20 63 6f  * string or a co
25cd0 6d 6d 65 6e 74 29 20 74 68 65 6e 20 2a 70 70 53  mment) then *ppS
25ce0 74 6d 74 20 69 73 20 73 65 74 20 74 6f 20 4e 55  tmt is set to NU
25cf0 4c 4c 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 69  LL..** The calli
25d00 6e 67 20 70 72 6f 63 65 64 75 72 65 20 69 73 20  ng procedure is 
25d10 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20  responsible for 
25d20 64 65 6c 65 74 69 6e 67 20 74 68 65 20 63 6f 6d  deleting the com
25d30 70 69 6c 65 64 0a 2a 2a 20 53 51 4c 20 73 74 61  piled.** SQL sta
25d40 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71  tement using [sq
25d50 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
25d60 5d 20 61 66 74 65 72 20 69 74 20 68 61 73 20 66  ] after it has f
25d70 69 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 2e  inished with it.
25d80 0a 2a 2a 20 70 70 53 74 6d 74 20 6d 61 79 20 6e  .** ppStmt may n
25d90 6f 74 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  ot be NULL..**.*
25da0 2a 20 5e 4f 6e 20 73 75 63 63 65 73 73 2c 20 74  * ^On success, t
25db0 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  he sqlite3_prepa
25dc0 72 65 28 29 20 66 61 6d 69 6c 79 20 6f 66 20 72  re() family of r
25dd0 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b  outines return [
25de0 53 51 4c 49 54 45 5f 4f 4b 5d 3b 0a 2a 2a 20 6f  SQLITE_OK];.** o
25df0 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72  therwise an [err
25e00 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75  or code] is retu
25e10 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  rned..**.** The 
25e20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
25e30 76 32 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  v2() and sqlite3
25e40 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 20  _prepare16_v2() 
25e50 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 0a 2a  interfaces are.*
25e60 2a 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f  * recommended fo
25e70 72 20 61 6c 6c 20 6e 65 77 20 70 72 6f 67 72 61  r all new progra
25e80 6d 73 2e 20 54 68 65 20 74 77 6f 20 6f 6c 64 65  ms. The two olde
25e90 72 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  r interfaces are
25ea0 20 72 65 74 61 69 6e 65 64 0a 2a 2a 20 66 6f 72   retained.** for
25eb0 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61   backwards compa
25ec0 74 69 62 69 6c 69 74 79 2c 20 62 75 74 20 74 68  tibility, but th
25ed0 65 69 72 20 75 73 65 20 69 73 20 64 69 73 63 6f  eir use is disco
25ee0 75 72 61 67 65 64 2e 0a 2a 2a 20 5e 49 6e 20 74  uraged..** ^In t
25ef0 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  he "v2" interfac
25f00 65 73 2c 20 74 68 65 20 70 72 65 70 61 72 65 64  es, the prepared
25f10 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 68   statement.** th
25f20 61 74 20 69 73 20 72 65 74 75 72 6e 65 64 20 28  at is returned (
25f30 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d  the [sqlite3_stm
25f40 74 5d 20 6f 62 6a 65 63 74 29 20 63 6f 6e 74 61  t] object) conta
25f50 69 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68  ins a copy of th
25f60 65 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51  e.** original SQ
25f70 4c 20 74 65 78 74 2e 20 54 68 69 73 20 63 61 75  L text. This cau
25f80 73 65 73 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ses the [sqlite3
25f90 5f 73 74 65 70 28 29 5d 20 69 6e 74 65 72 66 61  _step()] interfa
25fa0 63 65 20 74 6f 0a 2a 2a 20 62 65 68 61 76 65 20  ce to.** behave 
25fb0 64 69 66 66 65 72 65 6e 74 6c 79 20 69 6e 20 74  differently in t
25fc0 68 72 65 65 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a  hree ways:.**.**
25fd0 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a   <ol>.** <li>.**
25fe0 20 5e 49 66 20 74 68 65 20 64 61 74 61 62 61 73   ^If the databas
25ff0 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 73  e schema changes
26000 2c 20 69 6e 73 74 65 61 64 20 6f 66 20 72 65 74  , instead of ret
26010 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 53  urning [SQLITE_S
26020 43 48 45 4d 41 5d 20 61 73 20 69 74 0a 2a 2a 20  CHEMA] as it.** 
26030 61 6c 77 61 79 73 20 75 73 65 64 20 74 6f 20 64  always used to d
26040 6f 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  o, [sqlite3_step
26050 28 29 5d 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74  ()] will automat
26060 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65  ically recompile
26070 20 74 68 65 20 53 51 4c 0a 2a 2a 20 73 74 61 74   the SQL.** stat
26080 65 6d 65 6e 74 20 61 6e 64 20 74 72 79 20 74 6f  ement and try to
26090 20 72 75 6e 20 69 74 20 61 67 61 69 6e 2e 20 41   run it again. A
260a0 73 20 6d 61 6e 79 20 61 73 20 5b 53 51 4c 49 54  s many as [SQLIT
260b0 45 5f 4d 41 58 5f 53 43 48 45 4d 41 5f 52 45 54  E_MAX_SCHEMA_RET
260c0 52 59 5d 0a 2a 2a 20 72 65 74 72 69 65 73 20 77  RY].** retries w
260d0 69 6c 6c 20 6f 63 63 75 72 20 62 65 66 6f 72 65  ill occur before
260e0 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
260f0 67 69 76 65 73 20 75 70 20 61 6e 64 20 72 65 74  gives up and ret
26100 75 72 6e 73 20 61 6e 20 65 72 72 6f 72 2e 0a 2a  urns an error..*
26110 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c  * </li>.**.** <l
26120 69 3e 0a 2a 2a 20 5e 57 68 65 6e 20 61 6e 20 65  i>.** ^When an e
26130 72 72 6f 72 20 6f 63 63 75 72 73 2c 20 5b 73 71  rror occurs, [sq
26140 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69  lite3_step()] wi
26150 6c 6c 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66  ll return one of
26160 20 74 68 65 20 64 65 74 61 69 6c 65 64 0a 2a 2a   the detailed.**
26170 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 6f   [error codes] o
26180 72 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f  r [extended erro
26190 72 20 63 6f 64 65 73 5d 2e 20 20 5e 54 68 65 20  r codes].  ^The 
261a0 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f 72 20  legacy behavior 
261b0 77 61 73 20 74 68 61 74 0a 2a 2a 20 5b 73 71 6c  was that.** [sql
261c0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 6f 75  ite3_step()] wou
261d0 6c 64 20 6f 6e 6c 79 20 72 65 74 75 72 6e 20 61  ld only return a
261e0 20 67 65 6e 65 72 69 63 20 5b 53 51 4c 49 54 45   generic [SQLITE
261f0 5f 45 52 52 4f 52 5d 20 72 65 73 75 6c 74 20 63  _ERROR] result c
26200 6f 64 65 0a 2a 2a 20 61 6e 64 20 74 68 65 20 61  ode.** and the a
26210 70 70 6c 69 63 61 74 69 6f 6e 20 77 6f 75 6c 64  pplication would
26220 20 68 61 76 65 20 74 6f 20 6d 61 6b 65 20 61 20   have to make a 
26230 73 65 63 6f 6e 64 20 63 61 6c 6c 20 74 6f 20 5b  second call to [
26240 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
26250 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  .** in order to 
26260 66 69 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79  find the underly
26270 69 6e 67 20 63 61 75 73 65 20 6f 66 20 74 68 65  ing cause of the
26280 20 70 72 6f 62 6c 65 6d 2e 20 57 69 74 68 20 74   problem. With t
26290 68 65 20 22 76 32 22 20 70 72 65 70 61 72 65 0a  he "v2" prepare.
262a0 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74  ** interfaces, t
262b0 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 72 65  he underlying re
262c0 61 73 6f 6e 20 66 6f 72 20 74 68 65 20 65 72 72  ason for the err
262d0 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 20 69  or is returned i
262e0 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c  mmediately..** <
262f0 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a  /li>.**.** <li>.
26300 2a 2a 20 5e 49 66 20 74 68 65 20 73 70 65 63 69  ** ^If the speci
26310 66 69 63 20 76 61 6c 75 65 20 62 6f 75 6e 64 20  fic value bound 
26320 74 6f 20 5b 70 61 72 61 6d 65 74 65 72 20 7c 20  to [parameter | 
26330 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 5d 20  host parameter] 
26340 69 6e 20 74 68 65 20 0a 2a 2a 20 57 48 45 52 45  in the .** WHERE
26350 20 63 6c 61 75 73 65 20 6d 69 67 68 74 20 69 6e   clause might in
26360 66 6c 75 65 6e 63 65 20 74 68 65 20 63 68 6f 69  fluence the choi
26370 63 65 20 6f 66 20 71 75 65 72 79 20 70 6c 61 6e  ce of query plan
26380 20 66 6f 72 20 61 20 73 74 61 74 65 6d 65 6e 74   for a statement
26390 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 73 74  ,.** then the st
263a0 61 74 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20  atement will be 
263b0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65  automatically re
263c0 63 6f 6d 70 69 6c 65 64 2c 20 61 73 20 69 66 20  compiled, as if 
263d0 74 68 65 72 65 20 68 61 64 20 62 65 65 6e 20 0a  there had been .
263e0 2a 2a 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e  ** a schema chan
263f0 67 65 2c 20 6f 6e 20 74 68 65 20 66 69 72 73 74  ge, on the first
26400 20 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28    [sqlite3_step(
26410 29 5d 20 63 61 6c 6c 20 66 6f 6c 6c 6f 77 69 6e  )] call followin
26420 67 20 61 6e 79 20 63 68 61 6e 67 65 0a 2a 2a 20  g any change.** 
26430 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
26440 62 69 6e 64 5f 74 65 78 74 20 7c 20 62 69 6e 64  bind_text | bind
26450 69 6e 67 73 5d 20 6f 66 20 74 68 61 74 20 5b 70  ings] of that [p
26460 61 72 61 6d 65 74 65 72 5d 2e 20 0a 2a 2a 20 5e  arameter]. .** ^
26470 54 68 65 20 73 70 65 63 69 66 69 63 20 76 61 6c  The specific val
26480 75 65 20 6f 66 20 57 48 45 52 45 2d 63 6c 61 75  ue of WHERE-clau
26490 73 65 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 6d  se [parameter] m
264a0 69 67 68 74 20 69 6e 66 6c 75 65 6e 63 65 20 74  ight influence t
264b0 68 65 20 0a 2a 2a 20 63 68 6f 69 63 65 20 6f 66  he .** choice of
264c0 20 71 75 65 72 79 20 70 6c 61 6e 20 69 66 20 74   query plan if t
264d0 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  he parameter is 
264e0 74 68 65 20 6c 65 66 74 2d 68 61 6e 64 20 73 69  the left-hand si
264f0 64 65 20 6f 66 20 61 20 5b 4c 49 4b 45 5d 0a 2a  de of a [LIKE].*
26500 2a 20 6f 72 20 5b 47 4c 4f 42 5d 20 6f 70 65 72  * or [GLOB] oper
26510 61 74 6f 72 20 6f 72 20 69 66 20 74 68 65 20 70  ator or if the p
26520 61 72 61 6d 65 74 65 72 20 69 73 20 63 6f 6d 70  arameter is comp
26530 61 72 65 64 20 74 6f 20 61 6e 20 69 6e 64 65 78  ared to an index
26540 65 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 6e 64  ed column.** and
26550 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 45 4e 41   the [SQLITE_ENA
26560 42 4c 45 5f 53 54 41 54 33 5d 20 63 6f 6d 70 69  BLE_STAT3] compi
26570 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69  le-time option i
26580 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 3c 2f  s enabled..** </
26590 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a  li>.** </ol>.*/.
265a0 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70  int sqlite3_prep
265b0 61 72 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  are(.  sqlite3 *
265c0 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f  db,            /
265d0 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c  * Database handl
265e0 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
265f0 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f  r *zSql,       /
26600 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  * SQL statement,
26610 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a   UTF-8 encoded *
26620 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20  /.  int nByte,  
26630 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d              /* M
26640 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
26650 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20   zSql in bytes. 
26660 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d  */.  sqlite3_stm
26670 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20  t **ppStmt,  /* 
26680 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68  OUT: Statement h
26690 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
266a0 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20   char **pzTail  
266b0 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74     /* OUT: Point
266c0 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72  er to unused por
266d0 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a  tion of zSql */.
266e0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70  );.int sqlite3_p
266f0 72 65 70 61 72 65 5f 76 32 28 0a 20 20 73 71 6c  repare_v2(.  sql
26700 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
26710 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
26720 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
26730 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20  st char *zSql,  
26740 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74       /* SQL stat
26750 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63  ement, UTF-8 enc
26760 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42  oded */.  int nB
26770 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20  yte,            
26780 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e    /* Maximum len
26790 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62  gth of zSql in b
267a0 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74  ytes. */.  sqlit
267b0 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74  e3_stmt **ppStmt
267c0 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65  ,  /* OUT: State
267d0 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  ment handle */. 
267e0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a   const char **pz
267f0 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a  Tail     /* OUT:
26800 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73   Pointer to unus
26810 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53  ed portion of zS
26820 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c  ql */.);.int sql
26830 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 0a  ite3_prepare16(.
26840 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
26850 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
26860 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a  abase handle */.
26870 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53    const void *zS
26880 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c  ql,       /* SQL
26890 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d   statement, UTF-
268a0 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20  16 encoded */.  
268b0 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20  int nByte,      
268c0 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d          /* Maxim
268d0 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71  um length of zSq
268e0 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20  l in bytes. */. 
268f0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a   sqlite3_stmt **
26900 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a  ppStmt,  /* OUT:
26910 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c   Statement handl
26920 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  e */.  const voi
26930 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f  d **pzTail     /
26940 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74  * OUT: Pointer t
26950 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e  o unused portion
26960 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69   of zSql */.);.i
26970 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nt sqlite3_prepa
26980 72 65 31 36 5f 76 32 28 0a 20 20 73 71 6c 69 74  re16_v2(.  sqlit
26990 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
269a0 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68     /* Database h
269b0 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
269c0 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20   void *zSql,    
269d0 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d     /* SQL statem
269e0 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f  ent, UTF-16 enco
269f0 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79  ded */.  int nBy
26a00 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  te,             
26a10 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67   /* Maximum leng
26a20 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79  th of zSql in by
26a30 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65  tes. */.  sqlite
26a40 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c  3_stmt **ppStmt,
26a50 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d    /* OUT: Statem
26a60 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ent handle */.  
26a70 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54  const void **pzT
26a80 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20  ail     /* OUT: 
26a90 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65  Pointer to unuse
26aa0 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71  d portion of zSq
26ab0 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  l */.);../*.** C
26ac0 41 50 49 33 52 45 46 3a 20 52 65 74 72 69 65 76  API3REF: Retriev
26ad0 69 6e 67 20 53 74 61 74 65 6d 65 6e 74 20 53 51  ing Statement SQ
26ae0 4c 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e  L.**.** ^This in
26af0 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75  terface can be u
26b00 73 65 64 20 74 6f 20 72 65 74 72 69 65 76 65 20  sed to retrieve 
26b10 61 20 73 61 76 65 64 20 63 6f 70 79 20 6f 66 20  a saved copy of 
26b20 74 68 65 20 6f 72 69 67 69 6e 61 6c 0a 2a 2a 20  the original.** 
26b30 53 51 4c 20 74 65 78 74 20 75 73 65 64 20 74 6f  SQL text used to
26b40 20 63 72 65 61 74 65 20 61 20 5b 70 72 65 70 61   create a [prepa
26b50 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69  red statement] i
26b60 66 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74  f that statement
26b70 20 77 61 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64   was.** compiled
26b80 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73   using either [s
26b90 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
26ba0 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  2()] or [sqlite3
26bb0 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
26bc0 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20  ..*/.const char 
26bd0 2a 73 71 6c 69 74 65 33 5f 73 71 6c 28 73 71 6c  *sqlite3_sql(sql
26be0 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
26bf0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
26c00 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66  EF: Determine If
26c10 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e   An SQL Statemen
26c20 74 20 57 72 69 74 65 73 20 54 68 65 20 44 61 74  t Writes The Dat
26c30 61 62 61 73 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  abase.**.** ^The
26c40 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65   sqlite3_stmt_re
26c50 61 64 6f 6e 6c 79 28 58 29 20 69 6e 74 65 72 66  adonly(X) interf
26c60 61 63 65 20 72 65 74 75 72 6e 73 20 74 72 75 65  ace returns true
26c70 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 0a 2a   (non-zero) if.*
26c80 2a 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68  * and only if th
26c90 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
26ca0 65 6d 65 6e 74 5d 20 58 20 6d 61 6b 65 73 20 6e  ement] X makes n
26cb0 6f 20 64 69 72 65 63 74 20 63 68 61 6e 67 65 73  o direct changes
26cc0 20 74 6f 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65   to.** the conte
26cd0 6e 74 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  nt of the databa
26ce0 73 65 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 4e  se file..**.** N
26cf0 6f 74 65 20 74 68 61 74 20 5b 61 70 70 6c 69 63  ote that [applic
26d00 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
26d10 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 6f 72 0a  L functions] or.
26d20 2a 2a 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c  ** [virtual tabl
26d30 65 73 5d 20 6d 69 67 68 74 20 63 68 61 6e 67 65  es] might change
26d40 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 6e   the database in
26d50 64 69 72 65 63 74 6c 79 20 61 73 20 61 20 73 69  directly as a si
26d60 64 65 20 65 66 66 65 63 74 2e 20 20 0a 2a 2a 20  de effect.  .** 
26d70 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69  ^(For example, i
26d80 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  f an application
26d90 20 64 65 66 69 6e 65 73 20 61 20 66 75 6e 63 74   defines a funct
26da0 69 6f 6e 20 22 65 76 61 6c 28 29 22 20 74 68 61  ion "eval()" tha
26db0 74 20 0a 2a 2a 20 63 61 6c 6c 73 20 5b 73 71 6c  t .** calls [sql
26dc0 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 74 68  ite3_exec()], th
26dd0 65 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  en the following
26de0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 77   SQL statement w
26df0 6f 75 6c 64 0a 2a 2a 20 63 68 61 6e 67 65 20 74  ould.** change t
26e00 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
26e10 20 74 68 72 6f 75 67 68 20 73 69 64 65 2d 65 66   through side-ef
26e20 66 65 63 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  fects:.**.** <bl
26e30 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
26e40 2a 20 20 20 20 53 45 4c 45 43 54 20 65 76 61 6c  *    SELECT eval
26e50 28 27 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 31  ('DELETE FROM t1
26e60 27 29 20 46 52 4f 4d 20 74 32 3b 0a 2a 2a 20 3c  ') FROM t2;.** <
26e70 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
26e80 65 3e 0a 2a 2a 0a 2a 2a 20 42 75 74 20 62 65 63  e>.**.** But bec
26e90 61 75 73 65 20 74 68 65 20 5b 53 45 4c 45 43 54  ause the [SELECT
26ea0 5d 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73  ] statement does
26eb0 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20   not change the 
26ec0 64 61 74 61 62 61 73 65 20 66 69 6c 65 0a 2a 2a  database file.**
26ed0 20 64 69 72 65 63 74 6c 79 2c 20 73 71 6c 69 74   directly, sqlit
26ee0 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79  e3_stmt_readonly
26ef0 28 29 20 77 6f 75 6c 64 20 73 74 69 6c 6c 20 72  () would still r
26f00 65 74 75 72 6e 20 74 72 75 65 2e 29 5e 0a 2a 2a  eturn true.)^.**
26f10 0a 2a 2a 20 5e 54 72 61 6e 73 61 63 74 69 6f 6e  .** ^Transaction
26f20 20 63 6f 6e 74 72 6f 6c 20 73 74 61 74 65 6d 65   control stateme
26f30 6e 74 73 20 73 75 63 68 20 61 73 20 5b 42 45 47  nts such as [BEG
26f40 49 4e 5d 2c 20 5b 43 4f 4d 4d 49 54 5d 2c 20 5b  IN], [COMMIT], [
26f50 52 4f 4c 4c 42 41 43 4b 5d 2c 0a 2a 2a 20 5b 53  ROLLBACK],.** [S
26f60 41 56 45 50 4f 49 4e 54 5d 2c 20 61 6e 64 20 5b  AVEPOINT], and [
26f70 52 45 4c 45 41 53 45 5d 20 63 61 75 73 65 20 73  RELEASE] cause s
26f80 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64  qlite3_stmt_read
26f90 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74 75 72 6e  only() to return
26fa0 20 74 72 75 65 2c 0a 2a 2a 20 73 69 6e 63 65 20   true,.** since 
26fb0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 73 20 74  the statements t
26fc0 68 65 6d 73 65 6c 76 65 73 20 64 6f 20 6e 6f 74  hemselves do not
26fd0 20 61 63 74 75 61 6c 6c 79 20 6d 6f 64 69 66 79   actually modify
26fe0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 62 75   the database bu
26ff0 74 0a 2a 2a 20 72 61 74 68 65 72 20 74 68 65 79  t.** rather they
27000 20 63 6f 6e 74 72 6f 6c 20 74 68 65 20 74 69 6d   control the tim
27010 69 6e 67 20 6f 66 20 77 68 65 6e 20 6f 74 68 65  ing of when othe
27020 72 20 73 74 61 74 65 6d 65 6e 74 73 20 6d 6f 64  r statements mod
27030 69 66 79 20 74 68 65 20 0a 2a 2a 20 64 61 74 61  ify the .** data
27040 62 61 73 65 2e 20 20 5e 54 68 65 20 5b 41 54 54  base.  ^The [ATT
27050 41 43 48 5d 20 61 6e 64 20 5b 44 45 54 41 43 48  ACH] and [DETACH
27060 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 61 6c 73  ] statements als
27070 6f 20 63 61 75 73 65 0a 2a 2a 20 73 71 6c 69 74  o cause.** sqlit
27080 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79  e3_stmt_readonly
27090 28 29 20 74 6f 20 72 65 74 75 72 6e 20 74 72 75  () to return tru
270a0 65 20 73 69 6e 63 65 2c 20 77 68 69 6c 65 20 74  e since, while t
270b0 68 6f 73 65 20 73 74 61 74 65 6d 65 6e 74 73 0a  hose statements.
270c0 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 63 6f  ** change the co
270d0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 66 20 61  nfiguration of a
270e0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
270f0 74 69 6f 6e 2c 20 74 68 65 79 20 64 6f 20 6e 6f  tion, they do no
27100 74 20 6d 61 6b 65 20 0a 2a 2a 20 63 68 61 6e 67  t make .** chang
27110 65 73 20 74 6f 20 74 68 65 20 63 6f 6e 74 65 6e  es to the conten
27120 74 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  t of the databas
27130 65 20 66 69 6c 65 73 20 6f 6e 20 64 69 73 6b 2e  e files on disk.
27140 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
27150 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 73 71  stmt_readonly(sq
27160 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
27170 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
27180 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49  REF: Determine I
27190 66 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61  f A Prepared Sta
271a0 74 65 6d 65 6e 74 20 48 61 73 20 42 65 65 6e 20  tement Has Been 
271b0 52 65 73 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  Reset.**.** ^The
271c0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75   sqlite3_stmt_bu
271d0 73 79 28 53 29 20 69 6e 74 65 72 66 61 63 65 20  sy(S) interface 
271e0 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 6e 6f  returns true (no
271f0 6e 2d 7a 65 72 6f 29 20 69 66 20 74 68 65 0a 2a  n-zero) if the.*
27200 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
27210 65 6d 65 6e 74 5d 20 53 20 68 61 73 20 62 65 65  ement] S has bee
27220 6e 20 73 74 65 70 70 65 64 20 61 74 20 6c 65 61  n stepped at lea
27230 73 74 20 6f 6e 63 65 20 75 73 69 6e 67 20 0a 2a  st once using .*
27240 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  * [sqlite3_step(
27250 53 29 5d 20 62 75 74 20 68 61 73 20 6e 6f 74 20  S)] but has not 
27260 72 75 6e 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f  run to completio
27270 6e 20 61 6e 64 2f 6f 72 20 68 61 73 20 6e 6f 74  n and/or has not
27280 20 0a 2a 2a 20 62 65 65 6e 20 72 65 73 65 74 20   .** been reset 
27290 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72  using [sqlite3_r
272a0 65 73 65 74 28 53 29 5d 2e 20 20 5e 54 68 65 20  eset(S)].  ^The 
272b0 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73  sqlite3_stmt_bus
272c0 79 28 53 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  y(S).** interfac
272d0 65 20 72 65 74 75 72 6e 73 20 66 61 6c 73 65 20  e returns false 
272e0 69 66 20 53 20 69 73 20 61 20 4e 55 4c 4c 20 70  if S is a NULL p
272f0 6f 69 6e 74 65 72 2e 20 20 49 66 20 53 20 69 73  ointer.  If S is
27300 20 6e 6f 74 20 61 20 0a 2a 2a 20 4e 55 4c 4c 20   not a .** NULL 
27310 70 6f 69 6e 74 65 72 20 61 6e 64 20 69 73 20 6e  pointer and is n
27320 6f 74 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ot a pointer to 
27330 61 20 76 61 6c 69 64 20 5b 70 72 65 70 61 72 65  a valid [prepare
27340 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20  d statement].** 
27350 6f 62 6a 65 63 74 2c 20 74 68 65 6e 20 74 68 65  object, then the
27360 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64   behavior is und
27370 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61  efined and proba
27380 62 6c 79 20 75 6e 64 65 73 69 72 61 62 6c 65 2e  bly undesirable.
27390 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65  .**.** This inte
273a0 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65  rface can be use
273b0 64 20 69 6e 20 63 6f 6d 62 69 6e 61 74 69 6f 6e  d in combination
273c0 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73   [sqlite3_next_s
273d0 74 6d 74 28 29 5d 0a 2a 2a 20 74 6f 20 6c 6f 63  tmt()].** to loc
273e0 61 74 65 20 61 6c 6c 20 70 72 65 70 61 72 65 64  ate all prepared
273f0 20 73 74 61 74 65 6d 65 6e 74 73 20 61 73 73 6f   statements asso
27400 63 69 61 74 65 64 20 77 69 74 68 20 61 20 64 61  ciated with a da
27410 74 61 62 61 73 65 20 0a 2a 2a 20 63 6f 6e 6e 65  tabase .** conne
27420 63 74 69 6f 6e 20 74 68 61 74 20 61 72 65 20 69  ction that are i
27430 6e 20 6e 65 65 64 20 6f 66 20 62 65 69 6e 67 20  n need of being 
27440 72 65 73 65 74 2e 20 20 54 68 69 73 20 63 61 6e  reset.  This can
27450 20 62 65 20 75 73 65 64 2c 0a 2a 2a 20 66 6f 72   be used,.** for
27460 20 65 78 61 6d 70 6c 65 2c 20 69 6e 20 64 69 61   example, in dia
27470 67 6e 6f 73 74 69 63 20 72 6f 75 74 69 6e 65 73  gnostic routines
27480 20 74 6f 20 73 65 61 72 63 68 20 66 6f 72 20 70   to search for p
27490 72 65 70 61 72 65 64 20 0a 2a 2a 20 73 74 61 74  repared .** stat
274a0 65 6d 65 6e 74 73 20 74 68 61 74 20 61 72 65 20  ements that are 
274b0 68 6f 6c 64 69 6e 67 20 61 20 74 72 61 6e 73 61  holding a transa
274c0 63 74 69 6f 6e 20 6f 70 65 6e 2e 0a 2a 2f 0a 69  ction open..*/.i
274d0 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  nt sqlite3_stmt_
274e0 62 75 73 79 28 73 71 6c 69 74 65 33 5f 73 74 6d  busy(sqlite3_stm
274f0 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
27500 33 52 45 46 3a 20 44 79 6e 61 6d 69 63 61 6c 6c  3REF: Dynamicall
27510 79 20 54 79 70 65 64 20 56 61 6c 75 65 20 4f 62  y Typed Value Ob
27520 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ject.** KEYWORDS
27530 3a 20 7b 70 72 6f 74 65 63 74 65 64 20 73 71 6c  : {protected sql
27540 69 74 65 33 5f 76 61 6c 75 65 7d 20 7b 75 6e 70  ite3_value} {unp
27550 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
27560 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51  _value}.**.** SQ
27570 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 73 71  Lite uses the sq
27580 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
27590 63 74 20 74 6f 20 72 65 70 72 65 73 65 6e 74 20  ct to represent 
275a0 61 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68  all values.** th
275b0 61 74 20 63 61 6e 20 62 65 20 73 74 6f 72 65 64  at can be stored
275c0 20 69 6e 20 61 20 64 61 74 61 62 61 73 65 20 74   in a database t
275d0 61 62 6c 65 2e 20 53 51 4c 69 74 65 20 75 73 65  able. SQLite use
275e0 73 20 64 79 6e 61 6d 69 63 20 74 79 70 69 6e 67  s dynamic typing
275f0 0a 2a 2a 20 66 6f 72 20 74 68 65 20 76 61 6c 75  .** for the valu
27600 65 73 20 69 74 20 73 74 6f 72 65 73 2e 20 20 5e  es it stores.  ^
27610 56 61 6c 75 65 73 20 73 74 6f 72 65 64 20 69 6e  Values stored in
27620 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
27630 62 6a 65 63 74 73 0a 2a 2a 20 63 61 6e 20 62 65  bjects.** can be
27640 20 69 6e 74 65 67 65 72 73 2c 20 66 6c 6f 61 74   integers, float
27650 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 73  ing point values
27660 2c 20 73 74 72 69 6e 67 73 2c 20 42 4c 4f 42 73  , strings, BLOBs
27670 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  , or NULL..**.**
27680 20 41 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75   An sqlite3_valu
27690 65 20 6f 62 6a 65 63 74 20 6d 61 79 20 62 65 20  e object may be 
276a0 65 69 74 68 65 72 20 22 70 72 6f 74 65 63 74 65  either "protecte
276b0 64 22 20 6f 72 20 22 75 6e 70 72 6f 74 65 63 74  d" or "unprotect
276c0 65 64 22 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74  ed"..** Some int
276d0 65 72 66 61 63 65 73 20 72 65 71 75 69 72 65 20  erfaces require 
276e0 61 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  a protected sqli
276f0 74 65 33 5f 76 61 6c 75 65 2e 20 20 4f 74 68 65  te3_value.  Othe
27700 72 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  r interfaces.** 
27710 77 69 6c 6c 20 61 63 63 65 70 74 20 65 69 74 68  will accept eith
27720 65 72 20 61 20 70 72 6f 74 65 63 74 65 64 20 6f  er a protected o
27730 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64  r an unprotected
27740 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a   sqlite3_value..
27750 2a 2a 20 45 76 65 72 79 20 69 6e 74 65 72 66 61  ** Every interfa
27760 63 65 20 74 68 61 74 20 61 63 63 65 70 74 73 20  ce that accepts 
27770 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 61 72  sqlite3_value ar
27780 67 75 6d 65 6e 74 73 20 73 70 65 63 69 66 69 65  guments specifie
27790 73 0a 2a 2a 20 77 68 65 74 68 65 72 20 6f 72 20  s.** whether or 
277a0 6e 6f 74 20 69 74 20 72 65 71 75 69 72 65 73 20  not it requires 
277b0 61 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  a protected sqli
277c0 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a  te3_value..**.**
277d0 20 54 68 65 20 74 65 72 6d 73 20 22 70 72 6f 74   The terms "prot
277e0 65 63 74 65 64 22 20 61 6e 64 20 22 75 6e 70 72  ected" and "unpr
277f0 6f 74 65 63 74 65 64 22 20 72 65 66 65 72 20 74  otected" refer t
27800 6f 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  o whether or not
27810 0a 2a 2a 20 61 20 6d 75 74 65 78 20 69 73 20 68  .** a mutex is h
27820 65 6c 64 2e 20 20 41 6e 20 69 6e 74 65 72 6e 61  eld.  An interna
27830 6c 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20  l mutex is held 
27840 66 6f 72 20 61 20 70 72 6f 74 65 63 74 65 64 0a  for a protected.
27850 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ** sqlite3_value
27860 20 6f 62 6a 65 63 74 20 62 75 74 20 6e 6f 20 6d   object but no m
27870 75 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72  utex is held for
27880 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 0a   an unprotected.
27890 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ** sqlite3_value
278a0 20 6f 62 6a 65 63 74 2e 20 20 49 66 20 53 51 4c   object.  If SQL
278b0 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
278c0 74 6f 20 62 65 20 73 69 6e 67 6c 65 2d 74 68 72  to be single-thr
278d0 65 61 64 65 64 0a 2a 2a 20 28 77 69 74 68 20 5b  eaded.** (with [
278e0 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
278f0 45 3d 30 5d 20 61 6e 64 20 77 69 74 68 20 5b 73  E=0] and with [s
27900 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66  qlite3_threadsaf
27910 65 28 29 5d 20 72 65 74 75 72 6e 69 6e 67 20 30  e()] returning 0
27920 29 0a 2a 2a 20 6f 72 20 69 66 20 53 51 4c 69 74  ).** or if SQLit
27930 65 20 69 73 20 72 75 6e 20 69 6e 20 6f 6e 65 20  e is run in one 
27940 6f 66 20 72 65 64 75 63 65 64 20 6d 75 74 65 78  of reduced mutex
27950 20 6d 6f 64 65 73 20 0a 2a 2a 20 5b 53 51 4c 49   modes .** [SQLI
27960 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
27970 54 48 52 45 41 44 5d 20 6f 72 20 5b 53 51 4c 49  THREAD] or [SQLI
27980 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54  TE_CONFIG_MULTIT
27990 48 52 45 41 44 5d 0a 2a 2a 20 74 68 65 6e 20 74  HREAD].** then t
279a0 68 65 72 65 20 69 73 20 6e 6f 20 64 69 73 74 69  here is no disti
279b0 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 70  nction between p
279c0 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70  rotected and unp
279d0 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69  rotected.** sqli
279e0 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
279f0 73 20 61 6e 64 20 74 68 65 79 20 63 61 6e 20 62  s and they can b
27a00 65 20 75 73 65 64 20 69 6e 74 65 72 63 68 61 6e  e used interchan
27a10 67 65 61 62 6c 79 2e 20 20 48 6f 77 65 76 65 72  geably.  However
27a20 2c 0a 2a 2a 20 66 6f 72 20 6d 61 78 69 6d 75 6d  ,.** for maximum
27a30 20 63 6f 64 65 20 70 6f 72 74 61 62 69 6c 69 74   code portabilit
27a40 79 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e  y it is recommen
27a50 64 65 64 20 74 68 61 74 20 61 70 70 6c 69 63 61  ded that applica
27a60 74 69 6f 6e 73 0a 2a 2a 20 73 74 69 6c 6c 20 6d  tions.** still m
27a70 61 6b 65 20 74 68 65 20 64 69 73 74 69 6e 63 74  ake the distinct
27a80 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74  ion between prot
27a90 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74  ected and unprot
27aa0 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33  ected.** sqlite3
27ab0 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 65  _value objects e
27ac0 76 65 6e 20 77 68 65 6e 20 6e 6f 74 20 73 74 72  ven when not str
27ad0 69 63 74 6c 79 20 72 65 71 75 69 72 65 64 2e 0a  ictly required..
27ae0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
27af0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
27b00 20 74 68 61 74 20 61 72 65 20 70 61 73 73 65 64   that are passed
27b10 20 61 73 20 70 61 72 61 6d 65 74 65 72 73 20 69   as parameters i
27b20 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65  nto the.** imple
27b30 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 61 70  mentation of [ap
27b40 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
27b50 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d  d SQL functions]
27b60 20 61 72 65 20 70 72 6f 74 65 63 74 65 64 2e 0a   are protected..
27b70 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
27b80 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 72 65 74  value object ret
27b90 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c  urned by.** [sql
27ba0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75  ite3_column_valu
27bb0 65 28 29 5d 20 69 73 20 75 6e 70 72 6f 74 65 63  e()] is unprotec
27bc0 74 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74 65 63  ted..** Unprotec
27bd0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
27be0 65 20 6f 62 6a 65 63 74 73 20 6d 61 79 20 6f 6e  e objects may on
27bf0 6c 79 20 62 65 20 75 73 65 64 20 77 69 74 68 0a  ly be used with.
27c00 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  ** [sqlite3_resu
27c10 6c 74 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20  lt_value()] and 
27c20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61  [sqlite3_bind_va
27c30 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b  lue()]..** The [
27c40 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c  sqlite3_value_bl
27c50 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 76 61 6c  ob | sqlite3_val
27c60 75 65 5f 74 79 70 65 28 29 5d 20 66 61 6d 69 6c  ue_type()] famil
27c70 79 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63  y of.** interfac
27c80 65 73 20 72 65 71 75 69 72 65 20 70 72 6f 74 65  es require prote
27c90 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
27ca0 75 65 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74  ue objects..*/.t
27cb0 79 70 65 64 65 66 20 73 74 72 75 63 74 20 4d 65  ypedef struct Me
27cc0 6d 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 3b  m sqlite3_value;
27cd0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
27ce0 3a 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 43  : SQL Function C
27cf0 6f 6e 74 65 78 74 20 4f 62 6a 65 63 74 0a 2a 2a  ontext Object.**
27d00 0a 2a 2a 20 54 68 65 20 63 6f 6e 74 65 78 74 20  .** The context 
27d10 69 6e 20 77 68 69 63 68 20 61 6e 20 53 51 4c 20  in which an SQL 
27d20 66 75 6e 63 74 69 6f 6e 20 65 78 65 63 75 74 65  function execute
27d30 73 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 61  s is stored in a
27d40 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e  n.** sqlite3_con
27d50 74 65 78 74 20 6f 62 6a 65 63 74 2e 20 20 5e 41  text object.  ^A
27d60 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 73   pointer to an s
27d70 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f  qlite3_context o
27d80 62 6a 65 63 74 0a 2a 2a 20 69 73 20 61 6c 77 61  bject.** is alwa
27d90 79 73 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  ys first paramet
27da0 65 72 20 74 6f 20 5b 61 70 70 6c 69 63 61 74 69  er to [applicati
27db0 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
27dc0 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68  unctions]..** Th
27dd0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
27de0 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
27df0 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  on implementatio
27e00 6e 20 77 69 6c 6c 20 70 61 73 73 20 74 68 69 73  n will pass this
27e10 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 68 72 6f  .** pointer thro
27e20 75 67 68 20 69 6e 74 6f 20 63 61 6c 6c 73 20 74  ugh into calls t
27e30 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  o [sqlite3_resul
27e40 74 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f  t_int | sqlite3_
27e50 72 65 73 75 6c 74 28 29 5d 2c 0a 2a 2a 20 5b 73  result()],.** [s
27e60 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
27e70 5f 63 6f 6e 74 65 78 74 28 29 5d 2c 20 5b 73 71  _context()], [sq
27e80 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28  lite3_user_data(
27e90 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
27ea0 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c  context_db_handl
27eb0 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 67  e()], [sqlite3_g
27ec0 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2c 0a 2a  et_auxdata()],.*
27ed0 2a 20 61 6e 64 2f 6f 72 20 5b 73 71 6c 69 74 65  * and/or [sqlite
27ee0 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 5d  3_set_auxdata()]
27ef0 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
27f00 75 63 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74  uct sqlite3_cont
27f10 65 78 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ext sqlite3_cont
27f20 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ext;../*.** CAPI
27f30 33 52 45 46 3a 20 42 69 6e 64 69 6e 67 20 56 61  3REF: Binding Va
27f40 6c 75 65 73 20 54 6f 20 50 72 65 70 61 72 65 64  lues To Prepared
27f50 20 53 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 4b   Statements.** K
27f60 45 59 57 4f 52 44 53 3a 20 7b 68 6f 73 74 20 70  EYWORDS: {host p
27f70 61 72 61 6d 65 74 65 72 7d 20 7b 68 6f 73 74 20  arameter} {host 
27f80 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 68 6f 73  parameters} {hos
27f90 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65  t parameter name
27fa0 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  }.** KEYWORDS: {
27fb0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 7d 20 7b  SQL parameter} {
27fc0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 7d 20  SQL parameters} 
27fd0 7b 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69  {parameter bindi
27fe0 6e 67 7d 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74  ng}.**.** ^(In t
27ff0 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
28000 20 74 65 78 74 20 69 6e 70 75 74 20 74 6f 20 5b   text input to [
28010 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
28020 76 32 28 29 5d 20 61 6e 64 20 69 74 73 20 76 61  v2()] and its va
28030 72 69 61 6e 74 73 2c 0a 2a 2a 20 6c 69 74 65 72  riants,.** liter
28040 61 6c 73 20 6d 61 79 20 62 65 20 72 65 70 6c 61  als may be repla
28050 63 65 64 20 62 79 20 61 20 5b 70 61 72 61 6d 65  ced by a [parame
28060 74 65 72 5d 20 74 68 61 74 20 6d 61 74 63 68 65  ter] that matche
28070 73 20 6f 6e 65 20 6f 66 20 66 6f 6c 6c 6f 77 69  s one of followi
28080 6e 67 0a 2a 2a 20 74 65 6d 70 6c 61 74 65 73 3a  ng.** templates:
28090 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
280a0 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20  li>  ?.** <li>  
280b0 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56  ?NNN.** <li>  :V
280c0 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 40 56 56 56  VV.** <li>  @VVV
280d0 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56 56 56 0a 2a  .** <li>  $VVV.*
280e0 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e  * </ul>.**.** In
280f0 20 74 68 65 20 74 65 6d 70 6c 61 74 65 73 20 61   the templates a
28100 62 6f 76 65 2c 20 4e 4e 4e 20 72 65 70 72 65 73  bove, NNN repres
28110 65 6e 74 73 20 61 6e 20 69 6e 74 65 67 65 72 20  ents an integer 
28120 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20 61 6e 64 20  literal,.** and 
28130 56 56 56 20 72 65 70 72 65 73 65 6e 74 73 20 61  VVV represents a
28140 6e 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 69  n alphanumeric i
28150 64 65 6e 74 69 66 69 65 72 2e 29 5e 20 20 5e 54  dentifier.)^  ^T
28160 68 65 20 76 61 6c 75 65 73 20 6f 66 20 74 68 65  he values of the
28170 73 65 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73  se.** parameters
28180 20 28 61 6c 73 6f 20 63 61 6c 6c 65 64 20 22 68   (also called "h
28190 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61  ost parameter na
281a0 6d 65 73 22 20 6f 72 20 22 53 51 4c 20 70 61 72  mes" or "SQL par
281b0 61 6d 65 74 65 72 73 22 29 0a 2a 2a 20 63 61 6e  ameters").** can
281c0 20 62 65 20 73 65 74 20 75 73 69 6e 67 20 74 68   be set using th
281d0 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
281e0 28 29 20 72 6f 75 74 69 6e 65 73 20 64 65 66 69  () routines defi
281f0 6e 65 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20  ned here..**.** 
28200 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d  ^The first argum
28210 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ent to the sqlit
28220 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74  e3_bind_*() rout
28230 69 6e 65 73 20 69 73 20 61 6c 77 61 79 73 0a 2a  ines is always.*
28240 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  * a pointer to t
28250 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74  he [sqlite3_stmt
28260 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65  ] object returne
28270 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74  d from.** [sqlit
28280 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
28290 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73   or its variants
282a0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63  ..**.** ^The sec
282b0 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ond argument is 
282c0 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65  the index of the
282d0 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 74   SQL parameter t
282e0 6f 20 62 65 20 73 65 74 2e 0a 2a 2a 20 5e 54 68  o be set..** ^Th
282f0 65 20 6c 65 66 74 6d 6f 73 74 20 53 51 4c 20 70  e leftmost SQL p
28300 61 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20  arameter has an 
28310 69 6e 64 65 78 20 6f 66 20 31 2e 20 20 5e 57 68  index of 1.  ^Wh
28320 65 6e 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65  en the same name
28330 64 0a 2a 2a 20 53 51 4c 20 70 61 72 61 6d 65 74  d.** SQL paramet
28340 65 72 20 69 73 20 75 73 65 64 20 6d 6f 72 65 20  er is used more 
28350 74 68 61 6e 20 6f 6e 63 65 2c 20 73 65 63 6f 6e  than once, secon
28360 64 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74  d and subsequent
28370 0a 2a 2a 20 6f 63 63 75 72 72 65 6e 63 65 73 20  .** occurrences 
28380 68 61 76 65 20 74 68 65 20 73 61 6d 65 20 69 6e  have the same in
28390 64 65 78 20 61 73 20 74 68 65 20 66 69 72 73 74  dex as the first
283a0 20 6f 63 63 75 72 72 65 6e 63 65 2e 0a 2a 2a 20   occurrence..** 
283b0 5e 54 68 65 20 69 6e 64 65 78 20 66 6f 72 20 6e  ^The index for n
283c0 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72 73 20  amed parameters 
283d0 63 61 6e 20 62 65 20 6c 6f 6f 6b 65 64 20 75 70  can be looked up
283e0 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73   using the.** [s
283f0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
28400 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 20 41  meter_index()] A
28410 50 49 20 69 66 20 64 65 73 69 72 65 64 2e 20 20  PI if desired.  
28420 5e 54 68 65 20 69 6e 64 65 78 0a 2a 2a 20 66 6f  ^The index.** fo
28430 72 20 22 3f 4e 4e 4e 22 20 70 61 72 61 6d 65 74  r "?NNN" paramet
28440 65 72 73 20 69 73 20 74 68 65 20 76 61 6c 75 65  ers is the value
28450 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 5e 54 68 65   of NNN..** ^The
28460 20 4e 4e 4e 20 76 61 6c 75 65 20 6d 75 73 74 20   NNN value must 
28470 62 65 20 62 65 74 77 65 65 6e 20 31 20 61 6e 64  be between 1 and
28480 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 69   the [sqlite3_li
28490 6d 69 74 28 29 5d 0a 2a 2a 20 70 61 72 61 6d 65  mit()].** parame
284a0 74 65 72 20 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ter [SQLITE_LIMI
284b0 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45  T_VARIABLE_NUMBE
284c0 52 5d 20 28 64 65 66 61 75 6c 74 20 76 61 6c 75  R] (default valu
284d0 65 3a 20 39 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e  e: 999)..**.** ^
284e0 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  The third argume
284f0 6e 74 20 69 73 20 74 68 65 20 76 61 6c 75 65 20  nt is the value 
28500 74 6f 20 62 69 6e 64 20 74 6f 20 74 68 65 20 70  to bind to the p
28510 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 66  arameter..** ^If
28520 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   the third param
28530 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
28540 62 69 6e 64 5f 74 65 78 74 28 29 20 6f 72 20 73  bind_text() or s
28550 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
28560 31 36 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74  16().** or sqlit
28570 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 20 69  e3_bind_blob() i
28580 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
28590 20 74 68 65 6e 20 74 68 65 20 66 6f 75 72 74 68   then the fourth
285a0 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 73   parameter.** is
285b0 20 69 67 6e 6f 72 65 64 20 61 6e 64 20 74 68 65   ignored and the
285c0 20 65 6e 64 20 72 65 73 75 6c 74 20 69 73 20 74   end result is t
285d0 68 65 20 73 61 6d 65 20 61 73 20 73 71 6c 69 74  he same as sqlit
285e0 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 29 2e 0a  e3_bind_null()..
285f0 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 6f 73 65  **.** ^(In those
28600 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 68   routines that h
28610 61 76 65 20 61 20 66 6f 75 72 74 68 20 61 72 67  ave a fourth arg
28620 75 6d 65 6e 74 2c 20 69 74 73 20 76 61 6c 75 65  ument, its value
28630 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65   is the.** numbe
28640 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
28650 65 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 6f  e parameter.  To
28660 20 62 65 20 63 6c 65 61 72 3a 20 74 68 65 20 76   be clear: the v
28670 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e  alue is the.** n
28680 75 6d 62 65 72 20 6f 66 20 3c 75 3e 62 79 74 65  umber of <u>byte
28690 73 3c 2f 75 3e 20 69 6e 20 74 68 65 20 76 61 6c  s</u> in the val
286a0 75 65 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62  ue, not the numb
286b0 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73  er of characters
286c0 2e 29 5e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66  .)^.** ^If the f
286d0 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
286e0 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  to sqlite3_bind_
286f0 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65  text() or sqlite
28700 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 0a  3_bind_text16().
28710 2a 2a 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20  ** is negative, 
28720 74 68 65 6e 20 74 68 65 20 6c 65 6e 67 74 68 20  then the length 
28730 6f 66 20 74 68 65 20 73 74 72 69 6e 67 20 69 73  of the string is
28740 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  .** the number o
28750 66 20 62 79 74 65 73 20 75 70 20 74 6f 20 74 68  f bytes up to th
28760 65 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72  e first zero ter
28770 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 20 49 66 20 74  minator..** If t
28780 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
28790 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62  ter to sqlite3_b
287a0 69 6e 64 5f 62 6c 6f 62 28 29 20 69 73 20 6e 65  ind_blob() is ne
287b0 67 61 74 69 76 65 2c 20 74 68 65 6e 0a 2a 2a 20  gative, then.** 
287c0 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20  the behavior is 
287d0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66  undefined..** If
287e0 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20   a non-negative 
287f0 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
28800 20 69 73 20 70 72 6f 76 69 64 65 64 20 74 6f 20   is provided to 
28810 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
28820 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65  t().** or sqlite
28830 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20  3_bind_text16() 
28840 74 68 65 6e 20 74 68 61 74 20 70 61 72 61 6d 65  then that parame
28850 74 65 72 20 6d 75 73 74 20 62 65 20 74 68 65 20  ter must be the 
28860 62 79 74 65 20 6f 66 66 73 65 74 0a 2a 2a 20 77  byte offset.** w
28870 68 65 72 65 20 74 68 65 20 4e 55 4c 20 74 65 72  here the NUL ter
28880 6d 69 6e 61 74 6f 72 20 77 6f 75 6c 64 20 6f 63  minator would oc
28890 63 75 72 20 61 73 73 75 6d 69 6e 67 20 74 68 65  cur assuming the
288a0 20 73 74 72 69 6e 67 20 77 65 72 65 20 4e 55 4c   string were NUL
288b0 0a 2a 2a 20 74 65 72 6d 69 6e 61 74 65 64 2e 20  .** terminated. 
288c0 20 49 66 20 61 6e 79 20 4e 55 4c 20 63 68 61 72   If any NUL char
288d0 61 63 74 65 72 73 20 6f 63 63 75 72 20 61 74 20  acters occur at 
288e0 62 79 74 65 20 6f 66 66 73 65 74 73 20 6c 65 73  byte offsets les
288f0 73 20 74 68 61 6e 20 0a 2a 2a 20 74 68 65 20 76  s than .** the v
28900 61 6c 75 65 20 6f 66 20 74 68 65 20 66 6f 75 72  alue of the four
28910 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 68 65  th parameter the
28920 6e 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20  n the resulting 
28930 73 74 72 69 6e 67 20 76 61 6c 75 65 20 77 69 6c  string value wil
28940 6c 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 65 6d 62  l.** contain emb
28950 65 64 64 65 64 20 4e 55 4c 73 2e 20 20 54 68 65  edded NULs.  The
28960 20 72 65 73 75 6c 74 20 6f 66 20 65 78 70 72 65   result of expre
28970 73 73 69 6f 6e 73 20 69 6e 76 6f 6c 76 69 6e 67  ssions involving
28980 20 73 74 72 69 6e 67 73 0a 2a 2a 20 77 69 74 68   strings.** with
28990 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 20 69   embedded NULs i
289a0 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  s undefined..**.
289b0 2a 2a 20 5e 54 68 65 20 66 69 66 74 68 20 61 72  ** ^The fifth ar
289c0 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
289d0 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 2c 20 73  3_bind_blob(), s
289e0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
289f0 28 29 2c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74  (), and.** sqlit
28a00 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29  e3_bind_text16()
28a10 20 69 73 20 61 20 64 65 73 74 72 75 63 74 6f 72   is a destructor
28a20 20 75 73 65 64 20 74 6f 20 64 69 73 70 6f 73 65   used to dispose
28a30 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 0a   of the BLOB or.
28a40 2a 2a 20 73 74 72 69 6e 67 20 61 66 74 65 72 20  ** string after 
28a50 53 51 4c 69 74 65 20 68 61 73 20 66 69 6e 69 73  SQLite has finis
28a60 68 65 64 20 77 69 74 68 20 69 74 2e 20 20 5e 54  hed with it.  ^T
28a70 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 73  he destructor is
28a80 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 6f 20 64 69   called.** to di
28a90 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f  spose of the BLO
28aa0 42 20 6f 72 20 73 74 72 69 6e 67 20 65 76 65 6e  B or string even
28ab0 20 69 66 20 74 68 65 20 63 61 6c 6c 20 74 6f 20   if the call to 
28ac0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
28ad0 62 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  b(),.** sqlite3_
28ae0 62 69 6e 64 5f 74 65 78 74 28 29 2c 20 6f 72 20  bind_text(), or 
28af0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
28b00 74 31 36 28 29 20 66 61 69 6c 73 2e 20 20 0a 2a  t16() fails.  .*
28b10 2a 20 5e 49 66 20 74 68 65 20 66 69 66 74 68 20  * ^If the fifth 
28b20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 74  argument is.** t
28b30 68 65 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65  he special value
28b40 20 5b 53 51 4c 49 54 45 5f 53 54 41 54 49 43 5d   [SQLITE_STATIC]
28b50 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 61 73  , then SQLite as
28b60 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a  sumes that the.*
28b70 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73  * information is
28b80 20 69 6e 20 73 74 61 74 69 63 2c 20 75 6e 6d 61   in static, unma
28b90 6e 61 67 65 64 20 73 70 61 63 65 20 61 6e 64 20  naged space and 
28ba0 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f  does not need to
28bb0 20 62 65 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49   be freed..** ^I
28bc0 66 20 74 68 65 20 66 69 66 74 68 20 61 72 67 75  f the fifth argu
28bd0 6d 65 6e 74 20 68 61 73 20 74 68 65 20 76 61 6c  ment has the val
28be0 75 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53  ue [SQLITE_TRANS
28bf0 49 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53  IENT], then.** S
28c00 51 4c 69 74 65 20 6d 61 6b 65 73 20 69 74 73 20  QLite makes its 
28c10 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79  own private copy
28c20 20 6f 66 20 74 68 65 20 64 61 74 61 20 69 6d 6d   of the data imm
28c30 65 64 69 61 74 65 6c 79 2c 20 62 65 66 6f 72 65  ediately, before
28c40 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f  .** the sqlite3_
28c50 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65  bind_*() routine
28c60 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20   returns..**.** 
28c70 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e  ^The sqlite3_bin
28c80 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 72 6f 75  d_zeroblob() rou
28c90 74 69 6e 65 20 62 69 6e 64 73 20 61 20 42 4c 4f  tine binds a BLO
28ca0 42 20 6f 66 20 6c 65 6e 67 74 68 20 4e 20 74 68  B of length N th
28cb0 61 74 0a 2a 2a 20 69 73 20 66 69 6c 6c 65 64 20  at.** is filled 
28cc0 77 69 74 68 20 7a 65 72 6f 65 73 2e 20 20 5e 41  with zeroes.  ^A
28cd0 20 7a 65 72 6f 62 6c 6f 62 20 75 73 65 73 20 61   zeroblob uses a
28ce0 20 66 69 78 65 64 20 61 6d 6f 75 6e 74 20 6f 66   fixed amount of
28cf0 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73 74   memory.** (just
28d00 20 61 6e 20 69 6e 74 65 67 65 72 20 74 6f 20 68   an integer to h
28d10 6f 6c 64 20 69 74 73 20 73 69 7a 65 29 20 77 68  old its size) wh
28d20 69 6c 65 20 69 74 20 69 73 20 62 65 69 6e 67 20  ile it is being 
28d30 70 72 6f 63 65 73 73 65 64 2e 0a 2a 2a 20 5a 65  processed..** Ze
28d40 72 6f 62 6c 6f 62 73 20 61 72 65 20 69 6e 74 65  roblobs are inte
28d50 6e 64 65 64 20 74 6f 20 73 65 72 76 65 20 61 73  nded to serve as
28d60 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f   placeholders fo
28d70 72 20 42 4c 4f 42 73 20 77 68 6f 73 65 0a 2a 2a  r BLOBs whose.**
28d80 20 63 6f 6e 74 65 6e 74 20 69 73 20 6c 61 74 65   content is late
28d90 72 20 77 72 69 74 74 65 6e 20 75 73 69 6e 67 0a  r written using.
28da0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  ** [sqlite3_blob
28db0 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 65 6d 65 6e  _open | incremen
28dc0 74 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f  tal BLOB I/O] ro
28dd0 75 74 69 6e 65 73 2e 0a 2a 2a 20 5e 41 20 6e 65  utines..** ^A ne
28de0 67 61 74 69 76 65 20 76 61 6c 75 65 20 66 6f 72  gative value for
28df0 20 74 68 65 20 7a 65 72 6f 62 6c 6f 62 20 72 65   the zeroblob re
28e00 73 75 6c 74 73 20 69 6e 20 61 20 7a 65 72 6f 2d  sults in a zero-
28e10 6c 65 6e 67 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a  length BLOB..**.
28e20 2a 2a 20 5e 49 66 20 61 6e 79 20 6f 66 20 74 68  ** ^If any of th
28e30 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
28e40 28 29 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  () routines are 
28e50 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55  called with a NU
28e60 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 66 6f  LL pointer.** fo
28e70 72 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  r the [prepared 
28e80 73 74 61 74 65 6d 65 6e 74 5d 20 6f 72 20 77 69  statement] or wi
28e90 74 68 20 61 20 70 72 65 70 61 72 65 64 20 73 74  th a prepared st
28ea0 61 74 65 6d 65 6e 74 20 66 6f 72 20 77 68 69 63  atement for whic
28eb0 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74  h.** [sqlite3_st
28ec0 65 70 28 29 5d 20 68 61 73 20 62 65 65 6e 20 63  ep()] has been c
28ed0 61 6c 6c 65 64 20 6d 6f 72 65 20 72 65 63 65 6e  alled more recen
28ee0 74 6c 79 20 74 68 61 6e 20 5b 73 71 6c 69 74 65  tly than [sqlite
28ef0 33 5f 72 65 73 65 74 28 29 5d 2c 0a 2a 2a 20 74  3_reset()],.** t
28f00 68 65 6e 20 74 68 65 20 63 61 6c 6c 20 77 69 6c  hen the call wil
28f10 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  l return [SQLITE
28f20 5f 4d 49 53 55 53 45 5d 2e 20 20 49 66 20 61 6e  _MISUSE].  If an
28f30 79 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 28  y sqlite3_bind_(
28f40 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 69 73 20  ).** routine is 
28f50 70 61 73 73 65 64 20 61 20 5b 70 72 65 70 61 72  passed a [prepar
28f60 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68  ed statement] th
28f70 61 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61  at has been fina
28f80 6c 69 7a 65 64 2c 20 74 68 65 0a 2a 2a 20 72 65  lized, the.** re
28f90 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65  sult is undefine
28fa0 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 68  d and probably h
28fb0 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 42  armful..**.** ^B
28fc0 69 6e 64 69 6e 67 73 20 61 72 65 20 6e 6f 74 20  indings are not 
28fd0 63 6c 65 61 72 65 64 20 62 79 20 74 68 65 20 5b  cleared by the [
28fe0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
28ff0 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20 5e 55 6e   routine..** ^Un
29000 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72 73  bound parameters
29010 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64   are interpreted
29020 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   as NULL..**.** 
29030 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e  ^The sqlite3_bin
29040 64 5f 2a 20 72 6f 75 74 69 6e 65 73 20 72 65 74  d_* routines ret
29050 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  urn [SQLITE_OK] 
29060 6f 6e 20 73 75 63 63 65 73 73 20 6f 72 20 61 6e  on success or an
29070 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  .** [error code]
29080 20 69 66 20 61 6e 79 74 68 69 6e 67 20 67 6f 65   if anything goe
29090 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20 5e 5b 53 51  s wrong..** ^[SQ
290a0 4c 49 54 45 5f 52 41 4e 47 45 5d 20 69 73 20 72  LITE_RANGE] is r
290b0 65 74 75 72 6e 65 64 20 69 66 20 74 68 65 20 70  eturned if the p
290c0 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 6e 64 65  arameter.** inde
290d0 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67  x is out of rang
290e0 65 2e 20 20 5e 5b 53 51 4c 49 54 45 5f 4e 4f 4d  e.  ^[SQLITE_NOM
290f0 45 4d 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20  EM] is returned 
29100 69 66 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c  if malloc() fail
29110 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  s..**.** See als
29120 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  o: [sqlite3_bind
29130 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74  _parameter_count
29140 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
29150 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
29160 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71  name()], and [sq
29170 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
29180 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a  eter_index()]..*
29190 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  /.int sqlite3_bi
291a0 6e 64 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f  nd_blob(sqlite3_
291b0 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73  stmt*, int, cons
291c0 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c 20  t void*, int n, 
291d0 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
291e0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
291f0 64 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33  d_double(sqlite3
29200 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f 75  _stmt*, int, dou
29210 62 6c 65 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  ble);.int sqlite
29220 33 5f 62 69 6e 64 5f 69 6e 74 28 73 71 6c 69 74  3_bind_int(sqlit
29230 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69  e3_stmt*, int, i
29240 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  nt);.int sqlite3
29250 5f 62 69 6e 64 5f 69 6e 74 36 34 28 73 71 6c 69  _bind_int64(sqli
29260 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
29270 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a  sqlite3_int64);.
29280 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
29290 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 73 74  _null(sqlite3_st
292a0 6d 74 2a 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73  mt*, int);.int s
292b0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
292c0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
292d0 69 6e 74 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a  int, const char*
292e0 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29  , int n, void(*)
292f0 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71  (void*));.int sq
29300 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31  lite3_bind_text1
29310 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
29320 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64   int, const void
29330 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28  *, int, void(*)(
29340 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c  void*));.int sql
29350 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28  ite3_bind_value(
29360 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
29370 6e 74 2c 20 63 6f 6e 73 74 20 73 71 6c 69 74 65  nt, const sqlite
29380 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73  3_value*);.int s
29390 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f  qlite3_bind_zero
293a0 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d  blob(sqlite3_stm
293b0 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 20 6e 29 3b  t*, int, int n);
293c0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
293d0 3a 20 4e 75 6d 62 65 72 20 4f 66 20 53 51 4c 20  : Number Of SQL 
293e0 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a  Parameters.**.**
293f0 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63   ^This routine c
29400 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 66 69  an be used to fi
29410 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  nd the number of
29420 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73   [SQL parameters
29430 5d 0a 2a 2a 20 69 6e 20 61 20 5b 70 72 65 70 61  ].** in a [prepa
29440 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20  red statement]. 
29450 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20   SQL parameters 
29460 61 72 65 20 74 6f 6b 65 6e 73 20 6f 66 20 74 68  are tokens of th
29470 65 0a 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c 20 22  e.** form "?", "
29480 3f 4e 4e 4e 22 2c 20 22 3a 41 41 41 22 2c 20 22  ?NNN", ":AAA", "
29490 24 41 41 41 22 2c 20 6f 72 20 22 40 41 41 41 22  $AAA", or "@AAA"
294a0 20 74 68 61 74 20 73 65 72 76 65 20 61 73 0a 2a   that serve as.*
294b0 2a 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66  * placeholders f
294c0 6f 72 20 76 61 6c 75 65 73 20 74 68 61 74 20 61  or values that a
294d0 72 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  re [sqlite3_bind
294e0 5f 62 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a  _blob | bound].*
294f0 2a 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74  * to the paramet
29500 65 72 73 20 61 74 20 61 20 6c 61 74 65 72 20 74  ers at a later t
29510 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69  ime..**.** ^(Thi
29520 73 20 72 6f 75 74 69 6e 65 20 61 63 74 75 61 6c  s routine actual
29530 6c 79 20 72 65 74 75 72 6e 73 20 74 68 65 20 69  ly returns the i
29540 6e 64 65 78 20 6f 66 20 74 68 65 20 6c 61 72 67  ndex of the larg
29550 65 73 74 20 28 72 69 67 68 74 6d 6f 73 74 29 0a  est (rightmost).
29560 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 20 46 6f  ** parameter. Fo
29570 72 20 61 6c 6c 20 66 6f 72 6d 73 20 65 78 63 65  r all forms exce
29580 70 74 20 3f 4e 4e 4e 2c 20 74 68 69 73 20 77 69  pt ?NNN, this wi
29590 6c 6c 20 63 6f 72 72 65 73 70 6f 6e 64 20 74 6f  ll correspond to
295a0 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f   the.** number o
295b0 66 20 75 6e 69 71 75 65 20 70 61 72 61 6d 65 74  f unique paramet
295c0 65 72 73 2e 20 20 49 66 20 70 61 72 61 6d 65 74  ers.  If paramet
295d0 65 72 73 20 6f 66 20 74 68 65 20 3f 4e 4e 4e 20  ers of the ?NNN 
295e0 66 6f 72 6d 20 61 72 65 20 75 73 65 64 2c 0a 2a  form are used,.*
295f0 2a 20 74 68 65 72 65 20 6d 61 79 20 62 65 20 67  * there may be g
29600 61 70 73 20 69 6e 20 74 68 65 20 6c 69 73 74 2e  aps in the list.
29610 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  )^.**.** See als
29620 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  o: [sqlite3_bind
29630 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69  _blob|sqlite3_bi
29640 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  nd()],.** [sqlit
29650 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
29660 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a  r_name()], and.*
29670 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
29680 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28  parameter_index(
29690 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  )]..*/.int sqlit
296a0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
296b0 72 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f  r_count(sqlite3_
296c0 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  stmt*);../*.** C
296d0 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66  API3REF: Name Of
296e0 20 41 20 48 6f 73 74 20 50 61 72 61 6d 65 74 65   A Host Paramete
296f0 72 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  r.**.** ^The sql
29700 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
29710 74 65 72 5f 6e 61 6d 65 28 50 2c 4e 29 20 69 6e  ter_name(P,N) in
29720 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a  terface returns.
29730 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  ** the name of t
29740 68 65 20 4e 2d 74 68 20 5b 53 51 4c 20 70 61 72  he N-th [SQL par
29750 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 65 20 5b  ameter] in the [
29760 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
29770 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 28 53 51 4c 20  nt] P..** ^(SQL 
29780 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68  parameters of th
29790 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20 6f 72  e form "?NNN" or
297a0 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41   ":AAA" or "@AAA
297b0 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 68  " or "$AAA".** h
297c0 61 76 65 20 61 20 6e 61 6d 65 20 77 68 69 63 68  ave a name which
297d0 20 69 73 20 74 68 65 20 73 74 72 69 6e 67 20 22   is the string "
297e0 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20  ?NNN" or ":AAA" 
297f0 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22 24 41  or "@AAA" or "$A
29800 41 41 22 0a 2a 2a 20 72 65 73 70 65 63 74 69 76  AA".** respectiv
29810 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68 65 72  ely..** In other
29820 20 77 6f 72 64 73 2c 20 74 68 65 20 69 6e 69 74   words, the init
29830 69 61 6c 20 22 3a 22 20 6f 72 20 22 24 22 20 6f  ial ":" or "$" o
29840 72 20 22 40 22 20 6f 72 20 22 3f 22 0a 2a 2a 20  r "@" or "?".** 
29850 69 73 20 69 6e 63 6c 75 64 65 64 20 61 73 20 70  is included as p
29860 61 72 74 20 6f 66 20 74 68 65 20 6e 61 6d 65 2e  art of the name.
29870 29 5e 0a 2a 2a 20 5e 50 61 72 61 6d 65 74 65 72  )^.** ^Parameter
29880 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f  s of the form "?
29890 22 20 77 69 74 68 6f 75 74 20 61 20 66 6f 6c 6c  " without a foll
298a0 6f 77 69 6e 67 20 69 6e 74 65 67 65 72 20 68 61  owing integer ha
298b0 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a 20 61 6e  ve no name.** an
298c0 64 20 61 72 65 20 72 65 66 65 72 72 65 64 20 74  d are referred t
298d0 6f 20 61 73 20 22 6e 61 6d 65 6c 65 73 73 22 20  o as "nameless" 
298e0 6f 72 20 22 61 6e 6f 6e 79 6d 6f 75 73 20 70 61  or "anonymous pa
298f0 72 61 6d 65 74 65 72 73 22 2e 0a 2a 2a 0a 2a 2a  rameters"..**.**
29900 20 5e 54 68 65 20 66 69 72 73 74 20 68 6f 73 74   ^The first host
29910 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 61   parameter has a
29920 6e 20 69 6e 64 65 78 20 6f 66 20 31 2c 20 6e 6f  n index of 1, no
29930 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  t 0..**.** ^If t
29940 68 65 20 76 61 6c 75 65 20 4e 20 69 73 20 6f 75  he value N is ou
29950 74 20 6f 66 20 72 61 6e 67 65 20 6f 72 20 69 66  t of range or if
29960 20 74 68 65 20 4e 2d 74 68 20 70 61 72 61 6d 65   the N-th parame
29970 74 65 72 20 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65  ter is.** namele
29980 73 73 2c 20 74 68 65 6e 20 4e 55 4c 4c 20 69 73  ss, then NULL is
29990 20 72 65 74 75 72 6e 65 64 2e 20 20 5e 54 68 65   returned.  ^The
299a0 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67   returned string
299b0 20 69 73 0a 2a 2a 20 61 6c 77 61 79 73 20 69 6e   is.** always in
299c0 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20   UTF-8 encoding 
299d0 65 76 65 6e 20 69 66 20 74 68 65 20 6e 61 6d 65  even if the name
299e0 64 20 70 61 72 61 6d 65 74 65 72 20 77 61 73 0a  d parameter was.
299f0 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c 79 20 73 70  ** originally sp
29a00 65 63 69 66 69 65 64 20 61 73 20 55 54 46 2d 31  ecified as UTF-1
29a10 36 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72  6 in [sqlite3_pr
29a20 65 70 61 72 65 31 36 28 29 5d 20 6f 72 0a 2a 2a  epare16()] or.**
29a30 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
29a40 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a  e16_v2()]..**.**
29a50 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
29a60 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71  te3_bind_blob|sq
29a70 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a  lite3_bind()],.*
29a80 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
29a90 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28  parameter_count(
29aa0 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  )], and.** [sqli
29ab0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
29ac0 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a  er_index()]..*/.
29ad0 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
29ae0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
29af0 65 72 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f  er_name(sqlite3_
29b00 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a  stmt*, int);../*
29b10 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e  .** CAPI3REF: In
29b20 64 65 78 20 4f 66 20 41 20 50 61 72 61 6d 65 74  dex Of A Paramet
29b30 65 72 20 57 69 74 68 20 41 20 47 69 76 65 6e 20  er With A Given 
29b40 4e 61 6d 65 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75  Name.**.** ^Retu
29b50 72 6e 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20  rn the index of 
29b60 61 6e 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  an SQL parameter
29b70 20 67 69 76 65 6e 20 69 74 73 20 6e 61 6d 65 2e   given its name.
29b80 20 20 5e 54 68 65 0a 2a 2a 20 69 6e 64 65 78 20    ^The.** index 
29b90 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 69  value returned i
29ba0 73 20 73 75 69 74 61 62 6c 65 20 66 6f 72 20 75  s suitable for u
29bb0 73 65 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  se as the second
29bc0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f  .** parameter to
29bd0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
29be0 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64  lob|sqlite3_bind
29bf0 28 29 5d 2e 20 20 5e 41 20 7a 65 72 6f 0a 2a 2a  ()].  ^A zero.**
29c00 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20   is returned if 
29c10 6e 6f 20 6d 61 74 63 68 69 6e 67 20 70 61 72 61  no matching para
29c20 6d 65 74 65 72 20 69 73 20 66 6f 75 6e 64 2e 20  meter is found. 
29c30 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72 0a   ^The parameter.
29c40 2a 2a 20 6e 61 6d 65 20 6d 75 73 74 20 62 65 20  ** name must be 
29c50 67 69 76 65 6e 20 69 6e 20 55 54 46 2d 38 20 65  given in UTF-8 e
29c60 76 65 6e 20 69 66 20 74 68 65 20 6f 72 69 67 69  ven if the origi
29c70 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a  nal statement.**
29c80 20 77 61 73 20 70 72 65 70 61 72 65 64 20 66 72   was prepared fr
29c90 6f 6d 20 55 54 46 2d 31 36 20 74 65 78 74 20 75  om UTF-16 text u
29ca0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72  sing [sqlite3_pr
29cb0 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a  epare16_v2()]..*
29cc0 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
29cd0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
29ce0 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29  b|sqlite3_bind()
29cf0 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  ],.** [sqlite3_b
29d00 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f  ind_parameter_co
29d10 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b  unt()], and.** [
29d20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
29d30 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e  ameter_index()].
29d40 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
29d50 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69  bind_parameter_i
29d60 6e 64 65 78 28 73 71 6c 69 74 65 33 5f 73 74 6d  ndex(sqlite3_stm
29d70 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  t*, const char *
29d80 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  zName);../*.** C
29d90 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 41  API3REF: Reset A
29da0 6c 6c 20 42 69 6e 64 69 6e 67 73 20 4f 6e 20 41  ll Bindings On A
29db0 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d   Prepared Statem
29dc0 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 74 72  ent.**.** ^Contr
29dd0 61 72 79 20 74 6f 20 74 68 65 20 69 6e 74 75 69  ary to the intui
29de0 74 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b 73  tion of many, [s
29df0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
29e00 64 6f 65 73 20 6e 6f 74 20 72 65 73 65 74 0a 2a  does not reset.*
29e10 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62  * the [sqlite3_b
29e20 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 69 6e 64 69  ind_blob | bindi
29e30 6e 67 73 5d 20 6f 6e 20 61 20 5b 70 72 65 70 61  ngs] on a [prepa
29e40 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a  red statement]..
29e50 2a 2a 20 5e 55 73 65 20 74 68 69 73 20 72 6f 75  ** ^Use this rou
29e60 74 69 6e 65 20 74 6f 20 72 65 73 65 74 20 61 6c  tine to reset al
29e70 6c 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72  l host parameter
29e80 73 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e  s to NULL..*/.in
29e90 74 20 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f  t sqlite3_clear_
29ea0 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33  bindings(sqlite3
29eb0 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  _stmt*);../*.** 
29ec0 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72  CAPI3REF: Number
29ed0 20 4f 66 20 43 6f 6c 75 6d 6e 73 20 49 6e 20 41   Of Columns In A
29ee0 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a   Result Set.**.*
29ef0 2a 20 5e 52 65 74 75 72 6e 20 74 68 65 20 6e 75  * ^Return the nu
29f00 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
29f10 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  in the result se
29f20 74 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  t returned by th
29f30 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  e.** [prepared s
29f40 74 61 74 65 6d 65 6e 74 5d 2e 20 5e 54 68 69 73  tatement]. ^This
29f50 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
29f60 20 30 20 69 66 20 70 53 74 6d 74 20 69 73 20 61   0 if pStmt is a
29f70 6e 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65  n SQL.** stateme
29f80 6e 74 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74  nt that does not
29f90 20 72 65 74 75 72 6e 20 64 61 74 61 20 28 66 6f   return data (fo
29fa0 72 20 65 78 61 6d 70 6c 65 20 61 6e 20 5b 55 50  r example an [UP
29fb0 44 41 54 45 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65  DATE])..**.** Se
29fc0 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
29fd0 5f 64 61 74 61 5f 63 6f 75 6e 74 28 29 5d 0a 2a  _data_count()].*
29fe0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  /.int sqlite3_co
29ff0 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c 69 74  lumn_count(sqlit
2a000 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
2a010 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2a020 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20 49  : Column Names I
2a030 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a  n A Result Set.*
2a040 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74  *.** ^These rout
2a050 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20  ines return the 
2a060 6e 61 6d 65 20 61 73 73 69 67 6e 65 64 20 74 6f  name assigned to
2a070 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 63 6f   a particular co
2a080 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 72  lumn.** in the r
2a090 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b  esult set of a [
2a0a0 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e  SELECT] statemen
2a0b0 74 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33  t.  ^The sqlite3
2a0c0 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a  _column_name().*
2a0d0 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  * interface retu
2a0e0 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
2a0f0 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
2a100 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a  ed UTF-8 string.
2a110 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  ** and sqlite3_c
2a120 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 72  olumn_name16() r
2a130 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
2a140 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69   to a zero-termi
2a150 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20  nated.** UTF-16 
2a160 73 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 66 69  string.  ^The fi
2a170 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73  rst parameter is
2a180 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
2a190 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61  tatement].** tha
2a1a0 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65  t implements the
2a1b0 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d   [SELECT] statem
2a1c0 65 6e 74 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64  ent. ^The second
2a1d0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
2a1e0 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62  e.** column numb
2a1f0 65 72 2e 20 20 5e 54 68 65 20 6c 65 66 74 6d 6f  er.  ^The leftmo
2a200 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d  st column is num
2a210 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ber 0..**.** ^Th
2a220 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e  e returned strin
2a230 67 20 70 6f 69 6e 74 65 72 20 69 73 20 76 61 6c  g pointer is val
2a240 69 64 20 75 6e 74 69 6c 20 65 69 74 68 65 72 20  id until either 
2a250 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
2a260 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20 64  atement].** is d
2a270 65 73 74 72 6f 79 65 64 20 62 79 20 5b 73 71 6c  estroyed by [sql
2a280 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
2a290 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 74   or until the st
2a2a0 61 74 65 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d  atement is autom
2a2b0 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72  atically.** repr
2a2c0 65 70 61 72 65 64 20 62 79 20 74 68 65 20 66 69  epared by the fi
2a2d0 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  rst call to [sql
2a2e0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 66 6f 72  ite3_step()] for
2a2f0 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 75   a particular ru
2a300 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68  n.** or until th
2a310 65 20 6e 65 78 74 20 63 61 6c 6c 20 74 6f 0a 2a  e next call to.*
2a320 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  * sqlite3_column
2a330 5f 6e 61 6d 65 28 29 20 6f 72 20 73 71 6c 69 74  _name() or sqlit
2a340 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36  e3_column_name16
2a350 28 29 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 63  () on the same c
2a360 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  olumn..**.** ^If
2a370 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
2a380 29 20 66 61 69 6c 73 20 64 75 72 69 6e 67 20 74  ) fails during t
2a390 68 65 20 70 72 6f 63 65 73 73 69 6e 67 20 6f 66  he processing of
2a3a0 20 65 69 74 68 65 72 20 72 6f 75 74 69 6e 65 0a   either routine.
2a3b0 2a 2a 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20  ** (for example 
2a3c0 64 75 72 69 6e 67 20 61 20 63 6f 6e 76 65 72 73  during a convers
2a3d0 69 6f 6e 20 66 72 6f 6d 20 55 54 46 2d 38 20 74  ion from UTF-8 t
2a3e0 6f 20 55 54 46 2d 31 36 29 20 74 68 65 6e 20 61  o UTF-16) then a
2a3f0 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  .** NULL pointer
2a400 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
2a410 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66  .** ^The name of
2a420 20 61 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e   a result column
2a430 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66   is the value of
2a440 20 74 68 65 20 22 41 53 22 20 63 6c 61 75 73 65   the "AS" clause
2a450 20 66 6f 72 0a 2a 2a 20 74 68 61 74 20 63 6f 6c   for.** that col
2a460 75 6d 6e 2c 20 69 66 20 74 68 65 72 65 20 69 73  umn, if there is
2a470 20 61 6e 20 41 53 20 63 6c 61 75 73 65 2e 20 20   an AS clause.  
2a480 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20 41  If there is no A
2a490 53 20 63 6c 61 75 73 65 0a 2a 2a 20 74 68 65 6e  S clause.** then
2a4a0 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
2a4b0 20 63 6f 6c 75 6d 6e 20 69 73 20 75 6e 73 70 65   column is unspe
2a4c0 63 69 66 69 65 64 20 61 6e 64 20 6d 61 79 20 63  cified and may c
2a4d0 68 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e  hange from.** on
2a4e0 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c  e release of SQL
2a4f0 69 74 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e  ite to the next.
2a500 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  .*/.const char *
2a510 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
2a520 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
2a530 2a 2c 20 69 6e 74 20 4e 29 3b 0a 63 6f 6e 73 74  *, int N);.const
2a540 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
2a550 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 73 71 6c  olumn_name16(sql
2a560 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
2a570 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  N);../*.** CAPI3
2a580 52 45 46 3a 20 53 6f 75 72 63 65 20 4f 66 20 44  REF: Source Of D
2a590 61 74 61 20 49 6e 20 41 20 51 75 65 72 79 20 52  ata In A Query R
2a5a0 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  esult.**.** ^The
2a5b0 73 65 20 72 6f 75 74 69 6e 65 73 20 70 72 6f 76  se routines prov
2a5c0 69 64 65 20 61 20 6d 65 61 6e 73 20 74 6f 20 64  ide a means to d
2a5d0 65 74 65 72 6d 69 6e 65 20 74 68 65 20 64 61 74  etermine the dat
2a5e0 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e  abase, table, an
2a5f0 64 0a 2a 2a 20 74 61 62 6c 65 20 63 6f 6c 75 6d  d.** table colum
2a600 6e 20 74 68 61 74 20 69 73 20 74 68 65 20 6f 72  n that is the or
2a610 69 67 69 6e 20 6f 66 20 61 20 70 61 72 74 69 63  igin of a partic
2a620 75 6c 61 72 20 72 65 73 75 6c 74 20 63 6f 6c 75  ular result colu
2a630 6d 6e 20 69 6e 0a 2a 2a 20 5b 53 45 4c 45 43 54  mn in.** [SELECT
2a640 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20  ] statement..** 
2a650 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65  ^The name of the
2a660 20 64 61 74 61 62 61 73 65 20 6f 72 20 74 61 62   database or tab
2a670 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 20 63 61 6e  le or column can
2a680 20 62 65 20 72 65 74 75 72 6e 65 64 20 61 73 0a   be returned as.
2a690 2a 2a 20 65 69 74 68 65 72 20 61 20 55 54 46 2d  ** either a UTF-
2a6a0 38 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72 69  8 or UTF-16 stri
2a6b0 6e 67 2e 20 20 5e 54 68 65 20 5f 64 61 74 61 62  ng.  ^The _datab
2a6c0 61 73 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65  ase_ routines re
2a6d0 74 75 72 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61  turn.** the data
2a6e0 62 61 73 65 20 6e 61 6d 65 2c 20 74 68 65 20 5f  base name, the _
2a6f0 74 61 62 6c 65 5f 20 72 6f 75 74 69 6e 65 73 20  table_ routines 
2a700 72 65 74 75 72 6e 20 74 68 65 20 74 61 62 6c 65  return the table
2a710 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74 68   name, and.** th
2a720 65 20 6f 72 69 67 69 6e 5f 20 72 6f 75 74 69 6e  e origin_ routin
2a730 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 63 6f  es return the co
2a740 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 54  lumn name..** ^T
2a750 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69  he returned stri
2a760 6e 67 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69  ng is valid unti
2a770 6c 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  l the [prepared 
2a780 73 74 61 74 65 6d 65 6e 74 5d 20 69 73 20 64 65  statement] is de
2a790 73 74 72 6f 79 65 64 0a 2a 2a 20 75 73 69 6e 67  stroyed.** using
2a7a0 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
2a7b0 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74  ze()] or until t
2a7c0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
2a7d0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a  automatically.**
2a7e0 20 72 65 70 72 65 70 61 72 65 64 20 62 79 20 74   reprepared by t
2a7f0 68 65 20 66 69 72 73 74 20 63 61 6c 6c 20 74 6f  he first call to
2a800 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
2a810 5d 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c  ] for a particul
2a820 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74  ar run.** or unt
2a830 69 6c 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f  il the same info
2a840 72 6d 61 74 69 6f 6e 20 69 73 20 72 65 71 75 65  rmation is reque
2a850 73 74 65 64 0a 2a 2a 20 61 67 61 69 6e 20 69 6e  sted.** again in
2a860 20 61 20 64 69 66 66 65 72 65 6e 74 20 65 6e 63   a different enc
2a870 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  oding..**.** ^Th
2a880 65 20 6e 61 6d 65 73 20 72 65 74 75 72 6e 65 64  e names returned
2a890 20 61 72 65 20 74 68 65 20 6f 72 69 67 69 6e 61   are the origina
2a8a0 6c 20 75 6e 2d 61 6c 69 61 73 65 64 20 6e 61 6d  l un-aliased nam
2a8b0 65 73 20 6f 66 20 74 68 65 0a 2a 2a 20 64 61 74  es of the.** dat
2a8c0 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e  abase, table, an
2a8d0 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20  d column..**.** 
2a8e0 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d  ^The first argum
2a8f0 65 6e 74 20 74 6f 20 74 68 65 73 65 20 69 6e 74  ent to these int
2a900 65 72 66 61 63 65 73 20 69 73 20 61 20 5b 70 72  erfaces is a [pr
2a910 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2a920 5d 2e 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e  ]..** ^These fun
2a930 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 69 6e  ctions return in
2a940 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20  formation about 
2a950 74 68 65 20 4e 74 68 20 72 65 73 75 6c 74 20 63  the Nth result c
2a960 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62  olumn returned b
2a970 79 0a 2a 2a 20 74 68 65 20 73 74 61 74 65 6d 65  y.** the stateme
2a980 6e 74 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74  nt, where N is t
2a990 68 65 20 73 65 63 6f 6e 64 20 66 75 6e 63 74 69  he second functi
2a9a0 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20  on argument..** 
2a9b0 5e 54 68 65 20 6c 65 66 74 2d 6d 6f 73 74 20 63  ^The left-most c
2a9c0 6f 6c 75 6d 6e 20 69 73 20 63 6f 6c 75 6d 6e 20  olumn is column 
2a9d0 30 20 66 6f 72 20 74 68 65 73 65 20 72 6f 75 74  0 for these rout
2a9e0 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ines..**.** ^If 
2a9f0 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72  the Nth column r
2aa00 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 20 73  eturned by the s
2aa10 74 61 74 65 6d 65 6e 74 20 69 73 20 61 6e 20 65  tatement is an e
2aa20 78 70 72 65 73 73 69 6f 6e 20 6f 72 0a 2a 2a 20  xpression or.** 
2aa30 73 75 62 71 75 65 72 79 20 61 6e 64 20 69 73 20  subquery and is 
2aa40 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e 20 76 61 6c  not a column val
2aa50 75 65 2c 20 74 68 65 6e 20 61 6c 6c 20 6f 66 20  ue, then all of 
2aa60 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  these functions 
2aa70 72 65 74 75 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20  return.** NULL. 
2aa80 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 20   ^These routine 
2aa90 6d 69 67 68 74 20 61 6c 73 6f 20 72 65 74 75 72  might also retur
2aaa0 6e 20 4e 55 4c 4c 20 69 66 20 61 20 6d 65 6d 6f  n NULL if a memo
2aab0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72  ry allocation er
2aac0 72 6f 72 0a 2a 2a 20 6f 63 63 75 72 73 2e 20 20  ror.** occurs.  
2aad0 5e 4f 74 68 65 72 77 69 73 65 2c 20 74 68 65 79  ^Otherwise, they
2aae0 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65   return the name
2aaf0 20 6f 66 20 74 68 65 20 61 74 74 61 63 68 65 64   of the attached
2ab00 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65   database, table
2ab10 2c 0a 2a 2a 20 6f 72 20 63 6f 6c 75 6d 6e 20 74  ,.** or column t
2ab20 68 61 74 20 71 75 65 72 79 20 72 65 73 75 6c 74  hat query result
2ab30 20 63 6f 6c 75 6d 6e 20 77 61 73 20 65 78 74 72   column was extr
2ab40 61 63 74 65 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a  acted from..**.*
2ab50 2a 20 5e 41 73 20 77 69 74 68 20 61 6c 6c 20 6f  * ^As with all o
2ab60 74 68 65 72 20 53 51 4c 69 74 65 20 41 50 49 73  ther SQLite APIs
2ab70 2c 20 74 68 6f 73 65 20 77 68 6f 73 65 20 6e 61  , those whose na
2ab80 6d 65 73 20 65 6e 64 20 77 69 74 68 20 22 31 36  mes end with "16
2ab90 22 20 72 65 74 75 72 6e 0a 2a 2a 20 55 54 46 2d  " return.** UTF-
2aba0 31 36 20 65 6e 63 6f 64 65 64 20 73 74 72 69 6e  16 encoded strin
2abb0 67 73 20 61 6e 64 20 74 68 65 20 6f 74 68 65 72  gs and the other
2abc0 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72   functions retur
2abd0 6e 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 5e  n UTF-8..**.** ^
2abe0 54 68 65 73 65 20 41 50 49 73 20 61 72 65 20 6f  These APIs are o
2abf0 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66  nly available if
2ac00 20 74 68 65 20 6c 69 62 72 61 72 79 20 77 61 73   the library was
2ac10 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74   compiled with t
2ac20 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e  he.** [SQLITE_EN
2ac30 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41  ABLE_COLUMN_META
2ac40 44 41 54 41 5d 20 43 2d 70 72 65 70 72 6f 63 65  DATA] C-preproce
2ac50 73 73 6f 72 20 73 79 6d 62 6f 6c 2e 0a 2a 2a 0a  ssor symbol..**.
2ac60 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72  ** If two or mor
2ac70 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f  e threads call o
2ac80 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68  ne or more of th
2ac90 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 67 61  ese routines aga
2aca0 69 6e 73 74 20 74 68 65 20 73 61 6d 65 0a 2a 2a  inst the same.**
2acb0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
2acc0 65 6e 74 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 61  ent and column a
2acd0 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20  t the same time 
2ace0 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73  then the results
2acf0 20 61 72 65 0a 2a 2a 20 75 6e 64 65 66 69 6e 65   are.** undefine
2ad00 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20  d..**.** If two 
2ad10 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20  or more threads 
2ad20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  call one or more
2ad30 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
2ad40 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d  umn_database_nam
2ad50 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74 61 64  e | column metad
2ad60 61 74 61 20 69 6e 74 65 72 66 61 63 65 73 5d 0a  ata interfaces].
2ad70 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20  ** for the same 
2ad80 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2ad90 65 6e 74 5d 20 61 6e 64 20 72 65 73 75 6c 74 20  ent] and result 
2ada0 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 74 20 74 68 65  column.** at the
2adb0 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20   same time then 
2adc0 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20  the results are 
2add0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 63 6f  undefined..*/.co
2ade0 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
2adf0 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73  3_column_databas
2ae00 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73  e_name(sqlite3_s
2ae10 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74  tmt*,int);.const
2ae20 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
2ae30 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e  olumn_database_n
2ae40 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ame16(sqlite3_st
2ae50 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20  mt*,int);.const 
2ae60 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
2ae70 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28  lumn_table_name(
2ae80 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
2ae90 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  t);.const void *
2aea0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2aeb0 61 62 6c 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69  able_name16(sqli
2aec0 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
2aed0 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
2aee0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69  te3_column_origi
2aef0 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73  n_name(sqlite3_s
2af00 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74  tmt*,int);.const
2af10 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
2af20 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d  olumn_origin_nam
2af30 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  e16(sqlite3_stmt
2af40 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  *,int);../*.** C
2af50 41 50 49 33 52 45 46 3a 20 44 65 63 6c 61 72 65  API3REF: Declare
2af60 64 20 44 61 74 61 74 79 70 65 20 4f 66 20 41 20  d Datatype Of A 
2af70 51 75 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a 0a  Query Result.**.
2af80 2a 2a 20 5e 28 54 68 65 20 66 69 72 73 74 20 70  ** ^(The first p
2af90 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 5b 70  arameter is a [p
2afa0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2afb0 74 5d 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20 73  t]..** If this s
2afc0 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 53  tatement is a [S
2afd0 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74  ELECT] statement
2afe0 20 61 6e 64 20 74 68 65 20 4e 74 68 20 63 6f 6c   and the Nth col
2aff0 75 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65  umn of the.** re
2b000 74 75 72 6e 65 64 20 72 65 73 75 6c 74 20 73 65  turned result se
2b010 74 20 6f 66 20 74 68 61 74 20 5b 53 45 4c 45 43  t of that [SELEC
2b020 54 5d 20 69 73 20 61 20 74 61 62 6c 65 20 63 6f  T] is a table co
2b030 6c 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20  lumn (not an.** 
2b040 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75  expression or su
2b050 62 71 75 65 72 79 29 20 74 68 65 6e 20 74 68 65  bquery) then the
2b060 20 64 65 63 6c 61 72 65 64 20 74 79 70 65 20 6f   declared type o
2b070 66 20 74 68 65 20 74 61 62 6c 65 0a 2a 2a 20 63  f the table.** c
2b080 6f 6c 75 6d 6e 20 69 73 20 72 65 74 75 72 6e 65  olumn is returne
2b090 64 2e 29 5e 20 20 5e 49 66 20 74 68 65 20 4e 74  d.)^  ^If the Nt
2b0a0 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20  h column of the 
2b0b0 72 65 73 75 6c 74 20 73 65 74 20 69 73 20 61 6e  result set is an
2b0c0 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f  .** expression o
2b0d0 72 20 73 75 62 71 75 65 72 79 2c 20 74 68 65 6e  r subquery, then
2b0e0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
2b0f0 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20  is returned..** 
2b100 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74  ^The returned st
2b110 72 69 6e 67 20 69 73 20 61 6c 77 61 79 73 20 55  ring is always U
2b120 54 46 2d 38 20 65 6e 63 6f 64 65 64 2e 0a 2a 2a  TF-8 encoded..**
2b130 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c  .** ^(For exampl
2b140 65 2c 20 67 69 76 65 6e 20 74 68 65 20 64 61 74  e, given the dat
2b150 61 62 61 73 65 20 73 63 68 65 6d 61 3a 0a 2a 2a  abase schema:.**
2b160 0a 2a 2a 20 43 52 45 41 54 45 20 54 41 42 4c 45  .** CREATE TABLE
2b170 20 74 31 28 63 31 20 56 41 52 49 41 4e 54 29 3b   t1(c1 VARIANT);
2b180 0a 2a 2a 0a 2a 2a 20 61 6e 64 20 74 68 65 20 66  .**.** and the f
2b190 6f 6c 6c 6f 77 69 6e 67 20 73 74 61 74 65 6d 65  ollowing stateme
2b1a0 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65  nt to be compile
2b1b0 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54 20  d:.**.** SELECT 
2b1c0 63 31 20 2b 20 31 2c 20 63 31 20 46 52 4f 4d 20  c1 + 1, c1 FROM 
2b1d0 74 31 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 73 20 72  t1;.**.** this r
2b1e0 6f 75 74 69 6e 65 20 77 6f 75 6c 64 20 72 65 74  outine would ret
2b1f0 75 72 6e 20 74 68 65 20 73 74 72 69 6e 67 20 22  urn the string "
2b200 56 41 52 49 41 4e 54 22 20 66 6f 72 20 74 68 65  VARIANT" for the
2b210 20 73 65 63 6f 6e 64 20 72 65 73 75 6c 74 0a 2a   second result.*
2b220 2a 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c  * column (i==1),
2b230 20 61 6e 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e   and a NULL poin
2b240 74 65 72 20 66 6f 72 20 74 68 65 20 66 69 72 73  ter for the firs
2b250 74 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  t result column 
2b260 28 69 3d 3d 30 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20  (i==0).)^.**.** 
2b270 5e 53 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e  ^SQLite uses dyn
2b280 61 6d 69 63 20 72 75 6e 2d 74 69 6d 65 20 74 79  amic run-time ty
2b290 70 69 6e 67 2e 20 20 5e 53 6f 20 6a 75 73 74 20  ping.  ^So just 
2b2a0 62 65 63 61 75 73 65 20 61 20 63 6f 6c 75 6d 6e  because a column
2b2b0 0a 2a 2a 20 69 73 20 64 65 63 6c 61 72 65 64 20  .** is declared 
2b2c0 74 6f 20 63 6f 6e 74 61 69 6e 20 61 20 70 61 72  to contain a par
2b2d0 74 69 63 75 6c 61 72 20 74 79 70 65 20 64 6f 65  ticular type doe
2b2e0 73 20 6e 6f 74 20 6d 65 61 6e 20 74 68 61 74 20  s not mean that 
2b2f0 74 68 65 0a 2a 2a 20 64 61 74 61 20 73 74 6f 72  the.** data stor
2b300 65 64 20 69 6e 20 74 68 61 74 20 63 6f 6c 75 6d  ed in that colum
2b310 6e 20 69 73 20 6f 66 20 74 68 65 20 64 65 63 6c  n is of the decl
2b320 61 72 65 64 20 74 79 70 65 2e 20 20 53 51 4c 69  ared type.  SQLi
2b330 74 65 20 69 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c  te is.** strongl
2b340 79 20 74 79 70 65 64 2c 20 62 75 74 20 74 68 65  y typed, but the
2b350 20 74 79 70 69 6e 67 20 69 73 20 64 79 6e 61 6d   typing is dynam
2b360 69 63 20 6e 6f 74 20 73 74 61 74 69 63 2e 20 20  ic not static.  
2b370 5e 54 79 70 65 0a 2a 2a 20 69 73 20 61 73 73 6f  ^Type.** is asso
2b380 63 69 61 74 65 64 20 77 69 74 68 20 69 6e 64 69  ciated with indi
2b390 76 69 64 75 61 6c 20 76 61 6c 75 65 73 2c 20 6e  vidual values, n
2b3a0 6f 74 20 77 69 74 68 20 74 68 65 20 63 6f 6e 74  ot with the cont
2b3b0 61 69 6e 65 72 73 0a 2a 2a 20 75 73 65 64 20 74  ainers.** used t
2b3c0 6f 20 68 6f 6c 64 20 74 68 6f 73 65 20 76 61 6c  o hold those val
2b3d0 75 65 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68  ues..*/.const ch
2b3e0 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ar *sqlite3_colu
2b3f0 6d 6e 5f 64 65 63 6c 74 79 70 65 28 73 71 6c 69  mn_decltype(sqli
2b400 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
2b410 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
2b420 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74  te3_column_declt
2b430 79 70 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ype16(sqlite3_st
2b440 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  mt*,int);../*.**
2b450 20 43 41 50 49 33 52 45 46 3a 20 45 76 61 6c 75   CAPI3REF: Evalu
2b460 61 74 65 20 41 6e 20 53 51 4c 20 53 74 61 74 65  ate An SQL State
2b470 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72  ment.**.** After
2b480 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
2b490 74 65 6d 65 6e 74 5d 20 68 61 73 20 62 65 65 6e  tement] has been
2b4a0 20 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 20   prepared using 
2b4b0 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74  either.** [sqlit
2b4c0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
2b4d0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   or [sqlite3_pre
2b4e0 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20  pare16_v2()] or 
2b4f0 6f 6e 65 20 6f 66 20 74 68 65 20 6c 65 67 61 63  one of the legac
2b500 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  y.** interfaces 
2b510 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2b520 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
2b530 70 72 65 70 61 72 65 31 36 28 29 5d 2c 20 74 68  prepare16()], th
2b540 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d  is function.** m
2b550 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 6f 6e  ust be called on
2b560 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 20  e or more times 
2b570 74 6f 20 65 76 61 6c 75 61 74 65 20 74 68 65 20  to evaluate the 
2b580 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a  statement..**.**
2b590 20 54 68 65 20 64 65 74 61 69 6c 73 20 6f 66 20   The details of 
2b5a0 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20  the behavior of 
2b5b0 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70  the sqlite3_step
2b5c0 28 29 20 69 6e 74 65 72 66 61 63 65 20 64 65 70  () interface dep
2b5d0 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65  end.** on whethe
2b5e0 72 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  r the statement 
2b5f0 77 61 73 20 70 72 65 70 61 72 65 64 20 75 73 69  was prepared usi
2b600 6e 67 20 74 68 65 20 6e 65 77 65 72 20 22 76 32  ng the newer "v2
2b610 22 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 5b  " interface.** [
2b620 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
2b630 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  v2()] and [sqlit
2b640 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
2b650 29 5d 20 6f 72 20 74 68 65 20 6f 6c 64 65 72 20  )] or the older 
2b660 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66  legacy.** interf
2b670 61 63 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  ace [sqlite3_pre
2b680 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  pare()] and [sql
2b690 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
2b6a0 5d 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20 74  ].  The use of t
2b6b0 68 65 0a 2a 2a 20 6e 65 77 20 22 76 32 22 20 69  he.** new "v2" i
2b6c0 6e 74 65 72 66 61 63 65 20 69 73 20 72 65 63 6f  nterface is reco
2b6d0 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6e 65 77 20  mmended for new 
2b6e0 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 62 75 74  applications but
2b6f0 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69   the legacy.** i
2b700 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 63 6f  nterface will co
2b710 6e 74 69 6e 75 65 20 74 6f 20 62 65 20 73 75 70  ntinue to be sup
2b720 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  ported..**.** ^I
2b730 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74  n the legacy int
2b740 65 72 66 61 63 65 2c 20 74 68 65 20 72 65 74 75  erface, the retu
2b750 72 6e 20 76 61 6c 75 65 20 77 69 6c 6c 20 62 65  rn value will be
2b760 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f   either [SQLITE_
2b770 42 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54  BUSY],.** [SQLIT
2b780 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45  E_DONE], [SQLITE
2b790 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49 54 45 5f 45  _ROW], [SQLITE_E
2b7a0 52 52 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c 49 54  RROR], or [SQLIT
2b7b0 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20 5e 57  E_MISUSE]..** ^W
2b7c0 69 74 68 20 74 68 65 20 22 76 32 22 20 69 6e 74  ith the "v2" int
2b7d0 65 72 66 61 63 65 2c 20 61 6e 79 20 6f 66 20 74  erface, any of t
2b7e0 68 65 20 6f 74 68 65 72 20 5b 72 65 73 75 6c 74  he other [result
2b7f0 20 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65   codes] or.** [e
2b800 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
2b810 6f 64 65 73 5d 20 6d 69 67 68 74 20 62 65 20 72  odes] might be r
2b820 65 74 75 72 6e 65 64 20 61 73 20 77 65 6c 6c 2e  eturned as well.
2b830 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f  .**.** ^[SQLITE_
2b840 42 55 53 59 5d 20 6d 65 61 6e 73 20 74 68 61 74  BUSY] means that
2b850 20 74 68 65 20 64 61 74 61 62 61 73 65 20 65 6e   the database en
2b860 67 69 6e 65 20 77 61 73 20 75 6e 61 62 6c 65 20  gine was unable 
2b870 74 6f 20 61 63 71 75 69 72 65 20 74 68 65 0a 2a  to acquire the.*
2b880 2a 20 64 61 74 61 62 61 73 65 20 6c 6f 63 6b 73  * database locks
2b890 20 69 74 20 6e 65 65 64 73 20 74 6f 20 64 6f 20   it needs to do 
2b8a0 69 74 73 20 6a 6f 62 2e 20 20 5e 49 66 20 74 68  its job.  ^If th
2b8b0 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61  e statement is a
2b8c0 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20   [COMMIT].** or 
2b8d0 6f 63 63 75 72 73 20 6f 75 74 73 69 64 65 20 6f  occurs outside o
2b8e0 66 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72  f an explicit tr
2b8f0 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20  ansaction, then 
2b900 79 6f 75 20 63 61 6e 20 72 65 74 72 79 20 74 68  you can retry th
2b910 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e 20  e.** statement. 
2b920 20 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e   If the statemen
2b930 74 20 69 73 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d  t is not a [COMM
2b940 49 54 5d 20 61 6e 64 20 6f 63 63 75 72 73 20 77  IT] and occurs w
2b950 69 74 68 69 6e 20 61 6e 0a 2a 2a 20 65 78 70 6c  ithin an.** expl
2b960 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e  icit transaction
2b970 20 74 68 65 6e 20 79 6f 75 20 73 68 6f 75 6c 64   then you should
2b980 20 72 6f 6c 6c 62 61 63 6b 20 74 68 65 20 74 72   rollback the tr
2b990 61 6e 73 61 63 74 69 6f 6e 20 62 65 66 6f 72 65  ansaction before
2b9a0 0a 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a  .** continuing..
2b9b0 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 44  **.** ^[SQLITE_D
2b9c0 4f 4e 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20  ONE] means that 
2b9d0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61  the statement ha
2b9e0 73 20 66 69 6e 69 73 68 65 64 20 65 78 65 63 75  s finished execu
2b9f0 74 69 6e 67 0a 2a 2a 20 73 75 63 63 65 73 73 66  ting.** successf
2ba00 75 6c 6c 79 2e 20 20 73 71 6c 69 74 65 33 5f 73  ully.  sqlite3_s
2ba10 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74  tep() should not
2ba20 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e   be called again
2ba30 20 6f 6e 20 74 68 69 73 20 76 69 72 74 75 61 6c   on this virtual
2ba40 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 77 69 74 68  .** machine with
2ba50 6f 75 74 20 66 69 72 73 74 20 63 61 6c 6c 69 6e  out first callin
2ba60 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  g [sqlite3_reset
2ba70 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65  ()] to reset the
2ba80 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68   virtual.** mach
2ba90 69 6e 65 20 62 61 63 6b 20 74 6f 20 69 74 73 20  ine back to its 
2baa0 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2e 0a 2a  initial state..*
2bab0 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 53 51 4c  *.** ^If the SQL
2bac0 20 73 74 61 74 65 6d 65 6e 74 20 62 65 69 6e 67   statement being
2bad0 20 65 78 65 63 75 74 65 64 20 72 65 74 75 72 6e   executed return
2bae0 73 20 61 6e 79 20 64 61 74 61 2c 20 74 68 65 6e  s any data, then
2baf0 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a   [SQLITE_ROW].**
2bb00 20 69 73 20 72 65 74 75 72 6e 65 64 20 65 61 63   is returned eac
2bb10 68 20 74 69 6d 65 20 61 20 6e 65 77 20 72 6f 77  h time a new row
2bb20 20 6f 66 20 64 61 74 61 20 69 73 20 72 65 61 64   of data is read
2bb30 79 20 66 6f 72 20 70 72 6f 63 65 73 73 69 6e 67  y for processing
2bb40 20 62 79 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 65   by the.** calle
2bb50 72 2e 20 54 68 65 20 76 61 6c 75 65 73 20 6d 61  r. The values ma
2bb60 79 20 62 65 20 61 63 63 65 73 73 65 64 20 75 73  y be accessed us
2bb70 69 6e 67 20 74 68 65 20 5b 63 6f 6c 75 6d 6e 20  ing the [column 
2bb80 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73  access functions
2bb90 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74  ]..** sqlite3_st
2bba0 65 70 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61  ep() is called a
2bbb0 67 61 69 6e 20 74 6f 20 72 65 74 72 69 65 76 65  gain to retrieve
2bbc0 20 74 68 65 20 6e 65 78 74 20 72 6f 77 20 6f 66   the next row of
2bbd0 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53   data..**.** ^[S
2bbe0 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6d 65 61  QLITE_ERROR] mea
2bbf0 6e 73 20 74 68 61 74 20 61 20 72 75 6e 2d 74 69  ns that a run-ti
2bc00 6d 65 20 65 72 72 6f 72 20 28 73 75 63 68 20 61  me error (such a
2bc10 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a  s a constraint.*
2bc20 2a 20 76 69 6f 6c 61 74 69 6f 6e 29 20 68 61 73  * violation) has
2bc30 20 6f 63 63 75 72 72 65 64 2e 20 20 73 71 6c 69   occurred.  sqli
2bc40 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c  te3_step() shoul
2bc50 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20  d not be called 
2bc60 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20  again on.** the 
2bc70 56 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f 72 6d 61  VM. More informa
2bc80 74 69 6f 6e 20 6d 61 79 20 62 65 20 66 6f 75 6e  tion may be foun
2bc90 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71  d by calling [sq
2bca0 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e  lite3_errmsg()].
2bcb0 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 20 6c 65  .** ^With the le
2bcc0 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20  gacy interface, 
2bcd0 61 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20  a more specific 
2bce0 65 72 72 6f 72 20 63 6f 64 65 20 28 66 6f 72 20  error code (for 
2bcf0 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c  example,.** [SQL
2bd00 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2c 20  ITE_INTERRUPT], 
2bd10 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2c  [SQLITE_SCHEMA],
2bd20 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54   [SQLITE_CORRUPT
2bd30 5d 2c 20 61 6e 64 20 73 6f 20 66 6f 72 74 68 29  ], and so forth)
2bd40 0a 2a 2a 20 63 61 6e 20 62 65 20 6f 62 74 61 69  .** can be obtai
2bd50 6e 65 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b  ned by calling [
2bd60 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
2bd70 20 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70   on the.** [prep
2bd80 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
2bd90 20 20 5e 49 6e 20 74 68 65 20 22 76 32 22 20 69    ^In the "v2" i
2bda0 6e 74 65 72 66 61 63 65 2c 0a 2a 2a 20 74 68 65  nterface,.** the
2bdb0 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 65   more specific e
2bdc0 72 72 6f 72 20 63 6f 64 65 20 69 73 20 72 65 74  rror code is ret
2bdd0 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79 20 62  urned directly b
2bde0 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  y sqlite3_step()
2bdf0 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ..**.** [SQLITE_
2be00 4d 49 53 55 53 45 5d 20 6d 65 61 6e 73 20 74 68  MISUSE] means th
2be10 61 74 20 74 68 65 20 74 68 69 73 20 72 6f 75 74  at the this rout
2be20 69 6e 65 20 77 61 73 20 63 61 6c 6c 65 64 20 69  ine was called i
2be30 6e 61 70 70 72 6f 70 72 69 61 74 65 6c 79 2e 0a  nappropriately..
2be40 2a 2a 20 50 65 72 68 61 70 73 20 69 74 20 77 61  ** Perhaps it wa
2be50 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 70  s called on a [p
2be60 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2be70 74 5d 20 74 68 61 74 20 68 61 73 0a 2a 2a 20 61  t] that has.** a
2be80 6c 72 65 61 64 79 20 62 65 65 6e 20 5b 73 71 6c  lready been [sql
2be90 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20  ite3_finalize | 
2bea0 66 69 6e 61 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e  finalized] or on
2beb0 20 6f 6e 65 20 74 68 61 74 20 68 61 64 0a 2a 2a   one that had.**
2bec0 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75   previously retu
2bed0 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 45 52 52  rned [SQLITE_ERR
2bee0 4f 52 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44  OR] or [SQLITE_D
2bef0 4f 4e 45 5d 2e 20 20 4f 72 20 69 74 20 63 6f 75  ONE].  Or it cou
2bf00 6c 64 0a 2a 2a 20 62 65 20 74 68 65 20 63 61 73  ld.** be the cas
2bf10 65 20 74 68 61 74 20 74 68 65 20 73 61 6d 65 20  e that the same 
2bf20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2bf30 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 75 73 65  ion is being use
2bf40 64 20 62 79 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d  d by two or.** m
2bf50 6f 72 65 20 74 68 72 65 61 64 73 20 61 74 20 74  ore threads at t
2bf60 68 65 20 73 61 6d 65 20 6d 6f 6d 65 6e 74 20 69  he same moment i
2bf70 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f  n time..**.** Fo
2bf80 72 20 61 6c 6c 20 76 65 72 73 69 6f 6e 73 20 6f  r all versions o
2bf90 66 20 53 51 4c 69 74 65 20 75 70 20 74 6f 20 61  f SQLite up to a
2bfa0 6e 64 20 69 6e 63 6c 75 64 69 6e 67 20 33 2e 36  nd including 3.6
2bfb0 2e 32 33 2e 31 2c 20 61 20 63 61 6c 6c 20 74 6f  .23.1, a call to
2bfc0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  .** [sqlite3_res
2bfd0 65 74 28 29 5d 20 77 61 73 20 72 65 71 75 69 72  et()] was requir
2bfe0 65 64 20 61 66 74 65 72 20 73 71 6c 69 74 65 33  ed after sqlite3
2bff0 5f 73 74 65 70 28 29 20 72 65 74 75 72 6e 65 64  _step() returned
2c000 20 61 6e 79 74 68 69 6e 67 0a 2a 2a 20 6f 74 68   anything.** oth
2c010 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
2c020 52 4f 57 5d 20 62 65 66 6f 72 65 20 61 6e 79 20  ROW] before any 
2c030 73 75 62 73 65 71 75 65 6e 74 20 69 6e 76 6f 63  subsequent invoc
2c040 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 73 71 6c 69  ation of.** sqli
2c050 74 65 33 5f 73 74 65 70 28 29 2e 20 20 46 61 69  te3_step().  Fai
2c060 6c 75 72 65 20 74 6f 20 72 65 73 65 74 20 74 68  lure to reset th
2c070 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  e prepared state
2c080 6d 65 6e 74 20 75 73 69 6e 67 20 0a 2a 2a 20 5b  ment using .** [
2c090 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
2c0a0 20 77 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e   would result in
2c0b0 20 61 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55   an [SQLITE_MISU
2c0c0 53 45 5d 20 72 65 74 75 72 6e 20 66 72 6f 6d 0a  SE] return from.
2c0d0 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  ** sqlite3_step(
2c0e0 29 2e 20 20 42 75 74 20 61 66 74 65 72 20 76 65  ).  But after ve
2c0f0 72 73 69 6f 6e 20 33 2e 36 2e 32 33 2e 31 2c 20  rsion 3.6.23.1, 
2c100 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 62  sqlite3_step() b
2c110 65 67 61 6e 0a 2a 2a 20 63 61 6c 6c 69 6e 67 20  egan.** calling 
2c120 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
2c130 5d 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  ] automatically 
2c140 69 6e 20 74 68 69 73 20 63 69 72 63 75 6d 73 74  in this circumst
2c150 61 6e 63 65 20 72 61 74 68 65 72 0a 2a 2a 20 74  ance rather.** t
2c160 68 61 6e 20 72 65 74 75 72 6e 69 6e 67 20 5b 53  han returning [S
2c170 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20  QLITE_MISUSE].  
2c180 54 68 69 73 20 69 73 20 6e 6f 74 20 63 6f 6e 73  This is not cons
2c190 69 64 65 72 65 64 20 61 20 63 6f 6d 70 61 74 69  idered a compati
2c1a0 62 69 6c 69 74 79 0a 2a 2a 20 62 72 65 61 6b 20  bility.** break 
2c1b0 62 65 63 61 75 73 65 20 61 6e 79 20 61 70 70 6c  because any appl
2c1c0 69 63 61 74 69 6f 6e 20 74 68 61 74 20 65 76 65  ication that eve
2c1d0 72 20 72 65 63 65 69 76 65 73 20 61 6e 20 53 51  r receives an SQ
2c1e0 4c 49 54 45 5f 4d 49 53 55 53 45 20 65 72 72 6f  LITE_MISUSE erro
2c1f0 72 0a 2a 2a 20 69 73 20 62 72 6f 6b 65 6e 20 62  r.** is broken b
2c200 79 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54  y definition.  T
2c210 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  he [SQLITE_OMIT_
2c220 41 55 54 4f 52 45 53 45 54 5d 20 63 6f 6d 70 69  AUTORESET] compi
2c230 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 0a 2a  le-time option.*
2c240 2a 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  * can be used to
2c250 20 72 65 73 74 6f 72 65 20 74 68 65 20 6c 65 67   restore the leg
2c260 61 63 79 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a  acy behavior..**
2c270 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20 49 6e 74  .** <b>Goofy Int
2c280 65 72 66 61 63 65 20 41 6c 65 72 74 3a 3c 2f 62  erface Alert:</b
2c290 3e 20 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20  > In the legacy 
2c2a0 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 73  interface, the s
2c2b0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 0a 2a 2a  qlite3_step().**
2c2c0 20 41 50 49 20 61 6c 77 61 79 73 20 72 65 74 75   API always retu
2c2d0 72 6e 73 20 61 20 67 65 6e 65 72 69 63 20 65 72  rns a generic er
2c2e0 72 6f 72 20 63 6f 64 65 2c 20 5b 53 51 4c 49 54  ror code, [SQLIT
2c2f0 45 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77  E_ERROR], follow
2c300 69 6e 67 20 61 6e 79 0a 2a 2a 20 65 72 72 6f 72  ing any.** error
2c310 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
2c320 49 54 45 5f 42 55 53 59 5d 20 61 6e 64 20 5b 53  ITE_BUSY] and [S
2c330 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20  QLITE_MISUSE].  
2c340 59 6f 75 20 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a  You must call.**
2c350 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2c360 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66  )] or [sqlite3_f
2c370 69 6e 61 6c 69 7a 65 28 29 5d 20 69 6e 20 6f 72  inalize()] in or
2c380 64 65 72 20 74 6f 20 66 69 6e 64 20 6f 6e 65 20  der to find one 
2c390 6f 66 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66  of the.** specif
2c3a0 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d  ic [error codes]
2c3b0 20 74 68 61 74 20 62 65 74 74 65 72 20 64 65 73   that better des
2c3c0 63 72 69 62 65 73 20 74 68 65 20 65 72 72 6f 72  cribes the error
2c3d0 2e 0a 2a 2a 20 57 65 20 61 64 6d 69 74 20 74 68  ..** We admit th
2c3e0 61 74 20 74 68 69 73 20 69 73 20 61 20 67 6f 6f  at this is a goo
2c3f0 66 79 20 64 65 73 69 67 6e 2e 20 20 54 68 65 20  fy design.  The 
2c400 70 72 6f 62 6c 65 6d 20 68 61 73 20 62 65 65 6e  problem has been
2c410 20 66 69 78 65 64 0a 2a 2a 20 77 69 74 68 20 74   fixed.** with t
2c420 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  he "v2" interfac
2c430 65 2e 20 20 49 66 20 79 6f 75 20 70 72 65 70 61  e.  If you prepa
2c440 72 65 20 61 6c 6c 20 6f 66 20 79 6f 75 72 20 53  re all of your S
2c450 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  QL statements.**
2c460 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73   using either [s
2c470 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2c480 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  2()] or [sqlite3
2c490 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
2c4a0 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 74   instead.** of t
2c4b0 68 65 20 6c 65 67 61 63 79 20 5b 73 71 6c 69 74  he legacy [sqlit
2c4c0 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e  e3_prepare()] an
2c4d0 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  d [sqlite3_prepa
2c4e0 72 65 31 36 28 29 5d 20 69 6e 74 65 72 66 61 63  re16()] interfac
2c4f0 65 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  es,.** then the 
2c500 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 5b 65  more specific [e
2c510 72 72 6f 72 20 63 6f 64 65 73 5d 20 61 72 65 20  rror codes] are 
2c520 72 65 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c  returned directl
2c530 79 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f  y.** by sqlite3_
2c540 73 74 65 70 28 29 2e 20 20 54 68 65 20 75 73 65  step().  The use
2c550 20 6f 66 20 74 68 65 20 22 76 32 22 20 69 6e 74   of the "v2" int
2c560 65 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d  erface is recomm
2c570 65 6e 64 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ended..*/.int sq
2c580 6c 69 74 65 33 5f 73 74 65 70 28 73 71 6c 69 74  lite3_step(sqlit
2c590 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a  e3_stmt*);../*.*
2c5a0 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62  * CAPI3REF: Numb
2c5b0 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
2c5c0 20 61 20 72 65 73 75 6c 74 20 73 65 74 0a 2a 2a   a result set.**
2c5d0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2c5e0 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 69  _data_count(P) i
2c5f0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
2c600 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
2c610 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 0a 2a 2a  olumns in the.**
2c620 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20   current row of 
2c630 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f  the result set o
2c640 66 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  f [prepared stat
2c650 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 49 66  ement] P..** ^If
2c660 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
2c670 65 6e 74 20 50 20 64 6f 65 73 20 6e 6f 74 20 68  ent P does not h
2c680 61 76 65 20 72 65 73 75 6c 74 73 20 72 65 61 64  ave results read
2c690 79 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 28  y to return.** (
2c6a0 76 69 61 20 63 61 6c 6c 73 20 74 6f 20 74 68 65  via calls to the
2c6b0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
2c6c0 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f 63  _int | sqlite3_c
2c6d0 6f 6c 75 6d 6e 5f 2a 28 29 5d 20 6f 66 0a 2a 2a  olumn_*()] of.**
2c6e0 20 69 6e 74 65 72 66 61 63 65 73 29 20 74 68 65   interfaces) the
2c6f0 6e 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63  n sqlite3_data_c
2c700 6f 75 6e 74 28 50 29 20 72 65 74 75 72 6e 73 20  ount(P) returns 
2c710 30 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  0..** ^The sqlit
2c720 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29  e3_data_count(P)
2c730 20 72 6f 75 74 69 6e 65 20 61 6c 73 6f 20 72 65   routine also re
2c740 74 75 72 6e 73 20 30 20 69 66 20 50 20 69 73 20  turns 0 if P is 
2c750 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
2c760 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2c770 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f  data_count(P) ro
2c780 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30 20  utine returns 0 
2c790 69 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 20  if the previous 
2c7a0 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  call to.** [sqli
2c7b0 74 65 33 5f 73 74 65 70 5d 28 50 29 20 72 65 74  te3_step](P) ret
2c7c0 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 44 4f  urned [SQLITE_DO
2c7d0 4e 45 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 74  NE].  ^The sqlit
2c7e0 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29  e3_data_count(P)
2c7f0 0a 2a 2a 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  .** will return 
2c800 6e 6f 6e 2d 7a 65 72 6f 20 69 66 20 70 72 65 76  non-zero if prev
2c810 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 5b 73 71  ious call to [sq
2c820 6c 69 74 65 33 5f 73 74 65 70 5d 28 50 29 20 72  lite3_step](P) r
2c830 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 53 51 4c 49  eturned.** [SQLI
2c840 54 45 5f 52 4f 57 5d 2c 20 65 78 63 65 70 74 20  TE_ROW], except 
2c850 69 6e 20 74 68 65 20 63 61 73 65 20 6f 66 20 74  in the case of t
2c860 68 65 20 5b 50 52 41 47 4d 41 20 69 6e 63 72 65  he [PRAGMA incre
2c870 6d 65 6e 74 61 6c 5f 76 61 63 75 75 6d 5d 0a 2a  mental_vacuum].*
2c880 2a 20 77 68 65 72 65 20 69 74 20 61 6c 77 61 79  * where it alway
2c890 73 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 73  s returns zero s
2c8a0 69 6e 63 65 20 65 61 63 68 20 73 74 65 70 20 6f  ince each step o
2c8b0 66 20 74 68 61 74 20 6d 75 6c 74 69 2d 73 74 65  f that multi-ste
2c8c0 70 0a 2a 2a 20 70 72 61 67 6d 61 20 72 65 74 75  p.** pragma retu
2c8d0 72 6e 73 20 30 20 63 6f 6c 75 6d 6e 73 20 6f 66  rns 0 columns of
2c8e0 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 53 65 65   data..**.** See
2c8f0 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
2c900 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 0a  column_count()].
2c910 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 64  */.int sqlite3_d
2c920 61 74 61 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65  ata_count(sqlite
2c930 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
2c940 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2c950 20 46 75 6e 64 61 6d 65 6e 74 61 6c 20 44 61 74   Fundamental Dat
2c960 61 74 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52  atypes.** KEYWOR
2c970 44 53 3a 20 53 51 4c 49 54 45 5f 54 45 58 54 0a  DS: SQLITE_TEXT.
2c980 2a 2a 0a 2a 2a 20 5e 28 45 76 65 72 79 20 76 61  **.** ^(Every va
2c990 6c 75 65 20 69 6e 20 53 51 4c 69 74 65 20 68 61  lue in SQLite ha
2c9a0 73 20 6f 6e 65 20 6f 66 20 66 69 76 65 20 66 75  s one of five fu
2c9b0 6e 64 61 6d 65 6e 74 61 6c 20 64 61 74 61 74 79  ndamental dataty
2c9c0 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  pes:.**.** <ul>.
2c9d0 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 73  ** <li> 64-bit s
2c9e0 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a  igned integer.**
2c9f0 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 49 45 45   <li> 64-bit IEE
2ca00 45 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  E floating point
2ca10 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20   number.** <li> 
2ca20 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42  string.** <li> B
2ca30 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c  LOB.** <li> NULL
2ca40 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a  .** </ul>)^.**.*
2ca50 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74  * These constant
2ca60 73 20 61 72 65 20 63 6f 64 65 73 20 66 6f 72 20  s are codes for 
2ca70 65 61 63 68 20 6f 66 20 74 68 6f 73 65 20 74 79  each of those ty
2ca80 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20  pes..**.** Note 
2ca90 74 68 61 74 20 74 68 65 20 53 51 4c 49 54 45 5f  that the SQLITE_
2caa0 54 45 58 54 20 63 6f 6e 73 74 61 6e 74 20 77 61  TEXT constant wa
2cab0 73 20 61 6c 73 6f 20 75 73 65 64 20 69 6e 20 53  s also used in S
2cac0 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32 0a  QLite version 2.
2cad0 2a 2a 20 66 6f 72 20 61 20 63 6f 6d 70 6c 65 74  ** for a complet
2cae0 65 6c 79 20 64 69 66 66 65 72 65 6e 74 20 6d 65  ely different me
2caf0 61 6e 69 6e 67 2e 20 20 53 6f 66 74 77 61 72 65  aning.  Software
2cb00 20 74 68 61 74 20 6c 69 6e 6b 73 20 61 67 61 69   that links agai
2cb10 6e 73 74 20 62 6f 74 68 0a 2a 2a 20 53 51 4c 69  nst both.** SQLi
2cb20 74 65 20 76 65 72 73 69 6f 6e 20 32 20 61 6e 64  te version 2 and
2cb30 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
2cb40 33 20 73 68 6f 75 6c 64 20 75 73 65 20 53 51 4c  3 should use SQL
2cb50 49 54 45 33 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a  ITE3_TEXT, not.*
2cb60 2a 20 53 51 4c 49 54 45 5f 54 45 58 54 2e 0a 2a  * SQLITE_TEXT..*
2cb70 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
2cb80 5f 49 4e 54 45 47 45 52 20 20 31 0a 23 64 65 66  _INTEGER  1.#def
2cb90 69 6e 65 20 53 51 4c 49 54 45 5f 46 4c 4f 41 54  ine SQLITE_FLOAT
2cba0 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51      2.#define SQ
2cbb0 4c 49 54 45 5f 42 4c 4f 42 20 20 20 20 20 34 0a  LITE_BLOB     4.
2cbc0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e  #define SQLITE_N
2cbd0 55 4c 4c 20 20 20 20 20 35 0a 23 69 66 64 65 66  ULL     5.#ifdef
2cbe0 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 20 75   SQLITE_TEXT.# u
2cbf0 6e 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54  ndef SQLITE_TEXT
2cc00 0a 23 65 6c 73 65 0a 23 20 64 65 66 69 6e 65 20  .#else.# define 
2cc10 53 51 4c 49 54 45 5f 54 45 58 54 20 20 20 20 20  SQLITE_TEXT     
2cc20 33 0a 23 65 6e 64 69 66 0a 23 64 65 66 69 6e 65  3.#endif.#define
2cc30 20 53 51 4c 49 54 45 33 5f 54 45 58 54 20 20 20   SQLITE3_TEXT   
2cc40 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33    3../*.** CAPI3
2cc50 52 45 46 3a 20 52 65 73 75 6c 74 20 56 61 6c 75  REF: Result Valu
2cc60 65 73 20 46 72 6f 6d 20 41 20 51 75 65 72 79 0a  es From A Query.
2cc70 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f  ** KEYWORDS: {co
2cc80 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63  lumn access func
2cc90 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  tions}.**.** The
2cca0 73 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 6d  se routines form
2ccb0 20 74 68 65 20 22 72 65 73 75 6c 74 20 73 65 74   the "result set
2ccc0 22 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a  " interface..**.
2ccd0 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
2cce0 65 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d  es return inform
2ccf0 61 74 69 6f 6e 20 61 62 6f 75 74 20 61 20 73 69  ation about a si
2cd00 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66 20 74  ngle column of t
2cd10 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65  he current.** re
2cd20 73 75 6c 74 20 72 6f 77 20 6f 66 20 61 20 71 75  sult row of a qu
2cd30 65 72 79 2e 20 20 5e 49 6e 20 65 76 65 72 79 20  ery.  ^In every 
2cd40 63 61 73 65 20 74 68 65 20 66 69 72 73 74 20 61  case the first a
2cd50 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69  rgument is a poi
2cd60 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b  nter.** to the [
2cd70 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2cd80 6e 74 5d 20 74 68 61 74 20 69 73 20 62 65 69 6e  nt] that is bein
2cd90 67 20 65 76 61 6c 75 61 74 65 64 20 28 74 68 65  g evaluated (the
2cda0 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d   [sqlite3_stmt*]
2cdb0 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 72 65 74  .** that was ret
2cdc0 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  urned from [sqli
2cdd0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
2cde0 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74 73 20  ] or one of its 
2cdf0 76 61 72 69 61 6e 74 73 29 0a 2a 2a 20 61 6e 64  variants).** and
2ce00 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
2ce10 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65  ment is the inde
2ce20 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20  x of the column 
2ce30 66 6f 72 20 77 68 69 63 68 20 69 6e 66 6f 72 6d  for which inform
2ce40 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20  ation.** should 
2ce50 62 65 20 72 65 74 75 72 6e 65 64 2e 20 5e 54 68  be returned. ^Th
2ce60 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d  e leftmost colum
2ce70 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  n of the result 
2ce80 73 65 74 20 68 61 73 20 74 68 65 20 69 6e 64 65  set has the inde
2ce90 78 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 6e 75 6d  x 0..** ^The num
2cea0 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
2ceb0 6e 20 74 68 65 20 72 65 73 75 6c 74 20 63 61 6e  n the result can
2cec0 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64 20 75   be determined u
2ced0 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  sing.** [sqlite3
2cee0 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d  _column_count()]
2cef0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53  ..**.** If the S
2cf00 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65  QL statement doe
2cf10 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20  s not currently 
2cf20 70 6f 69 6e 74 20 74 6f 20 61 20 76 61 6c 69 64  point to a valid
2cf30 20 72 6f 77 2c 20 6f 72 20 69 66 20 74 68 65 0a   row, or if the.
2cf40 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e 64 65 78 20  ** column index 
2cf50 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c  is out of range,
2cf60 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 75   the result is u
2cf70 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65  ndefined..** The
2cf80 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 61 79 20  se routines may 
2cf90 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 77  only be called w
2cfa0 68 65 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63  hen the most rec
2cfb0 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b  ent call to.** [
2cfc0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
2cfd0 68 61 73 20 72 65 74 75 72 6e 65 64 20 5b 53 51  has returned [SQ
2cfe0 4c 49 54 45 5f 52 4f 57 5d 20 61 6e 64 20 6e 65  LITE_ROW] and ne
2cff0 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  ither.** [sqlite
2d000 33 5f 72 65 73 65 74 28 29 5d 20 6e 6f 72 20 5b  3_reset()] nor [
2d010 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2d020 28 29 5d 20 68 61 76 65 20 62 65 65 6e 20 63 61  ()] have been ca
2d030 6c 6c 65 64 20 73 75 62 73 65 71 75 65 6e 74 6c  lled subsequentl
2d040 79 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 6f 66 20  y..** If any of 
2d050 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  these routines a
2d060 72 65 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20  re called after 
2d070 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
2d080 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
2d090 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20  _finalize()] or 
2d0a0 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 73  after [sqlite3_s
2d0b0 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 75 72  tep()] has retur
2d0c0 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e 67  ned.** something
2d0d0 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
2d0e0 49 54 45 5f 52 4f 57 5d 2c 20 74 68 65 20 72 65  ITE_ROW], the re
2d0f0 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69  sults are undefi
2d100 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c 69  ned..** If [sqli
2d110 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b  te3_step()] or [
2d120 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
2d130 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e   or [sqlite3_fin
2d140 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61 72 65 20  alize()].** are 
2d150 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 20 64 69  called from a di
2d160 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 20 77  fferent thread w
2d170 68 69 6c 65 20 61 6e 79 20 6f 66 20 74 68 65 73  hile any of thes
2d180 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72  e routines.** ar
2d190 65 20 70 65 6e 64 69 6e 67 2c 20 74 68 65 6e 20  e pending, then 
2d1a0 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20  the results are 
2d1b0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
2d1c0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f   ^The sqlite3_co
2d1d0 6c 75 6d 6e 5f 74 79 70 65 28 29 20 72 6f 75 74  lumn_type() rout
2d1e0 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 0a  ine returns the.
2d1f0 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47  ** [SQLITE_INTEG
2d200 45 52 20 7c 20 64 61 74 61 74 79 70 65 20 63 6f  ER | datatype co
2d210 64 65 5d 20 66 6f 72 20 74 68 65 20 69 6e 69 74  de] for the init
2d220 69 61 6c 20 64 61 74 61 20 74 79 70 65 0a 2a 2a  ial data type.**
2d230 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 63   of the result c
2d240 6f 6c 75 6d 6e 2e 20 20 5e 54 68 65 20 72 65 74  olumn.  ^The ret
2d250 75 72 6e 65 64 20 76 61 6c 75 65 20 69 73 20 6f  urned value is o
2d260 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e  ne of [SQLITE_IN
2d270 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49  TEGER],.** [SQLI
2d280 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49  TE_FLOAT], [SQLI
2d290 54 45 5f 54 45 58 54 5d 2c 20 5b 53 51 4c 49 54  TE_TEXT], [SQLIT
2d2a0 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c  E_BLOB], or [SQL
2d2b0 49 54 45 5f 4e 55 4c 4c 5d 2e 20 20 54 68 65 20  ITE_NULL].  The 
2d2c0 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65  value.** returne
2d2d0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
2d2e0 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 6f 6e  umn_type() is on
2d2f0 6c 79 20 6d 65 61 6e 69 6e 67 66 75 6c 20 69 66  ly meaningful if
2d300 20 6e 6f 20 74 79 70 65 0a 2a 2a 20 63 6f 6e 76   no type.** conv
2d310 65 72 73 69 6f 6e 73 20 68 61 76 65 20 6f 63 63  ersions have occ
2d320 75 72 72 65 64 20 61 73 20 64 65 73 63 72 69 62  urred as describ
2d330 65 64 20 62 65 6c 6f 77 2e 20 20 41 66 74 65 72  ed below.  After
2d340 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69   a type conversi
2d350 6f 6e 2c 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65  on,.** the value
2d360 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
2d370 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
2d380 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  () is undefined.
2d390 20 20 46 75 74 75 72 65 0a 2a 2a 20 76 65 72 73    Future.** vers
2d3a0 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d  ions of SQLite m
2d3b0 61 79 20 63 68 61 6e 67 65 20 74 68 65 20 62 65  ay change the be
2d3c0 68 61 76 69 6f 72 20 6f 66 20 73 71 6c 69 74 65  havior of sqlite
2d3d0 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a  3_column_type().
2d3e0 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 74  ** following a t
2d3f0 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a  ype conversion..
2d400 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  **.** ^If the re
2d410 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f  sult is a BLOB o
2d420 72 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 74  r UTF-8 string t
2d430 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f  hen the sqlite3_
2d440 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a  column_bytes().*
2d450 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  * routine return
2d460 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
2d470 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c  bytes in that BL
2d480 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a  OB or string..**
2d490 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20   ^If the result 
2d4a0 69 73 20 61 20 55 54 46 2d 31 36 20 73 74 72 69  is a UTF-16 stri
2d4b0 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ng, then sqlite3
2d4c0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20  _column_bytes() 
2d4d0 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20  converts.** the 
2d4e0 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 38 20  string to UTF-8 
2d4f0 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73  and then returns
2d500 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
2d510 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ytes..** ^If the
2d520 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d   result is a num
2d530 65 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20  eric value then 
2d540 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2d550 79 74 65 73 28 29 20 75 73 65 73 0a 2a 2a 20 5b  ytes() uses.** [
2d560 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
2d570 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74  ()] to convert t
2d580 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55  hat value to a U
2d590 54 46 2d 38 20 73 74 72 69 6e 67 20 61 6e 64 20  TF-8 string and 
2d5a0 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e  returns.** the n
2d5b0 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
2d5c0 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a  n that string..*
2d5d0 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
2d5e0 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73   is NULL, then s
2d5f0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2d600 74 65 73 28 29 20 72 65 74 75 72 6e 73 20 7a 65  tes() returns ze
2d610 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  ro..**.** ^If th
2d620 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c  e result is a BL
2d630 4f 42 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72  OB or UTF-16 str
2d640 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c  ing then the sql
2d650 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2d660 73 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65  s16().** routine
2d670 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
2d680 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
2d690 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72  that BLOB or str
2d6a0 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ing..** ^If the 
2d6b0 72 65 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d  result is a UTF-
2d6c0 38 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73  8 string, then s
2d6d0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2d6e0 74 65 73 31 36 28 29 20 63 6f 6e 76 65 72 74 73  tes16() converts
2d6f0 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74  .** the string t
2d700 6f 20 55 54 46 2d 31 36 20 61 6e 64 20 74 68 65  o UTF-16 and the
2d710 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  n returns the nu
2d720 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a  mber of bytes..*
2d730 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
2d740 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61   is a numeric va
2d750 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33  lue then sqlite3
2d760 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
2d770 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74  ) uses.** [sqlit
2d780 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74  e3_snprintf()] t
2d790 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76  o convert that v
2d7a0 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 31 36  alue to a UTF-16
2d7b0 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75   string and retu
2d7c0 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65  rns.** the numbe
2d7d0 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
2d7e0 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49  at string..** ^I
2d7f0 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
2d800 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74  NULL, then sqlit
2d810 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
2d820 36 28 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f  6() returns zero
2d830 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 76 61 6c  ..**.** ^The val
2d840 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ues returned by 
2d850 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
2d860 62 79 74 65 73 28 29 5d 20 61 6e 64 20 0a 2a 2a  bytes()] and .**
2d870 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
2d880 5f 62 79 74 65 73 31 36 28 29 5d 20 64 6f 20 6e  _bytes16()] do n
2d890 6f 74 20 69 6e 63 6c 75 64 65 20 74 68 65 20 7a  ot include the z
2d8a0 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 73 20  ero terminators 
2d8b0 61 74 20 74 68 65 20 65 6e 64 0a 2a 2a 20 6f 66  at the end.** of
2d8c0 20 74 68 65 20 73 74 72 69 6e 67 2e 20 20 5e 46   the string.  ^F
2d8d0 6f 72 20 63 6c 61 72 69 74 79 3a 20 74 68 65 20  or clarity: the 
2d8e0 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20  values returned 
2d8f0 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  by.** [sqlite3_c
2d900 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61  olumn_bytes()] a
2d910 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  nd [sqlite3_colu
2d920 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d 20 61 72  mn_bytes16()] ar
2d930 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a  e the number of.
2d940 2a 2a 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  ** bytes in the 
2d950 73 74 72 69 6e 67 2c 20 6e 6f 74 20 74 68 65 20  string, not the 
2d960 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63  number of charac
2d970 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 53 74 72  ters..**.** ^Str
2d980 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79  ings returned by
2d990 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2d9a0 74 65 78 74 28 29 20 61 6e 64 20 73 71 6c 69 74  text() and sqlit
2d9b0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
2d9c0 28 29 2c 0a 2a 2a 20 65 76 65 6e 20 65 6d 70 74  (),.** even empt
2d9d0 79 20 73 74 72 69 6e 67 73 2c 20 61 72 65 20 61  y strings, are a
2d9e0 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69  lways zero-termi
2d9f0 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 72 65 74  nated.  ^The ret
2da00 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 66 72 6f  urn.** value fro
2da10 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  m sqlite3_column
2da20 5f 62 6c 6f 62 28 29 20 66 6f 72 20 61 20 7a 65  _blob() for a ze
2da30 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 20 69  ro-length BLOB i
2da40 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
2da50 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6f 62 6a  ..**.** ^The obj
2da60 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 20  ect returned by 
2da70 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
2da80 76 61 6c 75 65 28 29 5d 20 69 73 20 61 6e 0a 2a  value()] is an.*
2da90 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  * [unprotected s
2daa0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
2dab0 6a 65 63 74 2e 20 20 41 6e 20 75 6e 70 72 6f 74  ject.  An unprot
2dac0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
2dad0 6c 75 65 20 6f 62 6a 65 63 74 0a 2a 2a 20 6d 61  lue object.** ma
2dae0 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77  y only be used w
2daf0 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  ith [sqlite3_bin
2db00 64 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b  d_value()] and [
2db10 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
2db20 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49 66 20 74  alue()]..** If t
2db30 68 65 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20  he [unprotected 
2db40 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
2db50 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62  bject returned b
2db60 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  y.** [sqlite3_co
2db70 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73  lumn_value()] is
2db80 20 75 73 65 64 20 69 6e 20 61 6e 79 20 6f 74 68   used in any oth
2db90 65 72 20 77 61 79 2c 20 69 6e 63 6c 75 64 69 6e  er way, includin
2dba0 67 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f  g calls.** to ro
2dbb0 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c  utines like [sql
2dbc0 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 29  ite3_value_int()
2dbd0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ], [sqlite3_valu
2dbe0 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72  e_text()],.** or
2dbf0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
2dc00 62 79 74 65 73 28 29 5d 2c 20 74 68 65 6e 20 74  bytes()], then t
2dc10 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75  he behavior is u
2dc20 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
2dc30 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
2dc40 74 74 65 6d 70 74 20 74 6f 20 63 6f 6e 76 65 72  ttempt to conver
2dc50 74 20 74 68 65 20 76 61 6c 75 65 20 77 68 65 72  t the value wher
2dc60 65 20 61 70 70 72 6f 70 72 69 61 74 65 2e 20 20  e appropriate.  
2dc70 5e 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c  ^For.** example,
2dc80 20 69 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c   if the internal
2dc90 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20   representation 
2dca0 69 73 20 46 4c 4f 41 54 20 61 6e 64 20 61 20 74  is FLOAT and a t
2dcb0 65 78 74 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73  ext result.** is
2dcc0 20 72 65 71 75 65 73 74 65 64 2c 20 5b 73 71 6c   requested, [sql
2dcd0 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d  ite3_snprintf()]
2dce0 20 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61   is used interna
2dcf0 6c 6c 79 20 74 6f 20 70 65 72 66 6f 72 6d 20 74  lly to perform t
2dd00 68 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e  he.** conversion
2dd10 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20   automatically. 
2dd20 20 5e 28 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67   ^(The following
2dd30 20 74 61 62 6c 65 20 64 65 74 61 69 6c 73 20 74   table details t
2dd40 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a  he conversions.*
2dd50 2a 20 74 68 61 74 20 61 72 65 20 61 70 70 6c 69  * that are appli
2dd60 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ed:.**.** <block
2dd70 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65  quote>.** <table
2dd80 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20   border="1">.** 
2dd90 3c 74 72 3e 3c 74 68 3e 20 49 6e 74 65 72 6e 61  <tr><th> Interna
2dda0 6c 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 52  l<br>Type <th> R
2ddb0 65 71 75 65 73 74 65 64 3c 62 72 3e 54 79 70 65  equested<br>Type
2ddc0 20 3c 74 68 3e 20 20 43 6f 6e 76 65 72 73 69 6f   <th>  Conversio
2ddd0 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  n.**.** <tr><td>
2dde0 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 49    NULL    <td> I
2ddf0 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 52 65  NTEGER   <td> Re
2de00 73 75 6c 74 20 69 73 20 30 0a 2a 2a 20 3c 74 72  sult is 0.** <tr
2de10 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c  ><td>  NULL    <
2de20 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74  td>  FLOAT    <t
2de30 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30 2e 30  d> Result is 0.0
2de40 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55  .** <tr><td>  NU
2de50 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58  LL    <td>   TEX
2de60 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74  T    <td> Result
2de70 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
2de80 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  er.** <tr><td>  
2de90 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 42  NULL    <td>   B
2dea0 4c 4f 42 20 20 20 20 3c 74 64 3e 20 52 65 73 75  LOB    <td> Resu
2deb0 6c 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  lt is a NULL poi
2dec0 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  nter.** <tr><td>
2ded0 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20   INTEGER  <td>  
2dee0 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f  FLOAT    <td> Co
2def0 6e 76 65 72 74 20 66 72 6f 6d 20 69 6e 74 65 67  nvert from integ
2df00 65 72 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c  er to float.** <
2df10 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20  tr><td> INTEGER 
2df20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20   <td>   TEXT    
2df30 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65  <td> ASCII rende
2df40 72 69 6e 67 20 6f 66 20 74 68 65 20 69 6e 74 65  ring of the inte
2df50 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  ger.** <tr><td> 
2df60 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20  INTEGER  <td>   
2df70 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d  BLOB    <td> Sam
2df80 65 20 61 73 20 49 4e 54 45 47 45 52 2d 3e 54 45  e as INTEGER->TE
2df90 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  XT.** <tr><td>  
2dfa0 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 49 4e 54  FLOAT   <td> INT
2dfb0 45 47 45 52 20 20 20 3c 74 64 3e 20 5b 43 41 53  EGER   <td> [CAS
2dfc0 54 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a  T] to INTEGER.**
2dfd0 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54   <tr><td>  FLOAT
2dfe0 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20     <td>   TEXT  
2dff0 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e    <td> ASCII ren
2e000 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 66 6c  dering of the fl
2e010 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  oat.** <tr><td> 
2e020 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20   FLOAT   <td>   
2e030 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 5b 43 41  BLOB    <td> [CA
2e040 53 54 5d 20 74 6f 20 42 4c 4f 42 0a 2a 2a 20 3c  ST] to BLOB.** <
2e050 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20  tr><td>  TEXT   
2e060 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20   <td> INTEGER   
2e070 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49  <td> [CAST] to I
2e080 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74  NTEGER.** <tr><t
2e090 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  d>  TEXT    <td>
2e0a0 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20    FLOAT    <td> 
2e0b0 5b 43 41 53 54 5d 20 74 6f 20 52 45 41 4c 0a 2a  [CAST] to REAL.*
2e0c0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54  * <tr><td>  TEXT
2e0d0 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20      <td>   BLOB 
2e0e0 20 20 20 3c 74 64 3e 20 4e 6f 20 63 68 61 6e 67     <td> No chang
2e0f0 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42  e.** <tr><td>  B
2e100 4c 4f 42 20 20 20 20 3c 74 64 3e 20 49 4e 54 45  LOB    <td> INTE
2e110 47 45 52 20 20 20 3c 74 64 3e 20 5b 43 41 53 54  GER   <td> [CAST
2e120 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20  ] to INTEGER.** 
2e130 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20  <tr><td>  BLOB  
2e140 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20    <td>  FLOAT   
2e150 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20   <td> [CAST] to 
2e160 52 45 41 4c 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  REAL.** <tr><td>
2e170 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20    BLOB    <td>  
2e180 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 64   TEXT    <td> Ad
2e190 64 20 61 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  d a zero termina
2e1a0 74 6f 72 20 69 66 20 6e 65 65 64 65 64 0a 2a 2a  tor if needed.**
2e1b0 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62   </table>.** </b
2e1c0 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a  lockquote>)^.**.
2e1d0 2a 2a 20 54 68 65 20 74 61 62 6c 65 20 61 62 6f  ** The table abo
2e1e0 76 65 20 6d 61 6b 65 73 20 72 65 66 65 72 65 6e  ve makes referen
2e1f0 63 65 20 74 6f 20 73 74 61 6e 64 61 72 64 20 43  ce to standard C
2e200 20 6c 69 62 72 61 72 79 20 66 75 6e 63 74 69 6f   library functio
2e210 6e 73 20 61 74 6f 69 28 29 0a 2a 2a 20 61 6e 64  ns atoi().** and
2e220 20 61 74 6f 66 28 29 2e 20 20 53 51 4c 69 74 65   atof().  SQLite
2e230 20 64 6f 65 73 20 6e 6f 74 20 72 65 61 6c 6c 79   does not really
2e240 20 75 73 65 20 74 68 65 73 65 20 66 75 6e 63 74   use these funct
2e250 69 6f 6e 73 2e 20 20 49 74 20 68 61 73 20 69 74  ions.  It has it
2e260 73 0a 2a 2a 20 6f 77 6e 20 65 71 75 69 76 61 6c  s.** own equival
2e270 65 6e 74 20 69 6e 74 65 72 6e 61 6c 20 72 6f 75  ent internal rou
2e280 74 69 6e 65 73 2e 20 20 54 68 65 20 61 74 6f 69  tines.  The atoi
2e290 28 29 20 61 6e 64 20 61 74 6f 66 28 29 20 6e 61  () and atof() na
2e2a0 6d 65 73 20 61 72 65 0a 2a 2a 20 75 73 65 64 20  mes are.** used 
2e2b0 69 6e 20 74 68 65 20 74 61 62 6c 65 20 66 6f 72  in the table for
2e2c0 20 62 72 65 76 69 74 79 20 61 6e 64 20 62 65 63   brevity and bec
2e2d0 61 75 73 65 20 74 68 65 79 20 61 72 65 20 66 61  ause they are fa
2e2e0 6d 69 6c 69 61 72 20 74 6f 20 6d 6f 73 74 0a 2a  miliar to most.*
2e2f0 2a 20 43 20 70 72 6f 67 72 61 6d 6d 65 72 73 2e  * C programmers.
2e300 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  .**.** Note that
2e310 20 77 68 65 6e 20 74 79 70 65 20 63 6f 6e 76 65   when type conve
2e320 72 73 69 6f 6e 73 20 6f 63 63 75 72 2c 20 70 6f  rsions occur, po
2e330 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 20  inters returned 
2e340 62 79 20 70 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c  by prior.** call
2e350 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c  s to sqlite3_col
2e360 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69  umn_blob(), sqli
2e370 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
2e380 29 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c  ), and/or.** sql
2e390 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2e3a0 31 36 28 29 20 6d 61 79 20 62 65 20 69 6e 76 61  16() may be inva
2e3b0 6c 69 64 61 74 65 64 2e 0a 2a 2a 20 54 79 70 65  lidated..** Type
2e3c0 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 61 6e 64   conversions and
2e3d0 20 70 6f 69 6e 74 65 72 20 69 6e 76 61 6c 69 64   pointer invalid
2e3e0 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 6f 63 63  ations might occ
2e3f0 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20 66 6f 6c  ur.** in the fol
2e400 6c 6f 77 69 6e 67 20 63 61 73 65 73 3a 0a 2a 2a  lowing cases:.**
2e410 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
2e420 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e   The initial con
2e430 74 65 6e 74 20 69 73 20 61 20 42 4c 4f 42 20 61  tent is a BLOB a
2e440 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nd sqlite3_colum
2e450 6e 5f 74 65 78 74 28 29 20 6f 72 0a 2a 2a 20 20  n_text() or.**  
2e460 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75      sqlite3_colu
2e470 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20 63  mn_text16() is c
2e480 61 6c 6c 65 64 2e 20 20 41 20 7a 65 72 6f 2d 74  alled.  A zero-t
2e490 65 72 6d 69 6e 61 74 6f 72 20 6d 69 67 68 74 0a  erminator might.
2e4a0 2a 2a 20 20 20 20 20 20 6e 65 65 64 20 74 6f 20  **      need to 
2e4b0 62 65 20 61 64 64 65 64 20 74 6f 20 74 68 65 20  be added to the 
2e4c0 73 74 72 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20  string.</li>.** 
2e4d0 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c  <li> The initial
2e4e0 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d   content is UTF-
2e4f0 38 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74  8 text and sqlit
2e500 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
2e510 36 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73  6() or.**      s
2e520 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2e530 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64  xt16() is called
2e540 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d  .  The content m
2e550 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64  ust be converted
2e560 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d  .**      to UTF-
2e570 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e  16.</li>.** <li>
2e580 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e   The initial con
2e590 74 65 6e 74 20 69 73 20 55 54 46 2d 31 36 20 74  tent is UTF-16 t
2e5a0 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  ext and sqlite3_
2e5b0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f  column_bytes() o
2e5c0 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65  r.**      sqlite
2e5d0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20  3_column_text() 
2e5e0 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20  is called.  The 
2e5f0 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20  content must be 
2e600 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20  converted.**    
2e610 20 20 74 6f 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e    to UTF-8.</li>
2e620 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
2e630 5e 43 6f 6e 76 65 72 73 69 6f 6e 73 20 62 65 74  ^Conversions bet
2e640 77 65 65 6e 20 55 54 46 2d 31 36 62 65 20 61 6e  ween UTF-16be an
2e650 64 20 55 54 46 2d 31 36 6c 65 20 61 72 65 20 61  d UTF-16le are a
2e660 6c 77 61 79 73 20 64 6f 6e 65 20 69 6e 20 70 6c  lways done in pl
2e670 61 63 65 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f  ace and do.** no
2e680 74 20 69 6e 76 61 6c 69 64 61 74 65 20 61 20 70  t invalidate a p
2e690 72 69 6f 72 20 70 6f 69 6e 74 65 72 2c 20 74 68  rior pointer, th
2e6a0 6f 75 67 68 20 6f 66 20 63 6f 75 72 73 65 20 74  ough of course t
2e6b0 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68  he content of th
2e6c0 65 20 62 75 66 66 65 72 0a 2a 2a 20 74 68 61 74  e buffer.** that
2e6d0 20 74 68 65 20 70 72 69 6f 72 20 70 6f 69 6e 74   the prior point
2e6e0 65 72 20 72 65 66 65 72 65 6e 63 65 73 20 77 69  er references wi
2e6f0 6c 6c 20 68 61 76 65 20 62 65 65 6e 20 6d 6f 64  ll have been mod
2e700 69 66 69 65 64 2e 20 20 4f 74 68 65 72 20 6b 69  ified.  Other ki
2e710 6e 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65 72  nds.** of conver
2e720 73 69 6f 6e 20 61 72 65 20 64 6f 6e 65 20 69 6e  sion are done in
2e730 20 70 6c 61 63 65 20 77 68 65 6e 20 69 74 20 69   place when it i
2e740 73 20 70 6f 73 73 69 62 6c 65 2c 20 62 75 74 20  s possible, but 
2e750 73 6f 6d 65 74 69 6d 65 73 20 74 68 65 79 0a 2a  sometimes they.*
2e760 2a 20 61 72 65 20 6e 6f 74 20 70 6f 73 73 69 62  * are not possib
2e770 6c 65 20 61 6e 64 20 69 6e 20 74 68 6f 73 65 20  le and in those 
2e780 63 61 73 65 73 20 70 72 69 6f 72 20 70 6f 69 6e  cases prior poin
2e790 74 65 72 73 20 61 72 65 20 69 6e 76 61 6c 69 64  ters are invalid
2e7a0 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ated..**.** The 
2e7b0 73 61 66 65 73 74 20 61 6e 64 20 65 61 73 69 65  safest and easie
2e7c0 73 74 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 70  st to remember p
2e7d0 6f 6c 69 63 79 20 69 73 20 74 6f 20 69 6e 76 6f  olicy is to invo
2e7e0 6b 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  ke these routine
2e7f0 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f 66 20 74  s.** in one of t
2e800 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 77 61 79  he following way
2e810 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
2e820 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f    <li>sqlite3_co
2e830 6c 75 6d 6e 5f 74 65 78 74 28 29 20 66 6f 6c 6c  lumn_text() foll
2e840 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  owed by sqlite3_
2e850 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f  column_bytes()</
2e860 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69  li>.**  <li>sqli
2e870 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
2e880 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71  ) followed by sq
2e890 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2e8a0 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c  es()</li>.**  <l
2e8b0 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  i>sqlite3_column
2e8c0 5f 74 65 78 74 31 36 28 29 20 66 6f 6c 6c 6f 77  _text16() follow
2e8d0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
2e8e0 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 3c 2f  lumn_bytes16()</
2e8f0 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a  li>.** </ul>.**.
2e900 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  ** In other word
2e910 73 2c 20 79 6f 75 20 73 68 6f 75 6c 64 20 63 61  s, you should ca
2e920 6c 6c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ll sqlite3_colum
2e930 6e 5f 74 65 78 74 28 29 2c 0a 2a 2a 20 73 71 6c  n_text(),.** sql
2e940 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
2e950 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f 63  (), or sqlite3_c
2e960 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66  olumn_text16() f
2e970 69 72 73 74 20 74 6f 20 66 6f 72 63 65 20 74 68  irst to force th
2e980 65 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 74 6f  e result.** into
2e990 20 74 68 65 20 64 65 73 69 72 65 64 20 66 6f 72   the desired for
2e9a0 6d 61 74 2c 20 74 68 65 6e 20 69 6e 76 6f 6b 65  mat, then invoke
2e9b0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2e9c0 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 73 71  bytes() or.** sq
2e9d0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2e9e0 65 73 31 36 28 29 20 74 6f 20 66 69 6e 64 20 74  es16() to find t
2e9f0 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 72  he size of the r
2ea00 65 73 75 6c 74 2e 20 20 44 6f 20 6e 6f 74 20 6d  esult.  Do not m
2ea10 69 78 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 73  ix calls.** to s
2ea20 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2ea30 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  xt() or sqlite3_
2ea40 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 77 69  column_blob() wi
2ea50 74 68 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73  th calls to.** s
2ea60 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2ea70 74 65 73 31 36 28 29 2c 20 61 6e 64 20 64 6f 20  tes16(), and do 
2ea80 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 20 74 6f  not mix calls to
2ea90 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2eaa0 74 65 78 74 31 36 28 29 0a 2a 2a 20 77 69 74 68  text16().** with
2eab0 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
2eac0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
2ead0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 6f 69  ..**.** ^The poi
2eae0 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 61  nters returned a
2eaf0 72 65 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 61  re valid until a
2eb00 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e   type conversion
2eb10 20 6f 63 63 75 72 73 20 61 73 0a 2a 2a 20 64 65   occurs as.** de
2eb20 73 63 72 69 62 65 64 20 61 62 6f 76 65 2c 20 6f  scribed above, o
2eb30 72 20 75 6e 74 69 6c 20 5b 73 71 6c 69 74 65 33  r until [sqlite3
2eb40 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c  _step()] or [sql
2eb50 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72  ite3_reset()] or
2eb60 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  .** [sqlite3_fin
2eb70 61 6c 69 7a 65 28 29 5d 20 69 73 20 63 61 6c 6c  alize()] is call
2eb80 65 64 2e 20 20 5e 54 68 65 20 6d 65 6d 6f 72 79  ed.  ^The memory
2eb90 20 73 70 61 63 65 20 75 73 65 64 20 74 6f 20 68   space used to h
2eba0 6f 6c 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20 61  old strings.** a
2ebb0 6e 64 20 42 4c 4f 42 73 20 69 73 20 66 72 65 65  nd BLOBs is free
2ebc0 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e  d automatically.
2ebd0 20 20 44 6f 20 3c 62 3e 6e 6f 74 3c 2f 62 3e 20    Do <b>not</b> 
2ebe0 70 61 73 73 20 74 68 65 20 70 6f 69 6e 74 65 72  pass the pointer
2ebf0 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72  s returned.** fr
2ec00 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  om [sqlite3_colu
2ec10 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c  mn_blob()], [sql
2ec20 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2ec30 28 29 5d 2c 20 65 74 63 2e 20 69 6e 74 6f 0a 2a  ()], etc. into.*
2ec40 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  * [sqlite3_free(
2ec50 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61  )]..**.** ^(If a
2ec60 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
2ec70 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20  on error occurs 
2ec80 64 75 72 69 6e 67 20 74 68 65 20 65 76 61 6c 75  during the evalu
2ec90 61 74 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20  ation of any.** 
2eca0 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
2ecb0 73 2c 20 61 20 64 65 66 61 75 6c 74 20 76 61 6c  s, a default val
2ecc0 75 65 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  ue is returned. 
2ecd0 20 54 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c   The default val
2ece0 75 65 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20  ue.** is either 
2ecf0 74 68 65 20 69 6e 74 65 67 65 72 20 30 2c 20 74  the integer 0, t
2ed00 68 65 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e  he floating poin
2ed10 74 20 6e 75 6d 62 65 72 20 30 2e 30 2c 20 6f 72  t number 0.0, or
2ed20 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74   a NULL.** point
2ed30 65 72 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20  er.  Subsequent 
2ed40 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
2ed50 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 77 69 6c  3_errcode()] wil
2ed60 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c  l return.** [SQL
2ed70 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 29 5e 0a 2a 2f  ITE_NOMEM].)^.*/
2ed80 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
2ed90 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
2eda0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2edb0 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73  int iCol);.int s
2edc0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2edd0 74 65 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  tes(sqlite3_stmt
2ede0 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e  *, int iCol);.in
2edf0 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  t sqlite3_column
2ee00 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74 65 33  _bytes16(sqlite3
2ee10 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
2ee20 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74 65  );.double sqlite
2ee30 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28  3_column_double(
2ee40 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2ee50 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71  nt iCol);.int sq
2ee60 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74  lite3_column_int
2ee70 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2ee80 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74  int iCol);.sqlit
2ee90 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
2eea0 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28 73 71  _column_int64(sq
2eeb0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2eec0 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 75 6e   iCol);.const un
2eed0 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c  signed char *sql
2eee0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2eef0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2ef00 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74  int iCol);.const
2ef10 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
2ef20 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 73 71 6c  olumn_text16(sql
2ef30 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
2ef40 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74  iCol);.int sqlit
2ef50 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 73  e3_column_type(s
2ef60 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2ef70 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33  t iCol);.sqlite3
2ef80 5f 76 61 6c 75 65 20 2a 73 71 6c 69 74 65 33 5f  _value *sqlite3_
2ef90 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 73 71 6c  column_value(sql
2efa0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
2efb0 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  iCol);../*.** CA
2efc0 50 49 33 52 45 46 3a 20 44 65 73 74 72 6f 79 20  PI3REF: Destroy 
2efd0 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  A Prepared State
2efe0 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a  ment Object.**.*
2eff0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66  * ^The sqlite3_f
2f000 69 6e 61 6c 69 7a 65 28 29 20 66 75 6e 63 74 69  inalize() functi
2f010 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20  on is called to 
2f020 64 65 6c 65 74 65 20 61 20 5b 70 72 65 70 61 72  delete a [prepar
2f030 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a  ed statement]..*
2f040 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72  * ^If the most r
2f050 65 63 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e  ecent evaluation
2f060 20 6f 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e   of the statemen
2f070 74 20 65 6e 63 6f 75 6e 74 65 72 65 64 20 6e 6f  t encountered no
2f080 20 65 72 72 6f 72 73 0a 2a 2a 20 6f 72 20 69 66   errors.** or if
2f090 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
2f0a0 73 20 6e 65 76 65 72 20 62 65 65 6e 20 65 76 61  s never been eva
2f0b0 6c 75 61 74 65 64 2c 20 74 68 65 6e 20 73 71 6c  luated, then sql
2f0c0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20  ite3_finalize() 
2f0d0 72 65 74 75 72 6e 73 0a 2a 2a 20 53 51 4c 49 54  returns.** SQLIT
2f0e0 45 5f 4f 4b 2e 20 20 5e 49 66 20 74 68 65 20 6d  E_OK.  ^If the m
2f0f0 6f 73 74 20 72 65 63 65 6e 74 20 65 76 61 6c 75  ost recent evalu
2f100 61 74 69 6f 6e 20 6f 66 20 73 74 61 74 65 6d 65  ation of stateme
2f110 6e 74 20 53 20 66 61 69 6c 65 64 2c 20 74 68 65  nt S failed, the
2f120 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 69 6e  n.** sqlite3_fin
2f130 61 6c 69 7a 65 28 53 29 20 72 65 74 75 72 6e 73  alize(S) returns
2f140 20 74 68 65 20 61 70 70 72 6f 70 72 69 61 74 65   the appropriate
2f150 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72   [error code] or
2f160 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 65 72  .** [extended er
2f170 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a  ror code]..**.**
2f180 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66 69   ^The sqlite3_fi
2f190 6e 61 6c 69 7a 65 28 53 29 20 72 6f 75 74 69 6e  nalize(S) routin
2f1a0 65 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20  e can be called 
2f1b0 61 74 20 61 6e 79 20 70 6f 69 6e 74 20 64 75 72  at any point dur
2f1c0 69 6e 67 0a 2a 2a 20 74 68 65 20 6c 69 66 65 20  ing.** the life 
2f1d0 63 79 63 6c 65 20 6f 66 20 5b 70 72 65 70 61 72  cycle of [prepar
2f1e0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 3a  ed statement] S:
2f1f0 0a 2a 2a 20 62 65 66 6f 72 65 20 73 74 61 74 65  .** before state
2f200 6d 65 6e 74 20 53 20 69 73 20 65 76 65 72 20 65  ment S is ever e
2f210 76 61 6c 75 61 74 65 64 2c 20 61 66 74 65 72 0a  valuated, after.
2f220 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 63  ** one or more c
2f230 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
2f240 5f 72 65 73 65 74 28 29 5d 2c 20 6f 72 20 61 66  _reset()], or af
2f250 74 65 72 20 61 6e 79 20 63 61 6c 6c 0a 2a 2a 20  ter any call.** 
2f260 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
2f270 28 29 5d 20 72 65 67 61 72 64 6c 65 73 73 20 6f  ()] regardless o
2f280 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  f whether or not
2f290 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68   the statement h
2f2a0 61 73 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 64 20  as.** completed 
2f2b0 65 78 65 63 75 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  execution..**.**
2f2c0 20 5e 49 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74   ^Invoking sqlit
2f2d0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 6f 6e  e3_finalize() on
2f2e0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
2f2f0 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f  is a harmless no
2f300 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61  -op..**.** The a
2f310 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
2f320 66 69 6e 61 6c 69 7a 65 20 65 76 65 72 79 20 5b  finalize every [
2f330 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2f340 6e 74 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  nt] in order to 
2f350 61 76 6f 69 64 0a 2a 2a 20 72 65 73 6f 75 72 63  avoid.** resourc
2f360 65 20 6c 65 61 6b 73 2e 20 20 49 74 20 69 73 20  e leaks.  It is 
2f370 61 20 67 72 69 65 76 6f 75 73 20 65 72 72 6f 72  a grievous error
2f380 20 66 6f 72 20 74 68 65 20 61 70 70 6c 69 63 61   for the applica
2f390 74 69 6f 6e 20 74 6f 20 74 72 79 20 74 6f 20 75  tion to try to u
2f3a0 73 65 0a 2a 2a 20 61 20 70 72 65 70 61 72 65 64  se.** a prepared
2f3b0 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72   statement after
2f3c0 20 69 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e   it has been fin
2f3d0 61 6c 69 7a 65 64 2e 20 20 41 6e 79 20 75 73 65  alized.  Any use
2f3e0 20 6f 66 20 61 20 70 72 65 70 61 72 65 64 0a 2a   of a prepared.*
2f3f0 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65  * statement afte
2f400 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 66 69  r it has been fi
2f410 6e 61 6c 69 7a 65 64 20 63 61 6e 20 72 65 73 75  nalized can resu
2f420 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20  lt in undefined 
2f430 61 6e 64 0a 2a 2a 20 75 6e 64 65 73 69 72 61 62  and.** undesirab
2f440 6c 65 20 62 65 68 61 76 69 6f 72 20 73 75 63 68  le behavior such
2f450 20 61 73 20 73 65 67 66 61 75 6c 74 73 20 61 6e   as segfaults an
2f460 64 20 68 65 61 70 20 63 6f 72 72 75 70 74 69 6f  d heap corruptio
2f470 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  n..*/.int sqlite
2f480 33 5f 66 69 6e 61 6c 69 7a 65 28 73 71 6c 69 74  3_finalize(sqlit
2f490 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
2f4a0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2f4b0 3a 20 52 65 73 65 74 20 41 20 50 72 65 70 61 72  : Reset A Prepar
2f4c0 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a  ed Statement Obj
2f4d0 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ect.**.** The sq
2f4e0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 20 66 75  lite3_reset() fu
2f4f0 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64  nction is called
2f500 20 74 6f 20 72 65 73 65 74 20 61 20 5b 70 72 65   to reset a [pre
2f510 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2f520 0a 2a 2a 20 6f 62 6a 65 63 74 20 62 61 63 6b 20  .** object back 
2f530 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73  to its initial s
2f540 74 61 74 65 2c 20 72 65 61 64 79 20 74 6f 20 62  tate, ready to b
2f550 65 20 72 65 2d 65 78 65 63 75 74 65 64 2e 0a 2a  e re-executed..*
2f560 2a 20 5e 41 6e 79 20 53 51 4c 20 73 74 61 74 65  * ^Any SQL state
2f570 6d 65 6e 74 20 76 61 72 69 61 62 6c 65 73 20 74  ment variables t
2f580 68 61 74 20 68 61 64 20 76 61 6c 75 65 73 20 62  hat had values b
2f590 6f 75 6e 64 20 74 6f 20 74 68 65 6d 20 75 73 69  ound to them usi
2f5a0 6e 67 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74  ng.** the [sqlit
2f5b0 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73  e3_bind_blob | s
2f5c0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20  qlite3_bind_*() 
2f5d0 41 50 49 5d 20 72 65 74 61 69 6e 20 74 68 65 69  API] retain thei
2f5e0 72 20 76 61 6c 75 65 73 2e 0a 2a 2a 20 55 73 65  r values..** Use
2f5f0 20 5b 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f   [sqlite3_clear_
2f600 62 69 6e 64 69 6e 67 73 28 29 5d 20 74 6f 20 72  bindings()] to r
2f610 65 73 65 74 20 74 68 65 20 62 69 6e 64 69 6e 67  eset the binding
2f620 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73  s..**.** ^The [s
2f630 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d  qlite3_reset(S)]
2f640 20 69 6e 74 65 72 66 61 63 65 20 72 65 73 65 74   interface reset
2f650 73 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  s the [prepared 
2f660 73 74 61 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a 20  statement] S.** 
2f670 62 61 63 6b 20 74 6f 20 74 68 65 20 62 65 67 69  back to the begi
2f680 6e 6e 69 6e 67 20 6f 66 20 69 74 73 20 70 72 6f  nning of its pro
2f690 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  gram..**.** ^If 
2f6a0 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
2f6b0 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
2f6c0 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68  _step(S)] for th
2f6d0 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  e.** [prepared s
2f6e0 74 61 74 65 6d 65 6e 74 5d 20 53 20 72 65 74 75  tatement] S retu
2f6f0 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57  rned [SQLITE_ROW
2f700 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e  ] or [SQLITE_DON
2f710 45 5d 2c 0a 2a 2a 20 6f 72 20 69 66 20 5b 73 71  E],.** or if [sq
2f720 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 68  lite3_step(S)] h
2f730 61 73 20 6e 65 76 65 72 20 62 65 66 6f 72 65 20  as never before 
2f740 62 65 65 6e 20 63 61 6c 6c 65 64 20 6f 6e 20 53  been called on S
2f750 2c 0a 2a 2a 20 74 68 65 6e 20 5b 73 71 6c 69 74  ,.** then [sqlit
2f760 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74  e3_reset(S)] ret
2f770 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  urns [SQLITE_OK]
2f780 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
2f790 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c  most recent call
2f7a0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   to [sqlite3_ste
2f7b0 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a  p(S)] for the.**
2f7c0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2f7d0 6d 65 6e 74 5d 20 53 20 69 6e 64 69 63 61 74 65  ment] S indicate
2f7e0 64 20 61 6e 20 65 72 72 6f 72 2c 20 74 68 65 6e  d an error, then
2f7f0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  .** [sqlite3_res
2f800 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20 61  et(S)] returns a
2f810 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65  n appropriate [e
2f820 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a  rror code]..**.*
2f830 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  * ^The [sqlite3_
2f840 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66  reset(S)] interf
2f850 61 63 65 20 64 6f 65 73 20 6e 6f 74 20 63 68 61  ace does not cha
2f860 6e 67 65 20 74 68 65 20 76 61 6c 75 65 73 0a 2a  nge the values.*
2f870 2a 20 6f 66 20 61 6e 79 20 5b 73 71 6c 69 74 65  * of any [sqlite
2f880 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 62 69 6e 64  3_bind_blob|bind
2f890 69 6e 67 73 5d 20 6f 6e 20 74 68 65 20 5b 70 72  ings] on the [pr
2f8a0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2f8b0 5d 20 53 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ] S..*/.int sqli
2f8c0 74 65 33 5f 72 65 73 65 74 28 73 71 6c 69 74 65  te3_reset(sqlite
2f8d0 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
2f8e0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2f8f0 20 43 72 65 61 74 65 20 4f 72 20 52 65 64 65 66   Create Or Redef
2f900 69 6e 65 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e  ine SQL Function
2f910 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  s.** KEYWORDS: {
2f920 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f  function creatio
2f930 6e 20 72 6f 75 74 69 6e 65 73 7d 0a 2a 2a 20 4b  n routines}.** K
2f940 45 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63  EYWORDS: {applic
2f950 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
2f960 4c 20 66 75 6e 63 74 69 6f 6e 7d 0a 2a 2a 20 4b  L function}.** K
2f970 45 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63  EYWORDS: {applic
2f980 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
2f990 4c 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a  L functions}.**.
2f9a0 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69  ** ^These functi
2f9b0 6f 6e 73 20 28 63 6f 6c 6c 65 63 74 69 76 65 6c  ons (collectivel
2f9c0 79 20 6b 6e 6f 77 6e 20 61 73 20 22 66 75 6e 63  y known as "func
2f9d0 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f  tion creation ro
2f9e0 75 74 69 6e 65 73 22 29 0a 2a 2a 20 61 72 65 20  utines").** are 
2f9f0 75 73 65 64 20 74 6f 20 61 64 64 20 53 51 4c 20  used to add SQL 
2fa00 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67  functions or agg
2fa10 72 65 67 61 74 65 73 20 6f 72 20 74 6f 20 72 65  regates or to re
2fa20 64 65 66 69 6e 65 20 74 68 65 20 62 65 68 61 76  define the behav
2fa30 69 6f 72 0a 2a 2a 20 6f 66 20 65 78 69 73 74 69  ior.** of existi
2fa40 6e 67 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ng SQL functions
2fa50 20 6f 72 20 61 67 67 72 65 67 61 74 65 73 2e 20   or aggregates. 
2fa60 20 54 68 65 20 6f 6e 6c 79 20 64 69 66 66 65 72   The only differ
2fa70 65 6e 63 65 73 20 62 65 74 77 65 65 6e 0a 2a 2a  ences between.**
2fa80 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
2fa90 61 72 65 20 74 68 65 20 74 65 78 74 20 65 6e 63  are the text enc
2faa0 6f 64 69 6e 67 20 65 78 70 65 63 74 65 64 20 66  oding expected f
2fab0 6f 72 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64  or.** the second
2fac0 20 70 61 72 61 6d 65 74 65 72 20 28 74 68 65 20   parameter (the 
2fad0 6e 61 6d 65 20 6f 66 20 74 68 65 20 66 75 6e 63  name of the func
2fae0 74 69 6f 6e 20 62 65 69 6e 67 20 63 72 65 61 74  tion being creat
2faf0 65 64 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20 70  ed).** and the p
2fb00 72 65 73 65 6e 63 65 20 6f 72 20 61 62 73 65 6e  resence or absen
2fb10 63 65 20 6f 66 20 61 20 64 65 73 74 72 75 63 74  ce of a destruct
2fb20 6f 72 20 63 61 6c 6c 62 61 63 6b 20 66 6f 72 0a  or callback for.
2fb30 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ** the applicati
2fb40 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 2e  on data pointer.
2fb50 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
2fb60 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  t parameter is t
2fb70 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
2fb80 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 77 68 69 63  nection] to whic
2fb90 68 20 74 68 65 20 53 51 4c 0a 2a 2a 20 66 75 6e  h the SQL.** fun
2fba0 63 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 20 61  ction is to be a
2fbb0 64 64 65 64 2e 20 20 5e 49 66 20 61 6e 20 61 70  dded.  ^If an ap
2fbc0 70 6c 69 63 61 74 69 6f 6e 20 75 73 65 73 20 6d  plication uses m
2fbd0 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 64 61 74  ore than one dat
2fbe0 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74  abase.** connect
2fbf0 69 6f 6e 20 74 68 65 6e 20 61 70 70 6c 69 63 61  ion then applica
2fc00 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
2fc10 20 66 75 6e 63 74 69 6f 6e 73 20 6d 75 73 74 20   functions must 
2fc20 62 65 20 61 64 64 65 64 0a 2a 2a 20 74 6f 20 65  be added.** to e
2fc30 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ach database con
2fc40 6e 65 63 74 69 6f 6e 20 73 65 70 61 72 61 74 65  nection separate
2fc50 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ly..**.** ^The s
2fc60 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
2fc70 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  is the name of t
2fc80 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
2fc90 74 6f 20 62 65 20 63 72 65 61 74 65 64 20 6f 72  to be created or
2fca0 0a 2a 2a 20 72 65 64 65 66 69 6e 65 64 2e 20 20  .** redefined.  
2fcb0 5e 54 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74  ^The length of t
2fcc0 68 65 20 6e 61 6d 65 20 69 73 20 6c 69 6d 69 74  he name is limit
2fcd0 65 64 20 74 6f 20 32 35 35 20 62 79 74 65 73 20  ed to 255 bytes 
2fce0 69 6e 20 61 20 55 54 46 2d 38 0a 2a 2a 20 72 65  in a UTF-8.** re
2fcf0 70 72 65 73 65 6e 74 61 74 69 6f 6e 2c 20 65 78  presentation, ex
2fd00 63 6c 75 73 69 76 65 20 6f 66 20 74 68 65 20 7a  clusive of the z
2fd10 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 2e 20  ero-terminator. 
2fd20 20 5e 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20   ^Note that the 
2fd30 6e 61 6d 65 0a 2a 2a 20 6c 65 6e 67 74 68 20 6c  name.** length l
2fd40 69 6d 69 74 20 69 73 20 69 6e 20 55 54 46 2d 38  imit is in UTF-8
2fd50 20 62 79 74 65 73 2c 20 6e 6f 74 20 63 68 61 72   bytes, not char
2fd60 61 63 74 65 72 73 20 6e 6f 72 20 55 54 46 2d 31  acters nor UTF-1
2fd70 36 20 62 79 74 65 73 2e 20 20 0a 2a 2a 20 5e 41  6 bytes.  .** ^A
2fd80 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 63 72  ny attempt to cr
2fd90 65 61 74 65 20 61 20 66 75 6e 63 74 69 6f 6e 20  eate a function 
2fda0 77 69 74 68 20 61 20 6c 6f 6e 67 65 72 20 6e 61  with a longer na
2fdb0 6d 65 0a 2a 2a 20 77 69 6c 6c 20 72 65 73 75 6c  me.** will resul
2fdc0 74 20 69 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53  t in [SQLITE_MIS
2fdd0 55 53 45 5d 20 62 65 69 6e 67 20 72 65 74 75 72  USE] being retur
2fde0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ned..**.** ^The 
2fdf0 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
2fe00 28 6e 41 72 67 29 0a 2a 2a 20 69 73 20 74 68 65  (nArg).** is the
2fe10 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d   number of argum
2fe20 65 6e 74 73 20 74 68 61 74 20 74 68 65 20 53 51  ents that the SQ
2fe30 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a  L function or.**
2fe40 20 61 67 67 72 65 67 61 74 65 20 74 61 6b 65 73   aggregate takes
2fe50 2e 20 5e 49 66 20 74 68 69 73 20 70 61 72 61 6d  . ^If this param
2fe60 65 74 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e  eter is -1, then
2fe70 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
2fe80 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74  n or.** aggregat
2fe90 65 20 6d 61 79 20 74 61 6b 65 20 61 6e 79 20 6e  e may take any n
2fea0 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e  umber of argumen
2feb0 74 73 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64  ts between 0 and
2fec0 20 74 68 65 20 6c 69 6d 69 74 0a 2a 2a 20 73 65   the limit.** se
2fed0 74 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 69  t by [sqlite3_li
2fee0 6d 69 74 5d 28 5b 53 51 4c 49 54 45 5f 4c 49 4d  mit]([SQLITE_LIM
2fef0 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d  IT_FUNCTION_ARG]
2ff00 29 2e 20 20 49 66 20 74 68 65 20 74 68 69 72 64  ).  If the third
2ff10 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 69 73  .** parameter is
2ff20 20 6c 65 73 73 20 74 68 61 6e 20 2d 31 20 6f 72   less than -1 or
2ff30 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 31 32   greater than 12
2ff40 37 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  7 then the behav
2ff50 69 6f 72 20 69 73 0a 2a 2a 20 75 6e 64 65 66 69  ior is.** undefi
2ff60 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ned..**.** ^The 
2ff70 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
2ff80 2c 20 65 54 65 78 74 52 65 70 2c 20 73 70 65 63  , eTextRep, spec
2ff90 69 66 69 65 73 20 77 68 61 74 0a 2a 2a 20 5b 53  ifies what.** [S
2ffa0 51 4c 49 54 45 5f 55 54 46 38 20 7c 20 74 65 78  QLITE_UTF8 | tex
2ffb0 74 20 65 6e 63 6f 64 69 6e 67 5d 20 74 68 69 73  t encoding] this
2ffc0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 70 72   SQL function pr
2ffd0 65 66 65 72 73 20 66 6f 72 0a 2a 2a 20 69 74 73  efers for.** its
2ffe0 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 45 76   parameters.  Ev
2fff0 65 72 79 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ery SQL function
30000 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
30010 6d 75 73 74 20 62 65 20 61 62 6c 65 20 74 6f 20  must be able to 
30020 77 6f 72 6b 0a 2a 2a 20 77 69 74 68 20 55 54 46  work.** with UTF
30030 2d 38 2c 20 55 54 46 2d 31 36 6c 65 2c 20 6f 72  -8, UTF-16le, or
30040 20 55 54 46 2d 31 36 62 65 2e 20 20 42 75 74 20   UTF-16be.  But 
30050 73 6f 6d 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  some implementat
30060 69 6f 6e 73 20 6d 61 79 20 62 65 0a 2a 2a 20 6d  ions may be.** m
30070 6f 72 65 20 65 66 66 69 63 69 65 6e 74 20 77 69  ore efficient wi
30080 74 68 20 6f 6e 65 20 65 6e 63 6f 64 69 6e 67 20  th one encoding 
30090 74 68 61 6e 20 61 6e 6f 74 68 65 72 2e 20 20 5e  than another.  ^
300a0 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  An application m
300b0 61 79 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c  ay.** invoke sql
300c0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
300d0 74 69 6f 6e 28 29 20 6f 72 20 73 71 6c 69 74 65  tion() or sqlite
300e0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
300f0 6e 31 36 28 29 20 6d 75 6c 74 69 70 6c 65 0a 2a  n16() multiple.*
30100 2a 20 74 69 6d 65 73 20 77 69 74 68 20 74 68 65  * times with the
30110 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 62   same function b
30120 75 74 20 77 69 74 68 20 64 69 66 66 65 72 65 6e  ut with differen
30130 74 20 76 61 6c 75 65 73 20 6f 66 20 65 54 65 78  t values of eTex
30140 74 52 65 70 2e 0a 2a 2a 20 5e 57 68 65 6e 20 6d  tRep..** ^When m
30150 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e  ultiple implemen
30160 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73  tations of the s
30170 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 61 72 65  ame function are
30180 20 61 76 61 69 6c 61 62 6c 65 2c 20 53 51 4c 69   available, SQLi
30190 74 65 0a 2a 2a 20 77 69 6c 6c 20 70 69 63 6b 20  te.** will pick 
301a0 74 68 65 20 6f 6e 65 20 74 68 61 74 20 69 6e 76  the one that inv
301b0 6f 6c 76 65 73 20 74 68 65 20 6c 65 61 73 74 20  olves the least 
301c0 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74 61 20 63  amount of data c
301d0 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 20 49 66  onversion..** If
301e0 20 74 68 65 72 65 20 69 73 20 6f 6e 6c 79 20 61   there is only a
301f0 20 73 69 6e 67 6c 65 20 69 6d 70 6c 65 6d 65 6e   single implemen
30200 74 61 74 69 6f 6e 20 77 68 69 63 68 20 64 6f 65  tation which doe
30210 73 20 6e 6f 74 20 63 61 72 65 20 77 68 61 74 20  s not care what 
30220 74 65 78 74 0a 2a 2a 20 65 6e 63 6f 64 69 6e 67  text.** encoding
30230 20 69 73 20 75 73 65 64 2c 20 74 68 65 6e 20 74   is used, then t
30240 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65  he fourth argume
30250 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 5b 53 51  nt should be [SQ
30260 4c 49 54 45 5f 41 4e 59 5d 2e 0a 2a 2a 0a 2a 2a  LITE_ANY]..**.**
30270 20 5e 28 54 68 65 20 66 69 66 74 68 20 70 61 72   ^(The fifth par
30280 61 6d 65 74 65 72 20 69 73 20 61 6e 20 61 72 62  ameter is an arb
30290 69 74 72 61 72 79 20 70 6f 69 6e 74 65 72 2e 20  itrary pointer. 
302a0 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   The implementat
302b0 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 66 75  ion of the.** fu
302c0 6e 63 74 69 6f 6e 20 63 61 6e 20 67 61 69 6e 20  nction can gain 
302d0 61 63 63 65 73 73 20 74 6f 20 74 68 69 73 20 70  access to this p
302e0 6f 69 6e 74 65 72 20 75 73 69 6e 67 20 5b 73 71  ointer using [sq
302f0 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28  lite3_user_data(
30300 29 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  )].)^.**.** ^The
30310 20 73 69 78 74 68 2c 20 73 65 76 65 6e 74 68 20   sixth, seventh 
30320 61 6e 64 20 65 69 67 68 74 68 20 70 61 72 61 6d  and eighth param
30330 65 74 65 72 73 2c 20 78 46 75 6e 63 2c 20 78 53  eters, xFunc, xS
30340 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 2c 20  tep and xFinal, 
30350 61 72 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20  are.** pointers 
30360 74 6f 20 43 2d 6c 61 6e 67 75 61 67 65 20 66 75  to C-language fu
30370 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 69 6d 70  nctions that imp
30380 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66  lement the SQL f
30390 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67  unction or.** ag
303a0 67 72 65 67 61 74 65 2e 20 5e 41 20 73 63 61 6c  gregate. ^A scal
303b0 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  ar SQL function 
303c0 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c  requires an impl
303d0 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68  ementation of th
303e0 65 20 78 46 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62  e xFunc.** callb
303f0 61 63 6b 20 6f 6e 6c 79 3b 20 4e 55 4c 4c 20 70  ack only; NULL p
30400 6f 69 6e 74 65 72 73 20 6d 75 73 74 20 62 65 20  ointers must be 
30410 70 61 73 73 65 64 20 61 73 20 74 68 65 20 78 53  passed as the xS
30420 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 0a 2a  tep and xFinal.*
30430 2a 20 70 61 72 61 6d 65 74 65 72 73 2e 20 5e 41  * parameters. ^A
30440 6e 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20  n aggregate SQL 
30450 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65  function require
30460 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  s an implementat
30470 69 6f 6e 20 6f 66 20 78 53 74 65 70 0a 2a 2a 20  ion of xStep.** 
30480 61 6e 64 20 78 46 69 6e 61 6c 20 61 6e 64 20 4e  and xFinal and N
30490 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6d 75 73 74  ULL pointer must
304a0 20 62 65 20 70 61 73 73 65 64 20 66 6f 72 20 78   be passed for x
304b0 46 75 6e 63 2e 20 5e 54 6f 20 64 65 6c 65 74 65  Func. ^To delete
304c0 20 61 6e 20 65 78 69 73 74 69 6e 67 0a 2a 2a 20   an existing.** 
304d0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20  SQL function or 
304e0 61 67 67 72 65 67 61 74 65 2c 20 70 61 73 73 20  aggregate, pass 
304f0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 66 6f  NULL pointers fo
30500 72 20 61 6c 6c 20 74 68 72 65 65 20 66 75 6e 63  r all three func
30510 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b  tion.** callback
30520 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74 68  s..**.** ^(If th
30530 65 20 6e 69 6e 74 68 20 70 61 72 61 6d 65 74 65  e ninth paramete
30540 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 65  r to sqlite3_cre
30550 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28  ate_function_v2(
30560 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a  ) is not NULL,.*
30570 2a 20 74 68 65 6e 20 69 74 20 69 73 20 64 65 73  * then it is des
30580 74 72 75 63 74 6f 72 20 66 6f 72 20 74 68 65 20  tructor for the 
30590 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61  application data
305a0 20 70 6f 69 6e 74 65 72 2e 20 0a 2a 2a 20 54 68   pointer. .** Th
305b0 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20  e destructor is 
305c0 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 74 68 65  invoked when the
305d0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 64 65 6c   function is del
305e0 65 74 65 64 2c 20 65 69 74 68 65 72 20 62 79 20  eted, either by 
305f0 62 65 69 6e 67 0a 2a 2a 20 6f 76 65 72 6c 6f 61  being.** overloa
30600 64 65 64 20 6f 72 20 77 68 65 6e 20 74 68 65 20  ded or when the 
30610 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
30620 69 6f 6e 20 63 6c 6f 73 65 73 2e 29 5e 0a 2a 2a  ion closes.)^.**
30630 20 5e 54 68 65 20 64 65 73 74 72 75 63 74 6f 72   ^The destructor
30640 20 69 73 20 61 6c 73 6f 20 69 6e 76 6f 6b 65 64   is also invoked
30650 20 69 66 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a   if the call to.
30660 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  ** sqlite3_creat
30670 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20  e_function_v2() 
30680 66 61 69 6c 73 2e 0a 2a 2a 20 5e 57 68 65 6e 20  fails..** ^When 
30690 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 63  the destructor c
306a0 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 74  allback of the t
306b0 65 6e 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  enth parameter i
306c0 73 20 69 6e 76 6f 6b 65 64 2c 20 69 74 0a 2a 2a  s invoked, it.**
306d0 20 69 73 20 70 61 73 73 65 64 20 61 20 73 69 6e   is passed a sin
306e0 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69  gle argument whi
306f0 63 68 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20  ch is a copy of 
30700 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
30710 64 61 74 61 20 0a 2a 2a 20 70 6f 69 6e 74 65 72  data .** pointer
30720 20 77 68 69 63 68 20 77 61 73 20 74 68 65 20 66   which was the f
30730 69 66 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  ifth parameter t
30740 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  o sqlite3_create
30750 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 2e 0a  _function_v2()..
30760 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 70 65 72  **.** ^It is per
30770 6d 69 74 74 65 64 20 74 6f 20 72 65 67 69 73 74  mitted to regist
30780 65 72 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c  er multiple impl
30790 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74  ementations of t
307a0 68 65 20 73 61 6d 65 0a 2a 2a 20 66 75 6e 63 74  he same.** funct
307b0 69 6f 6e 73 20 77 69 74 68 20 74 68 65 20 73 61  ions with the sa
307c0 6d 65 20 6e 61 6d 65 20 62 75 74 20 77 69 74 68  me name but with
307d0 20 65 69 74 68 65 72 20 64 69 66 66 65 72 69 6e   either differin
307e0 67 20 6e 75 6d 62 65 72 73 20 6f 66 0a 2a 2a 20  g numbers of.** 
307f0 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 64 69 66  arguments or dif
30800 66 65 72 69 6e 67 20 70 72 65 66 65 72 72 65 64  fering preferred
30810 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 2e   text encodings.
30820 20 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75    ^SQLite will u
30830 73 65 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d  se.** the implem
30840 65 6e 74 61 74 69 6f 6e 20 74 68 61 74 20 6d 6f  entation that mo
30850 73 74 20 63 6c 6f 73 65 6c 79 20 6d 61 74 63 68  st closely match
30860 65 73 20 74 68 65 20 77 61 79 20 69 6e 20 77 68  es the way in wh
30870 69 63 68 20 74 68 65 0a 2a 2a 20 53 51 4c 20 66  ich the.** SQL f
30880 75 6e 63 74 69 6f 6e 20 69 73 20 75 73 65 64 2e  unction is used.
30890 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 69 6d    ^A function im
308a0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74  plementation wit
308b0 68 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65  h a non-negative
308c0 0a 2a 2a 20 6e 41 72 67 20 70 61 72 61 6d 65 74  .** nArg paramet
308d0 65 72 20 69 73 20 61 20 62 65 74 74 65 72 20 6d  er is a better m
308e0 61 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63  atch than a func
308f0 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  tion implementat
30900 69 6f 6e 20 77 69 74 68 0a 2a 2a 20 61 20 6e 65  ion with.** a ne
30910 67 61 74 69 76 65 20 6e 41 72 67 2e 20 20 5e 41  gative nArg.  ^A
30920 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20   function where 
30930 74 68 65 20 70 72 65 66 65 72 72 65 64 20 74 65  the preferred te
30940 78 74 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 6d  xt encoding.** m
30950 61 74 63 68 65 73 20 74 68 65 20 64 61 74 61 62  atches the datab
30960 61 73 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20  ase encoding is 
30970 61 20 62 65 74 74 65 72 0a 2a 2a 20 6d 61 74 63  a better.** matc
30980 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f  h than a functio
30990 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f  n where the enco
309a0 64 69 6e 67 20 69 73 20 64 69 66 66 65 72 65 6e  ding is differen
309b0 74 2e 20 20 0a 2a 2a 20 5e 41 20 66 75 6e 63 74  t.  .** ^A funct
309c0 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e  ion where the en
309d0 63 6f 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63  coding differenc
309e0 65 20 69 73 20 62 65 74 77 65 65 6e 20 55 54 46  e is between UTF
309f0 31 36 6c 65 20 61 6e 64 20 55 54 46 31 36 62 65  16le and UTF16be
30a00 0a 2a 2a 20 69 73 20 61 20 63 6c 6f 73 65 72 20  .** is a closer 
30a10 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e  match than a fun
30a20 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20  ction where the 
30a30 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 65 72 65  encoding differe
30a40 6e 63 65 20 69 73 0a 2a 2a 20 62 65 74 77 65 65  nce is.** betwee
30a50 6e 20 55 54 46 38 20 61 6e 64 20 55 54 46 31 36  n UTF8 and UTF16
30a60 2e 0a 2a 2a 0a 2a 2a 20 5e 42 75 69 6c 74 2d 69  ..**.** ^Built-i
30a70 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20  n functions may 
30a80 62 65 20 6f 76 65 72 6c 6f 61 64 65 64 20 62 79  be overloaded by
30a90 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e   new application
30aa0 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
30ab0 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 61 70  ns..**.** ^An ap
30ac0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
30ad0 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 70 65  d function is pe
30ae0 72 6d 69 74 74 65 64 20 74 6f 20 63 61 6c 6c 20  rmitted to call 
30af0 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20  other.** SQLite 
30b00 69 6e 74 65 72 66 61 63 65 73 2e 20 20 48 6f 77  interfaces.  How
30b10 65 76 65 72 2c 20 73 75 63 68 20 63 61 6c 6c 73  ever, such calls
30b20 20 6d 75 73 74 20 6e 6f 74 0a 2a 2a 20 63 6c 6f   must not.** clo
30b30 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  se the database 
30b40 63 6f 6e 6e 65 63 74 69 6f 6e 20 6e 6f 72 20 66  connection nor f
30b50 69 6e 61 6c 69 7a 65 20 6f 72 20 72 65 73 65 74  inalize or reset
30b60 20 74 68 65 20 70 72 65 70 61 72 65 64 0a 2a 2a   the prepared.**
30b70 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 77 68   statement in wh
30b80 69 63 68 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  ich the function
30b90 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a   is running..*/.
30ba0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61  int sqlite3_crea
30bb0 74 65 5f 66 75 6e 63 74 69 6f 6e 28 0a 20 20 73  te_function(.  s
30bc0 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f  qlite3 *db,.  co
30bd0 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74  nst char *zFunct
30be0 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e  ionName,.  int n
30bf0 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74  Arg,.  int eText
30c00 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70  Rep,.  void *pAp
30c10 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e  p,.  void (*xFun
30c20 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  c)(sqlite3_conte
30c30 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f  xt*,int,sqlite3_
30c40 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64  value**),.  void
30c50 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65   (*xStep)(sqlite
30c60 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73  3_context*,int,s
30c70 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c  qlite3_value**),
30c80 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c  .  void (*xFinal
30c90 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
30ca0 74 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  t*).);.int sqlit
30cb0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
30cc0 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20  on16(.  sqlite3 
30cd0 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 76 6f 69  *db,.  const voi
30ce0 64 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65  d *zFunctionName
30cf0 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20  ,.  int nArg,.  
30d00 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20  int eTextRep,.  
30d10 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f  void *pApp,.  vo
30d20 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69  id (*xFunc)(sqli
30d30 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74  te3_context*,int
30d40 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a  ,sqlite3_value**
30d50 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65  ),.  void (*xSte
30d60 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  p)(sqlite3_conte
30d70 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f  xt*,int,sqlite3_
30d80 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64  value**),.  void
30d90 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74   (*xFinal)(sqlit
30da0 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a  e3_context*).);.
30db0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61  int sqlite3_crea
30dc0 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 0a  te_function_v2(.
30dd0 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20    sqlite3 *db,. 
30de0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75   const char *zFu
30df0 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e  nctionName,.  in
30e00 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54  t nArg,.  int eT
30e10 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a  extRep,.  void *
30e20 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78  pApp,.  void (*x
30e30 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f  Func)(sqlite3_co
30e40 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74  ntext*,int,sqlit
30e50 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76  e3_value**),.  v
30e60 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c  oid (*xStep)(sql
30e70 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e  ite3_context*,in
30e80 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t,sqlite3_value*
30e90 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69  *),.  void (*xFi
30ea0 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  nal)(sqlite3_con
30eb0 74 65 78 74 2a 29 2c 0a 20 20 76 6f 69 64 28 2a  text*),.  void(*
30ec0 78 44 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29  xDestroy)(void*)
30ed0 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
30ee0 52 45 46 3a 20 54 65 78 74 20 45 6e 63 6f 64 69  REF: Text Encodi
30ef0 6e 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ngs.**.** These 
30f00 63 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e 65 20  constant define 
30f10 69 6e 74 65 67 65 72 20 63 6f 64 65 73 20 74 68  integer codes th
30f20 61 74 20 72 65 70 72 65 73 65 6e 74 20 74 68 65  at represent the
30f30 20 76 61 72 69 6f 75 73 0a 2a 2a 20 74 65 78 74   various.** text
30f40 20 65 6e 63 6f 64 69 6e 67 73 20 73 75 70 70 6f   encodings suppo
30f50 72 74 65 64 20 62 79 20 53 51 4c 69 74 65 2e 0a  rted by SQLite..
30f60 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
30f70 45 5f 55 54 46 38 20 20 20 20 20 20 20 20 20 20  E_UTF8          
30f80 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   1.#define SQLIT
30f90 45 5f 55 54 46 31 36 4c 45 20 20 20 20 20 20 20  E_UTF16LE       
30fa0 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   2.#define SQLIT
30fb0 45 5f 55 54 46 31 36 42 45 20 20 20 20 20 20 20  E_UTF16BE       
30fc0 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   3.#define SQLIT
30fd0 45 5f 55 54 46 31 36 20 20 20 20 20 20 20 20 20  E_UTF16         
30fe0 20 34 20 20 20 20 2f 2a 20 55 73 65 20 6e 61 74   4    /* Use nat
30ff0 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 2a  ive byte order *
31000 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
31010 5f 41 4e 59 20 20 20 20 20 20 20 20 20 20 20 20  _ANY            
31020 35 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f  5    /* sqlite3_
31030 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 20  create_function 
31040 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  only */.#define 
31050 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49  SQLITE_UTF16_ALI
31060 47 4e 45 44 20 20 38 20 20 20 20 2f 2a 20 73 71  GNED  8    /* sq
31070 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
31080 6c 61 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a  lation only */..
31090 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
310a0 44 65 70 72 65 63 61 74 65 64 20 46 75 6e 63 74  Deprecated Funct
310b0 69 6f 6e 73 0a 2a 2a 20 44 45 50 52 45 43 41 54  ions.** DEPRECAT
310c0 45 44 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66  ED.**.** These f
310d0 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 5b 64 65  unctions are [de
310e0 70 72 65 63 61 74 65 64 5d 2e 20 20 49 6e 20 6f  precated].  In o
310f0 72 64 65 72 20 74 6f 20 6d 61 69 6e 74 61 69 6e  rder to maintain
31100 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f  .** backwards co
31110 6d 70 61 74 69 62 69 6c 69 74 79 20 77 69 74 68  mpatibility with
31120 20 6f 6c 64 65 72 20 63 6f 64 65 2c 20 74 68 65   older code, the
31130 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 63 6f 6e  se functions con
31140 74 69 6e 75 65 20 0a 2a 2a 20 74 6f 20 62 65 20  tinue .** to be 
31150 73 75 70 70 6f 72 74 65 64 2e 20 20 48 6f 77 65  supported.  Howe
31160 76 65 72 2c 20 6e 65 77 20 61 70 70 6c 69 63 61  ver, new applica
31170 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 61 76 6f  tions should avo
31180 69 64 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f 66  id.** the use of
31190 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   these functions
311a0 2e 20 20 54 6f 20 68 65 6c 70 20 65 6e 63 6f 75  .  To help encou
311b0 72 61 67 65 20 70 65 6f 70 6c 65 20 74 6f 20 61  rage people to a
311c0 76 6f 69 64 0a 2a 2a 20 75 73 69 6e 67 20 74 68  void.** using th
311d0 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2c 20 77  ese functions, w
311e0 65 20 61 72 65 20 6e 6f 74 20 67 6f 69 6e 67 20  e are not going 
311f0 74 6f 20 74 65 6c 6c 20 79 6f 75 20 77 68 61 74  to tell you what
31200 20 74 68 65 79 20 64 6f 2e 0a 2a 2f 0a 23 69 66   they do..*/.#if
31210 6e 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54  ndef SQLITE_OMIT
31220 5f 44 45 50 52 45 43 41 54 45 44 0a 53 51 4c 49  _DEPRECATED.SQLI
31230 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e  TE_DEPRECATED in
31240 74 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  t sqlite3_aggreg
31250 61 74 65 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65  ate_count(sqlite
31260 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 51 4c  3_context*);.SQL
31270 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69  ITE_DEPRECATED i
31280 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 70 69 72  nt sqlite3_expir
31290 65 64 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ed(sqlite3_stmt*
312a0 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43  );.SQLITE_DEPREC
312b0 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33  ATED int sqlite3
312c0 5f 74 72 61 6e 73 66 65 72 5f 62 69 6e 64 69 6e  _transfer_bindin
312d0 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  gs(sqlite3_stmt*
312e0 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  , sqlite3_stmt*)
312f0 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  ;.SQLITE_DEPRECA
31300 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  TED int sqlite3_
31310 67 6c 6f 62 61 6c 5f 72 65 63 6f 76 65 72 28 76  global_recover(v
31320 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50  oid);.SQLITE_DEP
31330 52 45 43 41 54 45 44 20 76 6f 69 64 20 73 71 6c  RECATED void sql
31340 69 74 65 33 5f 74 68 72 65 61 64 5f 63 6c 65 61  ite3_thread_clea
31350 6e 75 70 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54  nup(void);.SQLIT
31360 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74  E_DEPRECATED int
31370 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f   sqlite3_memory_
31380 61 6c 61 72 6d 28 76 6f 69 64 28 2a 29 28 76 6f  alarm(void(*)(vo
31390 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36  id*,sqlite3_int6
313a0 34 2c 69 6e 74 29 2c 0a 20 20 20 20 20 20 20 20  4,int),.        
313b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 76 6f                vo
313c0 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36  id*,sqlite3_int6
313d0 34 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a  4);.#endif../*.*
313e0 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61  * CAPI3REF: Obta
313f0 69 6e 69 6e 67 20 53 51 4c 20 46 75 6e 63 74 69  ining SQL Functi
31400 6f 6e 20 50 61 72 61 6d 65 74 65 72 20 56 61 6c  on Parameter Val
31410 75 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d  ues.**.** The C-
31420 6c 61 6e 67 75 61 67 65 20 69 6d 70 6c 65 6d 65  language impleme
31430 6e 74 61 74 69 6f 6e 20 6f 66 20 53 51 4c 20 66  ntation of SQL f
31440 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67  unctions and agg
31450 72 65 67 61 74 65 73 20 75 73 65 73 0a 2a 2a 20  regates uses.** 
31460 74 68 69 73 20 73 65 74 20 6f 66 20 69 6e 74 65  this set of inte
31470 72 66 61 63 65 20 72 6f 75 74 69 6e 65 73 20 74  rface routines t
31480 6f 20 61 63 63 65 73 73 20 74 68 65 20 70 61 72  o access the par
31490 61 6d 65 74 65 72 20 76 61 6c 75 65 73 20 6f 6e  ameter values on
314a0 0a 2a 2a 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  .** the function
314b0 20 6f 72 20 61 67 67 72 65 67 61 74 65 2e 0a 2a   or aggregate..*
314c0 2a 0a 2a 2a 20 54 68 65 20 78 46 75 6e 63 20 28  *.** The xFunc (
314d0 66 6f 72 20 73 63 61 6c 61 72 20 66 75 6e 63 74  for scalar funct
314e0 69 6f 6e 73 29 20 6f 72 20 78 53 74 65 70 20 28  ions) or xStep (
314f0 66 6f 72 20 61 67 67 72 65 67 61 74 65 73 29 20  for aggregates) 
31500 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f  parameters.** to
31510 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
31520 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64  _function()] and
31530 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
31540 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a  _function16()].*
31550 2a 20 64 65 66 69 6e 65 20 63 61 6c 6c 62 61 63  * define callbac
31560 6b 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e  ks that implemen
31570 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  t the SQL functi
31580 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74  ons and aggregat
31590 65 73 2e 0a 2a 2a 20 54 68 65 20 33 72 64 20 70  es..** The 3rd p
315a0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 73  arameter to thes
315b0 65 20 63 61 6c 6c 62 61 63 6b 73 20 69 73 20 61  e callbacks is a
315c0 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74  n array of point
315d0 65 72 73 20 74 6f 0a 2a 2a 20 5b 70 72 6f 74 65  ers to.** [prote
315e0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
315f0 75 65 5d 20 6f 62 6a 65 63 74 73 2e 20 20 54 68  ue] objects.  Th
31600 65 72 65 20 69 73 20 6f 6e 65 20 5b 73 71 6c 69  ere is one [sqli
31610 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
31620 74 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 70 61  t for.** each pa
31630 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 53  rameter to the S
31640 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 20 20 54 68  QL function.  Th
31650 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
31660 20 75 73 65 64 20 74 6f 0a 2a 2a 20 65 78 74 72   used to.** extr
31670 61 63 74 20 76 61 6c 75 65 73 20 66 72 6f 6d 20  act values from 
31680 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  the [sqlite3_val
31690 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a  ue] objects..**.
316a0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
316b0 73 20 77 6f 72 6b 20 6f 6e 6c 79 20 77 69 74 68  s work only with
316c0 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   [protected sqli
316d0 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
316e0 74 73 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d  ts..** Any attem
316f0 70 74 20 74 6f 20 75 73 65 20 74 68 65 73 65 20  pt to use these 
31700 72 6f 75 74 69 6e 65 73 20 6f 6e 20 61 6e 20 5b  routines on an [
31710 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
31720 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62  te3_value].** ob
31730 6a 65 63 74 20 72 65 73 75 6c 74 73 20 69 6e 20  ject results in 
31740 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 69  undefined behavi
31750 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  or..**.** ^These
31760 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6a   routines work j
31770 75 73 74 20 6c 69 6b 65 20 74 68 65 20 63 6f 72  ust like the cor
31780 72 65 73 70 6f 6e 64 69 6e 67 20 5b 63 6f 6c 75  responding [colu
31790 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69  mn access functi
317a0 6f 6e 73 5d 0a 2a 2a 20 65 78 63 65 70 74 20 74  ons].** except t
317b0 68 61 74 20 20 74 68 65 73 65 20 72 6f 75 74 69  hat  these routi
317c0 6e 65 73 20 74 61 6b 65 20 61 20 73 69 6e 67 6c  nes take a singl
317d0 65 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c  e [protected sql
317e0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
317f0 63 74 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e  ct.** pointer in
31800 73 74 65 61 64 20 6f 66 20 61 20 5b 73 71 6c 69  stead of a [sqli
31810 74 65 33 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e 74  te3_stmt*] point
31820 65 72 20 61 6e 64 20 61 6e 20 69 6e 74 65 67 65  er and an intege
31830 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e  r column number.
31840 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
31850 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
31860 28 29 20 69 6e 74 65 72 66 61 63 65 20 65 78 74  () interface ext
31870 72 61 63 74 73 20 61 20 55 54 46 2d 31 36 20 73  racts a UTF-16 s
31880 74 72 69 6e 67 0a 2a 2a 20 69 6e 20 74 68 65 20  tring.** in the 
31890 6e 61 74 69 76 65 20 62 79 74 65 2d 6f 72 64 65  native byte-orde
318a0 72 20 6f 66 20 74 68 65 20 68 6f 73 74 20 6d 61  r of the host ma
318b0 63 68 69 6e 65 2e 20 20 5e 54 68 65 0a 2a 2a 20  chine.  ^The.** 
318c0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
318d0 78 74 31 36 62 65 28 29 20 61 6e 64 20 73 71 6c  xt16be() and sql
318e0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
318f0 36 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 73  6le() interfaces
31900 0a 2a 2a 20 65 78 74 72 61 63 74 20 55 54 46 2d  .** extract UTF-
31910 31 36 20 73 74 72 69 6e 67 73 20 61 73 20 62 69  16 strings as bi
31920 67 2d 65 6e 64 69 61 6e 20 61 6e 64 20 6c 69 74  g-endian and lit
31930 74 6c 65 2d 65 6e 64 69 61 6e 20 72 65 73 70 65  tle-endian respe
31940 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e  ctively..**.** ^
31950 28 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c  (The sqlite3_val
31960 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28  ue_numeric_type(
31970 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65  ) interface atte
31980 6d 70 74 73 20 74 6f 20 61 70 70 6c 79 0a 2a 2a  mpts to apply.**
31990 20 6e 75 6d 65 72 69 63 20 61 66 66 69 6e 69 74   numeric affinit
319a0 79 20 74 6f 20 74 68 65 20 76 61 6c 75 65 2e 20  y to the value. 
319b0 20 54 68 69 73 20 6d 65 61 6e 73 20 74 68 61 74   This means that
319c0 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 0a 2a   an attempt is.*
319d0 2a 20 6d 61 64 65 20 74 6f 20 63 6f 6e 76 65 72  * made to conver
319e0 74 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 61  t the value to a
319f0 6e 20 69 6e 74 65 67 65 72 20 6f 72 20 66 6c 6f  n integer or flo
31a00 61 74 69 6e 67 20 70 6f 69 6e 74 2e 20 20 49 66  ating point.  If
31a10 0a 2a 2a 20 73 75 63 68 20 61 20 63 6f 6e 76 65  .** such a conve
31a20 72 73 69 6f 6e 20 69 73 20 70 6f 73 73 69 62 6c  rsion is possibl
31a30 65 20 77 69 74 68 6f 75 74 20 6c 6f 73 73 20 6f  e without loss o
31a40 66 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 28 69  f information (i
31a50 6e 20 6f 74 68 65 72 0a 2a 2a 20 77 6f 72 64 73  n other.** words
31a60 2c 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 69  , if the value i
31a70 73 20 61 20 73 74 72 69 6e 67 20 74 68 61 74 20  s a string that 
31a80 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61 20 6e 75 6d  looks like a num
31a90 62 65 72 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ber).** then the
31aa0 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70   conversion is p
31ab0 65 72 66 6f 72 6d 65 64 2e 20 20 4f 74 68 65 72  erformed.  Other
31ac0 77 69 73 65 20 6e 6f 20 63 6f 6e 76 65 72 73 69  wise no conversi
31ad0 6f 6e 20 6f 63 63 75 72 73 2e 0a 2a 2a 20 54 68  on occurs..** Th
31ae0 65 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45  e [SQLITE_INTEGE
31af0 52 20 7c 20 64 61 74 61 74 79 70 65 5d 20 61 66  R | datatype] af
31b00 74 65 72 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69  ter conversion i
31b10 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 0a 2a 2a  s returned.)^.**
31b20 0a 2a 2a 20 50 6c 65 61 73 65 20 70 61 79 20 70  .** Please pay p
31b30 61 72 74 69 63 75 6c 61 72 20 61 74 74 65 6e 74  articular attent
31b40 69 6f 6e 20 74 6f 20 74 68 65 20 66 61 63 74 20  ion to the fact 
31b50 74 68 61 74 20 74 68 65 20 70 6f 69 6e 74 65 72  that the pointer
31b60 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f   returned.** fro
31b70 6d 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  m [sqlite3_value
31b80 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74  _blob()], [sqlit
31b90 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d  e3_value_text()]
31ba0 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  , or.** [sqlite3
31bb0 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d  _value_text16()]
31bc0 20 63 61 6e 20 62 65 20 69 6e 76 61 6c 69 64 61   can be invalida
31bd0 74 65 64 20 62 79 20 61 20 73 75 62 73 65 71 75  ted by a subsequ
31be0 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b  ent call to.** [
31bf0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
31c00 74 65 73 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  tes()], [sqlite3
31c10 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 29  _value_bytes16()
31c20 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ], [sqlite3_valu
31c30 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72  e_text()],.** or
31c40 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
31c50 74 65 78 74 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a  text16()]..**.**
31c60 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
31c70 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66  must be called f
31c80 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72  rom the same thr
31c90 65 61 64 20 61 73 0a 2a 2a 20 74 68 65 20 53 51  ead as.** the SQ
31ca0 4c 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20  L function that 
31cb0 73 75 70 70 6c 69 65 64 20 74 68 65 20 5b 73 71  supplied the [sq
31cc0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 5d 20 70 61  lite3_value*] pa
31cd0 72 61 6d 65 74 65 72 73 2e 0a 2a 2f 0a 63 6f 6e  rameters..*/.con
31ce0 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
31cf0 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 73 71 6c 69  _value_blob(sqli
31d00 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74  te3_value*);.int
31d10 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62   sqlite3_value_b
31d20 79 74 65 73 28 73 71 6c 69 74 65 33 5f 76 61 6c  ytes(sqlite3_val
31d30 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  ue*);.int sqlite
31d40 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28  3_value_bytes16(
31d50 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
31d60 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f  .double sqlite3_
31d70 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28 73 71 6c  value_double(sql
31d80 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e  ite3_value*);.in
31d90 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  t sqlite3_value_
31da0 69 6e 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  int(sqlite3_valu
31db0 65 2a 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74  e*);.sqlite3_int
31dc0 36 34 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  64 sqlite3_value
31dd0 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 76  _int64(sqlite3_v
31de0 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 75 6e  alue*);.const un
31df0 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c  signed char *sql
31e00 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28  ite3_value_text(
31e10 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
31e20 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
31e30 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
31e40 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  6(sqlite3_value*
31e50 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
31e60 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
31e70 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 76 61  t16le(sqlite3_va
31e80 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  lue*);.const voi
31e90 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  d *sqlite3_value
31ea0 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69 74 65  _text16be(sqlite
31eb0 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73  3_value*);.int s
31ec0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70  qlite3_value_typ
31ed0 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  e(sqlite3_value*
31ee0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76  );.int sqlite3_v
31ef0 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70  alue_numeric_typ
31f00 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  e(sqlite3_value*
31f10 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
31f20 45 46 3a 20 4f 62 74 61 69 6e 20 41 67 67 72 65  EF: Obtain Aggre
31f30 67 61 74 65 20 46 75 6e 63 74 69 6f 6e 20 43 6f  gate Function Co
31f40 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 49 6d 70 6c  ntext.**.** Impl
31f50 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 61  ementations of a
31f60 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e  ggregate SQL fun
31f70 63 74 69 6f 6e 73 20 75 73 65 20 74 68 69 73 0a  ctions use this.
31f80 2a 2a 20 72 6f 75 74 69 6e 65 20 74 6f 20 61 6c  ** routine to al
31f90 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 66 6f  locate memory fo
31fa0 72 20 73 74 6f 72 69 6e 67 20 74 68 65 69 72 20  r storing their 
31fb0 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  state..**.** ^Th
31fc0 65 20 66 69 72 73 74 20 74 69 6d 65 20 74 68 65  e first time the
31fd0 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
31fe0 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20  te_context(C,N) 
31ff0 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65  routine is calle
32000 64 20 0a 2a 2a 20 66 6f 72 20 61 20 70 61 72 74  d .** for a part
32010 69 63 75 6c 61 72 20 61 67 67 72 65 67 61 74 65  icular aggregate
32020 20 66 75 6e 63 74 69 6f 6e 2c 20 53 51 4c 69 74   function, SQLit
32030 65 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 73 20 4e  e.** allocates N
32040 20 6f 66 20 6d 65 6d 6f 72 79 2c 20 7a 65 72 6f   of memory, zero
32050 65 73 20 6f 75 74 20 74 68 61 74 20 6d 65 6d 6f  es out that memo
32060 72 79 2c 20 61 6e 64 20 72 65 74 75 72 6e 73 20  ry, and returns 
32070 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20  a pointer.** to 
32080 74 68 65 20 6e 65 77 20 6d 65 6d 6f 72 79 2e 20  the new memory. 
32090 5e 4f 6e 20 73 65 63 6f 6e 64 20 61 6e 64 20 73  ^On second and s
320a0 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20  ubsequent calls 
320b0 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67  to.** sqlite3_ag
320c0 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
320d0 29 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 61  ) for the same a
320e0 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f  ggregate functio
320f0 6e 20 69 6e 73 74 61 6e 63 65 2c 0a 2a 2a 20 74  n instance,.** t
32100 68 65 20 73 61 6d 65 20 62 75 66 66 65 72 20 69  he same buffer i
32110 73 20 72 65 74 75 72 6e 65 64 2e 20 20 53 71 6c  s returned.  Sql
32120 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
32130 6f 6e 74 65 78 74 28 29 20 69 73 20 6e 6f 72 6d  ontext() is norm
32140 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 6f  ally.** called o
32150 6e 63 65 20 66 6f 72 20 65 61 63 68 20 69 6e 76  nce for each inv
32160 6f 63 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78  ocation of the x
32170 53 74 65 70 20 63 61 6c 6c 62 61 63 6b 20 61 6e  Step callback an
32180 64 20 74 68 65 6e 20 6f 6e 65 0a 2a 2a 20 6c 61  d then one.** la
32190 73 74 20 74 69 6d 65 20 77 68 65 6e 20 74 68 65  st time when the
321a0 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b   xFinal callback
321b0 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 28   is invoked.  ^(
321c0 57 68 65 6e 20 6e 6f 20 72 6f 77 73 20 6d 61 74  When no rows mat
321d0 63 68 0a 2a 2a 20 61 6e 20 61 67 67 72 65 67 61  ch.** an aggrega
321e0 74 65 20 71 75 65 72 79 2c 20 74 68 65 20 78 53  te query, the xS
321f0 74 65 70 28 29 20 63 61 6c 6c 62 61 63 6b 20 6f  tep() callback o
32200 66 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20  f the aggregate 
32210 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 69 6d 70 6c  function.** impl
32220 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6e 65  ementation is ne
32230 76 65 72 20 63 61 6c 6c 65 64 20 61 6e 64 20 78  ver called and x
32240 46 69 6e 61 6c 28 29 20 69 73 20 63 61 6c 6c 65  Final() is calle
32250 64 20 65 78 61 63 74 6c 79 20 6f 6e 63 65 2e 0a  d exactly once..
32260 2a 2a 20 49 6e 20 74 68 6f 73 65 20 63 61 73 65  ** In those case
32270 73 2c 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  s, sqlite3_aggre
32280 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 6d  gate_context() m
32290 69 67 68 74 20 62 65 20 63 61 6c 6c 65 64 20 66  ight be called f
322a0 6f 72 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20  or the.** first 
322b0 74 69 6d 65 20 66 72 6f 6d 20 77 69 74 68 69 6e  time from within
322c0 20 78 46 69 6e 61 6c 28 29 2e 29 5e 0a 2a 2a 0a   xFinal().)^.**.
322d0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
322e0 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
322f0 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e 65 20 72  t(C,N) routine r
32300 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f  eturns a NULL po
32310 69 6e 74 65 72 20 0a 2a 2a 20 77 68 65 6e 20 66  inter .** when f
32320 69 72 73 74 20 63 61 6c 6c 65 64 20 69 66 20 4e  irst called if N
32330 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 6f 72   is less than or
32340 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 20 6f   equal to zero o
32350 72 20 69 66 20 61 20 6d 65 6d 6f 72 79 0a 2a 2a  r if a memory.**
32360 20 61 6c 6c 6f 63 61 74 65 20 65 72 72 6f 72 20   allocate error 
32370 6f 63 63 75 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28  occurs..**.** ^(
32380 54 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 73 70  The amount of sp
32390 61 63 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79  ace allocated by
323a0 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
323b0 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20  te_context(C,N) 
323c0 69 73 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 65 64  is.** determined
323d0 20 62 79 20 74 68 65 20 4e 20 70 61 72 61 6d 65   by the N parame
323e0 74 65 72 20 6f 6e 20 66 69 72 73 74 20 73 75 63  ter on first suc
323f0 63 65 73 73 66 75 6c 20 63 61 6c 6c 2e 20 20 43  cessful call.  C
32400 68 61 6e 67 69 6e 67 20 74 68 65 0a 2a 2a 20 76  hanging the.** v
32410 61 6c 75 65 20 6f 66 20 4e 20 69 6e 20 73 75 62  alue of N in sub
32420 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20  sequent call to 
32430 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
32440 65 5f 63 6f 6e 74 65 78 74 28 29 20 77 69 74 68  e_context() with
32450 69 6e 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 61  in.** the same a
32460 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f  ggregate functio
32470 6e 20 69 6e 73 74 61 6e 63 65 20 77 69 6c 6c 20  n instance will 
32480 6e 6f 74 20 72 65 73 69 7a 65 20 74 68 65 20 6d  not resize the m
32490 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74  emory.** allocat
324a0 69 6f 6e 2e 29 5e 20 20 57 69 74 68 69 6e 20 74  ion.)^  Within t
324b0 68 65 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61  he xFinal callba
324c0 63 6b 2c 20 69 74 20 69 73 20 63 75 73 74 6f 6d  ck, it is custom
324d0 61 72 79 20 74 6f 20 73 65 74 0a 2a 2a 20 4e 3d  ary to set.** N=
324e0 30 20 69 6e 20 63 61 6c 6c 73 20 74 6f 20 73 71  0 in calls to sq
324f0 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
32500 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 73 6f 20  context(C,N) so 
32510 74 68 61 74 20 6e 6f 20 0a 2a 2a 20 70 6f 69 6e  that no .** poin
32520 74 6c 65 73 73 20 6d 65 6d 6f 72 79 20 61 6c 6c  tless memory all
32530 6f 63 61 74 69 6f 6e 73 20 6f 63 63 75 72 2e 0a  ocations occur..
32540 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 61 75  **.** ^SQLite au
32550 74 6f 6d 61 74 69 63 61 6c 6c 79 20 66 72 65 65  tomatically free
32560 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  s the memory all
32570 6f 63 61 74 65 64 20 62 79 20 0a 2a 2a 20 73 71  ocated by .** sq
32580 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
32590 63 6f 6e 74 65 78 74 28 29 20 77 68 65 6e 20 74  context() when t
325a0 68 65 20 61 67 67 72 65 67 61 74 65 20 71 75 65  he aggregate que
325b0 72 79 20 63 6f 6e 63 6c 75 64 65 73 2e 0a 2a 2a  ry concludes..**
325c0 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 61  .** The first pa
325d0 72 61 6d 65 74 65 72 20 6d 75 73 74 20 62 65 20  rameter must be 
325e0 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a  a copy of the.**
325f0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78   [sqlite3_contex
32600 74 20 7c 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  t | SQL function
32610 20 63 6f 6e 74 65 78 74 5d 20 74 68 61 74 20 69   context] that i
32620 73 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61  s the first para
32630 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20  meter.** to the 
32640 78 53 74 65 70 20 6f 72 20 78 46 69 6e 61 6c 20  xStep or xFinal 
32650 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65  callback routine
32660 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73   that implements
32670 20 74 68 65 20 61 67 67 72 65 67 61 74 65 0a 2a   the aggregate.*
32680 2a 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a  * function..**.*
32690 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d  * This routine m
326a0 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72  ust be called fr
326b0 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65  om the same thre
326c0 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74  ad in which.** t
326d0 68 65 20 61 67 67 72 65 67 61 74 65 20 53 51 4c  he aggregate SQL
326e0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e   function is run
326f0 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73  ning..*/.void *s
32700 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
32710 5f 63 6f 6e 74 65 78 74 28 73 71 6c 69 74 65 33  _context(sqlite3
32720 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e  _context*, int n
32730 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  Bytes);../*.** C
32740 41 50 49 33 52 45 46 3a 20 55 73 65 72 20 44 61  API3REF: User Da
32750 74 61 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73  ta For Functions
32760 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
32770 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 20  te3_user_data() 
32780 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
32790 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74  s a copy of.** t
327a0 68 65 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20  he pointer that 
327b0 77 61 73 20 74 68 65 20 70 55 73 65 72 44 61 74  was the pUserDat
327c0 61 20 70 61 72 61 6d 65 74 65 72 20 28 74 68 65  a parameter (the
327d0 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 29 0a   5th parameter).
327e0 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ** of the [sqlit
327f0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
32800 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71  on()].** and [sq
32810 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
32820 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69  ction16()] routi
32830 6e 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e 61  nes that origina
32840 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65  lly.** registere
32850 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  d the applicatio
32860 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n defined functi
32870 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  on..**.** This r
32880 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63  outine must be c
32890 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73  alled from the s
328a0 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68  ame thread in wh
328b0 69 63 68 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69  ich.** the appli
328c0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
328d0 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69  unction is runni
328e0 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c  ng..*/.void *sql
328f0 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 73  ite3_user_data(s
32900 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
32910 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
32920 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e  F: Database Conn
32930 65 63 74 69 6f 6e 20 46 6f 72 20 46 75 6e 63 74  ection For Funct
32940 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ions.**.** ^The 
32950 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f  sqlite3_context_
32960 64 62 5f 68 61 6e 64 6c 65 28 29 20 69 6e 74 65  db_handle() inte
32970 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
32980 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70  copy of.** the p
32990 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 64  ointer to the [d
329a0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
329b0 6f 6e 5d 20 28 74 68 65 20 31 73 74 20 70 61 72  on] (the 1st par
329c0 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68  ameter).** of th
329d0 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  e [sqlite3_creat
329e0 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a  e_function()].**
329f0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72   and [sqlite3_cr
32a00 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
32a10 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74  )] routines that
32a20 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72   originally.** r
32a30 65 67 69 73 74 65 72 65 64 20 74 68 65 20 61 70  egistered the ap
32a40 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65  plication define
32a50 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2f 0a 73  d function..*/.s
32a60 71 6c 69 74 65 33 20 2a 73 71 6c 69 74 65 33 5f  qlite3 *sqlite3_
32a70 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c  context_db_handl
32a80 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  e(sqlite3_contex
32a90 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
32aa0 33 52 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20 41  3REF: Function A
32ab0 75 78 69 6c 69 61 72 79 20 44 61 74 61 0a 2a 2a  uxiliary Data.**
32ac0 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69  .** These functi
32ad0 6f 6e 73 20 6d 61 79 20 62 65 20 75 73 65 64 20  ons may be used 
32ae0 62 79 20 28 6e 6f 6e 2d 61 67 67 72 65 67 61 74  by (non-aggregat
32af0 65 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  e) SQL functions
32b00 20 74 6f 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65   to.** associate
32b10 20 6d 65 74 61 64 61 74 61 20 77 69 74 68 20 61   metadata with a
32b20 72 67 75 6d 65 6e 74 20 76 61 6c 75 65 73 2e 20  rgument values. 
32b30 49 66 20 74 68 65 20 73 61 6d 65 20 76 61 6c 75  If the same valu
32b40 65 20 69 73 20 70 61 73 73 65 64 20 74 6f 0a 2a  e is passed to.*
32b50 2a 20 6d 75 6c 74 69 70 6c 65 20 69 6e 76 6f 63  * multiple invoc
32b60 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61  ations of the sa
32b70 6d 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  me SQL function 
32b80 64 75 72 69 6e 67 20 71 75 65 72 79 20 65 78 65  during query exe
32b90 63 75 74 69 6f 6e 2c 20 75 6e 64 65 72 0a 2a 2a  cution, under.**
32ba0 20 73 6f 6d 65 20 63 69 72 63 75 6d 73 74 61 6e   some circumstan
32bb0 63 65 73 20 74 68 65 20 61 73 73 6f 63 69 61 74  ces the associat
32bc0 65 64 20 6d 65 74 61 64 61 74 61 20 6d 61 79 20  ed metadata may 
32bd0 62 65 20 70 72 65 73 65 72 76 65 64 2e 20 20 41  be preserved.  A
32be0 6e 20 65 78 61 6d 70 6c 65 0a 2a 2a 20 6f 66 20  n example.** of 
32bf0 77 68 65 72 65 20 74 68 69 73 20 6d 69 67 68 74  where this might
32c00 20 62 65 20 75 73 65 66 75 6c 20 69 73 20 69 6e   be useful is in
32c10 20 61 20 72 65 67 75 6c 61 72 2d 65 78 70 72 65   a regular-expre
32c20 73 73 69 6f 6e 20 6d 61 74 63 68 69 6e 67 0a 2a  ssion matching.*
32c30 2a 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20  * function. The 
32c40 63 6f 6d 70 69 6c 65 64 20 76 65 72 73 69 6f 6e  compiled version
32c50 20 6f 66 20 74 68 65 20 72 65 67 75 6c 61 72 20   of the regular 
32c60 65 78 70 72 65 73 73 69 6f 6e 20 63 61 6e 20 62  expression can b
32c70 65 20 73 74 6f 72 65 64 20 61 73 0a 2a 2a 20 6d  e stored as.** m
32c80 65 74 61 64 61 74 61 20 61 73 73 6f 63 69 61 74  etadata associat
32c90 65 64 20 77 69 74 68 20 74 68 65 20 70 61 74 74  ed with the patt
32ca0 65 72 6e 20 73 74 72 69 6e 67 2e 20 20 0a 2a 2a  ern string.  .**
32cb0 20 54 68 65 6e 20 61 73 20 6c 6f 6e 67 20 61 73   Then as long as
32cc0 20 74 68 65 20 70 61 74 74 65 72 6e 20 73 74 72   the pattern str
32cd0 69 6e 67 20 72 65 6d 61 69 6e 73 20 74 68 65 20  ing remains the 
32ce0 73 61 6d 65 2c 0a 2a 2a 20 74 68 65 20 63 6f 6d  same,.** the com
32cf0 70 69 6c 65 64 20 72 65 67 75 6c 61 72 20 65 78  piled regular ex
32d00 70 72 65 73 73 69 6f 6e 20 63 61 6e 20 62 65 20  pression can be 
32d10 72 65 75 73 65 64 20 6f 6e 20 6d 75 6c 74 69 70  reused on multip
32d20 6c 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e  le.** invocation
32d30 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75  s of the same fu
32d40 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54  nction..**.** ^T
32d50 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  he sqlite3_get_a
32d60 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 66 61  uxdata() interfa
32d70 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ce returns a poi
32d80 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65 74 61  nter to the meta
32d90 64 61 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74  data.** associat
32da0 65 64 20 62 79 20 74 68 65 20 73 71 6c 69 74 65  ed by the sqlite
32db0 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20  3_set_auxdata() 
32dc0 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 74 68  function with th
32dd0 65 20 4e 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a  e Nth argument.*
32de0 2a 20 76 61 6c 75 65 20 74 6f 20 74 68 65 20 61  * value to the a
32df0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
32e00 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 5e 49 66  ed function. ^If
32e10 20 74 68 65 72 65 20 69 73 20 6e 6f 20 6d 65 74   there is no met
32e20 61 64 61 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61  adata.** associa
32e30 74 65 64 20 77 69 74 68 20 74 68 65 20 66 75 6e  ted with the fun
32e40 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2c 20  ction argument, 
32e50 74 68 69 73 20 73 71 6c 69 74 65 33 5f 67 65 74  this sqlite3_get
32e60 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74 65 72  _auxdata() inter
32e70 66 61 63 65 0a 2a 2a 20 72 65 74 75 72 6e 73 20  face.** returns 
32e80 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
32e90 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
32ea0 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 43  e3_set_auxdata(C
32eb0 2c 4e 2c 50 2c 58 29 20 69 6e 74 65 72 66 61 63  ,N,P,X) interfac
32ec0 65 20 73 61 76 65 73 20 50 20 61 73 20 6d 65 74  e saves P as met
32ed0 61 64 61 74 61 20 66 6f 72 20 74 68 65 20 4e 2d  adata for the N-
32ee0 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6f  th.** argument o
32ef0 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  f the applicatio
32f00 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
32f10 6f 6e 2e 20 20 5e 53 75 62 73 65 71 75 65 6e 74  on.  ^Subsequent
32f20 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  .** calls to sql
32f30 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61  ite3_get_auxdata
32f40 28 43 2c 4e 29 20 72 65 74 75 72 6e 20 50 20 66  (C,N) return P f
32f50 72 6f 6d 20 74 68 65 20 6d 6f 73 74 20 72 65 63  rom the most rec
32f60 65 6e 74 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73  ent.** sqlite3_s
32f70 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c 50  et_auxdata(C,N,P
32f80 2c 58 29 20 63 61 6c 6c 20 69 66 20 74 68 65 20  ,X) call if the 
32f90 6d 65 74 61 64 61 74 61 20 69 73 20 73 74 69 6c  metadata is stil
32fa0 6c 20 76 61 6c 69 64 20 6f 72 0a 2a 2a 20 4e 55  l valid or.** NU
32fb0 4c 4c 20 69 66 20 74 68 65 20 6d 65 74 61 64 61  LL if the metada
32fc0 74 61 20 68 61 73 20 62 65 65 6e 20 64 69 73 63  ta has been disc
32fd0 61 72 64 65 64 2e 0a 2a 2a 20 5e 41 66 74 65 72  arded..** ^After
32fe0 20 65 61 63 68 20 63 61 6c 6c 20 74 6f 20 73 71   each call to sq
32ff0 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
33000 61 28 43 2c 4e 2c 50 2c 58 29 20 77 68 65 72 65  a(C,N,P,X) where
33010 20 58 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 0a   X is not NULL,.
33020 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 69  ** SQLite will i
33030 6e 76 6f 6b 65 20 74 68 65 20 64 65 73 74 72 75  nvoke the destru
33040 63 74 6f 72 20 66 75 6e 63 74 69 6f 6e 20 58 20  ctor function X 
33050 77 69 74 68 20 70 61 72 61 6d 65 74 65 72 20 50  with parameter P
33060 20 65 78 61 63 74 6c 79 0a 2a 2a 20 6f 6e 63 65   exactly.** once
33070 2c 20 77 68 65 6e 20 74 68 65 20 6d 65 74 61 64  , when the metad
33080 61 74 61 20 69 73 20 64 69 73 63 61 72 64 65 64  ata is discarded
33090 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 69 73 20 66  ..** SQLite is f
330a0 72 65 65 20 74 6f 20 64 69 73 63 61 72 64 20 74  ree to discard t
330b0 68 65 20 6d 65 74 61 64 61 74 61 20 61 74 20 61  he metadata at a
330c0 6e 79 20 74 69 6d 65 2c 20 69 6e 63 6c 75 64 69  ny time, includi
330d0 6e 67 3a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  ng: <ul>.** <li>
330e0 20 77 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73   when the corres
330f0 70 6f 6e 64 69 6e 67 20 66 75 6e 63 74 69 6f 6e  ponding function
33100 20 70 61 72 61 6d 65 74 65 72 20 63 68 61 6e 67   parameter chang
33110 65 73 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 77  es, or.** <li> w
33120 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  hen [sqlite3_res
33130 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  et()] or [sqlite
33140 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73  3_finalize()] is
33150 20 63 61 6c 6c 65 64 20 66 6f 72 20 74 68 65 0a   called for the.
33160 2a 2a 20 20 20 20 20 20 53 51 4c 20 73 74 61 74  **      SQL stat
33170 65 6d 65 6e 74 2c 20 6f 72 0a 2a 2a 20 3c 6c 69  ement, or.** <li
33180 3e 20 77 68 65 6e 20 73 71 6c 69 74 65 33 5f 73  > when sqlite3_s
33190 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 73 20  et_auxdata() is 
331a0 69 6e 76 6f 6b 65 64 20 61 67 61 69 6e 20 6f 6e  invoked again on
331b0 20 74 68 65 20 73 61 6d 65 20 70 61 72 61 6d 65   the same parame
331c0 74 65 72 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20  ter, or.** <li> 
331d0 64 75 72 69 6e 67 20 74 68 65 20 6f 72 69 67 69  during the origi
331e0 6e 61 6c 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  nal sqlite3_set_
331f0 61 75 78 64 61 74 61 28 29 20 63 61 6c 6c 20 77  auxdata() call w
33200 68 65 6e 20 61 20 6d 65 6d 6f 72 79 20 0a 2a 2a  hen a memory .**
33210 20 20 20 20 20 20 61 6c 6c 6f 63 61 74 69 6f 6e        allocation
33220 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 20 3c   error occurs. <
33230 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 4e 6f 74  /ul>)^.**.** Not
33240 65 20 74 68 65 20 6c 61 73 74 20 62 75 6c 6c 65  e the last bulle
33250 74 20 69 6e 20 70 61 72 74 69 63 75 6c 61 72 2e  t in particular.
33260 20 20 54 68 65 20 64 65 73 74 72 75 63 74 6f 72    The destructor
33270 20 58 20 69 6e 20 0a 2a 2a 20 73 71 6c 69 74 65   X in .** sqlite
33280 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 43 2c  3_set_auxdata(C,
33290 4e 2c 50 2c 58 29 20 6d 69 67 68 74 20 62 65 20  N,P,X) might be 
332a0 63 61 6c 6c 65 64 20 69 6d 6d 65 64 69 61 74 65  called immediate
332b0 6c 79 2c 20 62 65 66 6f 72 65 20 74 68 65 0a 2a  ly, before the.*
332c0 2a 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  * sqlite3_set_au
332d0 78 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63  xdata() interfac
332e0 65 20 65 76 65 6e 20 72 65 74 75 72 6e 73 2e 20  e even returns. 
332f0 20 48 65 6e 63 65 20 73 71 6c 69 74 65 33 5f 73   Hence sqlite3_s
33300 65 74 5f 61 75 78 64 61 74 61 28 29 0a 2a 2a 20  et_auxdata().** 
33310 73 68 6f 75 6c 64 20 62 65 20 63 61 6c 6c 65 64  should be called
33320 20 6e 65 61 72 20 74 68 65 20 65 6e 64 20 6f 66   near the end of
33330 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 6d   the function im
33340 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 61 6e 64  plementation and
33350 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e   the.** function
33360 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
33370 73 68 6f 75 6c 64 20 6e 6f 74 20 6d 61 6b 65 20  should not make 
33380 61 6e 79 20 75 73 65 20 6f 66 20 50 20 61 66 74  any use of P aft
33390 65 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 65  er.** sqlite3_se
333a0 74 5f 61 75 78 64 61 74 61 28 29 20 68 61 73 20  t_auxdata() has 
333b0 62 65 65 6e 20 63 61 6c 6c 65 64 2e 0a 2a 2a 0a  been called..**.
333c0 2a 2a 20 5e 28 49 6e 20 70 72 61 63 74 69 63 65  ** ^(In practice
333d0 2c 20 6d 65 74 61 64 61 74 61 20 69 73 20 70 72  , metadata is pr
333e0 65 73 65 72 76 65 64 20 62 65 74 77 65 65 6e 20  eserved between 
333f0 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 73 20 66  function calls f
33400 6f 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70  or.** function p
33410 61 72 61 6d 65 74 65 72 73 20 74 68 61 74 20 61  arameters that a
33420 72 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  re compile-time 
33430 63 6f 6e 73 74 61 6e 74 73 2c 20 69 6e 63 6c 75  constants, inclu
33440 64 69 6e 67 20 6c 69 74 65 72 61 6c 0a 2a 2a 20  ding literal.** 
33450 76 61 6c 75 65 73 20 61 6e 64 20 5b 70 61 72 61  values and [para
33460 6d 65 74 65 72 73 5d 20 61 6e 64 20 65 78 70 72  meters] and expr
33470 65 73 73 69 6f 6e 73 20 63 6f 6d 70 6f 73 65 64  essions composed
33480 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 2e 29   from the same.)
33490 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ^.**.** These ro
334a0 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63  utines must be c
334b0 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73  alled from the s
334c0 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68  ame thread in wh
334d0 69 63 68 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66  ich.** the SQL f
334e0 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69  unction is runni
334f0 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c  ng..*/.void *sql
33500 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61  ite3_get_auxdata
33510 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
33520 2a 2c 20 69 6e 74 20 4e 29 3b 0a 76 6f 69 64 20  *, int N);.void 
33530 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
33540 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ata(sqlite3_cont
33550 65 78 74 2a 2c 20 69 6e 74 20 4e 2c 20 76 6f 69  ext*, int N, voi
33560 64 2a 2c 20 76 6f 69 64 20 28 2a 29 28 76 6f 69  d*, void (*)(voi
33570 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41  d*));.../*.** CA
33580 50 49 33 52 45 46 3a 20 43 6f 6e 73 74 61 6e 74  PI3REF: Constant
33590 73 20 44 65 66 69 6e 69 6e 67 20 53 70 65 63 69  s Defining Speci
335a0 61 6c 20 44 65 73 74 72 75 63 74 6f 72 20 42 65  al Destructor Be
335b0 68 61 76 69 6f 72 0a 2a 2a 0a 2a 2a 20 54 68 65  havior.**.** The
335c0 73 65 20 61 72 65 20 73 70 65 63 69 61 6c 20 76  se are special v
335d0 61 6c 75 65 73 20 66 6f 72 20 74 68 65 20 64 65  alues for the de
335e0 73 74 72 75 63 74 6f 72 20 74 68 61 74 20 69 73  structor that is
335f0 20 70 61 73 73 65 64 20 69 6e 20 61 73 20 74 68   passed in as th
33600 65 0a 2a 2a 20 66 69 6e 61 6c 20 61 72 67 75 6d  e.** final argum
33610 65 6e 74 20 74 6f 20 72 6f 75 74 69 6e 65 73 20  ent to routines 
33620 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 72 65  like [sqlite3_re
33630 73 75 6c 74 5f 62 6c 6f 62 28 29 5d 2e 20 20 5e  sult_blob()].  ^
33640 49 66 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  If the destructo
33650 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73  r.** argument is
33660 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20   SQLITE_STATIC, 
33670 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  it means that th
33680 65 20 63 6f 6e 74 65 6e 74 20 70 6f 69 6e 74 65  e content pointe
33690 72 20 69 73 20 63 6f 6e 73 74 61 6e 74 0a 2a 2a  r is constant.**
336a0 20 61 6e 64 20 77 69 6c 6c 20 6e 65 76 65 72 20   and will never 
336b0 63 68 61 6e 67 65 2e 20 20 49 74 20 64 6f 65 73  change.  It does
336c0 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20   not need to be 
336d0 64 65 73 74 72 6f 79 65 64 2e 20 20 5e 54 68 65  destroyed.  ^The
336e0 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 52 41 4e 53  .** SQLITE_TRANS
336f0 49 45 4e 54 20 76 61 6c 75 65 20 6d 65 61 6e 73  IENT value means
33700 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e   that the conten
33710 74 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 63 68  t will likely ch
33720 61 6e 67 65 20 69 6e 0a 2a 2a 20 74 68 65 20 6e  ange in.** the n
33730 65 61 72 20 66 75 74 75 72 65 20 61 6e 64 20 74  ear future and t
33740 68 61 74 20 53 51 4c 69 74 65 20 73 68 6f 75 6c  hat SQLite shoul
33750 64 20 6d 61 6b 65 20 69 74 73 20 6f 77 6e 20 70  d make its own p
33760 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 0a 2a  rivate copy of.*
33770 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 62 65  * the content be
33780 66 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 2e 0a  fore returning..
33790 2a 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 64 65  **.** The typede
337a0 66 20 69 73 20 6e 65 63 65 73 73 61 72 79 20 74  f is necessary t
337b0 6f 20 77 6f 72 6b 20 61 72 6f 75 6e 64 20 70 72  o work around pr
337c0 6f 62 6c 65 6d 73 20 69 6e 20 63 65 72 74 61 69  oblems in certai
337d0 6e 0a 2a 2a 20 43 2b 2b 20 63 6f 6d 70 69 6c 65  n.** C++ compile
337e0 72 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 76  rs..*/.typedef v
337f0 6f 69 64 20 28 2a 73 71 6c 69 74 65 33 5f 64 65  oid (*sqlite3_de
33800 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 28 76  structor_type)(v
33810 6f 69 64 2a 29 3b 0a 23 64 65 66 69 6e 65 20 53  oid*);.#define S
33820 51 4c 49 54 45 5f 53 54 41 54 49 43 20 20 20 20  QLITE_STATIC    
33830 20 20 28 28 73 71 6c 69 74 65 33 5f 64 65 73 74    ((sqlite3_dest
33840 72 75 63 74 6f 72 5f 74 79 70 65 29 30 29 0a 23  ructor_type)0).#
33850 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52  define SQLITE_TR
33860 41 4e 53 49 45 4e 54 20 20 20 28 28 73 71 6c 69  ANSIENT   ((sqli
33870 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74  te3_destructor_t
33880 79 70 65 29 2d 31 29 0a 0a 2f 2a 0a 2a 2a 20 43  ype)-1)../*.** C
33890 41 50 49 33 52 45 46 3a 20 53 65 74 74 69 6e 67  API3REF: Setting
338a0 20 54 68 65 20 52 65 73 75 6c 74 20 4f 66 20 41   The Result Of A
338b0 6e 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 0a 2a  n SQL Function.*
338c0 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
338d0 6e 65 73 20 61 72 65 20 75 73 65 64 20 62 79 20  nes are used by 
338e0 74 68 65 20 78 46 75 6e 63 20 6f 72 20 78 46 69  the xFunc or xFi
338f0 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 73 20 74 68  nal callbacks th
33900 61 74 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 20  at.** implement 
33910 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e  SQL functions an
33920 64 20 61 67 67 72 65 67 61 74 65 73 2e 20 20 53  d aggregates.  S
33930 65 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  ee.** [sqlite3_c
33940 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
33950 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  ] and [sqlite3_c
33960 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
33970 28 29 5d 0a 2a 2a 20 66 6f 72 20 61 64 64 69 74  ()].** for addit
33980 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f  ional informatio
33990 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66  n..**.** These f
339a0 75 6e 63 74 69 6f 6e 73 20 77 6f 72 6b 20 76 65  unctions work ve
339b0 72 79 20 6d 75 63 68 20 6c 69 6b 65 20 74 68 65  ry much like the
339c0 20 5b 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64   [parameter bind
339d0 69 6e 67 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a  ing] family of.*
339e0 2a 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 64  * functions used
339f0 20 74 6f 20 62 69 6e 64 20 76 61 6c 75 65 73 20   to bind values 
33a00 74 6f 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65  to host paramete
33a10 72 73 20 69 6e 20 70 72 65 70 61 72 65 64 20 73  rs in prepared s
33a20 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 52 65  tatements..** Re
33a30 66 65 72 20 74 6f 20 74 68 65 20 5b 53 51 4c 20  fer to the [SQL 
33a40 70 61 72 61 6d 65 74 65 72 5d 20 64 6f 63 75 6d  parameter] docum
33a50 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 64 64  entation for add
33a60 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74  itional informat
33a70 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ion..**.** ^The 
33a80 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62  sqlite3_result_b
33a90 6c 6f 62 28 29 20 69 6e 74 65 72 66 61 63 65 20  lob() interface 
33aa0 73 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 20  sets the result 
33ab0 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69  from.** an appli
33ac0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
33ad0 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68  unction to be th
33ae0 65 20 42 4c 4f 42 20 77 68 6f 73 65 20 63 6f 6e  e BLOB whose con
33af0 74 65 6e 74 20 69 73 20 70 6f 69 6e 74 65 64 0a  tent is pointed.
33b00 2a 2a 20 74 6f 20 62 79 20 74 68 65 20 73 65 63  ** to by the sec
33b10 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 6e  ond parameter an
33b20 64 20 77 68 69 63 68 20 69 73 20 4e 20 62 79 74  d which is N byt
33b30 65 73 20 6c 6f 6e 67 20 77 68 65 72 65 20 4e 20  es long where N 
33b40 69 73 20 74 68 65 0a 2a 2a 20 74 68 69 72 64 20  is the.** third 
33b50 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a  parameter..**.**
33b60 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
33b70 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 29 20  sult_zeroblob() 
33b80 69 6e 74 65 72 66 61 63 65 73 20 73 65 74 20 74  interfaces set t
33b90 68 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20  he result of.** 
33ba0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
33bb0 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
33bc0 20 74 6f 20 62 65 20 61 20 42 4c 4f 42 20 63 6f   to be a BLOB co
33bd0 6e 74 61 69 6e 69 6e 67 20 61 6c 6c 20 7a 65 72  ntaining all zer
33be0 6f 0a 2a 2a 20 62 79 74 65 73 20 61 6e 64 20 4e  o.** bytes and N
33bf0 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 2c 20   bytes in size, 
33c00 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 76  where N is the v
33c10 61 6c 75 65 20 6f 66 20 74 68 65 20 32 6e 64 20  alue of the 2nd 
33c20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a  parameter..**.**
33c30 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
33c40 73 75 6c 74 5f 64 6f 75 62 6c 65 28 29 20 69 6e  sult_double() in
33c50 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65  terface sets the
33c60 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20   result from.** 
33c70 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  an application-d
33c80 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
33c90 74 6f 20 62 65 20 61 20 66 6c 6f 61 74 69 6e 67  to be a floating
33ca0 20 70 6f 69 6e 74 20 76 61 6c 75 65 20 73 70 65   point value spe
33cb0 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 69 74 73  cified.** by its
33cc0 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a   2nd argument..*
33cd0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
33ce0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
33cf0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73   and sqlite3_res
33d00 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 66 75  ult_error16() fu
33d10 6e 63 74 69 6f 6e 73 0a 2a 2a 20 63 61 75 73 65  nctions.** cause
33d20 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 65 64   the implemented
33d30 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f   SQL function to
33d40 20 74 68 72 6f 77 20 61 6e 20 65 78 63 65 70 74   throw an except
33d50 69 6f 6e 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ion..** ^SQLite 
33d60 75 73 65 73 20 74 68 65 20 73 74 72 69 6e 67 20  uses the string 
33d70 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68  pointed to by th
33d80 65 0a 2a 2a 20 32 6e 64 20 70 61 72 61 6d 65 74  e.** 2nd paramet
33d90 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 72 65  er of sqlite3_re
33da0 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72 20  sult_error() or 
33db0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
33dc0 72 72 6f 72 31 36 28 29 0a 2a 2a 20 61 73 20 74  rror16().** as t
33dd0 68 65 20 74 65 78 74 20 6f 66 20 61 6e 20 65 72  he text of an er
33de0 72 6f 72 20 6d 65 73 73 61 67 65 2e 20 20 5e 53  ror message.  ^S
33df0 51 4c 69 74 65 20 69 6e 74 65 72 70 72 65 74 73  QLite interprets
33e00 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65   the error.** me
33e10 73 73 61 67 65 20 73 74 72 69 6e 67 20 66 72 6f  ssage string fro
33e20 6d 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  m sqlite3_result
33e30 5f 65 72 72 6f 72 28 29 20 61 73 20 55 54 46 2d  _error() as UTF-
33e40 38 2e 20 5e 53 51 4c 69 74 65 0a 2a 2a 20 69 6e  8. ^SQLite.** in
33e50 74 65 72 70 72 65 74 73 20 74 68 65 20 73 74 72  terprets the str
33e60 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  ing from sqlite3
33e70 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
33e80 29 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 6e  ) as UTF-16 in n
33e90 61 74 69 76 65 0a 2a 2a 20 62 79 74 65 20 6f 72  ative.** byte or
33ea0 64 65 72 2e 20 20 5e 49 66 20 74 68 65 20 74 68  der.  ^If the th
33eb0 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
33ec0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
33ed0 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71  error().** or sq
33ee0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
33ef0 6f 72 31 36 28 29 20 69 73 20 6e 65 67 61 74 69  or16() is negati
33f00 76 65 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74  ve then SQLite t
33f10 61 6b 65 73 20 61 73 20 74 68 65 20 65 72 72 6f  akes as the erro
33f20 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 61 6c 6c  r.** message all
33f30 20 74 65 78 74 20 75 70 20 74 68 72 6f 75 67 68   text up through
33f40 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20   the first zero 
33f50 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 5e 49  character..** ^I
33f60 66 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  f the third para
33f70 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
33f80 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20  _result_error() 
33f90 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65  or.** sqlite3_re
33fa0 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 69  sult_error16() i
33fb0 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 74  s non-negative t
33fc0 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73  hen SQLite takes
33fd0 20 74 68 61 74 20 6d 61 6e 79 0a 2a 2a 20 62 79   that many.** by
33fe0 74 65 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74  tes (not charact
33ff0 65 72 73 29 20 66 72 6f 6d 20 74 68 65 20 32 6e  ers) from the 2n
34000 64 20 70 61 72 61 6d 65 74 65 72 20 61 73 20 74  d parameter as t
34010 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  he error message
34020 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
34030 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
34040 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73   and sqlite3_res
34050 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a  ult_error16().**
34060 20 72 6f 75 74 69 6e 65 73 20 6d 61 6b 65 20 61   routines make a
34070 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66   private copy of
34080 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61   the error messa
34090 67 65 20 74 65 78 74 20 62 65 66 6f 72 65 0a 2a  ge text before.*
340a0 2a 20 74 68 65 79 20 72 65 74 75 72 6e 2e 20 20  * they return.  
340b0 48 65 6e 63 65 2c 20 74 68 65 20 63 61 6c 6c 69  Hence, the calli
340c0 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20  ng function can 
340d0 64 65 61 6c 6c 6f 63 61 74 65 20 6f 72 0a 2a 2a  deallocate or.**
340e0 20 6d 6f 64 69 66 79 20 74 68 65 20 74 65 78 74   modify the text
340f0 20 61 66 74 65 72 20 74 68 65 79 20 72 65 74 75   after they retu
34100 72 6e 20 77 69 74 68 6f 75 74 20 68 61 72 6d 2e  rn without harm.
34110 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
34120 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f  _result_error_co
34130 64 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 68  de() function ch
34140 61 6e 67 65 73 20 74 68 65 20 65 72 72 6f 72 20  anges the error 
34150 63 6f 64 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64  code.** returned
34160 20 62 79 20 53 51 4c 69 74 65 20 61 73 20 61 20   by SQLite as a 
34170 72 65 73 75 6c 74 20 6f 66 20 61 6e 20 65 72 72  result of an err
34180 6f 72 20 69 6e 20 61 20 66 75 6e 63 74 69 6f 6e  or in a function
34190 2e 20 20 5e 42 79 20 64 65 66 61 75 6c 74 2c 0a  .  ^By default,.
341a0 2a 2a 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64  ** the error cod
341b0 65 20 69 73 20 53 51 4c 49 54 45 5f 45 52 52 4f  e is SQLITE_ERRO
341c0 52 2e 20 20 5e 41 20 73 75 62 73 65 71 75 65 6e  R.  ^A subsequen
341d0 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  t call to sqlite
341e0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
341f0 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  .** or sqlite3_r
34200 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20  esult_error16() 
34210 72 65 73 65 74 73 20 74 68 65 20 65 72 72 6f 72  resets the error
34220 20 63 6f 64 65 20 74 6f 20 53 51 4c 49 54 45 5f   code to SQLITE_
34230 45 52 52 4f 52 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ERROR..**.** ^Th
34240 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
34250 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28 29 20  _error_toobig() 
34260 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73  interface causes
34270 20 53 51 4c 69 74 65 20 74 6f 20 74 68 72 6f 77   SQLite to throw
34280 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 69 6e 64   an.** error ind
34290 69 63 61 74 69 6e 67 20 74 68 61 74 20 61 20 73  icating that a s
342a0 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 69 73  tring or BLOB is
342b0 20 74 6f 6f 20 6c 6f 6e 67 20 74 6f 20 72 65 70   too long to rep
342c0 72 65 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54  resent..**.** ^T
342d0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
342e0 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 29 20  t_error_nomem() 
342f0 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73  interface causes
34300 20 53 51 4c 69 74 65 20 74 6f 20 74 68 72 6f 77   SQLite to throw
34310 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 69 6e 64   an.** error ind
34320 69 63 61 74 69 6e 67 20 74 68 61 74 20 61 20 6d  icating that a m
34330 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
34340 20 66 61 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e   failed..**.** ^
34350 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
34360 6c 74 5f 69 6e 74 28 29 20 69 6e 74 65 72 66 61  lt_int() interfa
34370 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75  ce sets the retu
34380 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74  rn value.** of t
34390 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
343a0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
343b0 74 6f 20 62 65 20 74 68 65 20 33 32 2d 62 69 74  to be the 32-bit
343c0 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a   signed integer.
343d0 2a 2a 20 76 61 6c 75 65 20 67 69 76 65 6e 20 69  ** value given i
343e0 6e 20 74 68 65 20 32 6e 64 20 61 72 67 75 6d 65  n the 2nd argume
343f0 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  nt..** ^The sqli
34400 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34  te3_result_int64
34410 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74  () interface set
34420 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  s the return val
34430 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70  ue.** of the app
34440 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
34450 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
34460 74 68 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65  the 64-bit signe
34470 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c  d integer.** val
34480 75 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20  ue given in the 
34490 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  2nd argument..**
344a0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
344b0 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 29 20 69  _result_null() i
344c0 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68  nterface sets th
344d0 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a  e return value.*
344e0 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61  * of the applica
344f0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
34500 63 74 69 6f 6e 20 74 6f 20 62 65 20 4e 55 4c 4c  ction to be NULL
34510 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
34520 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
34530 28 29 2c 20 73 71 6c 69 74 65 33 5f 72 65 73 75  (), sqlite3_resu
34540 6c 74 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20  lt_text16(),.** 
34550 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
34560 65 78 74 31 36 6c 65 28 29 2c 20 61 6e 64 20 73  ext16le(), and s
34570 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
34580 78 74 31 36 62 65 28 29 20 69 6e 74 65 72 66 61  xt16be() interfa
34590 63 65 73 0a 2a 2a 20 73 65 74 20 74 68 65 20 72  ces.** set the r
345a0 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74  eturn value of t
345b0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
345c0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
345d0 74 6f 20 62 65 0a 2a 2a 20 61 20 74 65 78 74 20  to be.** a text 
345e0 73 74 72 69 6e 67 20 77 68 69 63 68 20 69 73 20  string which is 
345f0 72 65 70 72 65 73 65 6e 74 65 64 20 61 73 20 55  represented as U
34600 54 46 2d 38 2c 20 55 54 46 2d 31 36 20 6e 61 74  TF-8, UTF-16 nat
34610 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2c 0a  ive byte order,.
34620 2a 2a 20 55 54 46 2d 31 36 20 6c 69 74 74 6c 65  ** UTF-16 little
34630 20 65 6e 64 69 61 6e 2c 20 6f 72 20 55 54 46 2d   endian, or UTF-
34640 31 36 20 62 69 67 20 65 6e 64 69 61 6e 2c 20 72  16 big endian, r
34650 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20  espectively..** 
34660 5e 53 51 4c 69 74 65 20 74 61 6b 65 73 20 74 68  ^SQLite takes th
34670 65 20 74 65 78 74 20 72 65 73 75 6c 74 20 66 72  e text result fr
34680 6f 6d 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  om the applicati
34690 6f 6e 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 32  on from.** the 2
346a0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20  nd parameter of 
346b0 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  the sqlite3_resu
346c0 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61  lt_text* interfa
346d0 63 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ces..** ^If the 
346e0 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  3rd parameter to
346f0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   the sqlite3_res
34700 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66  ult_text* interf
34710 61 63 65 73 0a 2a 2a 20 69 73 20 6e 65 67 61 74  aces.** is negat
34720 69 76 65 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  ive, then SQLite
34730 20 74 61 6b 65 73 20 72 65 73 75 6c 74 20 74 65   takes result te
34740 78 74 20 66 72 6f 6d 20 74 68 65 20 32 6e 64 20  xt from the 2nd 
34750 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 68 72  parameter.** thr
34760 6f 75 67 68 20 74 68 65 20 66 69 72 73 74 20 7a  ough the first z
34770 65 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a  ero character..*
34780 2a 20 5e 49 66 20 74 68 65 20 33 72 64 20 70 61  * ^If the 3rd pa
34790 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73  rameter to the s
347a0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
347b0 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  xt* interfaces.*
347c0 2a 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  * is non-negativ
347d0 65 2c 20 74 68 65 6e 20 61 73 20 6d 61 6e 79 20  e, then as many 
347e0 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72 61  bytes (not chara
347f0 63 74 65 72 73 29 20 6f 66 20 74 68 65 20 74 65  cters) of the te
34800 78 74 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f  xt.** pointed to
34810 20 62 79 20 74 68 65 20 32 6e 64 20 70 61 72 61   by the 2nd para
34820 6d 65 74 65 72 20 61 72 65 20 74 61 6b 65 6e 20  meter are taken 
34830 61 73 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  as the applicati
34840 6f 6e 2d 64 65 66 69 6e 65 64 0a 2a 2a 20 66 75  on-defined.** fu
34850 6e 63 74 69 6f 6e 20 72 65 73 75 6c 74 2e 20 20  nction result.  
34860 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d  If the 3rd param
34870 65 74 65 72 20 69 73 20 6e 6f 6e 2d 6e 65 67 61  eter is non-nega
34880 74 69 76 65 2c 20 74 68 65 6e 20 69 74 0a 2a 2a  tive, then it.**
34890 20 6d 75 73 74 20 62 65 20 74 68 65 20 62 79 74   must be the byt
348a0 65 20 6f 66 66 73 65 74 20 69 6e 74 6f 20 74 68  e offset into th
348b0 65 20 73 74 72 69 6e 67 20 77 68 65 72 65 20 74  e string where t
348c0 68 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 6f  he NUL terminato
348d0 72 20 77 6f 75 6c 64 0a 2a 2a 20 61 70 70 65 61  r would.** appea
348e0 72 20 69 66 20 74 68 65 20 73 74 72 69 6e 67 20  r if the string 
348f0 77 68 65 72 65 20 4e 55 4c 20 74 65 72 6d 69 6e  where NUL termin
34900 61 74 65 64 2e 20 20 49 66 20 61 6e 79 20 4e 55  ated.  If any NU
34910 4c 20 63 68 61 72 61 63 74 65 72 73 20 6f 63 63  L characters occ
34920 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20 73 74 72  ur.** in the str
34930 69 6e 67 20 61 74 20 61 20 62 79 74 65 20 6f 66  ing at a byte of
34940 66 73 65 74 20 74 68 61 74 20 69 73 20 6c 65 73  fset that is les
34950 73 20 74 68 61 6e 20 74 68 65 20 76 61 6c 75 65  s than the value
34960 20 6f 66 20 74 68 65 20 33 72 64 0a 2a 2a 20 70   of the 3rd.** p
34970 61 72 61 6d 65 74 65 72 2c 20 74 68 65 6e 20 74  arameter, then t
34980 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72  he resulting str
34990 69 6e 67 20 77 69 6c 6c 20 63 6f 6e 74 61 69 6e  ing will contain
349a0 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 20 61   embedded NULs a
349b0 6e 64 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74  nd the.** result
349c0 20 6f 66 20 65 78 70 72 65 73 73 69 6f 6e 73 20   of expressions 
349d0 6f 70 65 72 61 74 69 6e 67 20 6f 6e 20 73 74 72  operating on str
349e0 69 6e 67 73 20 77 69 74 68 20 65 6d 62 65 64 64  ings with embedd
349f0 65 64 20 4e 55 4c 73 20 69 73 20 75 6e 64 65 66  ed NULs is undef
34a00 69 6e 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ined..** ^If the
34a10 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   4th parameter t
34a20 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65  o the sqlite3_re
34a30 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72  sult_text* inter
34a40 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69  faces.** or sqli
34a50 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20  te3_result_blob 
34a60 69 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f  is a non-NULL po
34a70 69 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 4c 69  inter, then SQLi
34a80 74 65 20 63 61 6c 6c 73 20 74 68 61 74 0a 2a 2a  te calls that.**
34a90 20 66 75 6e 63 74 69 6f 6e 20 61 73 20 74 68 65   function as the
34aa0 20 64 65 73 74 72 75 63 74 6f 72 20 6f 6e 20 74   destructor on t
34ab0 68 65 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 20  he text or BLOB 
34ac0 72 65 73 75 6c 74 20 77 68 65 6e 20 69 74 20 68  result when it h
34ad0 61 73 0a 2a 2a 20 66 69 6e 69 73 68 65 64 20 75  as.** finished u
34ae0 73 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c 74  sing that result
34af0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68  ..** ^If the 4th
34b00 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
34b10 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
34b20 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65  _text* interface
34b30 73 20 6f 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  s or to.** sqlit
34b40 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69  e3_result_blob i
34b50 73 20 74 68 65 20 73 70 65 63 69 61 6c 20 63 6f  s the special co
34b60 6e 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 53 54  nstant SQLITE_ST
34b70 41 54 49 43 2c 20 74 68 65 6e 20 53 51 4c 69 74  ATIC, then SQLit
34b80 65 0a 2a 2a 20 61 73 73 75 6d 65 73 20 74 68 61  e.** assumes tha
34b90 74 20 74 68 65 20 74 65 78 74 20 6f 72 20 42 4c  t the text or BL
34ba0 4f 42 20 72 65 73 75 6c 74 20 69 73 20 69 6e 20  OB result is in 
34bb0 63 6f 6e 73 74 61 6e 74 20 73 70 61 63 65 20 61  constant space a
34bc0 6e 64 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 63  nd does not.** c
34bd0 6f 70 79 20 74 68 65 20 63 6f 6e 74 65 6e 74 20  opy the content 
34be0 6f 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  of the parameter
34bf0 20 6e 6f 72 20 63 61 6c 6c 20 61 20 64 65 73 74   nor call a dest
34c00 72 75 63 74 6f 72 20 6f 6e 20 74 68 65 20 63 6f  ructor on the co
34c10 6e 74 65 6e 74 0a 2a 2a 20 77 68 65 6e 20 69 74  ntent.** when it
34c20 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 75 73   has finished us
34c30 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c 74 2e  ing that result.
34c40 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20  .** ^If the 4th 
34c50 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
34c60 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
34c70 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73  text* interfaces
34c80 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  .** or sqlite3_r
34c90 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68  esult_blob is th
34ca0 65 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74 61  e special consta
34cb0 6e 74 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49  nt SQLITE_TRANSI
34cc0 45 4e 54 0a 2a 2a 20 74 68 65 6e 20 53 51 4c 69  ENT.** then SQLi
34cd0 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20  te makes a copy 
34ce0 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 6e  of the result in
34cf0 74 6f 20 73 70 61 63 65 20 6f 62 74 61 69 6e 65  to space obtaine
34d00 64 20 66 72 6f 6d 0a 2a 2a 20 66 72 6f 6d 20 5b  d from.** from [
34d10 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
34d20 5d 20 62 65 66 6f 72 65 20 69 74 20 72 65 74 75  ] before it retu
34d30 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  rns..**.** ^The 
34d40 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
34d50 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63 65  alue() interface
34d60 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c 74   sets the result
34d70 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69   of.** the appli
34d80 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
34d90 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20  unction to be a 
34da0 63 6f 70 79 20 74 68 65 0a 2a 2a 20 5b 75 6e 70  copy the.** [unp
34db0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
34dc0 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 73  _value] object s
34dd0 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20  pecified by the 
34de0 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20  2nd parameter.  
34df0 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ^The.** sqlite3_
34e00 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 69  result_value() i
34e10 6e 74 65 72 66 61 63 65 20 6d 61 6b 65 73 20 61  nterface makes a
34e20 20 63 6f 70 79 20 6f 66 20 74 68 65 20 5b 73 71   copy of the [sq
34e30 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20  lite3_value].** 
34e40 73 6f 20 74 68 61 74 20 74 68 65 20 5b 73 71 6c  so that the [sql
34e50 69 74 65 33 5f 76 61 6c 75 65 5d 20 73 70 65 63  ite3_value] spec
34e60 69 66 69 65 64 20 69 6e 20 74 68 65 20 70 61 72  ified in the par
34e70 61 6d 65 74 65 72 20 6d 61 79 20 63 68 61 6e 67  ameter may chang
34e80 65 20 6f 72 0a 2a 2a 20 62 65 20 64 65 61 6c 6c  e or.** be deall
34e90 6f 63 61 74 65 64 20 61 66 74 65 72 20 73 71 6c  ocated after sql
34ea0 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75  ite3_result_valu
34eb0 65 28 29 20 72 65 74 75 72 6e 73 20 77 69 74 68  e() returns with
34ec0 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e 41 20  out harm..** ^A 
34ed0 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  [protected sqlit
34ee0 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
34ef0 20 6d 61 79 20 61 6c 77 61 79 73 20 62 65 20 75   may always be u
34f00 73 65 64 20 77 68 65 72 65 20 61 6e 0a 2a 2a 20  sed where an.** 
34f10 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c  [unprotected sql
34f20 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
34f30 63 74 20 69 73 20 72 65 71 75 69 72 65 64 2c 20  ct is required, 
34f40 73 6f 20 65 69 74 68 65 72 0a 2a 2a 20 6b 69 6e  so either.** kin
34f50 64 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 76 61  d of [sqlite3_va
34f60 6c 75 65 5d 20 6f 62 6a 65 63 74 20 63 61 6e 20  lue] object can 
34f70 62 65 20 75 73 65 64 20 77 69 74 68 20 74 68 69  be used with thi
34f80 73 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a  s interface..**.
34f90 2a 2a 20 49 66 20 74 68 65 73 65 20 72 6f 75 74  ** If these rout
34fa0 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20  ines are called 
34fb0 66 72 6f 6d 20 77 69 74 68 69 6e 20 74 68 65 20  from within the 
34fc0 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64  different thread
34fd0 0a 2a 2a 20 74 68 61 6e 20 74 68 65 20 6f 6e 65  .** than the one
34fe0 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20   containing the 
34ff0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
35000 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 68 61  ned function tha
35010 74 20 72 65 63 65 69 76 65 64 0a 2a 2a 20 74 68  t received.** th
35020 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  e [sqlite3_conte
35030 78 74 5d 20 70 6f 69 6e 74 65 72 2c 20 74 68 65  xt] pointer, the
35040 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64   results are und
35050 65 66 69 6e 65 64 2e 0a 2a 2f 0a 76 6f 69 64 20  efined..*/.void 
35060 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62  sqlite3_result_b
35070 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  lob(sqlite3_cont
35080 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64  ext*, const void
35090 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28  *, int, void(*)(
350a0 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71  void*));.void sq
350b0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75  lite3_result_dou
350c0 62 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ble(sqlite3_cont
350d0 65 78 74 2a 2c 20 64 6f 75 62 6c 65 29 3b 0a 76  ext*, double);.v
350e0 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
350f0 6c 74 5f 65 72 72 6f 72 28 73 71 6c 69 74 65 33  lt_error(sqlite3
35100 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74  _context*, const
35110 20 63 68 61 72 2a 2c 20 69 6e 74 29 3b 0a 76 6f   char*, int);.vo
35120 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
35130 74 5f 65 72 72 6f 72 31 36 28 73 71 6c 69 74 65  t_error16(sqlite
35140 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
35150 74 20 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76  t void*, int);.v
35160 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
35170 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28  lt_error_toobig(
35180 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
35190 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
351a0 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d  result_error_nom
351b0 65 6d 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  em(sqlite3_conte
351c0 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  xt*);.void sqlit
351d0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f  e3_result_error_
351e0 63 6f 64 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e  code(sqlite3_con
351f0 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69  text*, int);.voi
35200 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
35210 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e  _int(sqlite3_con
35220 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69  text*, int);.voi
35230 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
35240 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 63  _int64(sqlite3_c
35250 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 33  ontext*, sqlite3
35260 5f 69 6e 74 36 34 29 3b 0a 76 6f 69 64 20 73 71  _int64);.void sq
35270 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c  lite3_result_nul
35280 6c 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  l(sqlite3_contex
35290 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  t*);.void sqlite
352a0 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 73 71  3_result_text(sq
352b0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
352c0 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74  const char*, int
352d0 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  , void(*)(void*)
352e0 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
352f0 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28 73 71  result_text16(sq
35300 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
35310 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
35320 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  , void(*)(void*)
35330 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
35340 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28  result_text16le(
35350 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
35360 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
35370 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  nt,void(*)(void*
35380 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  ));.void sqlite3
35390 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65  _result_text16be
353a0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
353b0 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  *, const void*, 
353c0 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64  int,void(*)(void
353d0 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  *));.void sqlite
353e0 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 73  3_result_value(s
353f0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
35400 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29   sqlite3_value*)
35410 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
35420 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 73  esult_zeroblob(s
35430 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
35440 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20   int n);../*.** 
35450 43 41 50 49 33 52 45 46 3a 20 44 65 66 69 6e 65  CAPI3REF: Define
35460 20 4e 65 77 20 43 6f 6c 6c 61 74 69 6e 67 20 53   New Collating S
35470 65 71 75 65 6e 63 65 73 0a 2a 2a 0a 2a 2a 20 5e  equences.**.** ^
35480 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  These functions 
35490 61 64 64 2c 20 72 65 6d 6f 76 65 2c 20 6f 72 20  add, remove, or 
354a0 6d 6f 64 69 66 79 20 61 20 5b 63 6f 6c 6c 61 74  modify a [collat
354b0 69 6f 6e 5d 20 61 73 73 6f 63 69 61 74 65 64 0a  ion] associated.
354c0 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 64 61 74  ** with the [dat
354d0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
354e0 5d 20 73 70 65 63 69 66 69 65 64 20 61 73 20 74  ] specified as t
354f0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
35500 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61  t..**.** ^The na
35510 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61 74  me of the collat
35520 69 6f 6e 20 69 73 20 61 20 55 54 46 2d 38 20 73  ion is a UTF-8 s
35530 74 72 69 6e 67 0a 2a 2a 20 66 6f 72 20 73 71 6c  tring.** for sql
35540 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
35550 61 74 69 6f 6e 28 29 20 61 6e 64 20 73 71 6c 69  ation() and sqli
35560 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
35570 74 69 6f 6e 5f 76 32 28 29 0a 2a 2a 20 61 6e 64  tion_v2().** and
35580 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67   a UTF-16 string
35590 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20   in native byte 
355a0 6f 72 64 65 72 20 66 6f 72 20 73 71 6c 69 74 65  order for sqlite
355b0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
355c0 6f 6e 31 36 28 29 2e 0a 2a 2a 20 5e 43 6f 6c 6c  on16()..** ^Coll
355d0 61 74 69 6f 6e 20 6e 61 6d 65 73 20 74 68 61 74  ation names that
355e0 20 63 6f 6d 70 61 72 65 20 65 71 75 61 6c 20 61   compare equal a
355f0 63 63 6f 72 64 69 6e 67 20 74 6f 20 5b 73 71 6c  ccording to [sql
35600 69 74 65 33 5f 73 74 72 6e 69 63 6d 70 28 29 5d  ite3_strnicmp()]
35610 20 61 72 65 0a 2a 2a 20 63 6f 6e 73 69 64 65 72   are.** consider
35620 65 64 20 74 6f 20 62 65 20 74 68 65 20 73 61 6d  ed to be the sam
35630 65 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28  e name..**.** ^(
35640 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  The third argume
35650 6e 74 20 28 65 54 65 78 74 52 65 70 29 20 6d 75  nt (eTextRep) mu
35660 73 74 20 62 65 20 6f 6e 65 20 6f 66 20 74 68 65  st be one of the
35670 20 63 6f 6e 73 74 61 6e 74 73 3a 0a 2a 2a 20 3c   constants:.** <
35680 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  ul>.** <li> [SQL
35690 49 54 45 5f 55 54 46 38 5d 2c 0a 2a 2a 20 3c 6c  ITE_UTF8],.** <l
356a0 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  i> [SQLITE_UTF16
356b0 4c 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  LE],.** <li> [SQ
356c0 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 0a 2a  LITE_UTF16BE],.*
356d0 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55  * <li> [SQLITE_U
356e0 54 46 31 36 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69  TF16], or.** <li
356f0 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5f  > [SQLITE_UTF16_
35700 41 4c 49 47 4e 45 44 5d 2e 0a 2a 2a 20 3c 2f 75  ALIGNED]..** </u
35710 6c 3e 29 5e 0a 2a 2a 20 5e 54 68 65 20 65 54 65  l>)^.** ^The eTe
35720 78 74 52 65 70 20 61 72 67 75 6d 65 6e 74 20 64  xtRep argument d
35730 65 74 65 72 6d 69 6e 65 73 20 74 68 65 20 65 6e  etermines the en
35740 63 6f 64 69 6e 67 20 6f 66 20 73 74 72 69 6e 67  coding of string
35750 73 20 70 61 73 73 65 64 0a 2a 2a 20 74 6f 20 74  s passed.** to t
35760 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e  he collating fun
35770 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 2c 20  ction callback, 
35780 78 43 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 54  xCallback..** ^T
35790 68 65 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  he [SQLITE_UTF16
357a0 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 55 54  ] and [SQLITE_UT
357b0 46 31 36 5f 41 4c 49 47 4e 45 44 5d 20 76 61 6c  F16_ALIGNED] val
357c0 75 65 73 20 66 6f 72 20 65 54 65 78 74 52 65 70  ues for eTextRep
357d0 0a 2a 2a 20 66 6f 72 63 65 20 73 74 72 69 6e 67  .** force string
357e0 73 20 74 6f 20 62 65 20 55 54 46 31 36 20 77 69  s to be UTF16 wi
357f0 74 68 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  th native byte o
35800 72 64 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53  rder..** ^The [S
35810 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47  QLITE_UTF16_ALIG
35820 4e 45 44 5d 20 76 61 6c 75 65 20 66 6f 72 20 65  NED] value for e
35830 54 65 78 74 52 65 70 20 66 6f 72 63 65 73 20 73  TextRep forces s
35840 74 72 69 6e 67 73 20 74 6f 20 62 65 67 69 6e 0a  trings to begin.
35850 2a 2a 20 6f 6e 20 61 6e 20 65 76 65 6e 20 62 79  ** on an even by
35860 74 65 20 61 64 64 72 65 73 73 2e 0a 2a 2a 0a 2a  te address..**.*
35870 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20 61 72  * ^The fourth ar
35880 67 75 6d 65 6e 74 2c 20 70 41 72 67 2c 20 69 73  gument, pArg, is
35890 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20   an application 
358a0 64 61 74 61 20 70 6f 69 6e 74 65 72 20 74 68 61  data pointer tha
358b0 74 20 69 73 20 70 61 73 73 65 64 0a 2a 2a 20 74  t is passed.** t
358c0 68 72 6f 75 67 68 20 61 73 20 74 68 65 20 66 69  hrough as the fi
358d0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
358e0 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75  the collating fu
358f0 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 2e  nction callback.
35900 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 66 74  .**.** ^The fift
35910 68 20 61 72 67 75 6d 65 6e 74 2c 20 78 43 61 6c  h argument, xCal
35920 6c 62 61 63 6b 2c 20 69 73 20 61 20 70 6f 69 6e  lback, is a poin
35930 74 65 72 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61  ter to the colla
35940 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a  ting function..*
35950 2a 20 5e 4d 75 6c 74 69 70 6c 65 20 63 6f 6c 6c  * ^Multiple coll
35960 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20  ating functions 
35970 63 61 6e 20 62 65 20 72 65 67 69 73 74 65 72 65  can be registere
35980 64 20 75 73 69 6e 67 20 74 68 65 20 73 61 6d 65  d using the same
35990 20 6e 61 6d 65 20 62 75 74 0a 2a 2a 20 77 69 74   name but.** wit
359a0 68 20 64 69 66 66 65 72 65 6e 74 20 65 54 65 78  h different eTex
359b0 74 52 65 70 20 70 61 72 61 6d 65 74 65 72 73 20  tRep parameters 
359c0 61 6e 64 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  and SQLite will 
359d0 75 73 65 20 77 68 69 63 68 65 76 65 72 0a 2a 2a  use whichever.**
359e0 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72   function requir
359f0 65 73 20 74 68 65 20 6c 65 61 73 74 20 61 6d 6f  es the least amo
35a00 75 6e 74 20 6f 66 20 64 61 74 61 20 74 72 61 6e  unt of data tran
35a10 73 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 20 5e  sformation..** ^
35a20 49 66 20 74 68 65 20 78 43 61 6c 6c 62 61 63 6b  If the xCallback
35a30 20 61 72 67 75 6d 65 6e 74 20 69 73 20 4e 55 4c   argument is NUL
35a40 4c 20 74 68 65 6e 20 74 68 65 20 63 6f 6c 6c 61  L then the colla
35a50 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73  ting function is
35a60 0a 2a 2a 20 64 65 6c 65 74 65 64 2e 20 20 5e 57  .** deleted.  ^W
35a70 68 65 6e 20 61 6c 6c 20 63 6f 6c 6c 61 74 69 6e  hen all collatin
35a80 67 20 66 75 6e 63 74 69 6f 6e 73 20 68 61 76 69  g functions havi
35a90 6e 67 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65  ng the same name
35aa0 20 61 72 65 20 64 65 6c 65 74 65 64 2c 0a 2a 2a   are deleted,.**
35ab0 20 74 68 61 74 20 63 6f 6c 6c 61 74 69 6f 6e 20   that collation 
35ac0 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 75 73 61  is no longer usa
35ad0 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ble..**.** ^The 
35ae0 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
35af0 6f 6e 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  on callback is i
35b00 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 20 63 6f  nvoked with a co
35b10 70 79 20 6f 66 20 74 68 65 20 70 41 72 67 20 0a  py of the pArg .
35b20 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  ** application d
35b30 61 74 61 20 70 6f 69 6e 74 65 72 20 61 6e 64 20  ata pointer and 
35b40 77 69 74 68 20 74 77 6f 20 73 74 72 69 6e 67 73  with two strings
35b50 20 69 6e 20 74 68 65 20 65 6e 63 6f 64 69 6e 67   in the encoding
35b60 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79   specified.** by
35b70 20 74 68 65 20 65 54 65 78 74 52 65 70 20 61 72   the eTextRep ar
35b80 67 75 6d 65 6e 74 2e 20 20 54 68 65 20 63 6f 6c  gument.  The col
35b90 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  lating function 
35ba0 6d 75 73 74 20 72 65 74 75 72 6e 20 61 6e 0a 2a  must return an.*
35bb0 2a 20 69 6e 74 65 67 65 72 20 74 68 61 74 20 69  * integer that i
35bc0 73 20 6e 65 67 61 74 69 76 65 2c 20 7a 65 72 6f  s negative, zero
35bd0 2c 20 6f 72 20 70 6f 73 69 74 69 76 65 0a 2a 2a  , or positive.**
35be0 20 69 66 20 74 68 65 20 66 69 72 73 74 20 73 74   if the first st
35bf0 72 69 6e 67 20 69 73 20 6c 65 73 73 20 74 68 61  ring is less tha
35c00 6e 2c 20 65 71 75 61 6c 20 74 6f 2c 20 6f 72 20  n, equal to, or 
35c10 67 72 65 61 74 65 72 20 74 68 61 6e 20 74 68 65  greater than the
35c20 20 73 65 63 6f 6e 64 2c 0a 2a 2a 20 72 65 73 70   second,.** resp
35c30 65 63 74 69 76 65 6c 79 2e 20 20 41 20 63 6f 6c  ectively.  A col
35c40 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  lating function 
35c50 6d 75 73 74 20 61 6c 77 61 79 73 20 72 65 74 75  must always retu
35c60 72 6e 20 74 68 65 20 73 61 6d 65 20 61 6e 73 77  rn the same answ
35c70 65 72 0a 2a 2a 20 67 69 76 65 6e 20 74 68 65 20  er.** given the 
35c80 73 61 6d 65 20 69 6e 70 75 74 73 2e 20 20 49 66  same inputs.  If
35c90 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 63 6f 6c   two or more col
35ca0 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73  lating functions
35cb0 20 61 72 65 20 72 65 67 69 73 74 65 72 65 64 0a   are registered.
35cc0 2a 2a 20 74 6f 20 74 68 65 20 73 61 6d 65 20 63  ** to the same c
35cd0 6f 6c 6c 61 74 69 6f 6e 20 6e 61 6d 65 20 28 75  ollation name (u
35ce0 73 69 6e 67 20 64 69 66 66 65 72 65 6e 74 20 65  sing different e
35cf0 54 65 78 74 52 65 70 20 76 61 6c 75 65 73 29 20  TextRep values) 
35d00 74 68 65 6e 20 61 6c 6c 0a 2a 2a 20 6d 75 73 74  then all.** must
35d10 20 67 69 76 65 20 61 6e 20 65 71 75 69 76 61 6c   give an equival
35d20 65 6e 74 20 61 6e 73 77 65 72 20 77 68 65 6e 20  ent answer when 
35d30 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 65 71 75  invoked with equ
35d40 69 76 61 6c 65 6e 74 20 73 74 72 69 6e 67 73 2e  ivalent strings.
35d50 0a 2a 2a 20 54 68 65 20 63 6f 6c 6c 61 74 69 6e  .** The collatin
35d60 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20  g function must 
35d70 6f 62 65 79 20 74 68 65 20 66 6f 6c 6c 6f 77 69  obey the followi
35d80 6e 67 20 70 72 6f 70 65 72 74 69 65 73 20 66 6f  ng properties fo
35d90 72 20 61 6c 6c 0a 2a 2a 20 73 74 72 69 6e 67 73  r all.** strings
35da0 20 41 2c 20 42 2c 20 61 6e 64 20 43 3a 0a 2a 2a   A, B, and C:.**
35db0 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ol>.** <li>
35dc0 20 49 66 20 41 3d 3d 42 20 74 68 65 6e 20 42 3d   If A==B then B=
35dd0 3d 41 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41  =A..** <li> If A
35de0 3d 3d 42 20 61 6e 64 20 42 3d 3d 43 20 74 68 65  ==B and B==C the
35df0 6e 20 41 3d 3d 43 2e 0a 2a 2a 20 3c 6c 69 3e 20  n A==C..** <li> 
35e00 49 66 20 41 26 6c 74 3b 42 20 54 48 45 4e 20 42  If A&lt;B THEN B
35e10 26 67 74 3b 41 2e 0a 2a 2a 20 3c 6c 69 3e 20 49  &gt;A..** <li> I
35e20 66 20 41 26 6c 74 3b 42 20 61 6e 64 20 42 26 6c  f A&lt;B and B&l
35e30 74 3b 43 20 74 68 65 6e 20 41 26 6c 74 3b 43 2e  t;C then A&lt;C.
35e40 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ol>.**.** 
35e50 49 66 20 61 20 63 6f 6c 6c 61 74 69 6e 67 20 66  If a collating f
35e60 75 6e 63 74 69 6f 6e 20 66 61 69 6c 73 20 61 6e  unction fails an
35e70 79 20 6f 66 20 74 68 65 20 61 62 6f 76 65 20 63  y of the above c
35e80 6f 6e 73 74 72 61 69 6e 74 73 20 61 6e 64 20 74  onstraints and t
35e90 68 61 74 0a 2a 2a 20 63 6f 6c 6c 61 74 69 6e 67  hat.** collating
35ea0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 20 72 65   function is  re
35eb0 67 69 73 74 65 72 65 64 20 61 6e 64 20 75 73 65  gistered and use
35ec0 64 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  d, then the beha
35ed0 76 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 0a 2a  vior of SQLite.*
35ee0 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  * is undefined..
35ef0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
35f00 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
35f10 69 6f 6e 5f 76 32 28 29 20 77 6f 72 6b 73 20 6c  ion_v2() works l
35f20 69 6b 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61  ike sqlite3_crea
35f30 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 0a 2a  te_collation().*
35f40 2a 20 77 69 74 68 20 74 68 65 20 61 64 64 69 74  * with the addit
35f50 69 6f 6e 20 74 68 61 74 20 74 68 65 20 78 44 65  ion that the xDe
35f60 73 74 72 6f 79 20 63 61 6c 6c 62 61 63 6b 20 69  stroy callback i
35f70 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 20 70 41 72  s invoked on pAr
35f80 67 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20 63 6f  g when.** the co
35f90 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
35fa0 20 69 73 20 64 65 6c 65 74 65 64 2e 0a 2a 2a 20   is deleted..** 
35fb0 5e 43 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74  ^Collating funct
35fc0 69 6f 6e 73 20 61 72 65 20 64 65 6c 65 74 65 64  ions are deleted
35fd0 20 77 68 65 6e 20 74 68 65 79 20 61 72 65 20 6f   when they are o
35fe0 76 65 72 72 69 64 64 65 6e 20 62 79 20 6c 61 74  verridden by lat
35ff0 65 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 74  er.** calls to t
36000 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 63 72 65  he collation cre
36010 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 73 20  ation functions 
36020 6f 72 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20 5b  or when the.** [
36030 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
36040 69 6f 6e 5d 20 69 73 20 63 6c 6f 73 65 64 20 75  ion] is closed u
36050 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6c  sing [sqlite3_cl
36060 6f 73 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ose()]..**.** ^T
36070 68 65 20 78 44 65 73 74 72 6f 79 20 63 61 6c 6c  he xDestroy call
36080 62 61 63 6b 20 69 73 20 3c 75 3e 6e 6f 74 3c 2f  back is <u>not</
36090 75 3e 20 63 61 6c 6c 65 64 20 69 66 20 74 68 65  u> called if the
360a0 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72 65   .** sqlite3_cre
360b0 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32  ate_collation_v2
360c0 28 29 20 66 75 6e 63 74 69 6f 6e 20 66 61 69 6c  () function fail
360d0 73 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  s.  Applications
360e0 20 74 68 61 74 20 69 6e 76 6f 6b 65 0a 2a 2a 20   that invoke.** 
360f0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
36100 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 77 69  ollation_v2() wi
36110 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 78 44  th a non-NULL xD
36120 65 73 74 72 6f 79 20 61 72 67 75 6d 65 6e 74 20  estroy argument 
36130 73 68 6f 75 6c 64 20 0a 2a 2a 20 63 68 65 63 6b  should .** check
36140 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65   the return code
36150 20 61 6e 64 20 64 69 73 70 6f 73 65 20 6f 66 20   and dispose of 
36160 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
36170 64 61 74 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  data pointer.** 
36180 74 68 65 6d 73 65 6c 76 65 73 20 72 61 74 68 65  themselves rathe
36190 72 20 74 68 61 6e 20 65 78 70 65 63 74 69 6e 67  r than expecting
361a0 20 53 51 4c 69 74 65 20 74 6f 20 64 65 61 6c 20   SQLite to deal 
361b0 77 69 74 68 20 69 74 20 66 6f 72 20 74 68 65 6d  with it for them
361c0 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 64 69 66  ..** This is dif
361d0 66 65 72 65 6e 74 20 66 72 6f 6d 20 65 76 65 72  ferent from ever
361e0 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69  y other SQLite i
361f0 6e 74 65 72 66 61 63 65 2e 20 20 54 68 65 20 69  nterface.  The i
36200 6e 63 6f 6e 73 69 73 74 65 6e 63 79 20 0a 2a 2a  nconsistency .**
36210 20 69 73 20 75 6e 66 6f 72 74 75 6e 61 74 65 20   is unfortunate 
36220 62 75 74 20 63 61 6e 6e 6f 74 20 62 65 20 63 68  but cannot be ch
36230 61 6e 67 65 64 20 77 69 74 68 6f 75 74 20 62 72  anged without br
36240 65 61 6b 69 6e 67 20 62 61 63 6b 77 61 72 64 73  eaking backwards
36250 20 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69   .** compatibili
36260 74 79 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  ty..**.** See al
36270 73 6f 3a 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f  so:  [sqlite3_co
36280 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29  llation_needed()
36290 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  ] and [sqlite3_c
362a0 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31  ollation_needed1
362b0 36 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  6()]..*/.int sql
362c0 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
362d0 61 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33  ation(.  sqlite3
362e0 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  *, .  const char
362f0 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20   *zName, .  int 
36300 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69  eTextRep, .  voi
36310 64 20 2a 70 41 72 67 2c 0a 20 20 69 6e 74 28 2a  d *pArg,.  int(*
36320 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c  xCompare)(void*,
36330 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  int,const void*,
36340 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29  int,const void*)
36350 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
36360 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
36370 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c  _v2(.  sqlite3*,
36380 20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a   .  const char *
36390 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54  zName, .  int eT
363a0 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 20  extRep, .  void 
363b0 2a 70 41 72 67 2c 0a 20 20 69 6e 74 28 2a 78 43  *pArg,.  int(*xC
363c0 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e  ompare)(void*,in
363d0 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e  t,const void*,in
363e0 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 2c 0a  t,const void*),.
363f0 20 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79    void(*xDestroy
36400 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74 20  )(void*).);.int 
36410 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
36420 6f 6c 6c 61 74 69 6f 6e 31 36 28 0a 20 20 73 71  ollation16(.  sq
36430 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74  lite3*, .  const
36440 20 76 6f 69 64 20 2a 7a 4e 61 6d 65 2c 0a 20 20   void *zName,.  
36450 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20  int eTextRep, . 
36460 20 76 6f 69 64 20 2a 70 41 72 67 2c 0a 20 20 69   void *pArg,.  i
36470 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f  nt(*xCompare)(vo
36480 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f  id*,int,const vo
36490 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f  id*,int,const vo
364a0 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  id*).);../*.** C
364b0 41 50 49 33 52 45 46 3a 20 43 6f 6c 6c 61 74 69  API3REF: Collati
364c0 6f 6e 20 4e 65 65 64 65 64 20 43 61 6c 6c 62 61  on Needed Callba
364d0 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 6f 20 61 76  cks.**.** ^To av
364e0 6f 69 64 20 68 61 76 69 6e 67 20 74 6f 20 72 65  oid having to re
364f0 67 69 73 74 65 72 20 61 6c 6c 20 63 6f 6c 6c 61  gister all colla
36500 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 62  tion sequences b
36510 65 66 6f 72 65 20 61 20 64 61 74 61 62 61 73 65  efore a database
36520 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 64 2c  .** can be used,
36530 20 61 20 73 69 6e 67 6c 65 20 63 61 6c 6c 62 61   a single callba
36540 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20  ck function may 
36550 62 65 20 72 65 67 69 73 74 65 72 65 64 20 77 69  be registered wi
36560 74 68 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62  th the.** [datab
36570 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
36580 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68  to be invoked wh
36590 65 6e 65 76 65 72 20 61 6e 20 75 6e 64 65 66 69  enever an undefi
365a0 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a  ned collation.**
365b0 20 73 65 71 75 65 6e 63 65 20 69 73 20 72 65 71   sequence is req
365c0 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  uired..**.** ^If
365d0 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73   the function is
365e0 20 72 65 67 69 73 74 65 72 65 64 20 75 73 69 6e   registered usin
365f0 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  g the sqlite3_co
36600 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29  llation_needed()
36610 20 41 50 49 2c 0a 2a 2a 20 74 68 65 6e 20 69 74   API,.** then it
36620 20 69 73 20 70 61 73 73 65 64 20 74 68 65 20 6e   is passed the n
36630 61 6d 65 73 20 6f 66 20 75 6e 64 65 66 69 6e 65  ames of undefine
36640 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75  d collation sequ
36650 65 6e 63 65 73 20 61 73 20 73 74 72 69 6e 67 73  ences as strings
36660 0a 2a 2a 20 65 6e 63 6f 64 65 64 20 69 6e 20 55  .** encoded in U
36670 54 46 2d 38 2e 20 5e 49 66 20 73 71 6c 69 74 65  TF-8. ^If sqlite
36680 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
36690 65 64 31 36 28 29 20 69 73 20 75 73 65 64 2c 0a  ed16() is used,.
366a0 2a 2a 20 74 68 65 20 6e 61 6d 65 73 20 61 72 65  ** the names are
366b0 20 70 61 73 73 65 64 20 61 73 20 55 54 46 2d 31   passed as UTF-1
366c0 36 20 69 6e 20 6d 61 63 68 69 6e 65 20 6e 61 74  6 in machine nat
366d0 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a  ive byte order..
366e0 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 65 69  ** ^A call to ei
366f0 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 20 72 65  ther function re
36700 70 6c 61 63 65 73 20 74 68 65 20 65 78 69 73 74  places the exist
36710 69 6e 67 20 63 6f 6c 6c 61 74 69 6f 6e 2d 6e 65  ing collation-ne
36720 65 64 65 64 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a  eded callback..*
36730 2a 0a 2a 2a 20 5e 28 57 68 65 6e 20 74 68 65 20  *.** ^(When the 
36740 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
36750 6b 65 64 2c 20 74 68 65 20 66 69 72 73 74 20 61  ked, the first a
36760 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20 69  rgument passed i
36770 73 20 61 20 63 6f 70 79 0a 2a 2a 20 6f 66 20 74  s a copy.** of t
36780 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
36790 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  nt to sqlite3_co
367a0 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29  llation_needed()
367b0 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   or.** sqlite3_c
367c0 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31  ollation_needed1
367d0 36 28 29 2e 20 20 54 68 65 20 73 65 63 6f 6e 64  6().  The second
367e0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
367f0 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e   database.** con
36800 6e 65 63 74 69 6f 6e 2e 20 20 54 68 65 20 74 68  nection.  The th
36810 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ird argument is 
36820 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 55  one of [SQLITE_U
36830 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54  TF8], [SQLITE_UT
36840 46 31 36 42 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 53  F16BE],.** or [S
36850 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c 20  QLITE_UTF16LE], 
36860 69 6e 64 69 63 61 74 69 6e 67 20 74 68 65 20 6d  indicating the m
36870 6f 73 74 20 64 65 73 69 72 61 62 6c 65 20 66 6f  ost desirable fo
36880 72 6d 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61 74  rm of the collat
36890 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20  ion.** sequence 
368a0 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65  function require
368b0 64 2e 20 20 54 68 65 20 66 6f 75 72 74 68 20 70  d.  The fourth p
368c0 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20  arameter is the 
368d0 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 72  name of the.** r
368e0 65 71 75 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f  equired collatio
368f0 6e 20 73 65 71 75 65 6e 63 65 2e 29 5e 0a 2a 2a  n sequence.)^.**
36900 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b  .** The callback
36910 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64   function should
36920 20 72 65 67 69 73 74 65 72 20 74 68 65 20 64 65   register the de
36930 73 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20  sired collation 
36940 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  using.** [sqlite
36950 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
36960 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  on()], [sqlite3_
36970 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
36980 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71  16()], or.** [sq
36990 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
369a0 6c 61 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2f  lation_v2()]..*/
369b0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c  .int sqlite3_col
369c0 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 0a 20  lation_needed(. 
369d0 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f   sqlite3*, .  vo
369e0 69 64 2a 2c 20 0a 20 20 76 6f 69 64 28 2a 29 28  id*, .  void(*)(
369f0 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69  void*,sqlite3*,i
36a00 6e 74 20 65 54 65 78 74 52 65 70 2c 63 6f 6e 73  nt eTextRep,cons
36a10 74 20 63 68 61 72 2a 29 0a 29 3b 0a 69 6e 74 20  t char*).);.int 
36a20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
36a30 6e 5f 6e 65 65 64 65 64 31 36 28 0a 20 20 73 71  n_needed16(.  sq
36a40 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a  lite3*, .  void*
36a50 2c 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64  ,.  void(*)(void
36a60 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65  *,sqlite3*,int e
36a70 54 65 78 74 52 65 70 2c 63 6f 6e 73 74 20 76 6f  TextRep,const vo
36a80 69 64 2a 29 0a 29 3b 0a 0a 23 69 66 64 65 66 20  id*).);..#ifdef 
36a90 53 51 4c 49 54 45 5f 48 41 53 5f 43 4f 44 45 43  SQLITE_HAS_CODEC
36aa0 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20 74  ./*.** Specify t
36ab0 68 65 20 6b 65 79 20 66 6f 72 20 61 6e 20 65 6e  he key for an en
36ac0 63 72 79 70 74 65 64 20 64 61 74 61 62 61 73 65  crypted database
36ad0 2e 20 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  .  This routine 
36ae0 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 63 61 6c  should be.** cal
36af0 6c 65 64 20 72 69 67 68 74 20 61 66 74 65 72 20  led right after 
36b00 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 2e 0a  sqlite3_open()..
36b10 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 74  **.** The code t
36b20 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73  o implement this
36b30 20 41 50 49 20 69 73 20 6e 6f 74 20 61 76 61 69   API is not avai
36b40 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 70 75 62  lable in the pub
36b50 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f  lic release.** o
36b60 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74  f SQLite..*/.int
36b70 20 73 71 6c 69 74 65 33 5f 6b 65 79 28 0a 20 20   sqlite3_key(.  
36b80 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
36b90 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
36ba0 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20 62 65  * Database to be
36bb0 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f   rekeyed */.  co
36bc0 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20  nst void *pKey, 
36bd0 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20  int nKey     /* 
36be0 54 68 65 20 6b 65 79 20 2a 2f 0a 29 3b 0a 69 6e  The key */.);.in
36bf0 74 20 73 71 6c 69 74 65 33 5f 6b 65 79 5f 76 32  t sqlite3_key_v2
36c00 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
36c10 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
36c20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74     /* Database t
36c30 6f 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a  o be rekeyed */.
36c40 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44    const char *zD
36c50 62 4e 61 6d 65 2c 20 20 20 20 20 20 20 20 20 20  bName,          
36c60 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 65 20   /* Name of the 
36c70 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f  database */.  co
36c80 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20  nst void *pKey, 
36c90 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20  int nKey     /* 
36ca0 54 68 65 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f  The key */.);../
36cb0 2a 0a 2a 2a 20 43 68 61 6e 67 65 20 74 68 65 20  *.** Change the 
36cc0 6b 65 79 20 6f 6e 20 61 6e 20 6f 70 65 6e 20 64  key on an open d
36cd0 61 74 61 62 61 73 65 2e 20 20 49 66 20 74 68 65  atabase.  If the
36ce0 20 63 75 72 72 65 6e 74 20 64 61 74 61 62 61 73   current databas
36cf0 65 20 69 73 20 6e 6f 74 0a 2a 2a 20 65 6e 63 72  e is not.** encr
36d00 79 70 74 65 64 2c 20 74 68 69 73 20 72 6f 75 74  ypted, this rout
36d10 69 6e 65 20 77 69 6c 6c 20 65 6e 63 72 79 70 74  ine will encrypt
36d20 20 69 74 2e 20 20 49 66 20 70 4e 65 77 3d 3d 30   it.  If pNew==0
36d30 20 6f 72 20 6e 4e 65 77 3d 3d 30 2c 20 74 68 65   or nNew==0, the
36d40 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 69 73 20  .** database is 
36d50 64 65 63 72 79 70 74 65 64 2e 0a 2a 2a 0a 2a 2a  decrypted..**.**
36d60 20 54 68 65 20 63 6f 64 65 20 74 6f 20 69 6d 70   The code to imp
36d70 6c 65 6d 65 6e 74 20 74 68 69 73 20 41 50 49 20  lement this API 
36d80 69 73 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65  is not available
36d90 20 69 6e 20 74 68 65 20 70 75 62 6c 69 63 20 72   in the public r
36da0 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c  elease.** of SQL
36db0 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ite..*/.int sqli
36dc0 74 65 33 5f 72 65 6b 65 79 28 0a 20 20 73 71 6c  te3_rekey(.  sql
36dd0 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
36de0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44              /* D
36df0 61 74 61 62 61 73 65 20 74 6f 20 62 65 20 72 65  atabase to be re
36e00 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74  keyed */.  const
36e10 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74   void *pKey, int
36e20 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 68 65   nKey     /* The
36e30 20 6e 65 77 20 6b 65 79 20 2a 2f 0a 29 3b 0a 69   new key */.);.i
36e40 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 6b 65 79  nt sqlite3_rekey
36e50 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  _v2(.  sqlite3 *
36e60 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  db,             
36e70 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
36e80 65 20 74 6f 20 62 65 20 72 65 6b 65 79 65 64 20  e to be rekeyed 
36e90 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
36ea0 2a 7a 44 62 4e 61 6d 65 2c 20 20 20 20 20 20 20  *zDbName,       
36eb0 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74      /* Name of t
36ec0 68 65 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20  he database */. 
36ed0 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65   const void *pKe
36ee0 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20  y, int nKey     
36ef0 2f 2a 20 54 68 65 20 6e 65 77 20 6b 65 79 20 2a  /* The new key *
36f00 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 53 70 65 63  /.);../*.** Spec
36f10 69 66 79 20 74 68 65 20 61 63 74 69 76 61 74 69  ify the activati
36f20 6f 6e 20 6b 65 79 20 66 6f 72 20 61 20 53 45 45  on key for a SEE
36f30 20 64 61 74 61 62 61 73 65 2e 20 20 55 6e 6c 65   database.  Unle
36f40 73 73 20 0a 2a 2a 20 61 63 74 69 76 61 74 65 64  ss .** activated
36f50 2c 20 6e 6f 6e 65 20 6f 66 20 74 68 65 20 53 45  , none of the SE
36f60 45 20 72 6f 75 74 69 6e 65 73 20 77 69 6c 6c 20  E routines will 
36f70 77 6f 72 6b 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71  work..*/.void sq
36f80 6c 69 74 65 33 5f 61 63 74 69 76 61 74 65 5f 73  lite3_activate_s
36f90 65 65 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  ee(.  const char
36fa0 20 2a 7a 50 61 73 73 50 68 72 61 73 65 20 20 20   *zPassPhrase   
36fb0 20 20 20 20 20 2f 2a 20 41 63 74 69 76 61 74 69       /* Activati
36fc0 6f 6e 20 70 68 72 61 73 65 20 2a 2f 0a 29 3b 0a  on phrase */.);.
36fd0 23 65 6e 64 69 66 0a 0a 23 69 66 64 65 66 20 53  #endif..#ifdef S
36fe0 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 45 52  QLITE_ENABLE_CER
36ff0 4f 44 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79  OD./*.** Specify
37000 20 74 68 65 20 61 63 74 69 76 61 74 69 6f 6e 20   the activation 
37010 6b 65 79 20 66 6f 72 20 61 20 43 45 52 4f 44 20  key for a CEROD 
37020 64 61 74 61 62 61 73 65 2e 20 20 55 6e 6c 65 73  database.  Unles
37030 73 20 0a 2a 2a 20 61 63 74 69 76 61 74 65 64 2c  s .** activated,
37040 20 6e 6f 6e 65 20 6f 66 20 74 68 65 20 43 45 52   none of the CER
37050 4f 44 20 72 6f 75 74 69 6e 65 73 20 77 69 6c 6c  OD routines will
37060 20 77 6f 72 6b 2e 0a 2a 2f 0a 76 6f 69 64 20 73   work..*/.void s
37070 71 6c 69 74 65 33 5f 61 63 74 69 76 61 74 65 5f  qlite3_activate_
37080 63 65 72 6f 64 28 0a 20 20 63 6f 6e 73 74 20 63  cerod(.  const c
37090 68 61 72 20 2a 7a 50 61 73 73 50 68 72 61 73 65  har *zPassPhrase
370a0 20 20 20 20 20 20 20 20 2f 2a 20 41 63 74 69 76          /* Activ
370b0 61 74 69 6f 6e 20 70 68 72 61 73 65 20 2a 2f 0a  ation phrase */.
370c0 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a  );.#endif../*.**
370d0 20 43 41 50 49 33 52 45 46 3a 20 53 75 73 70 65   CAPI3REF: Suspe
370e0 6e 64 20 45 78 65 63 75 74 69 6f 6e 20 46 6f 72  nd Execution For
370f0 20 41 20 53 68 6f 72 74 20 54 69 6d 65 0a 2a 2a   A Short Time.**
37100 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
37110 73 6c 65 65 70 28 29 20 66 75 6e 63 74 69 6f 6e  sleep() function
37120 20 63 61 75 73 65 73 20 74 68 65 20 63 75 72 72   causes the curr
37130 65 6e 74 20 74 68 72 65 61 64 20 74 6f 20 73 75  ent thread to su
37140 73 70 65 6e 64 20 65 78 65 63 75 74 69 6f 6e 0a  spend execution.
37150 2a 2a 20 66 6f 72 20 61 74 20 6c 65 61 73 74 20  ** for at least 
37160 61 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c  a number of mill
37170 69 73 65 63 6f 6e 64 73 20 73 70 65 63 69 66 69  iseconds specifi
37180 65 64 20 69 6e 20 69 74 73 20 70 61 72 61 6d 65  ed in its parame
37190 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  ter..**.** If th
371a0 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  e operating syst
371b0 65 6d 20 64 6f 65 73 20 6e 6f 74 20 73 75 70 70  em does not supp
371c0 6f 72 74 20 73 6c 65 65 70 20 72 65 71 75 65 73  ort sleep reques
371d0 74 73 20 77 69 74 68 0a 2a 2a 20 6d 69 6c 6c 69  ts with.** milli
371e0 73 65 63 6f 6e 64 20 74 69 6d 65 20 72 65 73 6f  second time reso
371f0 6c 75 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65  lution, then the
37200 20 74 69 6d 65 20 77 69 6c 6c 20 62 65 20 72 6f   time will be ro
37210 75 6e 64 65 64 20 75 70 20 74 6f 0a 2a 2a 20 74  unded up to.** t
37220 68 65 20 6e 65 61 72 65 73 74 20 73 65 63 6f 6e  he nearest secon
37230 64 2e 20 54 68 65 20 6e 75 6d 62 65 72 20 6f 66  d. The number of
37240 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66   milliseconds of
37250 20 73 6c 65 65 70 20 61 63 74 75 61 6c 6c 79 0a   sleep actually.
37260 2a 2a 20 72 65 71 75 65 73 74 65 64 20 66 72 6f  ** requested fro
37270 6d 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20  m the operating 
37280 73 79 73 74 65 6d 20 69 73 20 72 65 74 75 72 6e  system is return
37290 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74  ed..**.** ^SQLit
372a0 65 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 69  e implements thi
372b0 73 20 69 6e 74 65 72 66 61 63 65 20 62 79 20 63  s interface by c
372c0 61 6c 6c 69 6e 67 20 74 68 65 20 78 53 6c 65 65  alling the xSlee
372d0 70 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f 66  p().** method of
372e0 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71   the default [sq
372f0 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
37300 74 2e 20 20 49 66 20 74 68 65 20 78 53 6c 65 65  t.  If the xSlee
37310 70 28 29 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66  p() method.** of
37320 20 74 68 65 20 64 65 66 61 75 6c 74 20 56 46 53   the default VFS
37330 20 69 73 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e   is not implemen
37340 74 65 64 20 63 6f 72 72 65 63 74 6c 79 2c 20 6f  ted correctly, o
37350 72 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74 65  r not implemente
37360 64 20 61 74 0a 2a 2a 20 61 6c 6c 2c 20 74 68 65  d at.** all, the
37370 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f  n the behavior o
37380 66 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28  f sqlite3_sleep(
37390 29 20 6d 61 79 20 64 65 76 69 61 74 65 20 66 72  ) may deviate fr
373a0 6f 6d 20 74 68 65 20 64 65 73 63 72 69 70 74 69  om the descripti
373b0 6f 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 70 72 65  on.** in the pre
373c0 76 69 6f 75 73 20 70 61 72 61 67 72 61 70 68 73  vious paragraphs
373d0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
373e0 5f 73 6c 65 65 70 28 69 6e 74 29 3b 0a 0a 2f 2a  _sleep(int);../*
373f0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 61  .** CAPI3REF: Na
37400 6d 65 20 4f 66 20 54 68 65 20 46 6f 6c 64 65 72  me Of The Folder
37410 20 48 6f 6c 64 69 6e 67 20 54 65 6d 70 6f 72 61   Holding Tempora
37420 72 79 20 46 69 6c 65 73 0a 2a 2a 0a 2a 2a 20 5e  ry Files.**.** ^
37430 28 49 66 20 74 68 69 73 20 67 6c 6f 62 61 6c 20  (If this global 
37440 76 61 72 69 61 62 6c 65 20 69 73 20 6d 61 64 65  variable is made
37450 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 61 20 73   to point to a s
37460 74 72 69 6e 67 20 77 68 69 63 68 20 69 73 0a 2a  tring which is.*
37470 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 61 20  * the name of a 
37480 66 6f 6c 64 65 72 20 28 61 2e 6b 2e 61 2e 20 64  folder (a.k.a. d
37490 69 72 65 63 74 6f 72 79 29 2c 20 74 68 65 6e 20  irectory), then 
374a0 61 6c 6c 20 74 65 6d 70 6f 72 61 72 79 20 66 69  all temporary fi
374b0 6c 65 73 0a 2a 2a 20 63 72 65 61 74 65 64 20 62  les.** created b
374c0 79 20 53 51 4c 69 74 65 20 77 68 65 6e 20 75 73  y SQLite when us
374d0 69 6e 67 20 61 20 62 75 69 6c 74 2d 69 6e 20 5b  ing a built-in [
374e0 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 56 46  sqlite3_vfs | VF
374f0 53 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 70 6c  S].** will be pl
37500 61 63 65 64 20 69 6e 20 74 68 61 74 20 64 69 72  aced in that dir
37510 65 63 74 6f 72 79 2e 29 5e 20 20 5e 49 66 20 74  ectory.)^  ^If t
37520 68 69 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20  his variable.** 
37530 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
37540 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 70  r, then SQLite p
37550 65 72 66 6f 72 6d 73 20 61 20 73 65 61 72 63 68  erforms a search
37560 20 66 6f 72 20 61 6e 20 61 70 70 72 6f 70 72 69   for an appropri
37570 61 74 65 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79  ate.** temporary
37580 20 66 69 6c 65 20 64 69 72 65 63 74 6f 72 79 2e   file directory.
37590 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74  .**.** It is not
375a0 20 73 61 66 65 20 74 6f 20 72 65 61 64 20 6f 72   safe to read or
375b0 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61 72   modify this var
375c0 69 61 62 6c 65 20 69 6e 20 6d 6f 72 65 20 74 68  iable in more th
375d0 61 6e 20 6f 6e 65 0a 2a 2a 20 74 68 72 65 61 64  an one.** thread
375e0 20 61 74 20 61 20 74 69 6d 65 2e 20 20 49 74 20   at a time.  It 
375f0 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 72  is not safe to r
37600 65 61 64 20 6f 72 20 6d 6f 64 69 66 79 20 74 68  ead or modify th
37610 69 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 69  is variable.** i
37620 66 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f  f a [database co
37630 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 65 69  nnection] is bei
37640 6e 67 20 75 73 65 64 20 61 74 20 74 68 65 20 73  ng used at the s
37650 61 6d 65 20 74 69 6d 65 20 69 6e 20 61 20 73 65  ame time in a se
37660 70 61 72 61 74 65 0a 2a 2a 20 74 68 72 65 61 64  parate.** thread
37670 2e 0a 2a 2a 20 49 74 20 69 73 20 69 6e 74 65 6e  ..** It is inten
37680 64 65 64 20 74 68 61 74 20 74 68 69 73 20 76 61  ded that this va
37690 72 69 61 62 6c 65 20 62 65 20 73 65 74 20 6f 6e  riable be set on
376a0 63 65 0a 2a 2a 20 61 73 20 70 61 72 74 20 6f 66  ce.** as part of
376b0 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61 6c   process initial
376c0 69 7a 61 74 69 6f 6e 20 61 6e 64 20 62 65 66 6f  ization and befo
376d0 72 65 20 61 6e 79 20 53 51 4c 69 74 65 20 69 6e  re any SQLite in
376e0 74 65 72 66 61 63 65 0a 2a 2a 20 72 6f 75 74 69  terface.** routi
376f0 6e 65 73 20 68 61 76 65 20 62 65 65 6e 20 63 61  nes have been ca
37700 6c 6c 65 64 20 61 6e 64 20 74 68 61 74 20 74 68  lled and that th
37710 69 73 20 76 61 72 69 61 62 6c 65 20 72 65 6d 61  is variable rema
37720 69 6e 20 75 6e 63 68 61 6e 67 65 64 0a 2a 2a 20  in unchanged.** 
37730 74 68 65 72 65 61 66 74 65 72 2e 0a 2a 2a 0a 2a  thereafter..**.*
37740 2a 20 5e 54 68 65 20 5b 74 65 6d 70 5f 73 74 6f  * ^The [temp_sto
37750 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61  re_directory pra
37760 67 6d 61 5d 20 6d 61 79 20 6d 6f 64 69 66 79 20  gma] may modify 
37770 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 61 6e  this variable an
37780 64 20 63 61 75 73 65 0a 2a 2a 20 69 74 20 74 6f  d cause.** it to
37790 20 70 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72 79   point to memory
377a0 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b   obtained from [
377b0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 2e  sqlite3_malloc].
377c0 20 20 5e 46 75 72 74 68 65 72 6d 6f 72 65 2c 0a    ^Furthermore,.
377d0 2a 2a 20 74 68 65 20 5b 74 65 6d 70 5f 73 74 6f  ** the [temp_sto
377e0 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61  re_directory pra
377f0 67 6d 61 5d 20 61 6c 77 61 79 73 20 61 73 73 75  gma] always assu
37800 6d 65 73 20 74 68 61 74 20 61 6e 79 20 73 74 72  mes that any str
37810 69 6e 67 0a 2a 2a 20 74 68 61 74 20 74 68 69 73  ing.** that this
37820 20 76 61 72 69 61 62 6c 65 20 70 6f 69 6e 74 73   variable points
37830 20 74 6f 20 69 73 20 68 65 6c 64 20 69 6e 20 6d   to is held in m
37840 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66  emory obtained f
37850 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  rom .** [sqlite3
37860 5f 6d 61 6c 6c 6f 63 5d 20 61 6e 64 20 74 68 65  _malloc] and the
37870 20 70 72 61 67 6d 61 20 6d 61 79 20 61 74 74 65   pragma may atte
37880 6d 70 74 20 74 6f 20 66 72 65 65 20 74 68 61 74  mpt to free that
37890 20 6d 65 6d 6f 72 79 0a 2a 2a 20 75 73 69 6e 67   memory.** using
378a0 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5d 2e   [sqlite3_free].
378b0 0a 2a 2a 20 48 65 6e 63 65 2c 20 69 66 20 74 68  .** Hence, if th
378c0 69 73 20 76 61 72 69 61 62 6c 65 20 69 73 20 6d  is variable is m
378d0 6f 64 69 66 69 65 64 20 64 69 72 65 63 74 6c 79  odified directly
378e0 2c 20 65 69 74 68 65 72 20 69 74 20 73 68 6f 75  , either it shou
378f0 6c 64 20 62 65 0a 2a 2a 20 6d 61 64 65 20 4e 55  ld be.** made NU
37900 4c 4c 20 6f 72 20 6d 61 64 65 20 74 6f 20 70 6f  LL or made to po
37910 69 6e 74 20 74 6f 20 6d 65 6d 6f 72 79 20 6f 62  int to memory ob
37920 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  tained from [sql
37930 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 0a 2a 2a 20  ite3_malloc].** 
37940 6f 72 20 65 6c 73 65 20 74 68 65 20 75 73 65 20  or else the use 
37950 6f 66 20 74 68 65 20 5b 74 65 6d 70 5f 73 74 6f  of the [temp_sto
37960 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61  re_directory pra
37970 67 6d 61 5d 20 73 68 6f 75 6c 64 20 62 65 20 61  gma] should be a
37980 76 6f 69 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62  voided..**.** <b
37990 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73  >Note to Windows
379a0 20 52 75 6e 74 69 6d 65 20 75 73 65 72 73 3a 3c   Runtime users:<
379b0 2f 62 3e 20 20 54 68 65 20 74 65 6d 70 6f 72 61  /b>  The tempora
379c0 72 79 20 64 69 72 65 63 74 6f 72 79 20 6d 75 73  ry directory mus
379d0 74 20 62 65 20 73 65 74 0a 2a 2a 20 70 72 69 6f  t be set.** prio
379e0 72 20 74 6f 20 63 61 6c 6c 69 6e 67 20 5b 73 71  r to calling [sq
379f0 6c 69 74 65 33 5f 6f 70 65 6e 5d 20 6f 72 20 5b  lite3_open] or [
37a00 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 5d  sqlite3_open_v2]
37a10 2e 20 20 4f 74 68 65 72 77 69 73 65 2c 20 76 61  .  Otherwise, va
37a20 72 69 6f 75 73 0a 2a 2a 20 66 65 61 74 75 72 65  rious.** feature
37a30 73 20 74 68 61 74 20 72 65 71 75 69 72 65 20 74  s that require t
37a40 68 65 20 75 73 65 20 6f 66 20 74 65 6d 70 6f 72  he use of tempor
37a50 61 72 79 20 66 69 6c 65 73 20 6d 61 79 20 66 61  ary files may fa
37a60 69 6c 2e 20 20 48 65 72 65 20 69 73 20 61 6e 0a  il.  Here is an.
37a70 2a 2a 20 65 78 61 6d 70 6c 65 20 6f 66 20 68 6f  ** example of ho
37a80 77 20 74 6f 20 64 6f 20 74 68 69 73 20 75 73 69  w to do this usi
37a90 6e 67 20 43 2b 2b 20 77 69 74 68 20 74 68 65 20  ng C++ with the 
37aa0 57 69 6e 64 6f 77 73 20 52 75 6e 74 69 6d 65 3a  Windows Runtime:
37ab0 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
37ac0 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 4c 50 43 57  te><pre>.** LPCW
37ad0 53 54 52 20 7a 50 61 74 68 20 3d 20 57 69 6e 64  STR zPath = Wind
37ae0 6f 77 73 3a 3a 53 74 6f 72 61 67 65 3a 3a 41 70  ows::Storage::Ap
37af0 70 6c 69 63 61 74 69 6f 6e 44 61 74 61 3a 3a 43  plicationData::C
37b00 75 72 72 65 6e 74 2d 3e 0a 2a 2a 20 26 6e 62 73  urrent->.** &nbs
37b10 70 3b 20 20 20 20 20 54 65 6d 70 6f 72 61 72 79  p;     Temporary
37b20 46 6f 6c 64 65 72 2d 3e 50 61 74 68 2d 3e 44 61  Folder->Path->Da
37b30 74 61 28 29 3b 0a 2a 2a 20 63 68 61 72 20 7a 50  ta();.** char zP
37b40 61 74 68 42 75 66 26 23 39 31 3b 4d 41 58 5f 50  athBuf&#91;MAX_P
37b50 41 54 48 20 2b 20 31 26 23 39 33 3b 3b 0a 2a 2a  ATH + 1&#93;;.**
37b60 20 6d 65 6d 73 65 74 28 7a 50 61 74 68 42 75 66   memset(zPathBuf
37b70 2c 20 30 2c 20 73 69 7a 65 6f 66 28 7a 50 61 74  , 0, sizeof(zPat
37b80 68 42 75 66 29 29 3b 0a 2a 2a 20 57 69 64 65 43  hBuf));.** WideC
37b90 68 61 72 54 6f 4d 75 6c 74 69 42 79 74 65 28 43  harToMultiByte(C
37ba0 50 5f 55 54 46 38 2c 20 30 2c 20 7a 50 61 74 68  P_UTF8, 0, zPath
37bb0 2c 20 2d 31 2c 20 7a 50 61 74 68 42 75 66 2c 20  , -1, zPathBuf, 
37bc0 73 69 7a 65 6f 66 28 7a 50 61 74 68 42 75 66 29  sizeof(zPathBuf)
37bd0 2c 0a 2a 2a 20 26 6e 62 73 70 3b 20 20 20 20 20  ,.** &nbsp;     
37be0 4e 55 4c 4c 2c 20 4e 55 4c 4c 29 3b 0a 2a 2a 20  NULL, NULL);.** 
37bf0 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64 69 72  sqlite3_temp_dir
37c00 65 63 74 6f 72 79 20 3d 20 73 71 6c 69 74 65 33  ectory = sqlite3
37c10 5f 6d 70 72 69 6e 74 66 28 22 25 73 22 2c 20 7a  _mprintf("%s", z
37c20 50 61 74 68 42 75 66 29 3b 0a 2a 2a 20 3c 2f 70  PathBuf);.** </p
37c30 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
37c40 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54 45 52  .*/.SQLITE_EXTER
37c50 4e 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  N char *sqlite3_
37c60 74 65 6d 70 5f 64 69 72 65 63 74 6f 72 79 3b 0a  temp_directory;.
37c70 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
37c80 20 4e 61 6d 65 20 4f 66 20 54 68 65 20 46 6f 6c   Name Of The Fol
37c90 64 65 72 20 48 6f 6c 64 69 6e 67 20 44 61 74 61  der Holding Data
37ca0 62 61 73 65 20 46 69 6c 65 73 0a 2a 2a 0a 2a 2a  base Files.**.**
37cb0 20 5e 28 49 66 20 74 68 69 73 20 67 6c 6f 62 61   ^(If this globa
37cc0 6c 20 76 61 72 69 61 62 6c 65 20 69 73 20 6d 61  l variable is ma
37cd0 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 61  de to point to a
37ce0 20 73 74 72 69 6e 67 20 77 68 69 63 68 20 69 73   string which is
37cf0 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  .** the name of 
37d00 61 20 66 6f 6c 64 65 72 20 28 61 2e 6b 2e 61 2e  a folder (a.k.a.
37d10 20 64 69 72 65 63 74 6f 72 79 29 2c 20 74 68 65   directory), the
37d20 6e 20 61 6c 6c 20 64 61 74 61 62 61 73 65 20 66  n all database f
37d30 69 6c 65 73 0a 2a 2a 20 73 70 65 63 69 66 69 65  iles.** specifie
37d40 64 20 77 69 74 68 20 61 20 72 65 6c 61 74 69 76  d with a relativ
37d50 65 20 70 61 74 68 6e 61 6d 65 20 61 6e 64 20 63  e pathname and c
37d60 72 65 61 74 65 64 20 6f 72 20 61 63 63 65 73 73  reated or access
37d70 65 64 20 62 79 0a 2a 2a 20 53 51 4c 69 74 65 20  ed by.** SQLite 
37d80 77 68 65 6e 20 75 73 69 6e 67 20 61 20 62 75 69  when using a bui
37d90 6c 74 2d 69 6e 20 77 69 6e 64 6f 77 73 20 5b 73  lt-in windows [s
37da0 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 56 46 53  qlite3_vfs | VFS
37db0 5d 20 77 69 6c 6c 20 62 65 20 61 73 73 75 6d 65  ] will be assume
37dc0 64 0a 2a 2a 20 74 6f 20 62 65 20 72 65 6c 61 74  d.** to be relat
37dd0 69 76 65 20 74 6f 20 74 68 61 74 20 64 69 72 65  ive to that dire
37de0 63 74 6f 72 79 2e 29 5e 20 5e 49 66 20 74 68 69  ctory.)^ ^If thi
37df0 73 20 76 61 72 69 61 62 6c 65 20 69 73 20 61 20  s variable is a 
37e00 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 2c  NULL.** pointer,
37e10 20 74 68 65 6e 20 53 51 4c 69 74 65 20 61 73 73   then SQLite ass
37e20 75 6d 65 73 20 74 68 61 74 20 61 6c 6c 20 64 61  umes that all da
37e30 74 61 62 61 73 65 20 66 69 6c 65 73 20 73 70 65  tabase files spe
37e40 63 69 66 69 65 64 0a 2a 2a 20 77 69 74 68 20 61  cified.** with a
37e50 20 72 65 6c 61 74 69 76 65 20 70 61 74 68 6e 61   relative pathna
37e60 6d 65 20 61 72 65 20 72 65 6c 61 74 69 76 65 20  me are relative 
37e70 74 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20 64  to the current d
37e80 69 72 65 63 74 6f 72 79 0a 2a 2a 20 66 6f 72 20  irectory.** for 
37e90 74 68 65 20 70 72 6f 63 65 73 73 2e 20 20 4f 6e  the process.  On
37ea0 6c 79 20 74 68 65 20 77 69 6e 64 6f 77 73 20 56  ly the windows V
37eb0 46 53 20 6d 61 6b 65 73 20 75 73 65 20 6f 66 20  FS makes use of 
37ec0 74 68 69 73 20 67 6c 6f 62 61 6c 0a 2a 2a 20 76  this global.** v
37ed0 61 72 69 61 62 6c 65 3b 20 69 74 20 69 73 20 69  ariable; it is i
37ee0 67 6e 6f 72 65 64 20 62 79 20 74 68 65 20 75 6e  gnored by the un
37ef0 69 78 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 43 68  ix VFS..**.** Ch
37f00 61 6e 67 69 6e 67 20 74 68 65 20 76 61 6c 75 65  anging the value
37f10 20 6f 66 20 74 68 69 73 20 76 61 72 69 61 62 6c   of this variabl
37f20 65 20 77 68 69 6c 65 20 61 20 64 61 74 61 62 61  e while a databa
37f30 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
37f40 0a 2a 2a 20 6f 70 65 6e 20 63 61 6e 20 72 65 73  .** open can res
37f50 75 6c 74 20 69 6e 20 61 20 63 6f 72 72 75 70 74  ult in a corrupt
37f60 20 64 61 74 61 62 61 73 65 2e 0a 2a 2a 0a 2a 2a   database..**.**
37f70 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20   It is not safe 
37f80 74 6f 20 72 65 61 64 20 6f 72 20 6d 6f 64 69 66  to read or modif
37f90 79 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20  y this variable 
37fa0 69 6e 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65  in more than one
37fb0 0a 2a 2a 20 74 68 72 65 61 64 20 61 74 20 61 20  .** thread at a 
37fc0 74 69 6d 65 2e 20 20 49 74 20 69 73 20 6e 6f 74  time.  It is not
37fd0 20 73 61 66 65 20 74 6f 20 72 65 61 64 20 6f 72   safe to read or
37fe0 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61 72   modify this var
37ff0 69 61 62 6c 65 0a 2a 2a 20 69 66 20 61 20 5b 64  iable.** if a [d
38000 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
38010 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20 75 73 65  on] is being use
38020 64 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69  d at the same ti
38030 6d 65 20 69 6e 20 61 20 73 65 70 61 72 61 74 65  me in a separate
38040 0a 2a 2a 20 74 68 72 65 61 64 2e 0a 2a 2a 20 49  .** thread..** I
38050 74 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74 68  t is intended th
38060 61 74 20 74 68 69 73 20 76 61 72 69 61 62 6c 65  at this variable
38070 20 62 65 20 73 65 74 20 6f 6e 63 65 0a 2a 2a 20   be set once.** 
38080 61 73 20 70 61 72 74 20 6f 66 20 70 72 6f 63 65  as part of proce
38090 73 73 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f  ss initializatio
380a0 6e 20 61 6e 64 20 62 65 66 6f 72 65 20 61 6e 79  n and before any
380b0 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
380c0 65 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 68 61  e.** routines ha
380d0 76 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 61  ve been called a
380e0 6e 64 20 74 68 61 74 20 74 68 69 73 20 76 61 72  nd that this var
380f0 69 61 62 6c 65 20 72 65 6d 61 69 6e 20 75 6e 63  iable remain unc
38100 68 61 6e 67 65 64 0a 2a 2a 20 74 68 65 72 65 61  hanged.** therea
38110 66 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  fter..**.** ^The
38120 20 5b 64 61 74 61 5f 73 74 6f 72 65 5f 64 69 72   [data_store_dir
38130 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 6d  ectory pragma] m
38140 61 79 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76  ay modify this v
38150 61 72 69 61 62 6c 65 20 61 6e 64 20 63 61 75 73  ariable and caus
38160 65 0a 2a 2a 20 69 74 20 74 6f 20 70 6f 69 6e 74  e.** it to point
38170 20 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69   to memory obtai
38180 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ned from [sqlite
38190 33 5f 6d 61 6c 6c 6f 63 5d 2e 20 20 5e 46 75 72  3_malloc].  ^Fur
381a0 74 68 65 72 6d 6f 72 65 2c 0a 2a 2a 20 74 68 65  thermore,.** the
381b0 20 5b 64 61 74 61 5f 73 74 6f 72 65 5f 64 69 72   [data_store_dir
381c0 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 61  ectory pragma] a
381d0 6c 77 61 79 73 20 61 73 73 75 6d 65 73 20 74 68  lways assumes th
381e0 61 74 20 61 6e 79 20 73 74 72 69 6e 67 0a 2a 2a  at any string.**
381f0 20 74 68 61 74 20 74 68 69 73 20 76 61 72 69 61   that this varia
38200 62 6c 65 20 70 6f 69 6e 74 73 20 74 6f 20 69 73  ble points to is
38210 20 68 65 6c 64 20 69 6e 20 6d 65 6d 6f 72 79 20   held in memory 
38220 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a  obtained from .*
38230 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  * [sqlite3_mallo
38240 63 5d 20 61 6e 64 20 74 68 65 20 70 72 61 67 6d  c] and the pragm
38250 61 20 6d 61 79 20 61 74 74 65 6d 70 74 20 74 6f  a may attempt to
38260 20 66 72 65 65 20 74 68 61 74 20 6d 65 6d 6f 72   free that memor
38270 79 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69  y.** using [sqli
38280 74 65 33 5f 66 72 65 65 5d 2e 0a 2a 2a 20 48 65  te3_free]..** He
38290 6e 63 65 2c 20 69 66 20 74 68 69 73 20 76 61 72  nce, if this var
382a0 69 61 62 6c 65 20 69 73 20 6d 6f 64 69 66 69 65  iable is modifie
382b0 64 20 64 69 72 65 63 74 6c 79 2c 20 65 69 74 68  d directly, eith
382c0 65 72 20 69 74 20 73 68 6f 75 6c 64 20 62 65 0a  er it should be.
382d0 2a 2a 20 6d 61 64 65 20 4e 55 4c 4c 20 6f 72 20  ** made NULL or 
382e0 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f  made to point to
382f0 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64   memory obtained
38300 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
38310 61 6c 6c 6f 63 5d 0a 2a 2a 20 6f 72 20 65 6c 73  alloc].** or els
38320 65 20 74 68 65 20 75 73 65 20 6f 66 20 74 68 65  e the use of the
38330 20 5b 64 61 74 61 5f 73 74 6f 72 65 5f 64 69 72   [data_store_dir
38340 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 73  ectory pragma] s
38350 68 6f 75 6c 64 20 62 65 20 61 76 6f 69 64 65 64  hould be avoided
38360 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54 45  ..*/.SQLITE_EXTE
38370 52 4e 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  RN char *sqlite3
38380 5f 64 61 74 61 5f 64 69 72 65 63 74 6f 72 79 3b  _data_directory;
38390 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
383a0 3a 20 54 65 73 74 20 46 6f 72 20 41 75 74 6f 2d  : Test For Auto-
383b0 43 6f 6d 6d 69 74 20 4d 6f 64 65 0a 2a 2a 20 4b  Commit Mode.** K
383c0 45 59 57 4f 52 44 53 3a 20 7b 61 75 74 6f 63 6f  EYWORDS: {autoco
383d0 6d 6d 69 74 20 6d 6f 64 65 7d 0a 2a 2a 0a 2a 2a  mmit mode}.**.**
383e0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65   ^The sqlite3_ge
383f0 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 29 20 69  t_autocommit() i
38400 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
38410 20 6e 6f 6e 2d 7a 65 72 6f 20 6f 72 0a 2a 2a 20   non-zero or.** 
38420 7a 65 72 6f 20 69 66 20 74 68 65 20 67 69 76 65  zero if the give
38430 6e 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  n database conne
38440 63 74 69 6f 6e 20 69 73 20 6f 72 20 69 73 20 6e  ction is or is n
38450 6f 74 20 69 6e 20 61 75 74 6f 63 6f 6d 6d 69 74  ot in autocommit
38460 20 6d 6f 64 65 2c 0a 2a 2a 20 72 65 73 70 65 63   mode,.** respec
38470 74 69 76 65 6c 79 2e 20 20 5e 41 75 74 6f 63 6f  tively.  ^Autoco
38480 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 6f 6e 20  mmit mode is on 
38490 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 5e  by default..** ^
384a0 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20  Autocommit mode 
384b0 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 20 61  is disabled by a
384c0 20 5b 42 45 47 49 4e 5d 20 73 74 61 74 65 6d 65   [BEGIN] stateme
384d0 6e 74 2e 0a 2a 2a 20 5e 41 75 74 6f 63 6f 6d 6d  nt..** ^Autocomm
384e0 69 74 20 6d 6f 64 65 20 69 73 20 72 65 2d 65 6e  it mode is re-en
384f0 61 62 6c 65 64 20 62 79 20 61 20 5b 43 4f 4d 4d  abled by a [COMM
38500 49 54 5d 20 6f 72 20 5b 52 4f 4c 4c 42 41 43 4b  IT] or [ROLLBACK
38510 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 63 65 72 74  ]..**.** If cert
38520 61 69 6e 20 6b 69 6e 64 73 20 6f 66 20 65 72 72  ain kinds of err
38530 6f 72 73 20 6f 63 63 75 72 20 6f 6e 20 61 20 73  ors occur on a s
38540 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20  tatement within 
38550 61 20 6d 75 6c 74 69 2d 73 74 61 74 65 6d 65 6e  a multi-statemen
38560 74 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e  t.** transaction
38570 20 28 65 72 72 6f 72 73 20 69 6e 63 6c 75 64 69   (errors includi
38580 6e 67 20 5b 53 51 4c 49 54 45 5f 46 55 4c 4c 5d  ng [SQLITE_FULL]
38590 2c 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d  , [SQLITE_IOERR]
385a0 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d  ,.** [SQLITE_NOM
385b0 45 4d 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 55 53  EM], [SQLITE_BUS
385c0 59 5d 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f  Y], and [SQLITE_
385d0 49 4e 54 45 52 52 55 50 54 5d 29 20 74 68 65 6e  INTERRUPT]) then
385e0 20 74 68 65 0a 2a 2a 20 74 72 61 6e 73 61 63 74   the.** transact
385f0 69 6f 6e 20 6d 69 67 68 74 20 62 65 20 72 6f 6c  ion might be rol
38600 6c 65 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 74  led back automat
38610 69 63 61 6c 6c 79 2e 20 20 54 68 65 20 6f 6e 6c  ically.  The onl
38620 79 20 77 61 79 20 74 6f 0a 2a 2a 20 66 69 6e 64  y way to.** find
38630 20 6f 75 74 20 77 68 65 74 68 65 72 20 53 51 4c   out whether SQL
38640 69 74 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ite automaticall
38650 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 74 68  y rolled back th
38660 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 61 66  e transaction af
38670 74 65 72 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20  ter.** an error 
38680 69 73 20 74 6f 20 75 73 65 20 74 68 69 73 20 66  is to use this f
38690 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49  unction..**.** I
386a0 66 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64  f another thread
386b0 20 63 68 61 6e 67 65 73 20 74 68 65 20 61 75 74   changes the aut
386c0 6f 63 6f 6d 6d 69 74 20 73 74 61 74 75 73 20 6f  ocommit status o
386d0 66 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  f the database.*
386e0 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69  * connection whi
386f0 6c 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  le this routine 
38700 69 73 20 72 75 6e 6e 69 6e 67 2c 20 74 68 65 6e  is running, then
38710 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
38720 65 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e 65  e.** is undefine
38730 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  d..*/.int sqlite
38740 33 5f 67 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74  3_get_autocommit
38750 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
38760 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69 6e  ** CAPI3REF: Fin
38770 64 20 54 68 65 20 44 61 74 61 62 61 73 65 20 48  d The Database H
38780 61 6e 64 6c 65 20 4f 66 20 41 20 50 72 65 70 61  andle Of A Prepa
38790 72 65 64 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a  red Statement.**
387a0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
387b0 5f 64 62 5f 68 61 6e 64 6c 65 20 69 6e 74 65 72  _db_handle inter
387c0 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
387d0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
387e0 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 0a 2a 2a  ction] handle.**
387f0 20 74 6f 20 77 68 69 63 68 20 61 20 5b 70 72 65   to which a [pre
38800 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
38810 20 62 65 6c 6f 6e 67 73 2e 20 20 5e 54 68 65 20   belongs.  ^The 
38820 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec