/ Hex Artifact Content
Login

Artifact a98eb3e8c86c934ea6f5bcfc6b69653dde2f4ed4:


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 20 20 54 68 65 0a 2a  hen open.  The.*
68c0: 2a 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49  * SQLITE_IOCAP_I
68d0: 4d 4d 55 54 41 42 4c 45 20 66 6c 61 67 20 69 6e  MMUTABLE flag in
68e0: 64 69 63 61 74 65 73 20 74 68 61 74 20 74 68 65  dicates that the
68f0: 20 66 69 6c 65 20 69 73 20 6f 6e 0a 2a 2a 20 72   file is on.** r
6900: 65 61 64 2d 6f 6e 6c 79 20 6d 65 64 69 61 20 61  ead-only media a
6910: 6e 64 20 63 61 6e 6e 6f 74 20 62 65 20 63 68 61  nd cannot be cha
6920: 6e 67 65 64 20 65 76 65 6e 20 62 79 20 70 72 6f  nged even by pro
6930: 63 65 73 73 65 73 20 77 69 74 68 0a 2a 2a 20 65  cesses with.** e
6940: 6c 65 76 61 74 65 64 20 70 72 69 76 69 6c 65 67  levated privileg
6950: 65 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  es..*/.#define S
6960: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
6970: 49 43 20 20 20 20 20 20 20 20 20 20 20 20 20 20  IC              
6980: 20 20 20 30 78 30 30 30 30 30 30 30 31 0a 23 64     0x00000001.#d
6990: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
69a0: 41 50 5f 41 54 4f 4d 49 43 35 31 32 20 20 20 20  AP_ATOMIC512    
69b0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
69c0: 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c  0002.#define SQL
69d0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
69e0: 31 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  1K              
69f0: 20 30 78 30 30 30 30 30 30 30 34 0a 23 64 65 66   0x00000004.#def
6a00: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
6a10: 5f 41 54 4f 4d 49 43 32 4b 20 20 20 20 20 20 20  _ATOMIC2K       
6a20: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
6a30: 30 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  08.#define SQLIT
6a40: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b  E_IOCAP_ATOMIC4K
6a50: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
6a60: 78 30 30 30 30 30 30 31 30 0a 23 64 65 66 69 6e  x00000010.#defin
6a70: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
6a80: 54 4f 4d 49 43 38 4b 20 20 20 20 20 20 20 20 20  TOMIC8K         
6a90: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 32 30        0x00000020
6aa0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6ab0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 20  IOCAP_ATOMIC16K 
6ac0: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
6ad0: 30 30 30 30 30 34 30 0a 23 64 65 66 69 6e 65 20  0000040.#define 
6ae0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
6af0: 4d 49 43 33 32 4b 20 20 20 20 20 20 20 20 20 20  MIC32K          
6b00: 20 20 20 20 30 78 30 30 30 30 30 30 38 30 0a 23      0x00000080.#
6b10: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
6b20: 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b 20 20 20  CAP_ATOMIC64K   
6b30: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
6b40: 30 30 31 30 30 0a 23 64 65 66 69 6e 65 20 53 51  00100.#define SQ
6b50: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f  LITE_IOCAP_SAFE_
6b60: 41 50 50 45 4e 44 20 20 20 20 20 20 20 20 20 20  APPEND          
6b70: 20 20 30 78 30 30 30 30 30 32 30 30 0a 23 64 65    0x00000200.#de
6b80: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
6b90: 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 20 20 20  P_SEQUENTIAL    
6ba0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6bb0: 34 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  400.#define SQLI
6bc0: 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45 54  TE_IOCAP_UNDELET
6bd0: 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 20 20  ABLE_WHEN_OPEN  
6be0: 30 78 30 30 30 30 30 38 30 30 0a 23 64 65 66 69  0x00000800.#defi
6bf0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
6c00: 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52  POWERSAFE_OVERWR
6c10: 49 54 45 20 20 20 20 30 78 30 30 30 30 31 30 30  ITE    0x0000100
6c20: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
6c30: 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41 42 4c 45  _IOCAP_IMMUTABLE
6c40: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
6c50: 30 30 30 30 32 30 30 30 0a 0a 2f 2a 0a 2a 2a 20  00002000../*.** 
6c60: 43 41 50 49 33 52 45 46 3a 20 46 69 6c 65 20 4c  CAPI3REF: File L
6c70: 6f 63 6b 69 6e 67 20 4c 65 76 65 6c 73 0a 2a 2a  ocking Levels.**
6c80: 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20  .** SQLite uses 
6c90: 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 69 6e 74  one of these int
6ca0: 65 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74  eger values as t
6cb0: 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67  he second.** arg
6cc0: 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73 20 69  ument to calls i
6cd0: 74 20 6d 61 6b 65 73 20 74 6f 20 74 68 65 20 78  t makes to the x
6ce0: 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f  Lock() and xUnlo
6cf0: 63 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a 2a 20  ck() methods.** 
6d00: 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69  of an [sqlite3_i
6d10: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63  o_methods] objec
6d20: 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  t..*/.#define SQ
6d30: 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20  LITE_LOCK_NONE  
6d40: 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e          0.#defin
6d50: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48  e SQLITE_LOCK_SH
6d60: 41 52 45 44 20 20 20 20 20 20 20 20 31 0a 23 64  ARED        1.#d
6d70: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43  efine SQLITE_LOC
6d80: 4b 5f 52 45 53 45 52 56 45 44 20 20 20 20 20 20  K_RESERVED      
6d90: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
6da0: 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 20 20  _LOCK_PENDING   
6db0: 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51      3.#define SQ
6dc0: 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53  LITE_LOCK_EXCLUS
6dd0: 49 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a  IVE     4../*.**
6de0: 20 43 41 50 49 33 52 45 46 3a 20 53 79 6e 63 68   CAPI3REF: Synch
6df0: 72 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70 65 20  ronization Type 
6e00: 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  Flags.**.** When
6e10: 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20   SQLite invokes 
6e20: 74 68 65 20 78 53 79 6e 63 28 29 20 6d 65 74 68  the xSync() meth
6e30: 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c  od of an.** [sql
6e40: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
6e50: 20 6f 62 6a 65 63 74 20 69 74 20 75 73 65 73 20   object it uses 
6e60: 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66  a combination of
6e70: 0a 2a 2a 20 74 68 65 73 65 20 69 6e 74 65 67 65  .** these intege
6e80: 72 20 76 61 6c 75 65 73 20 61 73 20 74 68 65 20  r values as the 
6e90: 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e  second argument.
6ea0: 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20  .**.** When the 
6eb0: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41  SQLITE_SYNC_DATA
6ec0: 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20 75 73 65  ONLY flag is use
6ed0: 64 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74  d, it means that
6ee0: 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f 70 65   the.** sync ope
6ef0: 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64  ration only need
6f00: 73 20 74 6f 20 66 6c 75 73 68 20 64 61 74 61 20  s to flush data 
6f10: 74 6f 20 6d 61 73 73 20 73 74 6f 72 61 67 65 2e  to mass storage.
6f20: 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72    Inode.** infor
6f30: 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f 74 20  mation need not 
6f40: 62 65 20 66 6c 75 73 68 65 64 2e 20 49 66 20 74  be flushed. If t
6f50: 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69  he lower four bi
6f60: 74 73 20 6f 66 20 74 68 65 20 66 6c 61 67 0a 2a  ts of the flag.*
6f70: 2a 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53  * equal SQLITE_S
6f80: 59 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68 61 74  YNC_NORMAL, that
6f90: 20 6d 65 61 6e 73 20 74 6f 20 75 73 65 20 6e 6f   means to use no
6fa0: 72 6d 61 6c 20 66 73 79 6e 63 28 29 20 73 65 6d  rmal fsync() sem
6fb0: 61 6e 74 69 63 73 2e 0a 2a 2a 20 49 66 20 74 68  antics..** If th
6fc0: 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74  e lower four bit
6fd0: 73 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53  s equal SQLITE_S
6fe0: 59 4e 43 5f 46 55 4c 4c 2c 20 74 68 61 74 20 6d  YNC_FULL, that m
6ff0: 65 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65 20 4d  eans.** to use M
7000: 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75  ac OS X style fu
7010: 6c 6c 73 79 6e 63 20 69 6e 73 74 65 61 64 20 6f  llsync instead o
7020: 66 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a  f fsync()..**.**
7030: 20 44 6f 20 6e 6f 74 20 63 6f 6e 66 75 73 65 20   Do not confuse 
7040: 74 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  the SQLITE_SYNC_
7050: 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54  NORMAL and SQLIT
7060: 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67  E_SYNC_FULL flag
7070: 73 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 50  s.** with the [P
7080: 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75  RAGMA synchronou
7090: 73 5d 3d 4e 4f 52 4d 41 4c 20 61 6e 64 20 5b 50  s]=NORMAL and [P
70a0: 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75  RAGMA synchronou
70b0: 73 5d 3d 46 55 4c 4c 0a 2a 2a 20 73 65 74 74 69  s]=FULL.** setti
70c0: 6e 67 73 2e 20 20 54 68 65 20 5b 73 79 6e 63 68  ngs.  The [synch
70d0: 72 6f 6e 6f 75 73 20 70 72 61 67 6d 61 5d 20 64  ronous pragma] d
70e0: 65 74 65 72 6d 69 6e 65 73 20 77 68 65 6e 20 63  etermines when c
70f0: 61 6c 6c 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78  alls to the.** x
7100: 53 79 6e 63 20 56 46 53 20 6d 65 74 68 6f 64 20  Sync VFS method 
7110: 6f 63 63 75 72 20 61 6e 64 20 61 70 70 6c 69 65  occur and applie
7120: 73 20 75 6e 69 66 6f 72 6d 6c 79 20 61 63 72 6f  s uniformly acro
7130: 73 73 20 61 6c 6c 20 70 6c 61 74 66 6f 72 6d 73  ss all platforms
7140: 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f  ..** The SQLITE_
7150: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20  SYNC_NORMAL and 
7160: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c  SQLITE_SYNC_FULL
7170: 20 66 6c 61 67 73 20 64 65 74 65 72 6d 69 6e 65   flags determine
7180: 20 68 6f 77 0a 2a 2a 20 65 6e 65 72 67 65 74 69   how.** energeti
7190: 63 20 6f 72 20 72 69 67 6f 72 6f 75 73 20 6f 72  c or rigorous or
71a0: 20 66 6f 72 63 65 66 75 6c 20 74 68 65 20 73 79   forceful the sy
71b0: 6e 63 20 6f 70 65 72 61 74 69 6f 6e 73 20 61 72  nc operations ar
71c0: 65 20 61 6e 64 0a 2a 2a 20 6f 6e 6c 79 20 6d 61  e and.** only ma
71d0: 6b 65 20 61 20 64 69 66 66 65 72 65 6e 63 65 20  ke a difference 
71e0: 6f 6e 20 4d 61 63 20 4f 53 58 20 66 6f 72 20 74  on Mac OSX for t
71f0: 68 65 20 64 65 66 61 75 6c 74 20 53 51 4c 69 74  he default SQLit
7200: 65 20 63 6f 64 65 2e 0a 2a 2a 20 28 54 68 69 72  e code..** (Thir
7210: 64 2d 70 61 72 74 79 20 56 46 53 20 69 6d 70 6c  d-party VFS impl
7220: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 69 67 68  ementations migh
7230: 74 20 61 6c 73 6f 20 6d 61 6b 65 20 74 68 65 20  t also make the 
7240: 64 69 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62  distinction.** b
7250: 65 74 77 65 65 6e 20 53 51 4c 49 54 45 5f 53 59  etween SQLITE_SY
7260: 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51  NC_NORMAL and SQ
7270: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20  LITE_SYNC_FULL, 
7280: 62 75 74 20 61 6d 6f 6e 67 20 74 68 65 0a 2a 2a  but among the.**
7290: 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
72a0: 6d 73 20 6e 61 74 69 76 65 6c 79 20 73 75 70 70  ms natively supp
72b0: 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74 65 2c  orted by SQLite,
72c0: 20 6f 6e 6c 79 20 4d 61 63 20 4f 53 58 0a 2a 2a   only Mac OSX.**
72d0: 20 63 61 72 65 73 20 61 62 6f 75 74 20 74 68 65   cares about the
72e0: 20 64 69 66 66 65 72 65 6e 63 65 2e 29 0a 2a 2f   difference.).*/
72f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
7300: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20  SYNC_NORMAL     
7310: 20 20 20 30 78 30 30 30 30 32 0a 23 64 65 66 69     0x00002.#defi
7320: 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46  ne SQLITE_SYNC_F
7330: 55 4c 4c 20 20 20 20 20 20 20 20 20 20 30 78 30  ULL          0x0
7340: 30 30 30 33 0a 23 64 65 66 69 6e 65 20 53 51 4c  0003.#define SQL
7350: 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c  ITE_SYNC_DATAONL
7360: 59 20 20 20 20 20 20 30 78 30 30 30 31 30 0a 0a  Y      0x00010..
7370: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
7380: 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f 70 65  OS Interface Ope
7390: 6e 20 46 69 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a  n File Handle.**
73a0: 0a 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f  .** An [sqlite3_
73b0: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65 70  file] object rep
73c0: 72 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20  resents an open 
73d0: 66 69 6c 65 20 69 6e 20 74 68 65 20 0a 2a 2a 20  file in the .** 
73e0: 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 4f  [sqlite3_vfs | O
73f0: 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65  S interface laye
7400: 72 5d 2e 20 20 49 6e 64 69 76 69 64 75 61 6c 20  r].  Individual 
7410: 4f 53 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  OS interface.** 
7420: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
7430: 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f 20  will.** want to 
7440: 73 75 62 63 6c 61 73 73 20 74 68 69 73 20 6f 62  subclass this ob
7450: 6a 65 63 74 20 62 79 20 61 70 70 65 6e 64 69 6e  ject by appendin
7460: 67 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65  g additional fie
7470: 6c 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65 69 72  lds.** for their
7480: 20 6f 77 6e 20 75 73 65 2e 20 20 54 68 65 20 70   own use.  The p
7490: 4d 65 74 68 6f 64 73 20 65 6e 74 72 79 20 69 73  Methods entry is
74a0: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
74b0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  .** [sqlite3_io_
74c0: 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20  methods] object 
74d0: 74 68 61 74 20 64 65 66 69 6e 65 73 20 6d 65 74  that defines met
74e0: 68 6f 64 73 20 66 6f 72 20 70 65 72 66 6f 72 6d  hods for perform
74f0: 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72 61  ing.** I/O opera
7500: 74 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70 65  tions on the ope
7510: 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64  n file..*/.typed
7520: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
7530: 33 5f 66 69 6c 65 20 73 71 6c 69 74 65 33 5f 66  3_file sqlite3_f
7540: 69 6c 65 3b 0a 73 74 72 75 63 74 20 73 71 6c 69  ile;.struct sqli
7550: 74 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f 6e  te3_file {.  con
7560: 73 74 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  st struct sqlite
7570: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70 4d  3_io_methods *pM
7580: 65 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74 68  ethods;  /* Meth
7590: 6f 64 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e 20  ods for an open 
75a0: 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a  file */.};../*.*
75b0: 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49  * CAPI3REF: OS I
75c0: 6e 74 65 72 66 61 63 65 20 46 69 6c 65 20 56 69  nterface File Vi
75d0: 72 74 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f 62  rtual Methods Ob
75e0: 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79  ject.**.** Every
75f0: 20 66 69 6c 65 20 6f 70 65 6e 65 64 20 62 79 20   file opened by 
7600: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  the [sqlite3_vfs
7610: 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20 70  .xOpen] method p
7620: 6f 70 75 6c 61 74 65 73 20 61 6e 0a 2a 2a 20 5b  opulates an.** [
7630: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62  sqlite3_file] ob
7640: 6a 65 63 74 20 28 6f 72 2c 20 6d 6f 72 65 20 63  ject (or, more c
7650: 6f 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 63 6c  ommonly, a subcl
7660: 61 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73  ass of the.** [s
7670: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a  qlite3_file] obj
7680: 65 63 74 29 20 77 69 74 68 20 61 20 70 6f 69 6e  ect) with a poin
7690: 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e  ter to an instan
76a0: 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63  ce of this objec
76b0: 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63  t..** This objec
76c0: 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 6d 65  t defines the me
76d0: 74 68 6f 64 73 20 75 73 65 64 20 74 6f 20 70 65  thods used to pe
76e0: 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f 70  rform various op
76f0: 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 61 69  erations.** agai
7700: 6e 73 74 20 74 68 65 20 6f 70 65 6e 20 66 69 6c  nst the open fil
7710: 65 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79  e represented by
7720: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69   the [sqlite3_fi
7730: 6c 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a  le] object..**.*
7740: 2a 20 49 66 20 74 68 65 20 5b 73 71 6c 69 74 65  * If the [sqlite
7750: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74  3_vfs.xOpen] met
7760: 68 6f 64 20 73 65 74 73 20 74 68 65 20 73 71 6c  hod sets the sql
7770: 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f  ite3_file.pMetho
7780: 64 73 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20 74  ds element .** t
7790: 6f 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69  o a non-NULL poi
77a0: 6e 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20 73  nter, then the s
77b0: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
77c0: 73 2e 78 43 6c 6f 73 65 20 6d 65 74 68 6f 64 0a  s.xClose method.
77d0: 2a 2a 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65  ** may be invoke
77e0: 64 20 65 76 65 6e 20 69 66 20 74 68 65 20 5b 73  d even if the [s
77f0: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e  qlite3_vfs.xOpen
7800: 5d 20 72 65 70 6f 72 74 65 64 20 74 68 61 74 20  ] reported that 
7810: 69 74 20 66 61 69 6c 65 64 2e 20 20 54 68 65 0a  it failed.  The.
7820: 2a 2a 20 6f 6e 6c 79 20 77 61 79 20 74 6f 20 70  ** only way to p
7830: 72 65 76 65 6e 74 20 61 20 63 61 6c 6c 20 74 6f  revent a call to
7840: 20 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f 77 69 6e   xClose followin
7850: 67 20 61 20 66 61 69 6c 65 64 20 5b 73 71 6c 69  g a failed [sqli
7860: 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 0a 2a  te3_vfs.xOpen].*
7870: 2a 20 69 73 20 66 6f 72 20 74 68 65 20 5b 73 71  * is for the [sq
7880: 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d  lite3_vfs.xOpen]
7890: 20 74 6f 20 73 65 74 20 74 68 65 20 73 71 6c 69   to set the sqli
78a0: 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64  te3_file.pMethod
78b0: 73 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 74 6f 20  s element.** to 
78c0: 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  NULL..**.** The 
78d0: 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74  flags argument t
78e0: 6f 20 78 53 79 6e 63 20 6d 61 79 20 62 65 20 6f  o xSync may be o
78f0: 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53 59  ne of [SQLITE_SY
7900: 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a  NC_NORMAL] or.**
7910: 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55   [SQLITE_SYNC_FU
7920: 4c 4c 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20  LL].  The first 
7930: 63 68 6f 69 63 65 20 69 73 20 74 68 65 20 6e 6f  choice is the no
7940: 72 6d 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a 2a  rmal fsync()..**
7950: 20 54 68 65 20 73 65 63 6f 6e 64 20 63 68 6f 69   The second choi
7960: 63 65 20 69 73 20 61 20 4d 61 63 20 4f 53 20 58  ce is a Mac OS X
7970: 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 2e   style fullsync.
7980: 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 53 59    The [SQLITE_SY
7990: 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20  NC_DATAONLY].** 
79a0: 66 6c 61 67 20 6d 61 79 20 62 65 20 4f 52 65 64  flag may be ORed
79b0: 20 69 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20   in to indicate 
79c0: 74 68 61 74 20 6f 6e 6c 79 20 74 68 65 20 64 61  that only the da
79d0: 74 61 20 6f 66 20 74 68 65 20 66 69 6c 65 0a 2a  ta of the file.*
79e0: 2a 20 61 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e  * and not its in
79f0: 6f 64 65 20 6e 65 65 64 73 20 74 6f 20 62 65 20  ode needs to be 
7a00: 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  synced..**.** Th
7a10: 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73  e integer values
7a20: 20 74 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20   to xLock() and 
7a30: 78 55 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f 6e  xUnlock() are on
7a40: 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  e of.** <ul>.** 
7a50: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
7a60: 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e  K_NONE],.** <li>
7a70: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48   [SQLITE_LOCK_SH
7a80: 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b  ARED],.** <li> [
7a90: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45  SQLITE_LOCK_RESE
7aa0: 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b  RVED],.** <li> [
7ab0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44  SQLITE_LOCK_PEND
7ac0: 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e  ING], or.** <li>
7ad0: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58   [SQLITE_LOCK_EX
7ae0: 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75  CLUSIVE]..** </u
7af0: 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 6e  l>.** xLock() in
7b00: 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b  creases the lock
7b10: 2e 20 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63 72  . xUnlock() decr
7b20: 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 0a  eases the lock..
7b30: 2a 2a 20 54 68 65 20 78 43 68 65 63 6b 52 65 73  ** The xCheckRes
7b40: 65 72 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74 68  ervedLock() meth
7b50: 6f 64 20 63 68 65 63 6b 73 20 77 68 65 74 68 65  od checks whethe
7b60: 72 20 61 6e 79 20 64 61 74 61 62 61 73 65 20 63  r any database c
7b70: 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69  onnection,.** ei
7b80: 74 68 65 72 20 69 6e 20 74 68 69 73 20 70 72 6f  ther in this pro
7b90: 63 65 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65 20  cess or in some 
7ba0: 6f 74 68 65 72 20 70 72 6f 63 65 73 73 2c 20 69  other process, i
7bb0: 73 20 68 6f 6c 64 69 6e 67 20 61 20 52 45 53 45  s holding a RESE
7bc0: 52 56 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47  RVED,.** PENDING
7bd0: 2c 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 6c  , or EXCLUSIVE l
7be0: 6f 63 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65 2e  ock on the file.
7bf0: 20 20 49 74 20 72 65 74 75 72 6e 73 20 74 72 75    It returns tru
7c00: 65 0a 2a 2a 20 69 66 20 73 75 63 68 20 61 20 6c  e.** if such a l
7c10: 6f 63 6b 20 65 78 69 73 74 73 20 61 6e 64 20 66  ock exists and f
7c20: 61 6c 73 65 20 6f 74 68 65 72 77 69 73 65 2e 0a  alse otherwise..
7c30: 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65 43  **.** The xFileC
7c40: 6f 6e 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64 20  ontrol() method 
7c50: 69 73 20 61 20 67 65 6e 65 72 69 63 20 69 6e 74  is a generic int
7c60: 65 72 66 61 63 65 20 74 68 61 74 20 61 6c 6c 6f  erface that allo
7c70: 77 73 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 53  ws custom.** VFS
7c80: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
7c90: 20 74 6f 20 64 69 72 65 63 74 6c 79 20 63 6f 6e   to directly con
7ca0: 74 72 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69 6c  trol an open fil
7cb0: 65 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b  e using the.** [
7cc0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
7cd0: 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61 63  trol()] interfac
7ce0: 65 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 22  e.  The second "
7cf0: 6f 70 22 20 61 72 67 75 6d 65 6e 74 20 69 73 20  op" argument is 
7d00: 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6f 70  an.** integer op
7d10: 63 6f 64 65 2e 20 20 54 68 65 20 74 68 69 72 64  code.  The third
7d20: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 67   argument is a g
7d30: 65 6e 65 72 69 63 20 70 6f 69 6e 74 65 72 20 69  eneric pointer i
7d40: 6e 74 65 6e 64 65 64 20 74 6f 0a 2a 2a 20 70 6f  ntended to.** po
7d50: 69 6e 74 20 74 6f 20 61 20 73 74 72 75 63 74 75  int to a structu
7d60: 72 65 20 74 68 61 74 20 6d 61 79 20 63 6f 6e 74  re that may cont
7d70: 61 69 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f 72  ain arguments or
7d80: 20 73 70 61 63 65 20 69 6e 20 77 68 69 63 68 20   space in which 
7d90: 74 6f 0a 2a 2a 20 77 72 69 74 65 20 72 65 74 75  to.** write retu
7da0: 72 6e 20 76 61 6c 75 65 73 2e 20 20 50 6f 74 65  rn values.  Pote
7db0: 6e 74 69 61 6c 20 75 73 65 73 20 66 6f 72 20 78  ntial uses for x
7dc0: 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 69  FileControl() mi
7dd0: 67 68 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74 69  ght be.** functi
7de0: 6f 6e 73 20 74 6f 20 65 6e 61 62 6c 65 20 62 6c  ons to enable bl
7df0: 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69 74  ocking locks wit
7e00: 68 20 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20 63  h timeouts, to c
7e10: 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f 63  hange the.** loc
7e20: 6b 69 6e 67 20 73 74 72 61 74 65 67 79 20 28 66  king strategy (f
7e30: 6f 72 20 65 78 61 6d 70 6c 65 20 74 6f 20 75 73  or example to us
7e40: 65 20 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 73  e dot-file locks
7e50: 29 2c 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a 2a  ), to inquire.**
7e60: 20 61 62 6f 75 74 20 74 68 65 20 73 74 61 74 75   about the statu
7e70: 73 20 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 20  s of a lock, or 
7e80: 74 6f 20 62 72 65 61 6b 20 73 74 61 6c 65 20 6c  to break stale l
7e90: 6f 63 6b 73 2e 20 20 54 68 65 20 53 51 4c 69 74  ocks.  The SQLit
7ea0: 65 0a 2a 2a 20 63 6f 72 65 20 72 65 73 65 72 76  e.** core reserv
7eb0: 65 73 20 61 6c 6c 20 6f 70 63 6f 64 65 73 20 6c  es all opcodes l
7ec0: 65 73 73 20 74 68 61 6e 20 31 30 30 20 66 6f 72  ess than 100 for
7ed0: 20 69 74 73 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a   its own use..**
7ee0: 20 41 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c   A [SQLITE_FCNTL
7ef0: 5f 4c 4f 43 4b 53 54 41 54 45 20 7c 20 6c 69 73  _LOCKSTATE | lis
7f00: 74 20 6f 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65  t of opcodes] le
7f10: 73 73 20 74 68 61 6e 20 31 30 30 20 69 73 20 61  ss than 100 is a
7f20: 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 70  vailable..** App
7f30: 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 64  lications that d
7f40: 65 66 69 6e 65 20 61 20 63 75 73 74 6f 6d 20 78  efine a custom x
7f50: 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68  FileControl meth
7f60: 6f 64 20 73 68 6f 75 6c 64 20 75 73 65 20 6f 70  od should use op
7f70: 63 6f 64 65 73 0a 2a 2a 20 67 72 65 61 74 65 72  codes.** greater
7f80: 20 74 68 61 6e 20 31 30 30 20 74 6f 20 61 76 6f   than 100 to avo
7f90: 69 64 20 63 6f 6e 66 6c 69 63 74 73 2e 20 20 56  id conflicts.  V
7fa0: 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  FS implementatio
7fb0: 6e 73 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74  ns should.** ret
7fc0: 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46  urn [SQLITE_NOTF
7fd0: 4f 55 4e 44 5d 20 66 6f 72 20 66 69 6c 65 20 63  OUND] for file c
7fe0: 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20 74  ontrol opcodes t
7ff0: 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a  hat they do not.
8000: 2a 2a 20 72 65 63 6f 67 6e 69 7a 65 2e 0a 2a 2a  ** recognize..**
8010: 0a 2a 2a 20 54 68 65 20 78 53 65 63 74 6f 72 53  .** The xSectorS
8020: 69 7a 65 28 29 20 6d 65 74 68 6f 64 20 72 65 74  ize() method ret
8030: 75 72 6e 73 20 74 68 65 20 73 65 63 74 6f 72 20  urns the sector 
8040: 73 69 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20 64  size of the.** d
8050: 65 76 69 63 65 20 74 68 61 74 20 75 6e 64 65 72  evice that under
8060: 6c 69 65 73 20 74 68 65 20 66 69 6c 65 2e 20 20  lies the file.  
8070: 54 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20  The sector size 
8080: 69 73 20 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75  is the.** minimu
8090: 6d 20 77 72 69 74 65 20 74 68 61 74 20 63 61 6e  m write that can
80a0: 20 62 65 20 70 65 72 66 6f 72 6d 65 64 20 77 69   be performed wi
80b0: 74 68 6f 75 74 20 64 69 73 74 75 72 62 69 6e 67  thout disturbing
80c0: 0a 2a 2a 20 6f 74 68 65 72 20 62 79 74 65 73 20  .** other bytes 
80d0: 69 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68  in the file.  Th
80e0: 65 20 78 44 65 76 69 63 65 43 68 61 72 61 63 74  e xDeviceCharact
80f0: 65 72 69 73 74 69 63 73 28 29 0a 2a 2a 20 6d 65  eristics().** me
8100: 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 62  thod returns a b
8110: 69 74 20 76 65 63 74 6f 72 20 64 65 73 63 72 69  it vector descri
8120: 62 69 6e 67 20 62 65 68 61 76 69 6f 72 73 20 6f  bing behaviors o
8130: 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79  f the.** underly
8140: 69 6e 67 20 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a  ing device:.**.*
8150: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b  * <ul>.** <li> [
8160: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
8170: 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  MIC].** <li> [SQ
8180: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
8190: 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  C512].** <li> [S
81a0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
81b0: 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  IC1K].** <li> [S
81c0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
81d0: 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  IC2K].** <li> [S
81e0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
81f0: 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  IC4K].** <li> [S
8200: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
8210: 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  IC8K].** <li> [S
8220: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
8230: 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  IC16K].** <li> [
8240: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
8250: 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  MIC32K].** <li> 
8260: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
8270: 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e  OMIC64K].** <li>
8280: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53   [SQLITE_IOCAP_S
8290: 41 46 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c  AFE_APPEND].** <
82a0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
82b0: 50 5f 53 45 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a  P_SEQUENTIAL].**
82c0: 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65   </ul>.**.** The
82d0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
82e0: 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65  OMIC property me
82f0: 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69  ans that all wri
8300: 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69  tes of.** any si
8310: 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  ze are atomic.  
8320: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
8330: 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65  _ATOMICnnn value
8340: 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77  s.** mean that w
8350: 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20  rites of blocks 
8360: 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74  that are nnn byt
8370: 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a  es in size and.*
8380: 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f  * are aligned to
8390: 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63   an address whic
83a0: 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  h is an integer 
83b0: 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e  multiple of.** n
83c0: 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  nn are atomic.  
83d0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
83e0: 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c  _SAFE_APPEND val
83f0: 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74  ue means.** that
8400: 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70   when data is ap
8410: 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65  pended to a file
8420: 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70  , the data is ap
8430: 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20  pended.** first 
8440: 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66  then the size of
8450: 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74   the file is ext
8460: 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65  ended, never the
8470: 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72   other.** way ar
8480: 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54  ound.  The SQLIT
8490: 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49  E_IOCAP_SEQUENTI
84a0: 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e  AL property mean
84b0: 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d  s that.** inform
84c0: 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e  ation is written
84d0: 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20   to disk in the 
84e0: 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61  same order as ca
84f0: 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65  lls.** to xWrite
8500: 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 78 52 65  ()..**.** If xRe
8510: 61 64 28 29 20 72 65 74 75 72 6e 73 20 53 51 4c  ad() returns SQL
8520: 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f  ITE_IOERR_SHORT_
8530: 52 45 41 44 20 69 74 20 6d 75 73 74 20 61 6c 73  READ it must als
8540: 6f 20 66 69 6c 6c 0a 2a 2a 20 69 6e 20 74 68 65  o fill.** in the
8550: 20 75 6e 72 65 61 64 20 70 6f 72 74 69 6f 6e 73   unread portions
8560: 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 20 77   of the buffer w
8570: 69 74 68 20 7a 65 72 6f 73 2e 20 20 41 20 56 46  ith zeros.  A VF
8580: 53 20 74 68 61 74 0a 2a 2a 20 66 61 69 6c 73 20  S that.** fails 
8590: 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f  to zero-fill sho
85a0: 72 74 20 72 65 61 64 73 20 6d 69 67 68 74 20 73  rt reads might s
85b0: 65 65 6d 20 74 6f 20 77 6f 72 6b 2e 20 20 48 6f  eem to work.  Ho
85c0: 77 65 76 65 72 2c 0a 2a 2a 20 66 61 69 6c 75 72  wever,.** failur
85d0: 65 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73  e to zero-fill s
85e0: 68 6f 72 74 20 72 65 61 64 73 20 77 69 6c 6c 20  hort reads will 
85f0: 65 76 65 6e 74 75 61 6c 6c 79 20 6c 65 61 64 20  eventually lead 
8600: 74 6f 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  to.** database c
8610: 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 74 79  orruption..*/.ty
8620: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
8630: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20  ite3_io_methods 
8640: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
8650: 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74  ds;.struct sqlit
8660: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a  e3_io_methods {.
8670: 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a    int iVersion;.
8680: 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28    int (*xClose)(
8690: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a  sqlite3_file*);.
86a0: 20 20 69 6e 74 20 28 2a 78 52 65 61 64 29 28 73    int (*xRead)(s
86b0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 76 6f  qlite3_file*, vo
86c0: 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73  id*, int iAmt, s
86d0: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66  qlite3_int64 iOf
86e0: 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 57 72  st);.  int (*xWr
86f0: 69 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ite)(sqlite3_fil
8700: 65 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  e*, const void*,
8710: 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74   int iAmt, sqlit
8720: 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b  e3_int64 iOfst);
8730: 0a 20 20 69 6e 74 20 28 2a 78 54 72 75 6e 63 61  .  int (*xTrunca
8740: 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  te)(sqlite3_file
8750: 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
8760: 20 73 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a   size);.  int (*
8770: 78 53 79 6e 63 29 28 73 71 6c 69 74 65 33 5f 66  xSync)(sqlite3_f
8780: 69 6c 65 2a 2c 20 69 6e 74 20 66 6c 61 67 73 29  ile*, int flags)
8790: 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 53  ;.  int (*xFileS
87a0: 69 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ize)(sqlite3_fil
87b0: 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  e*, sqlite3_int6
87c0: 34 20 2a 70 53 69 7a 65 29 3b 0a 20 20 69 6e 74  4 *pSize);.  int
87d0: 20 28 2a 78 4c 6f 63 6b 29 28 73 71 6c 69 74 65   (*xLock)(sqlite
87e0: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20  3_file*, int);. 
87f0: 20 69 6e 74 20 28 2a 78 55 6e 6c 6f 63 6b 29 28   int (*xUnlock)(
8800: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
8810: 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 68  nt);.  int (*xCh
8820: 65 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 29  eckReservedLock)
8830: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
8840: 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20  int *pResOut);. 
8850: 20 69 6e 74 20 28 2a 78 46 69 6c 65 43 6f 6e 74   int (*xFileCont
8860: 72 6f 6c 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  rol)(sqlite3_fil
8870: 65 2a 2c 20 69 6e 74 20 6f 70 2c 20 76 6f 69 64  e*, int op, void
8880: 20 2a 70 41 72 67 29 3b 0a 20 20 69 6e 74 20 28   *pArg);.  int (
8890: 2a 78 53 65 63 74 6f 72 53 69 7a 65 29 28 73 71  *xSectorSize)(sq
88a0: 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20  lite3_file*);.  
88b0: 69 6e 74 20 28 2a 78 44 65 76 69 63 65 43 68 61  int (*xDeviceCha
88c0: 72 61 63 74 65 72 69 73 74 69 63 73 29 28 73 71  racteristics)(sq
88d0: 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20  lite3_file*);.  
88e0: 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65  /* Methods above
88f0: 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76   are valid for v
8900: 65 72 73 69 6f 6e 20 31 20 2a 2f 0a 20 20 69 6e  ersion 1 */.  in
8910: 74 20 28 2a 78 53 68 6d 4d 61 70 29 28 73 71 6c  t (*xShmMap)(sql
8920: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20  ite3_file*, int 
8930: 69 50 67 2c 20 69 6e 74 20 70 67 73 7a 2c 20 69  iPg, int pgsz, i
8940: 6e 74 2c 20 76 6f 69 64 20 76 6f 6c 61 74 69 6c  nt, void volatil
8950: 65 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53  e**);.  int (*xS
8960: 68 6d 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f  hmLock)(sqlite3_
8970: 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 66 66 73 65  file*, int offse
8980: 74 2c 20 69 6e 74 20 6e 2c 20 69 6e 74 20 66 6c  t, int n, int fl
8990: 61 67 73 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78  ags);.  void (*x
89a0: 53 68 6d 42 61 72 72 69 65 72 29 28 73 71 6c 69  ShmBarrier)(sqli
89b0: 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e  te3_file*);.  in
89c0: 74 20 28 2a 78 53 68 6d 55 6e 6d 61 70 29 28 73  t (*xShmUnmap)(s
89d0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
89e0: 74 20 64 65 6c 65 74 65 46 6c 61 67 29 3b 0a 20  t deleteFlag);. 
89f0: 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76   /* Methods abov
8a00: 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20  e are valid for 
8a10: 76 65 72 73 69 6f 6e 20 32 20 2a 2f 0a 20 20 69  version 2 */.  i
8a20: 6e 74 20 28 2a 78 46 65 74 63 68 29 28 73 71 6c  nt (*xFetch)(sql
8a30: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69  ite3_file*, sqli
8a40: 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 2c  te3_int64 iOfst,
8a50: 20 69 6e 74 20 69 41 6d 74 2c 20 76 6f 69 64 20   int iAmt, void 
8a60: 2a 2a 70 70 29 3b 0a 20 20 69 6e 74 20 28 2a 78  **pp);.  int (*x
8a70: 55 6e 66 65 74 63 68 29 28 73 71 6c 69 74 65 33  Unfetch)(sqlite3
8a80: 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f  _file*, sqlite3_
8a90: 69 6e 74 36 34 20 69 4f 66 73 74 2c 20 76 6f 69  int64 iOfst, voi
8aa0: 64 20 2a 70 29 3b 0a 20 20 2f 2a 20 4d 65 74 68  d *p);.  /* Meth
8ab0: 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 76 61  ods above are va
8ac0: 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20  lid for version 
8ad0: 33 20 2a 2f 0a 20 20 2f 2a 20 41 64 64 69 74 69  3 */.  /* Additi
8ae0: 6f 6e 61 6c 20 6d 65 74 68 6f 64 73 20 6d 61 79  onal methods may
8af0: 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74   be added in fut
8b00: 75 72 65 20 72 65 6c 65 61 73 65 73 20 2a 2f 0a  ure releases */.
8b10: 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  };../*.** CAPI3R
8b20: 45 46 3a 20 53 74 61 6e 64 61 72 64 20 46 69 6c  EF: Standard Fil
8b30: 65 20 43 6f 6e 74 72 6f 6c 20 4f 70 63 6f 64 65  e Control Opcode
8b40: 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e  s.**.** These in
8b50: 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20  teger constants 
8b60: 61 72 65 20 6f 70 63 6f 64 65 73 20 66 6f 72 20  are opcodes for 
8b70: 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  the xFileControl
8b80: 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68   method.** of th
8b90: 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  e [sqlite3_io_me
8ba0: 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 61 6e  thods] object an
8bb0: 64 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74  d for the [sqlit
8bc0: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
8bd0: 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e  )].** interface.
8be0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  .**.** The [SQLI
8bf0: 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41  TE_FCNTL_LOCKSTA
8c00: 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73  TE] opcode is us
8c10: 65 64 20 66 6f 72 20 64 65 62 75 67 67 69 6e 67  ed for debugging
8c20: 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64  .  This.** opcod
8c30: 65 20 63 61 75 73 65 73 20 74 68 65 20 78 46 69  e causes the xFi
8c40: 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64  leControl method
8c50: 20 74 6f 20 77 72 69 74 65 20 74 68 65 20 63 75   to write the cu
8c60: 72 72 65 6e 74 20 73 74 61 74 65 20 6f 66 0a 2a  rrent state of.*
8c70: 2a 20 74 68 65 20 6c 6f 63 6b 20 28 6f 6e 65 20  * the lock (one 
8c80: 6f 66 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  of [SQLITE_LOCK_
8c90: 4e 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c  NONE], [SQLITE_L
8ca0: 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20  OCK_SHARED],.** 
8cb0: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53  [SQLITE_LOCK_RES
8cc0: 45 52 56 45 44 5d 2c 20 5b 53 51 4c 49 54 45 5f  ERVED], [SQLITE_
8cd0: 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f  LOCK_PENDING], o
8ce0: 72 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45  r [SQLITE_LOCK_E
8cf0: 58 43 4c 55 53 49 56 45 5d 29 0a 2a 2a 20 69 6e  XCLUSIVE]).** in
8d00: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 74 68  to an integer th
8d10: 61 74 20 74 68 65 20 70 41 72 67 20 61 72 67 75  at the pArg argu
8d20: 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 2e 20  ment points to. 
8d30: 54 68 69 73 20 63 61 70 61 62 69 6c 69 74 79 0a  This capability.
8d40: 2a 2a 20 69 73 20 75 73 65 64 20 64 75 72 69 6e  ** is used durin
8d50: 67 20 74 65 73 74 69 6e 67 20 61 6e 64 20 6f 6e  g testing and on
8d60: 6c 79 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73  ly needs to be s
8d70: 75 70 70 6f 72 74 65 64 20 77 68 65 6e 20 53 51  upported when SQ
8d80: 4c 49 54 45 5f 54 45 53 54 0a 2a 2a 20 69 73 20  LITE_TEST.** is 
8d90: 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 3c 75 6c 3e  defined..** <ul>
8da0: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
8db0: 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54  _FCNTL_SIZE_HINT
8dc0: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
8dd0: 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e  E_FCNTL_SIZE_HIN
8de0: 54 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65  T] opcode is use
8df0: 64 20 62 79 20 53 51 4c 69 74 65 20 74 6f 20 67  d by SQLite to g
8e00: 69 76 65 20 74 68 65 20 56 46 53 0a 2a 2a 20 6c  ive the VFS.** l
8e10: 61 79 65 72 20 61 20 68 69 6e 74 20 6f 66 20 68  ayer a hint of h
8e20: 6f 77 20 6c 61 72 67 65 20 74 68 65 20 64 61 74  ow large the dat
8e30: 61 62 61 73 65 20 66 69 6c 65 20 77 69 6c 6c 20  abase file will 
8e40: 67 72 6f 77 20 74 6f 20 62 65 20 64 75 72 69 6e  grow to be durin
8e50: 67 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74  g the.** current
8e60: 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 20 54   transaction.  T
8e70: 68 69 73 20 68 69 6e 74 20 69 73 20 6e 6f 74 20  his hint is not 
8e80: 67 75 61 72 61 6e 74 65 65 64 20 74 6f 20 62 65  guaranteed to be
8e90: 20 61 63 63 75 72 61 74 65 20 62 75 74 20 69 74   accurate but it
8ea0: 0a 2a 2a 20 69 73 20 6f 66 74 65 6e 20 63 6c 6f  .** is often clo
8eb0: 73 65 2e 20 20 54 68 65 20 75 6e 64 65 72 6c 79  se.  The underly
8ec0: 69 6e 67 20 56 46 53 20 6d 69 67 68 74 20 63 68  ing VFS might ch
8ed0: 6f 6f 73 65 20 74 6f 20 70 72 65 61 6c 6c 6f 63  oose to prealloc
8ee0: 61 74 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  ate database.** 
8ef0: 66 69 6c 65 20 73 70 61 63 65 20 62 61 73 65 64  file space based
8f00: 20 6f 6e 20 74 68 69 73 20 68 69 6e 74 20 69 6e   on this hint in
8f10: 20 6f 72 64 65 72 20 74 6f 20 68 65 6c 70 20 77   order to help w
8f20: 72 69 74 65 73 20 74 6f 20 74 68 65 20 64 61 74  rites to the dat
8f30: 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 72 75  abase.** file ru
8f40: 6e 20 66 61 73 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  n faster..**.** 
8f50: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
8f60: 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 5d 0a  TL_CHUNK_SIZE]].
8f70: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
8f80: 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d  CNTL_CHUNK_SIZE]
8f90: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20   opcode is used 
8fa0: 74 6f 20 72 65 71 75 65 73 74 20 74 68 61 74 20  to request that 
8fb0: 74 68 65 20 56 46 53 0a 2a 2a 20 65 78 74 65 6e  the VFS.** exten
8fc0: 64 73 20 61 6e 64 20 74 72 75 6e 63 61 74 65 73  ds and truncates
8fd0: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
8fe0: 6c 65 20 69 6e 20 63 68 75 6e 6b 73 20 6f 66 20  le in chunks of 
8ff0: 61 20 73 69 7a 65 20 73 70 65 63 69 66 69 65 64  a size specified
9000: 0a 2a 2a 20 62 79 20 74 68 65 20 75 73 65 72 2e  .** by the user.
9010: 20 54 68 65 20 66 6f 75 72 74 68 20 61 72 67 75   The fourth argu
9020: 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  ment to [sqlite3
9030: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d  _file_control()]
9040: 20 73 68 6f 75 6c 64 20 0a 2a 2a 20 70 6f 69 6e   should .** poin
9050: 74 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20  t to an integer 
9060: 28 74 79 70 65 20 69 6e 74 29 20 63 6f 6e 74 61  (type int) conta
9070: 69 6e 69 6e 67 20 74 68 65 20 6e 65 77 20 63 68  ining the new ch
9080: 75 6e 6b 2d 73 69 7a 65 20 74 6f 20 75 73 65 0a  unk-size to use.
9090: 2a 2a 20 66 6f 72 20 74 68 65 20 6e 6f 6d 69 6e  ** for the nomin
90a0: 61 74 65 64 20 64 61 74 61 62 61 73 65 2e 20 41  ated database. A
90b0: 6c 6c 6f 63 61 74 69 6e 67 20 64 61 74 61 62 61  llocating databa
90c0: 73 65 20 66 69 6c 65 20 73 70 61 63 65 20 69 6e  se file space in
90d0: 20 6c 61 72 67 65 0a 2a 2a 20 63 68 75 6e 6b 73   large.** chunks
90e0: 20 28 73 61 79 20 31 4d 42 20 61 74 20 61 20 74   (say 1MB at a t
90f0: 69 6d 65 29 2c 20 6d 61 79 20 72 65 64 75 63 65  ime), may reduce
9100: 20 66 69 6c 65 2d 73 79 73 74 65 6d 20 66 72 61   file-system fra
9110: 67 6d 65 6e 74 61 74 69 6f 6e 20 61 6e 64 0a 2a  gmentation and.*
9120: 2a 20 69 6d 70 72 6f 76 65 20 70 65 72 66 6f 72  * improve perfor
9130: 6d 61 6e 63 65 20 6f 6e 20 73 6f 6d 65 20 73 79  mance on some sy
9140: 73 74 65 6d 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  stems..**.** <li
9150: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
9160: 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a  FILE_POINTER]].*
9170: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
9180: 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52  NTL_FILE_POINTER
9190: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64  ] opcode is used
91a0: 20 74 6f 20 6f 62 74 61 69 6e 20 61 20 70 6f 69   to obtain a poi
91b0: 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b  nter.** to the [
91c0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62  sqlite3_file] ob
91d0: 6a 65 63 74 20 61 73 73 6f 63 69 61 74 65 64 20  ject associated 
91e0: 77 69 74 68 20 61 20 70 61 72 74 69 63 75 6c 61  with a particula
91f0: 72 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f  r database.** co
9200: 6e 6e 65 63 74 69 6f 6e 2e 20 20 53 65 65 20 74  nnection.  See t
9210: 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  he [sqlite3_file
9220: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 64 6f 63 75  _control()] docu
9230: 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a  mentation for.**
9240: 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f   additional info
9250: 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c  rmation..**.** <
9260: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
9270: 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 5d 5d  L_SYNC_OMITTED]]
9280: 0a 2a 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 69 6e  .** No longer in
9290: 20 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e   use..**.** <li>
92a0: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53  [[SQLITE_FCNTL_S
92b0: 59 4e 43 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  YNC]].** The [SQ
92c0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5d  LITE_FCNTL_SYNC]
92d0: 20 6f 70 63 6f 64 65 20 69 73 20 67 65 6e 65 72   opcode is gener
92e0: 61 74 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20  ated internally 
92f0: 62 79 20 53 51 4c 69 74 65 20 61 6e 64 0a 2a 2a  by SQLite and.**
9300: 20 73 65 6e 74 20 74 6f 20 74 68 65 20 56 46 53   sent to the VFS
9310: 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 62 65 66   immediately bef
9320: 6f 72 65 20 74 68 65 20 78 53 79 6e 63 20 6d 65  ore the xSync me
9330: 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64 20  thod is invoked 
9340: 6f 6e 20 61 0a 2a 2a 20 64 61 74 61 62 61 73 65  on a.** database
9350: 20 66 69 6c 65 20 64 65 73 63 72 69 70 74 6f 72   file descriptor
9360: 2e 20 4f 72 2c 20 69 66 20 74 68 65 20 78 53 79  . Or, if the xSy
9370: 6e 63 20 6d 65 74 68 6f 64 20 69 73 20 6e 6f 74  nc method is not
9380: 20 69 6e 76 6f 6b 65 64 20 0a 2a 2a 20 62 65 63   invoked .** bec
9390: 61 75 73 65 20 74 68 65 20 75 73 65 72 20 68 61  ause the user ha
93a0: 73 20 63 6f 6e 66 69 67 75 72 65 64 20 53 51 4c  s configured SQL
93b0: 69 74 65 20 77 69 74 68 20 0a 2a 2a 20 5b 50 52  ite with .** [PR
93c0: 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73  AGMA synchronous
93d0: 20 7c 20 50 52 41 47 4d 41 20 73 79 6e 63 68 72   | PRAGMA synchr
93e0: 6f 6e 6f 75 73 3d 4f 46 46 5d 20 69 74 20 69 73  onous=OFF] it is
93f0: 20 69 6e 76 6f 6b 65 64 20 69 6e 20 70 6c 61 63   invoked in plac
9400: 65 20 0a 2a 2a 20 6f 66 20 74 68 65 20 78 53 79  e .** of the xSy
9410: 6e 63 20 6d 65 74 68 6f 64 2e 20 49 6e 20 6d 6f  nc method. In mo
9420: 73 74 20 63 61 73 65 73 2c 20 74 68 65 20 70 6f  st cases, the po
9430: 69 6e 74 65 72 20 61 72 67 75 6d 65 6e 74 20 70  inter argument p
9440: 61 73 73 65 64 20 77 69 74 68 0a 2a 2a 20 74 68  assed with.** th
9450: 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20  is file-control 
9460: 69 73 20 4e 55 4c 4c 2e 20 48 6f 77 65 76 65 72  is NULL. However
9470: 2c 20 69 66 20 74 68 65 20 64 61 74 61 62 61 73  , if the databas
9480: 65 20 66 69 6c 65 20 69 73 20 62 65 69 6e 67 20  e file is being 
9490: 73 79 6e 63 65 64 0a 2a 2a 20 61 73 20 70 61 72  synced.** as par
94a0: 74 20 6f 66 20 61 20 6d 75 6c 74 69 2d 64 61 74  t of a multi-dat
94b0: 61 62 61 73 65 20 63 6f 6d 6d 69 74 2c 20 74 68  abase commit, th
94c0: 65 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74  e argument point
94d0: 73 20 74 6f 20 61 20 6e 75 6c 2d 74 65 72 6d 69  s to a nul-termi
94e0: 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20  nated.** string 
94f0: 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 74  containing the t
9500: 72 61 6e 73 61 63 74 69 6f 6e 73 20 6d 61 73 74  ransactions mast
9510: 65 72 2d 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20  er-journal file 
9520: 6e 61 6d 65 2e 20 56 46 53 65 73 20 74 68 61 74  name. VFSes that
9530: 20 0a 2a 2a 20 64 6f 20 6e 6f 74 20 6e 65 65 64   .** do not need
9540: 20 74 68 69 73 20 73 69 67 6e 61 6c 20 73 68 6f   this signal sho
9550: 75 6c 64 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e  uld silently ign
9560: 6f 72 65 20 74 68 69 73 20 6f 70 63 6f 64 65 2e  ore this opcode.
9570: 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 0a 2a   Applications .*
9580: 2a 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c  * should not cal
9590: 6c 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  l [sqlite3_file_
95a0: 63 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68 20  control()] with 
95b0: 74 68 69 73 20 6f 70 63 6f 64 65 20 61 73 20 64  this opcode as d
95c0: 6f 69 6e 67 20 73 6f 20 6d 61 79 20 0a 2a 2a 20  oing so may .** 
95d0: 64 69 73 72 75 70 74 20 74 68 65 20 6f 70 65 72  disrupt the oper
95e0: 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 70 65  ation of the spe
95f0: 63 69 61 6c 69 7a 65 64 20 56 46 53 65 73 20 74  cialized VFSes t
9600: 68 61 74 20 64 6f 20 72 65 71 75 69 72 65 20 69  hat do require i
9610: 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  t.  .**.** <li>[
9620: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f  [SQLITE_FCNTL_CO
9630: 4d 4d 49 54 5f 50 48 41 53 45 54 57 4f 5d 5d 0a  MMIT_PHASETWO]].
9640: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
9650: 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53  CNTL_COMMIT_PHAS
9660: 45 54 57 4f 5d 20 6f 70 63 6f 64 65 20 69 73 20  ETWO] opcode is 
9670: 67 65 6e 65 72 61 74 65 64 20 69 6e 74 65 72 6e  generated intern
9680: 61 6c 6c 79 20 62 79 20 53 51 4c 69 74 65 0a 2a  ally by SQLite.*
9690: 2a 20 61 6e 64 20 73 65 6e 74 20 74 6f 20 74 68  * and sent to th
96a0: 65 20 56 46 53 20 61 66 74 65 72 20 61 20 74 72  e VFS after a tr
96b0: 61 6e 73 61 63 74 69 6f 6e 20 68 61 73 20 62 65  ansaction has be
96c0: 65 6e 20 63 6f 6d 6d 69 74 74 65 64 20 69 6d 6d  en committed imm
96d0: 65 64 69 61 74 65 6c 79 0a 2a 2a 20 62 75 74 20  ediately.** but 
96e0: 62 65 66 6f 72 65 20 74 68 65 20 64 61 74 61 62  before the datab
96f0: 61 73 65 20 69 73 20 75 6e 6c 6f 63 6b 65 64 2e  ase is unlocked.
9700: 20 56 46 53 65 73 20 74 68 61 74 20 64 6f 20 6e   VFSes that do n
9710: 6f 74 20 6e 65 65 64 20 74 68 69 73 20 73 69 67  ot need this sig
9720: 6e 61 6c 0a 2a 2a 20 73 68 6f 75 6c 64 20 73 69  nal.** should si
9730: 6c 65 6e 74 6c 79 20 69 67 6e 6f 72 65 20 74 68  lently ignore th
9740: 69 73 20 6f 70 63 6f 64 65 2e 20 41 70 70 6c 69  is opcode. Appli
9750: 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 6e  cations should n
9760: 6f 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69  ot call.** [sqli
9770: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
9780: 28 29 5d 20 77 69 74 68 20 74 68 69 73 20 6f 70  ()] with this op
9790: 63 6f 64 65 20 61 73 20 64 6f 69 6e 67 20 73 6f  code as doing so
97a0: 20 6d 61 79 20 64 69 73 72 75 70 74 20 74 68 65   may disrupt the
97b0: 20 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 20 6f   .** operation o
97c0: 66 20 74 68 65 20 73 70 65 63 69 61 6c 69 7a 65  f the specialize
97d0: 64 20 56 46 53 65 73 20 74 68 61 74 20 64 6f 20  d VFSes that do 
97e0: 72 65 71 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a  require it.  .**
97f0: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
9800: 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f  _FCNTL_WIN32_AV_
9810: 52 45 54 52 59 5d 5d 0a 2a 2a 20 5e 54 68 65 20  RETRY]].** ^The 
9820: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49  [SQLITE_FCNTL_WI
9830: 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d 20 6f 70  N32_AV_RETRY] op
9840: 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20  code is used to 
9850: 63 6f 6e 66 69 67 75 72 65 20 61 75 74 6f 6d 61  configure automa
9860: 74 69 63 0a 2a 2a 20 72 65 74 72 79 20 63 6f 75  tic.** retry cou
9870: 6e 74 73 20 61 6e 64 20 69 6e 74 65 72 76 61 6c  nts and interval
9880: 73 20 66 6f 72 20 63 65 72 74 61 69 6e 20 64 69  s for certain di
9890: 73 6b 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e  sk I/O operation
98a0: 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20 77 69 6e  s for the.** win
98b0: 64 6f 77 73 20 5b 56 46 53 5d 20 69 6e 20 6f 72  dows [VFS] in or
98c0: 64 65 72 20 74 6f 20 70 72 6f 76 69 64 65 20 72  der to provide r
98d0: 6f 62 75 73 74 6e 65 73 73 20 69 6e 20 74 68 65  obustness in the
98e0: 20 70 72 65 73 65 6e 63 65 20 6f 66 0a 2a 2a 20   presence of.** 
98f0: 61 6e 74 69 2d 76 69 72 75 73 20 70 72 6f 67 72  anti-virus progr
9900: 61 6d 73 2e 20 20 42 79 20 64 65 66 61 75 6c 74  ams.  By default
9910: 2c 20 74 68 65 20 77 69 6e 64 6f 77 73 20 56 46  , the windows VF
9920: 53 20 77 69 6c 6c 20 72 65 74 72 79 20 66 69 6c  S will retry fil
9930: 65 20 72 65 61 64 2c 0a 2a 2a 20 66 69 6c 65 20  e read,.** file 
9940: 77 72 69 74 65 2c 20 61 6e 64 20 66 69 6c 65 20  write, and file 
9950: 64 65 6c 65 74 65 20 6f 70 65 72 61 74 69 6f 6e  delete operation
9960: 73 20 75 70 20 74 6f 20 31 30 20 74 69 6d 65 73  s up to 10 times
9970: 2c 20 77 69 74 68 20 61 20 64 65 6c 61 79 0a 2a  , with a delay.*
9980: 2a 20 6f 66 20 32 35 20 6d 69 6c 6c 69 73 65 63  * of 25 millisec
9990: 6f 6e 64 73 20 62 65 66 6f 72 65 20 74 68 65 20  onds before the 
99a0: 66 69 72 73 74 20 72 65 74 72 79 20 61 6e 64 20  first retry and 
99b0: 77 69 74 68 20 74 68 65 20 64 65 6c 61 79 20 69  with the delay i
99c0: 6e 63 72 65 61 73 69 6e 67 0a 2a 2a 20 62 79 20  ncreasing.** by 
99d0: 61 6e 20 61 64 64 69 74 69 6f 6e 61 6c 20 32 35  an additional 25
99e0: 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 77 69   milliseconds wi
99f0: 74 68 20 65 61 63 68 20 73 75 62 73 65 71 75 65  th each subseque
9a00: 6e 74 20 72 65 74 72 79 2e 20 20 54 68 69 73 0a  nt retry.  This.
9a10: 2a 2a 20 6f 70 63 6f 64 65 20 61 6c 6c 6f 77 73  ** opcode allows
9a20: 20 74 68 65 73 65 20 74 77 6f 20 76 61 6c 75 65   these two value
9a30: 73 20 28 31 30 20 72 65 74 72 69 65 73 20 61 6e  s (10 retries an
9a40: 64 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  d 25 millisecond
9a50: 73 20 6f 66 20 64 65 6c 61 79 29 0a 2a 2a 20 74  s of delay).** t
9a60: 6f 20 62 65 20 61 64 6a 75 73 74 65 64 2e 20 20  o be adjusted.  
9a70: 54 68 65 20 76 61 6c 75 65 73 20 61 72 65 20 63  The values are c
9a80: 68 61 6e 67 65 64 20 66 6f 72 20 61 6c 6c 20 64  hanged for all d
9a90: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
9aa0: 6f 6e 73 0a 2a 2a 20 77 69 74 68 69 6e 20 74 68  ons.** within th
9ab0: 65 20 73 61 6d 65 20 70 72 6f 63 65 73 73 2e 20  e same process. 
9ac0: 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73   The argument is
9ad0: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
9ae0: 20 61 72 72 61 79 20 6f 66 20 74 77 6f 0a 2a 2a   array of two.**
9af0: 20 69 6e 74 65 67 65 72 73 20 77 68 65 72 65 20   integers where 
9b00: 74 68 65 20 66 69 72 73 74 20 69 6e 74 65 67 65  the first intege
9b10: 72 20 69 20 74 68 65 20 6e 65 77 20 72 65 74 72  r i the new retr
9b20: 79 20 63 6f 75 6e 74 20 61 6e 64 20 74 68 65 20  y count and the 
9b30: 73 65 63 6f 6e 64 0a 2a 2a 20 69 6e 74 65 67 65  second.** intege
9b40: 72 20 69 73 20 74 68 65 20 64 65 6c 61 79 2e 20  r is the delay. 
9b50: 20 49 66 20 65 69 74 68 65 72 20 69 6e 74 65 67   If either integ
9b60: 65 72 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20  er is negative, 
9b70: 74 68 65 6e 20 74 68 65 20 73 65 74 74 69 6e 67  then the setting
9b80: 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67  .** is not chang
9b90: 65 64 20 62 75 74 20 69 6e 73 74 65 61 64 20 74  ed but instead t
9ba0: 68 65 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f  he prior value o
9bb0: 66 20 74 68 61 74 20 73 65 74 74 69 6e 67 20 69  f that setting i
9bc0: 73 20 77 72 69 74 74 65 6e 0a 2a 2a 20 69 6e 74  s written.** int
9bd0: 6f 20 74 68 65 20 61 72 72 61 79 20 65 6e 74 72  o the array entr
9be0: 79 2c 20 61 6c 6c 6f 77 69 6e 67 20 74 68 65 20  y, allowing the 
9bf0: 63 75 72 72 65 6e 74 20 72 65 74 72 79 20 73 65  current retry se
9c00: 74 74 69 6e 67 73 20 74 6f 20 62 65 0a 2a 2a 20  ttings to be.** 
9c10: 69 6e 74 65 72 72 6f 67 61 74 65 64 2e 20 20 54  interrogated.  T
9c20: 68 65 20 7a 44 62 4e 61 6d 65 20 70 61 72 61 6d  he zDbName param
9c30: 65 74 65 72 20 69 73 20 69 67 6e 6f 72 65 64 2e  eter is ignored.
9c40: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
9c50: 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53  ITE_FCNTL_PERSIS
9c60: 54 5f 57 41 4c 5d 5d 0a 2a 2a 20 5e 54 68 65 20  T_WAL]].** ^The 
9c70: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45  [SQLITE_FCNTL_PE
9c80: 52 53 49 53 54 5f 57 41 4c 5d 20 6f 70 63 6f 64  RSIST_WAL] opcod
9c90: 65 20 69 73 20 75 73 65 64 20 74 6f 20 73 65 74  e is used to set
9ca0: 20 6f 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a   or query the.**
9cb0: 20 70 65 72 73 69 73 74 65 6e 74 20 5b 57 41 4c   persistent [WAL
9cc0: 20 7c 20 57 72 69 74 65 20 41 68 65 61 64 20 4c   | Write Ahead L
9cd0: 6f 67 5d 20 73 65 74 74 69 6e 67 2e 20 20 42 79  og] setting.  By
9ce0: 20 64 65 66 61 75 6c 74 2c 20 74 68 65 20 61 75   default, the au
9cf0: 78 69 6c 69 61 72 79 0a 2a 2a 20 77 72 69 74 65  xiliary.** write
9d00: 20 61 68 65 61 64 20 6c 6f 67 20 61 6e 64 20 73   ahead log and s
9d10: 68 61 72 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c  hared memory fil
9d20: 65 73 20 75 73 65 64 20 66 6f 72 20 74 72 61 6e  es used for tran
9d30: 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 0a  saction control.
9d40: 2a 2a 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63  ** are automatic
9d50: 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 77 68 65  ally deleted whe
9d60: 6e 20 74 68 65 20 6c 61 74 65 73 74 20 63 6f 6e  n the latest con
9d70: 6e 65 63 74 69 6f 6e 20 74 6f 20 74 68 65 20 64  nection to the d
9d80: 61 74 61 62 61 73 65 0a 2a 2a 20 63 6c 6f 73 65  atabase.** close
9d90: 73 2e 20 20 53 65 74 74 69 6e 67 20 70 65 72 73  s.  Setting pers
9da0: 69 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20  istent WAL mode 
9db0: 63 61 75 73 65 73 20 74 68 6f 73 65 20 66 69 6c  causes those fil
9dc0: 65 73 20 74 6f 20 70 65 72 73 69 73 74 20 61 66  es to persist af
9dd0: 74 65 72 0a 2a 2a 20 63 6c 6f 73 65 2e 20 20 50  ter.** close.  P
9de0: 65 72 73 69 73 74 69 6e 67 20 74 68 65 20 66 69  ersisting the fi
9df0: 6c 65 73 20 69 73 20 75 73 65 66 75 6c 20 77 68  les is useful wh
9e00: 65 6e 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73  en other process
9e10: 65 73 20 74 68 61 74 20 64 6f 20 6e 6f 74 0a 2a  es that do not.*
9e20: 2a 20 68 61 76 65 20 77 72 69 74 65 20 70 65 72  * have write per
9e30: 6d 69 73 73 69 6f 6e 20 6f 6e 20 74 68 65 20 64  mission on the d
9e40: 69 72 65 63 74 6f 72 79 20 63 6f 6e 74 61 69 6e  irectory contain
9e50: 69 6e 67 20 74 68 65 20 64 61 74 61 62 61 73 65  ing the database
9e60: 20 66 69 6c 65 20 77 61 6e 74 0a 2a 2a 20 74 6f   file want.** to
9e70: 20 72 65 61 64 20 74 68 65 20 64 61 74 61 62 61   read the databa
9e80: 73 65 20 66 69 6c 65 2c 20 61 73 20 74 68 65 20  se file, as the 
9e90: 57 41 4c 20 61 6e 64 20 73 68 61 72 65 64 20 6d  WAL and shared m
9ea0: 65 6d 6f 72 79 20 66 69 6c 65 73 20 6d 75 73 74  emory files must
9eb0: 20 65 78 69 73 74 0a 2a 2a 20 69 6e 20 6f 72 64   exist.** in ord
9ec0: 65 72 20 66 6f 72 20 74 68 65 20 64 61 74 61 62  er for the datab
9ed0: 61 73 65 20 74 6f 20 62 65 20 72 65 61 64 61 62  ase to be readab
9ee0: 6c 65 2e 20 20 54 68 65 20 66 6f 75 72 74 68 20  le.  The fourth 
9ef0: 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
9f00: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
9f10: 6e 74 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69  ntrol()] for thi
9f20: 73 20 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64 20  s opcode should 
9f30: 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  be a pointer to 
9f40: 61 6e 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54  an integer..** T
9f50: 68 61 74 20 69 6e 74 65 67 65 72 20 69 73 20 30  hat integer is 0
9f60: 20 74 6f 20 64 69 73 61 62 6c 65 20 70 65 72 73   to disable pers
9f70: 69 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20  istent WAL mode 
9f80: 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c 65 20 70  or 1 to enable p
9f90: 65 72 73 69 73 74 65 6e 74 0a 2a 2a 20 57 41 4c  ersistent.** WAL
9fa0: 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69   mode.  If the i
9fb0: 6e 74 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68  nteger is -1, th
9fc0: 65 6e 20 69 74 20 69 73 20 6f 76 65 72 77 72 69  en it is overwri
9fd0: 74 74 65 6e 20 77 69 74 68 20 74 68 65 20 63 75  tten with the cu
9fe0: 72 72 65 6e 74 0a 2a 2a 20 57 41 4c 20 70 65 72  rrent.** WAL per
9ff0: 73 69 73 74 65 6e 63 65 20 73 65 74 74 69 6e 67  sistence setting
a000: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
a010: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52  LITE_FCNTL_POWER
a020: 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 5d  SAFE_OVERWRITE]]
a030: 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
a040: 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45  _FCNTL_POWERSAFE
a050: 5f 4f 56 45 52 57 52 49 54 45 5d 20 6f 70 63 6f  _OVERWRITE] opco
a060: 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 73 65  de is used to se
a070: 74 20 6f 72 20 71 75 65 72 79 20 74 68 65 0a 2a  t or query the.*
a080: 2a 20 70 65 72 73 69 73 74 65 6e 74 20 22 70 6f  * persistent "po
a090: 77 65 72 73 61 66 65 2d 6f 76 65 72 77 72 69 74  wersafe-overwrit
a0a0: 65 22 20 6f 72 20 22 50 53 4f 57 22 20 73 65 74  e" or "PSOW" set
a0b0: 74 69 6e 67 2e 20 20 54 68 65 20 50 53 4f 57 20  ting.  The PSOW 
a0c0: 73 65 74 74 69 6e 67 0a 2a 2a 20 64 65 74 65 72  setting.** deter
a0d0: 6d 69 6e 65 73 20 74 68 65 20 5b 53 51 4c 49 54  mines the [SQLIT
a0e0: 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46  E_IOCAP_POWERSAF
a0f0: 45 5f 4f 56 45 52 57 52 49 54 45 5d 20 62 69 74  E_OVERWRITE] bit
a100: 20 6f 66 20 74 68 65 0a 2a 2a 20 78 44 65 76 69   of the.** xDevi
a110: 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63  ceCharacteristic
a120: 73 20 6d 65 74 68 6f 64 73 2e 20 54 68 65 20 66  s methods. The f
a130: 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
a140: 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  to.** [sqlite3_f
a150: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66  ile_control()] f
a160: 6f 72 20 74 68 69 73 20 6f 70 63 6f 64 65 20 73  or this opcode s
a170: 68 6f 75 6c 64 20 62 65 20 61 20 70 6f 69 6e 74  hould be a point
a180: 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72  er to an integer
a190: 2e 0a 2a 2a 20 54 68 61 74 20 69 6e 74 65 67 65  ..** That intege
a1a0: 72 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c  r is 0 to disabl
a1b0: 65 20 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f  e zero-damage mo
a1c0: 64 65 20 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c  de or 1 to enabl
a1d0: 65 20 7a 65 72 6f 2d 64 61 6d 61 67 65 0a 2a 2a  e zero-damage.**
a1e0: 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69   mode.  If the i
a1f0: 6e 74 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68  nteger is -1, th
a200: 65 6e 20 69 74 20 69 73 20 6f 76 65 72 77 72 69  en it is overwri
a210: 74 74 65 6e 20 77 69 74 68 20 74 68 65 20 63 75  tten with the cu
a220: 72 72 65 6e 74 0a 2a 2a 20 7a 65 72 6f 2d 64 61  rrent.** zero-da
a230: 6d 61 67 65 20 6d 6f 64 65 20 73 65 74 74 69 6e  mage mode settin
a240: 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  g..**.** <li>[[S
a250: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52  QLITE_FCNTL_OVER
a260: 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20  WRITE]].** ^The 
a270: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56  [SQLITE_FCNTL_OV
a280: 45 52 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 20  ERWRITE] opcode 
a290: 69 73 20 69 6e 76 6f 6b 65 64 20 62 79 20 53 51  is invoked by SQ
a2a0: 4c 69 74 65 20 61 66 74 65 72 20 6f 70 65 6e 69  Lite after openi
a2b0: 6e 67 0a 2a 2a 20 61 20 77 72 69 74 65 20 74 72  ng.** a write tr
a2c0: 61 6e 73 61 63 74 69 6f 6e 20 74 6f 20 69 6e 64  ansaction to ind
a2d0: 69 63 61 74 65 20 74 68 61 74 2c 20 75 6e 6c 65  icate that, unle
a2e0: 73 73 20 69 74 20 69 73 20 72 6f 6c 6c 65 64 20  ss it is rolled 
a2f0: 62 61 63 6b 20 66 6f 72 20 73 6f 6d 65 0a 2a 2a  back for some.**
a300: 20 72 65 61 73 6f 6e 2c 20 74 68 65 20 65 6e 74   reason, the ent
a310: 69 72 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  ire database fil
a320: 65 20 77 69 6c 6c 20 62 65 20 6f 76 65 72 77 72  e will be overwr
a330: 69 74 74 65 6e 20 62 79 20 74 68 65 20 63 75 72  itten by the cur
a340: 72 65 6e 74 20 0a 2a 2a 20 74 72 61 6e 73 61 63  rent .** transac
a350: 74 69 6f 6e 2e 20 54 68 69 73 20 69 73 20 75 73  tion. This is us
a360: 65 64 20 62 79 20 56 41 43 55 55 4d 20 6f 70 65  ed by VACUUM ope
a370: 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 3c  rations..**.** <
a380: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
a390: 4c 5f 56 46 53 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e  L_VFSNAME]].** ^
a3a0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
a3b0: 4c 5f 56 46 53 4e 41 4d 45 5d 20 6f 70 63 6f 64  L_VFSNAME] opcod
a3c0: 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  e can be used to
a3d0: 20 6f 62 74 61 69 6e 20 74 68 65 20 6e 61 6d 65   obtain the name
a3e0: 73 20 6f 66 0a 2a 2a 20 61 6c 6c 20 5b 56 46 53  s of.** all [VFS
a3f0: 65 73 5d 20 69 6e 20 74 68 65 20 56 46 53 20 73  es] in the VFS s
a400: 74 61 63 6b 2e 20 20 54 68 65 20 6e 61 6d 65 73  tack.  The names
a410: 20 61 72 65 20 6f 66 20 61 6c 6c 20 56 46 53 20   are of all VFS 
a420: 73 68 69 6d 73 20 61 6e 64 20 74 68 65 0a 2a 2a  shims and the.**
a430: 20 66 69 6e 61 6c 20 62 6f 74 74 6f 6d 2d 6c 65   final bottom-le
a440: 76 65 6c 20 56 46 53 20 61 72 65 20 77 72 69 74  vel VFS are writ
a450: 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20  ten into memory 
a460: 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a  obtained from .*
a470: 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  * [sqlite3_mallo
a480: 63 28 29 5d 20 61 6e 64 20 74 68 65 20 72 65 73  c()] and the res
a490: 75 6c 74 20 69 73 20 73 74 6f 72 65 64 20 69 6e  ult is stored in
a4a0: 20 74 68 65 20 63 68 61 72 2a 20 76 61 72 69 61   the char* varia
a4b0: 62 6c 65 0a 2a 2a 20 74 68 61 74 20 74 68 65 20  ble.** that the 
a4c0: 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
a4d0: 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c   of [sqlite3_fil
a4e0: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 70 6f 69  e_control()] poi
a4f0: 6e 74 73 20 74 6f 2e 0a 2a 2a 20 54 68 65 20 63  nts to..** The c
a500: 61 6c 6c 65 72 20 69 73 20 72 65 73 70 6f 6e 73  aller is respons
a510: 69 62 6c 65 20 66 6f 72 20 66 72 65 65 69 6e 67  ible for freeing
a520: 20 74 68 65 20 6d 65 6d 6f 72 79 20 77 68 65 6e   the memory when
a530: 20 64 6f 6e 65 2e 20 20 41 73 20 77 69 74 68 0a   done.  As with.
a540: 2a 2a 20 61 6c 6c 20 66 69 6c 65 2d 63 6f 6e 74  ** all file-cont
a550: 72 6f 6c 20 61 63 74 69 6f 6e 73 2c 20 74 68 65  rol actions, the
a560: 72 65 20 69 73 20 6e 6f 20 67 75 61 72 61 6e 74  re is no guarant
a570: 65 65 20 74 68 61 74 20 74 68 69 73 20 77 69 6c  ee that this wil
a580: 6c 20 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 64 6f  l actually.** do
a590: 20 61 6e 79 74 68 69 6e 67 2e 20 20 43 61 6c 6c   anything.  Call
a5a0: 65 72 73 20 73 68 6f 75 6c 64 20 69 6e 69 74 69  ers should initi
a5b0: 61 6c 69 7a 65 20 74 68 65 20 63 68 61 72 2a 20  alize the char* 
a5c0: 76 61 72 69 61 62 6c 65 20 74 6f 20 61 20 4e 55  variable to a NU
a5d0: 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e  LL.** pointer in
a5e0: 20 63 61 73 65 20 74 68 69 73 20 66 69 6c 65 2d   case this file-
a5f0: 63 6f 6e 74 72 6f 6c 20 69 73 20 6e 6f 74 20 69  control is not i
a600: 6d 70 6c 65 6d 65 6e 74 65 64 2e 20 20 54 68 69  mplemented.  Thi
a610: 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a  s file-control.*
a620: 2a 20 69 73 20 69 6e 74 65 6e 64 65 64 20 66 6f  * is intended fo
a630: 72 20 64 69 61 67 6e 6f 73 74 69 63 20 75 73 65  r diagnostic use
a640: 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69   only..**.** <li
a650: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
a660: 50 52 41 47 4d 41 5d 5d 0a 2a 2a 20 5e 57 68 65  PRAGMA]].** ^Whe
a670: 6e 65 76 65 72 20 61 20 5b 50 52 41 47 4d 41 5d  never a [PRAGMA]
a680: 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 70 61   statement is pa
a690: 72 73 65 64 2c 20 61 6e 20 5b 53 51 4c 49 54 45  rsed, an [SQLITE
a6a0: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 0a  _FCNTL_PRAGMA] .
a6b0: 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  ** file control 
a6c0: 69 73 20 73 65 6e 74 20 74 6f 20 74 68 65 20 6f  is sent to the o
a6d0: 70 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  pen [sqlite3_fil
a6e0: 65 5d 20 6f 62 6a 65 63 74 20 63 6f 72 72 65 73  e] object corres
a6f0: 70 6f 6e 64 69 6e 67 0a 2a 2a 20 74 6f 20 74 68  ponding.** to th
a700: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
a710: 74 6f 20 77 68 69 63 68 20 74 68 65 20 70 72 61  to which the pra
a720: 67 6d 61 20 73 74 61 74 65 6d 65 6e 74 20 72 65  gma statement re
a730: 66 65 72 73 2e 20 5e 54 68 65 20 61 72 67 75 6d  fers. ^The argum
a740: 65 6e 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 53  ent.** to the [S
a750: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47  QLITE_FCNTL_PRAG
a760: 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  MA] file control
a770: 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 0a   is an array of.
a780: 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73  ** pointers to s
a790: 74 72 69 6e 67 73 20 28 63 68 61 72 2a 2a 29 20  trings (char**) 
a7a0: 69 6e 20 77 68 69 63 68 20 74 68 65 20 73 65 63  in which the sec
a7b0: 6f 6e 64 20 65 6c 65 6d 65 6e 74 20 6f 66 20 74  ond element of t
a7c0: 68 65 20 61 72 72 61 79 0a 2a 2a 20 69 73 20 74  he array.** is t
a7d0: 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 70  he name of the p
a7e0: 72 61 67 6d 61 20 61 6e 64 20 74 68 65 20 74 68  ragma and the th
a7f0: 69 72 64 20 65 6c 65 6d 65 6e 74 20 69 73 20 74  ird element is t
a800: 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  he argument to t
a810: 68 65 0a 2a 2a 20 70 72 61 67 6d 61 20 6f 72 20  he.** pragma or 
a820: 4e 55 4c 4c 20 69 66 20 74 68 65 20 70 72 61 67  NULL if the prag
a830: 6d 61 20 68 61 73 20 6e 6f 20 61 72 67 75 6d 65  ma has no argume
a840: 6e 74 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c 65  nt.  ^The handle
a850: 72 20 66 6f 72 20 61 6e 0a 2a 2a 20 5b 53 51 4c  r for an.** [SQL
a860: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41  ITE_FCNTL_PRAGMA
a870: 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 63  ] file control c
a880: 61 6e 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 6d 61  an optionally ma
a890: 6b 65 20 74 68 65 20 66 69 72 73 74 20 65 6c 65  ke the first ele
a8a0: 6d 65 6e 74 0a 2a 2a 20 6f 66 20 74 68 65 20 63  ment.** of the c
a8b0: 68 61 72 2a 2a 20 61 72 67 75 6d 65 6e 74 20 70  har** argument p
a8c0: 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 69 6e 67  oint to a string
a8d0: 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b   obtained from [
a8e0: 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28  sqlite3_mprintf(
a8f0: 29 5d 0a 2a 2a 20 6f 72 20 74 68 65 20 65 71 75  )].** or the equ
a900: 69 76 61 6c 65 6e 74 20 61 6e 64 20 74 68 61 74  ivalent and that
a910: 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 63   string will bec
a920: 6f 6d 65 20 74 68 65 20 72 65 73 75 6c 74 20 6f  ome the result o
a930: 66 20 74 68 65 20 70 72 61 67 6d 61 20 6f 72 0a  f the pragma or.
a940: 2a 2a 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73  ** the error mes
a950: 73 61 67 65 20 69 66 20 74 68 65 20 70 72 61 67  sage if the prag
a960: 6d 61 20 66 61 69 6c 73 2e 20 5e 49 66 20 74 68  ma fails. ^If th
a970: 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e  e.** [SQLITE_FCN
a980: 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20  TL_PRAGMA] file 
a990: 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 20  control returns 
a9a0: 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44  [SQLITE_NOTFOUND
a9b0: 5d 2c 20 74 68 65 6e 20 6e 6f 72 6d 61 6c 20 0a  ], then normal .
a9c0: 2a 2a 20 5b 50 52 41 47 4d 41 5d 20 70 72 6f 63  ** [PRAGMA] proc
a9d0: 65 73 73 69 6e 67 20 63 6f 6e 74 69 6e 75 65 73  essing continues
a9e0: 2e 20 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49  .  ^If the [SQLI
a9f0: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d  TE_FCNTL_PRAGMA]
aa00: 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  .** file control
aa10: 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
aa20: 5f 4f 4b 5d 2c 20 74 68 65 6e 20 74 68 65 20 70  _OK], then the p
aa30: 61 72 73 65 72 20 61 73 73 75 6d 65 73 20 74 68  arser assumes th
aa40: 61 74 20 74 68 65 0a 2a 2a 20 56 46 53 20 68 61  at the.** VFS ha
aa50: 73 20 68 61 6e 64 6c 65 64 20 74 68 65 20 50 52  s handled the PR
aa60: 41 47 4d 41 20 69 74 73 65 6c 66 20 61 6e 64 20  AGMA itself and 
aa70: 74 68 65 20 70 61 72 73 65 72 20 67 65 6e 65 72  the parser gener
aa80: 61 74 65 73 20 61 20 6e 6f 2d 6f 70 0a 2a 2a 20  ates a no-op.** 
aa90: 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
aaa0: 6e 74 2e 20 20 5e 49 66 20 74 68 65 20 5b 53 51  nt.  ^If the [SQ
aab0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d  LITE_FCNTL_PRAGM
aac0: 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  A] file control 
aad0: 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 72  returns.** any r
aae0: 65 73 75 6c 74 20 63 6f 64 65 20 6f 74 68 65 72  esult code other
aaf0: 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b   than [SQLITE_OK
ab00: 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 4f 54  ] or [SQLITE_NOT
ab10: 46 4f 55 4e 44 5d 2c 20 74 68 61 74 20 6d 65 61  FOUND], that mea
ab20: 6e 73 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 56  ns.** that the V
ab30: 46 53 20 65 6e 63 6f 75 6e 74 65 72 65 64 20 61  FS encountered a
ab40: 6e 20 65 72 72 6f 72 20 77 68 69 6c 65 20 68 61  n error while ha
ab50: 6e 64 6c 69 6e 67 20 74 68 65 20 5b 50 52 41 47  ndling the [PRAG
ab60: 4d 41 5d 20 61 6e 64 20 74 68 65 0a 2a 2a 20 63  MA] and the.** c
ab70: 6f 6d 70 69 6c 61 74 69 6f 6e 20 6f 66 20 74 68  ompilation of th
ab80: 65 20 50 52 41 47 4d 41 20 66 61 69 6c 73 20 77  e PRAGMA fails w
ab90: 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e  ith an error.  ^
aba0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
abb0: 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c  L_PRAGMA].** fil
abc0: 65 20 63 6f 6e 74 72 6f 6c 20 6f 63 63 75 72 73  e control occurs
abd0: 20 61 74 20 74 68 65 20 62 65 67 69 6e 6e 69 6e   at the beginnin
abe0: 67 20 6f 66 20 70 72 61 67 6d 61 20 73 74 61 74  g of pragma stat
abf0: 65 6d 65 6e 74 20 61 6e 61 6c 79 73 69 73 20 61  ement analysis a
ac00: 6e 64 20 73 6f 0a 2a 2a 20 69 74 20 69 73 20 61  nd so.** it is a
ac10: 62 6c 65 20 74 6f 20 6f 76 65 72 72 69 64 65 20  ble to override 
ac20: 62 75 69 6c 74 2d 69 6e 20 5b 50 52 41 47 4d 41  built-in [PRAGMA
ac30: 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  ] statements..**
ac40: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
ac50: 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c  _FCNTL_BUSYHANDL
ac60: 45 52 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  ER]].** ^The [SQ
ac70: 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48  LITE_FCNTL_BUSYH
ac80: 41 4e 44 4c 45 52 5d 0a 2a 2a 20 66 69 6c 65 2d  ANDLER].** file-
ac90: 63 6f 6e 74 72 6f 6c 20 6d 61 79 20 62 65 20 69  control may be i
aca0: 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c 69 74 65  nvoked by SQLite
acb0: 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73 65   on the database
acc0: 20 66 69 6c 65 20 68 61 6e 64 6c 65 0a 2a 2a 20   file handle.** 
acd0: 73 68 6f 72 74 6c 79 20 61 66 74 65 72 20 69 74  shortly after it
ace0: 20 69 73 20 6f 70 65 6e 65 64 20 69 6e 20 6f 72   is opened in or
acf0: 64 65 72 20 74 6f 20 70 72 6f 76 69 64 65 20 61  der to provide a
ad00: 20 63 75 73 74 6f 6d 20 56 46 53 20 77 69 74 68   custom VFS with
ad10: 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 74 68   access.** to th
ad20: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 62 75  e connections bu
ad30: 73 79 2d 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62  sy-handler callb
ad40: 61 63 6b 2e 20 54 68 65 20 61 72 67 75 6d 65 6e  ack. The argumen
ad50: 74 20 69 73 20 6f 66 20 74 79 70 65 20 28 76 6f  t is of type (vo
ad60: 69 64 20 2a 2a 29 0a 2a 2a 20 2d 20 61 6e 20 61  id **).** - an a
ad70: 72 72 61 79 20 6f 66 20 74 77 6f 20 28 76 6f 69  rray of two (voi
ad80: 64 20 2a 29 20 76 61 6c 75 65 73 2e 20 54 68 65  d *) values. The
ad90: 20 66 69 72 73 74 20 28 76 6f 69 64 20 2a 29 20   first (void *) 
ada0: 61 63 74 75 61 6c 6c 79 20 70 6f 69 6e 74 73 0a  actually points.
adb0: 2a 2a 20 74 6f 20 61 20 66 75 6e 63 74 69 6f 6e  ** to a function
adc0: 20 6f 66 20 74 79 70 65 20 28 69 6e 74 20 28 2a   of type (int (*
add0: 29 28 76 6f 69 64 20 2a 29 29 2e 20 49 6e 20 6f  )(void *)). In o
ade0: 72 64 65 72 20 74 6f 20 69 6e 76 6f 6b 65 20 74  rder to invoke t
adf0: 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a  he connections.*
ae00: 2a 20 62 75 73 79 2d 68 61 6e 64 6c 65 72 2c 20  * busy-handler, 
ae10: 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 73 68  this function sh
ae20: 6f 75 6c 64 20 62 65 20 69 6e 76 6f 6b 65 64 20  ould be invoked 
ae30: 77 69 74 68 20 74 68 65 20 73 65 63 6f 6e 64 20  with the second 
ae40: 28 76 6f 69 64 20 2a 29 20 69 6e 0a 2a 2a 20 74  (void *) in.** t
ae50: 68 65 20 61 72 72 61 79 20 61 73 20 74 68 65 20  he array as the 
ae60: 6f 6e 6c 79 20 61 72 67 75 6d 65 6e 74 2e 20 49  only argument. I
ae70: 66 20 69 74 20 72 65 74 75 72 6e 73 20 6e 6f 6e  f it returns non
ae80: 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20  -zero, then the 
ae90: 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f  operation.** sho
aea0: 75 6c 64 20 62 65 20 72 65 74 72 69 65 64 2e 20  uld be retried. 
aeb0: 49 66 20 69 74 20 72 65 74 75 72 6e 73 20 7a 65  If it returns ze
aec0: 72 6f 2c 20 74 68 65 20 63 75 73 74 6f 6d 20 56  ro, the custom V
aed0: 46 53 20 73 68 6f 75 6c 64 20 61 62 61 6e 64 6f  FS should abando
aee0: 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74  n the.** current
aef0: 20 6f 70 65 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a   operation..**.*
af00: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
af10: 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d  CNTL_TEMPFILENAM
af20: 45 5d 5d 0a 2a 2a 20 5e 41 70 70 6c 69 63 61 74  E]].** ^Applicat
af30: 69 6f 6e 20 63 61 6e 20 69 6e 76 6f 6b 65 20 74  ion can invoke t
af40: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
af50: 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45 5d 20 66  _TEMPFILENAME] f
af60: 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 74  ile-control.** t
af70: 6f 20 68 61 76 65 20 53 51 4c 69 74 65 20 67 65  o have SQLite ge
af80: 6e 65 72 61 74 65 20 61 0a 2a 2a 20 74 65 6d 70  nerate a.** temp
af90: 6f 72 61 72 79 20 66 69 6c 65 6e 61 6d 65 20 75  orary filename u
afa0: 73 69 6e 67 20 74 68 65 20 73 61 6d 65 20 61 6c  sing the same al
afb0: 67 6f 72 69 74 68 6d 20 74 68 61 74 20 69 73 20  gorithm that is 
afc0: 66 6f 6c 6c 6f 77 65 64 20 74 6f 20 67 65 6e 65  followed to gene
afd0: 72 61 74 65 0a 2a 2a 20 74 65 6d 70 6f 72 61 72  rate.** temporar
afe0: 79 20 66 69 6c 65 6e 61 6d 65 73 20 66 6f 72 20  y filenames for 
aff0: 54 45 4d 50 20 74 61 62 6c 65 73 20 61 6e 64 20  TEMP tables and 
b000: 6f 74 68 65 72 20 69 6e 74 65 72 6e 61 6c 20 75  other internal u
b010: 73 65 73 2e 20 20 54 68 65 0a 2a 2a 20 61 72 67  ses.  The.** arg
b020: 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20  ument should be 
b030: 61 20 63 68 61 72 2a 2a 20 77 68 69 63 68 20 77  a char** which w
b040: 69 6c 6c 20 62 65 20 66 69 6c 6c 65 64 20 77 69  ill be filled wi
b050: 74 68 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 0a  th the filename.
b060: 2a 2a 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20  ** written into 
b070: 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20  memory obtained 
b080: 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61  from [sqlite3_ma
b090: 6c 6c 6f 63 28 29 5d 2e 20 20 54 68 65 20 63 61  lloc()].  The ca
b0a0: 6c 6c 65 72 20 73 68 6f 75 6c 64 0a 2a 2a 20 69  ller should.** i
b0b0: 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66  nvoke [sqlite3_f
b0c0: 72 65 65 28 29 5d 20 6f 6e 20 74 68 65 20 72 65  ree()] on the re
b0d0: 73 75 6c 74 20 74 6f 20 61 76 6f 69 64 20 61 20  sult to avoid a 
b0e0: 6d 65 6d 6f 72 79 20 6c 65 61 6b 2e 0a 2a 2a 0a  memory leak..**.
b0f0: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
b100: 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d  FCNTL_MMAP_SIZE]
b110: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
b120: 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45  _FCNTL_MMAP_SIZE
b130: 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69  ] file control i
b140: 73 20 75 73 65 64 20 74 6f 20 71 75 65 72 79 20  s used to query 
b150: 6f 72 20 73 65 74 20 74 68 65 0a 2a 2a 20 6d 61  or set the.** ma
b160: 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
b170: 62 79 74 65 73 20 74 68 61 74 20 77 69 6c 6c 20  bytes that will 
b180: 62 65 20 75 73 65 64 20 66 6f 72 20 6d 65 6d 6f  be used for memo
b190: 72 79 2d 6d 61 70 70 65 64 20 49 2f 4f 2e 0a 2a  ry-mapped I/O..*
b1a0: 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69  * The argument i
b1b0: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
b1c0: 20 76 61 6c 75 65 20 6f 66 20 74 79 70 65 20 73   value of type s
b1d0: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 74 68 61  qlite3_int64 tha
b1e0: 74 0a 2a 2a 20 69 73 20 61 6e 20 61 64 76 69 73  t.** is an advis
b1f0: 6f 72 79 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  ory maximum numb
b200: 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
b210: 68 65 20 66 69 6c 65 20 74 6f 20 6d 65 6d 6f 72  he file to memor
b220: 79 20 6d 61 70 2e 20 20 54 68 65 0a 2a 2a 20 70  y map.  The.** p
b230: 6f 69 6e 74 65 72 20 69 73 20 6f 76 65 72 77 72  ointer is overwr
b240: 69 74 74 65 6e 20 77 69 74 68 20 74 68 65 20 6f  itten with the o
b250: 6c 64 20 76 61 6c 75 65 2e 20 20 54 68 65 20 6c  ld value.  The l
b260: 69 6d 69 74 20 69 73 20 6e 6f 74 20 63 68 61 6e  imit is not chan
b270: 67 65 64 20 69 66 0a 2a 2a 20 74 68 65 20 76 61  ged if.** the va
b280: 6c 75 65 20 6f 72 69 67 69 6e 61 6c 6c 79 20 70  lue originally p
b290: 6f 69 6e 74 65 64 20 74 6f 20 69 73 20 6e 65 67  ointed to is neg
b2a0: 61 74 69 76 65 2c 20 61 6e 64 20 73 6f 20 74 68  ative, and so th
b2b0: 65 20 63 75 72 72 65 6e 74 20 6c 69 6d 69 74 20  e current limit 
b2c0: 0a 2a 2a 20 63 61 6e 20 62 65 20 71 75 65 72 69  .** can be queri
b2d0: 65 64 20 62 79 20 70 61 73 73 69 6e 67 20 69 6e  ed by passing in
b2e0: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
b2f0: 6e 65 67 61 74 69 76 65 20 6e 75 6d 62 65 72 2e  negative number.
b300: 20 20 54 68 69 73 0a 2a 2a 20 66 69 6c 65 2d 63    This.** file-c
b310: 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65 64 20 69  ontrol is used i
b320: 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20 69 6d 70  nternally to imp
b330: 6c 65 6d 65 6e 74 20 5b 50 52 41 47 4d 41 20 6d  lement [PRAGMA m
b340: 6d 61 70 5f 73 69 7a 65 5d 2e 0a 2a 2a 0a 2a 2a  map_size]..**.**
b350: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
b360: 4e 54 4c 5f 54 52 41 43 45 5d 5d 0a 2a 2a 20 54  NTL_TRACE]].** T
b370: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
b380: 5f 54 52 41 43 45 5d 20 66 69 6c 65 20 63 6f 6e  _TRACE] file con
b390: 74 72 6f 6c 20 70 72 6f 76 69 64 65 73 20 61 64  trol provides ad
b3a0: 76 69 73 6f 72 79 20 69 6e 66 6f 72 6d 61 74 69  visory informati
b3b0: 6f 6e 0a 2a 2a 20 74 6f 20 74 68 65 20 56 46 53  on.** to the VFS
b3c0: 20 61 62 6f 75 74 20 77 68 61 74 20 74 68 65 20   about what the 
b3d0: 68 69 67 68 65 72 20 6c 61 79 65 72 73 20 6f 66  higher layers of
b3e0: 20 74 68 65 20 53 51 4c 69 74 65 20 73 74 61 63   the SQLite stac
b3f0: 6b 20 61 72 65 20 64 6f 69 6e 67 2e 0a 2a 2a 20  k are doing..** 
b400: 54 68 69 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f  This file contro
b410: 6c 20 69 73 20 75 73 65 64 20 62 79 20 73 6f 6d  l is used by som
b420: 65 20 56 46 53 20 61 63 74 69 76 69 74 79 20 74  e VFS activity t
b430: 72 61 63 69 6e 67 20 5b 73 68 69 6d 73 5d 2e 0a  racing [shims]..
b440: 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20  ** The argument 
b450: 69 73 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  is a zero-termin
b460: 61 74 65 64 20 73 74 72 69 6e 67 2e 20 20 48 69  ated string.  Hi
b470: 67 68 65 72 20 6c 61 79 65 72 73 20 69 6e 20 74  gher layers in t
b480: 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20 73 74 61  he.** SQLite sta
b490: 63 6b 20 6d 61 79 20 67 65 6e 65 72 61 74 65 20  ck may generate 
b4a0: 69 6e 73 74 61 6e 63 65 73 20 6f 66 20 74 68 69  instances of thi
b4b0: 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69  s file control i
b4c0: 66 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  f.** the [SQLITE
b4d0: 5f 55 53 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45  _USE_FCNTL_TRACE
b4e0: 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
b4f0: 70 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64  ption is enabled
b500: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
b510: 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d  LITE_FCNTL_HAS_M
b520: 4f 56 45 44 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53  OVED]].** The [S
b530: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f  QLITE_FCNTL_HAS_
b540: 4d 4f 56 45 44 5d 20 66 69 6c 65 20 63 6f 6e 74  MOVED] file cont
b550: 72 6f 6c 20 69 6e 74 65 72 70 72 65 74 73 20 69  rol interprets i
b560: 74 73 20 61 72 67 75 6d 65 6e 74 20 61 73 20 61  ts argument as a
b570: 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  .** pointer to a
b580: 6e 20 69 6e 74 65 67 65 72 20 61 6e 64 20 69 74  n integer and it
b590: 20 77 72 69 74 65 73 20 61 20 62 6f 6f 6c 65 61   writes a boolea
b5a0: 6e 20 69 6e 74 6f 20 74 68 61 74 20 69 6e 74 65  n into that inte
b5b0: 67 65 72 20 64 65 70 65 6e 64 69 6e 67 0a 2a 2a  ger depending.**
b5c0: 20 6f 6e 20 77 68 65 74 68 65 72 20 6f 72 20 6e   on whether or n
b5d0: 6f 74 20 74 68 65 20 66 69 6c 65 20 68 61 73 20  ot the file has 
b5e0: 62 65 65 6e 20 72 65 6e 61 6d 65 64 2c 20 6d 6f  been renamed, mo
b5f0: 76 65 64 2c 20 6f 72 20 64 65 6c 65 74 65 64 20  ved, or deleted 
b600: 73 69 6e 63 65 20 69 74 0a 2a 2a 20 77 61 73 20  since it.** was 
b610: 66 69 72 73 74 20 6f 70 65 6e 65 64 2e 0a 2a 2a  first opened..**
b620: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
b630: 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 53 45 54  _FCNTL_WIN32_SET
b640: 5f 48 41 4e 44 4c 45 5d 5d 0a 2a 2a 20 54 68 65  _HANDLE]].** The
b650: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57   [SQLITE_FCNTL_W
b660: 49 4e 33 32 5f 53 45 54 5f 48 41 4e 44 4c 45 5d  IN32_SET_HANDLE]
b670: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20   opcode is used 
b680: 66 6f 72 20 64 65 62 75 67 67 69 6e 67 2e 20 20  for debugging.  
b690: 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63  This.** opcode c
b6a0: 61 75 73 65 73 20 74 68 65 20 78 46 69 6c 65 43  auses the xFileC
b6b0: 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f  ontrol method to
b6c0: 20 73 77 61 70 20 74 68 65 20 66 69 6c 65 20 68   swap the file h
b6d0: 61 6e 64 6c 65 20 77 69 74 68 20 74 68 65 20 6f  andle with the o
b6e0: 6e 65 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f  ne.** pointed to
b6f0: 20 62 79 20 74 68 65 20 70 41 72 67 20 61 72 67   by the pArg arg
b700: 75 6d 65 6e 74 2e 20 20 54 68 69 73 20 63 61 70  ument.  This cap
b710: 61 62 69 6c 69 74 79 20 69 73 20 75 73 65 64 20  ability is used 
b720: 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67 0a 2a  during testing.*
b730: 2a 20 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64 73  * and only needs
b740: 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64   to be supported
b750: 20 77 68 65 6e 20 53 51 4c 49 54 45 5f 54 45 53   when SQLITE_TES
b760: 54 20 69 73 20 64 65 66 69 6e 65 64 2e 0a 2a 2a  T is defined..**
b770: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 23 64 65  .** </ul>.*/.#de
b780: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
b790: 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 20 20 20 20  L_LOCKSTATE     
b7a0: 20 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66            1.#def
b7b0: 69 6e 65 20 53 51 4c 49 54 45 5f 47 45 54 5f 4c  ine SQLITE_GET_L
b7c0: 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20  OCKPROXYFILE    
b7d0: 20 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69           2.#defi
b7e0: 6e 65 20 53 51 4c 49 54 45 5f 53 45 54 5f 4c 4f  ne SQLITE_SET_LO
b7f0: 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20  CKPROXYFILE     
b800: 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e          3.#defin
b810: 65 20 53 51 4c 49 54 45 5f 4c 41 53 54 5f 45 52  e SQLITE_LAST_ER
b820: 52 4e 4f 20 20 20 20 20 20 20 20 20 20 20 20 20  RNO             
b830: 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65         4.#define
b840: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49   SQLITE_FCNTL_SI
b850: 5a 45 5f 48 49 4e 54 20 20 20 20 20 20 20 20 20  ZE_HINT         
b860: 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20        5.#define 
b870: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55  SQLITE_FCNTL_CHU
b880: 4e 4b 5f 53 49 5a 45 20 20 20 20 20 20 20 20 20  NK_SIZE         
b890: 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20 53       6.#define S
b8a0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45  QLITE_FCNTL_FILE
b8b0: 5f 50 4f 49 4e 54 45 52 20 20 20 20 20 20 20 20  _POINTER        
b8c0: 20 20 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51      7.#define SQ
b8d0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f  LITE_FCNTL_SYNC_
b8e0: 4f 4d 49 54 54 45 44 20 20 20 20 20 20 20 20 20  OMITTED         
b8f0: 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c     8.#define SQL
b900: 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f  ITE_FCNTL_WIN32_
b910: 41 56 5f 52 45 54 52 59 20 20 20 20 20 20 20 20  AV_RETRY        
b920: 20 20 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    9.#define SQLI
b930: 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54  TE_FCNTL_PERSIST
b940: 5f 57 41 4c 20 20 20 20 20 20 20 20 20 20 20 20  _WAL            
b950: 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  10.#define SQLIT
b960: 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54  E_FCNTL_OVERWRIT
b970: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31  E              1
b980: 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
b990: 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 20 20  _FCNTL_VFSNAME  
b9a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 32                12
b9b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
b9c0: 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f  FCNTL_POWERSAFE_
b9d0: 4f 56 45 52 57 52 49 54 45 20 20 20 20 31 33 0a  OVERWRITE    13.
b9e0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
b9f0: 43 4e 54 4c 5f 50 52 41 47 4d 41 20 20 20 20 20  CNTL_PRAGMA     
ba00: 20 20 20 20 20 20 20 20 20 20 20 20 31 34 0a 23              14.#
ba10: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
ba20: 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52 20  NTL_BUSYHANDLER 
ba30: 20 20 20 20 20 20 20 20 20 20 20 31 35 0a 23 64             15.#d
ba40: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
ba50: 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45 20  TL_TEMPFILENAME 
ba60: 20 20 20 20 20 20 20 20 20 20 31 36 0a 23 64 65            16.#de
ba70: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
ba80: 4c 5f 4d 4d 41 50 5f 53 49 5a 45 20 20 20 20 20  L_MMAP_SIZE     
ba90: 20 20 20 20 20 20 20 20 20 31 38 0a 23 64 65 66           18.#def
baa0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
bab0: 5f 54 52 41 43 45 20 20 20 20 20 20 20 20 20 20  _TRACE          
bac0: 20 20 20 20 20 20 20 20 31 39 0a 23 64 65 66 69          19.#defi
bad0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
bae0: 48 41 53 5f 4d 4f 56 45 44 20 20 20 20 20 20 20  HAS_MOVED       
baf0: 20 20 20 20 20 20 20 32 30 0a 23 64 65 66 69 6e         20.#defin
bb00: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53  e SQLITE_FCNTL_S
bb10: 59 4e 43 20 20 20 20 20 20 20 20 20 20 20 20 20  YNC             
bb20: 20 20 20 20 20 20 32 31 0a 23 64 65 66 69 6e 65        21.#define
bb30: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f   SQLITE_FCNTL_CO
bb40: 4d 4d 49 54 5f 50 48 41 53 45 54 57 4f 20 20 20  MMIT_PHASETWO   
bb50: 20 20 20 20 20 32 32 0a 23 64 65 66 69 6e 65 20       22.#define 
bb60: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e  SQLITE_FCNTL_WIN
bb70: 33 32 5f 53 45 54 5f 48 41 4e 44 4c 45 20 20 20  32_SET_HANDLE   
bb80: 20 20 20 20 32 33 0a 0a 2f 2a 0a 2a 2a 20 43 41      23../*.** CA
bb90: 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20 48 61  PI3REF: Mutex Ha
bba0: 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d  ndle.**.** The m
bbb0: 75 74 65 78 20 6d 6f 64 75 6c 65 20 77 69 74 68  utex module with
bbc0: 69 6e 20 53 51 4c 69 74 65 20 64 65 66 69 6e 65  in SQLite define
bbd0: 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  s [sqlite3_mutex
bbe0: 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a 20 61 62  ] to be an.** ab
bbf0: 73 74 72 61 63 74 20 74 79 70 65 20 66 6f 72 20  stract type for 
bc00: 61 20 6d 75 74 65 78 20 6f 62 6a 65 63 74 2e 20  a mutex object. 
bc10: 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   The SQLite core
bc20: 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a 2a 20   never looks.** 
bc30: 61 74 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20  at the internal 
bc40: 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 6f  representation o
bc50: 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 6d 75  f an [sqlite3_mu
bc60: 74 65 78 5d 2e 20 20 49 74 20 6f 6e 6c 79 0a 2a  tex].  It only.*
bc70: 2a 20 64 65 61 6c 73 20 77 69 74 68 20 70 6f 69  * deals with poi
bc80: 6e 74 65 72 73 20 74 6f 20 74 68 65 20 5b 73 71  nters to the [sq
bc90: 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 6f 62 6a  lite3_mutex] obj
bca0: 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74 65 78  ect..**.** Mutex
bcb0: 65 73 20 61 72 65 20 63 72 65 61 74 65 64 20 75  es are created u
bcc0: 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75  sing [sqlite3_mu
bcd0: 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f  tex_alloc()]..*/
bce0: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
bcf0: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 73 71  sqlite3_mutex sq
bd00: 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a 0a 2f 2a  lite3_mutex;../*
bd10: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53  .** CAPI3REF: OS
bd20: 20 49 6e 74 65 72 66 61 63 65 20 4f 62 6a 65 63   Interface Objec
bd30: 74 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61  t.**.** An insta
bd40: 6e 63 65 20 6f 66 20 74 68 65 20 73 71 6c 69 74  nce of the sqlit
bd50: 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 64 65  e3_vfs object de
bd60: 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66  fines the interf
bd70: 61 63 65 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74  ace between.** t
bd80: 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 61  he SQLite core a
bd90: 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e  nd the underlyin
bda0: 67 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  g operating syst
bdb0: 65 6d 2e 20 20 54 68 65 20 22 76 66 73 22 0a 2a  em.  The "vfs".*
bdc0: 2a 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66  * in the name of
bdd0: 20 74 68 65 20 6f 62 6a 65 63 74 20 73 74 61 6e   the object stan
bde0: 64 73 20 66 6f 72 20 22 76 69 72 74 75 61 6c 20  ds for "virtual 
bdf0: 66 69 6c 65 20 73 79 73 74 65 6d 22 2e 20 20 53  file system".  S
be00: 65 65 0a 2a 2a 20 74 68 65 20 5b 56 46 53 20 7c  ee.** the [VFS |
be10: 20 56 46 53 20 64 6f 63 75 6d 65 6e 74 61 74 69   VFS documentati
be20: 6f 6e 5d 20 66 6f 72 20 66 75 72 74 68 65 72 20  on] for further 
be30: 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a  information..**.
be40: 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 6f 66 20  ** The value of 
be50: 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66 69 65  the iVersion fie
be60: 6c 64 20 69 73 20 69 6e 69 74 69 61 6c 6c 79 20  ld is initially 
be70: 31 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72  1 but may be lar
be80: 67 65 72 20 69 6e 0a 2a 2a 20 66 75 74 75 72 65  ger in.** future
be90: 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
bea0: 69 74 65 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c  ite.  Additional
beb0: 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61   fields may be a
bec0: 70 70 65 6e 64 65 64 20 74 6f 20 74 68 69 73 0a  ppended to this.
bed0: 2a 2a 20 6f 62 6a 65 63 74 20 77 68 65 6e 20 74  ** object when t
bee0: 68 65 20 69 56 65 72 73 69 6f 6e 20 76 61 6c 75  he iVersion valu
bef0: 65 20 69 73 20 69 6e 63 72 65 61 73 65 64 2e 20  e is increased. 
bf00: 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 73   Note that the s
bf10: 74 72 75 63 74 75 72 65 0a 2a 2a 20 6f 66 20 74  tructure.** of t
bf20: 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f  he sqlite3_vfs o
bf30: 62 6a 65 63 74 20 63 68 61 6e 67 65 73 20 69 6e  bject changes in
bf40: 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e   the transaction
bf50: 20 62 65 74 77 65 65 6e 0a 2a 2a 20 53 51 4c 69   between.** SQLi
bf60: 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 39  te version 3.5.9
bf70: 20 61 6e 64 20 33 2e 36 2e 30 20 61 6e 64 20 79   and 3.6.0 and y
bf80: 65 74 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20  et the iVersion 
bf90: 66 69 65 6c 64 20 77 61 73 20 6e 6f 74 0a 2a 2a  field was not.**
bfa0: 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a 2a 2a   modified..**.**
bfb0: 20 54 68 65 20 73 7a 4f 73 46 69 6c 65 20 66 69   The szOsFile fi
bfc0: 65 6c 64 20 69 73 20 74 68 65 20 73 69 7a 65 20  eld is the size 
bfd0: 6f 66 20 74 68 65 20 73 75 62 63 6c 61 73 73 65  of the subclasse
bfe0: 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  d [sqlite3_file]
bff0: 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 75 73  .** structure us
c000: 65 64 20 62 79 20 74 68 69 73 20 56 46 53 2e 20  ed by this VFS. 
c010: 20 6d 78 50 61 74 68 6e 61 6d 65 20 69 73 20 74   mxPathname is t
c020: 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  he maximum lengt
c030: 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74 68 6e 61  h of.** a pathna
c040: 6d 65 20 69 6e 20 74 68 69 73 20 56 46 53 2e 0a  me in this VFS..
c050: 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72 65 64  **.** Registered
c060: 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a   sqlite3_vfs obj
c070: 65 63 74 73 20 61 72 65 20 6b 65 70 74 20 6f 6e  ects are kept on
c080: 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73 74 20 66   a linked list f
c090: 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74 68 65 20  ormed by.** the 
c0a0: 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 20 20  pNext pointer.  
c0b0: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  The [sqlite3_vfs
c0c0: 5f 72 65 67 69 73 74 65 72 28 29 5d 0a 2a 2a 20  _register()].** 
c0d0: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  and [sqlite3_vfs
c0e0: 5f 75 6e 72 65 67 69 73 74 65 72 28 29 5d 20 69  _unregister()] i
c0f0: 6e 74 65 72 66 61 63 65 73 20 6d 61 6e 61 67 65  nterfaces manage
c100: 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a 20 69 6e   this list.** in
c110: 20 61 20 74 68 72 65 61 64 2d 73 61 66 65 20 77   a thread-safe w
c120: 61 79 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65  ay.  The [sqlite
c130: 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d 20 69 6e  3_vfs_find()] in
c140: 74 65 72 66 61 63 65 0a 2a 2a 20 73 65 61 72 63  terface.** searc
c150: 68 65 73 20 74 68 65 20 6c 69 73 74 2e 20 20 4e  hes the list.  N
c160: 65 69 74 68 65 72 20 74 68 65 20 61 70 70 6c 69  either the appli
c170: 63 61 74 69 6f 6e 20 63 6f 64 65 20 6e 6f 72 20  cation code nor 
c180: 74 68 65 20 56 46 53 0a 2a 2a 20 69 6d 70 6c 65  the VFS.** imple
c190: 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64  mentation should
c1a0: 20 75 73 65 20 74 68 65 20 70 4e 65 78 74 20 70   use the pNext p
c1b0: 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  ointer..**.** Th
c1c0: 65 20 70 4e 65 78 74 20 66 69 65 6c 64 20 69 73  e pNext field is
c1d0: 20 74 68 65 20 6f 6e 6c 79 20 66 69 65 6c 64 20   the only field 
c1e0: 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76  in the sqlite3_v
c1f0: 66 73 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20  fs.** structure 
c200: 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c  that SQLite will
c210: 20 65 76 65 72 20 6d 6f 64 69 66 79 2e 20 20 53   ever modify.  S
c220: 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c 79 20  QLite will only 
c230: 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20 6d 6f 64  access.** or mod
c240: 69 66 79 20 74 68 69 73 20 66 69 65 6c 64 20 77  ify this field w
c250: 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20 61 20 70  hile holding a p
c260: 61 72 74 69 63 75 6c 61 72 20 73 74 61 74 69 63  articular static
c270: 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68 65 20 61   mutex..** The a
c280: 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
c290: 64 20 6e 65 76 65 72 20 6d 6f 64 69 66 79 20 61  d never modify a
c2a0: 6e 79 74 68 69 6e 67 20 77 69 74 68 69 6e 20 74  nything within t
c2b0: 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a  he sqlite3_vfs.*
c2c0: 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65 20 74 68  * object once th
c2d0: 65 20 6f 62 6a 65 63 74 20 68 61 73 20 62 65 65  e object has bee
c2e0: 6e 20 72 65 67 69 73 74 65 72 65 64 2e 0a 2a 2a  n registered..**
c2f0: 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65 20 66 69  .** The zName fi
c300: 65 6c 64 20 68 6f 6c 64 73 20 74 68 65 20 6e 61  eld holds the na
c310: 6d 65 20 6f 66 20 74 68 65 20 56 46 53 20 6d 6f  me of the VFS mo
c320: 64 75 6c 65 2e 20 20 54 68 65 20 6e 61 6d 65 20  dule.  The name 
c330: 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e 69 71 75  must.** be uniqu
c340: 65 20 61 63 72 6f 73 73 20 61 6c 6c 20 56 46 53  e across all VFS
c350: 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20   modules..**.** 
c360: 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f  [[sqlite3_vfs.xO
c370: 70 65 6e 5d 5d 0a 2a 2a 20 5e 53 51 4c 69 74 65  pen]].** ^SQLite
c380: 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74   guarantees that
c390: 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70   the zFilename p
c3a0: 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65  arameter to xOpe
c3b0: 6e 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20 61  n.** is either a
c3c0: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72   NULL pointer or
c3d0: 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64   string obtained
c3e0: 0a 2a 2a 20 66 72 6f 6d 20 78 46 75 6c 6c 50 61  .** from xFullPa
c3f0: 74 68 6e 61 6d 65 28 29 20 77 69 74 68 20 61 6e  thname() with an
c400: 20 6f 70 74 69 6f 6e 61 6c 20 73 75 66 66 69 78   optional suffix
c410: 20 61 64 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 61   added..** ^If a
c420: 20 73 75 66 66 69 78 20 69 73 20 61 64 64 65 64   suffix is added
c430: 20 74 6f 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d   to the zFilenam
c440: 65 20 70 61 72 61 6d 65 74 65 72 2c 20 69 74 20  e parameter, it 
c450: 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 73 69 73 74 20  will.** consist 
c460: 6f 66 20 61 20 73 69 6e 67 6c 65 20 22 2d 22 20  of a single "-" 
c470: 63 68 61 72 61 63 74 65 72 20 66 6f 6c 6c 6f 77  character follow
c480: 65 64 20 62 79 20 6e 6f 20 6d 6f 72 65 20 74 68  ed by no more th
c490: 61 6e 0a 2a 2a 20 31 31 20 61 6c 70 68 61 6e 75  an.** 11 alphanu
c4a0: 6d 65 72 69 63 20 61 6e 64 2f 6f 72 20 22 2d 22  meric and/or "-"
c4b0: 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 20   characters..** 
c4c0: 5e 53 51 4c 69 74 65 20 66 75 72 74 68 65 72 20  ^SQLite further 
c4d0: 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 0a  guarantees that.
c4e0: 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 77 69  ** the string wi
c4f0: 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 6e 64 20  ll be valid and 
c500: 75 6e 63 68 61 6e 67 65 64 20 75 6e 74 69 6c 20  unchanged until 
c510: 78 43 6c 6f 73 65 28 29 20 69 73 0a 2a 2a 20 63  xClose() is.** c
c520: 61 6c 6c 65 64 2e 20 42 65 63 61 75 73 65 20 6f  alled. Because o
c530: 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 73  f the previous s
c540: 65 6e 74 65 6e 63 65 2c 0a 2a 2a 20 74 68 65 20  entence,.** the 
c550: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 63  [sqlite3_file] c
c560: 61 6e 20 73 61 66 65 6c 79 20 73 74 6f 72 65 20  an safely store 
c570: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
c580: 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 66 20  .** filename if 
c590: 69 74 20 6e 65 65 64 73 20 74 6f 20 72 65 6d 65  it needs to reme
c5a0: 6d 62 65 72 20 74 68 65 20 66 69 6c 65 6e 61 6d  mber the filenam
c5b0: 65 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f  e for some reaso
c5c0: 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 20 7a 46 69  n..** If the zFi
c5d0: 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72  lename parameter
c5e0: 20 74 6f 20 78 4f 70 65 6e 20 69 73 20 61 20 4e   to xOpen is a N
c5f0: 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e  ULL pointer then
c600: 20 78 4f 70 65 6e 0a 2a 2a 20 6d 75 73 74 20 69   xOpen.** must i
c610: 6e 76 65 6e 74 20 69 74 73 20 6f 77 6e 20 74 65  nvent its own te
c620: 6d 70 6f 72 61 72 79 20 6e 61 6d 65 20 66 6f 72  mporary name for
c630: 20 74 68 65 20 66 69 6c 65 2e 20 20 5e 57 68 65   the file.  ^Whe
c640: 6e 65 76 65 72 20 74 68 65 20 0a 2a 2a 20 78 46  never the .** xF
c650: 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65  ilename paramete
c660: 72 20 69 73 20 4e 55 4c 4c 20 69 74 20 77 69 6c  r is NULL it wil
c670: 6c 20 61 6c 73 6f 20 62 65 20 74 68 65 20 63 61  l also be the ca
c680: 73 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 66  se that the.** f
c690: 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 77  lags parameter w
c6a0: 69 6c 6c 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c  ill include [SQL
c6b0: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f  ITE_OPEN_DELETEO
c6c0: 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a 20 54  NCLOSE]..**.** T
c6d0: 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e  he flags argumen
c6e0: 74 20 74 6f 20 78 4f 70 65 6e 28 29 20 69 6e 63  t to xOpen() inc
c6f0: 6c 75 64 65 73 20 61 6c 6c 20 62 69 74 73 20 73  ludes all bits s
c700: 65 74 20 69 6e 0a 2a 2a 20 74 68 65 20 66 6c 61  et in.** the fla
c710: 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b  gs argument to [
c720: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
c730: 29 5d 2e 20 20 4f 72 20 69 66 20 5b 73 71 6c 69  )].  Or if [sqli
c740: 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 6f  te3_open()].** o
c750: 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  r [sqlite3_open1
c760: 36 28 29 5d 20 69 73 20 75 73 65 64 2c 20 74 68  6()] is used, th
c770: 65 6e 20 66 6c 61 67 73 20 69 6e 63 6c 75 64 65  en flags include
c780: 73 20 61 74 20 6c 65 61 73 74 0a 2a 2a 20 5b 53  s at least.** [S
c790: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
c7a0: 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f  RITE] | [SQLITE_
c7b0: 4f 50 45 4e 5f 43 52 45 41 54 45 5d 2e 20 0a 2a  OPEN_CREATE]. .*
c7c0: 2a 20 49 66 20 78 4f 70 65 6e 28 29 20 6f 70 65  * If xOpen() ope
c7d0: 6e 73 20 61 20 66 69 6c 65 20 72 65 61 64 2d 6f  ns a file read-o
c7e0: 6e 6c 79 20 74 68 65 6e 20 69 74 20 73 65 74 73  nly then it sets
c7f0: 20 2a 70 4f 75 74 46 6c 61 67 73 20 74 6f 0a 2a   *pOutFlags to.*
c800: 2a 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54  * include [SQLIT
c810: 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d  E_OPEN_READONLY]
c820: 2e 20 20 4f 74 68 65 72 20 62 69 74 73 20 69 6e  .  Other bits in
c830: 20 2a 70 4f 75 74 46 6c 61 67 73 20 6d 61 79 20   *pOutFlags may 
c840: 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28  be set..**.** ^(
c850: 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 73 6f  SQLite will also
c860: 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20   add one of the 
c870: 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20  following flags 
c880: 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 0a 2a  to the xOpen().*
c890: 2a 20 63 61 6c 6c 2c 20 64 65 70 65 6e 64 69 6e  * call, dependin
c8a0: 67 20 6f 6e 20 74 68 65 20 6f 62 6a 65 63 74 20  g on the object 
c8b0: 62 65 69 6e 67 20 6f 70 65 6e 65 64 3a 0a 2a 2a  being opened:.**
c8c0: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
c8d0: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d    [SQLITE_OPEN_M
c8e0: 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20  AIN_DB].** <li> 
c8f0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41   [SQLITE_OPEN_MA
c900: 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c  IN_JOURNAL].** <
c910: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
c920: 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a 2a 20 3c 6c  N_TEMP_DB].** <l
c930: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
c940: 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a  _TEMP_JOURNAL].*
c950: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
c960: 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44  OPEN_TRANSIENT_D
c970: 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  B].** <li>  [SQL
c980: 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52  ITE_OPEN_SUBJOUR
c990: 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  NAL].** <li>  [S
c9a0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45  QLITE_OPEN_MASTE
c9b0: 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c  R_JOURNAL].** <l
c9c0: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
c9d0: 5f 57 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e  _WAL].** </ul>)^
c9e0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 6c 65 20  .**.** The file 
c9f0: 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  I/O implementati
ca00: 6f 6e 20 63 61 6e 20 75 73 65 20 74 68 65 20 6f  on can use the o
ca10: 62 6a 65 63 74 20 74 79 70 65 20 66 6c 61 67 73  bject type flags
ca20: 20 74 6f 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68   to.** change th
ca30: 65 20 77 61 79 20 69 74 20 64 65 61 6c 73 20 77  e way it deals w
ca40: 69 74 68 20 66 69 6c 65 73 2e 20 20 46 6f 72 20  ith files.  For 
ca50: 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c  example, an appl
ca60: 69 63 61 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20  ication.** that 
ca70: 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 61 62  does not care ab
ca80: 6f 75 74 20 63 72 61 73 68 20 72 65 63 6f 76 65  out crash recove
ca90: 72 79 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 6d  ry or rollback m
caa0: 69 67 68 74 20 6d 61 6b 65 0a 2a 2a 20 74 68 65  ight make.** the
cab0: 20 6f 70 65 6e 20 6f 66 20 61 20 6a 6f 75 72 6e   open of a journ
cac0: 61 6c 20 66 69 6c 65 20 61 20 6e 6f 2d 6f 70 2e  al file a no-op.
cad0: 20 20 57 72 69 74 65 73 20 74 6f 20 74 68 69 73    Writes to this
cae0: 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 0a 2a   journal would.*
caf0: 2a 20 61 6c 73 6f 20 62 65 20 6e 6f 2d 6f 70 73  * also be no-ops
cb00: 2c 20 61 6e 64 20 61 6e 79 20 61 74 74 65 6d 70  , and any attemp
cb10: 74 20 74 6f 20 72 65 61 64 20 74 68 65 20 6a 6f  t to read the jo
cb20: 75 72 6e 61 6c 20 77 6f 75 6c 64 20 72 65 74 75  urnal would retu
cb30: 72 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 45  rn.** SQLITE_IOE
cb40: 52 52 2e 20 20 4f 72 20 74 68 65 20 69 6d 70 6c  RR.  Or the impl
cb50: 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 67 68 74  ementation might
cb60: 20 72 65 63 6f 67 6e 69 7a 65 20 74 68 61 74 20   recognize that 
cb70: 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69  a database.** fi
cb80: 6c 65 20 77 69 6c 6c 20 62 65 20 64 6f 69 6e 67  le will be doing
cb90: 20 70 61 67 65 2d 61 6c 69 67 6e 65 64 20 73 65   page-aligned se
cba0: 63 74 6f 72 20 72 65 61 64 73 20 61 6e 64 20 77  ctor reads and w
cbb0: 72 69 74 65 73 20 69 6e 20 61 20 72 61 6e 64 6f  rites in a rando
cbc0: 6d 0a 2a 2a 20 6f 72 64 65 72 20 61 6e 64 20 73  m.** order and s
cbd0: 65 74 20 75 70 20 69 74 73 20 49 2f 4f 20 73 75  et up its I/O su
cbe0: 62 73 79 73 74 65 6d 20 61 63 63 6f 72 64 69 6e  bsystem accordin
cbf0: 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  gly..**.** SQLit
cc00: 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 61 64 64  e might also add
cc10: 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c   one of the foll
cc20: 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74  owing flags to t
cc30: 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 3a  he xOpen method:
cc40: 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
cc50: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  li> [SQLITE_OPEN
cc60: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a  _DELETEONCLOSE].
cc70: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
cc80: 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 0a  OPEN_EXCLUSIVE].
cc90: 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54  ** </ul>.**.** T
cca0: 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
ccb0: 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 20 66  DELETEONCLOSE] f
ccc0: 6c 61 67 20 6d 65 61 6e 73 20 74 68 65 20 66 69  lag means the fi
ccd0: 6c 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20  le should be.** 
cce0: 64 65 6c 65 74 65 64 20 77 68 65 6e 20 69 74 20  deleted when it 
ccf0: 69 73 20 63 6c 6f 73 65 64 2e 20 20 5e 54 68 65  is closed.  ^The
cd00: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45   [SQLITE_OPEN_DE
cd10: 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20  LETEONCLOSE].** 
cd20: 77 69 6c 6c 20 62 65 20 73 65 74 20 66 6f 72 20  will be set for 
cd30: 54 45 4d 50 20 64 61 74 61 62 61 73 65 73 20 61  TEMP databases a
cd40: 6e 64 20 74 68 65 69 72 20 6a 6f 75 72 6e 61 6c  nd their journal
cd50: 73 2c 20 74 72 61 6e 73 69 65 6e 74 0a 2a 2a 20  s, transient.** 
cd60: 64 61 74 61 62 61 73 65 73 2c 20 61 6e 64 20 73  databases, and s
cd70: 75 62 6a 6f 75 72 6e 61 6c 73 2e 0a 2a 2a 0a 2a  ubjournals..**.*
cd80: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f  * ^The [SQLITE_O
cd90: 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 20 66  PEN_EXCLUSIVE] f
cda0: 6c 61 67 20 69 73 20 61 6c 77 61 79 73 20 75 73  lag is always us
cdb0: 65 64 20 69 6e 20 63 6f 6e 6a 75 6e 63 74 69 6f  ed in conjunctio
cdc0: 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 53  n.** with the [S
cdd0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
cde0: 45 5d 20 66 6c 61 67 2c 20 77 68 69 63 68 20 61  E] flag, which a
cdf0: 72 65 20 62 6f 74 68 20 64 69 72 65 63 74 6c 79  re both directly
ce00: 0a 2a 2a 20 61 6e 61 6c 6f 67 6f 75 73 20 74 6f  .** analogous to
ce10: 20 74 68 65 20 4f 5f 45 58 43 4c 20 61 6e 64 20   the O_EXCL and 
ce20: 4f 5f 43 52 45 41 54 20 66 6c 61 67 73 20 6f 66  O_CREAT flags of
ce30: 20 74 68 65 20 50 4f 53 49 58 20 6f 70 65 6e 28   the POSIX open(
ce40: 29 0a 2a 2a 20 41 50 49 2e 20 20 54 68 65 20 53  ).** API.  The S
ce50: 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55  QLITE_OPEN_EXCLU
ce60: 53 49 56 45 20 66 6c 61 67 2c 20 77 68 65 6e 20  SIVE flag, when 
ce70: 70 61 69 72 65 64 20 77 69 74 68 20 74 68 65 20  paired with the 
ce80: 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  .** SQLITE_OPEN_
ce90: 43 52 45 41 54 45 2c 20 69 73 20 75 73 65 64 20  CREATE, is used 
cea0: 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74  to indicate that
ceb0: 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 61 6c 77   file should alw
cec0: 61 79 73 0a 2a 2a 20 62 65 20 63 72 65 61 74 65  ays.** be create
ced0: 64 2c 20 61 6e 64 20 74 68 61 74 20 69 74 20 69  d, and that it i
cee0: 73 20 61 6e 20 65 72 72 6f 72 20 69 66 20 69 74  s an error if it
cef0: 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 73 2e   already exists.
cf00: 0a 2a 2a 20 49 74 20 69 73 20 3c 69 3e 6e 6f 74  .** It is <i>not
cf10: 3c 2f 69 3e 20 75 73 65 64 20 74 6f 20 69 6e 64  </i> used to ind
cf20: 69 63 61 74 65 20 74 68 65 20 66 69 6c 65 20 73  icate the file s
cf30: 68 6f 75 6c 64 20 62 65 20 6f 70 65 6e 65 64 20  hould be opened 
cf40: 0a 2a 2a 20 66 6f 72 20 65 78 63 6c 75 73 69 76  .** for exclusiv
cf50: 65 20 61 63 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20  e access..**.** 
cf60: 5e 41 74 20 6c 65 61 73 74 20 73 7a 4f 73 46 69  ^At least szOsFi
cf70: 6c 65 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f  le bytes of memo
cf80: 72 79 20 61 72 65 20 61 6c 6c 6f 63 61 74 65 64  ry are allocated
cf90: 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 74 6f   by SQLite.** to
cfa0: 20 68 6f 6c 64 20 74 68 65 20 20 5b 73 71 6c 69   hold the  [sqli
cfb0: 74 65 33 5f 66 69 6c 65 5d 20 73 74 72 75 63 74  te3_file] struct
cfc0: 75 72 65 20 70 61 73 73 65 64 20 61 73 20 74 68  ure passed as th
cfd0: 65 20 74 68 69 72 64 0a 2a 2a 20 61 72 67 75 6d  e third.** argum
cfe0: 65 6e 74 20 74 6f 20 78 4f 70 65 6e 2e 20 20 54  ent to xOpen.  T
cff0: 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20  he xOpen method 
d000: 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 74 6f  does not have to
d010: 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 74 68 65  .** allocate the
d020: 20 73 74 72 75 63 74 75 72 65 3b 20 69 74 20 73   structure; it s
d030: 68 6f 75 6c 64 20 6a 75 73 74 20 66 69 6c 6c 20  hould just fill 
d040: 69 74 20 69 6e 2e 20 20 4e 6f 74 65 20 74 68 61  it in.  Note tha
d050: 74 0a 2a 2a 20 74 68 65 20 78 4f 70 65 6e 20 6d  t.** the xOpen m
d060: 65 74 68 6f 64 20 6d 75 73 74 20 73 65 74 20 74  ethod must set t
d070: 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e  he sqlite3_file.
d080: 70 4d 65 74 68 6f 64 73 20 74 6f 20 65 69 74 68  pMethods to eith
d090: 65 72 0a 2a 2a 20 61 20 76 61 6c 69 64 20 5b 73  er.** a valid [s
d0a0: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
d0b0: 73 5d 20 6f 62 6a 65 63 74 20 6f 72 20 74 6f 20  s] object or to 
d0c0: 4e 55 4c 4c 2e 20 20 78 4f 70 65 6e 20 6d 75 73  NULL.  xOpen mus
d0d0: 74 20 64 6f 0a 2a 2a 20 74 68 69 73 20 65 76 65  t do.** this eve
d0e0: 6e 20 69 66 20 74 68 65 20 6f 70 65 6e 20 66 61  n if the open fa
d0f0: 69 6c 73 2e 20 20 53 51 4c 69 74 65 20 65 78 70  ils.  SQLite exp
d100: 65 63 74 73 20 74 68 61 74 20 74 68 65 20 73 71  ects that the sq
d110: 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68  lite3_file.pMeth
d120: 6f 64 73 0a 2a 2a 20 65 6c 65 6d 65 6e 74 20 77  ods.** element w
d130: 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 66 74  ill be valid aft
d140: 65 72 20 78 4f 70 65 6e 20 72 65 74 75 72 6e 73  er xOpen returns
d150: 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74   regardless of t
d160: 68 65 20 73 75 63 63 65 73 73 0a 2a 2a 20 6f 72  he success.** or
d170: 20 66 61 69 6c 75 72 65 20 6f 66 20 74 68 65 20   failure of the 
d180: 78 4f 70 65 6e 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a  xOpen call..**.*
d190: 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  * [[sqlite3_vfs.
d1a0: 78 41 63 63 65 73 73 5d 5d 0a 2a 2a 20 5e 54 68  xAccess]].** ^Th
d1b0: 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74  e flags argument
d1c0: 20 74 6f 20 78 41 63 63 65 73 73 28 29 20 6d 61   to xAccess() ma
d1d0: 79 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 43 43  y be [SQLITE_ACC
d1e0: 45 53 53 5f 45 58 49 53 54 53 5d 0a 2a 2a 20 74  ESS_EXISTS].** t
d1f0: 6f 20 74 65 73 74 20 66 6f 72 20 74 68 65 20 65  o test for the e
d200: 78 69 73 74 65 6e 63 65 20 6f 66 20 61 20 66 69  xistence of a fi
d210: 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41  le, or [SQLITE_A
d220: 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 5d  CCESS_READWRITE]
d230: 20 74 6f 0a 2a 2a 20 74 65 73 74 20 77 68 65 74   to.** test whet
d240: 68 65 72 20 61 20 66 69 6c 65 20 69 73 20 72 65  her a file is re
d250: 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61  adable and writa
d260: 62 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ble, or [SQLITE_
d270: 41 43 43 45 53 53 5f 52 45 41 44 5d 0a 2a 2a 20  ACCESS_READ].** 
d280: 74 6f 20 74 65 73 74 20 77 68 65 74 68 65 72 20  to test whether 
d290: 61 20 66 69 6c 65 20 69 73 20 61 74 20 6c 65 61  a file is at lea
d2a0: 73 74 20 72 65 61 64 61 62 6c 65 2e 20 20 20 54  st readable.   T
d2b0: 68 65 20 66 69 6c 65 20 63 61 6e 20 62 65 20 61  he file can be a
d2c0: 0a 2a 2a 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a  .** directory..*
d2d0: 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c  *.** ^SQLite wil
d2e0: 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f 63 61 74  l always allocat
d2f0: 65 20 61 74 20 6c 65 61 73 74 20 6d 78 50 61 74  e at least mxPat
d300: 68 6e 61 6d 65 2b 31 20 62 79 74 65 73 20 66 6f  hname+1 bytes fo
d310: 72 20 74 68 65 0a 2a 2a 20 6f 75 74 70 75 74 20  r the.** output 
d320: 62 75 66 66 65 72 20 78 46 75 6c 6c 50 61 74 68  buffer xFullPath
d330: 6e 61 6d 65 2e 20 20 54 68 65 20 65 78 61 63 74  name.  The exact
d340: 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6f 75 74   size of the out
d350: 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69 73  put buffer.** is
d360: 20 61 6c 73 6f 20 70 61 73 73 65 64 20 61 73 20   also passed as 
d370: 61 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62  a parameter to b
d380: 6f 74 68 20 20 6d 65 74 68 6f 64 73 2e 20 49 66  oth  methods. If
d390: 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 66 66   the output buff
d3a0: 65 72 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c 61 72  er.** is not lar
d3b0: 67 65 20 65 6e 6f 75 67 68 2c 20 5b 53 51 4c 49  ge enough, [SQLI
d3c0: 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 73 68 6f  TE_CANTOPEN] sho
d3d0: 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e  uld be returned.
d3e0: 20 53 69 6e 63 65 20 74 68 69 73 20 69 73 0a 2a   Since this is.*
d3f0: 2a 20 68 61 6e 64 6c 65 64 20 61 73 20 61 20 66  * handled as a f
d400: 61 74 61 6c 20 65 72 72 6f 72 20 62 79 20 53 51  atal error by SQ
d410: 4c 69 74 65 2c 20 76 66 73 20 69 6d 70 6c 65 6d  Lite, vfs implem
d420: 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64  entations should
d430: 20 65 6e 64 65 61 76 6f 72 0a 2a 2a 20 74 6f 20   endeavor.** to 
d440: 70 72 65 76 65 6e 74 20 74 68 69 73 20 62 79 20  prevent this by 
d450: 73 65 74 74 69 6e 67 20 6d 78 50 61 74 68 6e 61  setting mxPathna
d460: 6d 65 20 74 6f 20 61 20 73 75 66 66 69 63 69 65  me to a sufficie
d470: 6e 74 6c 79 20 6c 61 72 67 65 20 76 61 6c 75 65  ntly large value
d480: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 61 6e  ..**.** The xRan
d490: 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53 6c 65 65  domness(), xSlee
d4a0: 70 28 29 2c 20 78 43 75 72 72 65 6e 74 54 69 6d  p(), xCurrentTim
d4b0: 65 28 29 2c 20 61 6e 64 20 78 43 75 72 72 65 6e  e(), and xCurren
d4c0: 74 54 69 6d 65 49 6e 74 36 34 28 29 0a 2a 2a 20  tTimeInt64().** 
d4d0: 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 6e  interfaces are n
d4e0: 6f 74 20 73 74 72 69 63 74 6c 79 20 61 20 70 61  ot strictly a pa
d4f0: 72 74 20 6f 66 20 74 68 65 20 66 69 6c 65 73 79  rt of the filesy
d500: 73 74 65 6d 2c 20 62 75 74 20 74 68 65 79 20 61  stem, but they a
d510: 72 65 0a 2a 2a 20 69 6e 63 6c 75 64 65 64 20 69  re.** included i
d520: 6e 20 74 68 65 20 56 46 53 20 73 74 72 75 63 74  n the VFS struct
d530: 75 72 65 20 66 6f 72 20 63 6f 6d 70 6c 65 74 65  ure for complete
d540: 6e 65 73 73 2e 0a 2a 2a 20 54 68 65 20 78 52 61  ness..** The xRa
d550: 6e 64 6f 6d 6e 65 73 73 28 29 20 66 75 6e 63 74  ndomness() funct
d560: 69 6f 6e 20 61 74 74 65 6d 70 74 73 20 74 6f 20  ion attempts to 
d570: 72 65 74 75 72 6e 20 6e 42 79 74 65 73 20 62 79  return nBytes by
d580: 74 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64 2d 71  tes.** of good-q
d590: 75 61 6c 69 74 79 20 72 61 6e 64 6f 6d 6e 65 73  uality randomnes
d5a0: 73 20 69 6e 74 6f 20 7a 4f 75 74 2e 20 20 54 68  s into zOut.  Th
d5b0: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 69  e return value i
d5c0: 73 0a 2a 2a 20 74 68 65 20 61 63 74 75 61 6c 20  s.** the actual 
d5d0: 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
d5e0: 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62  of randomness ob
d5f0: 74 61 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 78  tained..** The x
d600: 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 20 63  Sleep() method c
d610: 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c 69 6e  auses the callin
d620: 67 20 74 68 72 65 61 64 20 74 6f 20 73 6c 65 65  g thread to slee
d630: 70 20 66 6f 72 20 61 74 0a 2a 2a 20 6c 65 61 73  p for at.** leas
d640: 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  t the number of 
d650: 6d 69 63 72 6f 73 65 63 6f 6e 64 73 20 67 69 76  microseconds giv
d660: 65 6e 2e 20 20 5e 54 68 65 20 78 43 75 72 72 65  en.  ^The xCurre
d670: 6e 74 54 69 6d 65 28 29 0a 2a 2a 20 6d 65 74 68  ntTime().** meth
d680: 6f 64 20 72 65 74 75 72 6e 73 20 61 20 4a 75 6c  od returns a Jul
d690: 69 61 6e 20 44 61 79 20 4e 75 6d 62 65 72 20 66  ian Day Number f
d6a0: 6f 72 20 74 68 65 20 63 75 72 72 65 6e 74 20 64  or the current d
d6b0: 61 74 65 20 61 6e 64 20 74 69 6d 65 20 61 73 0a  ate and time as.
d6c0: 2a 2a 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f  ** a floating po
d6d0: 69 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a 20 5e 54  int value..** ^T
d6e0: 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49  he xCurrentTimeI
d6f0: 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20 72 65  nt64() method re
d700: 74 75 72 6e 73 2c 20 61 73 20 61 6e 20 69 6e 74  turns, as an int
d710: 65 67 65 72 2c 20 74 68 65 20 4a 75 6c 69 61 6e  eger, the Julian
d720: 0a 2a 2a 20 44 61 79 20 4e 75 6d 62 65 72 20 6d  .** Day Number m
d730: 75 6c 74 69 70 6c 69 65 64 20 62 79 20 38 36 34  ultiplied by 864
d740: 30 30 30 30 30 20 28 74 68 65 20 6e 75 6d 62 65  00000 (the numbe
d750: 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  r of millisecond
d760: 73 20 69 6e 20 0a 2a 2a 20 61 20 32 34 2d 68 6f  s in .** a 24-ho
d770: 75 72 20 64 61 79 29 2e 20 20 0a 2a 2a 20 5e 53  ur day).  .** ^S
d780: 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 74  QLite will use t
d790: 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49  he xCurrentTimeI
d7a0: 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20 74 6f  nt64() method to
d7b0: 20 67 65 74 20 74 68 65 20 63 75 72 72 65 6e 74   get the current
d7c0: 0a 2a 2a 20 64 61 74 65 20 61 6e 64 20 74 69 6d  .** date and tim
d7d0: 65 20 69 66 20 74 68 61 74 20 6d 65 74 68 6f 64  e if that method
d7e0: 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 28 69   is available (i
d7f0: 66 20 69 56 65 72 73 69 6f 6e 20 69 73 20 32 20  f iVersion is 2 
d800: 6f 72 20 0a 2a 2a 20 67 72 65 61 74 65 72 20 61  or .** greater a
d810: 6e 64 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  nd the function 
d820: 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e  pointer is not N
d830: 55 4c 4c 29 20 61 6e 64 20 77 69 6c 6c 20 66 61  ULL) and will fa
d840: 6c 6c 20 62 61 63 6b 0a 2a 2a 20 74 6f 20 78 43  ll back.** to xC
d850: 75 72 72 65 6e 74 54 69 6d 65 28 29 20 69 66 20  urrentTime() if 
d860: 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36  xCurrentTimeInt6
d870: 34 28 29 20 69 73 20 75 6e 61 76 61 69 6c 61 62  4() is unavailab
d880: 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78  le..**.** ^The x
d890: 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 2c  SetSystemCall(),
d8a0: 20 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c 28   xGetSystemCall(
d8b0: 29 2c 20 61 6e 64 20 78 4e 65 73 74 53 79 73 74  ), and xNestSyst
d8c0: 65 6d 43 61 6c 6c 28 29 20 69 6e 74 65 72 66 61  emCall() interfa
d8d0: 63 65 73 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 75  ces.** are not u
d8e0: 73 65 64 20 62 79 20 74 68 65 20 53 51 4c 69 74  sed by the SQLit
d8f0: 65 20 63 6f 72 65 2e 20 20 54 68 65 73 65 20 6f  e core.  These o
d900: 70 74 69 6f 6e 61 6c 20 69 6e 74 65 72 66 61 63  ptional interfac
d910: 65 73 20 61 72 65 20 70 72 6f 76 69 64 65 64 0a  es are provided.
d920: 2a 2a 20 62 79 20 73 6f 6d 65 20 56 46 53 65 73  ** by some VFSes
d930: 20 74 6f 20 66 61 63 69 6c 69 74 61 74 65 20 74   to facilitate t
d940: 65 73 74 69 6e 67 20 6f 66 20 74 68 65 20 56 46  esting of the VF
d950: 53 20 63 6f 64 65 2e 20 42 79 20 6f 76 65 72 72  S code. By overr
d960: 69 64 69 6e 67 20 0a 2a 2a 20 73 79 73 74 65 6d  iding .** system
d970: 20 63 61 6c 6c 73 20 77 69 74 68 20 66 75 6e 63   calls with func
d980: 74 69 6f 6e 73 20 75 6e 64 65 72 20 69 74 73 20  tions under its 
d990: 63 6f 6e 74 72 6f 6c 2c 20 61 20 74 65 73 74 20  control, a test 
d9a0: 70 72 6f 67 72 61 6d 20 63 61 6e 0a 2a 2a 20 73  program can.** s
d9b0: 69 6d 75 6c 61 74 65 20 66 61 75 6c 74 73 20 61  imulate faults a
d9c0: 6e 64 20 65 72 72 6f 72 20 63 6f 6e 64 69 74 69  nd error conditi
d9d0: 6f 6e 73 20 74 68 61 74 20 77 6f 75 6c 64 20 6f  ons that would o
d9e0: 74 68 65 72 77 69 73 65 20 62 65 20 64 69 66 66  therwise be diff
d9f0: 69 63 75 6c 74 0a 2a 2a 20 6f 72 20 69 6d 70 6f  icult.** or impo
da00: 73 73 69 62 6c 65 20 74 6f 20 69 6e 64 75 63 65  ssible to induce
da10: 2e 20 20 54 68 65 20 73 65 74 20 6f 66 20 73 79  .  The set of sy
da20: 73 74 65 6d 20 63 61 6c 6c 73 20 74 68 61 74 20  stem calls that 
da30: 63 61 6e 20 62 65 20 6f 76 65 72 72 69 64 64 65  can be overridde
da40: 6e 0a 2a 2a 20 76 61 72 69 65 73 20 66 72 6f 6d  n.** varies from
da50: 20 6f 6e 65 20 56 46 53 20 74 6f 20 61 6e 6f 74   one VFS to anot
da60: 68 65 72 2c 20 61 6e 64 20 66 72 6f 6d 20 6f 6e  her, and from on
da70: 65 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65  e version of the
da80: 20 73 61 6d 65 20 56 46 53 20 74 6f 20 74 68 65   same VFS to the
da90: 0a 2a 2a 20 6e 65 78 74 2e 20 20 41 70 70 6c 69  .** next.  Appli
daa0: 63 61 74 69 6f 6e 73 20 74 68 61 74 20 75 73 65  cations that use
dab0: 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65   these interface
dac0: 73 20 6d 75 73 74 20 62 65 20 70 72 65 70 61 72  s must be prepar
dad0: 65 64 20 66 6f 72 20 61 6e 79 0a 2a 2a 20 6f 72  ed for any.** or
dae0: 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 69 6e   all of these in
daf0: 74 65 72 66 61 63 65 73 20 74 6f 20 62 65 20 4e  terfaces to be N
db00: 55 4c 4c 20 6f 72 20 66 6f 72 20 74 68 65 69 72  ULL or for their
db10: 20 62 65 68 61 76 69 6f 72 20 74 6f 20 63 68 61   behavior to cha
db20: 6e 67 65 0a 2a 2a 20 66 72 6f 6d 20 6f 6e 65 20  nge.** from one 
db30: 72 65 6c 65 61 73 65 20 74 6f 20 74 68 65 20 6e  release to the n
db40: 65 78 74 2e 20 20 41 70 70 6c 69 63 61 74 69 6f  ext.  Applicatio
db50: 6e 73 20 6d 75 73 74 20 6e 6f 74 20 61 74 74 65  ns must not atte
db60: 6d 70 74 20 74 6f 20 61 63 63 65 73 73 0a 2a 2a  mpt to access.**
db70: 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 6d 65   any of these me
db80: 74 68 6f 64 73 20 69 66 20 74 68 65 20 69 56 65  thods if the iVe
db90: 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 56 46 53  rsion of the VFS
dba0: 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 33 2e   is less than 3.
dbb0: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
dbc0: 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20 73  ct sqlite3_vfs s
dbd0: 71 6c 69 74 65 33 5f 76 66 73 3b 0a 74 79 70 65  qlite3_vfs;.type
dbe0: 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 74  def void (*sqlit
dbf0: 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 28  e3_syscall_ptr)(
dc00: 76 6f 69 64 29 3b 0a 73 74 72 75 63 74 20 73 71  void);.struct sq
dc10: 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20 20 69 6e  lite3_vfs {.  in
dc20: 74 20 69 56 65 72 73 69 6f 6e 3b 20 20 20 20 20  t iVersion;     
dc30: 20 20 20 20 20 20 20 2f 2a 20 53 74 72 75 63 74         /* Struct
dc40: 75 72 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62  ure version numb
dc50: 65 72 20 28 63 75 72 72 65 6e 74 6c 79 20 33 29  er (currently 3)
dc60: 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73 46 69   */.  int szOsFi
dc70: 6c 65 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f  le;            /
dc80: 2a 20 53 69 7a 65 20 6f 66 20 73 75 62 63 6c 61  * Size of subcla
dc90: 73 73 65 64 20 73 71 6c 69 74 65 33 5f 66 69 6c  ssed sqlite3_fil
dca0: 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50 61 74  e */.  int mxPat
dcb0: 68 6e 61 6d 65 3b 20 20 20 20 20 20 20 20 20 20  hname;          
dcc0: 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c 65 20  /* Maximum file 
dcd0: 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74 68 20  pathname length 
dce0: 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76 66 73  */.  sqlite3_vfs
dcf0: 20 2a 70 4e 65 78 74 3b 20 20 20 20 20 20 2f 2a   *pNext;      /*
dd00: 20 4e 65 78 74 20 72 65 67 69 73 74 65 72 65 64   Next registered
dd10: 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73 74 20   VFS */.  const 
dd20: 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20 20 20  char *zName;    
dd30: 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68     /* Name of th
dd40: 69 73 20 76 69 72 74 75 61 6c 20 66 69 6c 65 20  is virtual file 
dd50: 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f 69 64  system */.  void
dd60: 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20 20   *pAppData;     
dd70: 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65 72 20       /* Pointer 
dd80: 74 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73  to application-s
dd90: 70 65 63 69 66 69 63 20 64 61 74 61 20 2a 2f 0a  pecific data */.
dda0: 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73    int (*xOpen)(s
ddb0: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
ddc0: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
ddd0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 0a 20  sqlite3_file*,. 
dde0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 69 6e                in
ddf0: 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 4f  t flags, int *pO
de00: 75 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20  utFlags);.  int 
de10: 28 2a 78 44 65 6c 65 74 65 29 28 73 71 6c 69 74  (*xDelete)(sqlit
de20: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
de30: 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20  har *zName, int 
de40: 73 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e 74 20  syncDir);.  int 
de50: 28 2a 78 41 63 63 65 73 73 29 28 73 71 6c 69 74  (*xAccess)(sqlit
de60: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
de70: 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20  har *zName, int 
de80: 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 52 65 73  flags, int *pRes
de90: 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46  Out);.  int (*xF
dea0: 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73 71 6c  ullPathname)(sql
deb0: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
dec0: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e   char *zName, in
ded0: 74 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a 7a 4f  t nOut, char *zO
dee0: 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28 2a 78  ut);.  void *(*x
def0: 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f  DlOpen)(sqlite3_
df00: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
df10: 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a 20 20   *zFilename);.  
df20: 76 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f 72 29  void (*xDlError)
df30: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69  (sqlite3_vfs*, i
df40: 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a  nt nByte, char *
df50: 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f 69 64  zErrMsg);.  void
df60: 20 28 2a 28 2a 78 44 6c 53 79 6d 29 28 73 71 6c   (*(*xDlSym)(sql
df70: 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69 64 2a 2c  ite3_vfs*,void*,
df80: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 79   const char *zSy
df90: 6d 62 6f 6c 29 29 28 76 6f 69 64 29 3b 0a 20 20  mbol))(void);.  
dfa0: 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73 65 29  void (*xDlClose)
dfb0: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 76  (sqlite3_vfs*, v
dfc0: 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  oid*);.  int (*x
dfd0: 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71 6c 69  Randomness)(sqli
dfe0: 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42  te3_vfs*, int nB
dff0: 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29  yte, char *zOut)
e000: 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65 65 70  ;.  int (*xSleep
e010: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
e020: 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73  int microseconds
e030: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 72  );.  int (*xCurr
e040: 65 6e 74 54 69 6d 65 29 28 73 71 6c 69 74 65 33  entTime)(sqlite3
e050: 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a 29 3b  _vfs*, double*);
e060: 0a 20 20 69 6e 74 20 28 2a 78 47 65 74 4c 61 73  .  int (*xGetLas
e070: 74 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f  tError)(sqlite3_
e080: 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68 61 72 20  vfs*, int, char 
e090: 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68  *);.  /*.  ** Th
e0a0: 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20  e methods above 
e0b0: 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 20 31  are in version 1
e0c0: 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76   of the sqlite_v
e0d0: 66 73 20 6f 62 6a 65 63 74 0a 20 20 2a 2a 20 64  fs object.  ** d
e0e0: 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 6f 73  efinition.  Thos
e0f0: 65 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 61 72  e that follow ar
e100: 65 20 61 64 64 65 64 20 69 6e 20 76 65 72 73 69  e added in versi
e110: 6f 6e 20 32 20 6f 72 20 6c 61 74 65 72 0a 20 20  on 2 or later.  
e120: 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 72  */.  int (*xCurr
e130: 65 6e 74 54 69 6d 65 49 6e 74 36 34 29 28 73 71  entTimeInt64)(sq
e140: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 73 71 6c 69  lite3_vfs*, sqli
e150: 74 65 33 5f 69 6e 74 36 34 2a 29 3b 0a 20 20 2f  te3_int64*);.  /
e160: 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f  *.  ** The metho
e170: 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20  ds above are in 
e180: 76 65 72 73 69 6f 6e 73 20 31 20 61 6e 64 20 32  versions 1 and 2
e190: 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76   of the sqlite_v
e1a0: 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a 20  fs object..  ** 
e1b0: 54 68 6f 73 65 20 62 65 6c 6f 77 20 61 72 65 20  Those below are 
e1c0: 66 6f 72 20 76 65 72 73 69 6f 6e 20 33 20 61 6e  for version 3 an
e1d0: 64 20 67 72 65 61 74 65 72 2e 0a 20 20 2a 2f 0a  d greater..  */.
e1e0: 20 20 69 6e 74 20 28 2a 78 53 65 74 53 79 73 74    int (*xSetSyst
e1f0: 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f  emCall)(sqlite3_
e200: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
e210: 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33   *zName, sqlite3
e220: 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 3b 0a 20  _syscall_ptr);. 
e230: 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c   sqlite3_syscall
e240: 5f 70 74 72 20 28 2a 78 47 65 74 53 79 73 74 65  _ptr (*xGetSyste
e250: 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76  mCall)(sqlite3_v
e260: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
e270: 2a 7a 4e 61 6d 65 29 3b 0a 20 20 63 6f 6e 73 74  *zName);.  const
e280: 20 63 68 61 72 20 2a 28 2a 78 4e 65 78 74 53 79   char *(*xNextSy
e290: 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65  stemCall)(sqlite
e2a0: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
e2b0: 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 2f 2a  ar *zName);.  /*
e2c0: 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64  .  ** The method
e2d0: 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76  s above are in v
e2e0: 65 72 73 69 6f 6e 73 20 31 20 74 68 72 6f 75 67  ersions 1 throug
e2f0: 68 20 33 20 6f 66 20 74 68 65 20 73 71 6c 69 74  h 3 of the sqlit
e300: 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20  e_vfs object..  
e310: 2a 2a 20 4e 65 77 20 66 69 65 6c 64 73 20 6d 61  ** New fields ma
e320: 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 69 6e  y be appended in
e330: 20 66 69 67 75 72 65 20 76 65 72 73 69 6f 6e 73   figure versions
e340: 2e 20 20 54 68 65 20 69 56 65 72 73 69 6f 6e 0a  .  The iVersion.
e350: 20 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c 6c 20    ** value will 
e360: 69 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e 65 76  increment whenev
e370: 65 72 20 74 68 69 73 20 68 61 70 70 65 6e 73 2e  er this happens.
e380: 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a   .  */.};../*.**
e390: 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73   CAPI3REF: Flags
e3a0: 20 66 6f 72 20 74 68 65 20 78 41 63 63 65 73 73   for the xAccess
e3b0: 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a   VFS method.**.*
e3c0: 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20  * These integer 
e3d0: 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20 62 65  constants can be
e3e0: 20 75 73 65 64 20 61 73 20 74 68 65 20 74 68 69   used as the thi
e3f0: 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  rd parameter to.
e400: 2a 2a 20 74 68 65 20 78 41 63 63 65 73 73 20 6d  ** the xAccess m
e410: 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73 71 6c  ethod of an [sql
e420: 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
e430: 2e 20 20 54 68 65 79 20 64 65 74 65 72 6d 69 6e  .  They determin
e440: 65 0a 2a 2a 20 77 68 61 74 20 6b 69 6e 64 20 6f  e.** what kind o
e450: 66 20 70 65 72 6d 69 73 73 69 6f 6e 73 20 74 68  f permissions th
e460: 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64  e xAccess method
e470: 20 69 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f 72 2e   is looking for.
e480: 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f  .** With SQLITE_
e490: 41 43 43 45 53 53 5f 45 58 49 53 54 53 2c 20 74  ACCESS_EXISTS, t
e4a0: 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f  he xAccess metho
e4b0: 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68 65 63  d.** simply chec
e4c0: 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20 66  ks whether the f
e4d0: 69 6c 65 20 65 78 69 73 74 73 2e 0a 2a 2a 20 57  ile exists..** W
e4e0: 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53  ith SQLITE_ACCES
e4f0: 53 5f 52 45 41 44 57 52 49 54 45 2c 20 74 68 65  S_READWRITE, the
e500: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a   xAccess method.
e510: 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 65  ** checks whethe
e520: 72 20 74 68 65 20 6e 61 6d 65 64 20 64 69 72 65  r the named dire
e530: 63 74 6f 72 79 20 69 73 20 62 6f 74 68 20 72 65  ctory is both re
e540: 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61  adable and writa
e550: 62 6c 65 0a 2a 2a 20 28 69 6e 20 6f 74 68 65 72  ble.** (in other
e560: 20 77 6f 72 64 73 2c 20 69 66 20 66 69 6c 65 73   words, if files
e570: 20 63 61 6e 20 62 65 20 61 64 64 65 64 2c 20 72   can be added, r
e580: 65 6d 6f 76 65 64 2c 20 61 6e 64 20 72 65 6e 61  emoved, and rena
e590: 6d 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68  med within.** th
e5a0: 65 20 64 69 72 65 63 74 6f 72 79 29 2e 0a 2a 2a  e directory)..**
e5b0: 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43 45   The SQLITE_ACCE
e5c0: 53 53 5f 52 45 41 44 57 52 49 54 45 20 63 6f 6e  SS_READWRITE con
e5d0: 73 74 61 6e 74 20 69 73 20 63 75 72 72 65 6e 74  stant is current
e5e0: 6c 79 20 75 73 65 64 20 6f 6e 6c 79 20 62 79 20  ly used only by 
e5f0: 74 68 65 0a 2a 2a 20 5b 74 65 6d 70 5f 73 74 6f  the.** [temp_sto
e600: 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61  re_directory pra
e610: 67 6d 61 5d 2c 20 74 68 6f 75 67 68 20 74 68 69  gma], though thi
e620: 73 20 63 6f 75 6c 64 20 63 68 61 6e 67 65 20 69  s could change i
e630: 6e 20 61 20 66 75 74 75 72 65 0a 2a 2a 20 72 65  n a future.** re
e640: 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e  lease of SQLite.
e650: 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f  .** With SQLITE_
e660: 41 43 43 45 53 53 5f 52 45 41 44 2c 20 74 68 65  ACCESS_READ, the
e670: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a   xAccess method.
e680: 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 65  ** checks whethe
e690: 72 20 74 68 65 20 66 69 6c 65 20 69 73 20 72 65  r the file is re
e6a0: 61 64 61 62 6c 65 2e 20 20 54 68 65 20 53 51 4c  adable.  The SQL
e6b0: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20  ITE_ACCESS_READ 
e6c0: 63 6f 6e 73 74 61 6e 74 20 69 73 0a 2a 2a 20 63  constant is.** c
e6d0: 75 72 72 65 6e 74 6c 79 20 75 6e 75 73 65 64 2c  urrently unused,
e6e0: 20 74 68 6f 75 67 68 20 69 74 20 6d 69 67 68 74   though it might
e6f0: 20 62 65 20 75 73 65 64 20 69 6e 20 61 20 66 75   be used in a fu
e700: 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66 0a  ture release of.
e710: 2a 2a 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64  ** SQLite..*/.#d
e720: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43  efine SQLITE_ACC
e730: 45 53 53 5f 45 58 49 53 54 53 20 20 20 20 30 0a  ESS_EXISTS    0.
e740: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
e750: 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 20  CCESS_READWRITE 
e760: 31 20 20 20 2f 2a 20 55 73 65 64 20 62 79 20 50  1   /* Used by P
e770: 52 41 47 4d 41 20 74 65 6d 70 5f 73 74 6f 72 65  RAGMA temp_store
e780: 5f 64 69 72 65 63 74 6f 72 79 20 2a 2f 0a 23 64  _directory */.#d
e790: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43  efine SQLITE_ACC
e7a0: 45 53 53 5f 52 45 41 44 20 20 20 20 20 20 32 20  ESS_READ      2 
e7b0: 20 20 2f 2a 20 55 6e 75 73 65 64 20 2a 2f 0a 0a    /* Unused */..
e7c0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
e7d0: 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78 53  Flags for the xS
e7e0: 68 6d 4c 6f 63 6b 20 56 46 53 20 6d 65 74 68 6f  hmLock VFS metho
e7f0: 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e  d.**.** These in
e800: 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20  teger constants 
e810: 64 65 66 69 6e 65 20 74 68 65 20 76 61 72 69 6f  define the vario
e820: 75 73 20 6c 6f 63 6b 69 6e 67 20 6f 70 65 72 61  us locking opera
e830: 74 69 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f 77 65 64  tions.** allowed
e840: 20 62 79 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b   by the xShmLock
e850: 20 6d 65 74 68 6f 64 20 6f 66 20 5b 73 71 6c 69   method of [sqli
e860: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 2e  te3_io_methods].
e870: 20 20 54 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69    The.** followi
e880: 6e 67 20 61 72 65 20 74 68 65 20 6f 6e 6c 79 20  ng are the only 
e890: 6c 65 67 61 6c 20 63 6f 6d 62 69 6e 61 74 69 6f  legal combinatio
e8a0: 6e 73 20 6f 66 20 66 6c 61 67 73 20 74 6f 20 74  ns of flags to t
e8b0: 68 65 0a 2a 2a 20 78 53 68 6d 4c 6f 63 6b 20 6d  he.** xShmLock m
e8c0: 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  ethod:.**.** <ul
e8d0: 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54  >.** <li>  SQLIT
e8e0: 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c  E_SHM_LOCK | SQL
e8f0: 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a  ITE_SHM_SHARED.*
e900: 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53  * <li>  SQLITE_S
e910: 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45  HM_LOCK | SQLITE
e920: 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a 2a  _SHM_EXCLUSIVE.*
e930: 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53  * <li>  SQLITE_S
e940: 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49  HM_UNLOCK | SQLI
e950: 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a 2a  TE_SHM_SHARED.**
e960: 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48   <li>  SQLITE_SH
e970: 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 54  M_UNLOCK | SQLIT
e980: 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a  E_SHM_EXCLUSIVE.
e990: 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 57  ** </ul>.**.** W
e9a0: 68 65 6e 20 75 6e 6c 6f 63 6b 69 6e 67 2c 20 74  hen unlocking, t
e9b0: 68 65 20 73 61 6d 65 20 53 48 41 52 45 44 20 6f  he same SHARED o
e9c0: 72 20 45 58 43 4c 55 53 49 56 45 20 66 6c 61 67  r EXCLUSIVE flag
e9d0: 20 6d 75 73 74 20 62 65 20 73 75 70 70 6c 69 65   must be supplie
e9e0: 64 20 61 73 0a 2a 2a 20 77 61 73 20 67 69 76 65  d as.** was give
e9f0: 6e 20 6e 6f 20 74 68 65 20 63 6f 72 72 65 73 70  n no the corresp
ea00: 6f 6e 64 69 6e 67 20 6c 6f 63 6b 2e 20 20 0a 2a  onding lock.  .*
ea10: 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63  *.** The xShmLoc
ea20: 6b 20 6d 65 74 68 6f 64 20 63 61 6e 20 74 72 61  k method can tra
ea30: 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e 20  nsition between 
ea40: 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 53 48 41  unlocked and SHA
ea50: 52 45 44 20 6f 72 0a 2a 2a 20 62 65 74 77 65 65  RED or.** betwee
ea60: 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 45  n unlocked and E
ea70: 58 43 4c 55 53 49 56 45 2e 20 20 49 74 20 63 61  XCLUSIVE.  It ca
ea80: 6e 6e 6f 74 20 74 72 61 6e 73 69 74 69 6f 6e 20  nnot transition 
ea90: 62 65 74 77 65 65 6e 20 53 48 41 52 45 44 0a 2a  between SHARED.*
eaa0: 2a 20 61 6e 64 20 45 58 43 4c 55 53 49 56 45 2e  * and EXCLUSIVE.
eab0: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
eac0: 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 20 20  TE_SHM_UNLOCK   
ead0: 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51      1.#define SQ
eae0: 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 20 20  LITE_SHM_LOCK   
eaf0: 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20        2.#define 
eb00: 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45  SQLITE_SHM_SHARE
eb10: 44 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e  D       4.#defin
eb20: 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43  e SQLITE_SHM_EXC
eb30: 4c 55 53 49 56 45 20 20 20 20 38 0a 0a 2f 2a 0a  LUSIVE    8../*.
eb40: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 61 78  ** CAPI3REF: Max
eb50: 69 6d 75 6d 20 78 53 68 6d 4c 6f 63 6b 20 69 6e  imum xShmLock in
eb60: 64 65 78 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53  dex.**.** The xS
eb70: 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 6e  hmLock method on
eb80: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
eb90: 68 6f 64 73 5d 20 6d 61 79 20 75 73 65 20 76 61  hods] may use va
eba0: 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20  lues.** between 
ebb0: 30 20 61 6e 64 20 74 68 69 73 20 75 70 70 65 72  0 and this upper
ebc0: 20 62 6f 75 6e 64 20 61 73 20 69 74 73 20 22 6f   bound as its "o
ebd0: 66 66 73 65 74 22 20 61 72 67 75 6d 65 6e 74 2e  ffset" argument.
ebe0: 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63  .** The SQLite c
ebf0: 6f 72 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 61  ore will never a
ec00: 74 74 65 6d 70 74 20 74 6f 20 61 63 71 75 69 72  ttempt to acquir
ec10: 65 20 6f 72 20 72 65 6c 65 61 73 65 20 61 0a 2a  e or release a.*
ec20: 2a 20 6c 6f 63 6b 20 6f 75 74 73 69 64 65 20 6f  * lock outside o
ec30: 66 20 74 68 69 73 20 72 61 6e 67 65 0a 2a 2f 0a  f this range.*/.
ec40: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
ec50: 48 4d 5f 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20  HM_NLOCK        
ec60: 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  8.../*.** CAPI3R
ec70: 45 46 3a 20 49 6e 69 74 69 61 6c 69 7a 65 20 54  EF: Initialize T
ec80: 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72  he SQLite Librar
ec90: 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  y.**.** ^The sql
eca0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
ecb0: 29 20 72 6f 75 74 69 6e 65 20 69 6e 69 74 69 61  ) routine initia
ecc0: 6c 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53 51 4c  lizes the.** SQL
ecd0: 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 5e 54  ite library.  ^T
ece0: 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  he sqlite3_shutd
ecf0: 6f 77 6e 28 29 20 72 6f 75 74 69 6e 65 0a 2a 2a  own() routine.**
ed00: 20 64 65 61 6c 6c 6f 63 61 74 65 73 20 61 6e 79   deallocates any
ed10: 20 72 65 73 6f 75 72 63 65 73 20 74 68 61 74 20   resources that 
ed20: 77 65 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62  were allocated b
ed30: 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  y sqlite3_initia
ed40: 6c 69 7a 65 28 29 2e 0a 2a 2a 20 54 68 65 73 65  lize()..** These
ed50: 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 64 65   routines are de
ed60: 73 69 67 6e 65 64 20 74 6f 20 61 69 64 20 69 6e  signed to aid in
ed70: 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61 6c   process initial
ed80: 69 7a 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 73  ization and.** s
ed90: 68 75 74 64 6f 77 6e 20 6f 6e 20 65 6d 62 65 64  hutdown on embed
eda0: 64 65 64 20 73 79 73 74 65 6d 73 2e 20 20 57 6f  ded systems.  Wo
edb0: 72 6b 73 74 61 74 69 6f 6e 20 61 70 70 6c 69 63  rkstation applic
edc0: 61 74 69 6f 6e 73 20 75 73 69 6e 67 0a 2a 2a 20  ations using.** 
edd0: 53 51 4c 69 74 65 20 6e 6f 72 6d 61 6c 6c 79 20  SQLite normally 
ede0: 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 69  do not need to i
edf0: 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 6f 66 20  nvoke either of 
ee00: 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a  these routines..
ee10: 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20  **.** A call to 
ee20: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
ee30: 7a 65 28 29 20 69 73 20 61 6e 20 22 65 66 66 65  ze() is an "effe
ee40: 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69  ctive" call if i
ee50: 74 20 69 73 0a 2a 2a 20 74 68 65 20 66 69 72 73  t is.** the firs
ee60: 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69  t time sqlite3_i
ee70: 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69  nitialize() is i
ee80: 6e 76 6f 6b 65 64 20 64 75 72 69 6e 67 20 74 68  nvoked during th
ee90: 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 0a 2a 2a  e lifetime of.**
eea0: 20 74 68 65 20 70 72 6f 63 65 73 73 2c 20 6f 72   the process, or
eeb0: 20 69 66 20 69 74 20 69 73 20 74 68 65 20 66 69   if it is the fi
eec0: 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33  rst time sqlite3
eed0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73  _initialize() is
eee0: 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f 6c 6c   invoked.** foll
eef0: 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20  owing a call to 
ef00: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
ef10: 28 29 2e 20 20 5e 28 4f 6e 6c 79 20 61 6e 20 65  ().  ^(Only an e
ef20: 66 66 65 63 74 69 76 65 20 63 61 6c 6c 0a 2a 2a  ffective call.**
ef30: 20 6f 66 20 73 71 6c 69 74 65 33 5f 69 6e 69 74   of sqlite3_init
ef40: 69 61 6c 69 7a 65 28 29 20 64 6f 65 73 20 61 6e  ialize() does an
ef50: 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  y initialization
ef60: 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 63 61 6c  .  All other cal
ef70: 6c 73 0a 2a 2a 20 61 72 65 20 68 61 72 6d 6c 65  ls.** are harmle
ef80: 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a  ss no-ops.)^.**.
ef90: 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c  ** A call to sql
efa0: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20  ite3_shutdown() 
efb0: 69 73 20 61 6e 20 22 65 66 66 65 63 74 69 76 65  is an "effective
efc0: 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73 20  " call if it is 
efd0: 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 63 61 6c  the first.** cal
efe0: 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75  l to sqlite3_shu
eff0: 74 64 6f 77 6e 28 29 20 73 69 6e 63 65 20 74 68  tdown() since th
f000: 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33 5f 69  e last sqlite3_i
f010: 6e 69 74 69 61 6c 69 7a 65 28 29 2e 20 20 5e 28  nitialize().  ^(
f020: 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66 66 65 63  Only.** an effec
f030: 74 69 76 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c  tive call to sql
f040: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20  ite3_shutdown() 
f050: 64 6f 65 73 20 61 6e 79 20 64 65 69 6e 69 74 69  does any deiniti
f060: 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 20 41 6c  alization..** Al
f070: 6c 20 6f 74 68 65 72 20 76 61 6c 69 64 20 63 61  l other valid ca
f080: 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  lls to sqlite3_s
f090: 68 75 74 64 6f 77 6e 28 29 20 61 72 65 20 68 61  hutdown() are ha
f0a0: 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e  rmless no-ops.)^
f0b0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
f0c0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
f0d0: 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 68 72  interface is thr
f0e0: 65 61 64 73 61 66 65 2c 20 62 75 74 20 73 71 6c  eadsafe, but sql
f0f0: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a  ite3_shutdown().
f100: 2a 2a 20 69 73 20 6e 6f 74 2e 20 20 54 68 65 20  ** is not.  The 
f110: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
f120: 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d 75 73  () interface mus
f130: 74 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64  t only be called
f140: 20 66 72 6f 6d 20 61 0a 2a 2a 20 73 69 6e 67 6c   from a.** singl
f150: 65 20 74 68 72 65 61 64 2e 20 20 41 6c 6c 20 6f  e thread.  All o
f160: 70 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f  pen [database co
f170: 6e 6e 65 63 74 69 6f 6e 73 5d 20 6d 75 73 74 20  nnections] must 
f180: 62 65 20 63 6c 6f 73 65 64 20 61 6e 64 20 61 6c  be closed and al
f190: 6c 0a 2a 2a 20 6f 74 68 65 72 20 53 51 4c 69 74  l.** other SQLit
f1a0: 65 20 72 65 73 6f 75 72 63 65 73 20 6d 75 73 74  e resources must
f1b0: 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20   be deallocated 
f1c0: 70 72 69 6f 72 20 74 6f 20 69 6e 76 6f 6b 69 6e  prior to invokin
f1d0: 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 68 75  g.** sqlite3_shu
f1e0: 74 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 41  tdown()..**.** A
f1f0: 6d 6f 6e 67 20 6f 74 68 65 72 20 74 68 69 6e 67  mong other thing
f200: 73 2c 20 5e 73 71 6c 69 74 65 33 5f 69 6e 69 74  s, ^sqlite3_init
f210: 69 61 6c 69 7a 65 28 29 20 77 69 6c 6c 20 69 6e  ialize() will in
f220: 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  voke.** sqlite3_
f230: 6f 73 5f 69 6e 69 74 28 29 2e 20 20 53 69 6d 69  os_init().  Simi
f240: 6c 61 72 6c 79 2c 20 5e 73 71 6c 69 74 65 33 5f  larly, ^sqlite3_
f250: 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 77 69  shutdown().** wi
f260: 6c 6c 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65  ll invoke sqlite
f270: 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a 0a 2a  3_os_end()..**.*
f280: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69  * ^The sqlite3_i
f290: 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74  nitialize() rout
f2a0: 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ine returns [SQL
f2b0: 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65  ITE_OK] on succe
f2c0: 73 73 2e 0a 2a 2a 20 5e 49 66 20 66 6f 72 20 73  ss..** ^If for s
f2d0: 6f 6d 65 20 72 65 61 73 6f 6e 2c 20 73 71 6c 69  ome reason, sqli
f2e0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
f2f0: 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 69 6e   is unable to in
f300: 69 74 69 61 6c 69 7a 65 0a 2a 2a 20 74 68 65 20  itialize.** the 
f310: 6c 69 62 72 61 72 79 20 28 70 65 72 68 61 70 73  library (perhaps
f320: 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f   it is unable to
f330: 20 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65 65 64   allocate a need
f340: 65 64 20 72 65 73 6f 75 72 63 65 20 73 75 63 68  ed resource such
f350: 0a 2a 2a 20 61 73 20 61 20 6d 75 74 65 78 29 20  .** as a mutex) 
f360: 69 74 20 72 65 74 75 72 6e 73 20 61 6e 20 5b 65  it returns an [e
f370: 72 72 6f 72 20 63 6f 64 65 5d 20 6f 74 68 65 72  rror code] other
f380: 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b   than [SQLITE_OK
f390: 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ]..**.** ^The sq
f3a0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
f3b0: 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61  () routine is ca
f3c0: 6c 6c 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20  lled internally 
f3d0: 62 79 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a  by many other.**
f3e0: 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
f3f0: 65 73 20 73 6f 20 74 68 61 74 20 61 6e 20 61 70  es so that an ap
f400: 70 6c 69 63 61 74 69 6f 6e 20 75 73 75 61 6c 6c  plication usuall
f410: 79 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20  y does not need 
f420: 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c  to.** invoke sql
f430: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
f440: 29 20 64 69 72 65 63 74 6c 79 2e 20 20 46 6f 72  ) directly.  For
f450: 20 65 78 61 6d 70 6c 65 2c 20 5b 73 71 6c 69 74   example, [sqlit
f460: 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 63 61  e3_open()].** ca
f470: 6c 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  lls sqlite3_init
f480: 69 61 6c 69 7a 65 28 29 20 73 6f 20 74 68 65 20  ialize() so the 
f490: 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77  SQLite library w
f4a0: 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63  ill be automatic
f4b0: 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69 61 6c 69  ally.** initiali
f4c0: 7a 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65  zed when [sqlite
f4d0: 33 5f 6f 70 65 6e 28 29 5d 20 69 73 20 63 61 6c  3_open()] is cal
f4e0: 6c 65 64 20 69 66 20 69 74 20 68 61 73 20 6e 6f  led if it has no
f4f0: 74 20 62 65 20 69 6e 69 74 69 61 6c 69 7a 65 64  t be initialized
f500: 0a 2a 2a 20 61 6c 72 65 61 64 79 2e 20 20 5e 48  .** already.  ^H
f510: 6f 77 65 76 65 72 2c 20 69 66 20 53 51 4c 69 74  owever, if SQLit
f520: 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
f530: 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  th the [SQLITE_O
f540: 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 0a 2a 2a  MIT_AUTOINIT].**
f550: 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
f560: 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 61  tion, then the a
f570: 75 74 6f 6d 61 74 69 63 20 63 61 6c 6c 73 20 74  utomatic calls t
f580: 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  o sqlite3_initia
f590: 6c 69 7a 65 28 29 0a 2a 2a 20 61 72 65 20 6f 6d  lize().** are om
f5a0: 69 74 74 65 64 20 61 6e 64 20 74 68 65 20 61 70  itted and the ap
f5b0: 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 63  plication must c
f5c0: 61 6c 6c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  all sqlite3_init
f5d0: 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c  ialize() directl
f5e0: 79 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 75 73  y.** prior to us
f5f0: 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51  ing any other SQ
f600: 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20  Lite interface. 
f610: 20 46 6f 72 20 6d 61 78 69 6d 75 6d 20 70 6f 72   For maximum por
f620: 74 61 62 69 6c 69 74 79 2c 0a 2a 2a 20 69 74 20  tability,.** it 
f630: 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74  is recommended t
f640: 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  hat applications
f650: 20 61 6c 77 61 79 73 20 69 6e 76 6f 6b 65 20 73   always invoke s
f660: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
f670: 65 28 29 0a 2a 2a 20 64 69 72 65 63 74 6c 79 20  e().** directly 
f680: 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61  prior to using a
f690: 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20  ny other SQLite 
f6a0: 69 6e 74 65 72 66 61 63 65 2e 20 20 46 75 74 75  interface.  Futu
f6b0: 72 65 20 72 65 6c 65 61 73 65 73 0a 2a 2a 20 6f  re releases.** o
f6c0: 66 20 53 51 4c 69 74 65 20 6d 61 79 20 72 65 71  f SQLite may req
f6d0: 75 69 72 65 20 74 68 69 73 2e 20 20 49 6e 20 6f  uire this.  In o
f6e0: 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20  ther words, the 
f6f0: 62 65 68 61 76 69 6f 72 20 65 78 68 69 62 69 74  behavior exhibit
f700: 65 64 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74  ed.** when SQLit
f710: 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
f720: 74 68 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  th [SQLITE_OMIT_
f730: 41 55 54 4f 49 4e 49 54 5d 20 6d 69 67 68 74 20  AUTOINIT] might 
f740: 62 65 63 6f 6d 65 20 74 68 65 0a 2a 2a 20 64 65  become the.** de
f750: 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20 69  fault behavior i
f760: 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20 72 65  n some future re
f770: 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e  lease of SQLite.
f780: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
f790: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 72 6f 75  e3_os_init() rou
f7a0: 74 69 6e 65 20 64 6f 65 73 20 6f 70 65 72 61 74  tine does operat
f7b0: 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69  ing-system speci
f7c0: 66 69 63 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a  fic.** initializ
f7d0: 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 53 51 4c  ation of the SQL
f7e0: 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 54 68  ite library.  Th
f7f0: 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  e sqlite3_os_end
f800: 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 75 6e  ().** routine un
f810: 64 6f 65 73 20 74 68 65 20 65 66 66 65 63 74 20  does the effect 
f820: 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  of sqlite3_os_in
f830: 69 74 28 29 2e 20 20 54 79 70 69 63 61 6c 20 74  it().  Typical t
f840: 61 73 6b 73 0a 2a 2a 20 70 65 72 66 6f 72 6d 65  asks.** performe
f850: 64 20 62 79 20 74 68 65 73 65 20 72 6f 75 74 69  d by these routi
f860: 6e 65 73 20 69 6e 63 6c 75 64 65 20 61 6c 6c 6f  nes include allo
f870: 63 61 74 69 6f 6e 20 6f 72 20 64 65 61 6c 6c 6f  cation or deallo
f880: 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73 74 61  cation.** of sta
f890: 74 69 63 20 72 65 73 6f 75 72 63 65 73 2c 20 69  tic resources, i
f8a0: 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66  nitialization of
f8b0: 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65   global variable
f8c0: 73 2c 0a 2a 2a 20 73 65 74 74 69 6e 67 20 75 70  s,.** setting up
f8d0: 20 61 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69   a default [sqli
f8e0: 74 65 33 5f 76 66 73 5d 20 6d 6f 64 75 6c 65 2c  te3_vfs] module,
f8f0: 20 6f 72 20 73 65 74 74 69 6e 67 20 75 70 0a 2a   or setting up.*
f900: 2a 20 61 20 64 65 66 61 75 6c 74 20 63 6f 6e 66  * a default conf
f910: 69 67 75 72 61 74 69 6f 6e 20 75 73 69 6e 67 20  iguration using 
f920: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
f930: 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70  )]..**.** The ap
f940: 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64  plication should
f950: 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 65 69   never invoke ei
f960: 74 68 65 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f  ther sqlite3_os_
f970: 69 6e 69 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c  init().** or sql
f980: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 64 69  ite3_os_end() di
f990: 72 65 63 74 6c 79 2e 20 20 54 68 65 20 61 70 70  rectly.  The app
f9a0: 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  lication should 
f9b0: 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73  only invoke.** s
f9c0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
f9d0: 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  e() and sqlite3_
f9e0: 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 54 68 65  shutdown().  The
f9f0: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
fa00: 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  ().** interface 
fa10: 69 73 20 63 61 6c 6c 65 64 20 61 75 74 6f 6d 61  is called automa
fa20: 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74  tically by sqlit
fa30: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
fa40: 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  and.** sqlite3_o
fa50: 73 5f 65 6e 64 28 29 20 69 73 20 63 61 6c 6c 65  s_end() is calle
fa60: 64 20 62 79 20 73 71 6c 69 74 65 33 5f 73 68 75  d by sqlite3_shu
fa70: 74 64 6f 77 6e 28 29 2e 20 20 41 70 70 72 6f 70  tdown().  Approp
fa80: 72 69 61 74 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65  riate.** impleme
fa90: 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20 73 71 6c  ntations for sql
faa0: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61  ite3_os_init() a
fab0: 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  nd sqlite3_os_en
fac0: 64 28 29 0a 2a 2a 20 61 72 65 20 62 75 69 6c 74  d().** are built
fad0: 20 69 6e 74 6f 20 53 51 4c 69 74 65 20 77 68 65   into SQLite whe
fae0: 6e 20 69 74 20 69 73 20 63 6f 6d 70 69 6c 65 64  n it is compiled
faf0: 20 66 6f 72 20 55 6e 69 78 2c 20 57 69 6e 64 6f   for Unix, Windo
fb00: 77 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a 2a 2a 20  ws, or OS/2..** 
fb10: 57 68 65 6e 20 5b 63 75 73 74 6f 6d 20 62 75 69  When [custom bui
fb20: 6c 64 73 20 7c 20 62 75 69 6c 74 20 66 6f 72 20  lds | built for 
fb30: 6f 74 68 65 72 20 70 6c 61 74 66 6f 72 6d 73 5d  other platforms]
fb40: 0a 2a 2a 20 28 75 73 69 6e 67 20 74 68 65 20 5b  .** (using the [
fb50: 53 51 4c 49 54 45 5f 4f 53 5f 4f 54 48 45 52 3d  SQLITE_OS_OTHER=
fb60: 31 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a  1] compile-time.
fb70: 2a 2a 20 6f 70 74 69 6f 6e 29 20 74 68 65 20 61  ** option) the a
fb80: 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
fb90: 73 75 70 70 6c 79 20 61 20 73 75 69 74 61 62 6c  supply a suitabl
fba0: 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
fbb0: 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   for.** sqlite3_
fbc0: 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71  os_init() and sq
fbd0: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 20  lite3_os_end(). 
fbe0: 20 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   An application-
fbf0: 73 75 70 70 6c 69 65 64 0a 2a 2a 20 69 6d 70 6c  supplied.** impl
fc00: 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71  ementation of sq
fc10: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20  lite3_os_init() 
fc20: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  or sqlite3_os_en
fc30: 64 28 29 0a 2a 2a 20 6d 75 73 74 20 72 65 74 75  d().** must retu
fc40: 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f  rn [SQLITE_OK] o
fc50: 6e 20 73 75 63 63 65 73 73 20 61 6e 64 20 73 6f  n success and so
fc60: 6d 65 20 6f 74 68 65 72 20 5b 65 72 72 6f 72 20  me other [error 
fc70: 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20 66 61  code] upon.** fa
fc80: 69 6c 75 72 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ilure..*/.int sq
fc90: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
fca0: 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69  (void);.int sqli
fcb0: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 76 6f 69  te3_shutdown(voi
fcc0: 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  d);.int sqlite3_
fcd0: 6f 73 5f 69 6e 69 74 28 76 6f 69 64 29 3b 0a 69  os_init(void);.i
fce0: 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  nt sqlite3_os_en
fcf0: 64 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20  d(void);../*.** 
fd00: 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67  CAPI3REF: Config
fd10: 75 72 69 6e 67 20 54 68 65 20 53 51 4c 69 74 65  uring The SQLite
fd20: 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 54   Library.**.** T
fd30: 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  he sqlite3_confi
fd40: 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  g() interface is
fd50: 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 67 6c   used to make gl
fd60: 6f 62 61 6c 20 63 6f 6e 66 69 67 75 72 61 74 69  obal configurati
fd70: 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f  on.** changes to
fd80: 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72   SQLite in order
fd90: 20 74 6f 20 74 75 6e 65 20 53 51 4c 69 74 65 20   to tune SQLite 
fda0: 74 6f 20 74 68 65 20 73 70 65 63 69 66 69 63 20  to the specific 
fdb0: 6e 65 65 64 73 20 6f 66 0a 2a 2a 20 74 68 65 20  needs of.** the 
fdc0: 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 54 68  application.  Th
fdd0: 65 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67  e default config
fde0: 75 72 61 74 69 6f 6e 20 69 73 20 72 65 63 6f 6d  uration is recom
fdf0: 6d 65 6e 64 65 64 20 66 6f 72 20 6d 6f 73 74 0a  mended for most.
fe00: 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  ** applications 
fe10: 61 6e 64 20 73 6f 20 74 68 69 73 20 72 6f 75 74  and so this rout
fe20: 69 6e 65 20 69 73 20 75 73 75 61 6c 6c 79 20 6e  ine is usually n
fe30: 6f 74 20 6e 65 63 65 73 73 61 72 79 2e 20 20 49  ot necessary.  I
fe40: 74 20 69 73 0a 2a 2a 20 70 72 6f 76 69 64 65 64  t is.** provided
fe50: 20 74 6f 20 73 75 70 70 6f 72 74 20 72 61 72 65   to support rare
fe60: 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 77 69   applications wi
fe70: 74 68 20 75 6e 75 73 75 61 6c 20 6e 65 65 64 73  th unusual needs
fe80: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
fe90: 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74  te3_config() int
fea0: 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20 74 68  erface is not th
feb0: 72 65 61 64 73 61 66 65 2e 20 20 54 68 65 20 61  readsafe.  The a
fec0: 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75  pplication.** mu
fed0: 73 74 20 69 6e 73 75 72 65 20 74 68 61 74 20 6e  st insure that n
fee0: 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69  o other SQLite i
fef0: 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 69 6e  nterfaces are in
ff00: 76 6f 6b 65 64 20 62 79 20 6f 74 68 65 72 0a 2a  voked by other.*
ff10: 2a 20 74 68 72 65 61 64 73 20 77 68 69 6c 65 20  * threads while 
ff20: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
ff30: 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20 20 46 75   is running.  Fu
ff40: 72 74 68 65 72 6d 6f 72 65 2c 20 73 71 6c 69 74  rthermore, sqlit
ff50: 65 33 5f 63 6f 6e 66 69 67 28 29 0a 2a 2a 20 6d  e3_config().** m
ff60: 61 79 20 6f 6e 6c 79 20 62 65 20 69 6e 76 6f 6b  ay only be invok
ff70: 65 64 20 70 72 69 6f 72 20 74 6f 20 6c 69 62 72  ed prior to libr
ff80: 61 72 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  ary initializati
ff90: 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c  on using.** [sql
ffa0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
ffb0: 29 5d 20 6f 72 20 61 66 74 65 72 20 73 68 75 74  )] or after shut
ffc0: 64 6f 77 6e 20 62 79 20 5b 73 71 6c 69 74 65 33  down by [sqlite3
ffd0: 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a  _shutdown()]..**
ffe0: 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6f 6e   ^If sqlite3_con
fff0: 66 69 67 28 29 20 69 73 20 63 61 6c 6c 65 64 20  fig() is called 
10000 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 69  after [sqlite3_i
10010 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 61 6e 64  nitialize()] and
10020 20 62 65 66 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69   before.** [sqli
10030 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20  te3_shutdown()] 
10040 74 68 65 6e 20 69 74 20 77 69 6c 6c 20 72 65 74  then it will ret
10050 75 72 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53  urn SQLITE_MISUS
10060 45 2e 0a 2a 2a 20 4e 6f 74 65 2c 20 68 6f 77 65  E..** Note, howe
10070 76 65 72 2c 20 74 68 61 74 20 5e 73 71 6c 69 74  ver, that ^sqlit
10080 65 33 5f 63 6f 6e 66 69 67 28 29 20 63 61 6e 20  e3_config() can 
10090 62 65 20 63 61 6c 6c 65 64 20 61 73 20 70 61 72  be called as par
100a0 74 20 6f 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c  t of the.** impl
100b0 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e  ementation of an
100c0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
100d0 69 6e 65 64 20 5b 73 71 6c 69 74 65 33 5f 6f 73  ined [sqlite3_os
100e0 5f 69 6e 69 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  _init()]..**.** 
100f0 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
10100 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  nt to sqlite3_co
10110 6e 66 69 67 28 29 20 69 73 20 61 6e 20 69 6e 74  nfig() is an int
10120 65 67 65 72 0a 2a 2a 20 5b 63 6f 6e 66 69 67 75  eger.** [configu
10130 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 20 74  ration option] t
10140 68 61 74 20 64 65 74 65 72 6d 69 6e 65 73 0a 2a  hat determines.*
10150 2a 20 77 68 61 74 20 70 72 6f 70 65 72 74 79 20  * what property 
10160 6f 66 20 53 51 4c 69 74 65 20 69 73 20 74 6f 20  of SQLite is to 
10170 62 65 20 63 6f 6e 66 69 67 75 72 65 64 2e 20 20  be configured.  
10180 53 75 62 73 65 71 75 65 6e 74 20 61 72 67 75 6d  Subsequent argum
10190 65 6e 74 73 0a 2a 2a 20 76 61 72 79 20 64 65 70  ents.** vary dep
101a0 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 5b 63  ending on the [c
101b0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
101c0 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66  ion].** in the f
101d0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  irst argument..*
101e0 2a 0a 2a 2a 20 5e 57 68 65 6e 20 61 20 63 6f 6e  *.** ^When a con
101f0 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
10200 6e 20 69 73 20 73 65 74 2c 20 73 71 6c 69 74 65  n is set, sqlite
10210 33 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 75 72  3_config() retur
10220 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a  ns [SQLITE_OK]..
10230 2a 2a 20 5e 49 66 20 74 68 65 20 6f 70 74 69 6f  ** ^If the optio
10240 6e 20 69 73 20 75 6e 6b 6e 6f 77 6e 20 6f 72 20  n is unknown or 
10250 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65  SQLite is unable
10260 20 74 6f 20 73 65 74 20 74 68 65 20 6f 70 74 69   to set the opti
10270 6f 6e 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 20  on.** then this 
10280 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
10290 61 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f  a non-zero [erro
102a0 72 20 63 6f 64 65 5d 2e 0a 2a 2f 0a 69 6e 74 20  r code]..*/.int 
102b0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 69  sqlite3_config(i
102c0 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a  nt, ...);../*.**
102d0 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69   CAPI3REF: Confi
102e0 67 75 72 65 20 64 61 74 61 62 61 73 65 20 63 6f  gure database co
102f0 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20  nnections.**.** 
10300 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 63  The sqlite3_db_c
10310 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63  onfig() interfac
10320 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b  e is used to mak
10330 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a  e configuration.
10340 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 61 20  ** changes to a 
10350 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
10360 74 69 6f 6e 5d 2e 20 20 54 68 65 20 69 6e 74 65  tion].  The inte
10370 72 66 61 63 65 20 69 73 20 73 69 6d 69 6c 61 72  rface is similar
10380 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
10390 63 6f 6e 66 69 67 28 29 5d 20 65 78 63 65 70 74  config()] except
103a0 20 74 68 61 74 20 74 68 65 20 63 68 61 6e 67 65   that the change
103b0 73 20 61 70 70 6c 79 20 74 6f 20 61 20 73 69 6e  s apply to a sin
103c0 67 6c 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  gle.** [database
103d0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 73 70   connection] (sp
103e0 65 63 69 66 69 65 64 20 69 6e 20 74 68 65 20 66  ecified in the f
103f0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 29 2e 0a  irst argument)..
10400 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  **.** The second
10410 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
10420 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 44  ite3_db_config(D
10430 2c 56 2c 2e 2e 2e 29 20 20 69 73 20 74 68 65 0a  ,V,...)  is the.
10440 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e  ** [SQLITE_DBCON
10450 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 7c 20  FIG_LOOKASIDE | 
10460 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65  configuration ve
10470 72 62 5d 20 2d 20 61 6e 20 69 6e 74 65 67 65 72  rb] - an integer
10480 20 63 6f 64 65 20 0a 2a 2a 20 74 68 61 74 20 69   code .** that i
10490 6e 64 69 63 61 74 65 73 20 77 68 61 74 20 61 73  ndicates what as
104a0 70 65 63 74 20 6f 66 20 74 68 65 20 5b 64 61 74  pect of the [dat
104b0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
104c0 5d 20 69 73 20 62 65 69 6e 67 20 63 6f 6e 66 69  ] is being confi
104d0 67 75 72 65 64 2e 0a 2a 2a 20 53 75 62 73 65 71  gured..** Subseq
104e0 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 20 76  uent arguments v
104f0 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  ary depending on
10500 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69   the configurati
10510 6f 6e 20 76 65 72 62 2e 0a 2a 2a 0a 2a 2a 20 5e  on verb..**.** ^
10520 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  Calls to sqlite3
10530 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 72 65 74  _db_config() ret
10540 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66  urn SQLITE_OK if
10550 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20   and only if.** 
10560 74 68 65 20 63 61 6c 6c 20 69 73 20 63 6f 6e 73  the call is cons
10570 69 64 65 72 65 64 20 73 75 63 63 65 73 73 66 75  idered successfu
10580 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  l..*/.int sqlite
10590 33 5f 64 62 5f 63 6f 6e 66 69 67 28 73 71 6c 69  3_db_config(sqli
105a0 74 65 33 2a 2c 20 69 6e 74 20 6f 70 2c 20 2e 2e  te3*, int op, ..
105b0 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
105c0 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f  REF: Memory Allo
105d0 63 61 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73 0a  cation Routines.
105e0 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63  **.** An instanc
105f0 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
10600 20 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74   defines the int
10610 65 72 66 61 63 65 20 62 65 74 77 65 65 6e 20 53  erface between S
10620 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 6c 6f 77  QLite.** and low
10630 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c  -level memory al
10640 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  location routine
10650 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 6f 62  s..**.** This ob
10660 6a 65 63 74 20 69 73 20 75 73 65 64 20 69 6e 20  ject is used in 
10670 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61 63 65 20 69  only one place i
10680 6e 20 74 68 65 20 53 51 4c 69 74 65 20 69 6e 74  n the SQLite int
10690 65 72 66 61 63 65 2e 0a 2a 2a 20 41 20 70 6f 69  erface..** A poi
106a0 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61  nter to an insta
106b0 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65  nce of this obje
106c0 63 74 20 69 73 20 74 68 65 20 61 72 67 75 6d 65  ct is the argume
106d0 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  nt to.** [sqlite
106e0 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 68 65 6e  3_config()] when
106f0 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69   the configurati
10700 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20  on option is.** 
10710 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
10720 41 4c 4c 4f 43 5d 20 6f 72 20 5b 53 51 4c 49 54  ALLOC] or [SQLIT
10730 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c  E_CONFIG_GETMALL
10740 4f 43 5d 2e 20 20 0a 2a 2a 20 42 79 20 63 72 65  OC].  .** By cre
10750 61 74 69 6e 67 20 61 6e 20 69 6e 73 74 61 6e 63  ating an instanc
10760 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
10770 0a 2a 2a 20 61 6e 64 20 70 61 73 73 69 6e 67 20  .** and passing 
10780 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  it to [sqlite3_c
10790 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43  onfig]([SQLITE_C
107a0 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 29 0a 2a  ONFIG_MALLOC]).*
107b0 2a 20 64 75 72 69 6e 67 20 63 6f 6e 66 69 67 75  * during configu
107c0 72 61 74 69 6f 6e 2c 20 61 6e 20 61 70 70 6c 69  ration, an appli
107d0 63 61 74 69 6f 6e 20 63 61 6e 20 73 70 65 63 69  cation can speci
107e0 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76  fy an alternativ
107f0 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  e.** memory allo
10800 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d  cation subsystem
10810 20 66 6f 72 20 53 51 4c 69 74 65 20 74 6f 20 75   for SQLite to u
10820 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74  se for all of it
10830 73 0a 2a 2a 20 64 79 6e 61 6d 69 63 20 6d 65 6d  s.** dynamic mem
10840 6f 72 79 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a  ory needs..**.**
10850 20 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 69 74   Note that SQLit
10860 65 20 63 6f 6d 65 73 20 77 69 74 68 20 73 65 76  e comes with sev
10870 65 72 61 6c 20 5b 62 75 69 6c 74 2d 69 6e 20 6d  eral [built-in m
10880 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73  emory allocators
10890 5d 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 70 65  ].** that are pe
108a0 72 66 65 63 74 6c 79 20 61 64 65 71 75 61 74 65  rfectly adequate
108b0 20 66 6f 72 20 74 68 65 20 6f 76 65 72 77 68 65   for the overwhe
108c0 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69 74 79 20 6f  lming majority o
108d0 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a  f applications.*
108e0 2a 20 61 6e 64 20 74 68 61 74 20 74 68 69 73 20  * and that this 
108f0 6f 62 6a 65 63 74 20 69 73 20 6f 6e 6c 79 20 75  object is only u
10900 73 65 66 75 6c 20 74 6f 20 61 20 74 69 6e 79 20  seful to a tiny 
10910 6d 69 6e 6f 72 69 74 79 20 6f 66 20 61 70 70 6c  minority of appl
10920 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68  ications.** with
10930 20 73 70 65 63 69 61 6c 69 7a 65 64 20 6d 65 6d   specialized mem
10940 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ory allocation r
10950 65 71 75 69 72 65 6d 65 6e 74 73 2e 20 20 54 68  equirements.  Th
10960 69 73 20 6f 62 6a 65 63 74 20 69 73 0a 2a 2a 20  is object is.** 
10970 61 6c 73 6f 20 75 73 65 64 20 64 75 72 69 6e 67  also used during
10980 20 74 65 73 74 69 6e 67 20 6f 66 20 53 51 4c 69   testing of SQLi
10990 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 73  te in order to s
109a0 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e  pecify an altern
109b0 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20  ative.** memory 
109c0 61 6c 6c 6f 63 61 74 6f 72 20 74 68 61 74 20 73  allocator that s
109d0 69 6d 75 6c 61 74 65 73 20 6d 65 6d 6f 72 79 20  imulates memory 
109e0 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20 63 6f  out-of-memory co
109f0 6e 64 69 74 69 6f 6e 73 20 69 6e 0a 2a 2a 20 6f  nditions in.** o
10a00 72 64 65 72 20 74 6f 20 76 65 72 69 66 79 20 74  rder to verify t
10a10 68 61 74 20 53 51 4c 69 74 65 20 72 65 63 6f 76  hat SQLite recov
10a20 65 72 73 20 67 72 61 63 65 66 75 6c 6c 79 20 66  ers gracefully f
10a30 72 6f 6d 20 73 75 63 68 0a 2a 2a 20 63 6f 6e 64  rom such.** cond
10a40 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  itions..**.** Th
10a50 65 20 78 4d 61 6c 6c 6f 63 2c 20 78 52 65 61 6c  e xMalloc, xReal
10a60 6c 6f 63 2c 20 61 6e 64 20 78 46 72 65 65 20 6d  loc, and xFree m
10a70 65 74 68 6f 64 73 20 6d 75 73 74 20 77 6f 72 6b  ethods must work
10a80 20 6c 69 6b 65 20 74 68 65 0a 2a 2a 20 6d 61 6c   like the.** mal
10a90 6c 6f 63 28 29 2c 20 72 65 61 6c 6c 6f 63 28 29  loc(), realloc()
10aa0 20 61 6e 64 20 66 72 65 65 28 29 20 66 75 6e 63   and free() func
10ab0 74 69 6f 6e 73 20 66 72 6f 6d 20 74 68 65 20 73  tions from the s
10ac0 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72  tandard C librar
10ad0 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75  y..** ^SQLite gu
10ae0 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 68  arantees that th
10af0 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
10b00 74 20 74 6f 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63  t to.** xRealloc
10b10 20 69 73 20 61 6c 77 61 79 73 20 61 20 76 61 6c   is always a val
10b20 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 61  ue returned by a
10b30 20 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f 20 78   prior call to x
10b40 52 6f 75 6e 64 75 70 2e 0a 2a 2a 0a 2a 2a 20 78  Roundup..**.** x
10b50 53 69 7a 65 20 73 68 6f 75 6c 64 20 72 65 74 75  Size should retu
10b60 72 6e 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64  rn the allocated
10b70 20 73 69 7a 65 20 6f 66 20 61 20 6d 65 6d 6f 72   size of a memor
10b80 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  y allocation.** 
10b90 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69  previously obtai
10ba0 6e 65 64 20 66 72 6f 6d 20 78 4d 61 6c 6c 6f 63  ned from xMalloc
10bb0 20 6f 72 20 78 52 65 61 6c 6c 6f 63 2e 20 20 54   or xRealloc.  T
10bc0 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a  he allocated siz
10bd0 65 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61  e.** is always a
10be0 74 20 6c 65 61 73 74 20 61 73 20 62 69 67 20 61  t least as big a
10bf0 73 20 74 68 65 20 72 65 71 75 65 73 74 65 64 20  s the requested 
10c00 73 69 7a 65 20 62 75 74 20 6d 61 79 20 62 65 20  size but may be 
10c10 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  larger..**.** Th
10c20 65 20 78 52 6f 75 6e 64 75 70 20 6d 65 74 68 6f  e xRoundup metho
10c30 64 20 72 65 74 75 72 6e 73 20 77 68 61 74 20 77  d returns what w
10c40 6f 75 6c 64 20 62 65 20 74 68 65 20 61 6c 6c 6f  ould be the allo
10c50 63 61 74 65 64 20 73 69 7a 65 20 6f 66 0a 2a 2a  cated size of.**
10c60 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
10c70 74 69 6f 6e 20 67 69 76 65 6e 20 61 20 70 61 72  tion given a par
10c80 74 69 63 75 6c 61 72 20 72 65 71 75 65 73 74 65  ticular requeste
10c90 64 20 73 69 7a 65 2e 20 20 4d 6f 73 74 20 6d 65  d size.  Most me
10ca0 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f  mory.** allocato
10cb0 72 73 20 72 6f 75 6e 64 20 75 70 20 6d 65 6d 6f  rs round up memo
10cc0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 61  ry allocations a
10cd0 74 20 6c 65 61 73 74 20 74 6f 20 74 68 65 20 6e  t least to the n
10ce0 65 78 74 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20  ext multiple.** 
10cf0 6f 66 20 38 2e 20 20 53 6f 6d 65 20 61 6c 6c 6f  of 8.  Some allo
10d00 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20  cators round up 
10d10 74 6f 20 61 20 6c 61 72 67 65 72 20 6d 75 6c 74  to a larger mult
10d20 69 70 6c 65 20 6f 72 20 74 6f 20 61 20 70 6f 77  iple or to a pow
10d30 65 72 20 6f 66 20 32 2e 0a 2a 2a 20 45 76 65 72  er of 2..** Ever
10d40 79 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  y memory allocat
10d50 69 6f 6e 20 72 65 71 75 65 73 74 20 63 6f 6d 69  ion request comi
10d60 6e 67 20 69 6e 20 74 68 72 6f 75 67 68 20 5b 73  ng in through [s
10d70 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
10d80 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  .** or [sqlite3_
10d90 72 65 61 6c 6c 6f 63 28 29 5d 20 66 69 72 73 74  realloc()] first
10da0 20 63 61 6c 6c 73 20 78 52 6f 75 6e 64 75 70 2e   calls xRoundup.
10db0 20 20 49 66 20 78 52 6f 75 6e 64 75 70 20 72 65    If xRoundup re
10dc0 74 75 72 6e 73 20 30 2c 20 0a 2a 2a 20 74 68 61  turns 0, .** tha
10dd0 74 20 63 61 75 73 65 73 20 74 68 65 20 63 6f 72  t causes the cor
10de0 72 65 73 70 6f 6e 64 69 6e 67 20 6d 65 6d 6f 72  responding memor
10df0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20  y allocation to 
10e00 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  fail..**.** The 
10e10 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 69 6e 69  xInit method ini
10e20 74 69 61 6c 69 7a 65 73 20 74 68 65 20 6d 65 6d  tializes the mem
10e30 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 2e 20 20  ory allocator.  
10e40 46 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20  For example,.** 
10e50 69 74 20 6d 69 67 68 74 20 61 6c 6c 6f 63 61 74  it might allocat
10e60 65 20 61 6e 79 20 72 65 71 75 69 72 65 20 6d 75  e any require mu
10e70 74 65 78 65 73 20 6f 72 20 69 6e 69 74 69 61 6c  texes or initial
10e80 69 7a 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74  ize internal dat
10e90 61 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 73 2e  a.** structures.
10ea0 20 20 54 68 65 20 78 53 68 75 74 64 6f 77 6e 20    The xShutdown 
10eb0 6d 65 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65  method is invoke
10ec0 64 20 28 69 6e 64 69 72 65 63 74 6c 79 29 20 62  d (indirectly) b
10ed0 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68  y.** [sqlite3_sh
10ee0 75 74 64 6f 77 6e 28 29 5d 20 61 6e 64 20 73 68  utdown()] and sh
10ef0 6f 75 6c 64 20 64 65 61 6c 6c 6f 63 61 74 65 20  ould deallocate 
10f00 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20 61 63  any resources ac
10f10 71 75 69 72 65 64 0a 2a 2a 20 62 79 20 78 49 6e  quired.** by xIn
10f20 69 74 2e 20 20 54 68 65 20 70 41 70 70 44 61 74  it.  The pAppDat
10f30 61 20 70 6f 69 6e 74 65 72 20 69 73 20 75 73 65  a pointer is use
10f40 64 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 61  d as the only pa
10f50 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 78 49  rameter to.** xI
10f60 6e 69 74 20 61 6e 64 20 78 53 68 75 74 64 6f 77  nit and xShutdow
10f70 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  n..**.** SQLite 
10f80 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 54  holds the [SQLIT
10f90 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d  E_MUTEX_STATIC_M
10fa0 41 53 54 45 52 5d 20 6d 75 74 65 78 20 77 68 65  ASTER] mutex whe
10fb0 6e 20 69 74 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20  n it invokes.** 
10fc0 74 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64  the xInit method
10fd0 2c 20 73 6f 20 74 68 65 20 78 49 6e 69 74 20 6d  , so the xInit m
10fe0 65 74 68 6f 64 20 6e 65 65 64 20 6e 6f 74 20 62  ethod need not b
10ff0 65 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 54  e threadsafe.  T
11000 68 65 0a 2a 2a 20 78 53 68 75 74 64 6f 77 6e 20  he.** xShutdown 
11010 6d 65 74 68 6f 64 20 69 73 20 6f 6e 6c 79 20 63  method is only c
11020 61 6c 6c 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  alled from [sqli
11030 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20  te3_shutdown()] 
11040 73 6f 20 69 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f  so it does.** no
11050 74 20 6e 65 65 64 20 74 6f 20 62 65 20 74 68 72  t need to be thr
11060 65 61 64 73 61 66 65 20 65 69 74 68 65 72 2e 20  eadsafe either. 
11070 20 46 6f 72 20 61 6c 6c 20 6f 74 68 65 72 20 6d   For all other m
11080 65 74 68 6f 64 73 2c 20 53 51 4c 69 74 65 0a 2a  ethods, SQLite.*
11090 2a 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c  * holds the [SQL
110a0 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43  ITE_MUTEX_STATIC
110b0 5f 4d 45 4d 5d 20 6d 75 74 65 78 20 61 73 20 6c  _MEM] mutex as l
110c0 6f 6e 67 20 61 73 20 74 68 65 0a 2a 2a 20 5b 53  ong as the.** [S
110d0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d  QLITE_CONFIG_MEM
110e0 53 54 41 54 55 53 5d 20 63 6f 6e 66 69 67 75 72  STATUS] configur
110f0 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20  ation option is 
11100 74 75 72 6e 65 64 20 6f 6e 20 28 77 68 69 63 68  turned on (which
11110 0a 2a 2a 20 69 74 20 69 73 20 62 79 20 64 65 66  .** it is by def
11120 61 75 6c 74 29 20 61 6e 64 20 73 6f 20 74 68 65  ault) and so the
11130 20 6d 65 74 68 6f 64 73 20 61 72 65 20 61 75 74   methods are aut
11140 6f 6d 61 74 69 63 61 6c 6c 79 20 73 65 72 69 61  omatically seria
11150 6c 69 7a 65 64 2e 0a 2a 2a 20 48 6f 77 65 76 65  lized..** Howeve
11160 72 2c 20 69 66 20 5b 53 51 4c 49 54 45 5f 43 4f  r, if [SQLITE_CO
11170 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20  NFIG_MEMSTATUS] 
11180 69 73 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65  is disabled, the
11190 6e 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 6d  n the other.** m
111a0 65 74 68 6f 64 73 20 6d 75 73 74 20 62 65 20 74  ethods must be t
111b0 68 72 65 61 64 73 61 66 65 20 6f 72 20 65 6c 73  hreadsafe or els
111c0 65 20 6d 61 6b 65 20 74 68 65 69 72 20 6f 77 6e  e make their own
111d0 20 61 72 72 61 6e 67 65 6d 65 6e 74 73 20 66 6f   arrangements fo
111e0 72 0a 2a 2a 20 73 65 72 69 61 6c 69 7a 61 74 69  r.** serializati
111f0 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  on..**.** SQLite
11200 20 77 69 6c 6c 20 6e 65 76 65 72 20 69 6e 76 6f   will never invo
11210 6b 65 20 78 49 6e 69 74 28 29 20 6d 6f 72 65 20  ke xInit() more 
11220 74 68 61 6e 20 6f 6e 63 65 20 77 69 74 68 6f 75  than once withou
11230 74 20 61 6e 20 69 6e 74 65 72 76 65 6e 69 6e 67  t an intervening
11240 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 78 53 68 75  .** call to xShu
11250 74 64 6f 77 6e 28 29 2e 0a 2a 2f 0a 74 79 70 65  tdown()..*/.type
11260 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
11270 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 73  e3_mem_methods s
11280 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
11290 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74  ds;.struct sqlit
112a0 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 7b  e3_mem_methods {
112b0 0a 20 20 76 6f 69 64 20 2a 28 2a 78 4d 61 6c 6c  .  void *(*xMall
112c0 6f 63 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20  oc)(int);       
112d0 20 20 2f 2a 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f    /* Memory allo
112e0 63 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 20  cation function 
112f0 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 46 72 65  */.  void (*xFre
11300 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20  e)(void*);      
11310 20 20 20 20 2f 2a 20 46 72 65 65 20 61 20 70 72      /* Free a pr
11320 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a  ior allocation *
11330 2f 0a 20 20 76 6f 69 64 20 2a 28 2a 78 52 65 61  /.  void *(*xRea
11340 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c 69 6e 74 29  lloc)(void*,int)
11350 3b 20 20 2f 2a 20 52 65 73 69 7a 65 20 61 6e 20  ;  /* Resize an 
11360 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20  allocation */.  
11370 69 6e 74 20 28 2a 78 53 69 7a 65 29 28 76 6f 69  int (*xSize)(voi
11380 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f  d*);           /
11390 2a 20 52 65 74 75 72 6e 20 74 68 65 20 73 69 7a  * Return the siz
113a0 65 20 6f 66 20 61 6e 20 61 6c 6c 6f 63 61 74 69  e of an allocati
113b0 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 52  on */.  int (*xR
113c0 6f 75 6e 64 75 70 29 28 69 6e 74 29 3b 20 20 20  oundup)(int);   
113d0 20 20 20 20 20 20 20 2f 2a 20 52 6f 75 6e 64 20         /* Round 
113e0 75 70 20 72 65 71 75 65 73 74 20 73 69 7a 65 20  up request size 
113f0 74 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69  to allocation si
11400 7a 65 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 49  ze */.  int (*xI
11410 6e 69 74 29 28 76 6f 69 64 2a 29 3b 20 20 20 20  nit)(void*);    
11420 20 20 20 20 20 20 20 2f 2a 20 49 6e 69 74 69 61         /* Initia
11430 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20  lize the memory 
11440 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76  allocator */.  v
11450 6f 69 64 20 28 2a 78 53 68 75 74 64 6f 77 6e 29  oid (*xShutdown)
11460 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 2f 2a  (void*);      /*
11470 20 44 65 69 6e 69 74 69 61 6c 69 7a 65 20 74 68   Deinitialize th
11480 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
11490 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41  or */.  void *pA
114a0 70 70 44 61 74 61 3b 20 20 20 20 20 20 20 20 20  ppData;         
114b0 20 20 20 20 20 20 20 2f 2a 20 41 72 67 75 6d 65         /* Argume
114c0 6e 74 20 74 6f 20 78 49 6e 69 74 28 29 20 61 6e  nt to xInit() an
114d0 64 20 78 53 68 75 74 64 6f 77 6e 28 29 20 2a 2f  d xShutdown() */
114e0 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .};../*.** CAPI3
114f0 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 61 74 69  REF: Configurati
11500 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 20 4b 45  on Options.** KE
11510 59 57 4f 52 44 53 3a 20 7b 63 6f 6e 66 69 67 75  YWORDS: {configu
11520 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 7d 0a 2a  ration option}.*
11530 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74  *.** These const
11540 61 6e 74 73 20 61 72 65 20 74 68 65 20 61 76 61  ants are the ava
11550 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63  ilable integer c
11560 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
11570 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e  ions that.** can
11580 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68   be passed as th
11590 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
115a0 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
115b0 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72  _config()] inter
115c0 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20  face..**.** New 
115d0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
115e0 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64  tions may be add
115f0 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  ed in future rel
11600 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e  eases of SQLite.
11610 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e  .** Existing con
11620 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
11630 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69 73 63  ns might be disc
11640 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69  ontinued.  Appli
11650 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c  cations.** shoul
11660 64 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75  d check the retu
11670 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71  rn code from [sq
11680 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
11690 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61  to make sure tha
116a0 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f  t.** the call wo
116b0 72 6b 65 64 2e 20 20 54 68 65 20 5b 73 71 6c 69  rked.  The [sqli
116c0 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e  te3_config()] in
116d0 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74  terface will ret
116e0 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72  urn a.** non-zer
116f0 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  o [error code] i
11700 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64  f a discontinued
11710 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20   or unsupported 
11720 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
11730 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b  tion.** is invok
11740 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a  ed..**.** <dl>.*
11750 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
11760 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 5d  G_SINGLETHREAD]]
11770 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
11780 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 3c  IG_SINGLETHREAD<
11790 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72  /dt>.** <dd>Ther
117a0 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e  e are no argumen
117b0 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f  ts to this optio
117c0 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  n.  ^This option
117d0 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68   sets the.** [th
117e0 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f  reading mode] to
117f0 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 2e 20   Single-thread. 
11800 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
11810 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20   it disables.** 
11820 61 6c 6c 20 6d 75 74 65 78 69 6e 67 20 61 6e 64  all mutexing and
11830 20 70 75 74 73 20 53 51 4c 69 74 65 20 69 6e 74   puts SQLite int
11840 6f 20 61 20 6d 6f 64 65 20 77 68 65 72 65 20 69  o a mode where i
11850 74 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 75 73  t can only be us
11860 65 64 0a 2a 2a 20 62 79 20 61 20 73 69 6e 67 6c  ed.** by a singl
11870 65 20 74 68 72 65 61 64 2e 20 20 20 5e 49 66 20  e thread.   ^If 
11880 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
11890 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b  ed with.** the [
118a0 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
118b0 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41  E | SQLITE_THREA
118c0 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65  DSAFE=0] compile
118d0 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65  -time option the
118e0 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70  n.** it is not p
118f0 6f 73 73 69 62 6c 65 20 74 6f 20 63 68 61 6e 67  ossible to chang
11900 65 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e 67  e the [threading
11910 20 6d 6f 64 65 5d 20 66 72 6f 6d 20 69 74 73 20   mode] from its 
11920 64 65 66 61 75 6c 74 0a 2a 2a 20 76 61 6c 75 65  default.** value
11930 20 6f 66 20 53 69 6e 67 6c 65 2d 74 68 72 65 61   of Single-threa
11940 64 20 61 6e 64 20 73 6f 20 5b 73 71 6c 69 74 65  d and so [sqlite
11950 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c  3_config()] will
11960 20 72 65 74 75 72 6e 20 0a 2a 2a 20 5b 53 51 4c   return .** [SQL
11970 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61  ITE_ERROR] if ca
11980 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 53 51  lled with the SQ
11990 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
119a0 4c 45 54 48 52 45 41 44 0a 2a 2a 20 63 6f 6e 66  LETHREAD.** conf
119b0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
119c0 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  .</dd>.**.** [[S
119d0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c  QLITE_CONFIG_MUL
119e0 54 49 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53  TITHREAD]] <dt>S
119f0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c  QLITE_CONFIG_MUL
11a00 54 49 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a  TITHREAD</dt>.**
11a10 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e   <dd>There are n
11a20 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74  o arguments to t
11a30 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68  his option.  ^Th
11a40 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74  is option sets t
11a50 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67  he.** [threading
11a60 20 6d 6f 64 65 5d 20 74 6f 20 4d 75 6c 74 69 2d   mode] to Multi-
11a70 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68 65  thread.  In othe
11a80 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73 61  r words, it disa
11a90 62 6c 65 73 0a 2a 2a 20 6d 75 74 65 78 69 6e 67  bles.** mutexing
11aa0 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f   on [database co
11ab0 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70  nnection] and [p
11ac0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
11ad0 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 54  t] objects..** T
11ae0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69  he application i
11af0 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f  s responsible fo
11b00 72 20 73 65 72 69 61 6c 69 7a 69 6e 67 20 61 63  r serializing ac
11b10 63 65 73 73 20 74 6f 0a 2a 2a 20 5b 64 61 74 61  cess to.** [data
11b20 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
11b30 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20  ] and [prepared 
11b40 73 74 61 74 65 6d 65 6e 74 73 5d 2e 20 20 42 75  statements].  Bu
11b50 74 20 6f 74 68 65 72 20 6d 75 74 65 78 65 73 0a  t other mutexes.
11b60 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20 73  ** are enabled s
11b70 6f 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69  o that SQLite wi
11b80 6c 6c 20 62 65 20 73 61 66 65 20 74 6f 20 75 73  ll be safe to us
11b90 65 20 69 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72  e in a multi-thr
11ba0 65 61 64 65 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e  eaded.** environ
11bb0 6d 65 6e 74 20 61 73 20 6c 6f 6e 67 20 61 73 20  ment as long as 
11bc0 6e 6f 20 74 77 6f 20 74 68 72 65 61 64 73 20 61  no two threads a
11bd0 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68  ttempt to use th
11be0 65 20 73 61 6d 65 0a 2a 2a 20 5b 64 61 74 61 62  e same.** [datab
11bf0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
11c00 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65  at the same time
11c10 2e 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73  .  ^If SQLite is
11c20 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
11c30 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48  * the [SQLITE_TH
11c40 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54  READSAFE | SQLIT
11c50 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20  E_THREADSAFE=0] 
11c60 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
11c70 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69  ion then.** it i
11c80 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74  s not possible t
11c90 6f 20 73 65 74 20 74 68 65 20 4d 75 6c 74 69 2d  o set the Multi-
11ca0 74 68 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e  thread [threadin
11cb0 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b  g mode] and.** [
11cc0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
11cd0 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53  ] will return [S
11ce0 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20  QLITE_ERROR] if 
11cf0 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a  called with the.
11d00 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ** SQLITE_CONFIG
11d10 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 63 6f 6e  _MULTITHREAD con
11d20 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
11d30 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  n.</dd>.**.** [[
11d40 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45  SQLITE_CONFIG_SE
11d50 52 49 41 4c 49 5a 45 44 5d 5d 20 3c 64 74 3e 53  RIALIZED]] <dt>S
11d60 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52  QLITE_CONFIG_SER
11d70 49 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a 2a 2a 20  IALIZED</dt>.** 
11d80 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f  <dd>There are no
11d90 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68   arguments to th
11da0 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69  is option.  ^Thi
11db0 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68  s option sets th
11dc0 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20  e.** [threading 
11dd0 6d 6f 64 65 5d 20 74 6f 20 53 65 72 69 61 6c 69  mode] to Seriali
11de0 7a 65 64 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f  zed. In other wo
11df0 72 64 73 2c 20 74 68 69 73 20 6f 70 74 69 6f 6e  rds, this option
11e00 20 65 6e 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20   enables.** all 
11e10 6d 75 74 65 78 65 73 20 69 6e 63 6c 75 64 69 6e  mutexes includin
11e20 67 20 74 68 65 20 72 65 63 75 72 73 69 76 65 0a  g the recursive.
11e30 2a 2a 20 6d 75 74 65 78 65 73 20 6f 6e 20 5b 64  ** mutexes on [d
11e40 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
11e50 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65  on] and [prepare
11e60 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a  d statement] obj
11e70 65 63 74 73 2e 0a 2a 2a 20 49 6e 20 74 68 69 73  ects..** In this
11e80 20 6d 6f 64 65 20 28 77 68 69 63 68 20 69 73 20   mode (which is 
11e90 74 68 65 20 64 65 66 61 75 6c 74 20 77 68 65 6e  the default when
11ea0 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
11eb0 6c 65 64 20 77 69 74 68 0a 2a 2a 20 5b 53 51 4c  led with.** [SQL
11ec0 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31  ITE_THREADSAFE=1
11ed0 5d 29 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69  ]) the SQLite li
11ee0 62 72 61 72 79 20 77 69 6c 6c 20 69 74 73 65 6c  brary will itsel
11ef0 66 20 73 65 72 69 61 6c 69 7a 65 20 61 63 63 65  f serialize acce
11f00 73 73 0a 2a 2a 20 74 6f 20 5b 64 61 74 61 62 61  ss.** to [databa
11f10 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20  se connections] 
11f20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  and [prepared st
11f30 61 74 65 6d 65 6e 74 73 5d 20 73 6f 20 74 68 61  atements] so tha
11f40 74 20 74 68 65 0a 2a 2a 20 61 70 70 6c 69 63 61  t the.** applica
11f50 74 69 6f 6e 20 69 73 20 66 72 65 65 20 74 6f 20  tion is free to 
11f60 75 73 65 20 74 68 65 20 73 61 6d 65 20 5b 64 61  use the same [da
11f70 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
11f80 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a 20 73 61 6d  n] or the.** sam
11f90 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
11fa0 65 6d 65 6e 74 5d 20 69 6e 20 64 69 66 66 65 72  ement] in differ
11fb0 65 6e 74 20 74 68 72 65 61 64 73 20 61 74 20 74  ent threads at t
11fc0 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 0a 2a 2a  he same time..**
11fd0 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63   ^If SQLite is c
11fe0 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
11ff0 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
12000 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f  ADSAFE | SQLITE_
12010 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f  THREADSAFE=0] co
12020 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
12030 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20  n then.** it is 
12040 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20  not possible to 
12050 73 65 74 20 74 68 65 20 53 65 72 69 61 6c 69 7a  set the Serializ
12060 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ed [threading mo
12070 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  de] and.** [sqli
12080 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69  te3_config()] wi
12090 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ll return [SQLIT
120a0 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c  E_ERROR] if call
120b0 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53  ed with the.** S
120c0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52  QLITE_CONFIG_SER
120d0 49 41 4c 49 5a 45 44 20 63 6f 6e 66 69 67 75 72  IALIZED configur
120e0 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64  ation option.</d
120f0 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
12100 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d  E_CONFIG_MALLOC]
12110 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
12120 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a  FIG_MALLOC</dt>.
12130 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f  ** <dd> ^(This o
12140 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
12150 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
12160 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ich is a pointer
12170 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e   to an.** instan
12180 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ce of the [sqlit
12190 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20  e3_mem_methods] 
121a0 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 20  structure.  The 
121b0 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69  argument specifi
121c0 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76  es.** alternativ
121d0 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f  e low-level memo
121e0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f  ry allocation ro
121f0 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65  utines to be use
12200 64 20 69 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a  d in place of.**
12210 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   the memory allo
12220 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20  cation routines 
12230 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74  built into SQLit
12240 65 2e 29 5e 20 5e 53 51 4c 69 74 65 20 6d 61 6b  e.)^ ^SQLite mak
12250 65 73 0a 2a 2a 20 69 74 73 20 6f 77 6e 20 70 72  es.** its own pr
12260 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68  ivate copy of th
12270 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65  e content of the
12280 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65   [sqlite3_mem_me
12290 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65  thods] structure
122a0 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68 65 20 5b  .** before the [
122b0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
122c0 5d 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e 3c  ] call returns.<
122d0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
122e0 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41  ITE_CONFIG_GETMA
122f0 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  LLOC]] <dt>SQLIT
12300 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c  E_CONFIG_GETMALL
12310 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  OC</dt>.** <dd> 
12320 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61  ^(This option ta
12330 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
12340 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61  ument which is a
12350 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a   pointer to an.*
12360 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  * instance of th
12370 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  e [sqlite3_mem_m
12380 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72  ethods] structur
12390 65 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33  e.  The [sqlite3
123a0 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a  _mem_methods].**
123b0 20 73 74 72 75 63 74 75 72 65 20 69 73 20 66 69   structure is fi
123c0 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 63 75  lled with the cu
123d0 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20  rrently defined 
123e0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
123f0 6e 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a  n routines.)^.**
12400 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e   This option can
12410 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72   be used to over
12420 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c 74  load the default
12430 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
12440 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77  on.** routines w
12450 69 74 68 20 61 20 77 72 61 70 70 65 72 20 74 68  ith a wrapper th
12460 61 74 20 73 69 6d 75 6c 61 74 69 6f 6e 73 20 6d  at simulations m
12470 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
12480 20 66 61 69 6c 75 72 65 20 6f 72 0a 2a 2a 20 74   failure or.** t
12490 72 61 63 6b 73 20 6d 65 6d 6f 72 79 20 75 73 61  racks memory usa
124a0 67 65 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e  ge, for example.
124b0 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53   </dd>.**.** [[S
124c0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d  QLITE_CONFIG_MEM
124d0 53 54 41 54 55 53 5d 5d 20 3c 64 74 3e 53 51 4c  STATUS]] <dt>SQL
124e0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54  ITE_CONFIG_MEMST
124f0 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  ATUS</dt>.** <dd
12500 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74  > ^This option t
12510 61 6b 65 73 20 73 69 6e 67 6c 65 20 61 72 67 75  akes single argu
12520 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e 74  ment of type int
12530 2c 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  , interpreted as
12540 20 61 20 0a 2a 2a 20 62 6f 6f 6c 65 61 6e 2c 20   a .** boolean, 
12550 77 68 69 63 68 20 65 6e 61 62 6c 65 73 20 6f 72  which enables or
12560 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 63 6f   disables the co
12570 6c 6c 65 63 74 69 6f 6e 20 6f 66 20 6d 65 6d 6f  llection of memo
12580 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 0a 2a  ry allocation .*
12590 2a 20 73 74 61 74 69 73 74 69 63 73 2e 20 5e 28  * statistics. ^(
125a0 57 68 65 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  When memory allo
125b0 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63  cation statistic
125c0 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 2c 20  s are disabled, 
125d0 74 68 65 20 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e  the .** followin
125e0 67 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  g SQLite interfa
125f0 63 65 73 20 62 65 63 6f 6d 65 20 6e 6f 6e 2d 6f  ces become non-o
12600 70 65 72 61 74 69 6f 6e 61 6c 3a 0a 2a 2a 20 20  perational:.**  
12610 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20   <ul>.**   <li> 
12620 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
12630 75 73 65 64 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69  used()].**   <li
12640 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  > [sqlite3_memor
12650 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 0a 2a  y_highwater()].*
12660 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65  *   <li> [sqlite
12670 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69  3_soft_heap_limi
12680 74 36 34 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e  t64()].**   <li>
12690 20 5b 73 71 6c 69 74 65 33 5f 73 74 61 74 75 73   [sqlite3_status
126a0 28 29 5d 0a 2a 2a 20 20 20 3c 2f 75 6c 3e 29 5e  ()].**   </ul>)^
126b0 0a 2a 2a 20 5e 4d 65 6d 6f 72 79 20 61 6c 6c 6f  .** ^Memory allo
126c0 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63  cation statistic
126d0 73 20 61 72 65 20 65 6e 61 62 6c 65 64 20 62 79  s are enabled by
126e0 20 64 65 66 61 75 6c 74 20 75 6e 6c 65 73 73 20   default unless 
126f0 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 63 6f 6d  SQLite is.** com
12700 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c 49  piled with [SQLI
12710 54 45 5f 44 45 46 41 55 4c 54 5f 4d 45 4d 53 54  TE_DEFAULT_MEMST
12720 41 54 55 53 5d 3d 30 20 69 6e 20 77 68 69 63 68  ATUS]=0 in which
12730 20 63 61 73 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20   case memory.** 
12740 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69  allocation stati
12750 73 74 69 63 73 20 61 72 65 20 64 69 73 61 62 6c  stics are disabl
12760 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a  ed by default..*
12770 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  * </dd>.**.** [[
12780 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43  SQLITE_CONFIG_SC
12790 52 41 54 43 48 5d 5d 20 3c 64 74 3e 53 51 4c 49  RATCH]] <dt>SQLI
127a0 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43  TE_CONFIG_SCRATC
127b0 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  H</dt>.** <dd> ^
127c0 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63  This option spec
127d0 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d  ifies a static m
127e0 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68 61  emory buffer tha
127f0 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65  t SQLite can use
12800 20 66 6f 72 0a 2a 2a 20 73 63 72 61 74 63 68 20   for.** scratch 
12810 6d 65 6d 6f 72 79 2e 20 20 54 68 65 72 65 20 61  memory.  There a
12820 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e  re three argumen
12830 74 73 3a 20 20 41 20 70 6f 69 6e 74 65 72 20 61  ts:  A pointer a
12840 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 61 6c 69 67  n 8-byte.** alig
12850 6e 65 64 20 6d 65 6d 6f 72 79 20 62 75 66 66 65  ned memory buffe
12860 72 20 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65  r from which the
12870 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74   scratch allocat
12880 69 6f 6e 73 20 77 69 6c 6c 20 62 65 0a 2a 2a 20  ions will be.** 
12890 64 72 61 77 6e 2c 20 74 68 65 20 73 69 7a 65 20  drawn, the size 
128a0 6f 66 20 65 61 63 68 20 73 63 72 61 74 63 68 20  of each scratch 
128b0 61 6c 6c 6f 63 61 74 69 6f 6e 20 28 73 7a 29 2c  allocation (sz),
128c0 0a 2a 2a 20 61 6e 64 20 74 68 65 20 6d 61 78 69  .** and the maxi
128d0 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 73 63  mum number of sc
128e0 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e  ratch allocation
128f0 73 20 28 4e 29 2e 20 20 54 68 65 20 73 7a 0a 2a  s (N).  The sz.*
12900 2a 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20  * argument must 
12910 62 65 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66  be a multiple of
12920 20 31 36 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73   16..** The firs
12930 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20  t argument must 
12940 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  be a pointer to 
12950 61 6e 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65  an 8-byte aligne
12960 64 20 62 75 66 66 65 72 0a 2a 2a 20 6f 66 20 61  d buffer.** of a
12970 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74  t least sz*N byt
12980 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a  es of memory..**
12990 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73   ^SQLite will us
129a0 65 20 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 20 74  e no more than t
129b0 77 6f 20 73 63 72 61 74 63 68 20 62 75 66 66 65  wo scratch buffe
129c0 72 73 20 70 65 72 20 74 68 72 65 61 64 2e 20 20  rs per thread.  
129d0 53 6f 0a 2a 2a 20 4e 20 73 68 6f 75 6c 64 20 62  So.** N should b
129e0 65 20 73 65 74 20 74 6f 20 74 77 69 63 65 20 74  e set to twice t
129f0 68 65 20 65 78 70 65 63 74 65 64 20 6d 61 78 69  he expected maxi
12a00 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 68  mum number of th
12a10 72 65 61 64 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74  reads..** ^SQLit
12a20 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 72 65 71  e will never req
12a30 75 69 72 65 20 61 20 73 63 72 61 74 63 68 20 62  uire a scratch b
12a40 75 66 66 65 72 20 74 68 61 74 20 69 73 20 6d 6f  uffer that is mo
12a50 72 65 20 74 68 61 6e 20 36 0a 2a 2a 20 74 69 6d  re than 6.** tim
12a60 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  es the database 
12a70 70 61 67 65 20 73 69 7a 65 2e 20 5e 49 66 20 53  page size. ^If S
12a80 51 4c 69 74 65 20 6e 65 65 64 73 20 6e 65 65 64  QLite needs need
12a90 73 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  s additional.** 
12aa0 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 20 62  scratch memory b
12ab0 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72  eyond what is pr
12ac0 6f 76 69 64 65 64 20 62 79 20 74 68 69 73 20 63  ovided by this c
12ad0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
12ae0 69 6f 6e 2c 20 74 68 65 6e 20 0a 2a 2a 20 5b 73  ion, then .** [s
12af0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
12b00 20 77 69 6c 6c 20 62 65 20 75 73 65 64 20 74 6f   will be used to
12b10 20 6f 62 74 61 69 6e 20 74 68 65 20 6d 65 6d 6f   obtain the memo
12b20 72 79 20 6e 65 65 64 65 64 2e 3c 2f 64 64 3e 0a  ry needed.</dd>.
12b30 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
12b40 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d  ONFIG_PAGECACHE]
12b50 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
12b60 46 49 47 5f 50 41 47 45 43 41 43 48 45 3c 2f 64  FIG_PAGECACHE</d
12b70 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73  t>.** <dd> ^This
12b80 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65   option specifie
12b90 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72  s a static memor
12ba0 79 20 62 75 66 66 65 72 20 74 68 61 74 20 53 51  y buffer that SQ
12bb0 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72  Lite can use for
12bc0 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65  .** the database
12bd0 20 70 61 67 65 20 63 61 63 68 65 20 77 69 74 68   page cache with
12be0 20 74 68 65 20 64 65 66 61 75 6c 74 20 70 61 67   the default pag
12bf0 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e  e cache implemen
12c00 74 61 74 69 6f 6e 2e 20 20 0a 2a 2a 20 54 68 69  tation.  .** Thi
12c10 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  s configuration 
12c20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75 73  should not be us
12c30 65 64 20 69 66 20 61 6e 20 61 70 70 6c 69 63 61  ed if an applica
12c40 74 69 6f 6e 2d 64 65 66 69 6e 65 20 70 61 67 65  tion-define page
12c50 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70 6c 65 6d  .** cache implem
12c60 65 6e 74 61 74 69 6f 6e 20 69 73 20 6c 6f 61 64  entation is load
12c70 65 64 20 75 73 69 6e 67 20 74 68 65 20 53 51 4c  ed using the SQL
12c80 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48  ITE_CONFIG_PCACH
12c90 45 32 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 54 68  E2 option..** Th
12ca0 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72  ere are three ar
12cb0 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20  guments to this 
12cc0 6f 70 74 69 6f 6e 3a 20 41 20 70 6f 69 6e 74 65  option: A pointe
12cd0 72 20 74 6f 20 38 2d 62 79 74 65 20 61 6c 69 67  r to 8-byte alig
12ce0 6e 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 74  ned.** memory, t
12cf0 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20  he size of each 
12d00 70 61 67 65 20 62 75 66 66 65 72 20 28 73 7a 29  page buffer (sz)
12d10 2c 20 61 6e 64 20 74 68 65 20 6e 75 6d 62 65 72  , and the number
12d20 20 6f 66 20 70 61 67 65 73 20 28 4e 29 2e 0a 2a   of pages (N)..*
12d30 2a 20 54 68 65 20 73 7a 20 61 72 67 75 6d 65 6e  * The sz argumen
12d40 74 20 73 68 6f 75 6c 64 20 62 65 20 74 68 65 20  t should be the 
12d50 73 69 7a 65 20 6f 66 20 74 68 65 20 6c 61 72 67  size of the larg
12d60 65 73 74 20 64 61 74 61 62 61 73 65 20 70 61 67  est database pag
12d70 65 0a 2a 2a 20 28 61 20 70 6f 77 65 72 20 6f 66  e.** (a power of
12d80 20 74 77 6f 20 62 65 74 77 65 65 6e 20 35 31 32   two between 512
12d90 20 61 6e 64 20 33 32 37 36 38 29 20 70 6c 75 73   and 32768) plus
12da0 20 61 20 6c 69 74 74 6c 65 20 65 78 74 72 61 20   a little extra 
12db0 66 6f 72 20 65 61 63 68 0a 2a 2a 20 70 61 67 65  for each.** page
12dc0 20 68 65 61 64 65 72 2e 20 20 5e 54 68 65 20 70   header.  ^The p
12dd0 61 67 65 20 68 65 61 64 65 72 20 73 69 7a 65 20  age header size 
12de0 69 73 20 32 30 20 74 6f 20 34 30 20 62 79 74 65  is 20 to 40 byte
12df0 73 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 0a 2a  s depending on.*
12e00 2a 20 74 68 65 20 68 6f 73 74 20 61 72 63 68 69  * the host archi
12e10 74 65 63 74 75 72 65 2e 20 20 5e 49 74 20 69 73  tecture.  ^It is
12e20 20 68 61 72 6d 6c 65 73 73 2c 20 61 70 61 72 74   harmless, apart
12e30 20 66 72 6f 6d 20 74 68 65 20 77 61 73 74 65 64   from the wasted
12e40 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74 6f 20 6d   memory,.** to m
12e50 61 6b 65 20 73 7a 20 61 20 6c 69 74 74 6c 65 20  ake sz a little 
12e60 74 6f 6f 20 6c 61 72 67 65 2e 20 20 54 68 65 20  too large.  The 
12e70 66 69 72 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e  first.** argumen
12e80 74 20 73 68 6f 75 6c 64 20 70 6f 69 6e 74 20 74  t should point t
12e90 6f 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  o an allocation 
12ea0 6f 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e  of at least sz*N
12eb0 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79   bytes of memory
12ec0 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c  ..** ^SQLite wil
12ed0 6c 20 75 73 65 20 74 68 65 20 6d 65 6d 6f 72 79  l use the memory
12ee0 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 65   provided by the
12ef0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
12f00 74 6f 20 73 61 74 69 73 66 79 20 69 74 73 0a 2a  to satisfy its.*
12f10 2a 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 20 66  * memory needs f
12f20 6f 72 20 74 68 65 20 66 69 72 73 74 20 4e 20 70  or the first N p
12f30 61 67 65 73 20 74 68 61 74 20 69 74 20 61 64 64  ages that it add
12f40 73 20 74 6f 20 63 61 63 68 65 2e 20 20 5e 49 66  s to cache.  ^If
12f50 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 70   additional.** p
12f60 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79  age cache memory
12f70 20 69 73 20 6e 65 65 64 65 64 20 62 65 79 6f 6e   is needed beyon
12f80 64 20 77 68 61 74 20 69 73 20 70 72 6f 76 69 64  d what is provid
12f90 65 64 20 62 79 20 74 68 69 73 20 6f 70 74 69 6f  ed by this optio
12fa0 6e 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74  n, then.** SQLit
12fb0 65 20 67 6f 65 73 20 74 6f 20 5b 73 71 6c 69 74  e goes to [sqlit
12fc0 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 66 6f 72  e3_malloc()] for
12fd0 20 74 68 65 20 61 64 64 69 74 69 6f 6e 61 6c 20   the additional 
12fe0 73 74 6f 72 61 67 65 20 73 70 61 63 65 2e 0a 2a  storage space..*
12ff0 2a 20 54 68 65 20 70 6f 69 6e 74 65 72 20 69 6e  * The pointer in
13000 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
13010 65 6e 74 20 6d 75 73 74 0a 2a 2a 20 62 65 20 61  ent must.** be a
13020 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62  ligned to an 8-b
13030 79 74 65 20 62 6f 75 6e 64 61 72 79 20 6f 72 20  yte boundary or 
13040 73 75 62 73 65 71 75 65 6e 74 20 62 65 68 61 76  subsequent behav
13050 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a  ior of SQLite.**
13060 20 77 69 6c 6c 20 62 65 20 75 6e 64 65 66 69 6e   will be undefin
13070 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  ed.</dd>.**.** [
13080 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48  [SQLITE_CONFIG_H
13090 45 41 50 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  EAP]] <dt>SQLITE
130a0 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3c 2f 64 74  _CONFIG_HEAP</dt
130b0 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20  >.** <dd> ^This 
130c0 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73  option specifies
130d0 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79   a static memory
130e0 20 62 75 66 66 65 72 20 74 68 61 74 20 53 51 4c   buffer that SQL
130f0 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20  ite will use.** 
13100 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 64  for all of its d
13110 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 61 6c  ynamic memory al
13120 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 20 62  location needs b
13130 65 79 6f 6e 64 20 74 68 6f 73 65 20 70 72 6f 76  eyond those prov
13140 69 64 65 64 0a 2a 2a 20 66 6f 72 20 62 79 20 5b  ided.** for by [
13150 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43  SQLITE_CONFIG_SC
13160 52 41 54 43 48 5d 20 61 6e 64 20 5b 53 51 4c 49  RATCH] and [SQLI
13170 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41  TE_CONFIG_PAGECA
13180 43 48 45 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 61  CHE]..** There a
13190 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e  re three argumen
131a0 74 73 3a 20 41 6e 20 38 2d 62 79 74 65 20 61 6c  ts: An 8-byte al
131b0 69 67 6e 65 64 20 70 6f 69 6e 74 65 72 20 74 6f  igned pointer to
131c0 20 74 68 65 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20   the memory,.** 
131d0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
131e0 74 65 73 20 69 6e 20 74 68 65 20 6d 65 6d 6f 72  tes in the memor
131f0 79 20 62 75 66 66 65 72 2c 20 61 6e 64 20 74 68  y buffer, and th
13200 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61  e minimum alloca
13210 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49  tion size..** ^I
13220 66 20 74 68 65 20 66 69 72 73 74 20 70 6f 69 6e  f the first poin
13230 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20  ter (the memory 
13240 70 6f 69 6e 74 65 72 29 20 69 73 20 4e 55 4c 4c  pointer) is NULL
13250 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 72 65  , then SQLite re
13260 76 65 72 74 73 0a 2a 2a 20 74 6f 20 75 73 69 6e  verts.** to usin
13270 67 20 69 74 73 20 64 65 66 61 75 6c 74 20 6d 65  g its default me
13280 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 28  mory allocator (
13290 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f  the system mallo
132a0 63 28 29 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  c() implementati
132b0 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f 69 6e 67 20  on),.** undoing 
132c0 61 6e 79 20 70 72 69 6f 72 20 69 6e 76 6f 63 61  any prior invoca
132d0 74 69 6f 6e 20 6f 66 20 5b 53 51 4c 49 54 45 5f  tion of [SQLITE_
132e0 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 2e 20  CONFIG_MALLOC]. 
132f0 20 5e 49 66 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f   ^If the.** memo
13300 72 79 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f  ry pointer is no
13310 74 20 4e 55 4c 4c 20 61 6e 64 20 65 69 74 68 65  t NULL and eithe
13320 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  r [SQLITE_ENABLE
13330 5f 4d 45 4d 53 59 53 33 5d 20 6f 72 0a 2a 2a 20  _MEMSYS3] or.** 
13340 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d  [SQLITE_ENABLE_M
13350 45 4d 53 59 53 35 5d 20 61 72 65 20 64 65 66 69  EMSYS5] are defi
13360 6e 65 64 2c 20 74 68 65 6e 20 74 68 65 20 61 6c  ned, then the al
13370 74 65 72 6e 61 74 69 76 65 20 6d 65 6d 6f 72 79  ternative memory
13380 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 20 69 73  .** allocator is
13390 20 65 6e 67 61 67 65 64 20 74 6f 20 68 61 6e 64   engaged to hand
133a0 6c 65 20 61 6c 6c 20 6f 66 20 53 51 4c 69 74 65  le all of SQLite
133b0 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  s memory allocat
133c0 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a 2a 20 54 68  ion needs..** Th
133d0 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20  e first pointer 
133e0 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e  (the memory poin
133f0 74 65 72 29 20 6d 75 73 74 20 62 65 20 61 6c 69  ter) must be ali
13400 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74  gned to an 8-byt
13410 65 0a 2a 2a 20 62 6f 75 6e 64 61 72 79 20 6f 72  e.** boundary or
13420 20 73 75 62 73 65 71 75 65 6e 74 20 62 65 68 61   subsequent beha
13430 76 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 20 77  vior of SQLite w
13440 69 6c 6c 20 62 65 20 75 6e 64 65 66 69 6e 65 64  ill be undefined
13450 2e 0a 2a 2a 20 54 68 65 20 6d 69 6e 69 6d 75 6d  ..** The minimum
13460 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65   allocation size
13470 20 69 73 20 63 61 70 70 65 64 20 61 74 20 32 2a   is capped at 2*
13480 2a 31 32 2e 20 52 65 61 73 6f 6e 61 62 6c 65 20  *12. Reasonable 
13490 76 61 6c 75 65 73 0a 2a 2a 20 66 6f 72 20 74 68  values.** for th
134a0 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61  e minimum alloca
134b0 74 69 6f 6e 20 73 69 7a 65 20 61 72 65 20 32 2a  tion size are 2*
134c0 2a 35 20 74 68 72 6f 75 67 68 20 32 2a 2a 38 2e  *5 through 2**8.
134d0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
134e0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45  LITE_CONFIG_MUTE
134f0 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  X]] <dt>SQLITE_C
13500 4f 4e 46 49 47 5f 4d 55 54 45 58 3c 2f 64 74 3e  ONFIG_MUTEX</dt>
13510 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20  .** <dd> ^(This 
13520 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
13530 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77  ingle argument w
13540 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65  hich is a pointe
13550 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61  r to an.** insta
13560 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  nce of the [sqli
13570 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64  te3_mutex_method
13580 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54  s] structure.  T
13590 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63  he argument spec
135a0 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61  ifies.** alterna
135b0 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d  tive low-level m
135c0 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20 74 6f  utex routines to
135d0 20 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61 63   be used in plac
135e0 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 20 72  e.** the mutex r
135f0 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e  outines built in
13600 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 20 5e 53  to SQLite.)^  ^S
13610 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f  QLite makes a co
13620 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6e  py of the.** con
13630 74 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c  tent of the [sql
13640 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
13650 64 73 5d 20 73 74 72 75 63 74 75 72 65 20 62 65  ds] structure be
13660 66 6f 72 65 20 74 68 65 20 63 61 6c 6c 20 74 6f  fore the call to
13670 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
13680 66 69 67 28 29 5d 20 72 65 74 75 72 6e 73 2e 20  fig()] returns. 
13690 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f  ^If SQLite is co
136a0 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74  mpiled with.** t
136b0 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  he [SQLITE_THREA
136c0 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54  DSAFE | SQLITE_T
136d0 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d  HREADSAFE=0] com
136e0 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
136f0 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74   then.** the ent
13700 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62  ire mutexing sub
13710 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65  system is omitte
13720 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64  d from the build
13730 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73   and hence calls
13740 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
13750 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74  config()] with t
13760 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
13770 5f 4d 55 54 45 58 20 63 6f 6e 66 69 67 75 72 61  _MUTEX configura
13780 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c  tion option will
13790 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  .** return [SQLI
137a0 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a  TE_ERROR].</dd>.
137b0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
137c0 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 5d 5d  ONFIG_GETMUTEX]]
137d0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
137e0 49 47 5f 47 45 54 4d 55 54 45 58 3c 2f 64 74 3e  IG_GETMUTEX</dt>
137f0 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20  .** <dd> ^(This 
13800 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
13810 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77  ingle argument w
13820 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65  hich is a pointe
13830 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61  r to an.** insta
13840 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  nce of the [sqli
13850 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64  te3_mutex_method
13860 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54  s] structure.  T
13870 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  he.** [sqlite3_m
13880 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a  utex_methods].**
13890 20 73 74 72 75 63 74 75 72 65 20 69 73 20 66 69   structure is fi
138a0 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 63 75  lled with the cu
138b0 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20  rrently defined 
138c0 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 2e 29  mutex routines.)
138d0 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e  ^.** This option
138e0 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
138f0 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66  overload the def
13900 61 75 6c 74 20 6d 75 74 65 78 20 61 6c 6c 6f 63  ault mutex alloc
13910 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65  ation.** routine
13920 73 20 77 69 74 68 20 61 20 77 72 61 70 70 65 72  s with a wrapper
13930 20 75 73 65 64 20 74 6f 20 74 72 61 63 6b 20 6d   used to track m
13940 75 74 65 78 20 75 73 61 67 65 20 66 6f 72 20 70  utex usage for p
13950 65 72 66 6f 72 6d 61 6e 63 65 0a 2a 2a 20 70 72  erformance.** pr
13960 6f 66 69 6c 69 6e 67 20 6f 72 20 74 65 73 74 69  ofiling or testi
13970 6e 67 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e  ng, for example.
13980 20 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73     ^If SQLite is
13990 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
139a0 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48  * the [SQLITE_TH
139b0 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54  READSAFE | SQLIT
139c0 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20  E_THREADSAFE=0] 
139d0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
139e0 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20  ion then.** the 
139f0 65 6e 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20  entire mutexing 
13a00 73 75 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69  subsystem is omi
13a10 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75  tted from the bu
13a20 69 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61  ild and hence ca
13a30 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  lls to.** [sqlit
13a40 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74  e3_config()] wit
13a50 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  h the SQLITE_CON
13a60 46 49 47 5f 47 45 54 4d 55 54 45 58 20 63 6f 6e  FIG_GETMUTEX con
13a70 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
13a80 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e  n will.** return
13a90 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e   [SQLITE_ERROR].
13aa0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
13ab0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  LITE_CONFIG_LOOK
13ac0 41 53 49 44 45 5d 5d 20 3c 64 74 3e 53 51 4c 49  ASIDE]] <dt>SQLI
13ad0 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  TE_CONFIG_LOOKAS
13ae0 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  IDE</dt>.** <dd>
13af0 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74   ^(This option t
13b00 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e  akes two argumen
13b10 74 73 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e  ts that determin
13b20 65 20 74 68 65 20 64 65 66 61 75 6c 74 0a 2a 2a  e the default.**
13b30 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
13b40 6f 6e 20 66 6f 72 20 74 68 65 20 6c 6f 6f 6b 61  on for the looka
13b50 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  side memory allo
13b60 63 61 74 6f 72 20 6f 6e 20 65 61 63 68 0a 2a 2a  cator on each.**
13b70 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
13b80 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20 66 69 72  ction].  The fir
13b90 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  st argument is t
13ba0 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61  he.** size of ea
13bb0 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66  ch lookaside buf
13bc0 66 65 72 20 73 6c 6f 74 20 61 6e 64 20 74 68 65  fer slot and the
13bd0 20 73 65 63 6f 6e 64 20 69 73 20 74 68 65 20 6e   second is the n
13be0 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74  umber of.** slot
13bf0 73 20 61 6c 6c 6f 63 61 74 65 64 20 74 6f 20 65  s allocated to e
13c00 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ach database con
13c10 6e 65 63 74 69 6f 6e 2e 29 5e 20 20 5e 28 54 68  nection.)^  ^(Th
13c20 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74  is option sets t
13c30 68 65 0a 2a 2a 20 3c 69 3e 64 65 66 61 75 6c 74  he.** <i>default
13c40 3c 2f 69 3e 20 6c 6f 6f 6b 61 73 69 64 65 20 73  </i> lookaside s
13c50 69 7a 65 2e 20 54 68 65 20 5b 53 51 4c 49 54 45  ize. The [SQLITE
13c60 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  _DBCONFIG_LOOKAS
13c70 49 44 45 5d 0a 2a 2a 20 76 65 72 62 20 74 6f 20  IDE].** verb to 
13c80 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66  [sqlite3_db_conf
13c90 69 67 28 29 5d 20 63 61 6e 20 62 65 20 75 73 65  ig()] can be use
13ca0 64 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20  d to change the 
13cb0 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 63 6f 6e  lookaside.** con
13cc0 66 69 67 75 72 61 74 69 6f 6e 20 6f 6e 20 69 6e  figuration on in
13cd0 64 69 76 69 64 75 61 6c 20 63 6f 6e 6e 65 63 74  dividual connect
13ce0 69 6f 6e 73 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a  ions.)^ </dd>.**
13cf0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
13d00 46 49 47 5f 50 43 41 43 48 45 32 5d 5d 20 3c 64  FIG_PCACHE2]] <d
13d10 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
13d20 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20  PCACHE2</dt>.** 
13d30 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69  <dd> ^(This opti
13d40 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
13d50 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
13d60 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
13d70 0a 2a 2a 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f  .** an [sqlite3_
13d80 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d  pcache_methods2]
13d90 20 6f 62 6a 65 63 74 2e 20 20 54 68 69 73 20 6f   object.  This o
13da0 62 6a 65 63 74 20 73 70 65 63 69 66 69 65 73 20  bject specifies 
13db0 74 68 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  the interface.**
13dc0 20 74 6f 20 61 20 63 75 73 74 6f 6d 20 70 61 67   to a custom pag
13dd0 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e  e cache implemen
13de0 74 61 74 69 6f 6e 2e 29 5e 20 20 5e 53 51 4c 69  tation.)^  ^SQLi
13df0 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20  te makes a copy 
13e00 6f 66 20 74 68 65 0a 2a 2a 20 6f 62 6a 65 63 74  of the.** object
13e10 20 61 6e 64 20 75 73 65 73 20 69 74 20 66 6f 72   and uses it for
13e20 20 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f   page cache memo
13e30 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 3c  ry allocations.<
13e40 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
13e50 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43  ITE_CONFIG_GETPC
13e60 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53 51 4c 49  ACHE2]] <dt>SQLI
13e70 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41  TE_CONFIG_GETPCA
13e80 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  CHE2</dt>.** <dd
13e90 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20  > ^(This option 
13ea0 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
13eb0 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
13ec0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
13ed0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 63 61  .** [sqlite3_pca
13ee0 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62  che_methods2] ob
13ef0 6a 65 63 74 2e 20 20 53 51 4c 69 74 65 20 63 6f  ject.  SQLite co
13f00 70 69 65 73 20 6f 66 20 74 68 65 20 63 75 72 72  pies of the curr
13f10 65 6e 74 0a 2a 2a 20 70 61 67 65 20 63 61 63 68  ent.** page cach
13f20 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
13f30 20 69 6e 74 6f 20 74 68 61 74 20 6f 62 6a 65 63   into that objec
13f40 74 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  t.)^ </dd>.**.**
13f50 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
13f60 5f 4c 4f 47 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  _LOG]] <dt>SQLIT
13f70 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 3c 2f 64 74  E_CONFIG_LOG</dt
13f80 3e 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 20 53 51  >.** <dd> The SQ
13f90 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20  LITE_CONFIG_LOG 
13fa0 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74  option is used t
13fb0 6f 20 63 6f 6e 66 69 67 75 72 65 20 74 68 65 20  o configure the 
13fc0 53 51 4c 69 74 65 0a 2a 2a 20 67 6c 6f 62 61 6c  SQLite.** global
13fd0 20 5b 65 72 72 6f 72 20 6c 6f 67 5d 2e 0a 2a 2a   [error log]..**
13fe0 20 28 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f   (^The SQLITE_CO
13ff0 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20  NFIG_LOG option 
14000 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65  takes two argume
14010 6e 74 73 3a 20 61 20 70 6f 69 6e 74 65 72 20 74  nts: a pointer t
14020 6f 20 61 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  o a.** function 
14030 77 69 74 68 20 61 20 63 61 6c 6c 20 73 69 67 6e  with a call sign
14040 61 74 75 72 65 20 6f 66 20 76 6f 69 64 28 2a 29  ature of void(*)
14050 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74  (void*,int,const
14060 20 63 68 61 72 2a 29 2c 20 0a 2a 2a 20 61 6e 64   char*), .** and
14070 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 76 6f   a pointer to vo
14080 69 64 2e 20 5e 49 66 20 74 68 65 20 66 75 6e 63  id. ^If the func
14090 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20  tion pointer is 
140a0 6e 6f 74 20 4e 55 4c 4c 2c 20 69 74 20 69 73 0a  not NULL, it is.
140b0 2a 2a 20 69 6e 76 6f 6b 65 64 20 62 79 20 5b 73  ** invoked by [s
140c0 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 74 6f  qlite3_log()] to
140d0 20 70 72 6f 63 65 73 73 20 65 61 63 68 20 6c 6f   process each lo
140e0 67 67 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49  gging event.  ^I
140f0 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f  f the.** functio
14100 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 4e 55 4c  n pointer is NUL
14110 4c 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  L, the [sqlite3_
14120 6c 6f 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65  log()] interface
14130 20 62 65 63 6f 6d 65 73 20 61 20 6e 6f 2d 6f 70   becomes a no-op
14140 2e 0a 2a 2a 20 5e 54 68 65 20 76 6f 69 64 20 70  ..** ^The void p
14150 6f 69 6e 74 65 72 20 74 68 61 74 20 69 73 20 74  ointer that is t
14160 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
14170 6e 74 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e  nt to SQLITE_CON
14180 46 49 47 5f 4c 4f 47 20 69 73 0a 2a 2a 20 70 61  FIG_LOG is.** pa
14190 73 73 65 64 20 74 68 72 6f 75 67 68 20 61 73 20  ssed through as 
141a0 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
141b0 74 65 72 20 74 6f 20 74 68 65 20 61 70 70 6c 69  ter to the appli
141c0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c  cation-defined l
141d0 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f  ogger.** functio
141e0 6e 20 77 68 65 6e 65 76 65 72 20 74 68 61 74 20  n whenever that 
141f0 66 75 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f  function is invo
14200 6b 65 64 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e  ked.  ^The secon
14210 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  d parameter to.*
14220 2a 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e  * the logger fun
14230 63 74 69 6f 6e 20 69 73 20 61 20 63 6f 70 79 20  ction is a copy 
14240 6f 66 20 74 68 65 20 66 69 72 73 74 20 70 61 72  of the first par
14250 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 6f  ameter to the co
14260 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 5b  rresponding.** [
14270 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 63  sqlite3_log()] c
14280 61 6c 6c 20 61 6e 64 20 69 73 20 69 6e 74 65 6e  all and is inten
14290 64 65 64 20 74 6f 20 62 65 20 61 20 5b 72 65 73  ded to be a [res
142a0 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20 61 6e 0a  ult code] or an.
142b0 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  ** [extended res
142c0 75 6c 74 20 63 6f 64 65 5d 2e 20 20 5e 54 68 65  ult code].  ^The
142d0 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
142e0 20 70 61 73 73 65 64 20 74 6f 20 74 68 65 20 6c   passed to the l
142f0 6f 67 67 65 72 20 69 73 0a 2a 2a 20 6c 6f 67 20  ogger is.** log 
14300 6d 65 73 73 61 67 65 20 61 66 74 65 72 20 66 6f  message after fo
14310 72 6d 61 74 74 69 6e 67 20 76 69 61 20 5b 73 71  rmatting via [sq
14320 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
14330 5d 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65  ]..** The SQLite
14340 20 6c 6f 67 67 69 6e 67 20 69 6e 74 65 72 66 61   logging interfa
14350 63 65 20 69 73 20 6e 6f 74 20 72 65 65 6e 74 72  ce is not reentr
14360 61 6e 74 3b 20 74 68 65 20 6c 6f 67 67 65 72 20  ant; the logger 
14370 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73 75 70 70  function.** supp
14380 6c 69 65 64 20 62 79 20 74 68 65 20 61 70 70 6c  lied by the appl
14390 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  ication must not
143a0 20 69 6e 76 6f 6b 65 20 61 6e 79 20 53 51 4c 69   invoke any SQLi
143b0 74 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  te interface..**
143c0 20 49 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65   In a multi-thre
143d0 61 64 65 64 20 61 70 70 6c 69 63 61 74 69 6f 6e  aded application
143e0 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  , the applicatio
143f0 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72  n-defined logger
14400 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73  .** function mus
14410 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65 2e  t be threadsafe.
14420 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53   </dd>.**.** [[S
14430 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49  QLITE_CONFIG_URI
14440 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
14450 4e 46 49 47 5f 55 52 49 0a 2a 2a 20 3c 64 64 3e  NFIG_URI.** <dd>
14460 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61  ^(This option ta
14470 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
14480 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e  ument of type in
14490 74 2e 20 49 66 20 6e 6f 6e 2d 7a 65 72 6f 2c 20  t. If non-zero, 
144a0 74 68 65 6e 0a 2a 2a 20 55 52 49 20 68 61 6e 64  then.** URI hand
144b0 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79  ling is globally
144c0 20 65 6e 61 62 6c 65 64 2e 20 49 66 20 74 68 65   enabled. If the
144d0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 7a 65   parameter is ze
144e0 72 6f 2c 20 74 68 65 6e 20 55 52 49 20 68 61 6e  ro, then URI han
144f0 64 6c 69 6e 67 0a 2a 2a 20 69 73 20 67 6c 6f 62  dling.** is glob
14500 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 2e 29 5e  ally disabled.)^
14510 20 5e 49 66 20 55 52 49 20 68 61 6e 64 6c 69 6e   ^If URI handlin
14520 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 65 6e  g is globally en
14530 61 62 6c 65 64 2c 20 61 6c 6c 20 66 69 6c 65 6e  abled, all filen
14540 61 6d 65 73 0a 2a 2a 20 70 61 73 73 65 64 20 74  ames.** passed t
14550 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  o [sqlite3_open(
14560 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  )], [sqlite3_ope
14570 6e 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65  n_v2()], [sqlite
14580 33 5f 6f 70 65 6e 31 36 28 29 5d 20 6f 72 0a 2a  3_open16()] or.*
14590 2a 20 73 70 65 63 69 66 69 65 64 20 61 73 20 70  * specified as p
145a0 61 72 74 20 6f 66 20 5b 41 54 54 41 43 48 5d 20  art of [ATTACH] 
145b0 63 6f 6d 6d 61 6e 64 73 20 61 72 65 20 69 6e 74  commands are int
145c0 65 72 70 72 65 74 65 64 20 61 73 20 55 52 49 73  erpreted as URIs
145d0 2c 20 72 65 67 61 72 64 6c 65 73 73 0a 2a 2a 20  , regardless.** 
145e0 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  of whether or no
145f0 74 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  t the [SQLITE_OP
14600 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69 73 20  EN_URI] flag is 
14610 73 65 74 20 77 68 65 6e 20 74 68 65 20 64 61 74  set when the dat
14620 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74  abase.** connect
14630 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20 5e  ion is opened. ^
14640 49 66 20 69 74 20 69 73 20 67 6c 6f 62 61 6c 6c  If it is globall
14650 79 20 64 69 73 61 62 6c 65 64 2c 20 66 69 6c 65  y disabled, file
14660 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20 6f 6e 6c  names are.** onl
14670 79 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  y interpreted as
14680 20 55 52 49 73 20 69 66 20 74 68 65 20 53 51 4c   URIs if the SQL
14690 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20 66 6c 61  ITE_OPEN_URI fla
146a0 67 20 69 73 20 73 65 74 20 77 68 65 6e 20 74 68  g is set when th
146b0 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  e.** database co
146c0 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e  nnection is open
146d0 65 64 2e 20 5e 28 42 79 20 64 65 66 61 75 6c 74  ed. ^(By default
146e0 2c 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69  , URI handling i
146f0 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 64 69  s globally.** di
14700 73 61 62 6c 65 64 2e 20 54 68 65 20 64 65 66 61  sabled. The defa
14710 75 6c 74 20 76 61 6c 75 65 20 6d 61 79 20 62 65  ult value may be
14720 20 63 68 61 6e 67 65 64 20 62 79 20 63 6f 6d 70   changed by comp
14730 69 6c 69 6e 67 20 77 69 74 68 20 74 68 65 0a 2a  iling with the.*
14740 2a 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55 52  * [SQLITE_USE_UR
14750 49 5d 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65  I] symbol define
14760 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d.)^.**.** [[SQL
14770 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52  ITE_CONFIG_COVER
14780 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d 5d  ING_INDEX_SCAN]]
14790 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
147a0 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45  IG_COVERING_INDE
147b0 58 5f 53 43 41 4e 0a 2a 2a 20 3c 64 64 3e 5e 54  X_SCAN.** <dd>^T
147c0 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
147d0 20 61 20 73 69 6e 67 6c 65 20 69 6e 74 65 67 65   a single intege
147e0 72 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  r argument which
147f0 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20   is interpreted 
14800 61 73 0a 2a 2a 20 61 20 62 6f 6f 6c 65 61 6e 20  as.** a boolean 
14810 69 6e 20 6f 72 64 65 72 20 74 6f 20 65 6e 61 62  in order to enab
14820 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 74 68  le or disable th
14830 65 20 75 73 65 20 6f 66 20 63 6f 76 65 72 69 6e  e use of coverin
14840 67 20 69 6e 64 69 63 65 73 20 66 6f 72 0a 2a 2a  g indices for.**
14850 20 66 75 6c 6c 20 74 61 62 6c 65 20 73 63 61 6e   full table scan
14860 73 20 69 6e 20 74 68 65 20 71 75 65 72 79 20 6f  s in the query o
14870 70 74 69 6d 69 7a 65 72 2e 20 20 5e 54 68 65 20  ptimizer.  ^The 
14880 64 65 66 61 75 6c 74 20 73 65 74 74 69 6e 67 20  default setting 
14890 69 73 20 64 65 74 65 72 6d 69 6e 65 64 0a 2a 2a  is determined.**
148a0 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   by the [SQLITE_
148b0 41 4c 4c 4f 57 5f 43 4f 56 45 52 49 4e 47 5f 49  ALLOW_COVERING_I
148c0 4e 44 45 58 5f 53 43 41 4e 5d 20 63 6f 6d 70 69  NDEX_SCAN] compi
148d0 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20  le-time option, 
148e0 6f 72 20 69 73 20 22 6f 6e 22 0a 2a 2a 20 69 66  or is "on".** if
148f0 20 74 68 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69   that compile-ti
14900 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6d 69  me option is omi
14910 74 74 65 64 2e 0a 2a 2a 20 54 68 65 20 61 62 69  tted..** The abi
14920 6c 69 74 79 20 74 6f 20 64 69 73 61 62 6c 65 20  lity to disable 
14930 74 68 65 20 75 73 65 20 6f 66 20 63 6f 76 65 72  the use of cover
14940 69 6e 67 20 69 6e 64 69 63 65 73 20 66 6f 72 20  ing indices for 
14950 66 75 6c 6c 20 74 61 62 6c 65 20 73 63 61 6e 73  full table scans
14960 0a 2a 2a 20 69 73 20 62 65 63 61 75 73 65 20 73  .** is because s
14970 6f 6d 65 20 69 6e 63 6f 72 72 65 63 74 6c 79 20  ome incorrectly 
14980 63 6f 64 65 64 20 6c 65 67 61 63 79 20 61 70 70  coded legacy app
14990 6c 69 63 61 74 69 6f 6e 73 20 6d 69 67 68 74 20  lications might 
149a0 6d 61 6c 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77  malfunction.** w
149b0 68 65 6e 20 74 68 65 20 6f 70 74 69 6d 69 7a 61  hen the optimiza
149c0 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e  tion is enabled.
149d0 20 20 50 72 6f 76 69 64 69 6e 67 20 74 68 65 20    Providing the 
149e0 61 62 69 6c 69 74 79 20 74 6f 0a 2a 2a 20 64 69  ability to.** di
149f0 73 61 62 6c 65 20 74 68 65 20 6f 70 74 69 6d 69  sable the optimi
14a00 7a 61 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 74 68  zation allows th
14a10 65 20 6f 6c 64 65 72 2c 20 62 75 67 67 79 20 61  e older, buggy a
14a20 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20  pplication code 
14a30 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 69 74 68 6f  to work.** witho
14a40 75 74 20 63 68 61 6e 67 65 20 65 76 65 6e 20 77  ut change even w
14a50 69 74 68 20 6e 65 77 65 72 20 76 65 72 73 69 6f  ith newer versio
14a60 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  ns of SQLite..**
14a70 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
14a80 46 49 47 5f 50 43 41 43 48 45 5d 5d 20 5b 5b 53  FIG_PCACHE]] [[S
14a90 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
14aa0 50 43 41 43 48 45 5d 5d 0a 2a 2a 20 3c 64 74 3e  PCACHE]].** <dt>
14ab0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
14ac0 41 43 48 45 20 61 6e 64 20 53 51 4c 49 54 45 5f  ACHE and SQLITE_
14ad0 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45  CONFIG_GETPCACHE
14ae0 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 73 65 20 6f  .** <dd> These o
14af0 70 74 69 6f 6e 73 20 61 72 65 20 6f 62 73 6f 6c  ptions are obsol
14b00 65 74 65 20 61 6e 64 20 73 68 6f 75 6c 64 20 6e  ete and should n
14b10 6f 74 20 62 65 20 75 73 65 64 20 62 79 20 6e 65  ot be used by ne
14b20 77 20 63 6f 64 65 2e 0a 2a 2a 20 54 68 65 79 20  w code..** They 
14b30 61 72 65 20 72 65 74 61 69 6e 65 64 20 66 6f 72  are retained for
14b40 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61   backwards compa
14b50 74 69 62 69 6c 69 74 79 20 62 75 74 20 61 72 65  tibility but are
14b60 20 6e 6f 77 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 20   now no-ops..** 
14b70 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
14b80 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c  LITE_CONFIG_SQLL
14b90 4f 47 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  OG]].** <dt>SQLI
14ba0 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47  TE_CONFIG_SQLLOG
14bb0 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74  .** <dd>This opt
14bc0 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69  ion is only avai
14bd0 6c 61 62 6c 65 20 69 66 20 73 71 6c 69 74 65 20  lable if sqlite 
14be0 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
14bf0 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
14c00 45 4e 41 42 4c 45 5f 53 51 4c 4c 4f 47 5d 20 70  ENABLE_SQLLOG] p
14c10 72 65 2d 70 72 6f 63 65 73 73 6f 72 20 6d 61 63  re-processor mac
14c20 72 6f 20 64 65 66 69 6e 65 64 2e 20 54 68 65 20  ro defined. The 
14c30 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 73  first argument s
14c40 68 6f 75 6c 64 0a 2a 2a 20 62 65 20 61 20 70 6f  hould.** be a po
14c50 69 6e 74 65 72 20 74 6f 20 61 20 66 75 6e 63 74  inter to a funct
14c60 69 6f 6e 20 6f 66 20 74 79 70 65 20 76 6f 69 64  ion of type void
14c70 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65  (*)(void*,sqlite
14c80 33 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  3*,const char*, 
14c90 69 6e 74 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63  int)..** The sec
14ca0 6f 6e 64 20 73 68 6f 75 6c 64 20 62 65 20 6f 66  ond should be of
14cb0 20 74 79 70 65 20 28 76 6f 69 64 2a 29 2e 20 54   type (void*). T
14cc0 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  he callback is i
14cd0 6e 76 6f 6b 65 64 20 62 79 20 74 68 65 20 6c 69  nvoked by the li
14ce0 62 72 61 72 79 0a 2a 2a 20 69 6e 20 74 68 72 65  brary.** in thre
14cf0 65 20 73 65 70 61 72 61 74 65 20 63 69 72 63 75  e separate circu
14d00 6d 73 74 61 6e 63 65 73 2c 20 69 64 65 6e 74 69  mstances, identi
14d10 66 69 65 64 20 62 79 20 74 68 65 20 76 61 6c 75  fied by the valu
14d20 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 0a  e passed as the.
14d30 2a 2a 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  ** fourth parame
14d40 74 65 72 2e 20 49 66 20 74 68 65 20 66 6f 75 72  ter. If the four
14d50 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  th parameter is 
14d60 30 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61  0, then the data
14d70 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
14d80 2a 2a 20 70 61 73 73 65 64 20 61 73 20 74 68 65  ** passed as the
14d90 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
14da0 20 68 61 73 20 6a 75 73 74 20 62 65 65 6e 20 6f   has just been o
14db0 70 65 6e 65 64 2e 20 54 68 65 20 74 68 69 72 64  pened. The third
14dc0 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 70 6f 69   argument.** poi
14dd0 6e 74 73 20 74 6f 20 61 20 62 75 66 66 65 72 20  nts to a buffer 
14de0 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 6e  containing the n
14df0 61 6d 65 20 6f 66 20 74 68 65 20 6d 61 69 6e 20  ame of the main 
14e00 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e 20 49  database file. I
14e10 66 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20  f the.** fourth 
14e20 70 61 72 61 6d 65 74 65 72 20 69 73 20 31 2c 20  parameter is 1, 
14e30 74 68 65 6e 20 74 68 65 20 53 51 4c 20 73 74 61  then the SQL sta
14e40 74 65 6d 65 6e 74 20 74 68 61 74 20 74 68 65 20  tement that the 
14e50 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 0a  third parameter.
14e60 2a 2a 20 70 6f 69 6e 74 73 20 74 6f 20 68 61 73  ** points to has
14e70 20 6a 75 73 74 20 62 65 65 6e 20 65 78 65 63 75   just been execu
14e80 74 65 64 2e 20 4f 72 2c 20 69 66 20 74 68 65 20  ted. Or, if the 
14e90 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
14ea0 20 69 73 20 32 2c 20 74 68 65 6e 0a 2a 2a 20 74   is 2, then.** t
14eb0 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 65  he connection be
14ec0 69 6e 67 20 70 61 73 73 65 64 20 61 73 20 74 68  ing passed as th
14ed0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
14ee0 65 72 20 69 73 20 62 65 69 6e 67 20 63 6c 6f 73  er is being clos
14ef0 65 64 2e 20 54 68 65 0a 2a 2a 20 74 68 69 72 64  ed. The.** third
14f00 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 70 61   parameter is pa
14f10 73 73 65 64 20 4e 55 4c 4c 20 49 6e 20 74 68 69  ssed NULL In thi
14f20 73 20 63 61 73 65 2e 20 20 41 6e 20 65 78 61 6d  s case.  An exam
14f30 70 6c 65 20 6f 66 20 75 73 69 6e 67 20 74 68 69  ple of using thi
14f40 73 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69  s.** configurati
14f50 6f 6e 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65  on option can be
14f60 20 73 65 65 6e 20 69 6e 20 74 68 65 20 22 74 65   seen in the "te
14f70 73 74 5f 73 71 6c 6c 6f 67 2e 63 22 20 73 6f 75  st_sqllog.c" sou
14f80 72 63 65 20 66 69 6c 65 20 69 6e 0a 2a 2a 20 74  rce file in.** t
14f90 68 65 20 63 61 6e 6f 6e 69 63 61 6c 20 53 51 4c  he canonical SQL
14fa0 69 74 65 20 73 6f 75 72 63 65 20 74 72 65 65 2e  ite source tree.
14fb0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
14fc0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50  LITE_CONFIG_MMAP
14fd0 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53  _SIZE]].** <dt>S
14fe0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41  QLITE_CONFIG_MMA
14ff0 50 5f 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e 5e 53  P_SIZE.** <dd>^S
15000 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41  QLITE_CONFIG_MMA
15010 50 5f 53 49 5a 45 20 74 61 6b 65 73 20 74 77 6f  P_SIZE takes two
15020 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20   64-bit integer 
15030 28 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 20  (sqlite3_int64) 
15040 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 61  values.** that a
15050 72 65 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d  re the default m
15060 6d 61 70 20 73 69 7a 65 20 6c 69 6d 69 74 20 28  map size limit (
15070 74 68 65 20 64 65 66 61 75 6c 74 20 73 65 74 74  the default sett
15080 69 6e 67 20 66 6f 72 0a 2a 2a 20 5b 50 52 41 47  ing for.** [PRAG
15090 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 29 20 61  MA mmap_size]) a
150a0 6e 64 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 61  nd the maximum a
150b0 6c 6c 6f 77 65 64 20 6d 6d 61 70 20 73 69 7a 65  llowed mmap size
150c0 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 54 68 65 20   limit..** ^The 
150d0 64 65 66 61 75 6c 74 20 73 65 74 74 69 6e 67 20  default setting 
150e0 63 61 6e 20 62 65 20 6f 76 65 72 72 69 64 64 65  can be overridde
150f0 6e 20 62 79 20 65 61 63 68 20 64 61 74 61 62 61  n by each databa
15100 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 75 73  se connection us
15110 69 6e 67 0a 2a 2a 20 65 69 74 68 65 72 20 74 68  ing.** either th
15120 65 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73  e [PRAGMA mmap_s
15130 69 7a 65 5d 20 63 6f 6d 6d 61 6e 64 2c 20 6f 72  ize] command, or
15140 20 62 79 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a   by using the.**
15150 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d   [SQLITE_FCNTL_M
15160 4d 41 50 5f 53 49 5a 45 5d 20 66 69 6c 65 20 63  MAP_SIZE] file c
15170 6f 6e 74 72 6f 6c 2e 20 20 5e 28 54 68 65 20 6d  ontrol.  ^(The m
15180 61 78 69 6d 75 6d 20 61 6c 6c 6f 77 65 64 20 6d  aximum allowed m
15190 6d 61 70 20 73 69 7a 65 0a 2a 2a 20 63 61 6e 6e  map size.** cann
151a0 6f 74 20 62 65 20 63 68 61 6e 67 65 64 20 61 74  ot be changed at
151b0 20 72 75 6e 2d 74 69 6d 65 2e 20 20 4e 6f 72 20   run-time.  Nor 
151c0 6d 61 79 20 74 68 65 20 6d 61 78 69 6d 75 6d 20  may the maximum 
151d0 61 6c 6c 6f 77 65 64 20 6d 6d 61 70 20 73 69 7a  allowed mmap siz
151e0 65 0a 2a 2a 20 65 78 63 65 65 64 20 74 68 65 20  e.** exceed the 
151f0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 61 78  compile-time max
15200 69 6d 75 6d 20 6d 6d 61 70 20 73 69 7a 65 20 73  imum mmap size s
15210 65 74 20 62 79 20 74 68 65 0a 2a 2a 20 5b 53 51  et by the.** [SQ
15220 4c 49 54 45 5f 4d 41 58 5f 4d 4d 41 50 5f 53 49  LITE_MAX_MMAP_SI
15230 5a 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  ZE] compile-time
15240 20 6f 70 74 69 6f 6e 2e 29 5e 0a 2a 2a 20 5e 49   option.)^.** ^I
15250 66 20 65 69 74 68 65 72 20 61 72 67 75 6d 65 6e  f either argumen
15260 74 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e  t to this option
15270 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68   is negative, th
15280 65 6e 20 74 68 61 74 20 61 72 67 75 6d 65 6e 74  en that argument
15290 20 69 73 0a 2a 2a 20 63 68 61 6e 67 65 64 20 74   is.** changed t
152a0 6f 20 69 74 73 20 63 6f 6d 70 69 6c 65 2d 74 69  o its compile-ti
152b0 6d 65 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a  me default..**.*
152c0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
152d0 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45  G_WIN32_HEAPSIZE
152e0 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  ]].** <dt>SQLITE
152f0 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45  _CONFIG_WIN32_HE
15300 41 50 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e 5e 54  APSIZE.** <dd>^T
15310 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e  his option is on
15320 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20  ly available if 
15330 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
15340 65 64 20 66 6f 72 20 57 69 6e 64 6f 77 73 0a 2a  ed for Windows.*
15350 2a 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49  * with the [SQLI
15360 54 45 5f 57 49 4e 33 32 5f 4d 41 4c 4c 4f 43 5d  TE_WIN32_MALLOC]
15370 20 70 72 65 2d 70 72 6f 63 65 73 73 6f 72 20 6d   pre-processor m
15380 61 63 72 6f 20 64 65 66 69 6e 65 64 2e 0a 2a 2a  acro defined..**
15390 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57   SQLITE_CONFIG_W
153a0 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 20 74 61  IN32_HEAPSIZE ta
153b0 6b 65 73 20 61 20 33 32 2d 62 69 74 20 75 6e 73  kes a 32-bit uns
153c0 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 76 61  igned integer va
153d0 6c 75 65 0a 2a 2a 20 74 68 61 74 20 73 70 65 63  lue.** that spec
153e0 69 66 69 65 73 20 74 68 65 20 6d 61 78 69 6d 75  ifies the maximu
153f0 6d 20 73 69 7a 65 20 6f 66 20 74 68 65 20 63 72  m size of the cr
15400 65 61 74 65 64 20 68 65 61 70 2e 0a 2a 2a 20 3c  eated heap..** <
15410 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  /dl>.*/.#define 
15420 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49  SQLITE_CONFIG_SI
15430 4e 47 4c 45 54 48 52 45 41 44 20 20 31 20 20 2f  NGLETHREAD  1  /
15440 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65  * nil */.#define
15450 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
15460 55 4c 54 49 54 48 52 45 41 44 20 20 20 32 20 20  ULTITHREAD   2  
15470 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e  /* nil */.#defin
15480 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
15490 53 45 52 49 41 4c 49 5a 45 44 20 20 20 20 33 20  SERIALIZED    3 
154a0 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69   /* nil */.#defi
154b0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
154c0 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20 20 34  _MALLOC        4
154d0 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d    /* sqlite3_mem
154e0 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65  _methods* */.#de
154f0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
15500 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 20 20 20  IG_GETMALLOC    
15510 20 35 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d   5  /* sqlite3_m
15520 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23  em_methods* */.#
15530 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
15540 4e 46 49 47 5f 53 43 52 41 54 43 48 20 20 20 20  NFIG_SCRATCH    
15550 20 20 20 36 20 20 2f 2a 20 76 6f 69 64 2a 2c 20     6  /* void*, 
15560 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f  int sz, int N */
15570 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
15580 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45  CONFIG_PAGECACHE
15590 20 20 20 20 20 37 20 20 2f 2a 20 76 6f 69 64 2a       7  /* void*
155a0 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20  , int sz, int N 
155b0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
155c0 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 20 20  E_CONFIG_HEAP   
155d0 20 20 20 20 20 20 20 38 20 20 2f 2a 20 76 6f 69         8  /* voi
155e0 64 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 69  d*, int nByte, i
155f0 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64 65 66 69 6e  nt min */.#defin
15600 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
15610 4d 45 4d 53 54 41 54 55 53 20 20 20 20 20 39 20  MEMSTATUS     9 
15620 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 23   /* boolean */.#
15630 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
15640 4e 46 49 47 5f 4d 55 54 45 58 20 20 20 20 20 20  NFIG_MUTEX      
15650 20 20 31 30 20 20 2f 2a 20 73 71 6c 69 74 65 33    10  /* sqlite3
15660 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20  _mutex_methods* 
15670 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
15680 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45  E_CONFIG_GETMUTE
15690 58 20 20 20 20 20 31 31 20 20 2f 2a 20 73 71 6c  X     11  /* sql
156a0 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
156b0 64 73 2a 20 2a 2f 0a 2f 2a 20 70 72 65 76 69 6f  ds* */./* previo
156c0 75 73 6c 79 20 53 51 4c 49 54 45 5f 43 4f 4e 46  usly SQLITE_CONF
156d0 49 47 5f 43 48 55 4e 4b 41 4c 4c 4f 43 20 31 32  IG_CHUNKALLOC 12
156e0 20 77 68 69 63 68 20 69 73 20 6e 6f 77 20 75 6e   which is now un
156f0 75 73 65 64 2e 20 2a 2f 20 0a 23 64 65 66 69 6e  used. */ .#defin
15700 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
15710 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 31 33 20  LOOKASIDE    13 
15720 20 2f 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23   /* int int */.#
15730 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
15740 4e 46 49 47 5f 50 43 41 43 48 45 20 20 20 20 20  NFIG_PCACHE     
15750 20 20 31 34 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a    14  /* no-op *
15760 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
15770 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48  _CONFIG_GETPCACH
15780 45 20 20 20 20 31 35 20 20 2f 2a 20 6e 6f 2d 6f  E    15  /* no-o
15790 70 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  p */.#define SQL
157a0 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 20  ITE_CONFIG_LOG  
157b0 20 20 20 20 20 20 20 20 31 36 20 20 2f 2a 20 78          16  /* x
157c0 46 75 6e 63 2c 20 76 6f 69 64 2a 20 2a 2f 0a 23  Func, void* */.#
157d0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
157e0 4e 46 49 47 5f 55 52 49 20 20 20 20 20 20 20 20  NFIG_URI        
157f0 20 20 31 37 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a    17  /* int */.
15800 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
15810 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 20 20 20  ONFIG_PCACHE2   
15820 20 20 20 31 38 20 20 2f 2a 20 73 71 6c 69 74 65     18  /* sqlite
15830 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73  3_pcache_methods
15840 32 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  2* */.#define SQ
15850 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50  LITE_CONFIG_GETP
15860 43 41 43 48 45 32 20 20 20 31 39 20 20 2f 2a 20  CACHE2   19  /* 
15870 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d  sqlite3_pcache_m
15880 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23 64 65 66  ethods2* */.#def
15890 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
158a0 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58  G_COVERING_INDEX
158b0 5f 53 43 41 4e 20 32 30 20 20 2f 2a 20 69 6e 74  _SCAN 20  /* int
158c0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
158d0 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47  TE_CONFIG_SQLLOG
158e0 20 20 20 20 20 20 20 32 31 20 20 2f 2a 20 78 53         21  /* xS
158f0 71 6c 6c 6f 67 2c 20 76 6f 69 64 2a 20 2a 2f 0a  qllog, void* */.
15900 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
15910 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 20  ONFIG_MMAP_SIZE 
15920 20 20 20 32 32 20 20 2f 2a 20 73 71 6c 69 74 65     22  /* sqlite
15930 33 5f 69 6e 74 36 34 2c 20 73 71 6c 69 74 65 33  3_int64, sqlite3
15940 5f 69 6e 74 36 34 20 2a 2f 0a 23 64 65 66 69 6e  _int64 */.#defin
15950 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
15960 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 20 20  WIN32_HEAPSIZE  
15970 20 20 20 20 32 33 20 20 2f 2a 20 69 6e 74 20 6e      23  /* int n
15980 42 79 74 65 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  Byte */../*.** C
15990 41 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73  API3REF: Databas
159a0 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 43 6f 6e  e Connection Con
159b0 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f  figuration Optio
159c0 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63  ns.**.** These c
159d0 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68 65  onstants are the
159e0 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67   available integ
159f0 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  er configuration
15a00 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a   options that.**
15a10 20 63 61 6e 20 62 65 20 70 61 73 73 65 64 20 61   can be passed a
15a20 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  s the second arg
15a30 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71  ument to the [sq
15a40 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
15a50 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  )] interface..**
15a60 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75 72  .** New configur
15a70 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61  ation options ma
15a80 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75  y be added in fu
15a90 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66  ture releases of
15aa0 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73   SQLite..** Exis
15ab0 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69  ting configurati
15ac0 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74  on options might
15ad0 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65 64   be discontinued
15ae0 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a  .  Applications.
15af0 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b 20  ** should check 
15b00 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20  the return code 
15b10 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 64 62  from [sqlite3_db
15b20 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61  _config()] to ma
15b30 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20  ke sure that.** 
15b40 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e  the call worked.
15b50 20 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f    ^The [sqlite3_
15b60 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74  db_config()] int
15b70 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74 75  erface will retu
15b80 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f  rn a.** non-zero
15b90 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66   [error code] if
15ba0 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 20   a discontinued 
15bb0 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20 63  or unsupported c
15bc0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
15bd0 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65  ion.** is invoke
15be0 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a  d..**.** <dl>.**
15bf0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f   <dt>SQLITE_DBCO
15c00 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f  NFIG_LOOKASIDE</
15c10 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69  dt>.** <dd> ^Thi
15c20 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74  s option takes t
15c30 68 72 65 65 20 61 64 64 69 74 69 6f 6e 61 6c 20  hree additional 
15c40 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64  arguments that d
15c50 65 74 65 72 6d 69 6e 65 20 74 68 65 20 0a 2a 2a  etermine the .**
15c60 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f   [lookaside memo
15c70 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 20 63 6f  ry allocator] co
15c80 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f 72 20  nfiguration for 
15c90 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
15ca0 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 5e 54  nnection]..** ^T
15cb0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
15cc0 74 20 28 74 68 65 20 74 68 69 72 64 20 70 61 72  t (the third par
15cd0 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74  ameter to [sqlit
15ce0 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20  e3_db_config()] 
15cf0 69 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  is a.** pointer 
15d00 74 6f 20 61 20 6d 65 6d 6f 72 79 20 62 75 66 66  to a memory buff
15d10 65 72 20 74 6f 20 75 73 65 20 66 6f 72 20 6c 6f  er to use for lo
15d20 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 2e 0a  okaside memory..
15d30 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72  ** ^The first ar
15d40 67 75 6d 65 6e 74 20 61 66 74 65 72 20 74 68 65  gument after the
15d50 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47   SQLITE_DBCONFIG
15d60 5f 4c 4f 4f 4b 41 53 49 44 45 20 76 65 72 62 0a  _LOOKASIDE verb.
15d70 2a 2a 20 6d 61 79 20 62 65 20 4e 55 4c 4c 20 69  ** may be NULL i
15d80 6e 20 77 68 69 63 68 20 63 61 73 65 20 53 51 4c  n which case SQL
15d90 69 74 65 20 77 69 6c 6c 20 61 6c 6c 6f 63 61 74  ite will allocat
15da0 65 20 74 68 65 0a 2a 2a 20 6c 6f 6f 6b 61 73 69  e the.** lookasi
15db0 64 65 20 62 75 66 66 65 72 20 69 74 73 65 6c 66  de buffer itself
15dc0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
15dd0 6d 61 6c 6c 6f 63 28 29 5d 2e 20 5e 54 68 65 20  malloc()]. ^The 
15de0 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
15df0 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f  is the.** size o
15e00 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65  f each lookaside
15e10 20 62 75 66 66 65 72 20 73 6c 6f 74 2e 20 20 5e   buffer slot.  ^
15e20 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  The third argume
15e30 6e 74 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72  nt is the number
15e40 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 2e 20 20 54   of.** slots.  T
15e50 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62  he size of the b
15e60 75 66 66 65 72 20 69 6e 20 74 68 65 20 66 69 72  uffer in the fir
15e70 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74  st argument must
15e80 20 62 65 20 67 72 65 61 74 65 72 20 74 68 61 6e   be greater than
15e90 0a 2a 2a 20 6f 72 20 65 71 75 61 6c 20 74 6f 20  .** or equal to 
15ea0 74 68 65 20 70 72 6f 64 75 63 74 20 6f 66 20 74  the product of t
15eb0 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68  he second and th
15ec0 69 72 64 20 61 72 67 75 6d 65 6e 74 73 2e 20 20  ird arguments.  
15ed0 54 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 6d 75  The buffer.** mu
15ee0 73 74 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f  st be aligned to
15ef0 20 61 6e 20 38 2d 62 79 74 65 20 62 6f 75 6e 64   an 8-byte bound
15f00 61 72 79 2e 20 20 5e 49 66 20 74 68 65 20 73 65  ary.  ^If the se
15f10 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
15f20 0a 2a 2a 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  .** SQLITE_DBCON
15f30 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 69 73  FIG_LOOKASIDE is
15f40 20 6e 6f 74 20 61 20 6d 75 6c 74 69 70 6c 65 20   not a multiple 
15f50 6f 66 20 38 2c 20 69 74 20 69 73 20 69 6e 74 65  of 8, it is inte
15f60 72 6e 61 6c 6c 79 0a 2a 2a 20 72 6f 75 6e 64 65  rnally.** rounde
15f70 64 20 64 6f 77 6e 20 74 6f 20 74 68 65 20 6e 65  d down to the ne
15f80 78 74 20 73 6d 61 6c 6c 65 72 20 6d 75 6c 74 69  xt smaller multi
15f90 70 6c 65 20 6f 66 20 38 2e 20 20 5e 28 54 68 65  ple of 8.  ^(The
15fa0 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72   lookaside memor
15fb0 79 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69  y.** configurati
15fc0 6f 6e 20 66 6f 72 20 61 20 64 61 74 61 62 61 73  on for a databas
15fd0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 61 6e  e connection can
15fe0 20 6f 6e 6c 79 20 62 65 20 63 68 61 6e 67 65 64   only be changed
15ff0 20 77 68 65 6e 20 74 68 61 74 0a 2a 2a 20 63 6f   when that.** co
16000 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6e 6f 74 20  nnection is not 
16010 63 75 72 72 65 6e 74 6c 79 20 75 73 69 6e 67 20  currently using 
16020 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79  lookaside memory
16030 2c 20 6f 72 20 69 6e 20 6f 74 68 65 72 20 77 6f  , or in other wo
16040 72 64 73 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20  rds.** when the 
16050 22 63 75 72 72 65 6e 74 20 76 61 6c 75 65 22 20  "current value" 
16060 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b  returned by.** [
16070 73 71 6c 69 74 65 33 5f 64 62 5f 73 74 61 74 75  sqlite3_db_statu
16080 73 5d 28 44 2c 5b 53 51 4c 49 54 45 5f 43 4f 4e  s](D,[SQLITE_CON
16090 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 2c 2e  FIG_LOOKASIDE],.
160a0 2e 2e 29 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a 20  ..) is zero..** 
160b0 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 63  Any attempt to c
160c0 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73  hange the lookas
160d0 69 64 65 20 6d 65 6d 6f 72 79 20 63 6f 6e 66 69  ide memory confi
160e0 67 75 72 61 74 69 6f 6e 20 77 68 65 6e 20 6c 6f  guration when lo
160f0 6f 6b 61 73 69 64 65 0a 2a 2a 20 6d 65 6d 6f 72  okaside.** memor
16100 79 20 69 73 20 69 6e 20 75 73 65 20 6c 65 61 76  y is in use leav
16110 65 73 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61  es the configura
16120 74 69 6f 6e 20 75 6e 63 68 61 6e 67 65 64 20 61  tion unchanged a
16130 6e 64 20 72 65 74 75 72 6e 73 20 0a 2a 2a 20 5b  nd returns .** [
16140 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 29 5e 3c  SQLITE_BUSY].)^<
16150 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
16160 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45  QLITE_DBCONFIG_E
16170 4e 41 42 4c 45 5f 46 4b 45 59 3c 2f 64 74 3e 0a  NABLE_FKEY</dt>.
16180 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70  ** <dd> ^This op
16190 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20  tion is used to 
161a0 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c  enable or disabl
161b0 65 20 74 68 65 20 65 6e 66 6f 72 63 65 6d 65 6e  e the enforcemen
161c0 74 20 6f 66 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e  t of.** [foreign
161d0 20 6b 65 79 20 63 6f 6e 73 74 72 61 69 6e 74 73   key constraints
161e0 5d 2e 20 20 54 68 65 72 65 20 73 68 6f 75 6c 64  ].  There should
161f0 20 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e   be two addition
16200 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a  al arguments..**
16210 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
16220 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ent is an intege
16230 72 20 77 68 69 63 68 20 69 73 20 30 20 74 6f 20  r which is 0 to 
16240 64 69 73 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72  disable FK enfor
16250 63 65 6d 65 6e 74 2c 0a 2a 2a 20 70 6f 73 69 74  cement,.** posit
16260 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 46 4b  ive to enable FK
16270 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 72 20   enforcement or 
16280 6e 65 67 61 74 69 76 65 20 74 6f 20 6c 65 61 76  negative to leav
16290 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74  e FK enforcement
162a0 0a 2a 2a 20 75 6e 63 68 61 6e 67 65 64 2e 20 20  .** unchanged.  
162b0 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
162c0 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65  eter is a pointe
162d0 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20  r to an integer 
162e0 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73  into which.** is
162f0 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20   written 0 or 1 
16300 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65 74  to indicate whet
16310 68 65 72 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65  her FK enforceme
16320 6e 74 20 69 73 20 6f 66 66 20 6f 72 20 6f 6e 0a  nt is off or on.
16330 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69  ** following thi
16340 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 63  s call.  The sec
16350 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d 61  ond parameter ma
16360 79 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  y be a NULL poin
16370 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68  ter, in.** which
16380 20 63 61 73 65 20 74 68 65 20 46 4b 20 65 6e 66   case the FK enf
16390 6f 72 63 65 6d 65 6e 74 20 73 65 74 74 69 6e 67  orcement setting
163a0 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 64   is not reported
163b0 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a   back. </dd>.**.
163c0 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42  ** <dt>SQLITE_DB
163d0 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52  CONFIG_ENABLE_TR
163e0 49 47 47 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  IGGER</dt>.** <d
163f0 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  d> ^This option 
16400 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c  is used to enabl
16410 65 20 6f 72 20 64 69 73 61 62 6c 65 20 5b 43 52  e or disable [CR
16420 45 41 54 45 20 54 52 49 47 47 45 52 20 7c 20 74  EATE TRIGGER | t
16430 72 69 67 67 65 72 73 5d 2e 0a 2a 2a 20 54 68 65  riggers]..** The
16440 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f  re should be two
16450 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75   additional argu
16460 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69  ments..** The fi
16470 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20  rst argument is 
16480 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68  an integer which
16490 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65   is 0 to disable
164a0 20 74 72 69 67 67 65 72 73 2c 0a 2a 2a 20 70 6f   triggers,.** po
164b0 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65  sitive to enable
164c0 20 74 72 69 67 67 65 72 73 20 6f 72 20 6e 65 67   triggers or neg
164d0 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20 74  ative to leave t
164e0 68 65 20 73 65 74 74 69 6e 67 20 75 6e 63 68 61  he setting uncha
164f0 6e 67 65 64 2e 0a 2a 2a 20 54 68 65 20 73 65 63  nged..** The sec
16500 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
16510 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
16520 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68   integer into wh
16530 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65  ich.** is writte
16540 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69  n 0 or 1 to indi
16550 63 61 74 65 20 77 68 65 74 68 65 72 20 74 72 69  cate whether tri
16560 67 67 65 72 73 20 61 72 65 20 64 69 73 61 62 6c  ggers are disabl
16570 65 64 20 6f 72 20 65 6e 61 62 6c 65 64 0a 2a 2a  ed or enabled.**
16580 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20   following this 
16590 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e  call.  The secon
165a0 64 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20  d parameter may 
165b0 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  be a NULL pointe
165c0 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63  r, in.** which c
165d0 61 73 65 20 74 68 65 20 74 72 69 67 67 65 72 20  ase the trigger 
165e0 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72  setting is not r
165f0 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f  eported back. </
16600 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a  dd>.**.** </dl>.
16610 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
16620 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  E_DBCONFIG_LOOKA
16630 53 49 44 45 20 20 20 20 20 20 20 31 30 30 31 20  SIDE       1001 
16640 20 2f 2a 20 76 6f 69 64 2a 20 69 6e 74 20 69 6e   /* void* int in
16650 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  t */.#define SQL
16660 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41  ITE_DBCONFIG_ENA
16670 42 4c 45 5f 46 4b 45 59 20 20 20 20 20 31 30 30  BLE_FKEY     100
16680 32 20 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a  2  /* int int* *
16690 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
166a0 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45  _DBCONFIG_ENABLE
166b0 5f 54 52 49 47 47 45 52 20 20 31 30 30 33 20 20  _TRIGGER  1003  
166c0 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 0a  /* int int* */..
166d0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
166e0 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62   Enable Or Disab
166f0 6c 65 20 45 78 74 65 6e 64 65 64 20 52 65 73 75  le Extended Resu
16700 6c 74 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 5e  lt Codes.**.** ^
16710 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65  The sqlite3_exte
16720 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65  nded_result_code
16730 73 28 29 20 72 6f 75 74 69 6e 65 20 65 6e 61 62  s() routine enab
16740 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20  les or disables 
16750 74 68 65 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64  the.** [extended
16760 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 66   result codes] f
16770 65 61 74 75 72 65 20 6f 66 20 53 51 4c 69 74 65  eature of SQLite
16780 2e 20 5e 54 68 65 20 65 78 74 65 6e 64 65 64 20  . ^The extended 
16790 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 64 65 73 20  result.** codes 
167a0 61 72 65 20 64 69 73 61 62 6c 65 64 20 62 79 20  are disabled by 
167b0 64 65 66 61 75 6c 74 20 66 6f 72 20 68 69 73 74  default for hist
167c0 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74 69 62 69  orical compatibi
167d0 6c 69 74 79 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  lity..*/.int sql
167e0 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65  ite3_extended_re
167f0 73 75 6c 74 5f 63 6f 64 65 73 28 73 71 6c 69 74  sult_codes(sqlit
16800 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b  e3*, int onoff);
16810 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
16820 3a 20 4c 61 73 74 20 49 6e 73 65 72 74 20 52 6f  : Last Insert Ro
16830 77 69 64 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20  wid.**.** ^Each 
16840 65 6e 74 72 79 20 69 6e 20 6d 6f 73 74 20 53 51  entry in most SQ
16850 4c 69 74 65 20 74 61 62 6c 65 73 20 28 65 78 63  Lite tables (exc
16860 65 70 74 20 66 6f 72 20 5b 57 49 54 48 4f 55 54  ept for [WITHOUT
16870 20 52 4f 57 49 44 5d 20 74 61 62 6c 65 73 29 0a   ROWID] tables).
16880 2a 2a 20 68 61 73 20 61 20 75 6e 69 71 75 65 20  ** has a unique 
16890 36 34 2d 62 69 74 20 73 69 67 6e 65 64 0a 2a 2a  64-bit signed.**
168a0 20 69 6e 74 65 67 65 72 20 6b 65 79 20 63 61 6c   integer key cal
168b0 6c 65 64 20 74 68 65 20 5b 52 4f 57 49 44 20 7c  led the [ROWID |
168c0 20 22 72 6f 77 69 64 22 5d 2e 20 5e 54 68 65 20   "rowid"]. ^The 
168d0 72 6f 77 69 64 20 69 73 20 61 6c 77 61 79 73 20  rowid is always 
168e0 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 61 73 20  available.** as 
168f0 61 6e 20 75 6e 64 65 63 6c 61 72 65 64 20 63 6f  an undeclared co
16900 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f 57 49 44  lumn named ROWID
16910 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f 57 49 44  , OID, or _ROWID
16920 5f 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 6f  _ as long as tho
16930 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 61 72 65 20  se.** names are 
16940 6e 6f 74 20 61 6c 73 6f 20 75 73 65 64 20 62 79  not also used by
16950 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c   explicitly decl
16960 61 72 65 64 20 63 6f 6c 75 6d 6e 73 2e 20 5e 49  ared columns. ^I
16970 66 0a 2a 2a 20 74 68 65 20 74 61 62 6c 65 20 68  f.** the table h
16980 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74  as a column of t
16990 79 70 65 20 5b 49 4e 54 45 47 45 52 20 50 52 49  ype [INTEGER PRI
169a0 4d 41 52 59 20 4b 45 59 5d 20 74 68 65 6e 20 74  MARY KEY] then t
169b0 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73  hat column.** is
169c0 20 61 6e 6f 74 68 65 72 20 61 6c 69 61 73 20 66   another alias f
169d0 6f 72 20 74 68 65 20 72 6f 77 69 64 2e 0a 2a 2a  or the rowid..**
169e0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
169f0 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  _last_insert_row
16a00 69 64 28 44 29 20 69 6e 74 65 72 66 61 63 65 20  id(D) interface 
16a10 72 65 74 75 72 6e 73 20 74 68 65 20 5b 72 6f 77  returns the [row
16a20 69 64 5d 20 6f 66 20 74 68 65 20 0a 2a 2a 20 6d  id] of the .** m
16a30 6f 73 74 20 72 65 63 65 6e 74 20 73 75 63 63 65  ost recent succe
16a40 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 69  ssful [INSERT] i
16a50 6e 74 6f 20 61 20 72 6f 77 69 64 20 74 61 62 6c  nto a rowid tabl
16a60 65 20 6f 72 20 5b 76 69 72 74 75 61 6c 20 74 61  e or [virtual ta
16a70 62 6c 65 5d 0a 2a 2a 20 6f 6e 20 64 61 74 61 62  ble].** on datab
16a80 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44  ase connection D
16a90 2e 0a 2a 2a 20 5e 49 6e 73 65 72 74 73 20 69 6e  ..** ^Inserts in
16aa0 74 6f 20 5b 57 49 54 48 4f 55 54 20 52 4f 57 49  to [WITHOUT ROWI
16ab0 44 5d 20 74 61 62 6c 65 73 20 61 72 65 20 6e 6f  D] tables are no
16ac0 74 20 72 65 63 6f 72 64 65 64 2e 0a 2a 2a 20 5e  t recorded..** ^
16ad0 49 66 20 6e 6f 20 73 75 63 63 65 73 73 66 75 6c  If no successful
16ae0 20 5b 49 4e 53 45 52 54 5d 73 20 69 6e 74 6f 20   [INSERT]s into 
16af0 72 6f 77 69 64 20 74 61 62 6c 65 73 0a 2a 2a 20  rowid tables.** 
16b00 68 61 76 65 20 65 76 65 72 20 6f 63 63 75 72 72  have ever occurr
16b10 65 64 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61  ed on the databa
16b20 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2c  se connection D,
16b30 20 0a 2a 2a 20 74 68 65 6e 20 73 71 6c 69 74 65   .** then sqlite
16b40 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f  3_last_insert_ro
16b50 77 69 64 28 44 29 20 72 65 74 75 72 6e 73 20 7a  wid(D) returns z
16b60 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20  ero..**.** ^(If 
16b70 61 6e 20 5b 49 4e 53 45 52 54 5d 20 6f 63 63 75  an [INSERT] occu
16b80 72 73 20 77 69 74 68 69 6e 20 61 20 74 72 69 67  rs within a trig
16b90 67 65 72 20 6f 72 20 77 69 74 68 69 6e 20 61 20  ger or within a 
16ba0 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 0a  [virtual table].
16bb0 2a 2a 20 6d 65 74 68 6f 64 2c 20 74 68 65 6e 20  ** method, then 
16bc0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 6c  this routine wil
16bd0 6c 20 72 65 74 75 72 6e 20 74 68 65 20 5b 72 6f  l return the [ro
16be0 77 69 64 5d 20 6f 66 20 74 68 65 20 69 6e 73 65  wid] of the inse
16bf0 72 74 65 64 0a 2a 2a 20 72 6f 77 20 61 73 20 6c  rted.** row as l
16c00 6f 6e 67 20 61 73 20 74 68 65 20 74 72 69 67 67  ong as the trigg
16c10 65 72 20 6f 72 20 76 69 72 74 75 61 6c 20 74 61  er or virtual ta
16c20 62 6c 65 20 6d 65 74 68 6f 64 20 69 73 20 72 75  ble method is ru
16c30 6e 6e 69 6e 67 2e 0a 2a 2a 20 42 75 74 20 6f 6e  nning..** But on
16c40 63 65 20 74 68 65 20 74 72 69 67 67 65 72 20 6f  ce the trigger o
16c50 72 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20  r virtual table 
16c60 6d 65 74 68 6f 64 20 65 6e 64 73 2c 20 74 68 65  method ends, the
16c70 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
16c80 0a 2a 2a 20 62 79 20 74 68 69 73 20 72 6f 75 74  .** by this rout
16c90 69 6e 65 20 72 65 76 65 72 74 73 20 74 6f 20 77  ine reverts to w
16ca0 68 61 74 20 69 74 20 77 61 73 20 62 65 66 6f 72  hat it was befor
16cb0 65 20 74 68 65 20 74 72 69 67 67 65 72 20 6f 72  e the trigger or
16cc0 20 76 69 72 74 75 61 6c 0a 2a 2a 20 74 61 62 6c   virtual.** tabl
16cd0 65 20 6d 65 74 68 6f 64 20 62 65 67 61 6e 2e 29  e method began.)
16ce0 5e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b 49 4e 53  ^.**.** ^An [INS
16cf0 45 52 54 5d 20 74 68 61 74 20 66 61 69 6c 73 20  ERT] that fails 
16d00 64 75 65 20 74 6f 20 61 20 63 6f 6e 73 74 72 61  due to a constra
16d10 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 69 73  int violation is
16d20 20 6e 6f 74 20 61 0a 2a 2a 20 73 75 63 63 65 73   not a.** succes
16d30 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 61 6e  sful [INSERT] an
16d40 64 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67  d does not chang
16d50 65 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  e the value retu
16d60 72 6e 65 64 20 62 79 20 74 68 69 73 0a 2a 2a 20  rned by this.** 
16d70 72 6f 75 74 69 6e 65 2e 20 20 5e 54 68 75 73 20  routine.  ^Thus 
16d80 49 4e 53 45 52 54 20 4f 52 20 46 41 49 4c 2c 20  INSERT OR FAIL, 
16d90 49 4e 53 45 52 54 20 4f 52 20 49 47 4e 4f 52 45  INSERT OR IGNORE
16da0 2c 20 49 4e 53 45 52 54 20 4f 52 20 52 4f 4c 4c  , INSERT OR ROLL
16db0 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53  BACK,.** and INS
16dc0 45 52 54 20 4f 52 20 41 42 4f 52 54 20 6d 61 6b  ERT OR ABORT mak
16dd0 65 20 6e 6f 20 63 68 61 6e 67 65 73 20 74 6f 20  e no changes to 
16de0 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
16df0 20 6f 66 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74   of this.** rout
16e00 69 6e 65 20 77 68 65 6e 20 74 68 65 69 72 20 69  ine when their i
16e10 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 73 2e 20  nsertion fails. 
16e20 20 5e 28 57 68 65 6e 20 49 4e 53 45 52 54 20 4f   ^(When INSERT O
16e30 52 20 52 45 50 4c 41 43 45 0a 2a 2a 20 65 6e 63  R REPLACE.** enc
16e40 6f 75 6e 74 65 72 73 20 61 20 63 6f 6e 73 74 72  ounters a constr
16e50 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 2c 20  aint violation, 
16e60 69 74 20 64 6f 65 73 20 6e 6f 74 20 66 61 69 6c  it does not fail
16e70 2e 20 20 54 68 65 0a 2a 2a 20 49 4e 53 45 52 54  .  The.** INSERT
16e80 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63 6f   continues to co
16e90 6d 70 6c 65 74 69 6f 6e 20 61 66 74 65 72 20 64  mpletion after d
16ea0 65 6c 65 74 69 6e 67 20 72 6f 77 73 20 74 68 61  eleting rows tha
16eb0 74 20 63 61 75 73 65 64 0a 2a 2a 20 74 68 65 20  t caused.** the 
16ec0 63 6f 6e 73 74 72 61 69 6e 74 20 70 72 6f 62 6c  constraint probl
16ed0 65 6d 20 73 6f 20 49 4e 53 45 52 54 20 4f 52 20  em so INSERT OR 
16ee0 52 45 50 4c 41 43 45 20 77 69 6c 6c 20 61 6c 77  REPLACE will alw
16ef0 61 79 73 20 63 68 61 6e 67 65 0a 2a 2a 20 74 68  ays change.** th
16f00 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f  e return value o
16f10 66 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65  f this interface
16f20 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74  .)^.**.** ^For t
16f30 68 65 20 70 75 72 70 6f 73 65 73 20 6f 66 20 74  he purposes of t
16f40 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 61 6e 20  his routine, an 
16f50 5b 49 4e 53 45 52 54 5d 20 69 73 20 63 6f 6e 73  [INSERT] is cons
16f60 69 64 65 72 65 64 20 74 6f 0a 2a 2a 20 62 65 20  idered to.** be 
16f70 73 75 63 63 65 73 73 66 75 6c 20 65 76 65 6e 20  successful even 
16f80 69 66 20 69 74 20 69 73 20 73 75 62 73 65 71 75  if it is subsequ
16f90 65 6e 74 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63  ently rolled bac
16fa0 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75  k..**.** This fu
16fb0 6e 63 74 69 6f 6e 20 69 73 20 61 63 63 65 73 73  nction is access
16fc0 69 62 6c 65 20 74 6f 20 53 51 4c 20 73 74 61 74  ible to SQL stat
16fd0 65 6d 65 6e 74 73 20 76 69 61 20 74 68 65 0a 2a  ements via the.*
16fe0 2a 20 5b 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72  * [last_insert_r
16ff0 6f 77 69 64 28 29 20 53 51 4c 20 66 75 6e 63 74  owid() SQL funct
17000 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61  ion]..**.** If a
17010 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64   separate thread
17020 20 70 65 72 66 6f 72 6d 73 20 61 20 6e 65 77 20   performs a new 
17030 5b 49 4e 53 45 52 54 5d 20 6f 6e 20 74 68 65 20  [INSERT] on the 
17040 73 61 6d 65 0a 2a 2a 20 64 61 74 61 62 61 73 65  same.** database
17050 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c   connection whil
17060 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c  e the [sqlite3_l
17070 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
17080 28 29 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ()].** function 
17090 69 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20 74  is running and t
170a0 68 75 73 20 63 68 61 6e 67 65 73 20 74 68 65 20  hus changes the 
170b0 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77  last insert [row
170c0 69 64 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65  id],.** then the
170d0 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
170e0 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74  by [sqlite3_last
170f0 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d  _insert_rowid()]
17100 20 69 73 0a 2a 2a 20 75 6e 70 72 65 64 69 63 74   is.** unpredict
17110 61 62 6c 65 20 61 6e 64 20 6d 69 67 68 74 20 6e  able and might n
17120 6f 74 20 65 71 75 61 6c 20 65 69 74 68 65 72 20  ot equal either 
17130 74 68 65 20 6f 6c 64 20 6f 72 20 74 68 65 20 6e  the old or the n
17140 65 77 0a 2a 2a 20 6c 61 73 74 20 69 6e 73 65 72  ew.** last inser
17150 74 20 5b 72 6f 77 69 64 5d 2e 0a 2a 2f 0a 73 71  t [rowid]..*/.sq
17160 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69  lite3_int64 sqli
17170 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f  te3_last_insert_
17180 72 6f 77 69 64 28 73 71 6c 69 74 65 33 2a 29 3b  rowid(sqlite3*);
17190 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
171a0 3a 20 43 6f 75 6e 74 20 54 68 65 20 4e 75 6d 62  : Count The Numb
171b0 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66  er Of Rows Modif
171c0 69 65 64 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  ied.**.** ^This 
171d0 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
171e0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 64   the number of d
171f0 61 74 61 62 61 73 65 20 72 6f 77 73 20 74 68 61  atabase rows tha
17200 74 20 77 65 72 65 20 63 68 61 6e 67 65 64 0a 2a  t were changed.*
17210 2a 20 6f 72 20 69 6e 73 65 72 74 65 64 20 6f 72  * or inserted or
17220 20 64 65 6c 65 74 65 64 20 62 79 20 74 68 65 20   deleted by the 
17230 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f  most recently co
17240 6d 70 6c 65 74 65 64 20 53 51 4c 20 73 74 61 74  mpleted SQL stat
17250 65 6d 65 6e 74 0a 2a 2a 20 6f 6e 20 74 68 65 20  ement.** on the 
17260 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
17270 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20  tion] specified 
17280 62 79 20 74 68 65 20 66 69 72 73 74 20 70 61 72  by the first par
17290 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 28 4f 6e 6c  ameter..** ^(Onl
172a0 79 20 63 68 61 6e 67 65 73 20 74 68 61 74 20 61  y changes that a
172b0 72 65 20 64 69 72 65 63 74 6c 79 20 73 70 65 63  re directly spec
172c0 69 66 69 65 64 20 62 79 20 74 68 65 20 5b 49 4e  ified by the [IN
172d0 53 45 52 54 5d 2c 20 5b 55 50 44 41 54 45 5d 2c  SERT], [UPDATE],
172e0 0a 2a 2a 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20  .** or [DELETE] 
172f0 73 74 61 74 65 6d 65 6e 74 20 61 72 65 20 63 6f  statement are co
17300 75 6e 74 65 64 2e 20 20 41 75 78 69 6c 69 61 72  unted.  Auxiliar
17310 79 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 64  y changes caused
17320 20 62 79 0a 2a 2a 20 74 72 69 67 67 65 72 73 20   by.** triggers 
17330 6f 72 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20  or [foreign key 
17340 61 63 74 69 6f 6e 73 5d 20 61 72 65 20 6e 6f 74  actions] are not
17350 20 63 6f 75 6e 74 65 64 2e 29 5e 20 55 73 65 20   counted.)^ Use 
17360 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
17370 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d  total_changes()]
17380 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 66 69 6e   function to fin
17390 64 20 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62  d the total numb
173a0 65 72 20 6f 66 20 63 68 61 6e 67 65 73 0a 2a 2a  er of changes.**
173b0 20 69 6e 63 6c 75 64 69 6e 67 20 63 68 61 6e 67   including chang
173c0 65 73 20 63 61 75 73 65 64 20 62 79 20 74 72 69  es caused by tri
173d0 67 67 65 72 73 20 61 6e 64 20 66 6f 72 65 69 67  ggers and foreig
173e0 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 2e 0a 2a  n key actions..*
173f0 2a 0a 2a 2a 20 5e 43 68 61 6e 67 65 73 20 74 6f  *.** ^Changes to
17400 20 61 20 76 69 65 77 20 74 68 61 74 20 61 72 65   a view that are
17410 20 73 69 6d 75 6c 61 74 65 64 20 62 79 20 61 6e   simulated by an
17420 20 5b 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69   [INSTEAD OF tri
17430 67 67 65 72 5d 0a 2a 2a 20 61 72 65 20 6e 6f 74  gger].** are not
17440 20 63 6f 75 6e 74 65 64 2e 20 20 4f 6e 6c 79 20   counted.  Only 
17450 72 65 61 6c 20 74 61 62 6c 65 20 63 68 61 6e 67  real table chang
17460 65 73 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 0a  es are counted..
17470 2a 2a 0a 2a 2a 20 5e 28 41 20 22 72 6f 77 20 63  **.** ^(A "row c
17480 68 61 6e 67 65 22 20 69 73 20 61 20 63 68 61 6e  hange" is a chan
17490 67 65 20 74 6f 20 61 20 73 69 6e 67 6c 65 20 72  ge to a single r
174a0 6f 77 20 6f 66 20 61 20 73 69 6e 67 6c 65 20 74  ow of a single t
174b0 61 62 6c 65 0a 2a 2a 20 63 61 75 73 65 64 20 62  able.** caused b
174c0 79 20 61 6e 20 49 4e 53 45 52 54 2c 20 44 45 4c  y an INSERT, DEL
174d0 45 54 45 2c 20 6f 72 20 55 50 44 41 54 45 20 73  ETE, or UPDATE s
174e0 74 61 74 65 6d 65 6e 74 2e 20 20 52 6f 77 73 20  tatement.  Rows 
174f0 74 68 61 74 0a 2a 2a 20 61 72 65 20 63 68 61 6e  that.** are chan
17500 67 65 64 20 61 73 20 73 69 64 65 20 65 66 66 65  ged as side effe
17510 63 74 73 20 6f 66 20 5b 52 45 50 4c 41 43 45 5d  cts of [REPLACE]
17520 20 63 6f 6e 73 74 72 61 69 6e 74 20 72 65 73 6f   constraint reso
17530 6c 75 74 69 6f 6e 2c 0a 2a 2a 20 72 6f 6c 6c 62  lution,.** rollb
17540 61 63 6b 2c 20 41 42 4f 52 54 20 70 72 6f 63 65  ack, ABORT proce
17550 73 73 69 6e 67 2c 20 5b 44 52 4f 50 20 54 41 42  ssing, [DROP TAB
17560 4c 45 5d 2c 20 6f 72 20 62 79 20 61 6e 79 20 6f  LE], or by any o
17570 74 68 65 72 0a 2a 2a 20 6d 65 63 68 61 6e 69 73  ther.** mechanis
17580 6d 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20  ms do not count 
17590 61 73 20 64 69 72 65 63 74 20 72 6f 77 20 63 68  as direct row ch
175a0 61 6e 67 65 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41  anges.)^.**.** A
175b0 20 22 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78   "trigger contex
175c0 74 22 20 69 73 20 61 20 73 63 6f 70 65 20 6f 66  t" is a scope of
175d0 20 65 78 65 63 75 74 69 6f 6e 20 74 68 61 74 20   execution that 
175e0 62 65 67 69 6e 73 20 61 6e 64 0a 2a 2a 20 65 6e  begins and.** en
175f0 64 73 20 77 69 74 68 20 74 68 65 20 73 63 72 69  ds with the scri
17600 70 74 20 6f 66 20 61 20 5b 43 52 45 41 54 45 20  pt of a [CREATE 
17610 54 52 49 47 47 45 52 20 7c 20 74 72 69 67 67 65  TRIGGER | trigge
17620 72 5d 2e 20 0a 2a 2a 20 4d 6f 73 74 20 53 51 4c  r]. .** Most SQL
17630 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 0a   statements are.
17640 2a 2a 20 65 76 61 6c 75 61 74 65 64 20 6f 75 74  ** evaluated out
17650 73 69 64 65 20 6f 66 20 61 6e 79 20 74 72 69 67  side of any trig
17660 67 65 72 2e 20 20 54 68 69 73 20 69 73 20 74 68  ger.  This is th
17670 65 20 22 74 6f 70 20 6c 65 76 65 6c 22 0a 2a 2a  e "top level".**
17680 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74   trigger context
17690 2e 20 20 49 66 20 61 20 74 72 69 67 67 65 72 20  .  If a trigger 
176a0 66 69 72 65 73 20 66 72 6f 6d 20 74 68 65 20 74  fires from the t
176b0 6f 70 20 6c 65 76 65 6c 2c 20 61 0a 2a 2a 20 6e  op level, a.** n
176c0 65 77 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65  ew trigger conte
176d0 78 74 20 69 73 20 65 6e 74 65 72 65 64 20 66 6f  xt is entered fo
176e0 72 20 74 68 65 20 64 75 72 61 74 69 6f 6e 20 6f  r the duration o
176f0 66 20 74 68 61 74 20 6f 6e 65 0a 2a 2a 20 74 72  f that one.** tr
17700 69 67 67 65 72 2e 20 20 53 75 62 74 72 69 67 67  igger.  Subtrigg
17710 65 72 73 20 63 72 65 61 74 65 20 73 75 62 63 6f  ers create subco
17720 6e 74 65 78 74 73 20 66 6f 72 20 74 68 65 69 72  ntexts for their
17730 20 64 75 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a   duration..**.**
17740 20 5e 43 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74   ^Calling [sqlit
17750 65 33 5f 65 78 65 63 28 29 5d 20 6f 72 20 5b 73  e3_exec()] or [s
17760 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 72  qlite3_step()] r
17770 65 63 75 72 73 69 76 65 6c 79 20 64 6f 65 73 0a  ecursively does.
17780 2a 2a 20 6e 6f 74 20 63 72 65 61 74 65 20 61 20  ** not create a 
17790 6e 65 77 20 74 72 69 67 67 65 72 20 63 6f 6e 74  new trigger cont
177a0 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  ext..**.** ^This
177b0 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
177c0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
177d0 64 69 72 65 63 74 20 72 6f 77 20 63 68 61 6e 67  direct row chang
177e0 65 73 20 69 6e 20 74 68 65 0a 2a 2a 20 6d 6f 73  es in the.** mos
177f0 74 20 72 65 63 65 6e 74 20 49 4e 53 45 52 54 2c  t recent INSERT,
17800 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45   UPDATE, or DELE
17810 54 45 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74  TE statement wit
17820 68 69 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20  hin the same.** 
17830 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e  trigger context.
17840 0a 2a 2a 0a 2a 2a 20 5e 54 68 75 73 2c 20 77 68  .**.** ^Thus, wh
17850 65 6e 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74  en called from t
17860 68 65 20 74 6f 70 20 6c 65 76 65 6c 2c 20 74 68  he top level, th
17870 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  is function retu
17880 72 6e 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65  rns the.** numbe
17890 72 20 6f 66 20 63 68 61 6e 67 65 73 20 69 6e 20  r of changes in 
178a0 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
178b0 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20  INSERT, UPDATE, 
178c0 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61  or DELETE.** tha
178d0 74 20 61 6c 73 6f 20 6f 63 63 75 72 72 65 64 20  t also occurred 
178e0 61 74 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c  at the top level
178f0 2e 20 20 5e 28 57 69 74 68 69 6e 20 74 68 65 20  .  ^(Within the 
17900 62 6f 64 79 20 6f 66 20 61 20 74 72 69 67 67 65  body of a trigge
17910 72 2c 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65  r,.** the sqlite
17920 33 5f 63 68 61 6e 67 65 73 28 29 20 69 6e 74 65  3_changes() inte
17930 72 66 61 63 65 20 63 61 6e 20 62 65 20 63 61 6c  rface can be cal
17940 6c 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20  led to find the 
17950 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61  number of.** cha
17960 6e 67 65 73 20 69 6e 20 74 68 65 20 6d 6f 73 74  nges in the most
17970 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65   recently comple
17980 74 65 64 20 49 4e 53 45 52 54 2c 20 55 50 44 41  ted INSERT, UPDA
17990 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a  TE, or DELETE.**
179a0 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69   statement withi
179b0 6e 20 74 68 65 20 62 6f 64 79 20 6f 66 20 74 68  n the body of th
179c0 65 20 73 61 6d 65 20 74 72 69 67 67 65 72 2e 0a  e same trigger..
179d0 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20  ** However, the 
179e0 6e 75 6d 62 65 72 20 72 65 74 75 72 6e 65 64 20  number returned 
179f0 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65  does not include
17a00 20 63 68 61 6e 67 65 73 0a 2a 2a 20 63 61 75 73   changes.** caus
17a10 65 64 20 62 79 20 73 75 62 74 72 69 67 67 65 72  ed by subtrigger
17a20 73 20 73 69 6e 63 65 20 74 68 6f 73 65 20 68 61  s since those ha
17a30 76 65 20 74 68 65 69 72 20 6f 77 6e 20 63 6f 6e  ve their own con
17a40 74 65 78 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65  text.)^.**.** Se
17a50 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69  e also the [sqli
17a60 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
17a70 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2c 20  s()] interface, 
17a80 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68  the.** [count_ch
17a90 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c 20 61  anges pragma], a
17aa0 6e 64 20 74 68 65 20 5b 63 68 61 6e 67 65 73 28  nd the [changes(
17ab0 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e  ) SQL function].
17ac0 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61  .**.** If a sepa
17ad0 72 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65  rate thread make
17ae0 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65  s changes on the
17af0 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63   same database c
17b00 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69  onnection.** whi
17b10 6c 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e  le [sqlite3_chan
17b20 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e  ges()] is runnin
17b30 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65  g then the value
17b40 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 69 73 20   returned.** is 
17b50 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e  unpredictable an
17b60 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c  d not meaningful
17b70 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
17b80 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33  _changes(sqlite3
17b90 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
17ba0 52 45 46 3a 20 54 6f 74 61 6c 20 4e 75 6d 62 65  REF: Total Numbe
17bb0 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69  r Of Rows Modifi
17bc0 65 64 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66  ed.**.** ^This f
17bd0 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
17be0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f  the number of ro
17bf0 77 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 64  w changes caused
17c00 20 62 79 20 5b 49 4e 53 45 52 54 5d 2c 0a 2a 2a   by [INSERT],.**
17c10 20 5b 55 50 44 41 54 45 5d 20 6f 72 20 5b 44 45   [UPDATE] or [DE
17c20 4c 45 54 45 5d 20 73 74 61 74 65 6d 65 6e 74 73  LETE] statements
17c30 20 73 69 6e 63 65 20 74 68 65 20 5b 64 61 74 61   since the [data
17c40 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
17c50 20 77 61 73 20 6f 70 65 6e 65 64 2e 0a 2a 2a 20   was opened..** 
17c60 5e 28 54 68 65 20 63 6f 75 6e 74 20 72 65 74 75  ^(The count retu
17c70 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
17c80 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 20  total_changes() 
17c90 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 63 68 61  includes all cha
17ca0 6e 67 65 73 0a 2a 2a 20 66 72 6f 6d 20 61 6c 6c  nges.** from all
17cb0 20 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 52   [CREATE TRIGGER
17cc0 20 7c 20 74 72 69 67 67 65 72 5d 20 63 6f 6e 74   | trigger] cont
17cd0 65 78 74 73 20 61 6e 64 20 63 68 61 6e 67 65 73  exts and changes
17ce0 20 6d 61 64 65 20 62 79 0a 2a 2a 20 5b 66 6f 72   made by.** [for
17cf0 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73  eign key actions
17d00 5d 2e 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 74  ]. However,.** t
17d10 68 65 20 63 6f 75 6e 74 20 64 6f 65 73 20 6e 6f  he count does no
17d20 74 20 69 6e 63 6c 75 64 65 20 63 68 61 6e 67 65  t include change
17d30 73 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d  s used to implem
17d40 65 6e 74 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f  ent [REPLACE] co
17d50 6e 73 74 72 61 69 6e 74 73 2c 0a 2a 2a 20 64 6f  nstraints,.** do
17d60 20 72 6f 6c 6c 62 61 63 6b 73 20 6f 72 20 41 42   rollbacks or AB
17d70 4f 52 54 20 70 72 6f 63 65 73 73 69 6e 67 2c 20  ORT processing, 
17d80 6f 72 20 5b 44 52 4f 50 20 54 41 42 4c 45 5d 20  or [DROP TABLE] 
17d90 70 72 6f 63 65 73 73 69 6e 67 2e 20 20 54 68 65  processing.  The
17da0 0a 2a 2a 20 63 6f 75 6e 74 20 64 6f 65 73 20 6e  .** count does n
17db0 6f 74 20 69 6e 63 6c 75 64 65 20 72 6f 77 73 20  ot include rows 
17dc0 6f 66 20 76 69 65 77 73 20 74 68 61 74 20 66 69  of views that fi
17dd0 72 65 20 61 6e 20 5b 49 4e 53 54 45 41 44 20 4f  re an [INSTEAD O
17de0 46 20 74 72 69 67 67 65 72 5d 2c 0a 2a 2a 20 74  F trigger],.** t
17df0 68 6f 75 67 68 20 69 66 20 74 68 65 20 49 4e 53  hough if the INS
17e00 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 72 20  TEAD OF trigger 
17e10 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 66  makes changes of
17e20 20 69 74 73 20 6f 77 6e 2c 20 74 68 6f 73 65 20   its own, those 
17e30 63 68 61 6e 67 65 73 20 0a 2a 2a 20 61 72 65 20  changes .** are 
17e40 63 6f 75 6e 74 65 64 2e 29 5e 0a 2a 2a 20 5e 54  counted.)^.** ^T
17e50 68 65 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c  he sqlite3_total
17e60 5f 63 68 61 6e 67 65 73 28 29 20 66 75 6e 63 74  _changes() funct
17e70 69 6f 6e 20 63 6f 75 6e 74 73 20 74 68 65 20 63  ion counts the c
17e80 68 61 6e 67 65 73 20 61 73 20 73 6f 6f 6e 20 61  hanges as soon a
17e90 73 0a 2a 2a 20 74 68 65 20 73 74 61 74 65 6d 65  s.** the stateme
17ea0 6e 74 20 74 68 61 74 20 6d 61 6b 65 73 20 74 68  nt that makes th
17eb0 65 6d 20 69 73 20 63 6f 6d 70 6c 65 74 65 64 20  em is completed 
17ec0 28 77 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d  (when the statem
17ed0 65 6e 74 20 68 61 6e 64 6c 65 0a 2a 2a 20 69 73  ent handle.** is
17ee0 20 70 61 73 73 65 64 20 74 6f 20 5b 73 71 6c 69   passed to [sqli
17ef0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20  te3_reset()] or 
17f00 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
17f10 65 28 29 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  e()])..**.** See
17f20 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74   also the [sqlit
17f30 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e  e3_changes()] in
17f40 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20  terface, the.** 
17f50 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70  [count_changes p
17f60 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20  ragma], and the 
17f70 5b 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29  [total_changes()
17f80 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a   SQL function]..
17f90 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72  **.** If a separ
17fa0 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73  ate thread makes
17fb0 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20   changes on the 
17fc0 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f  same database co
17fd0 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c  nnection.** whil
17fe0 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c  e [sqlite3_total
17ff0 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72  _changes()] is r
18000 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20  unning then the 
18010 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65  value.** returne
18020 64 20 69 73 20 75 6e 70 72 65 64 69 63 74 61 62  d is unpredictab
18030 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69  le and not meani
18040 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ngful..*/.int sq
18050 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e  lite3_total_chan
18060 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  ges(sqlite3*);..
18070 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
18080 49 6e 74 65 72 72 75 70 74 20 41 20 4c 6f 6e 67  Interrupt A Long
18090 2d 52 75 6e 6e 69 6e 67 20 51 75 65 72 79 0a 2a  -Running Query.*
180a0 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74  *.** ^This funct
180b0 69 6f 6e 20 63 61 75 73 65 73 20 61 6e 79 20 70  ion causes any p
180c0 65 6e 64 69 6e 67 20 64 61 74 61 62 61 73 65 20  ending database 
180d0 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 61 62 6f  operation to abo
180e0 72 74 20 61 6e 64 0a 2a 2a 20 72 65 74 75 72 6e  rt and.** return
180f0 20 61 74 20 69 74 73 20 65 61 72 6c 69 65 73 74   at its earliest
18100 20 6f 70 70 6f 72 74 75 6e 69 74 79 2e 20 54 68   opportunity. Th
18110 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 74 79  is routine is ty
18120 70 69 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65  pically.** calle
18130 64 20 69 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f  d in response to
18140 20 61 20 75 73 65 72 20 61 63 74 69 6f 6e 20 73   a user action s
18150 75 63 68 20 61 73 20 70 72 65 73 73 69 6e 67 20  uch as pressing 
18160 22 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43  "Cancel".** or C
18170 74 72 6c 2d 43 20 77 68 65 72 65 20 74 68 65 20  trl-C where the 
18180 75 73 65 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e  user wants a lon
18190 67 20 71 75 65 72 79 20 6f 70 65 72 61 74 69 6f  g query operatio
181a0 6e 20 74 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d  n to halt.** imm
181b0 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20  ediately..**.** 
181c0 5e 49 74 20 69 73 20 73 61 66 65 20 74 6f 20 63  ^It is safe to c
181d0 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65  all this routine
181e0 20 66 72 6f 6d 20 61 20 74 68 72 65 61 64 20 64   from a thread d
181f0 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 74 68  ifferent from th
18200 65 0a 2a 2a 20 74 68 72 65 61 64 20 74 68 61 74  e.** thread that
18210 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 72 75   is currently ru
18220 6e 6e 69 6e 67 20 74 68 65 20 64 61 74 61 62 61  nning the databa
18230 73 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20 42  se operation.  B
18240 75 74 20 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 20  ut it.** is not 
18250 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69  safe to call thi
18260 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61  s routine with a
18270 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
18280 63 74 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20 69  ction] that.** i
18290 73 20 63 6c 6f 73 65 64 20 6f 72 20 6d 69 67 68  s closed or migh
182a0 74 20 63 6c 6f 73 65 20 62 65 66 6f 72 65 20 73  t close before s
182b0 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
182c0 28 29 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a  () returns..**.*
182d0 2a 20 5e 49 66 20 61 6e 20 53 51 4c 20 6f 70 65  * ^If an SQL ope
182e0 72 61 74 69 6f 6e 20 69 73 20 76 65 72 79 20 6e  ration is very n
182f0 65 61 72 6c 79 20 66 69 6e 69 73 68 65 64 20 61  early finished a
18300 74 20 74 68 65 20 74 69 6d 65 20 77 68 65 6e 0a  t the time when.
18310 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  ** sqlite3_inter
18320 72 75 70 74 28 29 20 69 73 20 63 61 6c 6c 65 64  rupt() is called
18330 2c 20 74 68 65 6e 20 69 74 20 6d 69 67 68 74 20  , then it might 
18340 6e 6f 74 20 68 61 76 65 20 61 6e 20 6f 70 70 6f  not have an oppo
18350 72 74 75 6e 69 74 79 0a 2a 2a 20 74 6f 20 62 65  rtunity.** to be
18360 20 69 6e 74 65 72 72 75 70 74 65 64 20 61 6e 64   interrupted and
18370 20 6d 69 67 68 74 20 63 6f 6e 74 69 6e 75 65 20   might continue 
18380 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a  to completion..*
18390 2a 0a 2a 2a 20 5e 41 6e 20 53 51 4c 20 6f 70 65  *.** ^An SQL ope
183a0 72 61 74 69 6f 6e 20 74 68 61 74 20 69 73 20 69  ration that is i
183b0 6e 74 65 72 72 75 70 74 65 64 20 77 69 6c 6c 20  nterrupted will 
183c0 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49  return [SQLITE_I
183d0 4e 54 45 52 52 55 50 54 5d 2e 0a 2a 2a 20 5e 49  NTERRUPT]..** ^I
183e0 66 20 74 68 65 20 69 6e 74 65 72 72 75 70 74 65  f the interrupte
183f0 64 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20  d SQL operation 
18400 69 73 20 61 6e 20 49 4e 53 45 52 54 2c 20 55 50  is an INSERT, UP
18410 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a  DATE, or DELETE.
18420 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 73 69 64  ** that is insid
18430 65 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72  e an explicit tr
18440 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20  ansaction, then 
18450 74 68 65 20 65 6e 74 69 72 65 20 74 72 61 6e 73  the entire trans
18460 61 63 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62  action.** will b
18470 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75  e rolled back au
18480 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a  tomatically..**.
18490 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
184a0 69 6e 74 65 72 72 75 70 74 28 44 29 20 63 61 6c  interrupt(D) cal
184b0 6c 20 69 73 20 69 6e 20 65 66 66 65 63 74 20 75  l is in effect u
184c0 6e 74 69 6c 20 61 6c 6c 20 63 75 72 72 65 6e 74  ntil all current
184d0 6c 79 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51  ly running.** SQ
184e0 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 6e 20  L statements on 
184f0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
18500 74 69 6f 6e 5d 20 44 20 63 6f 6d 70 6c 65 74 65  tion] D complete
18510 2e 20 20 5e 41 6e 79 20 6e 65 77 20 53 51 4c 20  .  ^Any new SQL 
18520 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68  statements.** th
18530 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61  at are started a
18540 66 74 65 72 20 74 68 65 20 73 71 6c 69 74 65 33  fter the sqlite3
18550 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c  _interrupt() cal
18560 6c 20 61 6e 64 20 62 65 66 6f 72 65 20 74 68 65  l and before the
18570 20 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 73 74 61   .** running sta
18580 74 65 6d 65 6e 74 73 20 72 65 61 63 68 65 73 20  tements reaches 
18590 7a 65 72 6f 20 61 72 65 20 69 6e 74 65 72 72 75  zero are interru
185a0 70 74 65 64 20 61 73 20 69 66 20 74 68 65 79 20  pted as if they 
185b0 68 61 64 20 62 65 65 6e 0a 2a 2a 20 72 75 6e 6e  had been.** runn
185c0 69 6e 67 20 70 72 69 6f 72 20 74 6f 20 74 68 65  ing prior to the
185d0 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
185e0 70 74 28 29 20 63 61 6c 6c 2e 20 20 5e 4e 65 77  pt() call.  ^New
185f0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a   SQL statements.
18600 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72  ** that are star
18610 74 65 64 20 61 66 74 65 72 20 74 68 65 20 72 75  ted after the ru
18620 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20  nning statement 
18630 63 6f 75 6e 74 20 72 65 61 63 68 65 73 20 7a 65  count reaches ze
18640 72 6f 20 61 72 65 0a 2a 2a 20 6e 6f 74 20 65 66  ro are.** not ef
18650 66 65 63 74 65 64 20 62 79 20 74 68 65 20 73 71  fected by the sq
18660 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
18670 29 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f  )..** ^A call to
18680 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
18690 70 74 28 44 29 20 74 68 61 74 20 6f 63 63 75 72  pt(D) that occur
186a0 73 20 77 68 65 6e 20 74 68 65 72 65 20 61 72 65  s when there are
186b0 20 6e 6f 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53   no running.** S
186c0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69 73  QL statements is
186d0 20 61 20 6e 6f 2d 6f 70 20 61 6e 64 20 68 61 73   a no-op and has
186e0 20 6e 6f 20 65 66 66 65 63 74 20 6f 6e 20 53 51   no effect on SQ
186f0 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  L statements.** 
18700 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64  that are started
18710 20 61 66 74 65 72 20 74 68 65 20 73 71 6c 69 74   after the sqlit
18720 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63  e3_interrupt() c
18730 61 6c 6c 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a  all returns..**.
18740 2a 2a 20 49 66 20 74 68 65 20 64 61 74 61 62 61  ** If the databa
18750 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c  se connection cl
18760 6f 73 65 73 20 77 68 69 6c 65 20 5b 73 71 6c 69  oses while [sqli
18770 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 5d  te3_interrupt()]
18780 0a 2a 2a 20 69 73 20 72 75 6e 6e 69 6e 67 20 74  .** is running t
18790 68 65 6e 20 62 61 64 20 74 68 69 6e 67 73 20 77  hen bad things w
187a0 69 6c 6c 20 6c 69 6b 65 6c 79 20 68 61 70 70 65  ill likely happe
187b0 6e 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74  n..*/.void sqlit
187c0 65 33 5f 69 6e 74 65 72 72 75 70 74 28 73 71 6c  e3_interrupt(sql
187d0 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
187e0 41 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69  API3REF: Determi
187f0 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61  ne If An SQL Sta
18800 74 65 6d 65 6e 74 20 49 73 20 43 6f 6d 70 6c 65  tement Is Comple
18810 74 65 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  te.**.** These r
18820 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 66  outines are usef
18830 75 6c 20 64 75 72 69 6e 67 20 63 6f 6d 6d 61 6e  ul during comman
18840 64 2d 6c 69 6e 65 20 69 6e 70 75 74 20 74 6f 20  d-line input to 
18850 64 65 74 65 72 6d 69 6e 65 20 69 66 20 74 68 65  determine if the
18860 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 65 6e  .** currently en
18870 74 65 72 65 64 20 74 65 78 74 20 73 65 65 6d 73  tered text seems
18880 20 74 6f 20 66 6f 72 6d 20 61 20 63 6f 6d 70 6c   to form a compl
18890 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ete SQL statemen
188a0 74 20 6f 72 0a 2a 2a 20 69 66 20 61 64 64 69 74  t or.** if addit
188b0 69 6f 6e 61 6c 20 69 6e 70 75 74 20 69 73 20 6e  ional input is n
188c0 65 65 64 65 64 20 62 65 66 6f 72 65 20 73 65 6e  eeded before sen
188d0 64 69 6e 67 20 74 68 65 20 74 65 78 74 20 69 6e  ding the text in
188e0 74 6f 0a 2a 2a 20 53 51 4c 69 74 65 20 66 6f 72  to.** SQLite for
188f0 20 70 61 72 73 69 6e 67 2e 20 20 5e 54 68 65 73   parsing.  ^Thes
18900 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  e routines retur
18910 6e 20 31 20 69 66 20 74 68 65 20 69 6e 70 75 74  n 1 if the input
18920 20 73 74 72 69 6e 67 0a 2a 2a 20 61 70 70 65 61   string.** appea
18930 72 73 20 74 6f 20 62 65 20 61 20 63 6f 6d 70 6c  rs to be a compl
18940 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ete SQL statemen
18950 74 2e 20 20 5e 41 20 73 74 61 74 65 6d 65 6e 74  t.  ^A statement
18960 20 69 73 20 6a 75 64 67 65 64 20 74 6f 20 62 65   is judged to be
18970 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 69 66 20  .** complete if 
18980 69 74 20 65 6e 64 73 20 77 69 74 68 20 61 20 73  it ends with a s
18990 65 6d 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61  emicolon token a
189a0 6e 64 20 69 73 20 6e 6f 74 20 61 20 70 72 65 66  nd is not a pref
189b0 69 78 20 6f 66 20 61 0a 2a 2a 20 77 65 6c 6c 2d  ix of a.** well-
189c0 66 6f 72 6d 65 64 20 43 52 45 41 54 45 20 54 52  formed CREATE TR
189d0 49 47 47 45 52 20 73 74 61 74 65 6d 65 6e 74 2e  IGGER statement.
189e0 20 20 5e 53 65 6d 69 63 6f 6c 6f 6e 73 20 74 68    ^Semicolons th
189f0 61 74 20 61 72 65 20 65 6d 62 65 64 64 65 64 20  at are embedded 
18a00 77 69 74 68 69 6e 0a 2a 2a 20 73 74 72 69 6e 67  within.** string
18a10 20 6c 69 74 65 72 61 6c 73 20 6f 72 20 71 75 6f   literals or quo
18a20 74 65 64 20 69 64 65 6e 74 69 66 69 65 72 20 6e  ted identifier n
18a30 61 6d 65 73 20 6f 72 20 63 6f 6d 6d 65 6e 74 73  ames or comments
18a40 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65   are not.** inde
18a50 70 65 6e 64 65 6e 74 20 74 6f 6b 65 6e 73 20 28  pendent tokens (
18a60 74 68 65 79 20 61 72 65 20 70 61 72 74 20 6f 66  they are part of
18a70 20 74 68 65 20 74 6f 6b 65 6e 20 69 6e 20 77 68   the token in wh
18a80 69 63 68 20 74 68 65 79 20 61 72 65 0a 2a 2a 20  ich they are.** 
18a90 65 6d 62 65 64 64 65 64 29 20 61 6e 64 20 74 68  embedded) and th
18aa0 75 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20  us do not count 
18ab0 61 73 20 61 20 73 74 61 74 65 6d 65 6e 74 20 74  as a statement t
18ac0 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 57 68 69  erminator.  ^Whi
18ad0 74 65 73 70 61 63 65 0a 2a 2a 20 61 6e 64 20 63  tespace.** and c
18ae0 6f 6d 6d 65 6e 74 73 20 74 68 61 74 20 66 6f 6c  omments that fol
18af0 6c 6f 77 20 74 68 65 20 66 69 6e 61 6c 20 73 65  low the final se
18b00 6d 69 63 6f 6c 6f 6e 20 61 72 65 20 69 67 6e 6f  micolon are igno
18b10 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  red..**.** ^Thes
18b20 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  e routines retur
18b30 6e 20 30 20 69 66 20 74 68 65 20 73 74 61 74 65  n 0 if the state
18b40 6d 65 6e 74 20 69 73 20 69 6e 63 6f 6d 70 6c 65  ment is incomple
18b50 74 65 2e 20 20 5e 49 66 20 61 0a 2a 2a 20 6d 65  te.  ^If a.** me
18b60 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
18b70 66 61 69 6c 73 2c 20 74 68 65 6e 20 53 51 4c 49  fails, then SQLI
18b80 54 45 5f 4e 4f 4d 45 4d 20 69 73 20 72 65 74 75  TE_NOMEM is retu
18b90 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  rned..**.** ^The
18ba0 73 65 20 72 6f 75 74 69 6e 65 73 20 64 6f 20 6e  se routines do n
18bb0 6f 74 20 70 61 72 73 65 20 74 68 65 20 53 51 4c  ot parse the SQL
18bc0 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 75 73   statements thus
18bd0 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20 64 65 74  .** will not det
18be0 65 63 74 20 73 79 6e 74 61 63 74 69 63 61 6c 6c  ect syntacticall
18bf0 79 20 69 6e 63 6f 72 72 65 63 74 20 53 51 4c 2e  y incorrect SQL.
18c00 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 53 51 4c 69  .**.** ^(If SQLi
18c10 74 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20  te has not been 
18c20 69 6e 69 74 69 61 6c 69 7a 65 64 20 75 73 69 6e  initialized usin
18c30 67 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  g [sqlite3_initi
18c40 61 6c 69 7a 65 28 29 5d 20 70 72 69 6f 72 20 0a  alize()] prior .
18c50 2a 2a 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 20 73  ** to invoking s
18c60 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31  qlite3_complete1
18c70 36 28 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33  6() then sqlite3
18c80 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73  _initialize() is
18c90 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 75 74 6f   invoked.** auto
18ca0 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c  matically by sql
18cb0 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28  ite3_complete16(
18cc0 29 2e 20 20 49 66 20 74 68 61 74 20 69 6e 69 74  ).  If that init
18cd0 69 61 6c 69 7a 61 74 69 6f 6e 20 66 61 69 6c 73  ialization fails
18ce0 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 72 65  ,.** then the re
18cf0 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20  turn value from 
18d00 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
18d10 31 36 28 29 20 77 69 6c 6c 20 62 65 20 6e 6f 6e  16() will be non
18d20 2d 7a 65 72 6f 0a 2a 2a 20 72 65 67 61 72 64 6c  -zero.** regardl
18d30 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f  ess of whether o
18d40 72 20 6e 6f 74 20 74 68 65 20 69 6e 70 75 74 20  r not the input 
18d50 53 51 4c 20 69 73 20 63 6f 6d 70 6c 65 74 65 2e  SQL is complete.
18d60 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70  )^.**.** The inp
18d70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ut to [sqlite3_c
18d80 6f 6d 70 6c 65 74 65 28 29 5d 20 6d 75 73 74 20  omplete()] must 
18d90 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  be a zero-termin
18da0 61 74 65 64 0a 2a 2a 20 55 54 46 2d 38 20 73 74  ated.** UTF-8 st
18db0 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ring..**.** The 
18dc0 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65  input to [sqlite
18dd0 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 5d 20  3_complete16()] 
18de0 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74  must be a zero-t
18df0 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46  erminated.** UTF
18e00 2d 31 36 20 73 74 72 69 6e 67 20 69 6e 20 6e 61  -16 string in na
18e10 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e  tive byte order.
18e20 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
18e30 63 6f 6d 70 6c 65 74 65 28 63 6f 6e 73 74 20 63  complete(const c
18e40 68 61 72 20 2a 73 71 6c 29 3b 0a 69 6e 74 20 73  har *sql);.int s
18e50 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31  qlite3_complete1
18e60 36 28 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  6(const void *sq
18e70 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  l);../*.** CAPI3
18e80 52 45 46 3a 20 52 65 67 69 73 74 65 72 20 41 20  REF: Register A 
18e90 43 61 6c 6c 62 61 63 6b 20 54 6f 20 48 61 6e 64  Callback To Hand
18ea0 6c 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 45  le SQLITE_BUSY E
18eb0 72 72 6f 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  rrors.**.** ^Thi
18ec0 73 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61  s routine sets a
18ed0 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
18ee0 6f 6e 20 74 68 61 74 20 6d 69 67 68 74 20 62 65  on that might be
18ef0 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65   invoked wheneve
18f00 72 0a 2a 2a 20 61 6e 20 61 74 74 65 6d 70 74 20  r.** an attempt 
18f10 69 73 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20  is made to open 
18f20 61 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65  a database table
18f30 20 74 68 61 74 20 61 6e 6f 74 68 65 72 20 74 68   that another th
18f40 72 65 61 64 0a 2a 2a 20 6f 72 20 70 72 6f 63 65  read.** or proce
18f50 73 73 20 68 61 73 20 6c 6f 63 6b 65 64 2e 0a 2a  ss has locked..*
18f60 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 62 75 73  *.** ^If the bus
18f70 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55  y callback is NU
18f80 4c 4c 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45  LL, then [SQLITE
18f90 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54  _BUSY] or [SQLIT
18fa0 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d  E_IOERR_BLOCKED]
18fb0 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20  .** is returned 
18fc0 69 6d 6d 65 64 69 61 74 65 6c 79 20 75 70 6f 6e  immediately upon
18fd0 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20 74 68   encountering th
18fe0 65 20 6c 6f 63 6b 2e 20 20 5e 49 66 20 74 68 65  e lock.  ^If the
18ff0 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 0a 2a   busy callback.*
19000 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74  * is not NULL, t
19010 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  hen the callback
19020 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65   might be invoke
19030 64 20 77 69 74 68 20 74 77 6f 20 61 72 67 75 6d  d with two argum
19040 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ents..**.** ^The
19050 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
19060 74 6f 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  to the busy hand
19070 6c 65 72 20 69 73 20 61 20 63 6f 70 79 20 6f 66  ler is a copy of
19080 20 74 68 65 20 76 6f 69 64 2a 20 70 6f 69 6e 74   the void* point
19090 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 74  er which.** is t
190a0 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
190b0 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 75 73  t to sqlite3_bus
190c0 79 5f 68 61 6e 64 6c 65 72 28 29 2e 20 20 5e 54  y_handler().  ^T
190d0 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
190e0 6e 74 20 74 6f 0a 2a 2a 20 74 68 65 20 62 75 73  nt to.** the bus
190f0 79 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61  y handler callba
19100 63 6b 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72  ck is the number
19110 20 6f 66 20 74 69 6d 65 73 20 74 68 61 74 20 74   of times that t
19120 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  he busy handler 
19130 68 61 73 0a 2a 2a 20 62 65 65 6e 20 69 6e 76 6f  has.** been invo
19140 6b 65 64 20 66 6f 72 20 74 68 69 73 20 6c 6f 63  ked for this loc
19150 6b 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66  king event.  ^If
19160 20 74 68 65 0a 2a 2a 20 62 75 73 79 20 63 61 6c   the.** busy cal
19170 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 30 2c  lback returns 0,
19180 20 74 68 65 6e 20 6e 6f 20 61 64 64 69 74 69 6f   then no additio
19190 6e 61 6c 20 61 74 74 65 6d 70 74 73 20 61 72 65  nal attempts are
191a0 20 6d 61 64 65 20 74 6f 0a 2a 2a 20 61 63 63 65   made to.** acce
191b0 73 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ss the database 
191c0 61 6e 64 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  and [SQLITE_BUSY
191d0 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45  ] or [SQLITE_IOE
191e0 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 73 20 72  RR_BLOCKED] is r
191f0 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 49 66 20  eturned..** ^If 
19200 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  the callback ret
19210 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74  urns non-zero, t
19220 68 65 6e 20 61 6e 6f 74 68 65 72 20 61 74 74 65  hen another atte
19230 6d 70 74 0a 2a 2a 20 69 73 20 6d 61 64 65 20 74  mpt.** is made t
19240 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62  o open the datab
19250 61 73 65 20 66 6f 72 20 72 65 61 64 69 6e 67 20  ase for reading 
19260 61 6e 64 20 74 68 65 20 63 79 63 6c 65 20 72 65  and the cycle re
19270 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  peats..**.** The
19280 20 70 72 65 73 65 6e 63 65 20 6f 66 20 61 20 62   presence of a b
19290 75 73 79 20 68 61 6e 64 6c 65 72 20 64 6f 65 73  usy handler does
192a0 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 20 74   not guarantee t
192b0 68 61 74 20 69 74 20 77 69 6c 6c 20 62 65 20 69  hat it will be i
192c0 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e 20 74  nvoked.** when t
192d0 68 65 72 65 20 69 73 20 6c 6f 63 6b 20 63 6f 6e  here is lock con
192e0 74 65 6e 74 69 6f 6e 2e 20 5e 49 66 20 53 51 4c  tention. ^If SQL
192f0 69 74 65 20 64 65 74 65 72 6d 69 6e 65 73 20 74  ite determines t
19300 68 61 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65  hat invoking the
19310 20 62 75 73 79 0a 2a 2a 20 68 61 6e 64 6c 65 72   busy.** handler
19320 20 63 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e   could result in
19330 20 61 20 64 65 61 64 6c 6f 63 6b 2c 20 69 74 20   a deadlock, it 
19340 77 69 6c 6c 20 67 6f 20 61 68 65 61 64 20 61 6e  will go ahead an
19350 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  d return [SQLITE
19360 5f 42 55 53 59 5d 0a 2a 2a 20 6f 72 20 5b 53 51  _BUSY].** or [SQ
19370 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b  LITE_IOERR_BLOCK
19380 45 44 5d 20 69 6e 73 74 65 61 64 20 6f 66 20 69  ED] instead of i
19390 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79  nvoking the busy
193a0 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e   handler..** Con
193b0 73 69 64 65 72 20 61 20 73 63 65 6e 61 72 69 6f  sider a scenario
193c0 20 77 68 65 72 65 20 6f 6e 65 20 70 72 6f 63 65   where one proce
193d0 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20  ss is holding a 
193e0 72 65 61 64 20 6c 6f 63 6b 20 74 68 61 74 0a 2a  read lock that.*
193f0 2a 20 69 74 20 69 73 20 74 72 79 69 6e 67 20 74  * it is trying t
19400 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 20 72  o promote to a r
19410 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 61 6e 64  eserved lock and
19420 0a 2a 2a 20 61 20 73 65 63 6f 6e 64 20 70 72 6f  .** a second pro
19430 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20  cess is holding 
19440 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20  a reserved lock 
19450 74 68 61 74 20 69 74 20 69 73 20 74 72 79 69 6e  that it is tryin
19460 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20  g.** to promote 
19470 74 6f 20 61 6e 20 65 78 63 6c 75 73 69 76 65 20  to an exclusive 
19480 6c 6f 63 6b 2e 20 20 54 68 65 20 66 69 72 73 74  lock.  The first
19490 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 20   process cannot 
194a0 70 72 6f 63 65 65 64 0a 2a 2a 20 62 65 63 61 75  proceed.** becau
194b0 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64  se it is blocked
194c0 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 61   by the second a
194d0 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72  nd the second pr
194e0 6f 63 65 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20  ocess cannot.** 
194f0 70 72 6f 63 65 65 64 20 62 65 63 61 75 73 65 20  proceed because 
19500 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79  it is blocked by
19510 20 74 68 65 20 66 69 72 73 74 2e 20 20 49 66 20   the first.  If 
19520 62 6f 74 68 20 70 72 6f 63 65 73 73 65 73 0a 2a  both processes.*
19530 2a 20 69 6e 76 6f 6b 65 20 74 68 65 20 62 75 73  * invoke the bus
19540 79 20 68 61 6e 64 6c 65 72 73 2c 20 6e 65 69 74  y handlers, neit
19550 68 65 72 20 77 69 6c 6c 20 6d 61 6b 65 20 61 6e  her will make an
19560 79 20 70 72 6f 67 72 65 73 73 2e 20 20 54 68 65  y progress.  The
19570 72 65 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69 74  refore,.** SQLit
19580 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  e returns [SQLIT
19590 45 5f 42 55 53 59 5d 20 66 6f 72 20 74 68 65 20  E_BUSY] for the 
195a0 66 69 72 73 74 20 70 72 6f 63 65 73 73 2c 20 68  first process, h
195b0 6f 70 69 6e 67 20 74 68 61 74 20 74 68 69 73 0a  oping that this.
195c0 2a 2a 20 77 69 6c 6c 20 69 6e 64 75 63 65 20 74  ** will induce t
195d0 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73  he first process
195e0 20 74 6f 20 72 65 6c 65 61 73 65 20 69 74 73 20   to release its 
195f0 72 65 61 64 20 6c 6f 63 6b 20 61 6e 64 20 61 6c  read lock and al
19600 6c 6f 77 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e  low.** the secon
19610 64 20 70 72 6f 63 65 73 73 20 74 6f 20 70 72 6f  d process to pro
19620 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ceed..**.** ^The
19630 20 64 65 66 61 75 6c 74 20 62 75 73 79 20 63 61   default busy ca
19640 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a  llback is NULL..
19650 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  **.** ^The [SQLI
19660 54 45 5f 42 55 53 59 5d 20 65 72 72 6f 72 20 69  TE_BUSY] error i
19670 73 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 5b  s converted to [
19680 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f  SQLITE_IOERR_BLO
19690 43 4b 45 44 5d 0a 2a 2a 20 77 68 65 6e 20 53 51  CKED].** when SQ
196a0 4c 69 74 65 20 69 73 20 69 6e 20 74 68 65 20 6d  Lite is in the m
196b0 69 64 64 6c 65 20 6f 66 20 61 20 6c 61 72 67 65  iddle of a large
196c0 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 77 68 65   transaction whe
196d0 72 65 20 61 6c 6c 20 74 68 65 0a 2a 2a 20 63 68  re all the.** ch
196e0 61 6e 67 65 73 20 77 69 6c 6c 20 6e 6f 74 20 66  anges will not f
196f0 69 74 20 69 6e 74 6f 20 74 68 65 20 69 6e 2d 6d  it into the in-m
19700 65 6d 6f 72 79 20 63 61 63 68 65 2e 20 20 53 51  emory cache.  SQ
19710 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a 20 61 6c 72  Lite will.** alr
19720 65 61 64 79 20 68 6f 6c 64 20 61 20 52 45 53 45  eady hold a RESE
19730 52 56 45 44 20 6c 6f 63 6b 20 6f 6e 20 74 68 65  RVED lock on the
19740 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20   database file, 
19750 62 75 74 20 69 74 20 6e 65 65 64 73 0a 2a 2a 20  but it needs.** 
19760 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68 69 73 20  to promote this 
19770 6c 6f 63 6b 20 74 6f 20 45 58 43 4c 55 53 49 56  lock to EXCLUSIV
19780 45 20 73 6f 20 74 68 61 74 20 69 74 20 63 61 6e  E so that it can
19790 20 73 70 69 6c 6c 20 63 61 63 68 65 0a 2a 2a 20   spill cache.** 
197a0 70 61 67 65 73 20 69 6e 74 6f 20 74 68 65 20 64  pages into the d
197b0 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 69 74  atabase file wit
197c0 68 6f 75 74 20 68 61 72 6d 20 74 6f 20 63 6f 6e  hout harm to con
197d0 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65 61 64 65  current.** reade
197e0 72 73 2e 20 20 5e 49 66 20 69 74 20 69 73 20 75  rs.  ^If it is u
197f0 6e 61 62 6c 65 20 74 6f 20 70 72 6f 6d 6f 74 65  nable to promote
19800 20 74 68 65 20 6c 6f 63 6b 2c 20 74 68 65 6e 20   the lock, then 
19810 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 0a 2a 2a  the in-memory.**
19820 20 63 61 63 68 65 20 77 69 6c 6c 20 62 65 20 6c   cache will be l
19830 65 66 74 20 69 6e 20 61 6e 20 69 6e 63 6f 6e 73  eft in an incons
19840 69 73 74 65 6e 74 20 73 74 61 74 65 20 61 6e 64  istent state and
19850 20 73 6f 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a   so the error.**
19860 20 63 6f 64 65 20 69 73 20 70 72 6f 6d 6f 74 65   code is promote
19870 64 20 66 72 6f 6d 20 74 68 65 20 72 65 6c 61 74  d from the relat
19880 69 76 65 6c 79 20 62 65 6e 69 67 6e 20 5b 53 51  ively benign [SQ
19890 4c 49 54 45 5f 42 55 53 59 5d 20 74 6f 0a 2a 2a  LITE_BUSY] to.**
198a0 20 74 68 65 20 6d 6f 72 65 20 73 65 76 65 72 65   the more severe
198b0 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42   [SQLITE_IOERR_B
198c0 4c 4f 43 4b 45 44 5d 2e 20 20 5e 54 68 69 73 20  LOCKED].  ^This 
198d0 65 72 72 6f 72 20 63 6f 64 65 20 70 72 6f 6d 6f  error code promo
198e0 74 69 6f 6e 0a 2a 2a 20 66 6f 72 63 65 73 20 61  tion.** forces a
198f0 6e 20 61 75 74 6f 6d 61 74 69 63 20 72 6f 6c 6c  n automatic roll
19900 62 61 63 6b 20 6f 66 20 74 68 65 20 63 68 61 6e  back of the chan
19910 67 65 73 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a  ges.  See the.**
19920 20 3c 61 20 68 72 65 66 3d 22 2f 63 76 73 74 72   <a href="/cvstr
19930 61 63 2f 77 69 6b 69 3f 70 3d 43 6f 72 72 75 70  ac/wiki?p=Corrup
19940 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73  tionFollowingBus
19950 79 45 72 72 6f 72 22 3e 0a 2a 2a 20 43 6f 72 72  yError">.** Corr
19960 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42  uptionFollowingB
19970 75 73 79 45 72 72 6f 72 3c 2f 61 3e 20 77 69 6b  usyError</a> wik
19980 69 20 70 61 67 65 20 66 6f 72 20 61 20 64 69 73  i page for a dis
19990 63 75 73 73 69 6f 6e 20 6f 66 20 77 68 79 0a 2a  cussion of why.*
199a0 2a 20 74 68 69 73 20 69 73 20 69 6d 70 6f 72 74  * this is import
199b0 61 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ant..**.** ^(The
199c0 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61  re can only be a
199d0 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e   single busy han
199e0 64 6c 65 72 20 64 65 66 69 6e 65 64 20 66 6f 72  dler defined for
199f0 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61   each.** [databa
19a00 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20  se connection]. 
19a10 20 53 65 74 74 69 6e 67 20 61 20 6e 65 77 20 62   Setting a new b
19a20 75 73 79 20 68 61 6e 64 6c 65 72 20 63 6c 65 61  usy handler clea
19a30 72 73 20 61 6e 79 0a 2a 2a 20 70 72 65 76 69 6f  rs any.** previo
19a40 75 73 6c 79 20 73 65 74 20 68 61 6e 64 6c 65 72  usly set handler
19a50 2e 29 5e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20  .)^  ^Note that 
19a60 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
19a70 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d  _busy_timeout()]
19a80 0a 2a 2a 20 77 69 6c 6c 20 61 6c 73 6f 20 73 65  .** will also se
19a90 74 20 6f 72 20 63 6c 65 61 72 20 74 68 65 20 62  t or clear the b
19aa0 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a  usy handler..**.
19ab0 2a 2a 20 54 68 65 20 62 75 73 79 20 63 61 6c 6c  ** The busy call
19ac0 62 61 63 6b 20 73 68 6f 75 6c 64 20 6e 6f 74 20  back should not 
19ad0 74 61 6b 65 20 61 6e 79 20 61 63 74 69 6f 6e 73  take any actions
19ae0 20 77 68 69 63 68 20 6d 6f 64 69 66 79 20 74 68   which modify th
19af0 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  e.** database co
19b00 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e  nnection that in
19b10 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20 68  voked the busy h
19b20 61 6e 64 6c 65 72 2e 20 20 41 6e 79 20 73 75 63  andler.  Any suc
19b30 68 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 73  h actions.** res
19b40 75 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 64  ult in undefined
19b50 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 20 0a 2a   behavior..** .*
19b60 2a 20 41 20 62 75 73 79 20 68 61 6e 64 6c 65 72  * A busy handler
19b70 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20   must not close 
19b80 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
19b90 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 72 20 5b 70  nection.** or [p
19ba0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
19bb0 74 5d 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20  t] that invoked 
19bc0 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
19bd0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
19be0 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 73 71  _busy_handler(sq
19bf0 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28 76  lite3*, int(*)(v
19c00 6f 69 64 2a 2c 69 6e 74 29 2c 20 76 6f 69 64 2a  oid*,int), void*
19c10 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
19c20 45 46 3a 20 53 65 74 20 41 20 42 75 73 79 20 54  EF: Set A Busy T
19c30 69 6d 65 6f 75 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  imeout.**.** ^Th
19c40 69 73 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20  is routine sets 
19c50 61 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  a [sqlite3_busy_
19c60 68 61 6e 64 6c 65 72 20 7c 20 62 75 73 79 20 68  handler | busy h
19c70 61 6e 64 6c 65 72 5d 20 74 68 61 74 20 73 6c 65  andler] that sle
19c80 65 70 73 0a 2a 2a 20 66 6f 72 20 61 20 73 70 65  eps.** for a spe
19c90 63 69 66 69 65 64 20 61 6d 6f 75 6e 74 20 6f 66  cified amount of
19ca0 20 74 69 6d 65 20 77 68 65 6e 20 61 20 74 61 62   time when a tab
19cb0 6c 65 20 69 73 20 6c 6f 63 6b 65 64 2e 20 20 5e  le is locked.  ^
19cc0 54 68 65 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77  The handler.** w
19cd0 69 6c 6c 20 73 6c 65 65 70 20 6d 75 6c 74 69 70  ill sleep multip
19ce0 6c 65 20 74 69 6d 65 73 20 75 6e 74 69 6c 20 61  le times until a
19cf0 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c  t least "ms" mil
19d00 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65  liseconds of sle
19d10 65 70 69 6e 67 0a 2a 2a 20 68 61 76 65 20 61 63  eping.** have ac
19d20 63 75 6d 75 6c 61 74 65 64 2e 20 20 5e 41 66 74  cumulated.  ^Aft
19d30 65 72 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22  er at least "ms"
19d40 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66   milliseconds of
19d50 20 73 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20 74 68   sleeping,.** th
19d60 65 20 68 61 6e 64 6c 65 72 20 72 65 74 75 72 6e  e handler return
19d70 73 20 30 20 77 68 69 63 68 20 63 61 75 73 65 73  s 0 which causes
19d80 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
19d90 5d 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 5b  ] to return.** [
19da0 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20  SQLITE_BUSY] or 
19db0 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c  [SQLITE_IOERR_BL
19dc0 4f 43 4b 45 44 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43  OCKED]..**.** ^C
19dd0 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 74  alling this rout
19de0 69 6e 65 20 77 69 74 68 20 61 6e 20 61 72 67 75  ine with an argu
19df0 6d 65 6e 74 20 6c 65 73 73 20 74 68 61 6e 20 6f  ment less than o
19e00 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 0a  r equal to zero.
19e10 2a 2a 20 74 75 72 6e 73 20 6f 66 66 20 61 6c 6c  ** turns off all
19e20 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2e 0a   busy handlers..
19e30 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61  **.** ^(There ca
19e40 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67  n only be a sing
19e50 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  le busy handler 
19e60 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72  for a particular
19e70 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
19e80 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 79 20 61 6e  nnection] any an
19e90 79 20 67 69 76 65 6e 20 6d 6f 6d 65 6e 74 2e 20  y given moment. 
19ea0 20 49 66 20 61 6e 6f 74 68 65 72 20 62 75 73 79   If another busy
19eb0 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 61 73 20   handler.** was 
19ec0 64 65 66 69 6e 65 64 20 20 28 75 73 69 6e 67 20  defined  (using 
19ed0 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61  [sqlite3_busy_ha
19ee0 6e 64 6c 65 72 28 29 5d 29 20 70 72 69 6f 72 20  ndler()]) prior 
19ef0 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68  to calling.** th
19f00 69 73 20 72 6f 75 74 69 6e 65 2c 20 74 68 61 74  is routine, that
19f10 20 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e 64   other busy hand
19f20 6c 65 72 20 69 73 20 63 6c 65 61 72 65 64 2e 29  ler is cleared.)
19f30 5e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ^.*/.int sqlite3
19f40 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 73 71  _busy_timeout(sq
19f50 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6d 73 29 3b  lite3*, int ms);
19f60 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
19f70 3a 20 43 6f 6e 76 65 6e 69 65 6e 63 65 20 52 6f  : Convenience Ro
19f80 75 74 69 6e 65 73 20 46 6f 72 20 52 75 6e 6e 69  utines For Runni
19f90 6e 67 20 51 75 65 72 69 65 73 0a 2a 2a 0a 2a 2a  ng Queries.**.**
19fa0 20 54 68 69 73 20 69 73 20 61 20 6c 65 67 61 63   This is a legac
19fb0 79 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74  y interface that
19fc0 20 69 73 20 70 72 65 73 65 72 76 65 64 20 66 6f   is preserved fo
19fd0 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70  r backwards comp
19fe0 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 20 55 73  atibility..** Us
19ff0 65 20 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66  e of this interf
1a000 61 63 65 20 69 73 20 6e 6f 74 20 72 65 63 6f 6d  ace is not recom
1a010 6d 65 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 44 65  mended..**.** De
1a020 66 69 6e 69 74 69 6f 6e 3a 20 41 20 3c 62 3e 72  finition: A <b>r
1a030 65 73 75 6c 74 20 74 61 62 6c 65 3c 2f 62 3e 20  esult table</b> 
1a040 69 73 20 6d 65 6d 6f 72 79 20 64 61 74 61 20 73  is memory data s
1a050 74 72 75 63 74 75 72 65 20 63 72 65 61 74 65 64  tructure created
1a060 20 62 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69   by the.** [sqli
1a070 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d  te3_get_table()]
1a080 20 69 6e 74 65 72 66 61 63 65 2e 20 20 41 20 72   interface.  A r
1a090 65 73 75 6c 74 20 74 61 62 6c 65 20 72 65 63 6f  esult table reco
1a0a0 72 64 73 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c  rds the.** compl
1a0b0 65 74 65 20 71 75 65 72 79 20 72 65 73 75 6c 74  ete query result
1a0c0 73 20 66 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f  s from one or mo
1a0d0 72 65 20 71 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a  re queries..**.*
1a0e0 2a 20 54 68 65 20 74 61 62 6c 65 20 63 6f 6e 63  * The table conc
1a0f0 65 70 74 75 61 6c 6c 79 20 68 61 73 20 61 20 6e  eptually has a n
1a100 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 61 6e  umber of rows an
1a110 64 20 63 6f 6c 75 6d 6e 73 2e 20 20 42 75 74 0a  d columns.  But.
1a120 2a 2a 20 74 68 65 73 65 20 6e 75 6d 62 65 72 73  ** these numbers
1a130 20 61 72 65 20 6e 6f 74 20 70 61 72 74 20 6f 66   are not part of
1a140 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c   the result tabl
1a150 65 20 69 74 73 65 6c 66 2e 20 20 54 68 65 73 65  e itself.  These
1a160 0a 2a 2a 20 6e 75 6d 62 65 72 73 20 61 72 65 20  .** numbers are 
1a170 6f 62 74 61 69 6e 65 64 20 73 65 70 61 72 61 74  obtained separat
1a180 65 6c 79 2e 20 20 4c 65 74 20 4e 20 62 65 20 74  ely.  Let N be t
1a190 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77  he number of row
1a1a0 73 0a 2a 2a 20 61 6e 64 20 4d 20 62 65 20 74 68  s.** and M be th
1a1b0 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  e number of colu
1a1c0 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73  mns..**.** A res
1a1d0 75 6c 74 20 74 61 62 6c 65 20 69 73 20 61 6e 20  ult table is an 
1a1e0 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72  array of pointer
1a1f0 73 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  s to zero-termin
1a200 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e  ated UTF-8 strin
1a210 67 73 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65  gs..** There are
1a220 20 28 4e 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e 74   (N+1)*M element
1a230 73 20 69 6e 20 74 68 65 20 61 72 72 61 79 2e 20  s in the array. 
1a240 20 54 68 65 20 66 69 72 73 74 20 4d 20 70 6f 69   The first M poi
1a250 6e 74 65 72 73 20 70 6f 69 6e 74 0a 2a 2a 20 74  nters point.** t
1a260 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  o zero-terminate
1a270 64 20 73 74 72 69 6e 67 73 20 74 68 61 74 20 20  d strings that  
1a280 63 6f 6e 74 61 69 6e 20 74 68 65 20 6e 61 6d 65  contain the name
1a290 73 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73  s of the columns
1a2a0 2e 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e 69  ..** The remaini
1a2b0 6e 67 20 65 6e 74 72 69 65 73 20 61 6c 6c 20 70  ng entries all p
1a2c0 6f 69 6e 74 20 74 6f 20 71 75 65 72 79 20 72 65  oint to query re
1a2d0 73 75 6c 74 73 2e 20 20 4e 55 4c 4c 20 76 61 6c  sults.  NULL val
1a2e0 75 65 73 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e  ues result.** in
1a2f0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 2e 20   NULL pointers. 
1a300 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 75 65   All other value
1a310 73 20 61 72 65 20 69 6e 20 74 68 65 69 72 20 55  s are in their U
1a320 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  TF-8 zero-termin
1a330 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 72  ated.** string r
1a340 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 61 73  epresentation as
1a350 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71   returned by [sq
1a360 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
1a370 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65  t()]..**.** A re
1a380 73 75 6c 74 20 74 61 62 6c 65 20 6d 69 67 68 74  sult table might
1a390 20 63 6f 6e 73 69 73 74 20 6f 66 20 6f 6e 65 20   consist of one 
1a3a0 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f 72 79 20 61  or more memory a
1a3b0 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49  llocations..** I
1a3c0 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f  t is not safe to
1a3d0 20 70 61 73 73 20 61 20 72 65 73 75 6c 74 20 74   pass a result t
1a3e0 61 62 6c 65 20 64 69 72 65 63 74 6c 79 20 74 6f  able directly to
1a3f0 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
1a400 5d 2e 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74  ]..** A result t
1a410 61 62 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 64  able should be d
1a420 65 61 6c 6c 6f 63 61 74 65 64 20 75 73 69 6e 67  eallocated using
1a430 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74   [sqlite3_free_t
1a440 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  able()]..**.** ^
1a450 28 41 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f  (As an example o
1a460 66 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62  f the result tab
1a470 6c 65 20 66 6f 72 6d 61 74 2c 20 73 75 70 70 6f  le format, suppo
1a480 73 65 20 61 20 71 75 65 72 79 20 72 65 73 75 6c  se a query resul
1a490 74 0a 2a 2a 20 69 73 20 61 73 20 66 6f 6c 6c 6f  t.** is as follo
1a4a0 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ws:.**.** <block
1a4b0 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
1a4c0 20 20 20 20 20 20 4e 61 6d 65 20 20 20 20 20 20        Name      
1a4d0 20 20 7c 20 41 67 65 0a 2a 2a 20 20 20 20 20 20    | Age.**      
1a4e0 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d    --------------
1a4f0 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20  ---------.**    
1a500 20 20 20 20 41 6c 69 63 65 20 20 20 20 20 20 20      Alice       
1a510 7c 20 34 33 0a 2a 2a 20 20 20 20 20 20 20 20 42  | 43.**        B
1a520 6f 62 20 20 20 20 20 20 20 20 20 7c 20 32 38 0a  ob         | 28.
1a530 2a 2a 20 20 20 20 20 20 20 20 43 69 6e 64 79 20  **        Cindy 
1a540 20 20 20 20 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f        | 21.** </
1a550 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
1a560 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 61 72  >.**.** There ar
1a570 65 20 74 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d  e two column (M=
1a580 3d 32 29 20 61 6e 64 20 74 68 72 65 65 20 72 6f  =2) and three ro
1a590 77 73 20 28 4e 3d 3d 33 29 2e 20 20 54 68 75 73  ws (N==3).  Thus
1a5a0 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 74   the.** result t
1a5b0 61 62 6c 65 20 68 61 73 20 38 20 65 6e 74 72 69  able has 8 entri
1a5c0 65 73 2e 20 20 53 75 70 70 6f 73 65 20 74 68 65  es.  Suppose the
1a5d0 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73   result table is
1a5e0 20 73 74 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 6e   stored.** in an
1a5f0 20 61 72 72 61 79 20 6e 61 6d 65 73 20 61 7a 52   array names azR
1a600 65 73 75 6c 74 2e 20 20 54 68 65 6e 20 61 7a 52  esult.  Then azR
1a610 65 73 75 6c 74 20 68 6f 6c 64 73 20 74 68 69 73  esult holds this
1a620 20 63 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20   content:.**.** 
1a630 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
1a640 3e 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  >.**        azRe
1a650 73 75 6c 74 26 23 39 31 3b 30 5d 20 3d 20 22 4e  sult&#91;0] = "N
1a660 61 6d 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  ame";.**        
1a670 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 31 5d 20  azResult&#91;1] 
1a680 3d 20 22 41 67 65 22 3b 0a 2a 2a 20 20 20 20 20  = "Age";.**     
1a690 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
1a6a0 32 5d 20 3d 20 22 41 6c 69 63 65 22 3b 0a 2a 2a  2] = "Alice";.**
1a6b0 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
1a6c0 26 23 39 31 3b 33 5d 20 3d 20 22 34 33 22 3b 0a  &#91;3] = "43";.
1a6d0 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
1a6e0 6c 74 26 23 39 31 3b 34 5d 20 3d 20 22 42 6f 62  lt&#91;4] = "Bob
1a6f0 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
1a700 65 73 75 6c 74 26 23 39 31 3b 35 5d 20 3d 20 22  esult&#91;5] = "
1a710 32 38 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  28";.**        a
1a720 7a 52 65 73 75 6c 74 26 23 39 31 3b 36 5d 20 3d  zResult&#91;6] =
1a730 20 22 43 69 6e 64 79 22 3b 0a 2a 2a 20 20 20 20   "Cindy";.**    
1a740 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
1a750 3b 37 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c  ;7] = "21";.** <
1a760 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
1a770 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  e>)^.**.** ^The 
1a780 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
1a790 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 65 76 61  e() function eva
1a7a0 6c 75 61 74 65 73 20 6f 6e 65 20 6f 72 20 6d 6f  luates one or mo
1a7b0 72 65 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d  re.** semicolon-
1a7c0 73 65 70 61 72 61 74 65 64 20 53 51 4c 20 73 74  separated SQL st
1a7d0 61 74 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20  atements in the 
1a7e0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
1a7f0 55 54 46 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20  UTF-8.** string 
1a800 6f 66 20 69 74 73 20 32 6e 64 20 70 61 72 61 6d  of its 2nd param
1a810 65 74 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73  eter and returns
1a820 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   a result table 
1a830 74 6f 20 74 68 65 0a 2a 2a 20 70 6f 69 6e 74 65  to the.** pointe
1a840 72 20 67 69 76 65 6e 20 69 6e 20 69 74 73 20 33  r given in its 3
1a850 72 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  rd parameter..**
1a860 0a 2a 2a 20 41 66 74 65 72 20 74 68 65 20 61 70  .** After the ap
1a870 70 6c 69 63 61 74 69 6f 6e 20 68 61 73 20 66 69  plication has fi
1a880 6e 69 73 68 65 64 20 77 69 74 68 20 74 68 65 20  nished with the 
1a890 72 65 73 75 6c 74 20 66 72 6f 6d 20 73 71 6c 69  result from sqli
1a8a0 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c  te3_get_table(),
1a8b0 0a 2a 2a 20 69 74 20 6d 75 73 74 20 70 61 73 73  .** it must pass
1a8c0 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c   the result tabl
1a8d0 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c  e pointer to sql
1a8e0 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28  ite3_free_table(
1a8f0 29 20 69 6e 20 6f 72 64 65 72 20 74 6f 0a 2a 2a  ) in order to.**
1a900 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d   release the mem
1a910 6f 72 79 20 74 68 61 74 20 77 61 73 20 6d 61 6c  ory that was mal
1a920 6c 6f 63 65 64 2e 20 20 42 65 63 61 75 73 65 20  loced.  Because 
1a930 6f 66 20 74 68 65 20 77 61 79 20 74 68 65 0a 2a  of the way the.*
1a940 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  * [sqlite3_mallo
1a950 63 28 29 5d 20 68 61 70 70 65 6e 73 20 77 69 74  c()] happens wit
1a960 68 69 6e 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  hin sqlite3_get_
1a970 74 61 62 6c 65 28 29 2c 20 74 68 65 20 63 61 6c  table(), the cal
1a980 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  ling.** function
1a990 20 6d 75 73 74 20 6e 6f 74 20 74 72 79 20 74 6f   must not try to
1a9a0 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66   call [sqlite3_f
1a9b0 72 65 65 28 29 5d 20 64 69 72 65 63 74 6c 79 2e  ree()] directly.
1a9c0 20 20 4f 6e 6c 79 0a 2a 2a 20 5b 73 71 6c 69 74    Only.** [sqlit
1a9d0 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d  e3_free_table()]
1a9e0 20 69 73 20 61 62 6c 65 20 74 6f 20 72 65 6c 65   is able to rele
1a9f0 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70  ase the memory p
1aa00 72 6f 70 65 72 6c 79 20 61 6e 64 20 73 61 66 65  roperly and safe
1aa10 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ly..**.** The sq
1aa20 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
1aa30 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 69  ) interface is i
1aa40 6d 70 6c 65 6d 65 6e 74 65 64 20 61 73 20 61 20  mplemented as a 
1aa50 77 72 61 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a  wrapper around.*
1aa60 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  * [sqlite3_exec(
1aa70 29 5d 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33  )].  The sqlite3
1aa80 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 72 6f 75  _get_table() rou
1aa90 74 69 6e 65 20 64 6f 65 73 20 6e 6f 74 20 68 61  tine does not ha
1aaa0 76 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20  ve access.** to 
1aab0 61 6e 79 20 69 6e 74 65 72 6e 61 6c 20 64 61 74  any internal dat
1aac0 61 20 73 74 72 75 63 74 75 72 65 73 20 6f 66 20  a structures of 
1aad0 53 51 4c 69 74 65 2e 20 20 49 74 20 75 73 65 73  SQLite.  It uses
1aae0 20 6f 6e 6c 79 20 74 68 65 20 70 75 62 6c 69 63   only the public
1aaf0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 64 65  .** interface de
1ab00 66 69 6e 65 64 20 68 65 72 65 2e 20 20 41 73 20  fined here.  As 
1ab10 61 20 63 6f 6e 73 65 71 75 65 6e 63 65 2c 20 65  a consequence, e
1ab20 72 72 6f 72 73 20 74 68 61 74 20 6f 63 63 75 72  rrors that occur
1ab30 20 69 6e 20 74 68 65 0a 2a 2a 20 77 72 61 70 70   in the.** wrapp
1ab40 65 72 20 6c 61 79 65 72 20 6f 75 74 73 69 64 65  er layer outside
1ab50 20 6f 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c   of the internal
1ab60 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
1ab70 5d 20 63 61 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a  ] call are not.*
1ab80 2a 20 72 65 66 6c 65 63 74 65 64 20 69 6e 20 73  * reflected in s
1ab90 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20  ubsequent calls 
1aba0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63  to [sqlite3_errc
1abb0 6f 64 65 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  ode()] or.** [sq
1abc0 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e  lite3_errmsg()].
1abd0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
1abe0 67 65 74 5f 74 61 62 6c 65 28 0a 20 20 73 71 6c  get_table(.  sql
1abf0 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
1ac00 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61     /* An open da
1ac10 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73  tabase */.  cons
1ac20 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20  t char *zSql,   
1ac30 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65    /* SQL to be e
1ac40 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 63 68  valuated */.  ch
1ac50 61 72 20 2a 2a 2a 70 61 7a 52 65 73 75 6c 74 2c  ar ***pazResult,
1ac60 20 20 20 20 2f 2a 20 52 65 73 75 6c 74 73 20 6f      /* Results o
1ac70 66 20 74 68 65 20 71 75 65 72 79 20 2a 2f 0a 20  f the query */. 
1ac80 20 69 6e 74 20 2a 70 6e 52 6f 77 2c 20 20 20 20   int *pnRow,    
1ac90 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72         /* Number
1aca0 20 6f 66 20 72 65 73 75 6c 74 20 72 6f 77 73 20   of result rows 
1acb0 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a  written here */.
1acc0 20 20 69 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e 2c    int *pnColumn,
1acd0 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65          /* Numbe
1ace0 72 20 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c 75  r of result colu
1acf0 6d 6e 73 20 77 72 69 74 74 65 6e 20 68 65 72 65  mns written here
1ad00 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45   */.  char **pzE
1ad10 72 72 6d 73 67 20 20 20 20 20 20 20 2f 2a 20 45  rrmsg       /* E
1ad20 72 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e  rror msg written
1ad30 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 76 6f 69 64   here */.);.void
1ad40 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61   sqlite3_free_ta
1ad50 62 6c 65 28 63 68 61 72 20 2a 2a 72 65 73 75 6c  ble(char **resul
1ad60 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
1ad70 52 45 46 3a 20 46 6f 72 6d 61 74 74 65 64 20 53  REF: Formatted S
1ad80 74 72 69 6e 67 20 50 72 69 6e 74 69 6e 67 20 46  tring Printing F
1ad90 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54  unctions.**.** T
1ada0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
1adb0 65 20 77 6f 72 6b 2d 61 6c 69 6b 65 73 20 6f 66  e work-alikes of
1adc0 20 74 68 65 20 22 70 72 69 6e 74 66 28 29 22 20   the "printf()" 
1add0 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e 63 74 69  family of functi
1ade0 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20  ons.** from the 
1adf0 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61  standard C libra
1ae00 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ry..**.** ^The s
1ae10 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29  qlite3_mprintf()
1ae20 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 6d 70   and sqlite3_vmp
1ae30 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 73  rintf() routines
1ae40 20 77 72 69 74 65 20 74 68 65 69 72 0a 2a 2a 20   write their.** 
1ae50 72 65 73 75 6c 74 73 20 69 6e 74 6f 20 6d 65 6d  results into mem
1ae60 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ory obtained fro
1ae70 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
1ae80 63 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 74 72  c()]..** The str
1ae90 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79  ings returned by
1aea0 20 74 68 65 73 65 20 74 77 6f 20 72 6f 75 74 69   these two routi
1aeb0 6e 65 73 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a  nes should be.**
1aec0 20 72 65 6c 65 61 73 65 64 20 62 79 20 5b 73 71   released by [sq
1aed0 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 20 20  lite3_free()].  
1aee0 5e 42 6f 74 68 20 72 6f 75 74 69 6e 65 73 20 72  ^Both routines r
1aef0 65 74 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20  eturn a.** NULL 
1af00 70 6f 69 6e 74 65 72 20 69 66 20 5b 73 71 6c 69  pointer if [sqli
1af10 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 73  te3_malloc()] is
1af20 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63   unable to alloc
1af30 61 74 65 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65  ate enough.** me
1af40 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65  mory to hold the
1af50 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e   resulting strin
1af60 67 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73  g..**.** ^(The s
1af70 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
1af80 29 20 72 6f 75 74 69 6e 65 20 69 73 20 73 69 6d  ) routine is sim
1af90 69 6c 61 72 20 74 6f 20 22 73 6e 70 72 69 6e 74  ilar to "snprint
1afa0 66 28 29 22 20 66 72 6f 6d 0a 2a 2a 20 74 68 65  f()" from.** the
1afb0 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72   standard C libr
1afc0 61 72 79 2e 20 20 54 68 65 20 72 65 73 75 6c 74  ary.  The result
1afd0 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f   is written into
1afe0 20 74 68 65 0a 2a 2a 20 62 75 66 66 65 72 20 73   the.** buffer s
1aff0 75 70 70 6c 69 65 64 20 61 73 20 74 68 65 20 73  upplied as the s
1b000 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
1b010 77 68 6f 73 65 20 73 69 7a 65 20 69 73 20 67 69  whose size is gi
1b020 76 65 6e 20 62 79 0a 2a 2a 20 74 68 65 20 66 69  ven by.** the fi
1b030 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e 20 4e  rst parameter. N
1b040 6f 74 65 20 74 68 61 74 20 74 68 65 20 6f 72 64  ote that the ord
1b050 65 72 20 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72  er of the.** fir
1b060 73 74 20 74 77 6f 20 70 61 72 61 6d 65 74 65 72  st two parameter
1b070 73 20 69 73 20 72 65 76 65 72 73 65 64 20 66 72  s is reversed fr
1b080 6f 6d 20 73 6e 70 72 69 6e 74 66 28 29 2e 29 5e  om snprintf().)^
1b090 20 20 54 68 69 73 20 69 73 20 61 6e 0a 2a 2a 20    This is an.** 
1b0a0 68 69 73 74 6f 72 69 63 61 6c 20 61 63 63 69 64  historical accid
1b0b0 65 6e 74 20 74 68 61 74 20 63 61 6e 6e 6f 74 20  ent that cannot 
1b0c0 62 65 20 66 69 78 65 64 20 77 69 74 68 6f 75 74  be fixed without
1b0d0 20 62 72 65 61 6b 69 6e 67 0a 2a 2a 20 62 61 63   breaking.** bac
1b0e0 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69  kwards compatibi
1b0f0 6c 69 74 79 2e 20 20 5e 28 4e 6f 74 65 20 61 6c  lity.  ^(Note al
1b100 73 6f 20 74 68 61 74 20 73 71 6c 69 74 65 33 5f  so that sqlite3_
1b110 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 72 65  snprintf().** re
1b120 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
1b130 74 6f 20 69 74 73 20 62 75 66 66 65 72 20 69 6e  to its buffer in
1b140 73 74 65 61 64 20 6f 66 20 74 68 65 20 6e 75 6d  stead of the num
1b150 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 72 61 63  ber of.** charac
1b160 74 65 72 73 20 61 63 74 75 61 6c 6c 79 20 77 72  ters actually wr
1b170 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 20 62  itten into the b
1b180 75 66 66 65 72 2e 29 5e 20 20 57 65 20 61 64 6d  uffer.)^  We adm
1b190 69 74 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e  it that.** the n
1b1a0 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74  umber of charact
1b1b0 65 72 73 20 77 72 69 74 74 65 6e 20 77 6f 75 6c  ers written woul
1b1c0 64 20 62 65 20 61 20 6d 6f 72 65 20 75 73 65 66  d be a more usef
1b1d0 75 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c  ul return.** val
1b1e0 75 65 20 62 75 74 20 77 65 20 63 61 6e 6e 6f 74  ue but we cannot
1b1f0 20 63 68 61 6e 67 65 20 74 68 65 20 69 6d 70 6c   change the impl
1b200 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71  ementation of sq
1b210 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
1b220 0a 2a 2a 20 6e 6f 77 20 77 69 74 68 6f 75 74 20  .** now without 
1b230 62 72 65 61 6b 69 6e 67 20 63 6f 6d 70 61 74 69  breaking compati
1b240 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41  bility..**.** ^A
1b250 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 62 75  s long as the bu
1b260 66 66 65 72 20 73 69 7a 65 20 69 73 20 67 72 65  ffer size is gre
1b270 61 74 65 72 20 74 68 61 6e 20 7a 65 72 6f 2c 20  ater than zero, 
1b280 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
1b290 28 29 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 73  ().** guarantees
1b2a0 20 74 68 61 74 20 74 68 65 20 62 75 66 66 65 72   that the buffer
1b2b0 20 69 73 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d   is always zero-
1b2c0 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68  terminated.  ^Th
1b2d0 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d  e first.** param
1b2e0 65 74 65 72 20 22 6e 22 20 69 73 20 74 68 65 20  eter "n" is the 
1b2f0 74 6f 74 61 6c 20 73 69 7a 65 20 6f 66 20 74 68  total size of th
1b300 65 20 62 75 66 66 65 72 2c 20 69 6e 63 6c 75 64  e buffer, includ
1b310 69 6e 67 20 73 70 61 63 65 20 66 6f 72 0a 2a 2a  ing space for.**
1b320 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e   the zero termin
1b330 61 74 6f 72 2e 20 20 53 6f 20 74 68 65 20 6c 6f  ator.  So the lo
1b340 6e 67 65 73 74 20 73 74 72 69 6e 67 20 74 68 61  ngest string tha
1b350 74 20 63 61 6e 20 62 65 20 63 6f 6d 70 6c 65 74  t can be complet
1b360 65 6c 79 0a 2a 2a 20 77 72 69 74 74 65 6e 20 77  ely.** written w
1b370 69 6c 6c 20 62 65 20 6e 2d 31 20 63 68 61 72 61  ill be n-1 chara
1b380 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  cters..**.** ^Th
1b390 65 20 73 71 6c 69 74 65 33 5f 76 73 6e 70 72 69  e sqlite3_vsnpri
1b3a0 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73  ntf() routine is
1b3b0 20 61 20 76 61 72 61 72 67 73 20 76 65 72 73 69   a varargs versi
1b3c0 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e  on of sqlite3_sn
1b3d0 70 72 69 6e 74 66 28 29 2e 0a 2a 2a 0a 2a 2a 20  printf()..**.** 
1b3e0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
1b3f0 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d  ll implement som
1b400 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 6f 72  e additional for
1b410 6d 61 74 74 69 6e 67 0a 2a 2a 20 6f 70 74 69 6f  matting.** optio
1b420 6e 73 20 74 68 61 74 20 61 72 65 20 75 73 65 66  ns that are usef
1b430 75 6c 20 66 6f 72 20 63 6f 6e 73 74 72 75 63 74  ul for construct
1b440 69 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ing SQL statemen
1b450 74 73 2e 0a 2a 2a 20 41 6c 6c 20 6f 66 20 74 68  ts..** All of th
1b460 65 20 75 73 75 61 6c 20 70 72 69 6e 74 66 28 29  e usual printf()
1b470 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69   formatting opti
1b480 6f 6e 73 20 61 70 70 6c 79 2e 20 20 49 6e 20 61  ons apply.  In a
1b490 64 64 69 74 69 6f 6e 2c 20 74 68 65 72 65 0a 2a  ddition, there.*
1b4a0 2a 20 69 73 20 61 72 65 20 22 25 71 22 2c 20 22  * is are "%q", "
1b4b0 25 51 22 2c 20 61 6e 64 20 22 25 7a 22 20 6f 70  %Q", and "%z" op
1b4c0 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  tions..**.** ^(T
1b4d0 68 65 20 25 71 20 6f 70 74 69 6f 6e 20 77 6f 72  he %q option wor
1b4e0 6b 73 20 6c 69 6b 65 20 25 73 20 69 6e 20 74 68  ks like %s in th
1b4f0 61 74 20 69 74 20 73 75 62 73 74 69 74 75 74 65  at it substitute
1b500 73 20 61 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74  s a nul-terminat
1b510 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 66 72 6f  ed.** string fro
1b520 6d 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 6c  m the argument l
1b530 69 73 74 2e 20 20 42 75 74 20 25 71 20 61 6c 73  ist.  But %q als
1b540 6f 20 64 6f 75 62 6c 65 73 20 65 76 65 72 79 20  o doubles every 
1b550 27 5c 27 27 20 63 68 61 72 61 63 74 65 72 2e 0a  '\'' character..
1b560 2a 2a 20 25 71 20 69 73 20 64 65 73 69 67 6e 65  ** %q is designe
1b570 64 20 66 6f 72 20 75 73 65 20 69 6e 73 69 64 65  d for use inside
1b580 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61   a string litera
1b590 6c 2e 29 5e 20 20 42 79 20 64 6f 75 62 6c 69 6e  l.)^  By doublin
1b5a0 67 20 65 61 63 68 20 27 5c 27 27 0a 2a 2a 20 63  g each '\''.** c
1b5b0 68 61 72 61 63 74 65 72 20 69 74 20 65 73 63 61  haracter it esca
1b5c0 70 65 73 20 74 68 61 74 20 63 68 61 72 61 63 74  pes that charact
1b5d0 65 72 20 61 6e 64 20 61 6c 6c 6f 77 73 20 69 74  er and allows it
1b5e0 20 74 6f 20 62 65 20 69 6e 73 65 72 74 65 64 20   to be inserted 
1b5f0 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 73 74 72 69  into.** the stri
1b600 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78  ng..**.** For ex
1b610 61 6d 70 6c 65 2c 20 61 73 73 75 6d 65 20 74 68  ample, assume th
1b620 65 20 73 74 72 69 6e 67 20 76 61 72 69 61 62 6c  e string variabl
1b630 65 20 7a 54 65 78 74 20 63 6f 6e 74 61 69 6e 73  e zText contains
1b640 20 74 65 78 74 20 61 73 20 66 6f 6c 6c 6f 77 73   text as follows
1b650 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
1b660 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68  ote><pre>.**  ch
1b670 61 72 20 2a 7a 54 65 78 74 20 3d 20 22 49 74 27  ar *zText = "It'
1b680 73 20 61 20 68 61 70 70 79 20 64 61 79 21 22 3b  s a happy day!";
1b690 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
1b6a0 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e  kquote>.**.** On
1b6b0 65 20 63 61 6e 20 75 73 65 20 74 68 69 73 20 74  e can use this t
1b6c0 65 78 74 20 69 6e 20 61 6e 20 53 51 4c 20 73 74  ext in an SQL st
1b6d0 61 74 65 6d 65 6e 74 20 61 73 20 66 6f 6c 6c 6f  atement as follo
1b6e0 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ws:.**.** <block
1b6f0 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
1b700 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c  char *zSQL = sql
1b710 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e  ite3_mprintf("IN
1b720 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20  SERT INTO table 
1b730 56 41 4c 55 45 53 28 27 25 71 27 29 22 2c 20 7a  VALUES('%q')", z
1b740 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74  Text);.**  sqlit
1b750 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c  e3_exec(db, zSQL
1b760 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20  , 0, 0, 0);.**  
1b770 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51  sqlite3_free(zSQ
1b780 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  L);.** </pre></b
1b790 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
1b7a0 20 42 65 63 61 75 73 65 20 74 68 65 20 25 71 20   Because the %q 
1b7b0 66 6f 72 6d 61 74 20 73 74 72 69 6e 67 20 69 73  format string is
1b7c0 20 75 73 65 64 2c 20 74 68 65 20 27 5c 27 27 20   used, the '\'' 
1b7d0 63 68 61 72 61 63 74 65 72 20 69 6e 20 7a 54 65  character in zTe
1b7e0 78 74 0a 2a 2a 20 69 73 20 65 73 63 61 70 65 64  xt.** is escaped
1b7f0 20 61 6e 64 20 74 68 65 20 53 51 4c 20 67 65 6e   and the SQL gen
1b800 65 72 61 74 65 64 20 69 73 20 61 73 20 66 6f 6c  erated is as fol
1b810 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  lows:.**.** <blo
1b820 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
1b830 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61    INSERT INTO ta
1b840 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74 27  ble1 VALUES('It'
1b850 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21 27  's a happy day!'
1b860 29 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ).** </pre></blo
1b870 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54  ckquote>.**.** T
1b880 68 69 73 20 69 73 20 63 6f 72 72 65 63 74 2e 20  his is correct. 
1b890 20 48 61 64 20 77 65 20 75 73 65 64 20 25 73 20   Had we used %s 
1b8a0 69 6e 73 74 65 61 64 20 6f 66 20 25 71 2c 20 74  instead of %q, t
1b8b0 68 65 20 67 65 6e 65 72 61 74 65 64 20 53 51 4c  he generated SQL
1b8c0 0a 2a 2a 20 77 6f 75 6c 64 20 68 61 76 65 20 6c  .** would have l
1b8d0 6f 6f 6b 65 64 20 6c 69 6b 65 20 74 68 69 73 3a  ooked like this:
1b8e0 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
1b8f0 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53  te><pre>.**  INS
1b900 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20  ERT INTO table1 
1b910 56 41 4c 55 45 53 28 27 49 74 27 73 20 61 20 68  VALUES('It's a h
1b920 61 70 70 79 20 64 61 79 21 27 29 3b 0a 2a 2a 20  appy day!');.** 
1b930 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
1b940 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73  te>.**.** This s
1b950 65 63 6f 6e 64 20 65 78 61 6d 70 6c 65 20 69 73  econd example is
1b960 20 61 6e 20 53 51 4c 20 73 79 6e 74 61 78 20 65   an SQL syntax e
1b970 72 72 6f 72 2e 20 20 41 73 20 61 20 67 65 6e 65  rror.  As a gene
1b980 72 61 6c 20 72 75 6c 65 20 79 6f 75 20 73 68 6f  ral rule you sho
1b990 75 6c 64 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73  uld.** always us
1b9a0 65 20 25 71 20 69 6e 73 74 65 61 64 20 6f 66 20  e %q instead of 
1b9b0 25 73 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e  %s when insertin
1b9c0 67 20 74 65 78 74 20 69 6e 74 6f 20 61 20 73 74  g text into a st
1b9d0 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a  ring literal..**
1b9e0 0a 2a 2a 20 5e 28 54 68 65 20 25 51 20 6f 70 74  .** ^(The %Q opt
1b9f0 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25  ion works like %
1ba00 71 20 65 78 63 65 70 74 20 69 74 20 61 6c 73 6f  q except it also
1ba10 20 61 64 64 73 20 73 69 6e 67 6c 65 20 71 75 6f   adds single quo
1ba20 74 65 73 20 61 72 6f 75 6e 64 0a 2a 2a 20 74 68  tes around.** th
1ba30 65 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65  e outside of the
1ba40 20 74 6f 74 61 6c 20 73 74 72 69 6e 67 2e 20 20   total string.  
1ba50 41 64 64 69 74 69 6f 6e 61 6c 6c 79 2c 20 69 66  Additionally, if
1ba60 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69   the parameter i
1ba70 6e 20 74 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e  n the.** argumen
1ba80 74 20 6c 69 73 74 20 69 73 20 61 20 4e 55 4c 4c  t list is a NULL
1ba90 20 70 6f 69 6e 74 65 72 2c 20 25 51 20 73 75 62   pointer, %Q sub
1baa0 73 74 69 74 75 74 65 73 20 74 68 65 20 74 65 78  stitutes the tex
1bab0 74 20 22 4e 55 4c 4c 22 20 28 77 69 74 68 6f 75  t "NULL" (withou
1bac0 74 0a 2a 2a 20 73 69 6e 67 6c 65 20 71 75 6f 74  t.** single quot
1bad0 65 73 29 2e 29 5e 20 20 53 6f 2c 20 66 6f 72 20  es).)^  So, for 
1bae0 65 78 61 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f 75  example, one cou
1baf0 6c 64 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ld say:.**.** <b
1bb00 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
1bb10 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d  **  char *zSQL =
1bb20 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66   sqlite3_mprintf
1bb30 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61  ("INSERT INTO ta
1bb40 62 6c 65 20 56 41 4c 55 45 53 28 25 51 29 22 2c  ble VALUES(%Q)",
1bb50 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c   zText);.**  sql
1bb60 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53  ite3_exec(db, zS
1bb70 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a  QL, 0, 0, 0);.**
1bb80 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a    sqlite3_free(z
1bb90 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  SQL);.** </pre><
1bba0 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
1bbb0 2a 2a 20 54 68 65 20 63 6f 64 65 20 61 62 6f 76  ** The code abov
1bbc0 65 20 77 69 6c 6c 20 72 65 6e 64 65 72 20 61 20  e will render a 
1bbd0 63 6f 72 72 65 63 74 20 53 51 4c 20 73 74 61 74  correct SQL stat
1bbe0 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 7a 53 51  ement in the zSQ
1bbf0 4c 0a 2a 2a 20 76 61 72 69 61 62 6c 65 20 65 76  L.** variable ev
1bc00 65 6e 20 69 66 20 74 68 65 20 7a 54 65 78 74 20  en if the zText 
1bc10 76 61 72 69 61 62 6c 65 20 69 73 20 61 20 4e 55  variable is a NU
1bc20 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  LL pointer..**.*
1bc30 2a 20 5e 28 54 68 65 20 22 25 7a 22 20 66 6f 72  * ^(The "%z" for
1bc40 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20 77  matting option w
1bc50 6f 72 6b 73 20 6c 69 6b 65 20 22 25 73 22 20 62  orks like "%s" b
1bc60 75 74 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 61  ut with the.** a
1bc70 64 64 69 74 69 6f 6e 20 74 68 61 74 20 61 66 74  ddition that aft
1bc80 65 72 20 74 68 65 20 73 74 72 69 6e 67 20 68 61  er the string ha
1bc90 73 20 62 65 65 6e 20 72 65 61 64 20 61 6e 64 20  s been read and 
1bca0 63 6f 70 69 65 64 20 69 6e 74 6f 0a 2a 2a 20 74  copied into.** t
1bcb0 68 65 20 72 65 73 75 6c 74 2c 20 5b 73 71 6c 69  he result, [sqli
1bcc0 74 65 33 5f 66 72 65 65 28 29 5d 20 69 73 20 63  te3_free()] is c
1bcd0 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20 69 6e 70  alled on the inp
1bce0 75 74 20 73 74 72 69 6e 67 2e 29 5e 0a 2a 2f 0a  ut string.)^.*/.
1bcf0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 6d 70  char *sqlite3_mp
1bd00 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72  rintf(const char
1bd10 2a 2c 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71  *,...);.char *sq
1bd20 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 63  lite3_vmprintf(c
1bd30 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c  onst char*, va_l
1bd40 69 73 74 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69  ist);.char *sqli
1bd50 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 69 6e 74  te3_snprintf(int
1bd60 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61  ,char*,const cha
1bd70 72 2a 2c 20 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a  r*, ...);.char *
1bd80 73 71 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e 74  sqlite3_vsnprint
1bd90 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73  f(int,char*,cons
1bda0 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74  t char*, va_list
1bdb0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1bdc0 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63  EF: Memory Alloc
1bdd0 61 74 69 6f 6e 20 53 75 62 73 79 73 74 65 6d 0a  ation Subsystem.
1bde0 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65  **.** The SQLite
1bdf0 20 63 6f 72 65 20 75 73 65 73 20 74 68 65 73 65   core uses these
1be00 20 74 68 72 65 65 20 72 6f 75 74 69 6e 65 73 20   three routines 
1be10 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 6f  for all of its o
1be20 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 20 6d  wn.** internal m
1be30 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
1be40 20 6e 65 65 64 73 2e 20 22 43 6f 72 65 22 20 69   needs. "Core" i
1be50 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 73  n the previous s
1be60 65 6e 74 65 6e 63 65 0a 2a 2a 20 64 6f 65 73 20  entence.** does 
1be70 6e 6f 74 20 69 6e 63 6c 75 64 65 20 6f 70 65 72  not include oper
1be80 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65  ating-system spe
1be90 63 69 66 69 63 20 56 46 53 20 69 6d 70 6c 65 6d  cific VFS implem
1bea0 65 6e 74 61 74 69 6f 6e 2e 20 20 54 68 65 0a 2a  entation.  The.*
1beb0 2a 20 57 69 6e 64 6f 77 73 20 56 46 53 20 75 73  * Windows VFS us
1bec0 65 73 20 6e 61 74 69 76 65 20 6d 61 6c 6c 6f 63  es native malloc
1bed0 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 66 6f  () and free() fo
1bee0 72 20 73 6f 6d 65 20 6f 70 65 72 61 74 69 6f 6e  r some operation
1bef0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  s..**.** ^The sq
1bf00 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72  lite3_malloc() r
1bf10 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61  outine returns a
1bf20 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 62 6c   pointer to a bl
1bf30 6f 63 6b 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79  ock.** of memory
1bf40 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65   at least N byte
1bf50 73 20 69 6e 20 6c 65 6e 67 74 68 2c 20 77 68 65  s in length, whe
1bf60 72 65 20 4e 20 69 73 20 74 68 65 20 70 61 72 61  re N is the para
1bf70 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 73 71  meter..** ^If sq
1bf80 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69  lite3_malloc() i
1bf90 73 20 75 6e 61 62 6c 65 20 74 6f 20 6f 62 74 61  s unable to obta
1bfa0 69 6e 20 73 75 66 66 69 63 69 65 6e 74 20 66 72  in sufficient fr
1bfb0 65 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 69 74  ee.** memory, it
1bfc0 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20   returns a NULL 
1bfd0 70 6f 69 6e 74 65 72 2e 20 20 5e 49 66 20 74 68  pointer.  ^If th
1bfe0 65 20 70 61 72 61 6d 65 74 65 72 20 4e 20 74 6f  e parameter N to
1bff0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  .** sqlite3_mall
1c000 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 20  oc() is zero or 
1c010 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 73 71  negative then sq
1c020 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72  lite3_malloc() r
1c030 65 74 75 72 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c  eturns.** a NULL
1c040 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
1c050 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33  ^Calling sqlite3
1c060 5f 66 72 65 65 28 29 20 77 69 74 68 20 61 20 70  _free() with a p
1c070 6f 69 6e 74 65 72 20 70 72 65 76 69 6f 75 73 6c  ointer previousl
1c080 79 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79  y returned.** by
1c090 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
1c0a0 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61  ) or sqlite3_rea
1c0b0 6c 6c 6f 63 28 29 20 72 65 6c 65 61 73 65 73 20  lloc() releases 
1c0c0 74 68 61 74 20 6d 65 6d 6f 72 79 20 73 6f 0a 2a  that memory so.*
1c0d0 2a 20 74 68 61 74 20 69 74 20 6d 69 67 68 74 20  * that it might 
1c0e0 62 65 20 72 65 75 73 65 64 2e 20 20 5e 54 68 65  be reused.  ^The
1c0f0 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20   sqlite3_free() 
1c100 72 6f 75 74 69 6e 65 20 69 73 0a 2a 2a 20 61 20  routine is.** a 
1c110 6e 6f 2d 6f 70 20 69 66 20 69 73 20 63 61 6c 6c  no-op if is call
1c120 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70  ed with a NULL p
1c130 6f 69 6e 74 65 72 2e 20 20 50 61 73 73 69 6e 67  ointer.  Passing
1c140 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a   a NULL pointer.
1c150 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72  ** to sqlite3_fr
1c160 65 65 28 29 20 69 73 20 68 61 72 6d 6c 65 73 73  ee() is harmless
1c170 2e 20 20 41 66 74 65 72 20 62 65 69 6e 67 20 66  .  After being f
1c180 72 65 65 64 2c 20 6d 65 6d 6f 72 79 0a 2a 2a 20  reed, memory.** 
1c190 73 68 6f 75 6c 64 20 6e 65 69 74 68 65 72 20 62  should neither b
1c1a0 65 20 72 65 61 64 20 6e 6f 72 20 77 72 69 74 74  e read nor writt
1c1b0 65 6e 2e 20 20 45 76 65 6e 20 72 65 61 64 69 6e  en.  Even readin
1c1c0 67 20 70 72 65 76 69 6f 75 73 6c 79 20 66 72 65  g previously fre
1c1d0 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6d 69 67  ed.** memory mig
1c1e0 68 74 20 72 65 73 75 6c 74 20 69 6e 20 61 20 73  ht result in a s
1c1f0 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c  egmentation faul
1c200 74 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72  t or other sever
1c210 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f  e error..** Memo
1c220 72 79 20 63 6f 72 72 75 70 74 69 6f 6e 2c 20 61  ry corruption, a
1c230 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61   segmentation fa
1c240 75 6c 74 2c 20 6f 72 20 6f 74 68 65 72 20 73 65  ult, or other se
1c250 76 65 72 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 69  vere error.** mi
1c260 67 68 74 20 72 65 73 75 6c 74 20 69 66 20 73 71  ght result if sq
1c270 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 73 20  lite3_free() is 
1c280 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 6e 6f  called with a no
1c290 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74  n-NULL pointer t
1c2a0 68 61 74 0a 2a 2a 20 77 61 73 20 6e 6f 74 20 6f  hat.** was not o
1c2b0 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c  btained from sql
1c2c0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72  ite3_malloc() or
1c2d0 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
1c2e0 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  ()..**.** ^(The 
1c2f0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1c300 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65  ) interface atte
1c310 6d 70 74 73 20 74 6f 20 72 65 73 69 7a 65 20 61  mpts to resize a
1c320 0a 2a 2a 20 70 72 69 6f 72 20 6d 65 6d 6f 72 79  .** prior memory
1c330 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 62   allocation to b
1c340 65 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74  e at least N byt
1c350 65 73 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74  es, where N is t
1c360 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72  he.** second par
1c370 61 6d 65 74 65 72 2e 20 20 54 68 65 20 6d 65 6d  ameter.  The mem
1c380 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74  ory allocation t
1c390 6f 20 62 65 20 72 65 73 69 7a 65 64 20 69 73 20  o be resized is 
1c3a0 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72  the first.** par
1c3b0 61 6d 65 74 65 72 2e 29 5e 20 5e 20 49 66 20 74  ameter.)^ ^ If t
1c3c0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
1c3d0 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65  er to sqlite3_re
1c3e0 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61 20  alloc().** is a 
1c3f0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65  NULL pointer the
1c400 6e 20 69 74 73 20 62 65 68 61 76 69 6f 72 20 69  n its behavior i
1c410 73 20 69 64 65 6e 74 69 63 61 6c 20 74 6f 20 63  s identical to c
1c420 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65  alling.** sqlite
1c430 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20 77 68 65 72  3_malloc(N) wher
1c440 65 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e  e N is the secon
1c450 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
1c460 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
1c470 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73 65 63  ..** ^If the sec
1c480 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ond parameter to
1c490 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
1c4a0 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 0a 2a 2a  () is zero or.**
1c4b0 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 74   negative then t
1c4c0 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 65  he behavior is e
1c4d0 78 61 63 74 6c 79 20 74 68 65 20 73 61 6d 65 20  xactly the same 
1c4e0 61 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71  as calling.** sq
1c4f0 6c 69 74 65 33 5f 66 72 65 65 28 50 29 20 77 68  lite3_free(P) wh
1c500 65 72 65 20 50 20 69 73 20 74 68 65 20 66 69 72  ere P is the fir
1c510 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
1c520 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1c530 29 2e 0a 2a 2a 20 5e 73 71 6c 69 74 65 33 5f 72  )..** ^sqlite3_r
1c540 65 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73  ealloc() returns
1c550 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
1c560 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
1c570 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74  n.** of at least
1c580 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65   N bytes in size
1c590 20 6f 72 20 4e 55 4c 4c 20 69 66 20 73 75 66 66   or NULL if suff
1c5a0 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20 69 73  icient memory is
1c5b0 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a   unavailable..**
1c5c0 20 5e 49 66 20 4d 20 69 73 20 74 68 65 20 73 69   ^If M is the si
1c5d0 7a 65 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20  ze of the prior 
1c5e0 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e  allocation, then
1c5f0 20 6d 69 6e 28 4e 2c 4d 29 20 62 79 74 65 73 0a   min(N,M) bytes.
1c600 2a 2a 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20  ** of the prior 
1c610 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 72 65 20 63  allocation are c
1c620 6f 70 69 65 64 20 69 6e 74 6f 20 74 68 65 20 62  opied into the b
1c630 65 67 69 6e 6e 69 6e 67 20 6f 66 20 62 75 66 66  eginning of buff
1c640 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62  er returned.** b
1c650 79 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  y sqlite3_reallo
1c660 63 28 29 20 61 6e 64 20 74 68 65 20 70 72 69 6f  c() and the prio
1c670 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20  r allocation is 
1c680 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 73 71  freed..** ^If sq
1c690 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20  lite3_realloc() 
1c6a0 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2c 20 74 68  returns NULL, th
1c6b0 65 6e 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c  en the prior all
1c6c0 6f 63 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6e 6f  ocation.** is no
1c6d0 74 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  t freed..**.** ^
1c6e0 54 68 65 20 6d 65 6d 6f 72 79 20 72 65 74 75 72  The memory retur
1c6f0 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d  ned by sqlite3_m
1c700 61 6c 6c 6f 63 28 29 20 61 6e 64 20 73 71 6c 69  alloc() and sqli
1c710 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a  te3_realloc().**
1c720 20 69 73 20 61 6c 77 61 79 73 20 61 6c 69 67 6e   is always align
1c730 65 64 20 74 6f 20 61 74 20 6c 65 61 73 74 20 61  ed to at least a
1c740 6e 20 38 20 62 79 74 65 20 62 6f 75 6e 64 61 72  n 8 byte boundar
1c750 79 2c 20 6f 72 20 74 6f 20 61 0a 2a 2a 20 34 20  y, or to a.** 4 
1c760 62 79 74 65 20 62 6f 75 6e 64 61 72 79 20 69 66  byte boundary if
1c770 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 34 5f 42   the [SQLITE_4_B
1c780 59 54 45 5f 41 4c 49 47 4e 45 44 5f 4d 41 4c 4c  YTE_ALIGNED_MALL
1c790 4f 43 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  OC] compile-time
1c7a0 0a 2a 2a 20 6f 70 74 69 6f 6e 20 69 73 20 75 73  .** option is us
1c7b0 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51 4c  ed..**.** In SQL
1c7c0 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e  ite version 3.5.
1c7d0 30 20 61 6e 64 20 33 2e 35 2e 31 2c 20 69 74 20  0 and 3.5.1, it 
1c7e0 77 61 73 20 70 6f 73 73 69 62 6c 65 20 74 6f 20  was possible to 
1c7f0 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20 53 51  define.** the SQ
1c800 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59  LITE_OMIT_MEMORY
1c810 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20 77 68 69 63  _ALLOCATION whic
1c820 68 20 77 6f 75 6c 64 20 63 61 75 73 65 20 74 68  h would cause th
1c830 65 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69 6d  e built-in.** im
1c840 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
1c850 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74  these routines t
1c860 6f 20 62 65 20 6f 6d 69 74 74 65 64 2e 20 20 54  o be omitted.  T
1c870 68 61 74 20 63 61 70 61 62 69 6c 69 74 79 0a 2a  hat capability.*
1c880 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 70  * is no longer p
1c890 72 6f 76 69 64 65 64 2e 20 20 4f 6e 6c 79 20 62  rovided.  Only b
1c8a0 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61  uilt-in memory a
1c8b0 6c 6c 6f 63 61 74 6f 72 73 20 63 61 6e 20 62 65  llocators can be
1c8c0 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 50 72 69   used..**.** Pri
1c8d0 6f 72 20 74 6f 20 53 51 4c 69 74 65 20 76 65 72  or to SQLite ver
1c8e0 73 69 6f 6e 20 33 2e 37 2e 31 30 2c 20 74 68 65  sion 3.7.10, the
1c8f0 20 57 69 6e 64 6f 77 73 20 4f 53 20 69 6e 74 65   Windows OS inte
1c900 72 66 61 63 65 20 6c 61 79 65 72 20 63 61 6c 6c  rface layer call
1c910 65 64 0a 2a 2a 20 74 68 65 20 73 79 73 74 65 6d  ed.** the system
1c920 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72   malloc() and fr
1c930 65 65 28 29 20 64 69 72 65 63 74 6c 79 20 77 68  ee() directly wh
1c940 65 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a  en converting.**
1c950 20 66 69 6c 65 6e 61 6d 65 73 20 62 65 74 77 65   filenames betwe
1c960 65 6e 20 74 68 65 20 55 54 46 2d 38 20 65 6e 63  en the UTF-8 enc
1c970 6f 64 69 6e 67 20 75 73 65 64 20 62 79 20 53 51  oding used by SQ
1c980 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68 61 74  Lite.** and what
1c990 65 76 65 72 20 66 69 6c 65 6e 61 6d 65 20 65 6e  ever filename en
1c9a0 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64 20 62  coding is used b
1c9b0 79 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72  y the particular
1c9c0 20 57 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73 74   Windows.** inst
1c9d0 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72  allation.  Memor
1c9e0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72  y allocation err
1c9f0 6f 72 73 20 77 65 72 65 20 64 65 74 65 63 74 65  ors were detecte
1ca00 64 2c 20 62 75 74 0a 2a 2a 20 74 68 65 79 20 77  d, but.** they w
1ca10 65 72 65 20 72 65 70 6f 72 74 65 64 20 62 61 63  ere reported bac
1ca20 6b 20 61 73 20 5b 53 51 4c 49 54 45 5f 43 41 4e  k as [SQLITE_CAN
1ca30 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51  TOPEN] or.** [SQ
1ca40 4c 49 54 45 5f 49 4f 45 52 52 5d 20 72 61 74 68  LITE_IOERR] rath
1ca50 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
1ca60 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68  NOMEM]..**.** Th
1ca70 65 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d 65  e pointer argume
1ca80 6e 74 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  nts to [sqlite3_
1ca90 66 72 65 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  free()] and [sql
1caa0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a  ite3_realloc()].
1cab0 2a 2a 20 6d 75 73 74 20 62 65 20 65 69 74 68 65  ** must be eithe
1cac0 72 20 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 20 70  r NULL or else p
1cad0 6f 69 6e 74 65 72 73 20 6f 62 74 61 69 6e 65 64  ointers obtained
1cae0 20 66 72 6f 6d 20 61 20 70 72 69 6f 72 0a 2a 2a   from a prior.**
1caf0 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b   invocation of [
1cb00 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1cb10 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  ] or [sqlite3_re
1cb20 61 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20 68 61  alloc()] that ha
1cb30 76 65 0a 2a 2a 20 6e 6f 74 20 79 65 74 20 62 65  ve.** not yet be
1cb40 65 6e 20 72 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a  en released..**.
1cb50 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
1cb60 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 72 65 61 64  on must not read
1cb70 20 6f 72 20 77 72 69 74 65 20 61 6e 79 20 70 61   or write any pa
1cb80 72 74 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f 63 6b  rt of.** a block
1cb90 20 6f 66 20 6d 65 6d 6f 72 79 20 61 66 74 65 72   of memory after
1cba0 20 69 74 20 68 61 73 20 62 65 65 6e 20 72 65 6c   it has been rel
1cbb0 65 61 73 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b  eased using.** [
1cbc0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20  sqlite3_free()] 
1cbd0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  or [sqlite3_real
1cbe0 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 76 6f 69 64 20  loc()]..*/.void 
1cbf0 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  *sqlite3_malloc(
1cc00 69 6e 74 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69  int);.void *sqli
1cc10 74 65 33 5f 72 65 61 6c 6c 6f 63 28 76 6f 69 64  te3_realloc(void
1cc20 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71  *, int);.void sq
1cc30 6c 69 74 65 33 5f 66 72 65 65 28 76 6f 69 64 2a  lite3_free(void*
1cc40 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1cc50 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63  EF: Memory Alloc
1cc60 61 74 6f 72 20 53 74 61 74 69 73 74 69 63 73 0a  ator Statistics.
1cc70 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 70 72 6f  **.** SQLite pro
1cc80 76 69 64 65 73 20 74 68 65 73 65 20 74 77 6f 20  vides these two 
1cc90 69 6e 74 65 72 66 61 63 65 73 20 66 6f 72 20 72  interfaces for r
1cca0 65 70 6f 72 74 69 6e 67 20 6f 6e 20 74 68 65 20  eporting on the 
1ccb0 73 74 61 74 75 73 0a 2a 2a 20 6f 66 20 74 68 65  status.** of the
1ccc0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
1ccd0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72  ()], [sqlite3_fr
1cce0 65 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69  ee()], and [sqli
1ccf0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a  te3_realloc()].*
1cd00 2a 20 72 6f 75 74 69 6e 65 73 2c 20 77 68 69 63  * routines, whic
1cd10 68 20 66 6f 72 6d 20 74 68 65 20 62 75 69 6c 74  h form the built
1cd20 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  -in memory alloc
1cd30 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 2e  ation subsystem.
1cd40 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c  .**.** ^The [sql
1cd50 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64  ite3_memory_used
1cd60 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75  ()] routine retu
1cd70 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
1cd80 66 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 6d 65  f bytes.** of me
1cd90 6d 6f 72 79 20 63 75 72 72 65 6e 74 6c 79 20 6f  mory currently o
1cda0 75 74 73 74 61 6e 64 69 6e 67 20 28 6d 61 6c 6c  utstanding (mall
1cdb0 6f 63 65 64 20 62 75 74 20 6e 6f 74 20 66 72 65  oced but not fre
1cdc0 65 64 29 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73 71  ed)..** ^The [sq
1cdd0 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67  lite3_memory_hig
1cde0 68 77 61 74 65 72 28 29 5d 20 72 6f 75 74 69 6e  hwater()] routin
1cdf0 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6d 61  e returns the ma
1ce00 78 69 6d 75 6d 0a 2a 2a 20 76 61 6c 75 65 20 6f  ximum.** value o
1ce10 66 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  f [sqlite3_memor
1ce20 79 5f 75 73 65 64 28 29 5d 20 73 69 6e 63 65 20  y_used()] since 
1ce30 74 68 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d  the high-water m
1ce40 61 72 6b 0a 2a 2a 20 77 61 73 20 6c 61 73 74 20  ark.** was last 
1ce50 72 65 73 65 74 2e 20 20 5e 54 68 65 20 76 61 6c  reset.  ^The val
1ce60 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ues returned by 
1ce70 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
1ce80 75 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b  used()] and.** [
1ce90 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68  sqlite3_memory_h
1cea0 69 67 68 77 61 74 65 72 28 29 5d 20 69 6e 63 6c  ighwater()] incl
1ceb0 75 64 65 20 61 6e 79 20 6f 76 65 72 68 65 61 64  ude any overhead
1cec0 0a 2a 2a 20 61 64 64 65 64 20 62 79 20 53 51 4c  .** added by SQL
1ced0 69 74 65 20 69 6e 20 69 74 73 20 69 6d 70 6c 65  ite in its imple
1cee0 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 73 71  mentation of [sq
1cef0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c  lite3_malloc()],
1cf00 0a 2a 2a 20 62 75 74 20 6e 6f 74 20 6f 76 65 72  .** but not over
1cf10 68 65 61 64 20 61 64 64 65 64 20 62 79 20 74 68  head added by th
1cf20 65 20 61 6e 79 20 75 6e 64 65 72 6c 79 69 6e 67  e any underlying
1cf30 20 73 79 73 74 65 6d 20 6c 69 62 72 61 72 79 0a   system library.
1cf40 2a 2a 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74  ** routines that
1cf50 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
1cf60 28 29 5d 20 6d 61 79 20 63 61 6c 6c 2e 0a 2a 2a  ()] may call..**
1cf70 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20  .** ^The memory 
1cf80 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 20  high-water mark 
1cf90 69 73 20 72 65 73 65 74 20 74 6f 20 74 68 65 20  is reset to the 
1cfa0 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66  current value of
1cfb0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  .** [sqlite3_mem
1cfc0 6f 72 79 5f 75 73 65 64 28 29 5d 20 69 66 20 61  ory_used()] if a
1cfd0 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 70  nd only if the p
1cfe0 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b  arameter to.** [
1cff0 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68  sqlite3_memory_h
1d000 69 67 68 77 61 74 65 72 28 29 5d 20 69 73 20 74  ighwater()] is t
1d010 72 75 65 2e 20 20 5e 54 68 65 20 76 61 6c 75 65  rue.  ^The value
1d020 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20   returned.** by 
1d030 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
1d040 68 69 67 68 77 61 74 65 72 28 31 29 5d 20 69 73  highwater(1)] is
1d050 20 74 68 65 20 68 69 67 68 2d 77 61 74 65 72 20   the high-water 
1d060 6d 61 72 6b 0a 2a 2a 20 70 72 69 6f 72 20 74 6f  mark.** prior to
1d070 20 74 68 65 20 72 65 73 65 74 2e 0a 2a 2f 0a 73   the reset..*/.s
1d080 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
1d090 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64  ite3_memory_used
1d0a0 28 76 6f 69 64 29 3b 0a 73 71 6c 69 74 65 33 5f  (void);.sqlite3_
1d0b0 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65  int64 sqlite3_me
1d0c0 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 69  mory_highwater(i
1d0d0 6e 74 20 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a  nt resetFlag);..
1d0e0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1d0f0 50 73 65 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75  Pseudo-Random Nu
1d100 6d 62 65 72 20 47 65 6e 65 72 61 74 6f 72 0a 2a  mber Generator.*
1d110 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 6f 6e 74  *.** SQLite cont
1d120 61 69 6e 73 20 61 20 68 69 67 68 2d 71 75 61 6c  ains a high-qual
1d130 69 74 79 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f  ity pseudo-rando
1d140 6d 20 6e 75 6d 62 65 72 20 67 65 6e 65 72 61 74  m number generat
1d150 6f 72 20 28 50 52 4e 47 29 20 75 73 65 64 20 74  or (PRNG) used t
1d160 6f 0a 2a 2a 20 73 65 6c 65 63 74 20 72 61 6e 64  o.** select rand
1d170 6f 6d 20 5b 52 4f 57 49 44 20 7c 20 52 4f 57 49  om [ROWID | ROWI
1d180 44 73 5d 20 77 68 65 6e 20 69 6e 73 65 72 74 69  Ds] when inserti
1d190 6e 67 20 6e 65 77 20 72 65 63 6f 72 64 73 20 69  ng new records i
1d1a0 6e 74 6f 20 61 20 74 61 62 6c 65 20 74 68 61 74  nto a table that
1d1b0 0a 2a 2a 20 61 6c 72 65 61 64 79 20 75 73 65 73  .** already uses
1d1c0 20 74 68 65 20 6c 61 72 67 65 73 74 20 70 6f 73   the largest pos
1d1d0 73 69 62 6c 65 20 5b 52 4f 57 49 44 5d 2e 20 20  sible [ROWID].  
1d1e0 54 68 65 20 50 52 4e 47 20 69 73 20 61 6c 73 6f  The PRNG is also
1d1f0 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65   used for.** the
1d200 20 62 75 69 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d   build-in random
1d210 28 29 20 61 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f  () and randomblo
1d220 62 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  b() SQL function
1d230 73 2e 20 20 54 68 69 73 20 69 6e 74 65 72 66 61  s.  This interfa
1d240 63 65 20 61 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70  ce allows.** app
1d250 6c 69 63 61 74 69 6f 6e 73 20 74 6f 20 61 63 63  lications to acc
1d260 65 73 73 20 74 68 65 20 73 61 6d 65 20 50 52 4e  ess the same PRN
1d270 47 20 66 6f 72 20 6f 74 68 65 72 20 70 75 72 70  G for other purp
1d280 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 63  oses..**.** ^A c
1d290 61 6c 6c 20 74 6f 20 74 68 69 73 20 72 6f 75 74  all to this rout
1d2a0 69 6e 65 20 73 74 6f 72 65 73 20 4e 20 62 79 74  ine stores N byt
1d2b0 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73  es of randomness
1d2c0 20 69 6e 74 6f 20 62 75 66 66 65 72 20 50 2e 0a   into buffer P..
1d2d0 2a 2a 20 5e 49 66 20 4e 20 69 73 20 6c 65 73 73  ** ^If N is less
1d2e0 20 74 68 61 6e 20 6f 6e 65 2c 20 74 68 65 6e 20   than one, then 
1d2f0 50 20 63 61 6e 20 62 65 20 61 20 4e 55 4c 4c 20  P can be a NULL 
1d300 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  pointer..**.** ^
1d310 49 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  If this routine 
1d320 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 70 72 65  has not been pre
1d330 76 69 6f 75 73 6c 79 20 63 61 6c 6c 65 64 20 6f  viously called o
1d340 72 20 69 66 20 74 68 65 20 70 72 65 76 69 6f 75  r if the previou
1d350 73 0a 2a 2a 20 63 61 6c 6c 20 68 61 64 20 4e 20  s.** call had N 
1d360 6c 65 73 73 20 74 68 61 6e 20 6f 6e 65 2c 20 74  less than one, t
1d370 68 65 6e 20 74 68 65 20 50 52 4e 47 20 69 73 20  hen the PRNG is 
1d380 73 65 65 64 65 64 20 75 73 69 6e 67 20 72 61 6e  seeded using ran
1d390 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6f 62 74 61 69  domness.** obtai
1d3a0 6e 65 64 20 66 72 6f 6d 20 74 68 65 20 78 52 61  ned from the xRa
1d3b0 6e 64 6f 6d 6e 65 73 73 20 6d 65 74 68 6f 64 20  ndomness method 
1d3c0 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b  of the default [
1d3d0 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a  sqlite3_vfs] obj
1d3e0 65 63 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ect..** ^If the 
1d3f0 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f  previous call to
1d400 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 68 61   this routine ha
1d410 64 20 61 6e 20 4e 20 6f 66 20 31 20 6f 72 20 6d  d an N of 1 or m
1d420 6f 72 65 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20  ore then.** the 
1d430 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73  pseudo-randomnes
1d440 73 20 69 73 20 67 65 6e 65 72 61 74 65 64 0a 2a  s is generated.*
1d450 2a 20 69 6e 74 65 72 6e 61 6c 6c 79 20 61 6e 64  * internally and
1d460 20 77 69 74 68 6f 75 74 20 72 65 63 6f 75 72 73   without recours
1d470 65 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  e to the [sqlite
1d480 33 5f 76 66 73 5d 20 78 52 61 6e 64 6f 6d 6e 65  3_vfs] xRandomne
1d490 73 73 0a 2a 2a 20 6d 65 74 68 6f 64 2e 0a 2a 2f  ss.** method..*/
1d4a0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 61  .void sqlite3_ra
1d4b0 6e 64 6f 6d 6e 65 73 73 28 69 6e 74 20 4e 2c 20  ndomness(int N, 
1d4c0 76 6f 69 64 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a  void *P);../*.**
1d4d0 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69   CAPI3REF: Compi
1d4e0 6c 65 2d 54 69 6d 65 20 41 75 74 68 6f 72 69 7a  le-Time Authoriz
1d4f0 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a  ation Callbacks.
1d500 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74  **.** ^This rout
1d510 69 6e 65 20 72 65 67 69 73 74 65 72 73 20 61 6e  ine registers an
1d520 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
1d530 62 61 63 6b 20 77 69 74 68 20 61 20 70 61 72 74  back with a part
1d540 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62  icular.** [datab
1d550 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c  ase connection],
1d560 20 73 75 70 70 6c 69 65 64 20 69 6e 20 74 68 65   supplied in the
1d570 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e   first argument.
1d580 0a 2a 2a 20 5e 54 68 65 20 61 75 74 68 6f 72 69  .** ^The authori
1d590 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
1d5a0 69 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c 20 73  invoked as SQL s
1d5b0 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 62 65  tatements are be
1d5c0 69 6e 67 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20  ing compiled.** 
1d5d0 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  by [sqlite3_prep
1d5e0 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61  are()] or its va
1d5f0 72 69 61 6e 74 73 20 5b 73 71 6c 69 74 65 33 5f  riants [sqlite3_
1d600 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 0a 2a  prepare_v2()],.*
1d610 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
1d620 72 65 31 36 28 29 5d 20 61 6e 64 20 5b 73 71 6c  re16()] and [sql
1d630 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
1d640 32 28 29 5d 2e 20 20 5e 41 74 20 76 61 72 69 6f  2()].  ^At vario
1d650 75 73 0a 2a 2a 20 70 6f 69 6e 74 73 20 64 75 72  us.** points dur
1d660 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 61 74  ing the compilat
1d670 69 6f 6e 20 70 72 6f 63 65 73 73 2c 20 61 73 20  ion process, as 
1d680 6c 6f 67 69 63 20 69 73 20 62 65 69 6e 67 20 63  logic is being c
1d690 72 65 61 74 65 64 0a 2a 2a 20 74 6f 20 70 65 72  reated.** to per
1d6a0 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 61 63 74  form various act
1d6b0 69 6f 6e 73 2c 20 74 68 65 20 61 75 74 68 6f 72  ions, the author
1d6c0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  izer callback is
1d6d0 20 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73   invoked to.** s
1d6e0 65 65 20 69 66 20 74 68 6f 73 65 20 61 63 74 69  ee if those acti
1d6f0 6f 6e 73 20 61 72 65 20 61 6c 6c 6f 77 65 64 2e  ons are allowed.
1d700 20 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65    ^The authorize
1d710 72 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c  r callback shoul
1d720 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c  d.** return [SQL
1d730 49 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77  ITE_OK] to allow
1d740 20 74 68 65 20 61 63 74 69 6f 6e 2c 20 5b 53 51   the action, [SQ
1d750 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 6f 20  LITE_IGNORE] to 
1d760 64 69 73 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20  disallow the.** 
1d770 73 70 65 63 69 66 69 63 20 61 63 74 69 6f 6e 20  specific action 
1d780 62 75 74 20 61 6c 6c 6f 77 20 74 68 65 20 53 51  but allow the SQ
1d790 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 63  L statement to c
1d7a0 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 0a 2a 2a  ontinue to be.**
1d7b0 20 63 6f 6d 70 69 6c 65 64 2c 20 6f 72 20 5b 53   compiled, or [S
1d7c0 51 4c 49 54 45 5f 44 45 4e 59 5d 20 74 6f 20 63  QLITE_DENY] to c
1d7d0 61 75 73 65 20 74 68 65 20 65 6e 74 69 72 65 20  ause the entire 
1d7e0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f  SQL statement to
1d7f0 20 62 65 0a 2a 2a 20 72 65 6a 65 63 74 65 64 20   be.** rejected 
1d800 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20  with an error.  
1d810 5e 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a  ^If the authoriz
1d820 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  er callback retu
1d830 72 6e 73 0a 2a 2a 20 61 6e 79 20 76 61 6c 75 65  rns.** any value
1d840 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
1d850 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 51  ITE_IGNORE], [SQ
1d860 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51  LITE_OK], or [SQ
1d870 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68  LITE_DENY].** th
1d880 65 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  en the [sqlite3_
1d890 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
1d8a0 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c   equivalent call
1d8b0 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64 0a   that triggered.
1d8c0 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  ** the authorize
1d8d0 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68  r will fail with
1d8e0 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67   an error messag
1d8f0 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68  e..**.** When th
1d900 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  e callback retur
1d910 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20  ns [SQLITE_OK], 
1d920 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 6f  that means the o
1d930 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 72 65 71 75  peration.** requ
1d940 65 73 74 65 64 20 69 73 20 6f 6b 2e 20 20 5e 57  ested is ok.  ^W
1d950 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  hen the callback
1d960 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
1d970 5f 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b  _DENY], the.** [
1d980 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
1d990 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c  v2()] or equival
1d9a0 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72  ent call that tr
1d9b0 69 67 67 65 72 65 64 20 74 68 65 0a 2a 2a 20 61  iggered the.** a
1d9c0 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66  uthorizer will f
1d9d0 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f  ail with an erro
1d9e0 72 20 6d 65 73 73 61 67 65 20 65 78 70 6c 61 69  r message explai
1d9f0 6e 69 6e 67 20 74 68 61 74 0a 2a 2a 20 61 63 63  ning that.** acc
1da00 65 73 73 20 69 73 20 64 65 6e 69 65 64 2e 20 0a  ess is denied. .
1da10 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
1da20 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
1da30 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
1da40 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20  lback is a copy 
1da50 6f 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20  of the third.** 
1da60 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
1da70 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74   sqlite3_set_aut
1da80 68 6f 72 69 7a 65 72 28 29 20 69 6e 74 65 72 66  horizer() interf
1da90 61 63 65 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64  ace. ^The second
1daa0 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f   parameter.** to
1dab0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73   the callback is
1dac0 20 61 6e 20 69 6e 74 65 67 65 72 20 5b 53 51 4c   an integer [SQL
1dad0 49 54 45 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f  ITE_COPY | actio
1dae0 6e 20 63 6f 64 65 5d 20 74 68 61 74 20 73 70 65  n code] that spe
1daf0 63 69 66 69 65 73 0a 2a 2a 20 74 68 65 20 70 61  cifies.** the pa
1db00 72 74 69 63 75 6c 61 72 20 61 63 74 69 6f 6e 20  rticular action 
1db10 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64  to be authorized
1db20 2e 20 5e 54 68 65 20 74 68 69 72 64 20 74 68 72  . ^The third thr
1db30 6f 75 67 68 20 73 69 78 74 68 20 70 61 72 61 6d  ough sixth param
1db40 65 74 65 72 73 0a 2a 2a 20 74 6f 20 74 68 65 20  eters.** to the 
1db50 63 61 6c 6c 62 61 63 6b 20 61 72 65 20 7a 65 72  callback are zer
1db60 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72  o-terminated str
1db70 69 6e 67 73 20 74 68 61 74 20 63 6f 6e 74 61 69  ings that contai
1db80 6e 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  n additional.** 
1db90 64 65 74 61 69 6c 73 20 61 62 6f 75 74 20 74 68  details about th
1dba0 65 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61  e action to be a
1dbb0 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a  uthorized..**.**
1dbc0 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20   ^If the action 
1dbd0 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f  code is [SQLITE_
1dbe0 52 45 41 44 5d 0a 2a 2a 20 61 6e 64 20 74 68 65  READ].** and the
1dbf0 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
1dc00 73 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  s [SQLITE_IGNORE
1dc10 5d 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 70  ] then the.** [p
1dc20 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1dc30 74 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  t] statement is 
1dc40 63 6f 6e 73 74 72 75 63 74 65 64 20 74 6f 20 73  constructed to s
1dc50 75 62 73 74 69 74 75 74 65 0a 2a 2a 20 61 20 4e  ubstitute.** a N
1dc60 55 4c 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c 61  ULL value in pla
1dc70 63 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20  ce of the table 
1dc80 63 6f 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c  column that woul
1dc90 64 20 68 61 76 65 0a 2a 2a 20 62 65 65 6e 20 72  d have.** been r
1dca0 65 61 64 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f  ead if [SQLITE_O
1dcb0 4b 5d 20 68 61 64 20 62 65 65 6e 20 72 65 74 75  K] had been retu
1dcc0 72 6e 65 64 2e 20 20 54 68 65 20 5b 53 51 4c 49  rned.  The [SQLI
1dcd0 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65  TE_IGNORE].** re
1dce0 74 75 72 6e 20 63 61 6e 20 62 65 20 75 73 65 64  turn can be used
1dcf0 20 74 6f 20 64 65 6e 79 20 61 6e 20 75 6e 74 72   to deny an untr
1dd00 75 73 74 65 64 20 75 73 65 72 20 61 63 63 65 73  usted user acces
1dd10 73 20 74 6f 20 69 6e 64 69 76 69 64 75 61 6c 0a  s to individual.
1dd20 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 61 20  ** columns of a 
1dd30 74 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 74 68  table..** ^If th
1dd40 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73  e action code is
1dd50 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d   [SQLITE_DELETE]
1dd60 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63   and the callbac
1dd70 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51  k returns.** [SQ
1dd80 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65  LITE_IGNORE] the
1dd90 6e 20 74 68 65 20 5b 44 45 4c 45 54 45 5d 20 6f  n the [DELETE] o
1dda0 70 65 72 61 74 69 6f 6e 20 70 72 6f 63 65 65 64  peration proceed
1ddb0 73 20 62 75 74 20 74 68 65 0a 2a 2a 20 5b 74 72  s but the.** [tr
1ddc0 75 6e 63 61 74 65 20 6f 70 74 69 6d 69 7a 61 74  uncate optimizat
1ddd0 69 6f 6e 5d 20 69 73 20 64 69 73 61 62 6c 65 64  ion] is disabled
1dde0 20 61 6e 64 20 61 6c 6c 20 72 6f 77 73 20 61 72   and all rows ar
1ddf0 65 20 64 65 6c 65 74 65 64 20 69 6e 64 69 76 69  e deleted indivi
1de00 64 75 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e  dually..**.** An
1de10 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 75   authorizer is u
1de20 73 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65  sed when [sqlite
1de30 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70  3_prepare | prep
1de40 61 72 69 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73 74  aring].** SQL st
1de50 61 74 65 6d 65 6e 74 73 20 66 72 6f 6d 20 61 6e  atements from an
1de60 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63   untrusted sourc
1de70 65 2c 20 74 6f 20 65 6e 73 75 72 65 20 74 68 61  e, to ensure tha
1de80 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  t the SQL statem
1de90 65 6e 74 73 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74  ents.** do not t
1dea0 72 79 20 74 6f 20 61 63 63 65 73 73 20 64 61 74  ry to access dat
1deb0 61 20 74 68 65 79 20 61 72 65 20 6e 6f 74 20 61  a they are not a
1dec0 6c 6c 6f 77 65 64 20 74 6f 20 73 65 65 2c 20 6f  llowed to see, o
1ded0 72 20 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e  r that they do n
1dee0 6f 74 0a 2a 2a 20 74 72 79 20 74 6f 20 65 78 65  ot.** try to exe
1def0 63 75 74 65 20 6d 61 6c 69 63 69 6f 75 73 20 73  cute malicious s
1df00 74 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20 64  tatements that d
1df10 61 6d 61 67 65 20 74 68 65 20 64 61 74 61 62 61  amage the databa
1df20 73 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d  se.  For.** exam
1df30 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74  ple, an applicat
1df40 69 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77 20 61 20  ion may allow a 
1df50 75 73 65 72 20 74 6f 20 65 6e 74 65 72 20 61 72  user to enter ar
1df60 62 69 74 72 61 72 79 0a 2a 2a 20 53 51 4c 20 71  bitrary.** SQL q
1df70 75 65 72 69 65 73 20 66 6f 72 20 65 76 61 6c 75  ueries for evalu
1df80 61 74 69 6f 6e 20 62 79 20 61 20 64 61 74 61 62  ation by a datab
1df90 61 73 65 2e 20 20 42 75 74 20 74 68 65 20 61 70  ase.  But the ap
1dfa0 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 0a 2a  plication does.*
1dfb0 2a 20 6e 6f 74 20 77 61 6e 74 20 74 68 65 20 75  * not want the u
1dfc0 73 65 72 20 74 6f 20 62 65 20 61 62 6c 65 20 74  ser to be able t
1dfd0 6f 20 6d 61 6b 65 20 61 72 62 69 74 72 61 72 79  o make arbitrary
1dfe0 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 0a   changes to the.
1dff0 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20 41 6e  ** database.  An
1e000 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 75 6c   authorizer coul
1e010 64 20 74 68 65 6e 20 62 65 20 70 75 74 20 69 6e  d then be put in
1e020 20 70 6c 61 63 65 20 77 68 69 6c 65 20 74 68 65   place while the
1e030 0a 2a 2a 20 75 73 65 72 2d 65 6e 74 65 72 65 64  .** user-entered
1e040 20 53 51 4c 20 69 73 20 62 65 69 6e 67 20 5b 73   SQL is being [s
1e050 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c  qlite3_prepare |
1e060 20 70 72 65 70 61 72 65 64 5d 20 74 68 61 74 0a   prepared] that.
1e070 2a 2a 20 64 69 73 61 6c 6c 6f 77 73 20 65 76 65  ** disallows eve
1e080 72 79 74 68 69 6e 67 20 65 78 63 65 70 74 20 5b  rything except [
1e090 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e  SELECT] statemen
1e0a0 74 73 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63  ts..**.** Applic
1e0b0 61 74 69 6f 6e 73 20 74 68 61 74 20 6e 65 65 64  ations that need
1e0c0 20 74 6f 20 70 72 6f 63 65 73 73 20 53 51 4c 20   to process SQL 
1e0d0 66 72 6f 6d 20 75 6e 74 72 75 73 74 65 64 20 73  from untrusted s
1e0e0 6f 75 72 63 65 73 0a 2a 2a 20 6d 69 67 68 74 20  ources.** might 
1e0f0 61 6c 73 6f 20 63 6f 6e 73 69 64 65 72 20 6c 6f  also consider lo
1e100 77 65 72 69 6e 67 20 72 65 73 6f 75 72 63 65 20  wering resource 
1e110 6c 69 6d 69 74 73 20 75 73 69 6e 67 20 5b 73 71  limits using [sq
1e120 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a  lite3_limit()].*
1e130 2a 20 61 6e 64 20 6c 69 6d 69 74 69 6e 67 20 64  * and limiting d
1e140 61 74 61 62 61 73 65 20 73 69 7a 65 20 75 73 69  atabase size usi
1e150 6e 67 20 74 68 65 20 5b 6d 61 78 5f 70 61 67 65  ng the [max_page
1e160 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d  _count] [PRAGMA]
1e170 0a 2a 2a 20 69 6e 20 61 64 64 69 74 69 6f 6e 20  .** in addition 
1e180 74 6f 20 75 73 69 6e 67 20 61 6e 20 61 75 74 68  to using an auth
1e190 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28  orizer..**.** ^(
1e1a0 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 61 75  Only a single au
1e1b0 74 68 6f 72 69 7a 65 72 20 63 61 6e 20 62 65 20  thorizer can be 
1e1c0 69 6e 20 70 6c 61 63 65 20 6f 6e 20 61 20 64 61  in place on a da
1e1d0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1e1e0 6e 0a 2a 2a 20 61 74 20 61 20 74 69 6d 65 2e 20  n.** at a time. 
1e1f0 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 73 71   Each call to sq
1e200 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
1e210 69 7a 65 72 20 6f 76 65 72 72 69 64 65 73 20 74  izer overrides t
1e220 68 65 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20 63  he.** previous c
1e230 61 6c 6c 2e 29 5e 20 20 5e 44 69 73 61 62 6c 65  all.)^  ^Disable
1e240 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
1e250 62 79 20 69 6e 73 74 61 6c 6c 69 6e 67 20 61 20  by installing a 
1e260 4e 55 4c 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a  NULL callback..*
1e270 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72  * The authorizer
1e280 20 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 20   is disabled by 
1e290 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54  default..**.** T
1e2a0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
1e2b0 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20  llback must not 
1e2c0 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74  do anything that
1e2d0 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20   will modify.** 
1e2e0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
1e2f0 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76  nection that inv
1e300 6f 6b 65 64 20 74 68 65 20 61 75 74 68 6f 72 69  oked the authori
1e310 7a 65 72 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a  zer callback..**
1e320 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69   Note that [sqli
1e330 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
1e340 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73  ] and [sqlite3_s
1e350 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69  tep()] both modi
1e360 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61  fy their.** data
1e370 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
1e380 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67   for the meaning
1e390 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20   of "modify" in 
1e3a0 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a  this paragraph..
1e3b0 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 5b 73 71 6c  **.** ^When [sql
1e3c0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1e3d0 29 5d 20 69 73 20 75 73 65 64 20 74 6f 20 70 72  )] is used to pr
1e3e0 65 70 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e  epare a statemen
1e3f0 74 2c 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d  t, the.** statem
1e400 65 6e 74 20 6d 69 67 68 74 20 62 65 20 72 65 2d  ent might be re-
1e410 70 72 65 70 61 72 65 64 20 64 75 72 69 6e 67 20  prepared during 
1e420 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
1e430 20 64 75 65 20 74 6f 20 61 20 0a 2a 2a 20 73 63   due to a .** sc
1e440 68 65 6d 61 20 63 68 61 6e 67 65 2e 20 20 48 65  hema change.  He
1e450 6e 63 65 2c 20 74 68 65 20 61 70 70 6c 69 63 61  nce, the applica
1e460 74 69 6f 6e 20 73 68 6f 75 6c 64 20 65 6e 73 75  tion should ensu
1e470 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 63  re that the.** c
1e480 6f 72 72 65 63 74 20 61 75 74 68 6f 72 69 7a 65  orrect authorize
1e490 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 6d 61 69  r callback remai
1e4a0 6e 73 20 69 6e 20 70 6c 61 63 65 20 64 75 72 69  ns in place duri
1e4b0 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ng the [sqlite3_
1e4c0 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  step()]..**.** ^
1e4d0 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 61 75  Note that the au
1e4e0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1e4f0 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c  k is invoked onl
1e500 79 20 64 75 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c  y during.** [sql
1e510 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
1e520 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e  or its variants.
1e530 20 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20    Authorization 
1e540 69 73 20 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f 72  is not.** perfor
1e550 6d 65 64 20 64 75 72 69 6e 67 20 73 74 61 74 65  med during state
1e560 6d 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20  ment evaluation 
1e570 69 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  in [sqlite3_step
1e580 28 29 5d 2c 20 75 6e 6c 65 73 73 0a 2a 2a 20 61  ()], unless.** a
1e590 73 20 73 74 61 74 65 64 20 69 6e 20 74 68 65 20  s stated in the 
1e5a0 70 72 65 76 69 6f 75 73 20 70 61 72 61 67 72 61  previous paragra
1e5b0 70 68 2c 20 73 71 6c 69 74 65 33 5f 73 74 65 70  ph, sqlite3_step
1e5c0 28 29 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 73 71  () invokes.** sq
1e5d0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
1e5e0 28 29 20 74 6f 20 72 65 70 72 65 70 61 72 65 20  () to reprepare 
1e5f0 61 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65  a statement afte
1e600 72 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e 67  r a schema chang
1e610 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  e..*/.int sqlite
1e620 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
1e630 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20  (.  sqlite3*,.  
1e640 69 6e 74 20 28 2a 78 41 75 74 68 29 28 76 6f 69  int (*xAuth)(voi
1e650 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61  d*,int,const cha
1e660 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63  r*,const char*,c
1e670 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74  onst char*,const
1e680 20 63 68 61 72 2a 29 2c 0a 20 20 76 6f 69 64 20   char*),.  void 
1e690 2a 70 55 73 65 72 44 61 74 61 0a 29 3b 0a 0a 2f  *pUserData.);../
1e6a0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41  *.** CAPI3REF: A
1e6b0 75 74 68 6f 72 69 7a 65 72 20 52 65 74 75 72 6e  uthorizer Return
1e6c0 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65   Codes.**.** The
1e6d0 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
1e6e0 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f  thorizer | autho
1e6f0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 66  rizer callback f
1e700 75 6e 63 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a  unction] must.**
1e710 20 72 65 74 75 72 6e 20 65 69 74 68 65 72 20 5b   return either [
1e720 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e  SQLITE_OK] or on
1e730 65 20 6f 66 20 74 68 65 73 65 20 74 77 6f 20 63  e of these two c
1e740 6f 6e 73 74 61 6e 74 73 20 69 6e 20 6f 72 64 65  onstants in orde
1e750 72 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20 53  r.** to signal S
1e760 51 4c 69 74 65 20 77 68 65 74 68 65 72 20 6f 72  QLite whether or
1e770 20 6e 6f 74 20 74 68 65 20 61 63 74 69 6f 6e 20   not the action 
1e780 69 73 20 70 65 72 6d 69 74 74 65 64 2e 20 20 53  is permitted.  S
1e790 65 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ee the.** [sqlit
1e7a0 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
1e7b0 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 64  r | authorizer d
1e7c0 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f  ocumentation] fo
1e7d0 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  r additional.** 
1e7e0 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a  information..**.
1e7f0 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 51 4c  ** Note that SQL
1e800 49 54 45 5f 49 47 4e 4f 52 45 20 69 73 20 61 6c  ITE_IGNORE is al
1e810 73 6f 20 75 73 65 64 20 61 73 20 61 20 5b 53 51  so used as a [SQ
1e820 4c 49 54 45 5f 52 4f 4c 4c 42 41 43 4b 20 7c 20  LITE_ROLLBACK | 
1e830 72 65 74 75 72 6e 20 63 6f 64 65 5d 0a 2a 2a 20  return code].** 
1e840 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65  from the [sqlite
1e850 33 5f 76 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69  3_vtab_on_confli
1e860 63 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  ct()] interface.
1e870 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
1e880 54 45 5f 44 45 4e 59 20 20 20 31 20 20 20 2f 2a  TE_DENY   1   /*
1e890 20 41 62 6f 72 74 20 74 68 65 20 53 51 4c 20 73   Abort the SQL s
1e8a0 74 61 74 65 6d 65 6e 74 20 77 69 74 68 20 61 6e  tatement with an
1e8b0 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e   error */.#defin
1e8c0 65 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20  e SQLITE_IGNORE 
1e8d0 32 20 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c  2   /* Don't all
1e8e0 6f 77 20 61 63 63 65 73 73 2c 20 62 75 74 20 64  ow access, but d
1e8f0 6f 6e 27 74 20 67 65 6e 65 72 61 74 65 20 61 6e  on't generate an
1e900 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a   error */../*.**
1e910 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f   CAPI3REF: Autho
1e920 72 69 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f 64  rizer Action Cod
1e930 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71  es.**.** The [sq
1e940 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
1e950 69 7a 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63  izer()] interfac
1e960 65 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61  e registers a ca
1e970 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a  llback function.
1e980 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b  ** that is invok
1e990 65 64 20 74 6f 20 61 75 74 68 6f 72 69 7a 65 20  ed to authorize 
1e9a0 63 65 72 74 61 69 6e 20 53 51 4c 20 73 74 61 74  certain SQL stat
1e9b0 65 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e 20 20  ement actions.  
1e9c0 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61  The.** second pa
1e9d0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63  rameter to the c
1e9e0 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e  allback is an in
1e9f0 74 65 67 65 72 20 63 6f 64 65 20 74 68 61 74 20  teger code that 
1ea00 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 61  specifies.** wha
1ea10 74 20 61 63 74 69 6f 6e 20 69 73 20 62 65 69 6e  t action is bein
1ea20 67 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54  g authorized.  T
1ea30 68 65 73 65 20 61 72 65 20 74 68 65 20 69 6e 74  hese are the int
1ea40 65 67 65 72 20 61 63 74 69 6f 6e 20 63 6f 64 65  eger action code
1ea50 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 61 75  s that.** the au
1ea60 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1ea70 6b 20 6d 61 79 20 62 65 20 70 61 73 73 65 64 2e  k may be passed.
1ea80 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 63 74  .**.** These act
1ea90 69 6f 6e 20 63 6f 64 65 20 76 61 6c 75 65 73 20  ion code values 
1eaa0 73 69 67 6e 69 66 79 20 77 68 61 74 20 6b 69 6e  signify what kin
1eab0 64 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e 20 69  d of operation i
1eac0 73 20 74 6f 20 62 65 0a 2a 2a 20 61 75 74 68 6f  s to be.** autho
1ead0 72 69 7a 65 64 2e 20 20 54 68 65 20 33 72 64 20  rized.  The 3rd 
1eae0 61 6e 64 20 34 74 68 20 70 61 72 61 6d 65 74 65  and 4th paramete
1eaf0 72 73 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72  rs to the author
1eb00 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62  ization.** callb
1eb10 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c  ack function wil
1eb20 6c 20 62 65 20 70 61 72 61 6d 65 74 65 72 73 20  l be parameters 
1eb30 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e  or NULL dependin
1eb40 67 20 6f 6e 20 77 68 69 63 68 20 6f 66 20 74 68  g on which of th
1eb50 65 73 65 0a 2a 2a 20 63 6f 64 65 73 20 69 73 20  ese.** codes is 
1eb60 75 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f  used as the seco
1eb70 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e  nd parameter.  ^
1eb80 28 54 68 65 20 35 74 68 20 70 61 72 61 6d 65 74  (The 5th paramet
1eb90 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75 74  er to the.** aut
1eba0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1ebb0 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
1ebc0 74 68 65 20 64 61 74 61 62 61 73 65 20 28 22 6d  the database ("m
1ebd0 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a  ain", "temp",.**
1ebe0 20 65 74 63 2e 29 20 69 66 20 61 70 70 6c 69 63   etc.) if applic
1ebf0 61 62 6c 65 2e 29 5e 20 20 5e 54 68 65 20 36 74  able.)^  ^The 6t
1ec00 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
1ec10 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
1ec20 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 74 68 65  llback.** is the
1ec30 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 69 6e 6e   name of the inn
1ec40 65 72 2d 6d 6f 73 74 20 74 72 69 67 67 65 72 20  er-most trigger 
1ec50 6f 72 20 76 69 65 77 20 74 68 61 74 20 69 73 20  or view that is 
1ec60 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a  responsible for.
1ec70 2a 2a 20 74 68 65 20 61 63 63 65 73 73 20 61 74  ** the access at
1ec80 74 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66  tempt or NULL if
1ec90 20 74 68 69 73 20 61 63 63 65 73 73 20 61 74 74   this access att
1eca0 65 6d 70 74 20 69 73 20 64 69 72 65 63 74 6c 79  empt is directly
1ecb0 20 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76   from.** top-lev
1ecc0 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a  el SQL code..*/.
1ecd0 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  /***************
1ece0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1ecf0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64  ************ 3rd
1ed00 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74   ************ 4t
1ed10 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23  h ***********/.#
1ed20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
1ed30 45 41 54 45 5f 49 4e 44 45 58 20 20 20 20 20 20  EATE_INDEX      
1ed40 20 20 20 20 31 20 20 20 2f 2a 20 49 6e 64 65 78      1   /* Index
1ed50 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65   Name      Table
1ed60 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
1ed70 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
1ed80 41 54 45 5f 54 41 42 4c 45 20 20 20 20 20 20 20  ATE_TABLE       
1ed90 20 20 20 32 20 20 20 2f 2a 20 54 61 62 6c 65 20     2   /* Table 
1eda0 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
1edb0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
1edc0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
1edd0 54 45 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20  TE_TEMP_INDEX   
1ede0 20 20 33 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e    3   /* Index N
1edf0 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e  ame      Table N
1ee00 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
1ee10 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
1ee20 45 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20  E_TEMP_TABLE    
1ee30 20 34 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61   4   /* Table Na
1ee40 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
1ee50 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
1ee60 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
1ee70 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20  _TEMP_TRIGGER   
1ee80 35 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e  5   /* Trigger N
1ee90 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  ame    Table Nam
1eea0 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
1eeb0 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
1eec0 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20 36  TEMP_VIEW      6
1eed0 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20     /* View Name 
1eee0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1eef0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1ef00 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
1ef10 52 49 47 47 45 52 20 20 20 20 20 20 20 20 37 20  RIGGER        7 
1ef20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d    /* Trigger Nam
1ef30 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20  e    Table Name 
1ef40 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1ef50 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 49  SQLITE_CREATE_VI
1ef60 45 57 20 20 20 20 20 20 20 20 20 20 20 38 20 20  EW           8  
1ef70 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20   /* View Name   
1ef80 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
1ef90 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1efa0 51 4c 49 54 45 5f 44 45 4c 45 54 45 20 20 20 20  QLITE_DELETE    
1efb0 20 20 20 20 20 20 20 20 20 20 20 20 39 20 20 20              9   
1efc0 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
1efd0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1efe0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1eff0 4c 49 54 45 5f 44 52 4f 50 5f 49 4e 44 45 58 20  LITE_DROP_INDEX 
1f000 20 20 20 20 20 20 20 20 20 20 31 30 20 20 20 2f            10   /
1f010 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20  * Index Name    
1f020 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
1f030 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1f040 49 54 45 5f 44 52 4f 50 5f 54 41 42 4c 45 20 20  ITE_DROP_TABLE  
1f050 20 20 20 20 20 20 20 20 20 31 31 20 20 20 2f 2a           11   /*
1f060 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1f070 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1f080 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1f090 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 49 4e 44  TE_DROP_TEMP_IND
1f0a0 45 58 20 20 20 20 20 20 31 32 20 20 20 2f 2a 20  EX      12   /* 
1f0b0 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20  Index Name      
1f0c0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1f0d0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1f0e0 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 41 42 4c  E_DROP_TEMP_TABL
1f0f0 45 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20 54  E      13   /* T
1f100 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
1f110 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1f120 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1f130 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 52 49 47 47  _DROP_TEMP_TRIGG
1f140 45 52 20 20 20 20 31 34 20 20 20 2f 2a 20 54 72  ER    14   /* Tr
1f150 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61  igger Name    Ta
1f160 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
1f170 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1f180 44 52 4f 50 5f 54 45 4d 50 5f 56 49 45 57 20 20  DROP_TEMP_VIEW  
1f190 20 20 20 20 20 31 35 20 20 20 2f 2a 20 56 69 65       15   /* Vie
1f1a0 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c  w Name       NUL
1f1b0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
1f1c0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1f1d0 52 4f 50 5f 54 52 49 47 47 45 52 20 20 20 20 20  ROP_TRIGGER     
1f1e0 20 20 20 20 31 36 20 20 20 2f 2a 20 54 72 69 67      16   /* Trig
1f1f0 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c  ger Name    Tabl
1f200 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
1f210 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
1f220 4f 50 5f 56 49 45 57 20 20 20 20 20 20 20 20 20  OP_VIEW         
1f230 20 20 20 31 37 20 20 20 2f 2a 20 56 69 65 77 20     17   /* View 
1f240 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20  Name       NULL 
1f250 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
1f260 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 53  efine SQLITE_INS
1f270 45 52 54 20 20 20 20 20 20 20 20 20 20 20 20 20  ERT             
1f280 20 20 31 38 20 20 20 2f 2a 20 54 61 62 6c 65 20    18   /* Table 
1f290 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
1f2a0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
1f2b0 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 41 47  fine SQLITE_PRAG
1f2c0 4d 41 20 20 20 20 20 20 20 20 20 20 20 20 20 20  MA              
1f2d0 20 31 39 20 20 20 2f 2a 20 50 72 61 67 6d 61 20   19   /* Pragma 
1f2e0 4e 61 6d 65 20 20 20 20 20 31 73 74 20 61 72 67  Name     1st arg
1f2f0 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66   or NULL */.#def
1f300 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 20  ine SQLITE_READ 
1f310 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1f320 32 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  20   /* Table Na
1f330 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e  me      Column N
1f340 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  ame     */.#defi
1f350 6e 65 20 53 51 4c 49 54 45 5f 53 45 4c 45 43 54  ne SQLITE_SELECT
1f360 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
1f370 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20  1   /* NULL     
1f380 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
1f390 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
1f3a0 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 41 43  e SQLITE_TRANSAC
1f3b0 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20 32 32  TION          22
1f3c0 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20     /* Operation 
1f3d0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1f3e0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1f3f0 20 53 51 4c 49 54 45 5f 55 50 44 41 54 45 20 20   SQLITE_UPDATE  
1f400 20 20 20 20 20 20 20 20 20 20 20 20 20 32 33 20               23 
1f410 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
1f420 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65       Column Name
1f430 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1f440 53 51 4c 49 54 45 5f 41 54 54 41 43 48 20 20 20  SQLITE_ATTACH   
1f450 20 20 20 20 20 20 20 20 20 20 20 20 32 34 20 20              24  
1f460 20 2f 2a 20 46 69 6c 65 6e 61 6d 65 20 20 20 20   /* Filename    
1f470 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
1f480 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1f490 51 4c 49 54 45 5f 44 45 54 41 43 48 20 20 20 20  QLITE_DETACH    
1f4a0 20 20 20 20 20 20 20 20 20 20 20 32 35 20 20 20             25   
1f4b0 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65  /* Database Name
1f4c0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1f4d0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1f4e0 4c 49 54 45 5f 41 4c 54 45 52 5f 54 41 42 4c 45  LITE_ALTER_TABLE
1f4f0 20 20 20 20 20 20 20 20 20 20 32 36 20 20 20 2f            26   /
1f500 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20  * Database Name 
1f510 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
1f520 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1f530 49 54 45 5f 52 45 49 4e 44 45 58 20 20 20 20 20  ITE_REINDEX     
1f540 20 20 20 20 20 20 20 20 20 32 37 20 20 20 2f 2a           27   /*
1f550 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20   Index Name     
1f560 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1f570 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1f580 54 45 5f 41 4e 41 4c 59 5a 45 20 20 20 20 20 20  TE_ANALYZE      
1f590 20 20 20 20 20 20 20 20 32 38 20 20 20 2f 2a 20          28   /* 
1f5a0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1f5b0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1f5c0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1f5d0 45 5f 43 52 45 41 54 45 5f 56 54 41 42 4c 45 20  E_CREATE_VTABLE 
1f5e0 20 20 20 20 20 20 20 32 39 20 20 20 2f 2a 20 54         29   /* T
1f5f0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d  able Name      M
1f600 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a  odule Name     *
1f610 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1f620 5f 44 52 4f 50 5f 56 54 41 42 4c 45 20 20 20 20  _DROP_VTABLE    
1f630 20 20 20 20 20 20 33 30 20 20 20 2f 2a 20 54 61        30   /* Ta
1f640 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f  ble Name      Mo
1f650 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f  dule Name     */
1f660 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1f670 46 55 4e 43 54 49 4f 4e 20 20 20 20 20 20 20 20  FUNCTION        
1f680 20 20 20 20 20 33 31 20 20 20 2f 2a 20 4e 55 4c       31   /* NUL
1f690 4c 20 20 20 20 20 20 20 20 20 20 20 20 46 75 6e  L            Fun
1f6a0 63 74 69 6f 6e 20 4e 61 6d 65 20 20 20 2a 2f 0a  ction Name   */.
1f6b0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
1f6c0 41 56 45 50 4f 49 4e 54 20 20 20 20 20 20 20 20  AVEPOINT        
1f6d0 20 20 20 20 33 32 20 20 20 2f 2a 20 4f 70 65 72      32   /* Oper
1f6e0 61 74 69 6f 6e 20 20 20 20 20 20 20 53 61 76 65  ation       Save
1f6f0 70 6f 69 6e 74 20 4e 61 6d 65 20 20 2a 2f 0a 23  point Name  */.#
1f700 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
1f710 50 59 20 20 20 20 20 20 20 20 20 20 20 20 20 20  PY              
1f720 20 20 20 20 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f      0   /* No lo
1f730 6e 67 65 72 20 75 73 65 64 20 2a 2f 0a 23 64 65  nger used */.#de
1f740 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 43 55  fine SQLITE_RECU
1f750 52 53 49 56 45 20 20 20 20 20 20 20 20 20 20 20  RSIVE           
1f760 20 33 33 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20   33   /* NULL   
1f770 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20           NULL   
1f780 20 20 20 20 20 20 20 20 20 2a 2f 0a 0a 2f 2a 0a           */../*.
1f790 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 72 61  ** CAPI3REF: Tra
1f7a0 63 69 6e 67 20 41 6e 64 20 50 72 6f 66 69 6c 69  cing And Profili
1f7b0 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a  ng Functions.**.
1f7c0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
1f7d0 73 20 72 65 67 69 73 74 65 72 20 63 61 6c 6c 62  s register callb
1f7e0 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20 74 68  ack functions th
1f7f0 61 74 20 63 61 6e 20 62 65 20 75 73 65 64 20 66  at can be used f
1f800 6f 72 0a 2a 2a 20 74 72 61 63 69 6e 67 20 61 6e  or.** tracing an
1f810 64 20 70 72 6f 66 69 6c 69 6e 67 20 74 68 65 20  d profiling the 
1f820 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 53 51 4c  execution of SQL
1f830 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a   statements..**.
1f840 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b  ** ^The callback
1f850 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74   function regist
1f860 65 72 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  ered by sqlite3_
1f870 74 72 61 63 65 28 29 20 69 73 20 69 6e 76 6f 6b  trace() is invok
1f880 65 64 20 61 74 0a 2a 2a 20 76 61 72 69 6f 75 73  ed at.** various
1f890 20 74 69 6d 65 73 20 77 68 65 6e 20 61 6e 20 53   times when an S
1f8a0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  QL statement is 
1f8b0 62 65 69 6e 67 20 72 75 6e 20 62 79 20 5b 73 71  being run by [sq
1f8c0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a  lite3_step()]..*
1f8d0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74  * ^The sqlite3_t
1f8e0 72 61 63 65 28 29 20 63 61 6c 6c 62 61 63 6b 20  race() callback 
1f8f0 69 73 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20  is invoked with 
1f900 61 20 55 54 46 2d 38 20 72 65 6e 64 65 72 69 6e  a UTF-8 renderin
1f910 67 20 6f 66 20 74 68 65 0a 2a 2a 20 53 51 4c 20  g of the.** SQL 
1f920 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61  statement text a
1f930 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  s the statement 
1f940 66 69 72 73 74 20 62 65 67 69 6e 73 20 65 78 65  first begins exe
1f950 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e 28 41 64 64  cuting..** ^(Add
1f960 69 74 69 6f 6e 61 6c 20 73 71 6c 69 74 65 33 5f  itional sqlite3_
1f970 74 72 61 63 65 28 29 20 63 61 6c 6c 62 61 63 6b  trace() callback
1f980 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a  s might occur.**
1f990 20 61 73 20 65 61 63 68 20 74 72 69 67 67 65 72   as each trigger
1f9a0 65 64 20 73 75 62 70 72 6f 67 72 61 6d 20 69 73  ed subprogram is
1f9b0 20 65 6e 74 65 72 65 64 2e 20 20 54 68 65 20 63   entered.  The c
1f9c0 61 6c 6c 62 61 63 6b 73 20 66 6f 72 20 74 72 69  allbacks for tri
1f9d0 67 67 65 72 73 0a 2a 2a 20 63 6f 6e 74 61 69 6e  ggers.** contain
1f9e0 20 61 20 55 54 46 2d 38 20 53 51 4c 20 63 6f 6d   a UTF-8 SQL com
1f9f0 6d 65 6e 74 20 74 68 61 74 20 69 64 65 6e 74 69  ment that identi
1fa00 66 69 65 73 20 74 68 65 20 74 72 69 67 67 65 72  fies the trigger
1fa10 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53  .)^.**.** The [S
1fa20 51 4c 49 54 45 5f 54 52 41 43 45 5f 53 49 5a 45  QLITE_TRACE_SIZE
1fa30 5f 4c 49 4d 49 54 5d 20 63 6f 6d 70 69 6c 65 2d  _LIMIT] compile-
1fa40 74 69 6d 65 20 6f 70 74 69 6f 6e 20 63 61 6e 20  time option can 
1fa50 62 65 20 75 73 65 64 20 74 6f 20 6c 69 6d 69 74  be used to limit
1fa60 0a 2a 2a 20 74 68 65 20 6c 65 6e 67 74 68 20 6f  .** the length o
1fa70 66 20 5b 62 6f 75 6e 64 20 70 61 72 61 6d 65 74  f [bound paramet
1fa80 65 72 5d 20 65 78 70 61 6e 73 69 6f 6e 20 69 6e  er] expansion in
1fa90 20 74 68 65 20 6f 75 74 70 75 74 20 6f 66 20 73   the output of s
1faa0 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 2e 0a  qlite3_trace()..
1fab0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62  **.** ^The callb
1fac0 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67  ack function reg
1fad0 69 73 74 65 72 65 64 20 62 79 20 73 71 6c 69 74  istered by sqlit
1fae0 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 69 73 20  e3_profile() is 
1faf0 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73 20 65 61  invoked.** as ea
1fb00 63 68 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ch SQL statement
1fb10 20 66 69 6e 69 73 68 65 73 2e 20 20 5e 54 68 65   finishes.  ^The
1fb20 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63   profile callbac
1fb30 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74 68  k contains.** th
1fb40 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65  e original state
1fb50 6d 65 6e 74 20 74 65 78 74 20 61 6e 64 20 61 6e  ment text and an
1fb60 20 65 73 74 69 6d 61 74 65 20 6f 66 20 77 61 6c   estimate of wal
1fb70 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a 20  l-clock time.** 
1fb80 6f 66 20 68 6f 77 20 6c 6f 6e 67 20 74 68 61 74  of how long that
1fb90 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b 20   statement took 
1fba0 74 6f 20 72 75 6e 2e 20 20 5e 54 68 65 20 70 72  to run.  ^The pr
1fbb0 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 0a 2a  ofile callback.*
1fbc0 2a 20 74 69 6d 65 20 69 73 20 69 6e 20 75 6e 69  * time is in uni
1fbd0 74 73 20 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e 64  ts of nanosecond
1fbe0 73 2c 20 68 6f 77 65 76 65 72 20 74 68 65 20 63  s, however the c
1fbf0 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74  urrent implement
1fc00 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6f 6e 6c 79  ation.** is only
1fc10 20 63 61 70 61 62 6c 65 20 6f 66 20 6d 69 6c 6c   capable of mill
1fc20 69 73 65 63 6f 6e 64 20 72 65 73 6f 6c 75 74 69  isecond resoluti
1fc30 6f 6e 20 73 6f 20 74 68 65 20 73 69 78 20 6c 65  on so the six le
1fc40 61 73 74 20 73 69 67 6e 69 66 69 63 61 6e 74 0a  ast significant.
1fc50 2a 2a 20 64 69 67 69 74 73 20 69 6e 20 74 68 65  ** digits in the
1fc60 20 74 69 6d 65 20 61 72 65 20 6d 65 61 6e 69 6e   time are meanin
1fc70 67 6c 65 73 73 2e 20 20 46 75 74 75 72 65 20 76  gless.  Future v
1fc80 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
1fc90 65 0a 2a 2a 20 6d 69 67 68 74 20 70 72 6f 76 69  e.** might provi
1fca0 64 65 20 67 72 65 61 74 65 72 20 72 65 73 6f 6c  de greater resol
1fcb0 75 74 69 6f 6e 20 6f 6e 20 74 68 65 20 70 72 6f  ution on the pro
1fcc0 66 69 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20  filer callback. 
1fcd0 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   The.** sqlite3_
1fce0 70 72 6f 66 69 6c 65 28 29 20 66 75 6e 63 74 69  profile() functi
1fcf0 6f 6e 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64  on is considered
1fd00 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e   experimental an
1fd10 64 20 69 73 0a 2a 2a 20 73 75 62 6a 65 63 74 20  d is.** subject 
1fd20 74 6f 20 63 68 61 6e 67 65 20 69 6e 20 66 75 74  to change in fut
1fd30 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ure versions of 
1fd40 53 51 4c 69 74 65 2e 0a 2a 2f 0a 76 6f 69 64 20  SQLite..*/.void 
1fd50 2a 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 73  *sqlite3_trace(s
1fd60 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a 78  qlite3*, void(*x
1fd70 54 72 61 63 65 29 28 76 6f 69 64 2a 2c 63 6f 6e  Trace)(void*,con
1fd80 73 74 20 63 68 61 72 2a 29 2c 20 76 6f 69 64 2a  st char*), void*
1fd90 29 3b 0a 53 51 4c 49 54 45 5f 45 58 50 45 52 49  );.SQLITE_EXPERI
1fda0 4d 45 4e 54 41 4c 20 76 6f 69 64 20 2a 73 71 6c  MENTAL void *sql
1fdb0 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 73 71 6c  ite3_profile(sql
1fdc0 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a  ite3*,.   void(*
1fdd0 78 50 72 6f 66 69 6c 65 29 28 76 6f 69 64 2a 2c  xProfile)(void*,
1fde0 63 6f 6e 73 74 20 63 68 61 72 2a 2c 73 71 6c 69  const char*,sqli
1fdf0 74 65 33 5f 75 69 6e 74 36 34 29 2c 20 76 6f 69  te3_uint64), voi
1fe00 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d*);../*.** CAPI
1fe10 33 52 45 46 3a 20 51 75 65 72 79 20 50 72 6f 67  3REF: Query Prog
1fe20 72 65 73 73 20 43 61 6c 6c 62 61 63 6b 73 0a 2a  ress Callbacks.*
1fe30 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
1fe40 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c  3_progress_handl
1fe50 65 72 28 44 2c 4e 2c 58 2c 50 29 20 69 6e 74 65  er(D,N,X,P) inte
1fe60 72 66 61 63 65 20 63 61 75 73 65 73 20 74 68 65  rface causes the
1fe70 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e   callback.** fun
1fe80 63 74 69 6f 6e 20 58 20 74 6f 20 62 65 20 69 6e  ction X to be in
1fe90 76 6f 6b 65 64 20 70 65 72 69 6f 64 69 63 61 6c  voked periodical
1fea0 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67 20 72  ly during long r
1feb0 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f 0a  unning calls to.
1fec0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  ** [sqlite3_exec
1fed0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74  ()], [sqlite3_st
1fee0 65 70 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  ep()] and [sqlit
1fef0 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20  e3_get_table()] 
1ff00 66 6f 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  for.** database 
1ff10 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 20 41  connection D.  A
1ff20 6e 20 65 78 61 6d 70 6c 65 20 75 73 65 20 66 6f  n example use fo
1ff30 72 20 74 68 69 73 0a 2a 2a 20 69 6e 74 65 72 66  r this.** interf
1ff40 61 63 65 20 69 73 20 74 6f 20 6b 65 65 70 20 61  ace is to keep a
1ff50 20 47 55 49 20 75 70 64 61 74 65 64 20 64 75 72   GUI updated dur
1ff60 69 6e 67 20 61 20 6c 61 72 67 65 20 71 75 65 72  ing a large quer
1ff70 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 61  y..**.** ^The pa
1ff80 72 61 6d 65 74 65 72 20 50 20 69 73 20 70 61 73  rameter P is pas
1ff90 73 65 64 20 74 68 72 6f 75 67 68 20 61 73 20 74  sed through as t
1ffa0 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65  he only paramete
1ffb0 72 20 74 6f 20 74 68 65 20 0a 2a 2a 20 63 61 6c  r to the .** cal
1ffc0 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 58  lback function X
1ffd0 2e 20 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65  .  ^The paramete
1ffe0 72 20 4e 20 69 73 20 74 68 65 20 61 70 70 72 6f  r N is the appro
1fff0 78 69 6d 61 74 65 20 6e 75 6d 62 65 72 20 6f 66  ximate number of
20000 20 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 6d 61   .** [virtual ma
20010 63 68 69 6e 65 20 69 6e 73 74 72 75 63 74 69 6f  chine instructio
20020 6e 73 5d 20 74 68 61 74 20 61 72 65 20 65 76 61  ns] that are eva
20030 6c 75 61 74 65 64 20 62 65 74 77 65 65 6e 20 73  luated between s
20040 75 63 63 65 73 73 69 76 65 0a 2a 2a 20 69 6e 76  uccessive.** inv
20050 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  ocations of the 
20060 63 61 6c 6c 62 61 63 6b 20 58 2e 20 20 5e 49 66  callback X.  ^If
20070 20 4e 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20   N is less than 
20080 6f 6e 65 20 74 68 65 6e 20 74 68 65 20 70 72 6f  one then the pro
20090 67 72 65 73 73 0a 2a 2a 20 68 61 6e 64 6c 65 72  gress.** handler
200a0 20 69 73 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a   is disabled..**
200b0 0a 2a 2a 20 5e 4f 6e 6c 79 20 61 20 73 69 6e 67  .** ^Only a sing
200c0 6c 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64  le progress hand
200d0 6c 65 72 20 6d 61 79 20 62 65 20 64 65 66 69 6e  ler may be defin
200e0 65 64 20 61 74 20 6f 6e 65 20 74 69 6d 65 20 70  ed at one time p
200f0 65 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  er.** [database 
20100 63 6f 6e 6e 65 63 74 69 6f 6e 5d 3b 20 73 65 74  connection]; set
20110 74 69 6e 67 20 61 20 6e 65 77 20 70 72 6f 67 72  ting a new progr
20120 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61 6e 63  ess handler canc
20130 65 6c 73 20 74 68 65 0a 2a 2a 20 6f 6c 64 20 6f  els the.** old o
20140 6e 65 2e 20 20 5e 53 65 74 74 69 6e 67 20 70 61  ne.  ^Setting pa
20150 72 61 6d 65 74 65 72 20 58 20 74 6f 20 4e 55 4c  rameter X to NUL
20160 4c 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 70  L disables the p
20170 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e  rogress handler.
20180 0a 2a 2a 20 5e 54 68 65 20 70 72 6f 67 72 65 73  .** ^The progres
20190 73 20 68 61 6e 64 6c 65 72 20 69 73 20 61 6c 73  s handler is als
201a0 6f 20 64 69 73 61 62 6c 65 64 20 62 79 20 73 65  o disabled by se
201b0 74 74 69 6e 67 20 4e 20 74 6f 20 61 20 76 61 6c  tting N to a val
201c0 75 65 20 6c 65 73 73 0a 2a 2a 20 74 68 61 6e 20  ue less.** than 
201d0 31 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  1..**.** ^If the
201e0 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61   progress callba
201f0 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a  ck returns non-z
20200 65 72 6f 2c 20 74 68 65 20 6f 70 65 72 61 74 69  ero, the operati
20210 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74 65 72 72 75  on is.** interru
20220 70 74 65 64 2e 20 20 54 68 69 73 20 66 65 61 74  pted.  This feat
20230 75 72 65 20 63 61 6e 20 62 65 20 75 73 65 64 20  ure can be used 
20240 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 0a 2a  to implement a.*
20250 2a 20 22 43 61 6e 63 65 6c 22 20 62 75 74 74 6f  * "Cancel" butto
20260 6e 20 6f 6e 20 61 20 47 55 49 20 70 72 6f 67 72  n on a GUI progr
20270 65 73 73 20 64 69 61 6c 6f 67 20 62 6f 78 2e 0a  ess dialog box..
20280 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 6f 67 72 65  **.** The progre
20290 73 73 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62  ss handler callb
202a0 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20  ack must not do 
202b0 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 69  anything that wi
202c0 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65  ll modify.** the
202d0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
202e0 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65  tion that invoke
202f0 64 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 68  d the progress h
20300 61 6e 64 6c 65 72 2e 0a 2a 2a 20 4e 6f 74 65 20  andler..** Note 
20310 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72  that [sqlite3_pr
20320 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20  epare_v2()] and 
20330 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
20340 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65   both modify the
20350 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  ir.** database c
20360 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74  onnections for t
20370 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d  he meaning of "m
20380 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 70  odify" in this p
20390 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2f 0a  aragraph..**.*/.
203a0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 70 72 6f  void sqlite3_pro
203b0 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 73 71  gress_handler(sq
203c0 6c 69 74 65 33 2a 2c 20 69 6e 74 2c 20 69 6e 74  lite3*, int, int
203d0 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64  (*)(void*), void
203e0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
203f0 52 45 46 3a 20 4f 70 65 6e 69 6e 67 20 41 20 4e  REF: Opening A N
20400 65 77 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e  ew Database Conn
20410 65 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ection.**.** ^Th
20420 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 70 65  ese routines ope
20430 6e 20 61 6e 20 53 51 4c 69 74 65 20 64 61 74 61  n an SQLite data
20440 62 61 73 65 20 66 69 6c 65 20 61 73 20 73 70 65  base file as spe
20450 63 69 66 69 65 64 20 62 79 20 74 68 65 20 0a 2a  cified by the .*
20460 2a 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d  * filename argum
20470 65 6e 74 2e 20 5e 54 68 65 20 66 69 6c 65 6e 61  ent. ^The filena
20480 6d 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 69  me argument is i
20490 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55 54  nterpreted as UT
204a0 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74  F-8 for.** sqlit
204b0 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71  e3_open() and sq
204c0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
204d0 61 6e 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e  and as UTF-16 in
204e0 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65   the native byte
204f0 0a 2a 2a 20 6f 72 64 65 72 20 66 6f 72 20 73 71  .** order for sq
20500 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 20  lite3_open16(). 
20510 5e 28 41 20 5b 64 61 74 61 62 61 73 65 20 63 6f  ^(A [database co
20520 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65  nnection] handle
20530 20 69 73 20 75 73 75 61 6c 6c 79 0a 2a 2a 20 72   is usually.** r
20540 65 74 75 72 6e 65 64 20 69 6e 20 2a 70 70 44 62  eturned in *ppDb
20550 2c 20 65 76 65 6e 20 69 66 20 61 6e 20 65 72 72  , even if an err
20560 6f 72 20 6f 63 63 75 72 73 2e 20 20 54 68 65 20  or occurs.  The 
20570 6f 6e 6c 79 20 65 78 63 65 70 74 69 6f 6e 20 69  only exception i
20580 73 20 74 68 61 74 0a 2a 2a 20 69 66 20 53 51 4c  s that.** if SQL
20590 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f  ite is unable to
205a0 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79   allocate memory
205b0 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 5b 73 71   to hold the [sq
205c0 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a  lite3] object,.*
205d0 2a 20 61 20 4e 55 4c 4c 20 77 69 6c 6c 20 62 65  * a NULL will be
205e0 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70   written into *p
205f0 70 44 62 20 69 6e 73 74 65 61 64 20 6f 66 20 61  pDb instead of a
20600 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
20610 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a  [sqlite3].** obj
20620 65 63 74 2e 29 5e 20 5e 28 49 66 20 74 68 65 20  ect.)^ ^(If the 
20630 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
20640 65 64 20 28 61 6e 64 2f 6f 72 20 63 72 65 61 74  ed (and/or creat
20650 65 64 29 20 73 75 63 63 65 73 73 66 75 6c 6c 79  ed) successfully
20660 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54  , then.** [SQLIT
20670 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65  E_OK] is returne
20680 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 61 6e  d.  Otherwise an
20690 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73   [error code] is
206a0 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 5e 54 68   returned.)^ ^Th
206b0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72  e.** [sqlite3_er
206c0 72 6d 73 67 28 29 5d 20 6f 72 20 5b 73 71 6c 69  rmsg()] or [sqli
206d0 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 20  te3_errmsg16()] 
206e0 72 6f 75 74 69 6e 65 73 20 63 61 6e 20 62 65 20  routines can be 
206f0 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 0a 2a  used to obtain.*
20700 2a 20 61 6e 20 45 6e 67 6c 69 73 68 20 6c 61 6e  * an English lan
20710 67 75 61 67 65 20 64 65 73 63 72 69 70 74 69 6f  guage descriptio
20720 6e 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20 66  n of the error f
20730 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 75  ollowing a failu
20740 72 65 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20  re of any.** of 
20750 74 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  the sqlite3_open
20760 28 29 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a  () routines..**.
20770 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20  ** ^The default 
20780 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20 74 68 65  encoding for the
20790 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62   database will b
207a0 65 20 55 54 46 2d 38 20 69 66 0a 2a 2a 20 73 71  e UTF-8 if.** sq
207b0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20  lite3_open() or 
207c0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
207d0 29 20 69 73 20 63 61 6c 6c 65 64 20 61 6e 64 0a  ) is called and.
207e0 2a 2a 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65  ** UTF-16 in the
207f0 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
20800 65 72 20 69 66 20 73 71 6c 69 74 65 33 5f 6f 70  er if sqlite3_op
20810 65 6e 31 36 28 29 20 69 73 20 75 73 65 64 2e 0a  en16() is used..
20820 2a 2a 0a 2a 2a 20 57 68 65 74 68 65 72 20 6f 72  **.** Whether or
20830 20 6e 6f 74 20 61 6e 20 65 72 72 6f 72 20 6f 63   not an error oc
20840 63 75 72 73 20 77 68 65 6e 20 69 74 20 69 73 20  curs when it is 
20850 6f 70 65 6e 65 64 2c 20 72 65 73 6f 75 72 63 65  opened, resource
20860 73 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20  s.** associated 
20870 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61  with the [databa
20880 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68  se connection] h
20890 61 6e 64 6c 65 20 73 68 6f 75 6c 64 20 62 65 20  andle should be 
208a0 72 65 6c 65 61 73 65 64 20 62 79 0a 2a 2a 20 70  released by.** p
208b0 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71  assing it to [sq
208c0 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 77  lite3_close()] w
208d0 68 65 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f 6e  hen it is no lon
208e0 67 65 72 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a  ger required..**
208f0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
20900 6f 70 65 6e 5f 76 32 28 29 20 69 6e 74 65 72 66  open_v2() interf
20910 61 63 65 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73  ace works like s
20920 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a  qlite3_open().**
20930 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20   except that it 
20940 61 63 63 65 70 74 73 20 74 77 6f 20 61 64 64 69  accepts two addi
20950 74 69 6f 6e 61 6c 20 70 61 72 61 6d 65 74 65 72  tional parameter
20960 73 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  s for additional
20970 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72   control.** over
20980 20 74 68 65 20 6e 65 77 20 64 61 74 61 62 61 73   the new databas
20990 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e  e connection.  ^
209a0 28 54 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d  (The flags param
209b0 65 74 65 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  eter to.** sqlit
209c0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 63 61 6e  e3_open_v2() can
209d0 20 74 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20   take one of.** 
209e0 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68  the following th
209f0 72 65 65 20 76 61 6c 75 65 73 2c 20 6f 70 74 69  ree values, opti
20a00 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20  onally combined 
20a10 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51  with the .** [SQ
20a20 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45  LITE_OPEN_NOMUTE
20a30 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  X], [SQLITE_OPEN
20a40 5f 46 55 4c 4c 4d 55 54 45 58 5d 2c 20 5b 53 51  _FULLMUTEX], [SQ
20a50 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44  LITE_OPEN_SHARED
20a60 43 41 43 48 45 5d 2c 0a 2a 2a 20 5b 53 51 4c 49  CACHE],.** [SQLI
20a70 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43  TE_OPEN_PRIVATEC
20a80 41 43 48 45 5d 2c 20 61 6e 64 2f 6f 72 20 5b 53  ACHE], and/or [S
20a90 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20  QLITE_OPEN_URI] 
20aa0 66 6c 61 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c  flags:)^.**.** <
20ab0 64 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51  dl>.** ^(<dt>[SQ
20ac0 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e  LITE_OPEN_READON
20ad0 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  LY]</dt>.** <dd>
20ae0 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  The database is 
20af0 6f 70 65 6e 65 64 20 69 6e 20 72 65 61 64 2d 6f  opened in read-o
20b00 6e 6c 79 20 6d 6f 64 65 2e 20 20 49 66 20 74 68  nly mode.  If th
20b10 65 20 64 61 74 61 62 61 73 65 20 64 6f 65 73 20  e database does 
20b20 6e 6f 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 65  not.** already e
20b30 78 69 73 74 2c 20 61 6e 20 65 72 72 6f 72 20 69  xist, an error i
20b40 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e  s returned.</dd>
20b50 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b  )^.**.** ^(<dt>[
20b60 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
20b70 57 52 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c  WRITE]</dt>.** <
20b80 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20  dd>The database 
20b90 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65  is opened for re
20ba0 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e  ading and writin
20bb0 67 20 69 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f  g if possible, o
20bc0 72 20 72 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c  r reading.** onl
20bd0 79 20 69 66 20 74 68 65 20 66 69 6c 65 20 69 73  y if the file is
20be0 20 77 72 69 74 65 20 70 72 6f 74 65 63 74 65 64   write protected
20bf0 20 62 79 20 74 68 65 20 6f 70 65 72 61 74 69 6e   by the operatin
20c00 67 20 73 79 73 74 65 6d 2e 20 20 49 6e 20 65 69  g system.  In ei
20c10 74 68 65 72 0a 2a 2a 20 63 61 73 65 20 74 68 65  ther.** case the
20c20 20 64 61 74 61 62 61 73 65 20 6d 75 73 74 20 61   database must a
20c30 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20 6f 74  lready exist, ot
20c40 68 65 72 77 69 73 65 20 61 6e 20 65 72 72 6f 72  herwise an error
20c50 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64   is returned.</d
20c60 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74  d>)^.**.** ^(<dt
20c70 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45  >[SQLITE_OPEN_RE
20c80 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49  ADWRITE] | [SQLI
20c90 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 3c  TE_OPEN_CREATE]<
20ca0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
20cb0 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
20cc0 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61  ed for reading a
20cd0 6e 64 20 77 72 69 74 69 6e 67 2c 20 61 6e 64 20  nd writing, and 
20ce0 69 73 20 63 72 65 61 74 65 64 20 69 66 0a 2a 2a  is created if.**
20cf0 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 61 6c 72   it does not alr
20d00 65 61 64 79 20 65 78 69 73 74 2e 20 54 68 69 73  eady exist. This
20d10 20 69 73 20 74 68 65 20 62 65 68 61 76 69 6f 72   is the behavior
20d20 20 74 68 61 74 20 69 73 20 61 6c 77 61 79 73 20   that is always 
20d30 75 73 65 64 20 66 6f 72 0a 2a 2a 20 73 71 6c 69  used for.** sqli
20d40 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73  te3_open() and s
20d50 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e  qlite3_open16().
20d60 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e  </dd>)^.** </dl>
20d70 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 33 72  .**.** If the 3r
20d80 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
20d90 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
20da0 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74   is not one of t
20db0 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74 69 6f  he.** combinatio
20dc0 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 6f  ns shown above o
20dd0 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e  ptionally combin
20de0 65 64 20 77 69 74 68 20 6f 74 68 65 72 0a 2a 2a  ed with other.**
20df0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45   [SQLITE_OPEN_RE
20e00 41 44 4f 4e 4c 59 20 7c 20 53 51 4c 49 54 45 5f  ADONLY | SQLITE_
20e10 4f 50 45 4e 5f 2a 20 62 69 74 73 5d 0a 2a 2a 20  OPEN_* bits].** 
20e20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
20e30 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  r is undefined..
20e40 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b 53  **.** ^If the [S
20e50 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54  QLITE_OPEN_NOMUT
20e60 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74 2c  EX] flag is set,
20e70 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   then the databa
20e80 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
20e90 20 6f 70 65 6e 73 20 69 6e 20 74 68 65 20 6d 75   opens in the mu
20ea0 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65  lti-thread [thre
20eb0 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 73 20 6c  ading mode] as l
20ec0 6f 6e 67 20 61 73 20 74 68 65 20 73 69 6e 67 6c  ong as the singl
20ed0 65 2d 74 68 72 65 61 64 0a 2a 2a 20 6d 6f 64 65  e-thread.** mode
20ee0 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 73 65   has not been se
20ef0 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  t at compile-tim
20f00 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e  e or start-time.
20f10 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51    ^If the.** [SQ
20f20 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55  LITE_OPEN_FULLMU
20f30 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74  TEX] flag is set
20f40 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   then the databa
20f50 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70  se connection op
20f60 65 6e 73 0a 2a 2a 20 69 6e 20 74 68 65 20 73 65  ens.** in the se
20f70 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64  rialized [thread
20f80 69 6e 67 20 6d 6f 64 65 5d 20 75 6e 6c 65 73 73  ing mode] unless
20f90 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 77   single-thread w
20fa0 61 73 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79  as.** previously
20fb0 20 73 65 6c 65 63 74 65 64 20 61 74 20 63 6f 6d   selected at com
20fc0 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61  pile-time or sta
20fd0 72 74 2d 74 69 6d 65 2e 0a 2a 2a 20 5e 54 68 65  rt-time..** ^The
20fe0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48   [SQLITE_OPEN_SH
20ff0 41 52 45 44 43 41 43 48 45 5d 20 66 6c 61 67 20  AREDCACHE] flag 
21000 63 61 75 73 65 73 20 74 68 65 20 64 61 74 61 62  causes the datab
21010 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  ase connection t
21020 6f 20 62 65 0a 2a 2a 20 65 6c 69 67 69 62 6c 65  o be.** eligible
21030 20 74 6f 20 75 73 65 20 5b 73 68 61 72 65 64 20   to use [shared 
21040 63 61 63 68 65 20 6d 6f 64 65 5d 2c 20 72 65 67  cache mode], reg
21050 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68  ardless of wheth
21060 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65 64  er or not shared
21070 0a 2a 2a 20 63 61 63 68 65 20 69 73 20 65 6e 61  .** cache is ena
21080 62 6c 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  bled using [sqli
21090 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65  te3_enable_share
210a0 64 5f 63 61 63 68 65 28 29 5d 2e 20 20 5e 54 68  d_cache()].  ^Th
210b0 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45  e.** [SQLITE_OPE
210c0 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d 20  N_PRIVATECACHE] 
210d0 66 6c 61 67 20 63 61 75 73 65 73 20 74 68 65 20  flag causes the 
210e0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
210f0 69 6f 6e 20 74 6f 20 6e 6f 74 0a 2a 2a 20 70 61  ion to not.** pa
21100 72 74 69 63 69 70 61 74 65 20 69 6e 20 5b 73 68  rticipate in [sh
21110 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d  ared cache mode]
21120 20 65 76 65 6e 20 69 66 20 69 74 20 69 73 20 65   even if it is e
21130 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  nabled..**.** ^T
21140 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
21150 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f  ter to sqlite3_o
21160 70 65 6e 5f 76 32 28 29 20 69 73 20 74 68 65 20  pen_v2() is the 
21170 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b  name of the.** [
21180 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a  sqlite3_vfs] obj
21190 65 63 74 20 74 68 61 74 20 64 65 66 69 6e 65 73  ect that defines
211a0 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73   the operating s
211b0 79 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20  ystem interface 
211c0 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 65 77 20  that.** the new 
211d0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
211e0 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 2e 20  ion should use. 
211f0 20 5e 49 66 20 74 68 65 20 66 6f 75 72 74 68 20   ^If the fourth 
21200 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20  parameter is.** 
21210 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74  a NULL pointer t
21220 68 65 6e 20 74 68 65 20 64 65 66 61 75 6c 74 20  hen the default 
21230 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
21240 6a 65 63 74 20 69 73 20 75 73 65 64 2e 0a 2a 2a  ject is used..**
21250 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 6c 65  .** ^If the file
21260 6e 61 6d 65 20 69 73 20 22 3a 6d 65 6d 6f 72 79  name is ":memory
21270 3a 22 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61  :", then a priva
21280 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 20 69 6e  te, temporary in
21290 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65  -memory database
212a0 0a 2a 2a 20 69 73 20 63 72 65 61 74 65 64 20 66  .** is created f
212b0 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f  or the connectio
212c0 6e 2e 20 20 5e 54 68 69 73 20 69 6e 2d 6d 65 6d  n.  ^This in-mem
212d0 6f 72 79 20 64 61 74 61 62 61 73 65 20 77 69 6c  ory database wil
212e0 6c 20 76 61 6e 69 73 68 20 77 68 65 6e 0a 2a 2a  l vanish when.**
212f0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
21300 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73  nnection is clos
21310 65 64 2e 20 20 46 75 74 75 72 65 20 76 65 72 73  ed.  Future vers
21320 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d  ions of SQLite m
21330 69 67 68 74 0a 2a 2a 20 6d 61 6b 65 20 75 73 65  ight.** make use
21340 20 6f 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 73   of additional s
21350 70 65 63 69 61 6c 20 66 69 6c 65 6e 61 6d 65 73  pecial filenames
21360 20 74 68 61 74 20 62 65 67 69 6e 20 77 69 74 68   that begin with
21370 20 74 68 65 20 22 3a 22 20 63 68 61 72 61 63 74   the ":" charact
21380 65 72 2e 0a 2a 2a 20 49 74 20 69 73 20 72 65 63  er..** It is rec
21390 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 77 68  ommended that wh
213a0 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 66 69  en a database fi
213b0 6c 65 6e 61 6d 65 20 61 63 74 75 61 6c 6c 79 20  lename actually 
213c0 64 6f 65 73 20 62 65 67 69 6e 20 77 69 74 68 0a  does begin with.
213d0 2a 2a 20 61 20 22 3a 22 20 63 68 61 72 61 63 74  ** a ":" charact
213e0 65 72 20 79 6f 75 20 73 68 6f 75 6c 64 20 70 72  er you should pr
213f0 65 66 69 78 20 74 68 65 20 66 69 6c 65 6e 61 6d  efix the filenam
21400 65 20 77 69 74 68 20 61 20 70 61 74 68 6e 61 6d  e with a pathnam
21410 65 20 73 75 63 68 20 61 73 0a 2a 2a 20 22 2e 2f  e such as.** "./
21420 22 20 74 6f 20 61 76 6f 69 64 20 61 6d 62 69 67  " to avoid ambig
21430 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  uity..**.** ^If 
21440 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20  the filename is 
21450 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c  an empty string,
21460 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c   then a private,
21470 20 74 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e   temporary.** on
21480 2d 64 69 73 6b 20 64 61 74 61 62 61 73 65 20 77  -disk database w
21490 69 6c 6c 20 62 65 20 63 72 65 61 74 65 64 2e 20  ill be created. 
214a0 20 5e 54 68 69 73 20 70 72 69 76 61 74 65 20 64   ^This private d
214b0 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 0a  atabase will be.
214c0 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ** automatically
214d0 20 64 65 6c 65 74 65 64 20 61 73 20 73 6f 6f 6e   deleted as soon
214e0 20 61 73 20 74 68 65 20 64 61 74 61 62 61 73 65   as the database
214f0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63   connection is c
21500 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55  losed..**.** [[U
21510 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 69 6e 20  RI filenames in 
21520 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 5d  sqlite3_open()]]
21530 20 3c 68 33 3e 55 52 49 20 46 69 6c 65 6e 61 6d   <h3>URI Filenam
21540 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 5e 49  es</h3>.**.** ^I
21550 66 20 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 5d  f [URI filename]
21560 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20   interpretation 
21570 69 73 20 65 6e 61 62 6c 65 64 2c 20 61 6e 64 20  is enabled, and 
21580 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67  the filename arg
21590 75 6d 65 6e 74 0a 2a 2a 20 62 65 67 69 6e 73 20  ument.** begins 
215a0 77 69 74 68 20 22 66 69 6c 65 3a 22 2c 20 74 68  with "file:", th
215b0 65 6e 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  en the filename 
215c0 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  is interpreted a
215d0 73 20 61 20 55 52 49 2e 20 5e 55 52 49 0a 2a 2a  s a URI. ^URI.**
215e0 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70   filename interp
215f0 72 65 74 61 74 69 6f 6e 20 69 73 20 65 6e 61 62  retation is enab
21600 6c 65 64 20 69 66 20 74 68 65 20 5b 53 51 4c 49  led if the [SQLI
21610 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61  TE_OPEN_URI] fla
21620 67 20 69 73 0a 2a 2a 20 73 65 74 20 69 6e 20 74  g is.** set in t
21630 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65  he fourth argume
21640 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70  nt to sqlite3_op
21650 65 6e 5f 76 32 28 29 2c 20 6f 72 20 69 66 20 69  en_v2(), or if i
21660 74 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 65 6e  t has.** been en
21670 61 62 6c 65 64 20 67 6c 6f 62 61 6c 6c 79 20 75  abled globally u
21680 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45  sing the [SQLITE
21690 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 20 6f 70 74  _CONFIG_URI] opt
216a0 69 6f 6e 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  ion with the.** 
216b0 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
216c0 29 5d 20 6d 65 74 68 6f 64 20 6f 72 20 62 79 20  )] method or by 
216d0 74 68 65 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f  the [SQLITE_USE_
216e0 55 52 49 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  URI] compile-tim
216f0 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 41 73 20  e option..** As 
21700 6f 66 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  of SQLite versio
21710 6e 20 33 2e 37 2e 37 2c 20 55 52 49 20 66 69 6c  n 3.7.7, URI fil
21720 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 65 74 61  ename interpreta
21730 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 6f  tion is turned o
21740 66 66 0a 2a 2a 20 62 79 20 64 65 66 61 75 6c 74  ff.** by default
21750 2c 20 62 75 74 20 66 75 74 75 72 65 20 72 65 6c  , but future rel
21760 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 20  eases of SQLite 
21770 6d 69 67 68 74 20 65 6e 61 62 6c 65 20 55 52 49  might enable URI
21780 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 69 6e 74   filename.** int
21790 65 72 70 72 65 74 61 74 69 6f 6e 20 62 79 20 64  erpretation by d
217a0 65 66 61 75 6c 74 2e 20 20 53 65 65 20 22 5b 55  efault.  See "[U
217b0 52 49 20 66 69 6c 65 6e 61 6d 65 73 5d 22 20 66  RI filenames]" f
217c0 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a  or additional.**
217d0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a   information..**
217e0 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d 65  .** URI filename
217f0 73 20 61 72 65 20 70 61 72 73 65 64 20 61 63 63  s are parsed acc
21800 6f 72 64 69 6e 67 20 74 6f 20 52 46 43 20 33 39  ording to RFC 39
21810 38 36 2e 20 5e 49 66 20 74 68 65 20 55 52 49 20  86. ^If the URI 
21820 63 6f 6e 74 61 69 6e 73 20 61 6e 0a 2a 2a 20 61  contains an.** a
21830 75 74 68 6f 72 69 74 79 2c 20 74 68 65 6e 20 69  uthority, then i
21840 74 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72  t must be either
21850 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67   an empty string
21860 20 6f 72 20 74 68 65 20 73 74 72 69 6e 67 20 0a   or the string .
21870 2a 2a 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2e 20  ** "localhost". 
21880 5e 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 74  ^If the authorit
21890 79 20 69 73 20 6e 6f 74 20 61 6e 20 65 6d 70 74  y is not an empt
218a0 79 20 73 74 72 69 6e 67 20 6f 72 20 22 6c 6f 63  y string or "loc
218b0 61 6c 68 6f 73 74 22 2c 20 61 6e 20 0a 2a 2a 20  alhost", an .** 
218c0 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65  error is returne
218d0 64 20 74 6f 20 74 68 65 20 63 61 6c 6c 65 72 2e  d to the caller.
218e0 20 5e 54 68 65 20 66 72 61 67 6d 65 6e 74 20 63   ^The fragment c
218f0 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52  omponent of a UR
21900 49 2c 20 69 66 20 0a 2a 2a 20 70 72 65 73 65 6e  I, if .** presen
21910 74 2c 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a  t, is ignored..*
21920 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65  *.** ^SQLite use
21930 73 20 74 68 65 20 70 61 74 68 20 63 6f 6d 70 6f  s the path compo
21940 6e 65 6e 74 20 6f 66 20 74 68 65 20 55 52 49 20  nent of the URI 
21950 61 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  as the name of t
21960 68 65 20 64 69 73 6b 20 66 69 6c 65 0a 2a 2a 20  he disk file.** 
21970 77 68 69 63 68 20 63 6f 6e 74 61 69 6e 73 20 74  which contains t
21980 68 65 20 64 61 74 61 62 61 73 65 2e 20 5e 49 66  he database. ^If
21990 20 74 68 65 20 70 61 74 68 20 62 65 67 69 6e 73   the path begins
219a0 20 77 69 74 68 20 61 20 27 2f 27 20 63 68 61 72   with a '/' char
219b0 61 63 74 65 72 2c 20 0a 2a 2a 20 74 68 65 6e 20  acter, .** then 
219c0 69 74 20 69 73 20 69 6e 74 65 72 70 72 65 74 65  it is interprete
219d0 64 20 61 73 20 61 6e 20 61 62 73 6f 6c 75 74 65  d as an absolute
219e0 20 70 61 74 68 2e 20 5e 49 66 20 74 68 65 20 70   path. ^If the p
219f0 61 74 68 20 64 6f 65 73 20 6e 6f 74 20 62 65 67  ath does not beg
21a00 69 6e 20 0a 2a 2a 20 77 69 74 68 20 61 20 27 2f  in .** with a '/
21a10 27 20 28 6d 65 61 6e 69 6e 67 20 74 68 61 74 20  ' (meaning that 
21a20 74 68 65 20 61 75 74 68 6f 72 69 74 79 20 73 65  the authority se
21a30 63 74 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64  ction is omitted
21a40 20 66 72 6f 6d 20 74 68 65 20 55 52 49 29 0a 2a   from the URI).*
21a50 2a 20 74 68 65 6e 20 74 68 65 20 70 61 74 68 20  * then the path 
21a60 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  is interpreted a
21a70 73 20 61 20 72 65 6c 61 74 69 76 65 20 70 61 74  s a relative pat
21a80 68 2e 20 0a 2a 2a 20 5e 4f 6e 20 77 69 6e 64 6f  h. .** ^On windo
21a90 77 73 2c 20 74 68 65 20 66 69 72 73 74 20 63 6f  ws, the first co
21aa0 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 6e 20 61 62  mponent of an ab
21ab0 73 6f 6c 75 74 65 20 70 61 74 68 20 0a 2a 2a 20  solute path .** 
21ac0 69 73 20 61 20 64 72 69 76 65 20 73 70 65 63 69  is a drive speci
21ad0 66 69 63 61 74 69 6f 6e 20 28 65 2e 67 2e 20 22  fication (e.g. "
21ae0 43 3a 22 29 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 63 6f  C:")..**.** [[co
21af0 72 65 20 55 52 49 20 71 75 65 72 79 20 70 61 72  re URI query par
21b00 61 6d 65 74 65 72 73 5d 5d 0a 2a 2a 20 54 68 65  ameters]].** The
21b10 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74   query component
21b20 20 6f 66 20 61 20 55 52 49 20 6d 61 79 20 63 6f   of a URI may co
21b30 6e 74 61 69 6e 20 70 61 72 61 6d 65 74 65 72 73  ntain parameters
21b40 20 74 68 61 74 20 61 72 65 20 69 6e 74 65 72 70   that are interp
21b50 72 65 74 65 64 0a 2a 2a 20 65 69 74 68 65 72 20  reted.** either 
21b60 62 79 20 53 51 4c 69 74 65 20 69 74 73 65 6c 66  by SQLite itself
21b70 2c 20 6f 72 20 62 79 20 61 20 5b 56 46 53 20 7c  , or by a [VFS |
21b80 20 63 75 73 74 6f 6d 20 56 46 53 20 69 6d 70 6c   custom VFS impl
21b90 65 6d 65 6e 74 61 74 69 6f 6e 5d 2e 0a 2a 2a 20  ementation]..** 
21ba0 53 51 4c 69 74 65 20 69 6e 74 65 72 70 72 65 74  SQLite interpret
21bb0 73 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  s the following 
21bc0 74 68 72 65 65 20 71 75 65 72 79 20 70 61 72 61  three query para
21bd0 6d 65 74 65 72 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75  meters:.**.** <u
21be0 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e  l>.**   <li> <b>
21bf0 76 66 73 3c 2f 62 3e 3a 20 5e 54 68 65 20 22 76  vfs</b>: ^The "v
21c00 66 73 22 20 70 61 72 61 6d 65 74 65 72 20 6d 61  fs" parameter ma
21c10 79 20 62 65 20 75 73 65 64 20 74 6f 20 73 70 65  y be used to spe
21c20 63 69 66 79 20 74 68 65 20 6e 61 6d 65 20 6f 66  cify the name of
21c30 0a 2a 2a 20 20 20 20 20 61 20 56 46 53 20 6f 62  .**     a VFS ob
21c40 6a 65 63 74 20 74 68 61 74 20 70 72 6f 76 69 64  ject that provid
21c50 65 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67  es the operating
21c60 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61 63   system interfac
21c70 65 20 74 68 61 74 20 73 68 6f 75 6c 64 0a 2a 2a  e that should.**
21c80 20 20 20 20 20 62 65 20 75 73 65 64 20 74 6f 20       be used to 
21c90 61 63 63 65 73 73 20 74 68 65 20 64 61 74 61 62  access the datab
21ca0 61 73 65 20 66 69 6c 65 20 6f 6e 20 64 69 73 6b  ase file on disk
21cb0 2e 20 5e 49 66 20 74 68 69 73 20 6f 70 74 69 6f  . ^If this optio
21cc0 6e 20 69 73 20 73 65 74 20 74 6f 0a 2a 2a 20 20  n is set to.**  
21cd0 20 20 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69     an empty stri
21ce0 6e 67 20 74 68 65 20 64 65 66 61 75 6c 74 20 56  ng the default V
21cf0 46 53 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65  FS object is use
21d00 64 2e 20 5e 53 70 65 63 69 66 79 69 6e 67 20 61  d. ^Specifying a
21d10 6e 20 75 6e 6b 6e 6f 77 6e 0a 2a 2a 20 20 20 20  n unknown.**    
21d20 20 56 46 53 20 69 73 20 61 6e 20 65 72 72 6f 72   VFS is an error
21d30 2e 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f 70  . ^If sqlite3_op
21d40 65 6e 5f 76 32 28 29 20 69 73 20 75 73 65 64 20  en_v2() is used 
21d50 61 6e 64 20 74 68 65 20 76 66 73 20 6f 70 74 69  and the vfs opti
21d60 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20 70 72 65  on is.**     pre
21d70 73 65 6e 74 2c 20 74 68 65 6e 20 74 68 65 20 56  sent, then the V
21d80 46 53 20 73 70 65 63 69 66 69 65 64 20 62 79 20  FS specified by 
21d90 74 68 65 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  the option takes
21da0 20 70 72 65 63 65 64 65 6e 63 65 20 6f 76 65 72   precedence over
21db0 0a 2a 2a 20 20 20 20 20 74 68 65 20 76 61 6c 75  .**     the valu
21dc0 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  e passed as the 
21dd0 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
21de0 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   to sqlite3_open
21df0 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c  _v2()..**.**   <
21e00 6c 69 3e 20 3c 62 3e 6d 6f 64 65 3c 2f 62 3e 3a  li> <b>mode</b>:
21e10 20 5e 28 54 68 65 20 6d 6f 64 65 20 70 61 72 61   ^(The mode para
21e20 6d 65 74 65 72 20 6d 61 79 20 62 65 20 73 65 74  meter may be set
21e30 20 74 6f 20 65 69 74 68 65 72 20 22 72 6f 22 2c   to either "ro",
21e40 20 22 72 77 22 2c 0a 2a 2a 20 20 20 20 20 22 72   "rw",.**     "r
21e50 77 63 22 2c 20 6f 72 20 22 6d 65 6d 6f 72 79 22  wc", or "memory"
21e60 2e 20 41 74 74 65 6d 70 74 69 6e 67 20 74 6f 20  . Attempting to 
21e70 73 65 74 20 69 74 20 74 6f 20 61 6e 79 20 6f 74  set it to any ot
21e80 68 65 72 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20  her value is.** 
21e90 20 20 20 20 61 6e 20 65 72 72 6f 72 29 5e 2e 20      an error)^. 
21ea0 0a 2a 2a 20 20 20 20 20 5e 49 66 20 22 72 6f 22  .**     ^If "ro"
21eb0 20 69 73 20 73 70 65 63 69 66 69 65 64 2c 20 74   is specified, t
21ec0 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
21ed0 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72   is opened for r
21ee0 65 61 64 2d 6f 6e 6c 79 20 0a 2a 2a 20 20 20 20  ead-only .**    
21ef0 20 61 63 63 65 73 73 2c 20 6a 75 73 74 20 61 73   access, just as
21f00 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   if the [SQLITE_
21f10 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 20 66  OPEN_READONLY] f
21f20 6c 61 67 20 68 61 64 20 62 65 65 6e 20 73 65 74  lag had been set
21f30 20 69 6e 20 74 68 65 20 0a 2a 2a 20 20 20 20 20   in the .**     
21f40 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74  third argument t
21f50 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  o sqlite3_open_v
21f60 32 28 29 2e 20 5e 49 66 20 74 68 65 20 6d 6f 64  2(). ^If the mod
21f70 65 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 20  e option is set 
21f80 74 6f 20 0a 2a 2a 20 20 20 20 20 22 72 77 22 2c  to .**     "rw",
21f90 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   then the databa
21fa0 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72  se is opened for
21fb0 20 72 65 61 64 2d 77 72 69 74 65 20 28 62 75 74   read-write (but
21fc0 20 6e 6f 74 20 63 72 65 61 74 65 29 20 0a 2a 2a   not create) .**
21fd0 20 20 20 20 20 61 63 63 65 73 73 2c 20 61 73 20       access, as 
21fe0 69 66 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  if SQLITE_OPEN_R
21ff0 45 41 44 57 52 49 54 45 20 28 62 75 74 20 6e 6f  EADWRITE (but no
22000 74 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52  t SQLITE_OPEN_CR
22010 45 41 54 45 29 20 68 61 64 20 0a 2a 2a 20 20 20  EATE) had .**   
22020 20 20 62 65 65 6e 20 73 65 74 2e 20 5e 56 61 6c    been set. ^Val
22030 75 65 20 22 72 77 63 22 20 69 73 20 65 71 75 69  ue "rwc" is equi
22040 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e  valent to settin
22050 67 20 62 6f 74 68 20 0a 2a 2a 20 20 20 20 20 53  g both .**     S
22060 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
22070 52 49 54 45 20 61 6e 64 20 53 51 4c 49 54 45 5f  RITE and SQLITE_
22080 4f 50 45 4e 5f 43 52 45 41 54 45 2e 20 20 5e 49  OPEN_CREATE.  ^I
22090 66 20 74 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f  f the mode optio
220a0 6e 20 69 73 0a 2a 2a 20 20 20 20 20 73 65 74 20  n is.**     set 
220b0 74 6f 20 22 6d 65 6d 6f 72 79 22 20 74 68 65 6e  to "memory" then
220c0 20 61 20 70 75 72 65 20 5b 69 6e 2d 6d 65 6d 6f   a pure [in-memo
220d0 72 79 20 64 61 74 61 62 61 73 65 5d 20 74 68 61  ry database] tha
220e0 74 20 6e 65 76 65 72 20 72 65 61 64 73 0a 2a 2a  t never reads.**
220f0 20 20 20 20 20 6f 72 20 77 72 69 74 65 73 20 66       or writes f
22100 72 6f 6d 20 64 69 73 6b 20 69 73 20 75 73 65 64  rom disk is used
22110 2e 20 5e 49 74 20 69 73 20 61 6e 20 65 72 72 6f  . ^It is an erro
22120 72 20 74 6f 20 73 70 65 63 69 66 79 20 61 20 76  r to specify a v
22130 61 6c 75 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20  alue for.**     
22140 74 68 65 20 6d 6f 64 65 20 70 61 72 61 6d 65 74  the mode paramet
22150 65 72 20 74 68 61 74 20 69 73 20 6c 65 73 73 20  er that is less 
22160 72 65 73 74 72 69 63 74 69 76 65 20 74 68 61 6e  restrictive than
22170 20 74 68 61 74 20 73 70 65 63 69 66 69 65 64 20   that specified 
22180 62 79 0a 2a 2a 20 20 20 20 20 74 68 65 20 66 6c  by.**     the fl
22190 61 67 73 20 70 61 73 73 65 64 20 69 6e 20 74 68  ags passed in th
221a0 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
221b0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65  r to sqlite3_ope
221c0 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20  n_v2()..**.**   
221d0 3c 6c 69 3e 20 3c 62 3e 63 61 63 68 65 3c 2f 62  <li> <b>cache</b
221e0 3e 3a 20 5e 54 68 65 20 63 61 63 68 65 20 70 61  >: ^The cache pa
221f0 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 73  rameter may be s
22200 65 74 20 74 6f 20 65 69 74 68 65 72 20 22 73 68  et to either "sh
22210 61 72 65 64 22 20 6f 72 0a 2a 2a 20 20 20 20 20  ared" or.**     
22220 22 70 72 69 76 61 74 65 22 2e 20 5e 53 65 74 74  "private". ^Sett
22230 69 6e 67 20 69 74 20 74 6f 20 22 73 68 61 72 65  ing it to "share
22240 64 22 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74  d" is equivalent
22250 20 74 6f 20 73 65 74 74 69 6e 67 20 74 68 65 0a   to setting the.
22260 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50  **     SQLITE_OP
22270 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20 62  EN_SHAREDCACHE b
22280 69 74 20 69 6e 20 74 68 65 20 66 6c 61 67 73 20  it in the flags 
22290 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20  argument passed 
222a0 74 6f 0a 2a 2a 20 20 20 20 20 73 71 6c 69 74 65  to.**     sqlite
222b0 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 53 65  3_open_v2(). ^Se
222c0 74 74 69 6e 67 20 74 68 65 20 63 61 63 68 65 20  tting the cache 
222d0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 22 70 72  parameter to "pr
222e0 69 76 61 74 65 22 20 69 73 20 0a 2a 2a 20 20 20  ivate" is .**   
222f0 20 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20    equivalent to 
22300 73 65 74 74 69 6e 67 20 74 68 65 20 53 51 4c 49  setting the SQLI
22310 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43  TE_OPEN_PRIVATEC
22320 41 43 48 45 20 62 69 74 2e 0a 2a 2a 20 20 20 20  ACHE bit..**    
22330 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 65   ^If sqlite3_ope
22340 6e 5f 76 32 28 29 20 69 73 20 75 73 65 64 20 61  n_v2() is used a
22350 6e 64 20 74 68 65 20 22 63 61 63 68 65 22 20 70  nd the "cache" p
22360 61 72 61 6d 65 74 65 72 20 69 73 20 70 72 65 73  arameter is pres
22370 65 6e 74 20 69 6e 0a 2a 2a 20 20 20 20 20 61 20  ent in.**     a 
22380 55 52 49 20 66 69 6c 65 6e 61 6d 65 2c 20 69 74  URI filename, it
22390 73 20 76 61 6c 75 65 20 6f 76 65 72 72 69 64 65  s value override
223a0 73 20 61 6e 79 20 62 65 68 61 76 69 6f 72 20 72  s any behavior r
223b0 65 71 75 65 73 74 65 64 20 62 79 20 73 65 74 74  equested by sett
223c0 69 6e 67 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54  ing.**     SQLIT
223d0 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41  E_OPEN_PRIVATECA
223e0 43 48 45 20 6f 72 20 53 51 4c 49 54 45 5f 4f 50  CHE or SQLITE_OP
223f0 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20 66  EN_SHAREDCACHE f
22400 6c 61 67 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e  lag..**.**  <li>
22410 20 3c 62 3e 70 73 6f 77 3c 2f 62 3e 3a 20 5e 54   <b>psow</b>: ^T
22420 68 65 20 70 73 6f 77 20 70 61 72 61 6d 65 74 65  he psow paramete
22430 72 20 6d 61 79 20 62 65 20 22 74 72 75 65 22 20  r may be "true" 
22440 28 6f 72 20 22 6f 6e 22 20 6f 72 20 22 79 65 73  (or "on" or "yes
22450 22 20 6f 72 0a 2a 2a 20 20 20 20 20 22 31 22 29  " or.**     "1")
22460 20 6f 72 20 22 66 61 6c 73 65 22 20 28 6f 72 20   or "false" (or 
22470 22 6f 66 66 22 20 6f 72 20 22 6e 6f 22 20 6f 72  "off" or "no" or
22480 20 22 30 22 29 20 74 6f 20 69 6e 64 69 63 61 74   "0") to indicat
22490 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 20 20  e that the.**   
224a0 20 20 5b 70 6f 77 65 72 73 61 66 65 20 6f 76 65    [powersafe ove
224b0 72 77 72 69 74 65 5d 20 70 72 6f 70 65 72 74 79  rwrite] property
224c0 20 64 6f 65 73 20 6f 72 20 64 6f 65 73 20 6e 6f   does or does no
224d0 74 20 61 70 70 6c 79 20 74 6f 20 74 68 65 0a 2a  t apply to the.*
224e0 2a 20 20 20 20 20 73 74 6f 72 61 67 65 20 6d 65  *     storage me
224f0 64 69 61 20 6f 6e 20 77 68 69 63 68 20 74 68 65  dia on which the
22500 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 72   database file r
22510 65 73 69 64 65 73 2e 20 20 5e 54 68 65 20 70 73  esides.  ^The ps
22520 6f 77 20 71 75 65 72 79 0a 2a 2a 20 20 20 20 20  ow query.**     
22530 70 61 72 61 6d 65 74 65 72 20 6f 6e 6c 79 20 77  parameter only w
22540 6f 72 6b 73 20 66 6f 72 20 74 68 65 20 62 75 69  orks for the bui
22550 6c 74 2d 69 6e 20 75 6e 69 78 20 61 6e 64 20 57  lt-in unix and W
22560 69 6e 64 6f 77 73 20 56 46 53 65 73 2e 0a 2a 2a  indows VFSes..**
22570 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e 6e 6f 6c  .**  <li> <b>nol
22580 6f 63 6b 3c 2f 62 3e 3a 20 5e 54 68 65 20 6e 6f  ock</b>: ^The no
22590 6c 6f 63 6b 20 70 61 72 61 6d 65 74 65 72 20 69  lock parameter i
225a0 73 20 61 20 62 6f 6f 6c 65 61 6e 20 71 75 65 72  s a boolean quer
225b0 79 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 20  y parameter.**  
225c0 20 20 20 77 68 69 63 68 20 69 66 20 73 65 74 20     which if set 
225d0 64 69 73 61 62 6c 65 73 20 66 69 6c 65 20 6c 6f  disables file lo
225e0 63 6b 69 6e 67 20 69 6e 20 72 6f 6c 6c 62 61 63  cking in rollbac
225f0 6b 20 6a 6f 75 72 6e 61 6c 20 6d 6f 64 65 73 2e  k journal modes.
22600 20 20 54 68 69 73 0a 2a 2a 20 20 20 20 20 69 73    This.**     is
22610 20 75 73 65 66 75 6c 20 66 6f 72 20 61 63 63 65   useful for acce
22620 73 73 69 6e 67 20 61 20 64 61 74 61 62 61 73 65  ssing a database
22630 20 6f 6e 20 61 20 66 69 6c 65 73 79 73 74 65 6d   on a filesystem
22640 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 0a 2a   that does not.*
22650 2a 20 20 20 20 20 73 75 70 70 6f 72 74 20 6c 6f  *     support lo
22660 63 6b 69 6e 67 2e 20 20 43 61 75 74 69 6f 6e 3a  cking.  Caution:
22670 20 20 44 61 74 61 62 61 73 65 20 63 6f 72 72 75    Database corru
22680 70 74 69 6f 6e 20 6d 69 67 68 74 20 72 65 73 75  ption might resu
22690 6c 74 20 69 66 20 74 77 6f 0a 2a 2a 20 20 20 20  lt if two.**    
226a0 20 6f 72 20 6d 6f 72 65 20 70 72 6f 63 65 73 73   or more process
226b0 65 73 20 77 72 69 74 65 20 74 6f 20 74 68 65 20  es write to the 
226c0 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 61 6e  same database an
226d0 64 20 61 6e 79 20 6f 6e 65 20 6f 66 20 74 68 6f  d any one of tho
226e0 73 65 0a 2a 2a 20 20 20 20 20 70 72 6f 63 65 73  se.**     proces
226f0 73 65 73 20 75 73 65 73 20 6e 6f 6c 6f 63 6b 3d  ses uses nolock=
22700 31 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c  1..**.**  <li> <
22710 62 3e 69 6d 6d 75 74 61 62 6c 65 3c 2f 62 3e 3a  b>immutable</b>:
22720 20 5e 54 68 65 20 69 6d 6d 75 74 61 62 6c 65 20   ^The immutable 
22730 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 62  parameter is a b
22740 6f 6f 6c 65 61 6e 20 71 75 65 72 79 0a 2a 2a 20  oolean query.** 
22750 20 20 20 20 70 61 72 61 6d 65 74 65 72 20 74 68      parameter th
22760 61 74 20 69 6e 64 69 63 61 74 65 73 20 74 68 61  at indicates tha
22770 74 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  t the database f
22780 69 6c 65 20 69 73 20 73 74 6f 72 65 64 20 6f 6e  ile is stored on
22790 0a 2a 2a 20 20 20 20 20 72 65 61 64 2d 6f 6e 6c  .**     read-onl
227a0 79 20 6d 65 64 69 61 2e 20 20 5e 57 68 65 6e 20  y media.  ^When 
227b0 69 6d 6d 75 74 61 62 6c 65 20 69 73 20 73 65 74  immutable is set
227c0 2c 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73  , SQLite assumes
227d0 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 20 20 20   that the.**    
227e0 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 63   database file c
227f0 61 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67 65 64  annot be changed
22800 2c 20 65 76 65 6e 20 62 79 20 61 20 70 72 6f 63  , even by a proc
22810 65 73 73 20 77 69 74 68 20 68 69 67 68 65 72 0a  ess with higher.
22820 2a 2a 20 20 20 20 20 70 72 69 76 69 6c 65 67 65  **     privilege
22830 2c 20 61 6e 64 20 73 6f 20 74 68 65 20 64 61 74  , and so the dat
22840 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
22850 72 65 61 64 2d 6f 6e 6c 79 20 61 6e 64 20 61 6c  read-only and al
22860 6c 20 6c 6f 63 6b 69 6e 67 0a 2a 2a 20 20 20 20  l locking.**    
22870 20 61 6e 64 20 63 68 61 6e 67 65 20 64 65 74 65   and change dete
22880 63 74 69 6f 6e 20 69 73 20 64 69 73 61 62 6c 65  ction is disable
22890 64 2e 20 20 43 61 75 74 69 6f 6e 3a 20 53 65 74  d.  Caution: Set
228a0 74 69 6e 67 20 74 68 65 20 69 6d 6d 75 74 61 62  ting the immutab
228b0 6c 65 0a 2a 2a 20 20 20 20 20 70 72 6f 70 65 72  le.**     proper
228c0 74 79 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65  ty on a database
228d0 20 66 69 6c 65 20 74 68 61 74 20 64 6f 65 73 20   file that does 
228e0 69 6e 20 66 61 63 74 20 63 68 61 6e 67 65 20 63  in fact change c
228f0 61 6e 20 72 65 73 75 6c 74 0a 2a 2a 20 20 20 20  an result.**    
22900 20 69 6e 20 69 6e 63 6f 72 72 65 63 74 20 71 75   in incorrect qu
22910 65 72 79 20 72 65 73 75 6c 74 73 20 61 6e 64 2f  ery results and/
22920 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55  or [SQLITE_CORRU
22930 50 54 5d 20 65 72 72 6f 72 73 2e 0a 2a 2a 20 20  PT] errors..**  
22940 20 20 20 53 65 65 20 61 6c 73 6f 3a 20 5b 53 51     See also: [SQ
22950 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54  LITE_IOCAP_IMMUT
22960 41 42 4c 45 5d 2e 0a 2a 2a 20 20 20 20 20 20 20  ABLE]..**       
22970 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
22980 5e 53 70 65 63 69 66 79 69 6e 67 20 61 6e 20 75  ^Specifying an u
22990 6e 6b 6e 6f 77 6e 20 70 61 72 61 6d 65 74 65 72  nknown parameter
229a0 20 69 6e 20 74 68 65 20 71 75 65 72 79 20 63 6f   in the query co
229b0 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49  mponent of a URI
229c0 20 69 73 20 6e 6f 74 20 61 6e 0a 2a 2a 20 65 72   is not an.** er
229d0 72 6f 72 2e 20 20 46 75 74 75 72 65 20 76 65 72  ror.  Future ver
229e0 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20  sions of SQLite 
229f0 6d 69 67 68 74 20 75 6e 64 65 72 73 74 61 6e 64  might understand
22a00 20 61 64 64 69 74 69 6f 6e 61 6c 20 71 75 65 72   additional quer
22a10 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e  y.** parameters.
22a20 20 20 53 65 65 20 22 5b 71 75 65 72 79 20 70 61    See "[query pa
22a30 72 61 6d 65 74 65 72 73 20 77 69 74 68 20 73 70  rameters with sp
22a40 65 63 69 61 6c 20 6d 65 61 6e 69 6e 67 20 74 6f  ecial meaning to
22a50 20 53 51 4c 69 74 65 5d 22 20 66 6f 72 0a 2a 2a   SQLite]" for.**
22a60 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f   additional info
22a70 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b  rmation..**.** [
22a80 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 65 78  [URI filename ex
22a90 61 6d 70 6c 65 73 5d 5d 20 3c 68 33 3e 55 52 49  amples]] <h3>URI
22aa0 20 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c   filename exampl
22ab0 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 3c 74  es</h3>.**.** <t
22ac0 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 20  able border="1" 
22ad0 61 6c 69 67 6e 3d 63 65 6e 74 65 72 20 63 65 6c  align=center cel
22ae0 6c 70 61 64 64 69 6e 67 3d 35 3e 0a 2a 2a 20 3c  lpadding=5>.** <
22af0 74 72 3e 3c 74 68 3e 20 55 52 49 20 66 69 6c 65  tr><th> URI file
22b00 6e 61 6d 65 73 20 3c 74 68 3e 20 52 65 73 75 6c  names <th> Resul
22b10 74 73 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66  ts.** <tr><td> f
22b20 69 6c 65 3a 64 61 74 61 2e 64 62 20 3c 74 64 3e  ile:data.db <td>
22b30 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70   .**          Op
22b40 65 6e 20 74 68 65 20 66 69 6c 65 20 22 64 61 74  en the file "dat
22b50 61 2e 64 62 22 20 69 6e 20 74 68 65 20 63 75 72  a.db" in the cur
22b60 72 65 6e 74 20 64 69 72 65 63 74 6f 72 79 2e 0a  rent directory..
22b70 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65  ** <tr><td> file
22b80 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61  :/home/fred/data
22b90 2e 64 62 3c 62 72 3e 0a 2a 2a 20 20 20 20 20 20  .db<br>.**      
22ba0 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 68 6f 6d 65      file:///home
22bb0 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 62  /fred/data.db <b
22bc0 72 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  r> .**          
22bd0 66 69 6c 65 3a 2f 2f 6c 6f 63 61 6c 68 6f 73 74  file://localhost
22be0 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e  /home/fred/data.
22bf0 64 62 20 3c 62 72 3e 20 3c 74 64 3e 20 0a 2a 2a  db <br> <td> .**
22c00 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 74            Open t
22c10 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
22c20 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74   "/home/fred/dat
22c30 61 2e 64 62 22 2e 0a 2a 2a 20 3c 74 72 3e 3c 74  a.db"..** <tr><t
22c40 64 3e 20 66 69 6c 65 3a 2f 2f 64 61 72 6b 73 74  d> file://darkst
22c50 61 72 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74  ar/home/fred/dat
22c60 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20  a.db <td> .**   
22c70 20 20 20 20 20 20 20 41 6e 20 65 72 72 6f 72 2e         An error.
22c80 20 22 64 61 72 6b 73 74 61 72 22 20 69 73 20 6e   "darkstar" is n
22c90 6f 74 20 61 20 72 65 63 6f 67 6e 69 7a 65 64 20  ot a recognized 
22ca0 61 75 74 68 6f 72 69 74 79 2e 0a 2a 2a 20 3c 74  authority..** <t
22cb0 72 3e 3c 74 64 20 73 74 79 6c 65 3d 22 77 68 69  r><td style="whi
22cc0 74 65 2d 73 70 61 63 65 3a 6e 6f 77 72 61 70 22  te-space:nowrap"
22cd0 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66  > .**          f
22ce0 69 6c 65 3a 2f 2f 2f 43 3a 2f 44 6f 63 75 6d 65  ile:///C:/Docume
22cf0 6e 74 73 25 32 30 61 6e 64 25 32 30 53 65 74 74  nts%20and%20Sett
22d00 69 6e 67 73 2f 66 72 65 64 2f 44 65 73 6b 74 6f  ings/fred/Deskto
22d10 70 2f 64 61 74 61 2e 64 62 0a 2a 2a 20 20 20 20  p/data.db.**    
22d20 20 3c 74 64 3e 20 57 69 6e 64 6f 77 73 20 6f 6e   <td> Windows on
22d30 6c 79 3a 20 4f 70 65 6e 20 74 68 65 20 66 69 6c  ly: Open the fil
22d40 65 20 22 64 61 74 61 2e 64 62 22 20 6f 6e 20 66  e "data.db" on f
22d50 72 65 64 27 73 20 64 65 73 6b 74 6f 70 20 6f 6e  red's desktop on
22d60 20 64 72 69 76 65 0a 2a 2a 20 20 20 20 20 20 20   drive.**       
22d70 20 20 20 43 3a 2e 20 4e 6f 74 65 20 74 68 61 74     C:. Note that
22d80 20 74 68 65 20 25 32 30 20 65 73 63 61 70 69 6e   the %20 escapin
22d90 67 20 69 6e 20 74 68 69 73 20 65 78 61 6d 70 6c  g in this exampl
22da0 65 20 69 73 20 6e 6f 74 20 73 74 72 69 63 74 6c  e is not strictl
22db0 79 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e  y .**          n
22dc0 65 63 65 73 73 61 72 79 20 2d 20 73 70 61 63 65  ecessary - space
22dd0 20 63 68 61 72 61 63 74 65 72 73 20 63 61 6e 20   characters can 
22de0 62 65 20 75 73 65 64 20 6c 69 74 65 72 61 6c 6c  be used literall
22df0 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e  y.**          in
22e00 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 2e 0a   URI filenames..
22e10 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65  ** <tr><td> file
22e20 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 6f  :data.db?mode=ro
22e30 26 63 61 63 68 65 3d 70 72 69 76 61 74 65 20 3c  &cache=private <
22e40 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  td> .**         
22e50 20 4f 70 65 6e 20 66 69 6c 65 20 22 64 61 74 61   Open file "data
22e60 2e 64 62 22 20 69 6e 20 74 68 65 20 63 75 72 72  .db" in the curr
22e70 65 6e 74 20 64 69 72 65 63 74 6f 72 79 20 66 6f  ent directory fo
22e80 72 20 72 65 61 64 2d 6f 6e 6c 79 20 61 63 63 65  r read-only acce
22e90 73 73 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ss..**          
22ea0 52 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68  Regardless of wh
22eb0 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61  ether or not sha
22ec0 72 65 64 2d 63 61 63 68 65 20 6d 6f 64 65 20 69  red-cache mode i
22ed0 73 20 65 6e 61 62 6c 65 64 20 62 79 0a 2a 2a 20  s enabled by.** 
22ee0 20 20 20 20 20 20 20 20 20 64 65 66 61 75 6c 74           default
22ef0 2c 20 75 73 65 20 61 20 70 72 69 76 61 74 65 20  , use a private 
22f00 63 61 63 68 65 2e 0a 2a 2a 20 3c 74 72 3e 3c 74  cache..** <tr><t
22f10 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72  d> file:/home/fr
22f20 65 64 2f 64 61 74 61 2e 64 62 3f 76 66 73 3d 75  ed/data.db?vfs=u
22f30 6e 69 78 2d 64 6f 74 66 69 6c 65 20 3c 74 64 3e  nix-dotfile <td>
22f40 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65  .**          Ope
22f50 6e 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72  n file "/home/fr
22f60 65 64 2f 64 61 74 61 2e 64 62 22 2e 20 55 73 65  ed/data.db". Use
22f70 20 74 68 65 20 73 70 65 63 69 61 6c 20 56 46 53   the special VFS
22f80 20 22 75 6e 69 78 2d 64 6f 74 66 69 6c 65 22 0a   "unix-dotfile".
22f90 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 61 74  **          that
22fa0 20 75 73 65 73 20 64 6f 74 2d 66 69 6c 65 73 20   uses dot-files 
22fb0 69 6e 20 70 6c 61 63 65 20 6f 66 20 70 6f 73 69  in place of posi
22fc0 78 20 61 64 76 69 73 6f 72 79 20 6c 6f 63 6b 69  x advisory locki
22fd0 6e 67 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  ng..** <tr><td> 
22fe0 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64  file:data.db?mod
22ff0 65 3d 72 65 61 64 6f 6e 6c 79 20 3c 74 64 3e 20  e=readonly <td> 
23000 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 41 6e 20  .**          An 
23010 65 72 72 6f 72 2e 20 22 72 65 61 64 6f 6e 6c 79  error. "readonly
23020 22 20 69 73 20 6e 6f 74 20 61 20 76 61 6c 69 64  " is not a valid
23030 20 6f 70 74 69 6f 6e 20 66 6f 72 20 74 68 65 20   option for the 
23040 22 6d 6f 64 65 22 20 70 61 72 61 6d 65 74 65 72  "mode" parameter
23050 2e 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a  ..** </table>.**
23060 0a 2a 2a 20 5e 55 52 49 20 68 65 78 61 64 65 63  .** ^URI hexadec
23070 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71 75  imal escape sequ
23080 65 6e 63 65 73 20 28 25 48 48 29 20 61 72 65 20  ences (%HH) are 
23090 73 75 70 70 6f 72 74 65 64 20 77 69 74 68 69 6e  supported within
230a0 20 74 68 65 20 70 61 74 68 20 61 6e 64 0a 2a 2a   the path and.**
230b0 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74   query component
230c0 73 20 6f 66 20 61 20 55 52 49 2e 20 41 20 68 65  s of a URI. A he
230d0 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65  xadecimal escape
230e0 20 73 65 71 75 65 6e 63 65 20 63 6f 6e 73 69 73   sequence consis
230f0 74 73 20 6f 66 20 61 0a 2a 2a 20 70 65 72 63 65  ts of a.** perce
23100 6e 74 20 73 69 67 6e 20 2d 20 22 25 22 20 2d 20  nt sign - "%" - 
23110 66 6f 6c 6c 6f 77 65 64 20 62 79 20 65 78 61 63  followed by exac
23120 74 6c 79 20 74 77 6f 20 68 65 78 61 64 65 63 69  tly two hexadeci
23130 6d 61 6c 20 64 69 67 69 74 73 20 0a 2a 2a 20 73  mal digits .** s
23140 70 65 63 69 66 79 69 6e 67 20 61 6e 20 6f 63 74  pecifying an oct
23150 65 74 20 76 61 6c 75 65 2e 20 5e 42 65 66 6f 72  et value. ^Befor
23160 65 20 74 68 65 20 70 61 74 68 20 6f 72 20 71 75  e the path or qu
23170 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f  ery components o
23180 66 20 61 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e  f a.** URI filen
23190 61 6d 65 20 61 72 65 20 69 6e 74 65 72 70 72 65  ame are interpre
231a0 74 65 64 2c 20 74 68 65 79 20 61 72 65 20 65 6e  ted, they are en
231b0 63 6f 64 65 64 20 75 73 69 6e 67 20 55 54 46 2d  coded using UTF-
231c0 38 20 61 6e 64 20 61 6c 6c 20 0a 2a 2a 20 68 65  8 and all .** he
231d0 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65  xadecimal escape
231e0 20 73 65 71 75 65 6e 63 65 73 20 72 65 70 6c 61   sequences repla
231f0 63 65 64 20 62 79 20 61 20 73 69 6e 67 6c 65 20  ced by a single 
23200 62 79 74 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20  byte containing 
23210 74 68 65 0a 2a 2a 20 63 6f 72 72 65 73 70 6f 6e  the.** correspon
23220 64 69 6e 67 20 6f 63 74 65 74 2e 20 49 66 20 74  ding octet. If t
23230 68 69 73 20 70 72 6f 63 65 73 73 20 67 65 6e 65  his process gene
23240 72 61 74 65 73 20 61 6e 20 69 6e 76 61 6c 69 64  rates an invalid
23250 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 2c   UTF-8 encoding,
23260 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 73 20  .** the results 
23270 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  are undefined..*
23280 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20  *.** <b>Note to 
23290 57 69 6e 64 6f 77 73 20 75 73 65 72 73 3a 3c 2f  Windows users:</
232a0 62 3e 20 20 54 68 65 20 65 6e 63 6f 64 69 6e 67  b>  The encoding
232b0 20 75 73 65 64 20 66 6f 72 20 74 68 65 20 66 69   used for the fi
232c0 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a  lename argument.
232d0 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 70  ** of sqlite3_op
232e0 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  en() and sqlite3
232f0 5f 6f 70 65 6e 5f 76 32 28 29 20 6d 75 73 74 20  _open_v2() must 
23300 62 65 20 55 54 46 2d 38 2c 20 6e 6f 74 20 77 68  be UTF-8, not wh
23310 61 74 65 76 65 72 0a 2a 2a 20 63 6f 64 65 70 61  atever.** codepa
23320 67 65 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20  ge is currently 
23330 64 65 66 69 6e 65 64 2e 20 20 46 69 6c 65 6e 61  defined.  Filena
23340 6d 65 73 20 63 6f 6e 74 61 69 6e 69 6e 67 20 69  mes containing i
23350 6e 74 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20  nternational.** 
23360 63 68 61 72 61 63 74 65 72 73 20 6d 75 73 74 20  characters must 
23370 62 65 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20  be converted to 
23380 55 54 46 2d 38 20 70 72 69 6f 72 20 74 6f 20 70  UTF-8 prior to p
23390 61 73 73 69 6e 67 20 74 68 65 6d 20 69 6e 74 6f  assing them into
233a0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  .** sqlite3_open
233b0 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  () or sqlite3_op
233c0 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 3c  en_v2()..**.** <
233d0 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77  b>Note to Window
233e0 73 20 52 75 6e 74 69 6d 65 20 75 73 65 72 73 3a  s Runtime users:
233f0 3c 2f 62 3e 20 20 54 68 65 20 74 65 6d 70 6f 72  </b>  The tempor
23400 61 72 79 20 64 69 72 65 63 74 6f 72 79 20 6d 75  ary directory mu
23410 73 74 20 62 65 20 73 65 74 0a 2a 2a 20 70 72 69  st be set.** pri
23420 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 20 73 71  or to calling sq
23430 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20  lite3_open() or 
23440 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
23450 29 2e 20 20 4f 74 68 65 72 77 69 73 65 2c 20 76  ).  Otherwise, v
23460 61 72 69 6f 75 73 0a 2a 2a 20 66 65 61 74 75 72  arious.** featur
23470 65 73 20 74 68 61 74 20 72 65 71 75 69 72 65 20  es that require 
23480 74 68 65 20 75 73 65 20 6f 66 20 74 65 6d 70 6f  the use of tempo
23490 72 61 72 79 20 66 69 6c 65 73 20 6d 61 79 20 66  rary files may f
234a0 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ail..**.** See a
234b0 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 74 65  lso: [sqlite3_te
234c0 6d 70 5f 64 69 72 65 63 74 6f 72 79 5d 0a 2a 2f  mp_directory].*/
234d0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65  .int sqlite3_ope
234e0 6e 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  n(.  const char 
234f0 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20  *filename,   /* 
23500 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d  Database filenam
23510 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73  e (UTF-8) */.  s
23520 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20  qlite3 **ppDb   
23530 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53         /* OUT: S
23540 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20  QLite db handle 
23550 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  */.);.int sqlite
23560 33 5f 6f 70 65 6e 31 36 28 0a 20 20 63 6f 6e 73  3_open16(.  cons
23570 74 20 76 6f 69 64 20 2a 66 69 6c 65 6e 61 6d 65  t void *filename
23580 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  ,   /* Database 
23590 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 31 36  filename (UTF-16
235a0 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a  ) */.  sqlite3 *
235b0 2a 70 70 44 62 20 20 20 20 20 20 20 20 20 20 2f  *ppDb          /
235c0 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62  * OUT: SQLite db
235d0 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e   handle */.);.in
235e0 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  t sqlite3_open_v
235f0 32 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  2(.  const char 
23600 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20  *filename,   /* 
23610 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d  Database filenam
23620 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73  e (UTF-8) */.  s
23630 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 2c 20 20  qlite3 **ppDb,  
23640 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53         /* OUT: S
23650 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20  QLite db handle 
23660 2a 2f 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c 20  */.  int flags, 
23670 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
23680 46 6c 61 67 73 20 2a 2f 0a 20 20 63 6f 6e 73 74  Flags */.  const
23690 20 63 68 61 72 20 2a 7a 56 66 73 20 20 20 20 20   char *zVfs     
236a0 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 56 46     /* Name of VF
236b0 53 20 6d 6f 64 75 6c 65 20 74 6f 20 75 73 65 20  S module to use 
236c0 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.);../*.** CAP
236d0 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 56 61  I3REF: Obtain Va
236e0 6c 75 65 73 20 46 6f 72 20 55 52 49 20 50 61 72  lues For URI Par
236f0 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 54 68  ameters.**.** Th
23700 65 73 65 20 61 72 65 20 75 74 69 6c 69 74 79 20  ese are utility 
23710 72 6f 75 74 69 6e 65 73 2c 20 75 73 65 66 75 6c  routines, useful
23720 20 74 6f 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e   to VFS implemen
23730 74 61 74 69 6f 6e 73 2c 20 74 68 61 74 20 63 68  tations, that ch
23740 65 63 6b 0a 2a 2a 20 74 6f 20 73 65 65 20 69 66  eck.** to see if
23750 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65   a database file
23760 20 77 61 73 20 61 20 55 52 49 20 74 68 61 74 20   was a URI that 
23770 63 6f 6e 74 61 69 6e 65 64 20 61 20 73 70 65 63  contained a spec
23780 69 66 69 63 20 71 75 65 72 79 20 0a 2a 2a 20 70  ific query .** p
23790 61 72 61 6d 65 74 65 72 2c 20 61 6e 64 20 69 66  arameter, and if
237a0 20 73 6f 20 6f 62 74 61 69 6e 73 20 74 68 65 20   so obtains the 
237b0 76 61 6c 75 65 20 6f 66 20 74 68 61 74 20 71 75  value of that qu
237c0 65 72 79 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  ery parameter..*
237d0 2a 0a 2a 2a 20 49 66 20 46 20 69 73 20 74 68 65  *.** If F is the
237e0 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61   database filena
237f0 6d 65 20 70 6f 69 6e 74 65 72 20 70 61 73 73 65  me pointer passe
23800 64 20 69 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e  d into the xOpen
23810 28 29 20 6d 65 74 68 6f 64 20 6f 66 20 0a 2a 2a  () method of .**
23820 20 61 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74   a VFS implement
23830 61 74 69 6f 6e 20 77 68 65 6e 20 74 68 65 20 66  ation when the f
23840 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 74  lags parameter t
23850 6f 20 78 4f 70 65 6e 28 29 20 68 61 73 20 6f 6e  o xOpen() has on
23860 65 20 6f 72 20 0a 2a 2a 20 6d 6f 72 65 20 6f 66  e or .** more of
23870 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   the [SQLITE_OPE
23880 4e 5f 55 52 49 5d 20 6f 72 20 5b 53 51 4c 49 54  N_URI] or [SQLIT
23890 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 20  E_OPEN_MAIN_DB] 
238a0 62 69 74 73 20 73 65 74 20 61 6e 64 0a 2a 2a 20  bits set and.** 
238b0 50 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  P is the name of
238c0 20 74 68 65 20 71 75 65 72 79 20 70 61 72 61 6d   the query param
238d0 65 74 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 73 71  eter, then.** sq
238e0 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65  lite3_uri_parame
238f0 74 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73  ter(F,P) returns
23900 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68   the value of th
23910 65 20 50 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  e P.** parameter
23920 20 69 66 20 69 74 20 65 78 69 73 74 73 20 6f 72   if it exists or
23930 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
23940 69 66 20 50 20 64 6f 65 73 20 6e 6f 74 20 61 70  if P does not ap
23950 70 65 61 72 20 61 73 20 61 20 0a 2a 2a 20 71 75  pear as a .** qu
23960 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 6f 6e  ery parameter on
23970 20 46 2e 20 20 49 66 20 50 20 69 73 20 61 20 71   F.  If P is a q
23980 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 6f  uery parameter o
23990 66 20 46 0a 2a 2a 20 68 61 73 20 6e 6f 20 65 78  f F.** has no ex
239a0 70 6c 69 63 69 74 20 76 61 6c 75 65 2c 20 74 68  plicit value, th
239b0 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70  en sqlite3_uri_p
239c0 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65  arameter(F,P) re
239d0 74 75 72 6e 73 0a 2a 2a 20 61 20 70 6f 69 6e 74  turns.** a point
239e0 65 72 20 74 6f 20 61 6e 20 65 6d 70 74 79 20 73  er to an empty s
239f0 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  tring..**.** The
23a00 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f   sqlite3_uri_boo
23a10 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74  lean(F,P,B) rout
23a20 69 6e 65 20 61 73 73 75 6d 65 73 20 74 68 61 74  ine assumes that
23a30 20 50 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e 0a   P is a boolean.
23a40 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64  ** parameter and
23a50 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 31   returns true (1
23a60 29 20 6f 72 20 66 61 6c 73 65 20 28 30 29 20 61  ) or false (0) a
23a70 63 63 6f 72 64 69 6e 67 20 74 6f 20 74 68 65 20  ccording to the 
23a80 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 50 2e 20 20  value.** of P.  
23a90 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  The sqlite3_uri_
23aa0 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72  boolean(F,P,B) r
23ab0 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
23ac0 72 75 65 20 28 31 29 20 69 66 20 74 68 65 0a 2a  rue (1) if the.*
23ad0 2a 20 76 61 6c 75 65 20 6f 66 20 71 75 65 72 79  * value of query
23ae0 20 70 61 72 61 6d 65 74 65 72 20 50 20 69 73 20   parameter P is 
23af0 6f 6e 65 20 6f 66 20 22 79 65 73 22 2c 20 22 74  one of "yes", "t
23b00 72 75 65 22 2c 20 6f 72 20 22 6f 6e 22 20 69 6e  rue", or "on" in
23b10 20 61 6e 79 0a 2a 2a 20 63 61 73 65 20 6f 72 20   any.** case or 
23b20 69 66 20 74 68 65 20 76 61 6c 75 65 20 62 65 67  if the value beg
23b30 69 6e 73 20 77 69 74 68 20 61 20 6e 6f 6e 2d 7a  ins with a non-z
23b40 65 72 6f 20 6e 75 6d 62 65 72 2e 20 20 54 68 65  ero number.  The
23b50 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69   .** sqlite3_uri
23b60 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20  _boolean(F,P,B) 
23b70 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 73  routines returns
23b80 20 66 61 6c 73 65 20 28 30 29 20 69 66 20 74 68   false (0) if th
23b90 65 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 71 75  e value of.** qu
23ba0 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 50 20  ery parameter P 
23bb0 69 73 20 6f 6e 65 20 6f 66 20 22 6e 6f 22 2c 20  is one of "no", 
23bc0 22 66 61 6c 73 65 22 2c 20 6f 72 20 22 6f 66 66  "false", or "off
23bd0 22 20 69 6e 20 61 6e 79 20 63 61 73 65 20 6f 72  " in any case or
23be0 0a 2a 2a 20 69 66 20 74 68 65 20 76 61 6c 75 65  .** if the value
23bf0 20 62 65 67 69 6e 73 20 77 69 74 68 20 61 20 6e   begins with a n
23c00 75 6d 65 72 69 63 20 7a 65 72 6f 2e 20 20 49 66  umeric zero.  If
23c10 20 50 20 69 73 20 6e 6f 74 20 61 20 71 75 65 72   P is not a quer
23c20 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 6f  y.** parameter o
23c30 6e 20 46 20 6f 72 20 69 66 20 74 68 65 20 76 61  n F or if the va
23c40 6c 75 65 20 6f 66 20 50 20 69 73 20 64 6f 65 73  lue of P is does
23c50 20 6e 6f 74 20 6d 61 74 63 68 20 61 6e 79 20 6f   not match any o
23c60 66 20 74 68 65 0a 2a 2a 20 61 62 6f 76 65 2c 20  f the.** above, 
23c70 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69  then sqlite3_uri
23c80 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20  _boolean(F,P,B) 
23c90 72 65 74 75 72 6e 73 20 28 42 21 3d 30 29 2e 0a  returns (B!=0)..
23ca0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
23cb0 33 5f 75 72 69 5f 69 6e 74 36 34 28 46 2c 50 2c  3_uri_int64(F,P,
23cc0 44 29 20 72 6f 75 74 69 6e 65 20 63 6f 6e 76 65  D) routine conve
23cd0 72 74 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66  rts the value of
23ce0 20 50 20 69 6e 74 6f 20 61 0a 2a 2a 20 36 34 2d   P into a.** 64-
23cf0 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67  bit signed integ
23d00 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20 74  er and returns t
23d10 68 61 74 20 69 6e 74 65 67 65 72 2c 20 6f 72 20  hat integer, or 
23d20 44 20 69 66 20 50 20 64 6f 65 73 20 6e 6f 74 0a  D if P does not.
23d30 2a 2a 20 65 78 69 73 74 2e 20 20 49 66 20 74 68  ** exist.  If th
23d40 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69 73 20  e value of P is 
23d50 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20  something other 
23d60 74 68 61 6e 20 61 6e 20 69 6e 74 65 67 65 72 2c  than an integer,
23d70 20 74 68 65 6e 0a 2a 2a 20 7a 65 72 6f 20 69 73   then.** zero is
23d80 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 0a 2a   returned..** .*
23d90 2a 20 49 66 20 46 20 69 73 20 61 20 4e 55 4c 4c  * If F is a NULL
23da0 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 73   pointer, then s
23db0 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d  qlite3_uri_param
23dc0 65 74 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e  eter(F,P) return
23dd0 73 20 4e 55 4c 4c 20 61 6e 64 0a 2a 2a 20 73 71  s NULL and.** sq
23de0 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61  lite3_uri_boolea
23df0 6e 28 46 2c 50 2c 42 29 20 72 65 74 75 72 6e 73  n(F,P,B) returns
23e00 20 42 2e 20 20 49 66 20 46 20 69 73 20 6e 6f 74   B.  If F is not
23e10 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
23e20 61 6e 64 0a 2a 2a 20 69 73 20 6e 6f 74 20 61 20  and.** is not a 
23e30 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 70 61  database file pa
23e40 74 68 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20 74  thname pointer t
23e50 68 61 74 20 53 51 4c 69 74 65 20 70 61 73 73 65  hat SQLite passe
23e60 64 20 69 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e  d into the xOpen
23e70 0a 2a 2a 20 56 46 53 20 6d 65 74 68 6f 64 2c 20  .** VFS method, 
23e80 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
23e90 72 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e  r of this routin
23ea0 65 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61  e is undefined a
23eb0 6e 64 20 70 72 6f 62 61 62 6c 79 0a 2a 2a 20 75  nd probably.** u
23ec0 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2f 0a 63  ndesirable..*/.c
23ed0 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
23ee0 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72  e3_uri_parameter
23ef0 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69  (const char *zFi
23f00 6c 65 6e 61 6d 65 2c 20 63 6f 6e 73 74 20 63 68  lename, const ch
23f10 61 72 20 2a 7a 50 61 72 61 6d 29 3b 0a 69 6e 74  ar *zParam);.int
23f20 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f   sqlite3_uri_boo
23f30 6c 65 61 6e 28 63 6f 6e 73 74 20 63 68 61 72 20  lean(const char 
23f40 2a 7a 46 69 6c 65 2c 20 63 6f 6e 73 74 20 63 68  *zFile, const ch
23f50 61 72 20 2a 7a 50 61 72 61 6d 2c 20 69 6e 74 20  ar *zParam, int 
23f60 62 44 65 66 61 75 6c 74 29 3b 0a 73 71 6c 69 74  bDefault);.sqlit
23f70 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
23f80 5f 75 72 69 5f 69 6e 74 36 34 28 63 6f 6e 73 74  _uri_int64(const
23f90 20 63 68 61 72 2a 2c 20 63 6f 6e 73 74 20 63 68   char*, const ch
23fa0 61 72 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  ar*, sqlite3_int
23fb0 36 34 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  64);.../*.** CAP
23fc0 49 33 52 45 46 3a 20 45 72 72 6f 72 20 43 6f 64  I3REF: Error Cod
23fd0 65 73 20 41 6e 64 20 4d 65 73 73 61 67 65 73 0a  es And Messages.
23fe0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
23ff0 65 33 5f 65 72 72 63 6f 64 65 28 29 20 69 6e 74  e3_errcode() int
24000 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
24010 68 65 20 6e 75 6d 65 72 69 63 20 5b 72 65 73 75  he numeric [resu
24020 6c 74 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b  lt code] or.** [
24030 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
24040 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 6d 6f  code] for the mo
24050 73 74 20 72 65 63 65 6e 74 20 66 61 69 6c 65 64  st recent failed
24060 20 73 71 6c 69 74 65 33 5f 2a 20 41 50 49 20 63   sqlite3_* API c
24070 61 6c 6c 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65  all.** associate
24080 64 20 77 69 74 68 20 61 20 5b 64 61 74 61 62 61  d with a [databa
24090 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20  se connection]. 
240a0 49 66 20 61 20 70 72 69 6f 72 20 41 50 49 20 63  If a prior API c
240b0 61 6c 6c 20 66 61 69 6c 65 64 0a 2a 2a 20 62 75  all failed.** bu
240c0 74 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  t the most recen
240d0 74 20 41 50 49 20 63 61 6c 6c 20 73 75 63 63 65  t API call succe
240e0 65 64 65 64 2c 20 74 68 65 20 72 65 74 75 72 6e  eded, the return
240f0 20 76 61 6c 75 65 20 66 72 6f 6d 0a 2a 2a 20 73   value from.** s
24100 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29  qlite3_errcode()
24110 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20   is undefined.  
24120 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74  ^The sqlite3_ext
24130 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29 0a  ended_errcode().
24140 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  ** interface is 
24150 74 68 65 20 73 61 6d 65 20 65 78 63 65 70 74 20  the same except 
24160 74 68 61 74 20 69 74 20 61 6c 77 61 79 73 20 72  that it always r
24170 65 74 75 72 6e 73 20 74 68 65 20 0a 2a 2a 20 5b  eturns the .** [
24180 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
24190 63 6f 64 65 5d 20 65 76 65 6e 20 77 68 65 6e 20  code] even when 
241a0 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
241b0 63 6f 64 65 73 20 61 72 65 0a 2a 2a 20 64 69 73  codes are.** dis
241c0 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  abled..**.** ^Th
241d0 65 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67  e sqlite3_errmsg
241e0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 65  () and sqlite3_e
241f0 72 72 6d 73 67 31 36 28 29 20 72 65 74 75 72 6e  rrmsg16() return
24200 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67   English-languag
24210 65 0a 2a 2a 20 74 65 78 74 20 74 68 61 74 20 64  e.** text that d
24220 65 73 63 72 69 62 65 73 20 74 68 65 20 65 72 72  escribes the err
24230 6f 72 2c 20 61 73 20 65 69 74 68 65 72 20 55 54  or, as either UT
24240 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 72 65  F-8 or UTF-16 re
24250 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e  spectively..** ^
24260 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20  (Memory to hold 
24270 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  the error messag
24280 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61  e string is mana
24290 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a  ged internally..
242a0 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
242b0 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64  on does not need
242c0 20 74 6f 20 77 6f 72 72 79 20 61 62 6f 75 74 20   to worry about 
242d0 66 72 65 65 69 6e 67 20 74 68 65 20 72 65 73 75  freeing the resu
242e0 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20  lt..** However, 
242f0 74 68 65 20 65 72 72 6f 72 20 73 74 72 69 6e 67  the error string
24300 20 6d 69 67 68 74 20 62 65 20 6f 76 65 72 77 72   might be overwr
24310 69 74 74 65 6e 20 6f 72 20 64 65 61 6c 6c 6f 63  itten or dealloc
24320 61 74 65 64 20 62 79 0a 2a 2a 20 73 75 62 73 65  ated by.** subse
24330 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 6f  quent calls to o
24340 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65  ther SQLite inte
24350 72 66 61 63 65 20 66 75 6e 63 74 69 6f 6e 73 2e  rface functions.
24360 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  )^.**.** ^The sq
24370 6c 69 74 65 33 5f 65 72 72 73 74 72 28 29 20 69  lite3_errstr() i
24380 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
24390 20 74 68 65 20 45 6e 67 6c 69 73 68 2d 6c 61 6e   the English-lan
243a0 67 75 61 67 65 20 74 65 78 74 0a 2a 2a 20 74 68  guage text.** th
243b0 61 74 20 64 65 73 63 72 69 62 65 73 20 74 68 65  at describes the
243c0 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 2c 20   [result code], 
243d0 61 73 20 55 54 46 2d 38 2e 0a 2a 2a 20 5e 28 4d  as UTF-8..** ^(M
243e0 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68  emory to hold th
243f0 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  e error message 
24400 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65  string is manage
24410 64 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20  d internally.** 
24420 61 6e 64 20 6d 75 73 74 20 6e 6f 74 20 62 65 20  and must not be 
24430 66 72 65 65 64 20 62 79 20 74 68 65 20 61 70 70  freed by the app
24440 6c 69 63 61 74 69 6f 6e 29 5e 2e 0a 2a 2a 0a 2a  lication)^..**.*
24450 2a 20 57 68 65 6e 20 74 68 65 20 73 65 72 69 61  * When the seria
24460 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67  lized [threading
24470 20 6d 6f 64 65 5d 20 69 73 20 69 6e 20 75 73 65   mode] is in use
24480 2c 20 69 74 20 6d 69 67 68 74 20 62 65 20 74 68  , it might be th
24490 65 0a 2a 2a 20 63 61 73 65 20 74 68 61 74 20 61  e.** case that a
244a0 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 6f 63   second error oc
244b0 63 75 72 73 20 6f 6e 20 61 20 73 65 70 61 72 61  curs on a separa
244c0 74 65 20 74 68 72 65 61 64 20 69 6e 20 62 65 74  te thread in bet
244d0 77 65 65 6e 0a 2a 2a 20 74 68 65 20 74 69 6d 65  ween.** the time
244e0 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 65 72   of the first er
244f0 72 6f 72 20 61 6e 64 20 74 68 65 20 63 61 6c 6c  ror and the call
24500 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66   to these interf
24510 61 63 65 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 68  aces..** When th
24520 61 74 20 68 61 70 70 65 6e 73 2c 20 74 68 65 20  at happens, the 
24530 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 77 69 6c  second error wil
24540 6c 20 62 65 20 72 65 70 6f 72 74 65 64 20 73 69  l be reported si
24550 6e 63 65 20 74 68 65 73 65 0a 2a 2a 20 69 6e 74  nce these.** int
24560 65 72 66 61 63 65 73 20 61 6c 77 61 79 73 20 72  erfaces always r
24570 65 70 6f 72 74 20 74 68 65 20 6d 6f 73 74 20 72  eport the most r
24580 65 63 65 6e 74 20 72 65 73 75 6c 74 2e 20 20 54  ecent result.  T
24590 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68 69 73 2c  o avoid.** this,
245a0 20 65 61 63 68 20 74 68 72 65 61 64 20 63 61 6e   each thread can
245b0 20 6f 62 74 61 69 6e 20 65 78 63 6c 75 73 69 76   obtain exclusiv
245c0 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b 64 61  e use of the [da
245d0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
245e0 6e 5d 20 44 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b  n] D.** by invok
245f0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  ing [sqlite3_mut
24600 65 78 5f 65 6e 74 65 72 5d 28 5b 73 71 6c 69 74  ex_enter]([sqlit
24610 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29  e3_db_mutex](D))
24620 20 62 65 66 6f 72 65 20 62 65 67 69 6e 6e 69 6e   before beginnin
24630 67 0a 2a 2a 20 74 6f 20 75 73 65 20 44 20 61 6e  g.** to use D an
24640 64 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69  d invoking [sqli
24650 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 5d  te3_mutex_leave]
24660 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74  ([sqlite3_db_mut
24670 65 78 5d 28 44 29 29 20 61 66 74 65 72 0a 2a 2a  ex](D)) after.**
24680 20 61 6c 6c 20 63 61 6c 6c 73 20 74 6f 20 74 68   all calls to th
24690 65 20 69 6e 74 65 72 66 61 63 65 73 20 6c 69 73  e interfaces lis
246a0 74 65 64 20 68 65 72 65 20 61 72 65 20 63 6f 6d  ted here are com
246b0 70 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66  pleted..**.** If
246c0 20 61 6e 20 69 6e 74 65 72 66 61 63 65 20 66 61   an interface fa
246d0 69 6c 73 20 77 69 74 68 20 53 51 4c 49 54 45 5f  ils with SQLITE_
246e0 4d 49 53 55 53 45 2c 20 74 68 61 74 20 6d 65 61  MISUSE, that mea
246f0 6e 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  ns the interface
24700 0a 2a 2a 20 77 61 73 20 69 6e 76 6f 6b 65 64 20  .** was invoked 
24710 69 6e 63 6f 72 72 65 63 74 6c 79 20 62 79 20 74  incorrectly by t
24720 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20  he application. 
24730 20 49 6e 20 74 68 61 74 20 63 61 73 65 2c 20 74   In that case, t
24740 68 65 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65  he.** error code
24750 20 61 6e 64 20 6d 65 73 73 61 67 65 20 6d 61 79   and message may
24760 20 6f 72 20 6d 61 79 20 6e 6f 74 20 62 65 20 73   or may not be s
24770 65 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  et..*/.int sqlit
24780 65 33 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74  e3_errcode(sqlit
24790 65 33 20 2a 64 62 29 3b 0a 69 6e 74 20 73 71 6c  e3 *db);.int sql
247a0 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72  ite3_extended_er
247b0 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64  rcode(sqlite3 *d
247c0 62 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  b);.const char *
247d0 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 73  sqlite3_errmsg(s
247e0 71 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e 73 74 20  qlite3*);.const 
247f0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 65 72  void *sqlite3_er
24800 72 6d 73 67 31 36 28 73 71 6c 69 74 65 33 2a 29  rmsg16(sqlite3*)
24810 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  ;.const char *sq
24820 6c 69 74 65 33 5f 65 72 72 73 74 72 28 69 6e 74  lite3_errstr(int
24830 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
24840 45 46 3a 20 53 51 4c 20 53 74 61 74 65 6d 65 6e  EF: SQL Statemen
24850 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57  t Object.** KEYW
24860 4f 52 44 53 3a 20 7b 70 72 65 70 61 72 65 64 20  ORDS: {prepared 
24870 73 74 61 74 65 6d 65 6e 74 7d 20 7b 70 72 65 70  statement} {prep
24880 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 7d  ared statements}
24890 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e  .**.** An instan
248a0 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63  ce of this objec
248b0 74 20 72 65 70 72 65 73 65 6e 74 73 20 61 20 73  t represents a s
248c0 69 6e 67 6c 65 20 53 51 4c 20 73 74 61 74 65 6d  ingle SQL statem
248d0 65 6e 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a  ent..** This obj
248e0 65 63 74 20 69 73 20 76 61 72 69 6f 75 73 6c 79  ect is variously
248f0 20 6b 6e 6f 77 6e 20 61 73 20 61 20 22 70 72 65   known as a "pre
24900 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 22  pared statement"
24910 20 6f 72 20 61 0a 2a 2a 20 22 63 6f 6d 70 69 6c   or a.** "compil
24920 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ed SQL statement
24930 22 20 6f 72 20 73 69 6d 70 6c 79 20 61 73 20 61  " or simply as a
24940 20 22 73 74 61 74 65 6d 65 6e 74 22 2e 0a 2a 2a   "statement"..**
24950 0a 2a 2a 20 54 68 65 20 6c 69 66 65 20 6f 66 20  .** The life of 
24960 61 20 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65  a statement obje
24970 63 74 20 67 6f 65 73 20 73 6f 6d 65 74 68 69 6e  ct goes somethin
24980 67 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a  g like this:.**.
24990 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ol>.** <li> 
249a0 43 72 65 61 74 65 20 74 68 65 20 6f 62 6a 65 63  Create the objec
249b0 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  t using [sqlite3
249c0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
249d0 72 20 61 20 72 65 6c 61 74 65 64 0a 2a 2a 20 20  r a related.**  
249e0 20 20 20 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a      function..**
249f0 20 3c 6c 69 3e 20 42 69 6e 64 20 76 61 6c 75 65   <li> Bind value
24a00 73 20 74 6f 20 5b 68 6f 73 74 20 70 61 72 61 6d  s to [host param
24a10 65 74 65 72 73 5d 20 75 73 69 6e 67 20 74 68 65  eters] using the
24a20 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28   sqlite3_bind_*(
24a30 29 0a 2a 2a 20 20 20 20 20 20 69 6e 74 65 72 66  ).**      interf
24a40 61 63 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 75  aces..** <li> Ru
24a50 6e 20 74 68 65 20 53 51 4c 20 62 79 20 63 61 6c  n the SQL by cal
24a60 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74  ling [sqlite3_st
24a70 65 70 28 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f 72  ep()] one or mor
24a80 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e  e times..** <li>
24a90 20 52 65 73 65 74 20 74 68 65 20 73 74 61 74 65   Reset the state
24aa0 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69  ment using [sqli
24ab0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74 68 65  te3_reset()] the
24ac0 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a 20 20 20 20  n go back.**    
24ad0 20 20 74 6f 20 73 74 65 70 20 32 2e 20 20 44 6f    to step 2.  Do
24ae0 20 74 68 69 73 20 7a 65 72 6f 20 6f 72 20 6d 6f   this zero or mo
24af0 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69  re times..** <li
24b00 3e 20 44 65 73 74 72 6f 79 20 74 68 65 20 6f 62  > Destroy the ob
24b10 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69  ject using [sqli
24b20 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e  te3_finalize()].
24b30 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ol>.**.** 
24b40 52 65 66 65 72 20 74 6f 20 64 6f 63 75 6d 65 6e  Refer to documen
24b50 74 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69  tation on indivi
24b60 64 75 61 6c 20 6d 65 74 68 6f 64 73 20 61 62 6f  dual methods abo
24b70 76 65 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  ve for additiona
24b80 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  l.** information
24b90 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
24ba0 75 63 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  uct sqlite3_stmt
24bb0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 3b 0a 0a   sqlite3_stmt;..
24bc0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
24bd0 52 75 6e 2d 74 69 6d 65 20 4c 69 6d 69 74 73 0a  Run-time Limits.
24be0 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 69 6e 74  **.** ^(This int
24bf0 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 20 74 68  erface allows th
24c00 65 20 73 69 7a 65 20 6f 66 20 76 61 72 69 6f 75  e size of variou
24c10 73 20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20  s constructs to 
24c20 62 65 20 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e  be limited.** on
24c30 20 61 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 79   a connection by
24c40 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69   connection basi
24c50 73 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 61  s.  The first pa
24c60 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a  rameter is the.*
24c70 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
24c80 65 63 74 69 6f 6e 5d 20 77 68 6f 73 65 20 6c 69  ection] whose li
24c90 6d 69 74 20 69 73 20 74 6f 20 62 65 20 73 65 74  mit is to be set
24ca0 20 6f 72 20 71 75 65 72 69 65 64 2e 20 20 54 68   or queried.  Th
24cb0 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61  e.** second para
24cc0 6d 65 74 65 72 20 69 73 20 6f 6e 65 20 6f 66 20  meter is one of 
24cd0 74 68 65 20 5b 6c 69 6d 69 74 20 63 61 74 65 67  the [limit categ
24ce0 6f 72 69 65 73 5d 20 74 68 61 74 20 64 65 66 69  ories] that defi
24cf0 6e 65 20 61 0a 2a 2a 20 63 6c 61 73 73 20 6f 66  ne a.** class of
24d00 20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62   constructs to b
24d10 65 20 73 69 7a 65 20 6c 69 6d 69 74 65 64 2e 20  e size limited. 
24d20 20 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   The third param
24d30 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 6e  eter is the.** n
24d40 65 77 20 6c 69 6d 69 74 20 66 6f 72 20 74 68 61  ew limit for tha
24d50 74 20 63 6f 6e 73 74 72 75 63 74 2e 29 5e 0a 2a  t construct.)^.*
24d60 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e 65 77  *.** ^If the new
24d70 20 6c 69 6d 69 74 20 69 73 20 61 20 6e 65 67 61   limit is a nega
24d80 74 69 76 65 20 6e 75 6d 62 65 72 2c 20 74 68 65  tive number, the
24d90 20 6c 69 6d 69 74 20 69 73 20 75 6e 63 68 61 6e   limit is unchan
24da0 67 65 64 2e 0a 2a 2a 20 5e 28 46 6f 72 20 65 61  ged..** ^(For ea
24db0 63 68 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72  ch limit categor
24dc0 79 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 3c  y SQLITE_LIMIT_<
24dd0 69 3e 4e 41 4d 45 3c 2f 69 3e 20 74 68 65 72 65  i>NAME</i> there
24de0 20 69 73 20 61 20 0a 2a 2a 20 5b 6c 69 6d 69 74   is a .** [limit
24df0 73 20 7c 20 68 61 72 64 20 75 70 70 65 72 20 62  s | hard upper b
24e00 6f 75 6e 64 5d 0a 2a 2a 20 73 65 74 20 61 74 20  ound].** set at 
24e10 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 62 79 20  compile-time by 
24e20 61 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72  a C preprocessor
24e30 20 6d 61 63 72 6f 20 63 61 6c 6c 65 64 0a 2a 2a   macro called.**
24e40 20 5b 6c 69 6d 69 74 73 20 7c 20 53 51 4c 49 54   [limits | SQLIT
24e50 45 5f 4d 41 58 5f 3c 69 3e 4e 41 4d 45 3c 2f 69  E_MAX_<i>NAME</i
24e60 3e 5d 2e 0a 2a 2a 20 28 54 68 65 20 22 5f 4c 49  >]..** (The "_LI
24e70 4d 49 54 5f 22 20 69 6e 20 74 68 65 20 6e 61 6d  MIT_" in the nam
24e80 65 20 69 73 20 63 68 61 6e 67 65 64 20 74 6f 20  e is changed to 
24e90 22 5f 4d 41 58 5f 22 2e 29 29 5e 0a 2a 2a 20 5e  "_MAX_".))^.** ^
24ea0 41 74 74 65 6d 70 74 73 20 74 6f 20 69 6e 63 72  Attempts to incr
24eb0 65 61 73 65 20 61 20 6c 69 6d 69 74 20 61 62 6f  ease a limit abo
24ec0 76 65 20 69 74 73 20 68 61 72 64 20 75 70 70 65  ve its hard uppe
24ed0 72 20 62 6f 75 6e 64 20 61 72 65 0a 2a 2a 20 73  r bound are.** s
24ee0 69 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61 74 65  ilently truncate
24ef0 64 20 74 6f 20 74 68 65 20 68 61 72 64 20 75 70  d to the hard up
24f00 70 65 72 20 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a  per bound..**.**
24f10 20 5e 52 65 67 61 72 64 6c 65 73 73 20 6f 66 20   ^Regardless of 
24f20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74  whether or not t
24f30 68 65 20 6c 69 6d 69 74 20 77 61 73 20 63 68 61  he limit was cha
24f40 6e 67 65 64 2c 20 74 68 65 20 0a 2a 2a 20 5b 73  nged, the .** [s
24f50 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 20  qlite3_limit()] 
24f60 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
24f70 73 20 74 68 65 20 70 72 69 6f 72 20 76 61 6c 75  s the prior valu
24f80 65 20 6f 66 20 74 68 65 20 6c 69 6d 69 74 2e 0a  e of the limit..
24f90 2a 2a 20 5e 48 65 6e 63 65 2c 20 74 6f 20 66 69  ** ^Hence, to fi
24fa0 6e 64 20 74 68 65 20 63 75 72 72 65 6e 74 20 76  nd the current v
24fb0 61 6c 75 65 20 6f 66 20 61 20 6c 69 6d 69 74 20  alue of a limit 
24fc0 77 69 74 68 6f 75 74 20 63 68 61 6e 67 69 6e 67  without changing
24fd0 20 69 74 2c 0a 2a 2a 20 73 69 6d 70 6c 79 20 69   it,.** simply i
24fe0 6e 76 6f 6b 65 20 74 68 69 73 20 69 6e 74 65 72  nvoke this inter
24ff0 66 61 63 65 20 77 69 74 68 20 74 68 65 20 74 68  face with the th
25000 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 73 65  ird parameter se
25010 74 20 74 6f 20 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52  t to -1..**.** R
25020 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 73 20 61  un-time limits a
25030 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20  re intended for 
25040 75 73 65 20 69 6e 20 61 70 70 6c 69 63 61 74 69  use in applicati
25050 6f 6e 73 20 74 68 61 74 20 6d 61 6e 61 67 65 0a  ons that manage.
25060 2a 2a 20 62 6f 74 68 20 74 68 65 69 72 20 6f 77  ** both their ow
25070 6e 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62  n internal datab
25080 61 73 65 20 61 6e 64 20 61 6c 73 6f 20 64 61 74  ase and also dat
25090 61 62 61 73 65 73 20 74 68 61 74 20 61 72 65 20  abases that are 
250a0 63 6f 6e 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79  controlled.** by
250b0 20 75 6e 74 72 75 73 74 65 64 20 65 78 74 65 72   untrusted exter
250c0 6e 61 6c 20 73 6f 75 72 63 65 73 2e 20 20 41 6e  nal sources.  An
250d0 20 65 78 61 6d 70 6c 65 20 61 70 70 6c 69 63 61   example applica
250e0 74 69 6f 6e 20 6d 69 67 68 74 20 62 65 20 61 0a  tion might be a.
250f0 2a 2a 20 77 65 62 20 62 72 6f 77 73 65 72 20 74  ** web browser t
25100 68 61 74 20 68 61 73 20 69 74 73 20 6f 77 6e 20  hat has its own 
25110 64 61 74 61 62 61 73 65 73 20 66 6f 72 20 73 74  databases for st
25120 6f 72 69 6e 67 20 68 69 73 74 6f 72 79 20 61 6e  oring history an
25130 64 0a 2a 2a 20 73 65 70 61 72 61 74 65 20 64 61  d.** separate da
25140 74 61 62 61 73 65 73 20 63 6f 6e 74 72 6f 6c 6c  tabases controll
25150 65 64 20 62 79 20 4a 61 76 61 53 63 72 69 70 74  ed by JavaScript
25160 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 64 6f   applications do
25170 77 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66 66 20  wnloaded.** off 
25180 74 68 65 20 49 6e 74 65 72 6e 65 74 2e 20 20 54  the Internet.  T
25190 68 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61  he internal data
251a0 62 61 73 65 73 20 63 61 6e 20 62 65 20 67 69 76  bases can be giv
251b0 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 72 67 65 2c  en the.** large,
251c0 20 64 65 66 61 75 6c 74 20 6c 69 6d 69 74 73 2e   default limits.
251d0 20 20 44 61 74 61 62 61 73 65 73 20 6d 61 6e 61    Databases mana
251e0 67 65 64 20 62 79 20 65 78 74 65 72 6e 61 6c 20  ged by external 
251f0 73 6f 75 72 63 65 73 20 63 61 6e 0a 2a 2a 20 62  sources can.** b
25200 65 20 67 69 76 65 6e 20 6d 75 63 68 20 73 6d 61  e given much sma
25210 6c 6c 65 72 20 6c 69 6d 69 74 73 20 64 65 73 69  ller limits desi
25220 67 6e 65 64 20 74 6f 20 70 72 65 76 65 6e 74 20  gned to prevent 
25230 61 20 64 65 6e 69 61 6c 20 6f 66 20 73 65 72 76  a denial of serv
25240 69 63 65 0a 2a 2a 20 61 74 74 61 63 6b 2e 20 20  ice.** attack.  
25250 44 65 76 65 6c 6f 70 65 72 73 20 6d 69 67 68 74  Developers might
25260 20 61 6c 73 6f 20 77 61 6e 74 20 74 6f 20 75 73   also want to us
25270 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  e the [sqlite3_s
25280 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d  et_authorizer()]
25290 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 74 6f  .** interface to
252a0 20 66 75 72 74 68 65 72 20 63 6f 6e 74 72 6f 6c   further control
252b0 20 75 6e 74 72 75 73 74 65 64 20 53 51 4c 2e 20   untrusted SQL. 
252c0 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   The size of the
252d0 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 72 65   database.** cre
252e0 61 74 65 64 20 62 79 20 61 6e 20 75 6e 74 72 75  ated by an untru
252f0 73 74 65 64 20 73 63 72 69 70 74 20 63 61 6e 20  sted script can 
25300 62 65 20 63 6f 6e 74 61 69 6e 65 64 20 75 73 69  be contained usi
25310 6e 67 20 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70  ng the.** [max_p
25320 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47  age_count] [PRAG
25330 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72  MA]..**.** New r
25340 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 20 63 61  un-time limit ca
25350 74 65 67 6f 72 69 65 73 20 6d 61 79 20 62 65 20  tegories may be 
25360 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
25370 72 65 6c 65 61 73 65 73 2e 0a 2a 2f 0a 69 6e 74  releases..*/.int
25380 20 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 73   sqlite3_limit(s
25390 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 69 64 2c  qlite3*, int id,
253a0 20 69 6e 74 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f   int newVal);../
253b0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
253c0 75 6e 2d 54 69 6d 65 20 4c 69 6d 69 74 20 43 61  un-Time Limit Ca
253d0 74 65 67 6f 72 69 65 73 0a 2a 2a 20 4b 45 59 57  tegories.** KEYW
253e0 4f 52 44 53 3a 20 7b 6c 69 6d 69 74 20 63 61 74  ORDS: {limit cat
253f0 65 67 6f 72 79 7d 20 7b 2a 6c 69 6d 69 74 20 63  egory} {*limit c
25400 61 74 65 67 6f 72 69 65 73 7d 0a 2a 2a 0a 2a 2a  ategories}.**.**
25410 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73   These constants
25420 20 64 65 66 69 6e 65 20 76 61 72 69 6f 75 73 20   define various 
25430 70 65 72 66 6f 72 6d 61 6e 63 65 20 6c 69 6d 69  performance limi
25440 74 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62  ts.** that can b
25450 65 20 6c 6f 77 65 72 65 64 20 61 74 20 72 75 6e  e lowered at run
25460 2d 74 69 6d 65 20 75 73 69 6e 67 20 5b 73 71 6c  -time using [sql
25470 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 2e 0a 2a  ite3_limit()]..*
25480 2a 20 54 68 65 20 73 79 6e 6f 70 73 69 73 20 6f  * The synopsis o
25490 66 20 74 68 65 20 6d 65 61 6e 69 6e 67 73 20 6f  f the meanings o
254a0 66 20 74 68 65 20 76 61 72 69 6f 75 73 20 6c 69  f the various li
254b0 6d 69 74 73 20 69 73 20 73 68 6f 77 6e 20 62 65  mits is shown be
254c0 6c 6f 77 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e  low..** Addition
254d0 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69  al information i
254e0 73 20 61 76 61 69 6c 61 62 6c 65 20 61 74 20 5b  s available at [
254f0 6c 69 6d 69 74 73 20 7c 20 4c 69 6d 69 74 73 20  limits | Limits 
25500 69 6e 20 53 51 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a  in SQLite]..**.*
25510 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49  * <dl>.** [[SQLI
25520 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 5d  TE_LIMIT_LENGTH]
25530 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  ] ^(<dt>SQLITE_L
25540 49 4d 49 54 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e  IMIT_LENGTH</dt>
25550 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
25560 6d 75 6d 20 73 69 7a 65 20 6f 66 20 61 6e 79 20  mum size of any 
25570 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 6f  string or BLOB o
25580 72 20 74 61 62 6c 65 20 72 6f 77 2c 20 69 6e 20  r table row, in 
25590 62 79 74 65 73 2e 3c 64 64 3e 29 5e 0a 2a 2a 0a  bytes.<dd>)^.**.
255a0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
255b0 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 5d 5d 20 5e  T_SQL_LENGTH]] ^
255c0 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
255d0 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 3c 2f 64 74  T_SQL_LENGTH</dt
255e0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
255f0 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 61  imum length of a
25600 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  n SQL statement,
25610 20 69 6e 20 62 79 74 65 73 2e 3c 2f 64 64 3e 29   in bytes.</dd>)
25620 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
25630 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 5d 5d 20  _LIMIT_COLUMN]] 
25640 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
25650 49 54 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a  IT_COLUMN</dt>.*
25660 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
25670 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  m number of colu
25680 6d 6e 73 20 69 6e 20 61 20 74 61 62 6c 65 20 64  mns in a table d
25690 65 66 69 6e 69 74 69 6f 6e 20 6f 72 20 69 6e 20  efinition or in 
256a0 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 73 65  the.** result se
256b0 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20  t of a [SELECT] 
256c0 6f 72 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e  or the maximum n
256d0 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
256e0 20 69 6e 20 61 6e 20 69 6e 64 65 78 0a 2a 2a 20   in an index.** 
256f0 6f 72 20 69 6e 20 61 6e 20 4f 52 44 45 52 20 42  or in an ORDER B
25700 59 20 6f 72 20 47 52 4f 55 50 20 42 59 20 63 6c  Y or GROUP BY cl
25710 61 75 73 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  ause.</dd>)^.**.
25720 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
25730 54 5f 45 58 50 52 5f 44 45 50 54 48 5d 5d 20 5e  T_EXPR_DEPTH]] ^
25740 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
25750 54 5f 45 58 50 52 5f 44 45 50 54 48 3c 2f 64 74  T_EXPR_DEPTH</dt
25760 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
25770 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 74 68  imum depth of th
25780 65 20 70 61 72 73 65 20 74 72 65 65 20 6f 6e 20  e parse tree on 
25790 61 6e 79 20 65 78 70 72 65 73 73 69 6f 6e 2e 3c  any expression.<
257a0 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  /dd>)^.**.** [[S
257b0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50  QLITE_LIMIT_COMP
257c0 4f 55 4e 44 5f 53 45 4c 45 43 54 5d 5d 20 5e 28  OUND_SELECT]] ^(
257d0 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
257e0 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54  _COMPOUND_SELECT
257f0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
25800 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
25810 6f 66 20 74 65 72 6d 73 20 69 6e 20 61 20 63 6f  of terms in a co
25820 6d 70 6f 75 6e 64 20 53 45 4c 45 43 54 20 73 74  mpound SELECT st
25830 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 29 5e 0a  atement.</dd>)^.
25840 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
25850 49 4d 49 54 5f 56 44 42 45 5f 4f 50 5d 5d 20 5e  IMIT_VDBE_OP]] ^
25860 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
25870 54 5f 56 44 42 45 5f 4f 50 3c 2f 64 74 3e 0a 2a  T_VDBE_OP</dt>.*
25880 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
25890 6d 20 6e 75 6d 62 65 72 20 6f 66 20 69 6e 73 74  m number of inst
258a0 72 75 63 74 69 6f 6e 73 20 69 6e 20 61 20 76 69  ructions in a vi
258b0 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 70 72  rtual machine pr
258c0 6f 67 72 61 6d 0a 2a 2a 20 75 73 65 64 20 74 6f  ogram.** used to
258d0 20 69 6d 70 6c 65 6d 65 6e 74 20 61 6e 20 53 51   implement an SQ
258e0 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 54 68  L statement.  Th
258f0 69 73 20 6c 69 6d 69 74 20 69 73 20 6e 6f 74 20  is limit is not 
25900 63 75 72 72 65 6e 74 6c 79 0a 2a 2a 20 65 6e 66  currently.** enf
25910 6f 72 63 65 64 2c 20 74 68 6f 75 67 68 20 74 68  orced, though th
25920 61 74 20 6d 69 67 68 74 20 62 65 20 61 64 64 65  at might be adde
25930 64 20 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65  d in some future
25940 20 72 65 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53   release of.** S
25950 51 4c 69 74 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  QLite.</dd>)^.**
25960 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
25970 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d  IT_FUNCTION_ARG]
25980 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  ] ^(<dt>SQLITE_L
25990 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52  IMIT_FUNCTION_AR
259a0 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  G</dt>.** <dd>Th
259b0 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
259c0 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 6f 6e   of arguments on
259d0 20 61 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64   a function.</dd
259e0 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
259f0 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45  TE_LIMIT_ATTACHE
25a00 44 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  D]] ^(<dt>SQLITE
25a10 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 3c  _LIMIT_ATTACHED<
25a20 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
25a30 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
25a40 66 20 5b 41 54 54 41 43 48 20 7c 20 61 74 74 61  f [ATTACH | atta
25a50 63 68 65 64 20 64 61 74 61 62 61 73 65 73 5d 2e  ched databases].
25a60 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  )^</dd>.**.** [[
25a70 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b  SQLITE_LIMIT_LIK
25a80 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48  E_PATTERN_LENGTH
25a90 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49  ]].** ^(<dt>SQLI
25aa0 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41  TE_LIMIT_LIKE_PA
25ab0 54 54 45 52 4e 5f 4c 45 4e 47 54 48 3c 2f 64 74  TTERN_LENGTH</dt
25ac0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
25ad0 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 74  imum length of t
25ae0 68 65 20 70 61 74 74 65 72 6e 20 61 72 67 75 6d  he pattern argum
25af0 65 6e 74 20 74 6f 20 74 68 65 20 5b 4c 49 4b 45  ent to the [LIKE
25b00 5d 20 6f 72 0a 2a 2a 20 5b 47 4c 4f 42 5d 20 6f  ] or.** [GLOB] o
25b10 70 65 72 61 74 6f 72 73 2e 3c 2f 64 64 3e 29 5e  perators.</dd>)^
25b20 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
25b30 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e  LIMIT_VARIABLE_N
25b40 55 4d 42 45 52 5d 5d 0a 2a 2a 20 5e 28 3c 64 74  UMBER]].** ^(<dt
25b50 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41  >SQLITE_LIMIT_VA
25b60 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64  RIABLE_NUMBER</d
25b70 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
25b80 78 69 6d 75 6d 20 69 6e 64 65 78 20 6e 75 6d 62  ximum index numb
25b90 65 72 20 6f 66 20 61 6e 79 20 5b 70 61 72 61 6d  er of any [param
25ba0 65 74 65 72 5d 20 69 6e 20 61 6e 20 53 51 4c 20  eter] in an SQL 
25bb0 73 74 61 74 65 6d 65 6e 74 2e 29 5e 0a 2a 2a 0a  statement.)^.**.
25bc0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
25bd0 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 5d  T_TRIGGER_DEPTH]
25be0 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  ] ^(<dt>SQLITE_L
25bf0 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50  IMIT_TRIGGER_DEP
25c00 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  TH</dt>.** <dd>T
25c10 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68  he maximum depth
25c20 20 6f 66 20 72 65 63 75 72 73 69 6f 6e 20 66 6f   of recursion fo
25c30 72 20 74 72 69 67 67 65 72 73 2e 3c 2f 64 64 3e  r triggers.</dd>
25c40 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23  )^.** </dl>.*/.#
25c50 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
25c60 4d 49 54 5f 4c 45 4e 47 54 48 20 20 20 20 20 20  MIT_LENGTH      
25c70 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 0a                0.
25c80 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
25c90 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 20  IMIT_SQL_LENGTH 
25ca0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31                 1
25cb0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
25cc0 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 20 20 20 20  LIMIT_COLUMN    
25cd0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
25ce0 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
25cf0 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54  _LIMIT_EXPR_DEPT
25d00 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  H               
25d10 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   3.#define SQLIT
25d20 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44  E_LIMIT_COMPOUND
25d30 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20 20 20  _SELECT         
25d40 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    4.#define SQLI
25d50 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50  TE_LIMIT_VDBE_OP
25d60 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
25d70 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c     5.#define SQL
25d80 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49  ITE_LIMIT_FUNCTI
25d90 4f 4e 5f 41 52 47 20 20 20 20 20 20 20 20 20 20  ON_ARG          
25da0 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20 53 51      6.#define SQ
25db0 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43  LITE_LIMIT_ATTAC
25dc0 48 45 44 20 20 20 20 20 20 20 20 20 20 20 20 20  HED             
25dd0 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65 20 53       7.#define S
25de0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45  QLITE_LIMIT_LIKE
25df0 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 20  _PATTERN_LENGTH 
25e00 20 20 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20        8.#define 
25e10 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52  SQLITE_LIMIT_VAR
25e20 49 41 42 4c 45 5f 4e 55 4d 42 45 52 20 20 20 20  IABLE_NUMBER    
25e30 20 20 20 20 20 20 20 39 0a 23 64 65 66 69 6e 65         9.#define
25e40 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52   SQLITE_LIMIT_TR
25e50 49 47 47 45 52 5f 44 45 50 54 48 20 20 20 20 20  IGGER_DEPTH     
25e60 20 20 20 20 20 20 20 31 30 0a 0a 2f 2a 0a 2a 2a         10../*.**
25e70 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69   CAPI3REF: Compi
25e80 6c 69 6e 67 20 41 6e 20 53 51 4c 20 53 74 61 74  ling An SQL Stat
25e90 65 6d 65 6e 74 0a 2a 2a 20 4b 45 59 57 4f 52 44  ement.** KEYWORD
25ea0 53 3a 20 7b 53 51 4c 20 73 74 61 74 65 6d 65 6e  S: {SQL statemen
25eb0 74 20 63 6f 6d 70 69 6c 65 72 7d 0a 2a 2a 0a 2a  t compiler}.**.*
25ec0 2a 20 54 6f 20 65 78 65 63 75 74 65 20 61 6e 20  * To execute an 
25ed0 53 51 4c 20 71 75 65 72 79 2c 20 69 74 20 6d 75  SQL query, it mu
25ee0 73 74 20 66 69 72 73 74 20 62 65 20 63 6f 6d 70  st first be comp
25ef0 69 6c 65 64 20 69 6e 74 6f 20 61 20 62 79 74 65  iled into a byte
25f00 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f 67 72 61 6d  -code.** program
25f10 20 75 73 69 6e 67 20 6f 6e 65 20 6f 66 20 74 68   using one of th
25f20 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a  ese routines..**
25f30 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72  .** The first ar
25f40 67 75 6d 65 6e 74 2c 20 22 64 62 22 2c 20 69 73  gument, "db", is
25f50 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e   a [database con
25f60 6e 65 63 74 69 6f 6e 5d 20 6f 62 74 61 69 6e 65  nection] obtaine
25f70 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 70 72 69 6f  d from a.** prio
25f80 72 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c  r successful cal
25f90 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70  l to [sqlite3_op
25fa0 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  en()], [sqlite3_
25fb0 6f 70 65 6e 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a  open_v2()] or.**
25fc0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
25fd0 28 29 5d 2e 20 20 54 68 65 20 64 61 74 61 62 61  ()].  The databa
25fe0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75  se connection mu
25ff0 73 74 20 6e 6f 74 20 68 61 76 65 20 62 65 65 6e  st not have been
26000 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54   closed..**.** T
26010 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
26020 6e 74 2c 20 22 7a 53 71 6c 22 2c 20 69 73 20 74  nt, "zSql", is t
26030 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20  he statement to 
26040 62 65 20 63 6f 6d 70 69 6c 65 64 2c 20 65 6e 63  be compiled, enc
26050 6f 64 65 64 0a 2a 2a 20 61 73 20 65 69 74 68 65  oded.** as eithe
26060 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31  r UTF-8 or UTF-1
26070 36 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  6.  The sqlite3_
26080 70 72 65 70 61 72 65 28 29 20 61 6e 64 20 73 71  prepare() and sq
26090 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
260a0 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  ().** interfaces
260b0 20 75 73 65 20 55 54 46 2d 38 2c 20 61 6e 64 20   use UTF-8, and 
260c0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
260d0 36 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  6() and sqlite3_
260e0 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 0a 2a  prepare16_v2().*
260f0 2a 20 75 73 65 20 55 54 46 2d 31 36 2e 0a 2a 2a  * use UTF-16..**
26100 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e 42 79 74  .** ^If the nByt
26110 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6c 65  e argument is le
26120 73 73 20 74 68 61 6e 20 7a 65 72 6f 2c 20 74 68  ss than zero, th
26130 65 6e 20 7a 53 71 6c 20 69 73 20 72 65 61 64 20  en zSql is read 
26140 75 70 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 72  up to the.** fir
26150 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  st zero terminat
26160 6f 72 2e 20 5e 49 66 20 6e 42 79 74 65 20 69 73  or. ^If nByte is
26170 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74   non-negative, t
26180 68 65 6e 20 69 74 20 69 73 20 74 68 65 20 6d 61  hen it is the ma
26190 78 69 6d 75 6d 0a 2a 2a 20 6e 75 6d 62 65 72 20  ximum.** number 
261a0 6f 66 20 20 62 79 74 65 73 20 72 65 61 64 20 66  of  bytes read f
261b0 72 6f 6d 20 7a 53 71 6c 2e 20 20 5e 57 68 65 6e  rom zSql.  ^When
261c0 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65   nByte is non-ne
261d0 67 61 74 69 76 65 2c 20 74 68 65 0a 2a 2a 20 7a  gative, the.** z
261e0 53 71 6c 20 73 74 72 69 6e 67 20 65 6e 64 73 20  Sql string ends 
261f0 61 74 20 65 69 74 68 65 72 20 74 68 65 20 66 69  at either the fi
26200 72 73 74 20 27 5c 30 30 30 27 20 6f 72 20 27 5c  rst '\000' or '\
26210 75 30 30 30 30 27 20 63 68 61 72 61 63 74 65 72  u0000' character
26220 20 6f 72 0a 2a 2a 20 74 68 65 20 6e 42 79 74 65   or.** the nByte
26230 2d 74 68 20 62 79 74 65 2c 20 77 68 69 63 68 65  -th byte, whiche
26240 76 65 72 20 63 6f 6d 65 73 20 66 69 72 73 74 2e  ver comes first.
26250 20 49 66 20 74 68 65 20 63 61 6c 6c 65 72 20 6b   If the caller k
26260 6e 6f 77 73 0a 2a 2a 20 74 68 61 74 20 74 68 65  nows.** that the
26270 20 73 75 70 70 6c 69 65 64 20 73 74 72 69 6e 67   supplied string
26280 20 69 73 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74   is nul-terminat
26290 65 64 2c 20 74 68 65 6e 20 74 68 65 72 65 20 69  ed, then there i
262a0 73 20 61 20 73 6d 61 6c 6c 0a 2a 2a 20 70 65 72  s a small.** per
262b0 66 6f 72 6d 61 6e 63 65 20 61 64 76 61 6e 74 61  formance advanta
262c0 67 65 20 74 6f 20 62 65 20 67 61 69 6e 65 64 20  ge to be gained 
262d0 62 79 20 70 61 73 73 69 6e 67 20 61 6e 20 6e 42  by passing an nB
262e0 79 74 65 20 70 61 72 61 6d 65 74 65 72 20 74 68  yte parameter th
262f0 61 74 0a 2a 2a 20 69 73 20 65 71 75 61 6c 20 74  at.** is equal t
26300 6f 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  o the number of 
26310 62 79 74 65 73 20 69 6e 20 74 68 65 20 69 6e 70  bytes in the inp
26320 75 74 20 73 74 72 69 6e 67 20 3c 69 3e 69 6e 63  ut string <i>inc
26330 6c 75 64 69 6e 67 3c 2f 69 3e 0a 2a 2a 20 74 68  luding</i>.** th
26340 65 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 6f 72  e nul-terminator
26350 20 62 79 74 65 73 20 61 73 20 74 68 69 73 20 73   bytes as this s
26360 61 76 65 73 20 53 51 4c 69 74 65 20 66 72 6f 6d  aves SQLite from
26370 20 68 61 76 69 6e 67 20 74 6f 0a 2a 2a 20 6d 61   having to.** ma
26380 6b 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  ke a copy of the
26390 20 69 6e 70 75 74 20 73 74 72 69 6e 67 2e 0a 2a   input string..*
263a0 2a 0a 2a 2a 20 5e 49 66 20 70 7a 54 61 69 6c 20  *.** ^If pzTail 
263b0 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e  is not NULL then
263c0 20 2a 70 7a 54 61 69 6c 20 69 73 20 6d 61 64 65   *pzTail is made
263d0 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68 65   to point to the
263e0 20 66 69 72 73 74 20 62 79 74 65 0a 2a 2a 20 70   first byte.** p
263f0 61 73 74 20 74 68 65 20 65 6e 64 20 6f 66 20 74  ast the end of t
26400 68 65 20 66 69 72 73 74 20 53 51 4c 20 73 74 61  he first SQL sta
26410 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 20  tement in zSql. 
26420 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
26430 6f 6e 6c 79 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20  only.** compile 
26440 74 68 65 20 66 69 72 73 74 20 73 74 61 74 65 6d  the first statem
26450 65 6e 74 20 69 6e 20 7a 53 71 6c 2c 20 73 6f 20  ent in zSql, so 
26460 2a 70 7a 54 61 69 6c 20 69 73 20 6c 65 66 74 20  *pzTail is left 
26470 70 6f 69 6e 74 69 6e 67 20 74 6f 0a 2a 2a 20 77  pointing to.** w
26480 68 61 74 20 72 65 6d 61 69 6e 73 20 75 6e 63 6f  hat remains unco
26490 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 2a  mpiled..**.** ^*
264a0 70 70 53 74 6d 74 20 69 73 20 6c 65 66 74 20 70  ppStmt is left p
264b0 6f 69 6e 74 69 6e 67 20 74 6f 20 61 20 63 6f 6d  ointing to a com
264c0 70 69 6c 65 64 20 5b 70 72 65 70 61 72 65 64 20  piled [prepared 
264d0 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20  statement] that 
264e0 63 61 6e 20 62 65 0a 2a 2a 20 65 78 65 63 75 74  can be.** execut
264f0 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
26500 33 5f 73 74 65 70 28 29 5d 2e 20 20 5e 49 66 20  3_step()].  ^If 
26510 74 68 65 72 65 20 69 73 20 61 6e 20 65 72 72 6f  there is an erro
26520 72 2c 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65  r, *ppStmt is se
26530 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 20 20 5e  t.** to NULL.  ^
26540 49 66 20 74 68 65 20 69 6e 70 75 74 20 74 65 78  If the input tex
26550 74 20 63 6f 6e 74 61 69 6e 73 20 6e 6f 20 53 51  t contains no SQ
26560 4c 20 28 69 66 20 74 68 65 20 69 6e 70 75 74 20  L (if the input 
26570 69 73 20 61 6e 20 65 6d 70 74 79 0a 2a 2a 20 73  is an empty.** s
26580 74 72 69 6e 67 20 6f 72 20 61 20 63 6f 6d 6d 65  tring or a comme
26590 6e 74 29 20 74 68 65 6e 20 2a 70 70 53 74 6d 74  nt) then *ppStmt
265a0 20 69 73 20 73 65 74 20 74 6f 20 4e 55 4c 4c 2e   is set to NULL.
265b0 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 69 6e 67 20  .** The calling 
265c0 70 72 6f 63 65 64 75 72 65 20 69 73 20 72 65 73  procedure is res
265d0 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 64 65 6c  ponsible for del
265e0 65 74 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c  eting the compil
265f0 65 64 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d  ed.** SQL statem
26600 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ent using [sqlit
26610 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 61  e3_finalize()] a
26620 66 74 65 72 20 69 74 20 68 61 73 20 66 69 6e 69  fter it has fini
26630 73 68 65 64 20 77 69 74 68 20 69 74 2e 0a 2a 2a  shed with it..**
26640 20 70 70 53 74 6d 74 20 6d 61 79 20 6e 6f 74 20   ppStmt may not 
26650 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e  be NULL..**.** ^
26660 4f 6e 20 73 75 63 63 65 73 73 2c 20 74 68 65 20  On success, the 
26670 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
26680 29 20 66 61 6d 69 6c 79 20 6f 66 20 72 6f 75 74  ) family of rout
26690 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c  ines return [SQL
266a0 49 54 45 5f 4f 4b 5d 3b 0a 2a 2a 20 6f 74 68 65  ITE_OK];.** othe
266b0 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20  rwise an [error 
266c0 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65  code] is returne
266d0 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  d..**.** The sql
266e0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
266f0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72  ) and sqlite3_pr
26700 65 70 61 72 65 31 36 5f 76 32 28 29 20 69 6e 74  epare16_v2() int
26710 65 72 66 61 63 65 73 20 61 72 65 0a 2a 2a 20 72  erfaces are.** r
26720 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 61  ecommended for a
26730 6c 6c 20 6e 65 77 20 70 72 6f 67 72 61 6d 73 2e  ll new programs.
26740 20 54 68 65 20 74 77 6f 20 6f 6c 64 65 72 20 69   The two older i
26750 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 72 65  nterfaces are re
26760 74 61 69 6e 65 64 0a 2a 2a 20 66 6f 72 20 62 61  tained.** for ba
26770 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62  ckwards compatib
26780 69 6c 69 74 79 2c 20 62 75 74 20 74 68 65 69 72  ility, but their
26790 20 75 73 65 20 69 73 20 64 69 73 63 6f 75 72 61   use is discoura
267a0 67 65 64 2e 0a 2a 2a 20 5e 49 6e 20 74 68 65 20  ged..** ^In the 
267b0 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 73 2c  "v2" interfaces,
267c0 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74   the prepared st
267d0 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 68 61 74 20  atement.** that 
267e0 69 73 20 72 65 74 75 72 6e 65 64 20 28 74 68 65  is returned (the
267f0 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20   [sqlite3_stmt] 
26800 6f 62 6a 65 63 74 29 20 63 6f 6e 74 61 69 6e 73  object) contains
26810 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a   a copy of the.*
26820 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 74  * original SQL t
26830 65 78 74 2e 20 54 68 69 73 20 63 61 75 73 65 73  ext. This causes
26840 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74   the [sqlite3_st
26850 65 70 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  ep()] interface 
26860 74 6f 0a 2a 2a 20 62 65 68 61 76 65 20 64 69 66  to.** behave dif
26870 66 65 72 65 6e 74 6c 79 20 69 6e 20 74 68 72 65  ferently in thre
26880 65 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f  e ways:.**.** <o
26890 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49  l>.** <li>.** ^I
268a0 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 73  f the database s
268b0 63 68 65 6d 61 20 63 68 61 6e 67 65 73 2c 20 69  chema changes, i
268c0 6e 73 74 65 61 64 20 6f 66 20 72 65 74 75 72 6e  nstead of return
268d0 69 6e 67 20 5b 53 51 4c 49 54 45 5f 53 43 48 45  ing [SQLITE_SCHE
268e0 4d 41 5d 20 61 73 20 69 74 0a 2a 2a 20 61 6c 77  MA] as it.** alw
268f0 61 79 73 20 75 73 65 64 20 74 6f 20 64 6f 2c 20  ays used to do, 
26900 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
26910 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61   will automatica
26920 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 20 74 68  lly recompile th
26930 65 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65  e SQL.** stateme
26940 6e 74 20 61 6e 64 20 74 72 79 20 74 6f 20 72 75  nt and try to ru
26950 6e 20 69 74 20 61 67 61 69 6e 2e 20 41 73 20 6d  n it again. As m
26960 61 6e 79 20 61 73 20 5b 53 51 4c 49 54 45 5f 4d  any as [SQLITE_M
26970 41 58 5f 53 43 48 45 4d 41 5f 52 45 54 52 59 5d  AX_SCHEMA_RETRY]
26980 0a 2a 2a 20 72 65 74 72 69 65 73 20 77 69 6c 6c  .** retries will
26990 20 6f 63 63 75 72 20 62 65 66 6f 72 65 20 73 71   occur before sq
269a0 6c 69 74 65 33 5f 73 74 65 70 28 29 20 67 69 76  lite3_step() giv
269b0 65 73 20 75 70 20 61 6e 64 20 72 65 74 75 72 6e  es up and return
269c0 73 20 61 6e 20 65 72 72 6f 72 2e 0a 2a 2a 20 3c  s an error..** <
269d0 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a  /li>.**.** <li>.
269e0 2a 2a 20 5e 57 68 65 6e 20 61 6e 20 65 72 72 6f  ** ^When an erro
269f0 72 20 6f 63 63 75 72 73 2c 20 5b 73 71 6c 69 74  r occurs, [sqlit
26a00 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20  e3_step()] will 
26a10 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 74 68  return one of th
26a20 65 20 64 65 74 61 69 6c 65 64 0a 2a 2a 20 5b 65  e detailed.** [e
26a30 72 72 6f 72 20 63 6f 64 65 73 5d 20 6f 72 20 5b  rror codes] or [
26a40 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63  extended error c
26a50 6f 64 65 73 5d 2e 20 20 5e 54 68 65 20 6c 65 67  odes].  ^The leg
26a60 61 63 79 20 62 65 68 61 76 69 6f 72 20 77 61 73  acy behavior was
26a70 20 74 68 61 74 0a 2a 2a 20 5b 73 71 6c 69 74 65   that.** [sqlite
26a80 33 5f 73 74 65 70 28 29 5d 20 77 6f 75 6c 64 20  3_step()] would 
26a90 6f 6e 6c 79 20 72 65 74 75 72 6e 20 61 20 67 65  only return a ge
26aa0 6e 65 72 69 63 20 5b 53 51 4c 49 54 45 5f 45 52  neric [SQLITE_ER
26ab0 52 4f 52 5d 20 72 65 73 75 6c 74 20 63 6f 64 65  ROR] result code
26ac0 0a 2a 2a 20 61 6e 64 20 74 68 65 20 61 70 70 6c  .** and the appl
26ad0 69 63 61 74 69 6f 6e 20 77 6f 75 6c 64 20 68 61  ication would ha
26ae0 76 65 20 74 6f 20 6d 61 6b 65 20 61 20 73 65 63  ve to make a sec
26af0 6f 6e 64 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ond call to [sql
26b00 69 74 65 33 5f 72 65 73 65 74 28 29 5d 0a 2a 2a  ite3_reset()].**
26b10 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e   in order to fin
26b20 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67  d the underlying
26b30 20 63 61 75 73 65 20 6f 66 20 74 68 65 20 70 72   cause of the pr
26b40 6f 62 6c 65 6d 2e 20 57 69 74 68 20 74 68 65 20  oblem. With the 
26b50 22 76 32 22 20 70 72 65 70 61 72 65 0a 2a 2a 20  "v2" prepare.** 
26b60 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65 20  interfaces, the 
26b70 75 6e 64 65 72 6c 79 69 6e 67 20 72 65 61 73 6f  underlying reaso
26b80 6e 20 66 6f 72 20 74 68 65 20 65 72 72 6f 72 20  n for the error 
26b90 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65  is returned imme
26ba0 64 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69  diately..** </li
26bb0 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20  >.**.** <li>.** 
26bc0 5e 49 66 20 74 68 65 20 73 70 65 63 69 66 69 63  ^If the specific
26bd0 20 76 61 6c 75 65 20 62 6f 75 6e 64 20 74 6f 20   value bound to 
26be0 5b 70 61 72 61 6d 65 74 65 72 20 7c 20 68 6f 73  [parameter | hos
26bf0 74 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20  t parameter] in 
26c00 74 68 65 20 0a 2a 2a 20 57 48 45 52 45 20 63 6c  the .** WHERE cl
26c10 61 75 73 65 20 6d 69 67 68 74 20 69 6e 66 6c 75  ause might influ
26c20 65 6e 63 65 20 74 68 65 20 63 68 6f 69 63 65 20  ence the choice 
26c30 6f 66 20 71 75 65 72 79 20 70 6c 61 6e 20 66 6f  of query plan fo
26c40 72 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 0a 2a  r a statement,.*
26c50 2a 20 74 68 65 6e 20 74 68 65 20 73 74 61 74 65  * then the state
26c60 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 61 75 74  ment will be aut
26c70 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d  omatically recom
26c80 70 69 6c 65 64 2c 20 61 73 20 69 66 20 74 68 65  piled, as if the
26c90 72 65 20 68 61 64 20 62 65 65 6e 20 0a 2a 2a 20  re had been .** 
26ca0 61 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2c  a schema change,
26cb0 20 6f 6e 20 74 68 65 20 66 69 72 73 74 20 20 5b   on the first  [
26cc0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
26cd0 63 61 6c 6c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  call following a
26ce0 6e 79 20 63 68 61 6e 67 65 0a 2a 2a 20 74 6f 20  ny change.** to 
26cf0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  the [sqlite3_bin
26d00 64 5f 74 65 78 74 20 7c 20 62 69 6e 64 69 6e 67  d_text | binding
26d10 73 5d 20 6f 66 20 74 68 61 74 20 5b 70 61 72 61  s] of that [para
26d20 6d 65 74 65 72 5d 2e 20 0a 2a 2a 20 5e 54 68 65  meter]. .** ^The
26d30 20 73 70 65 63 69 66 69 63 20 76 61 6c 75 65 20   specific value 
26d40 6f 66 20 57 48 45 52 45 2d 63 6c 61 75 73 65 20  of WHERE-clause 
26d50 5b 70 61 72 61 6d 65 74 65 72 5d 20 6d 69 67 68  [parameter] migh
26d60 74 20 69 6e 66 6c 75 65 6e 63 65 20 74 68 65 20  t influence the 
26d70 0a 2a 2a 20 63 68 6f 69 63 65 20 6f 66 20 71 75  .** choice of qu
26d80 65 72 79 20 70 6c 61 6e 20 69 66 20 74 68 65 20  ery plan if the 
26d90 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
26da0 20 6c 65 66 74 2d 68 61 6e 64 20 73 69 64 65 20   left-hand side 
26db0 6f 66 20 61 20 5b 4c 49 4b 45 5d 0a 2a 2a 20 6f  of a [LIKE].** o
26dc0 72 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f  r [GLOB] operato
26dd0 72 20 6f 72 20 69 66 20 74 68 65 20 70 61 72 61  r or if the para
26de0 6d 65 74 65 72 20 69 73 20 63 6f 6d 70 61 72 65  meter is compare
26df0 64 20 74 6f 20 61 6e 20 69 6e 64 65 78 65 64 20  d to an indexed 
26e00 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 6e 64 20 74 68  column.** and th
26e10 65 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  e [SQLITE_ENABLE
26e20 5f 53 54 41 54 33 5d 20 63 6f 6d 70 69 6c 65 2d  _STAT3] compile-
26e30 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 65  time option is e
26e40 6e 61 62 6c 65 64 2e 0a 2a 2a 20 3c 2f 6c 69 3e  nabled..** </li>
26e50 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 69 6e 74  .** </ol>.*/.int
26e60 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
26e70 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
26e80 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44              /* D
26e90 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a  atabase handle *
26ea0 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
26eb0 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53  zSql,       /* S
26ec0 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54  QL statement, UT
26ed0 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20  F-8 encoded */. 
26ee0 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20   int nByte,     
26ef0 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69           /* Maxi
26f00 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53  mum length of zS
26f10 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a  ql in bytes. */.
26f20 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a    sqlite3_stmt *
26f30 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54  *ppStmt,  /* OUT
26f40 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64  : Statement hand
26f50 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  le */.  const ch
26f60 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20  ar **pzTail     
26f70 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20  /* OUT: Pointer 
26f80 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f  to unused portio
26f90 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a  n of zSql */.);.
26fa0 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70  int sqlite3_prep
26fb0 61 72 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65  are_v2(.  sqlite
26fc0 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
26fd0 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61    /* Database ha
26fe0 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
26ff0 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20  char *zSql,     
27000 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65    /* SQL stateme
27010 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65  nt, UTF-8 encode
27020 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65  d */.  int nByte
27030 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
27040 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  * Maximum length
27050 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65   of zSql in byte
27060 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  s. */.  sqlite3_
27070 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20  stmt **ppStmt,  
27080 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e  /* OUT: Statemen
27090 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  t handle */.  co
270a0 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69  nst char **pzTai
270b0 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f  l     /* OUT: Po
270c0 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20  inter to unused 
270d0 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20  portion of zSql 
270e0 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  */.);.int sqlite
270f0 33 5f 70 72 65 70 61 72 65 31 36 28 0a 20 20 73  3_prepare16(.  s
27100 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
27110 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
27120 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  se handle */.  c
27130 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c  onst void *zSql,
27140 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74         /* SQL st
27150 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20  atement, UTF-16 
27160 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74  encoded */.  int
27170 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20   nByte,         
27180 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20       /* Maximum 
27190 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69  length of zSql i
271a0 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71  n bytes. */.  sq
271b0 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53  lite3_stmt **ppS
271c0 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74  tmt,  /* OUT: St
271d0 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a  atement handle *
271e0 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  /.  const void *
271f0 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f  *pzTail     /* O
27200 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75  UT: Pointer to u
27210 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66  nused portion of
27220 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20   zSql */.);.int 
27230 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
27240 36 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20  6_v2(.  sqlite3 
27250 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
27260 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64  /* Database hand
27270 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  le */.  const vo
27280 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20  id *zSql,       
27290 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  /* SQL statement
272a0 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64  , UTF-16 encoded
272b0 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c   */.  int nByte,
272c0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
272d0 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   Maximum length 
272e0 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73  of zSql in bytes
272f0 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73  . */.  sqlite3_s
27300 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f  tmt **ppStmt,  /
27310 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74  * OUT: Statement
27320 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
27330 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c  st void **pzTail
27340 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69       /* OUT: Poi
27350 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70  nter to unused p
27360 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a  ortion of zSql *
27370 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.);../*.** CAPI
27380 33 52 45 46 3a 20 52 65 74 72 69 65 76 69 6e 67  3REF: Retrieving
27390 20 53 74 61 74 65 6d 65 6e 74 20 53 51 4c 0a 2a   Statement SQL.*
273a0 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65 72  *.** ^This inter
273b0 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 64  face can be used
273c0 20 74 6f 20 72 65 74 72 69 65 76 65 20 61 20 73   to retrieve a s
273d0 61 76 65 64 20 63 6f 70 79 20 6f 66 20 74 68 65  aved copy of the
273e0 20 6f 72 69 67 69 6e 61 6c 0a 2a 2a 20 53 51 4c   original.** SQL
273f0 20 74 65 78 74 20 75 73 65 64 20 74 6f 20 63 72   text used to cr
27400 65 61 74 65 20 61 20 5b 70 72 65 70 61 72 65 64  eate a [prepared
27410 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 66 20 74   statement] if t
27420 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20 77 61  hat statement wa
27430 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 75 73  s.** compiled us
27440 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69  ing either [sqli
27450 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
27460 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ] or [sqlite3_pr
27470 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a  epare16_v2()]..*
27480 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  /.const char *sq
27490 6c 69 74 65 33 5f 73 71 6c 28 73 71 6c 69 74 65  lite3_sql(sqlite
274a0 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
274b0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
274c0 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 6e   Determine If An
274d0 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 57   SQL Statement W
274e0 72 69 74 65 73 20 54 68 65 20 44 61 74 61 62 61  rites The Databa
274f0 73 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  se.**.** ^The sq
27500 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f  lite3_stmt_reado
27510 6e 6c 79 28 58 29 20 69 6e 74 65 72 66 61 63 65  nly(X) interface
27520 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 6e   returns true (n
27530 6f 6e 2d 7a 65 72 6f 29 20 69 66 0a 2a 2a 20 61  on-zero) if.** a
27540 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 5b  nd only if the [
27550 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
27560 6e 74 5d 20 58 20 6d 61 6b 65 73 20 6e 6f 20 64  nt] X makes no d
27570 69 72 65 63 74 20 63 68 61 6e 67 65 73 20 74 6f  irect changes to
27580 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20  .** the content 
27590 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  of the database 
275a0 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65  file..**.** Note
275b0 20 74 68 61 74 20 5b 61 70 70 6c 69 63 61 74 69   that [applicati
275c0 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
275d0 75 6e 63 74 69 6f 6e 73 5d 20 6f 72 0a 2a 2a 20  unctions] or.** 
275e0 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 5d  [virtual tables]
275f0 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20 74 68   might change th
27600 65 20 64 61 74 61 62 61 73 65 20 69 6e 64 69 72  e database indir
27610 65 63 74 6c 79 20 61 73 20 61 20 73 69 64 65 20  ectly as a side 
27620 65 66 66 65 63 74 2e 20 20 0a 2a 2a 20 5e 28 46  effect.  .** ^(F
27630 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 61  or example, if a
27640 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65  n application de
27650 66 69 6e 65 73 20 61 20 66 75 6e 63 74 69 6f 6e  fines a function
27660 20 22 65 76 61 6c 28 29 22 20 74 68 61 74 20 0a   "eval()" that .
27670 2a 2a 20 63 61 6c 6c 73 20 5b 73 71 6c 69 74 65  ** calls [sqlite
27680 33 5f 65 78 65 63 28 29 5d 2c 20 74 68 65 6e 20  3_exec()], then 
27690 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51  the following SQ
276a0 4c 20 73 74 61 74 65 6d 65 6e 74 20 77 6f 75 6c  L statement woul
276b0 64 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20  d.** change the 
276c0 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 74 68  database file th
276d0 72 6f 75 67 68 20 73 69 64 65 2d 65 66 66 65 63  rough side-effec
276e0 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ts:.**.** <block
276f0 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
27700 20 20 53 45 4c 45 43 54 20 65 76 61 6c 28 27 44    SELECT eval('D
27710 45 4c 45 54 45 20 46 52 4f 4d 20 74 31 27 29 20  ELETE FROM t1') 
27720 46 52 4f 4d 20 74 32 3b 0a 2a 2a 20 3c 2f 70 72  FROM t2;.** </pr
27730 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
27740 2a 2a 0a 2a 2a 20 42 75 74 20 62 65 63 61 75 73  **.** But becaus
27750 65 20 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 73  e the [SELECT] s
27760 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f  tatement does no
27770 74 20 63 68 61 6e 67 65 20 74 68 65 20 64 61 74  t change the dat
27780 61 62 61 73 65 20 66 69 6c 65 0a 2a 2a 20 64 69  abase file.** di
27790 72 65 63 74 6c 79 2c 20 73 71 6c 69 74 65 33 5f  rectly, sqlite3_
277a0 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20  stmt_readonly() 
277b0 77 6f 75 6c 64 20 73 74 69 6c 6c 20 72 65 74 75  would still retu
277c0 72 6e 20 74 72 75 65 2e 29 5e 0a 2a 2a 0a 2a 2a  rn true.)^.**.**
277d0 20 5e 54 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f   ^Transaction co
277e0 6e 74 72 6f 6c 20 73 74 61 74 65 6d 65 6e 74 73  ntrol statements
277f0 20 73 75 63 68 20 61 73 20 5b 42 45 47 49 4e 5d   such as [BEGIN]
27800 2c 20 5b 43 4f 4d 4d 49 54 5d 2c 20 5b 52 4f 4c  , [COMMIT], [ROL
27810 4c 42 41 43 4b 5d 2c 0a 2a 2a 20 5b 53 41 56 45  LBACK],.** [SAVE
27820 50 4f 49 4e 54 5d 2c 20 61 6e 64 20 5b 52 45 4c  POINT], and [REL
27830 45 41 53 45 5d 20 63 61 75 73 65 20 73 71 6c 69  EASE] cause sqli
27840 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c  te3_stmt_readonl
27850 79 28 29 20 74 6f 20 72 65 74 75 72 6e 20 74 72  y() to return tr
27860 75 65 2c 0a 2a 2a 20 73 69 6e 63 65 20 74 68 65  ue,.** since the
27870 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 65 6d   statements them
27880 73 65 6c 76 65 73 20 64 6f 20 6e 6f 74 20 61 63  selves do not ac
27890 74 75 61 6c 6c 79 20 6d 6f 64 69 66 79 20 74 68  tually modify th
278a0 65 20 64 61 74 61 62 61 73 65 20 62 75 74 0a 2a  e database but.*
278b0 2a 20 72 61 74 68 65 72 20 74 68 65 79 20 63 6f  * rather they co
278c0 6e 74 72 6f 6c 20 74 68 65 20 74 69 6d 69 6e 67  ntrol the timing
278d0 20 6f 66 20 77 68 65 6e 20 6f 74 68 65 72 20 73   of when other s
278e0 74 61 74 65 6d 65 6e 74 73 20 6d 6f 64 69 66 79  tatements modify
278f0 20 74 68 65 20 0a 2a 2a 20 64 61 74 61 62 61 73   the .** databas
27900 65 2e 20 20 5e 54 68 65 20 5b 41 54 54 41 43 48  e.  ^The [ATTACH
27910 5d 20 61 6e 64 20 5b 44 45 54 41 43 48 5d 20 73  ] and [DETACH] s
27920 74 61 74 65 6d 65 6e 74 73 20 61 6c 73 6f 20 63  tatements also c
27930 61 75 73 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ause.** sqlite3_
27940 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20  stmt_readonly() 
27950 74 6f 20 72 65 74 75 72 6e 20 74 72 75 65 20 73  to return true s
27960 69 6e 63 65 2c 20 77 68 69 6c 65 20 74 68 6f 73  ince, while thos
27970 65 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  e statements.** 
27980 63 68 61 6e 67 65 20 74 68 65 20 63 6f 6e 66 69  change the confi
27990 67 75 72 61 74 69 6f 6e 20 6f 66 20 61 20 64 61  guration of a da
279a0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
279b0 6e 2c 20 74 68 65 79 20 64 6f 20 6e 6f 74 20 6d  n, they do not m
279c0 61 6b 65 20 0a 2a 2a 20 63 68 61 6e 67 65 73 20  ake .** changes 
279d0 74 6f 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f  to the content o
279e0 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  f the database f
279f0 69 6c 65 73 20 6f 6e 20 64 69 73 6b 2e 0a 2a 2f  iles on disk..*/
27a00 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 6d  .int sqlite3_stm
27a10 74 5f 72 65 61 64 6f 6e 6c 79 28 73 71 6c 69 74  t_readonly(sqlit
27a20 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
27a30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
27a40 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41  : Determine If A
27a50 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d   Prepared Statem
27a60 65 6e 74 20 48 61 73 20 42 65 65 6e 20 52 65 73  ent Has Been Res
27a70 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  et.**.** ^The sq
27a80 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28  lite3_stmt_busy(
27a90 53 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  S) interface ret
27aa0 75 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a  urns true (non-z
27ab0 65 72 6f 29 20 69 66 20 74 68 65 0a 2a 2a 20 5b  ero) if the.** [
27ac0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
27ad0 6e 74 5d 20 53 20 68 61 73 20 62 65 65 6e 20 73  nt] S has been s
27ae0 74 65 70 70 65 64 20 61 74 20 6c 65 61 73 74 20  tepped at least 
27af0 6f 6e 63 65 20 75 73 69 6e 67 20 0a 2a 2a 20 5b  once using .** [
27b00 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d  sqlite3_step(S)]
27b10 20 62 75 74 20 68 61 73 20 6e 6f 74 20 72 75 6e   but has not run
27b20 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61   to completion a
27b30 6e 64 2f 6f 72 20 68 61 73 20 6e 6f 74 20 0a 2a  nd/or has not .*
27b40 2a 20 62 65 65 6e 20 72 65 73 65 74 20 75 73 69  * been reset usi
27b50 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ng [sqlite3_rese
27b60 74 28 53 29 5d 2e 20 20 5e 54 68 65 20 73 71 6c  t(S)].  ^The sql
27b70 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 53  ite3_stmt_busy(S
27b80 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72  ).** interface r
27b90 65 74 75 72 6e 73 20 66 61 6c 73 65 20 69 66 20  eturns false if 
27ba0 53 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  S is a NULL poin
27bb0 74 65 72 2e 20 20 49 66 20 53 20 69 73 20 6e 6f  ter.  If S is no
27bc0 74 20 61 20 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69  t a .** NULL poi
27bd0 6e 74 65 72 20 61 6e 64 20 69 73 20 6e 6f 74 20  nter and is not 
27be0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 76  a pointer to a v
27bf0 61 6c 69 64 20 5b 70 72 65 70 61 72 65 64 20 73  alid [prepared s
27c00 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a  tatement].** obj
27c10 65 63 74 2c 20 74 68 65 6e 20 74 68 65 20 62 65  ect, then the be
27c20 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69  havior is undefi
27c30 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79  ned and probably
27c40 20 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2a   undesirable..**
27c50 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61  .** This interfa
27c60 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 69  ce can be used i
27c70 6e 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 5b 73  n combination [s
27c80 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74  qlite3_next_stmt
27c90 28 29 5d 0a 2a 2a 20 74 6f 20 6c 6f 63 61 74 65  ()].** to locate
27ca0 20 61 6c 6c 20 70 72 65 70 61 72 65 64 20 73 74   all prepared st
27cb0 61 74 65 6d 65 6e 74 73 20 61 73 73 6f 63 69 61  atements associa
27cc0 74 65 64 20 77 69 74 68 20 61 20 64 61 74 61 62  ted with a datab
27cd0 61 73 65 20 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  ase .** connecti
27ce0 6f 6e 20 74 68 61 74 20 61 72 65 20 69 6e 20 6e  on that are in n
27cf0 65 65 64 20 6f 66 20 62 65 69 6e 67 20 72 65 73  eed of being res
27d00 65 74 2e 20 20 54 68 69 73 20 63 61 6e 20 62 65  et.  This can be
27d10 20 75 73 65 64 2c 0a 2a 2a 20 66 6f 72 20 65 78   used,.** for ex
27d20 61 6d 70 6c 65 2c 20 69 6e 20 64 69 61 67 6e 6f  ample, in diagno
27d30 73 74 69 63 20 72 6f 75 74 69 6e 65 73 20 74 6f  stic routines to
27d40 20 73 65 61 72 63 68 20 66 6f 72 20 70 72 65 70   search for prep
27d50 61 72 65 64 20 0a 2a 2a 20 73 74 61 74 65 6d 65  ared .** stateme
27d60 6e 74 73 20 74 68 61 74 20 61 72 65 20 68 6f 6c  nts that are hol
27d70 64 69 6e 67 20 61 20 74 72 61 6e 73 61 63 74 69  ding a transacti
27d80 6f 6e 20 6f 70 65 6e 2e 0a 2a 2f 0a 69 6e 74 20  on open..*/.int 
27d90 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73  sqlite3_stmt_bus
27da0 79 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  y(sqlite3_stmt*)
27db0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
27dc0 46 3a 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54  F: Dynamically T
27dd0 79 70 65 64 20 56 61 6c 75 65 20 4f 62 6a 65 63  yped Value Objec
27de0 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  t.** KEYWORDS: {
27df0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
27e00 33 5f 76 61 6c 75 65 7d 20 7b 75 6e 70 72 6f 74  3_value} {unprot
27e10 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
27e20 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  lue}.**.** SQLit
27e30 65 20 75 73 65 73 20 74 68 65 20 73 71 6c 69 74  e uses the sqlit
27e40 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20  e3_value object 
27e50 74 6f 20 72 65 70 72 65 73 65 6e 74 20 61 6c 6c  to represent all
27e60 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20   values.** that 
27e70 63 61 6e 20 62 65 20 73 74 6f 72 65 64 20 69 6e  can be stored in
27e80 20 61 20 64 61 74 61 62 61 73 65 20 74 61 62 6c   a database tabl
27e90 65 2e 20 53 51 4c 69 74 65 20 75 73 65 73 20 64  e. SQLite uses d
27ea0 79 6e 61 6d 69 63 20 74 79 70 69 6e 67 0a 2a 2a  ynamic typing.**
27eb0 20 66 6f 72 20 74 68 65 20 76 61 6c 75 65 73 20   for the values 
27ec0 69 74 20 73 74 6f 72 65 73 2e 20 20 5e 56 61 6c  it stores.  ^Val
27ed0 75 65 73 20 73 74 6f 72 65 64 20 69 6e 20 73 71  ues stored in sq
27ee0 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
27ef0 63 74 73 0a 2a 2a 20 63 61 6e 20 62 65 20 69 6e  cts.** can be in
27f00 74 65 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67  tegers, floating
27f10 20 70 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20 73   point values, s
27f20 74 72 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f  trings, BLOBs, o
27f30 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e  r NULL..**.** An
27f40 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
27f50 62 6a 65 63 74 20 6d 61 79 20 62 65 20 65 69 74  bject may be eit
27f60 68 65 72 20 22 70 72 6f 74 65 63 74 65 64 22 20  her "protected" 
27f70 6f 72 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22  or "unprotected"
27f80 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74 65 72 66  ..** Some interf
27f90 61 63 65 73 20 72 65 71 75 69 72 65 20 61 20 70  aces require a p
27fa0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
27fb0 5f 76 61 6c 75 65 2e 20 20 4f 74 68 65 72 20 69  _value.  Other i
27fc0 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 77 69 6c  nterfaces.** wil
27fd0 6c 20 61 63 63 65 70 74 20 65 69 74 68 65 72 20  l accept either 
27fe0 61 20 70 72 6f 74 65 63 74 65 64 20 6f 72 20 61  a protected or a
27ff0 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71  n unprotected sq
28000 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20  lite3_value..** 
28010 45 76 65 72 79 20 69 6e 74 65 72 66 61 63 65 20  Every interface 
28020 74 68 61 74 20 61 63 63 65 70 74 73 20 73 71 6c  that accepts sql
28030 69 74 65 33 5f 76 61 6c 75 65 20 61 72 67 75 6d  ite3_value argum
28040 65 6e 74 73 20 73 70 65 63 69 66 69 65 73 0a 2a  ents specifies.*
28050 2a 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  * whether or not
28060 20 69 74 20 72 65 71 75 69 72 65 73 20 61 20 70   it requires a p
28070 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
28080 5f 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  _value..**.** Th
28090 65 20 74 65 72 6d 73 20 22 70 72 6f 74 65 63 74  e terms "protect
280a0 65 64 22 20 61 6e 64 20 22 75 6e 70 72 6f 74 65  ed" and "unprote
280b0 63 74 65 64 22 20 72 65 66 65 72 20 74 6f 20 77  cted" refer to w
280c0 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a  hether or not.**
280d0 20 61 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64   a mutex is held
280e0 2e 20 20 41 6e 20 69 6e 74 65 72 6e 61 6c 20 6d  .  An internal m
280f0 75 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72  utex is held for
28100 20 61 20 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20   a protected.** 
28110 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
28120 6a 65 63 74 20 62 75 74 20 6e 6f 20 6d 75 74 65  ject but no mute
28130 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61 6e  x is held for an
28140 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20   unprotected.** 
28150 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
28160 6a 65 63 74 2e 20 20 49 66 20 53 51 4c 69 74 65  ject.  If SQLite
28170 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 74 6f 20   is compiled to 
28180 62 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64  be single-thread
28190 65 64 0a 2a 2a 20 28 77 69 74 68 20 5b 53 51 4c  ed.** (with [SQL
281a0 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30  ITE_THREADSAFE=0
281b0 5d 20 61 6e 64 20 77 69 74 68 20 5b 73 71 6c 69  ] and with [sqli
281c0 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29  te3_threadsafe()
281d0 5d 20 72 65 74 75 72 6e 69 6e 67 20 30 29 0a 2a  ] returning 0).*
281e0 2a 20 6f 72 20 69 66 20 53 51 4c 69 74 65 20 69  * or if SQLite i
281f0 73 20 72 75 6e 20 69 6e 20 6f 6e 65 20 6f 66 20  s run in one of 
28200 72 65 64 75 63 65 64 20 6d 75 74 65 78 20 6d 6f  reduced mutex mo
28210 64 65 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  des .** [SQLITE_
28220 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52  CONFIG_SINGLETHR
28230 45 41 44 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  EAD] or [SQLITE_
28240 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45  CONFIG_MULTITHRE
28250 41 44 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 72  AD].** then ther
28260 65 20 69 73 20 6e 6f 20 64 69 73 74 69 6e 63 74  e is no distinct
28270 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74  ion between prot
28280 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74  ected and unprot
28290 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33  ected.** sqlite3
282a0 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 61  _value objects a
282b0 6e 64 20 74 68 65 79 20 63 61 6e 20 62 65 20 75  nd they can be u
282c0 73 65 64 20 69 6e 74 65 72 63 68 61 6e 67 65 61  sed interchangea
282d0 62 6c 79 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a  bly.  However,.*
282e0 2a 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 63 6f  * for maximum co
282f0 64 65 20 70 6f 72 74 61 62 69 6c 69 74 79 20 69  de portability i
28300 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  t is recommended
28310 20 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f   that applicatio
28320 6e 73 0a 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b 65  ns.** still make
28330 20 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e   the distinction
28340 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74   between protect
28350 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74  ed and unprotect
28360 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61  ed.** sqlite3_va
28370 6c 75 65 20 6f 62 6a 65 63 74 73 20 65 76 65 6e  lue objects even
28380 20 77 68 65 6e 20 6e 6f 74 20 73 74 72 69 63 74   when not strict
28390 6c 79 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a  ly required..**.
283a0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
283b0 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 74 68  value objects th
283c0 61 74 20 61 72 65 20 70 61 73 73 65 64 20 61 73  at are passed as
283d0 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e 74 6f   parameters into
283e0 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e   the.** implemen
283f0 74 61 74 69 6f 6e 20 6f 66 20 5b 61 70 70 6c 69  tation of [appli
28400 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
28410 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 61 72  QL functions] ar
28420 65 20 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20  e protected..** 
28430 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c  ^The sqlite3_val
28440 75 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e  ue object return
28450 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65  ed by.** [sqlite
28460 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29  3_column_value()
28470 5d 20 69 73 20 75 6e 70 72 6f 74 65 63 74 65 64  ] is unprotected
28480 2e 0a 2a 2a 20 55 6e 70 72 6f 74 65 63 74 65 64  ..** Unprotected
28490 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
284a0 62 6a 65 63 74 73 20 6d 61 79 20 6f 6e 6c 79 20  bjects may only 
284b0 62 65 20 75 73 65 64 20 77 69 74 68 0a 2a 2a 20  be used with.** 
284c0 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
284d0 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71  value()] and [sq
284e0 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65  lite3_bind_value
284f0 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c  ()]..** The [sql
28500 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 20  ite3_value_blob 
28510 7c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  | sqlite3_value_
28520 74 79 70 65 28 29 5d 20 66 61 6d 69 6c 79 20 6f  type()] family o
28530 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  f.** interfaces 
28540 72 65 71 75 69 72 65 20 70 72 6f 74 65 63 74 65  require protecte
28550 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  d sqlite3_value 
28560 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74 79 70 65  objects..*/.type
28570 64 65 66 20 73 74 72 75 63 74 20 4d 65 6d 20 73  def struct Mem s
28580 71 6c 69 74 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f  qlite3_value;../
28590 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
285a0 51 4c 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74  QL Function Cont
285b0 65 78 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a  ext Object.**.**
285c0 20 54 68 65 20 63 6f 6e 74 65 78 74 20 69 6e 20   The context in 
285d0 77 68 69 63 68 20 61 6e 20 53 51 4c 20 66 75 6e  which an SQL fun
285e0 63 74 69 6f 6e 20 65 78 65 63 75 74 65 73 20 69  ction executes i
285f0 73 20 73 74 6f 72 65 64 20 69 6e 20 61 6e 0a 2a  s stored in an.*
28600 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  * sqlite3_contex
28610 74 20 6f 62 6a 65 63 74 2e 20 20 5e 41 20 70 6f  t object.  ^A po
28620 69 6e 74 65 72 20 74 6f 20 61 6e 20 73 71 6c 69  inter to an sqli
28630 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65  te3_context obje
28640 63 74 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20  ct.** is always 
28650 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
28660 74 6f 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d  to [application-
28670 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
28680 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20 61  tions]..** The a
28690 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
286a0 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  ed SQL function 
286b0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77  implementation w
286c0 69 6c 6c 20 70 61 73 73 20 74 68 69 73 0a 2a 2a  ill pass this.**
286d0 20 70 6f 69 6e 74 65 72 20 74 68 72 6f 75 67 68   pointer through
286e0 20 69 6e 74 6f 20 63 61 6c 6c 73 20 74 6f 20 5b   into calls to [
286f0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69  sqlite3_result_i
28700 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f 72 65 73  nt | sqlite3_res
28710 75 6c 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ult()],.** [sqli
28720 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
28730 6e 74 65 78 74 28 29 5d 2c 20 5b 73 71 6c 69 74  ntext()], [sqlit
28740 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2c  e3_user_data()],
28750 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
28760 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29  text_db_handle()
28770 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f  ], [sqlite3_get_
28780 61 75 78 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 61  auxdata()],.** a
28790 6e 64 2f 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73  nd/or [sqlite3_s
287a0 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2e 0a 2a  et_auxdata()]..*
287b0 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
287c0 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
287d0 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
287e0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
287f0 46 3a 20 42 69 6e 64 69 6e 67 20 56 61 6c 75 65  F: Binding Value
28800 73 20 54 6f 20 50 72 65 70 61 72 65 64 20 53 74  s To Prepared St
28810 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 4b 45 59 57  atements.** KEYW
28820 4f 52 44 53 3a 20 7b 68 6f 73 74 20 70 61 72 61  ORDS: {host para
28830 6d 65 74 65 72 7d 20 7b 68 6f 73 74 20 70 61 72  meter} {host par
28840 61 6d 65 74 65 72 73 7d 20 7b 68 6f 73 74 20 70  ameters} {host p
28850 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 7d 0a 2a  arameter name}.*
28860 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c  * KEYWORDS: {SQL
28870 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 53 51 4c   parameter} {SQL
28880 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 70 61   parameters} {pa
28890 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 7d  rameter binding}
288a0 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 65 20  .**.** ^(In the 
288b0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65  SQL statement te
288c0 78 74 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c  xt input to [sql
288d0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
288e0 29 5d 20 61 6e 64 20 69 74 73 20 76 61 72 69 61  )] and its varia
288f0 6e 74 73 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c 73  nts,.** literals
28900 20 6d 61 79 20 62 65 20 72 65 70 6c 61 63 65 64   may be replaced
28910 20 62 79 20 61 20 5b 70 61 72 61 6d 65 74 65 72   by a [parameter
28920 5d 20 74 68 61 74 20 6d 61 74 63 68 65 73 20 6f  ] that matches o
28930 6e 65 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67 0a  ne of following.
28940 2a 2a 20 74 65 6d 70 6c 61 74 65 73 3a 0a 2a 2a  ** templates:.**
28950 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
28960 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e    ?.** <li>  ?NN
28970 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56 56 0a  N.** <li>  :VVV.
28980 2a 2a 20 3c 6c 69 3e 20 20 40 56 56 56 0a 2a 2a  ** <li>  @VVV.**
28990 20 3c 6c 69 3e 20 20 24 56 56 56 0a 2a 2a 20 3c   <li>  $VVV.** <
289a0 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68  /ul>.**.** In th
289b0 65 20 74 65 6d 70 6c 61 74 65 73 20 61 62 6f 76  e templates abov
289c0 65 2c 20 4e 4e 4e 20 72 65 70 72 65 73 65 6e 74  e, NNN represent
289d0 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6c 69 74  s an integer lit
289e0 65 72 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56 56  eral,.** and VVV
289f0 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 61   represents an a
28a00 6c 70 68 61 6e 75 6d 65 72 69 63 20 69 64 65 6e  lphanumeric iden
28a10 74 69 66 69 65 72 2e 29 5e 20 20 5e 54 68 65 20  tifier.)^  ^The 
28a20 76 61 6c 75 65 73 20 6f 66 20 74 68 65 73 65 0a  values of these.
28a30 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 20 28 61  ** parameters (a
28a40 6c 73 6f 20 63 61 6c 6c 65 64 20 22 68 6f 73 74  lso called "host
28a50 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 73   parameter names
28a60 22 20 6f 72 20 22 53 51 4c 20 70 61 72 61 6d 65  " or "SQL parame
28a70 74 65 72 73 22 29 0a 2a 2a 20 63 61 6e 20 62 65  ters").** can be
28a80 20 73 65 74 20 75 73 69 6e 67 20 74 68 65 20 73   set using the s
28a90 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20  qlite3_bind_*() 
28aa0 72 6f 75 74 69 6e 65 73 20 64 65 66 69 6e 65 64  routines defined
28ab0 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68   here..**.** ^Th
28ac0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
28ad0 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
28ae0 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65  bind_*() routine
28af0 73 20 69 73 20 61 6c 77 61 79 73 0a 2a 2a 20 61  s is always.** a
28b00 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
28b10 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f  [sqlite3_stmt] o
28b20 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 66  bject returned f
28b30 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  rom.** [sqlite3_
28b40 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
28b50 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e 0a 2a   its variants..*
28b60 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64  *.** ^The second
28b70 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
28b80 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 53 51   index of the SQ
28b90 4c 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62  L parameter to b
28ba0 65 20 73 65 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c  e set..** ^The l
28bb0 65 66 74 6d 6f 73 74 20 53 51 4c 20 70 61 72 61  eftmost SQL para
28bc0 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64  meter has an ind
28bd0 65 78 20 6f 66 20 31 2e 20 20 5e 57 68 65 6e 20  ex of 1.  ^When 
28be0 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 64 0a 2a  the same named.*
28bf0 2a 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20  * SQL parameter 
28c00 69 73 20 75 73 65 64 20 6d 6f 72 65 20 74 68 61  is used more tha
28c10 6e 20 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 20 61  n once, second a
28c20 6e 64 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a  nd subsequent.**
28c30 20 6f 63 63 75 72 72 65 6e 63 65 73 20 68 61 76   occurrences hav
28c40 65 20 74 68 65 20 73 61 6d 65 20 69 6e 64 65 78  e the same index
28c50 20 61 73 20 74 68 65 20 66 69 72 73 74 20 6f 63   as the first oc
28c60 63 75 72 72 65 6e 63 65 2e 0a 2a 2a 20 5e 54 68  currence..** ^Th
28c70 65 20 69 6e 64 65 78 20 66 6f 72 20 6e 61 6d 65  e index for name
28c80 64 20 70 61 72 61 6d 65 74 65 72 73 20 63 61 6e  d parameters can
28c90 20 62 65 20 6c 6f 6f 6b 65 64 20 75 70 20 75 73   be looked up us
28ca0 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  ing the.** [sqli
28cb0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
28cc0 65 72 5f 69 6e 64 65 78 28 29 5d 20 41 50 49 20  er_index()] API 
28cd0 69 66 20 64 65 73 69 72 65 64 2e 20 20 5e 54 68  if desired.  ^Th
28ce0 65 20 69 6e 64 65 78 0a 2a 2a 20 66 6f 72 20 22  e index.** for "
28cf0 3f 4e 4e 4e 22 20 70 61 72 61 6d 65 74 65 72 73  ?NNN" parameters
28d00 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66   is the value of
28d10 20 4e 4e 4e 2e 0a 2a 2a 20 5e 54 68 65 20 4e 4e   NNN..** ^The NN
28d20 4e 20 76 61 6c 75 65 20 6d 75 73 74 20 62 65 20  N value must be 
28d30 62 65 74 77 65 65 6e 20 31 20 61 6e 64 20 74 68  between 1 and th
28d40 65 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  e [sqlite3_limit
28d50 28 29 5d 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ()].** parameter
28d60 20 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56   [SQLITE_LIMIT_V
28d70 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 20  ARIABLE_NUMBER] 
28d80 28 64 65 66 61 75 6c 74 20 76 61 6c 75 65 3a 20  (default value: 
28d90 39 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  999)..**.** ^The
28da0 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
28db0 69 73 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20  is the value to 
28dc0 62 69 6e 64 20 74 6f 20 74 68 65 20 70 61 72 61  bind to the para
28dd0 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68  meter..** ^If th
28de0 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
28df0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e  r to sqlite3_bin
28e00 64 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69  d_text() or sqli
28e10 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28  te3_bind_text16(
28e20 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f  ).** or sqlite3_
28e30 62 69 6e 64 5f 62 6c 6f 62 28 29 20 69 73 20 61  bind_blob() is a
28e40 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68   NULL pointer th
28e50 65 6e 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  en the fourth pa
28e60 72 61 6d 65 74 65 72 0a 2a 2a 20 69 73 20 69 67  rameter.** is ig
28e70 6e 6f 72 65 64 20 61 6e 64 20 74 68 65 20 65 6e  nored and the en
28e80 64 20 72 65 73 75 6c 74 20 69 73 20 74 68 65 20  d result is the 
28e90 73 61 6d 65 20 61 73 20 73 71 6c 69 74 65 33 5f  same as sqlite3_
28ea0 62 69 6e 64 5f 6e 75 6c 6c 28 29 2e 0a 2a 2a 0a  bind_null()..**.
28eb0 2a 2a 20 5e 28 49 6e 20 74 68 6f 73 65 20 72 6f  ** ^(In those ro
28ec0 75 74 69 6e 65 73 20 74 68 61 74 20 68 61 76 65  utines that have
28ed0 20 61 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65   a fourth argume
28ee0 6e 74 2c 20 69 74 73 20 76 61 6c 75 65 20 69 73  nt, its value is
28ef0 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f   the.** number o
28f00 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 70  f bytes in the p
28f10 61 72 61 6d 65 74 65 72 2e 20 20 54 6f 20 62 65  arameter.  To be
28f20 20 63 6c 65 61 72 3a 20 74 68 65 20 76 61 6c 75   clear: the valu
28f30 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62  e is the.** numb
28f40 65 72 20 6f 66 20 3c 75 3e 62 79 74 65 73 3c 2f  er of <u>bytes</
28f50 75 3e 20 69 6e 20 74 68 65 20 76 61 6c 75 65 2c  u> in the value,
28f60 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20   not the number 
28f70 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e 29 5e  of characters.)^
28f80 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 6f 75 72  .** ^If the four
28f90 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
28fa0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
28fb0 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 62  t() or sqlite3_b
28fc0 69 6e 64 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20  ind_text16().** 
28fd0 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65  is negative, the
28fe0 6e 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20  n the length of 
28ff0 74 68 65 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a  the string is.**
29000 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
29010 79 74 65 73 20 75 70 20 74 6f 20 74 68 65 20 66  ytes up to the f
29020 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e  irst zero termin
29030 61 74 6f 72 2e 0a 2a 2a 20 49 66 20 74 68 65 20  ator..** If the 
29040 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
29050 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   to sqlite3_bind
29060 5f 62 6c 6f 62 28 29 20 69 73 20 6e 65 67 61 74  _blob() is negat
29070 69 76 65 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65  ive, then.** the
29080 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64   behavior is und
29090 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 61 20  efined..** If a 
290a0 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 66 6f 75  non-negative fou
290b0 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  rth parameter is
290c0 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73 71 6c   provided to sql
290d0 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29  ite3_bind_text()
290e0 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 62  .** or sqlite3_b
290f0 69 6e 64 5f 74 65 78 74 31 36 28 29 20 74 68 65  ind_text16() the
29100 6e 20 74 68 61 74 20 70 61 72 61 6d 65 74 65 72  n that parameter
29110 20 6d 75 73 74 20 62 65 20 74 68 65 20 62 79 74   must be the byt
29120 65 20 6f 66 66 73 65 74 0a 2a 2a 20 77 68 65 72  e offset.** wher
29130 65 20 74 68 65 20 4e 55 4c 20 74 65 72 6d 69 6e  e the NUL termin
29140 61 74 6f 72 20 77 6f 75 6c 64 20 6f 63 63 75 72  ator would occur
29150 20 61 73 73 75 6d 69 6e 67 20 74 68 65 20 73 74   assuming the st
29160 72 69 6e 67 20 77 65 72 65 20 4e 55 4c 0a 2a 2a  ring were NUL.**
29170 20 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 49 66   terminated.  If
29180 20 61 6e 79 20 4e 55 4c 20 63 68 61 72 61 63 74   any NUL charact
29190 65 72 73 20 6f 63 63 75 72 20 61 74 20 62 79 74  ers occur at byt
291a0 65 20 6f 66 66 73 65 74 73 20 6c 65 73 73 20 74  e offsets less t
291b0 68 61 6e 20 0a 2a 2a 20 74 68 65 20 76 61 6c 75  han .** the valu
291c0 65 20 6f 66 20 74 68 65 20 66 6f 75 72 74 68 20  e of the fourth 
291d0 70 61 72 61 6d 65 74 65 72 20 74 68 65 6e 20 74  parameter then t
291e0 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72  he resulting str
291f0 69 6e 67 20 76 61 6c 75 65 20 77 69 6c 6c 0a 2a  ing value will.*
29200 2a 20 63 6f 6e 74 61 69 6e 20 65 6d 62 65 64 64  * contain embedd
29210 65 64 20 4e 55 4c 73 2e 20 20 54 68 65 20 72 65  ed NULs.  The re
29220 73 75 6c 74 20 6f 66 20 65 78 70 72 65 73 73 69  sult of expressi
29230 6f 6e 73 20 69 6e 76 6f 6c 76 69 6e 67 20 73 74  ons involving st
29240 72 69 6e 67 73 0a 2a 2a 20 77 69 74 68 20 65 6d  rings.** with em
29250 62 65 64 64 65 64 20 4e 55 4c 73 20 69 73 20 75  bedded NULs is u
29260 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
29270 5e 54 68 65 20 66 69 66 74 68 20 61 72 67 75 6d  ^The fifth argum
29280 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62  ent to sqlite3_b
29290 69 6e 64 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69  ind_blob(), sqli
292a0 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 2c  te3_bind_text(),
292b0 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   and.** sqlite3_
292c0 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20 69 73  bind_text16() is
292d0 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 75 73   a destructor us
292e0 65 64 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66  ed to dispose of
292f0 20 74 68 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20   the BLOB or.** 
29300 73 74 72 69 6e 67 20 61 66 74 65 72 20 53 51 4c  string after SQL
29310 69 74 65 20 68 61 73 20 66 69 6e 69 73 68 65 64  ite has finished
29320 20 77 69 74 68 20 69 74 2e 20 20 5e 54 68 65 20   with it.  ^The 
29330 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 63 61  destructor is ca
29340 6c 6c 65 64 0a 2a 2a 20 74 6f 20 64 69 73 70 6f  lled.** to dispo
29350 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f  se of the BLOB o
29360 72 20 73 74 72 69 6e 67 20 65 76 65 6e 20 69 66  r string even if
29370 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c   the call to sql
29380 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29  ite3_bind_blob()
29390 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62 69 6e  ,.** sqlite3_bin
293a0 64 5f 74 65 78 74 28 29 2c 20 6f 72 20 73 71 6c  d_text(), or sql
293b0 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36  ite3_bind_text16
293c0 28 29 20 66 61 69 6c 73 2e 20 20 0a 2a 2a 20 5e  () fails.  .** ^
293d0 49 66 20 74 68 65 20 66 69 66 74 68 20 61 72 67  If the fifth arg
293e0 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 74 68 65 20  ument is.** the 
293f0 73 70 65 63 69 61 6c 20 76 61 6c 75 65 20 5b 53  special value [S
29400 51 4c 49 54 45 5f 53 54 41 54 49 43 5d 2c 20 74  QLITE_STATIC], t
29410 68 65 6e 20 53 51 4c 69 74 65 20 61 73 73 75 6d  hen SQLite assum
29420 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 69  es that the.** i
29430 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 69 6e  nformation is in
29440 20 73 74 61 74 69 63 2c 20 75 6e 6d 61 6e 61 67   static, unmanag
29450 65 64 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65  ed space and doe
29460 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65  s not need to be
29470 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 74   freed..** ^If t
29480 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e  he fifth argumen
29490 74 20 68 61 73 20 74 68 65 20 76 61 6c 75 65 20  t has the value 
294a0 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e  [SQLITE_TRANSIEN
294b0 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69  T], then.** SQLi
294c0 74 65 20 6d 61 6b 65 73 20 69 74 73 20 6f 77 6e  te makes its own
294d0 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66   private copy of
294e0 20 74 68 65 20 64 61 74 61 20 69 6d 6d 65 64 69   the data immedi
294f0 61 74 65 6c 79 2c 20 62 65 66 6f 72 65 0a 2a 2a  ately, before.**
29500 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e   the sqlite3_bin
29510 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 20 72 65  d_*() routine re
29520 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  turns..**.** ^Th
29530 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a  e sqlite3_bind_z
29540 65 72 6f 62 6c 6f 62 28 29 20 72 6f 75 74 69 6e  eroblob() routin
29550 65 20 62 69 6e 64 73 20 61 20 42 4c 4f 42 20 6f  e binds a BLOB o
29560 66 20 6c 65 6e 67 74 68 20 4e 20 74 68 61 74 0a  f length N that.
29570 2a 2a 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74  ** is filled wit
29580 68 20 7a 65 72 6f 65 73 2e 20 20 5e 41 20 7a 65  h zeroes.  ^A ze
29590 72 6f 62 6c 6f 62 20 75 73 65 73 20 61 20 66 69  roblob uses a fi
295a0 78 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65  xed amount of me
295b0 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73 74 20 61 6e  mory.** (just an
295c0 20 69 6e 74 65 67 65 72 20 74 6f 20 68 6f 6c 64   integer to hold
295d0 20 69 74 73 20 73 69 7a 65 29 20 77 68 69 6c 65   its size) while
295e0 20 69 74 20 69 73 20 62 65 69 6e 67 20 70 72 6f   it is being pro
295f0 63 65 73 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62  cessed..** Zerob
29600 6c 6f 62 73 20 61 72 65 20 69 6e 74 65 6e 64 65  lobs are intende
29610 64 20 74 6f 20 73 65 72 76 65 20 61 73 20 70 6c  d to serve as pl
29620 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 42  aceholders for B
29630 4c 4f 42 73 20 77 68 6f 73 65 0a 2a 2a 20 63 6f  LOBs whose.** co
29640 6e 74 65 6e 74 20 69 73 20 6c 61 74 65 72 20 77  ntent is later w
29650 72 69 74 74 65 6e 20 75 73 69 6e 67 0a 2a 2a 20  ritten using.** 
29660 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70  [sqlite3_blob_op
29670 65 6e 20 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c  en | incremental
29680 20 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75 74 69   BLOB I/O] routi
29690 6e 65 73 2e 0a 2a 2a 20 5e 41 20 6e 65 67 61 74  nes..** ^A negat
296a0 69 76 65 20 76 61 6c 75 65 20 66 6f 72 20 74 68  ive value for th
296b0 65 20 7a 65 72 6f 62 6c 6f 62 20 72 65 73 75 6c  e zeroblob resul
296c0 74 73 20 69 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e  ts in a zero-len
296d0 67 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20  gth BLOB..**.** 
296e0 5e 49 66 20 61 6e 79 20 6f 66 20 74 68 65 20 73  ^If any of the s
296f0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20  qlite3_bind_*() 
29700 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c  routines are cal
29710 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c 20  led with a NULL 
29720 70 6f 69 6e 74 65 72 0a 2a 2a 20 66 6f 72 20 74  pointer.** for t
29730 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
29740 74 65 6d 65 6e 74 5d 20 6f 72 20 77 69 74 68 20  tement] or with 
29750 61 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  a prepared state
29760 6d 65 6e 74 20 66 6f 72 20 77 68 69 63 68 0a 2a  ment for which.*
29770 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  * [sqlite3_step(
29780 29 5d 20 68 61 73 20 62 65 65 6e 20 63 61 6c 6c  )] has been call
29790 65 64 20 6d 6f 72 65 20 72 65 63 65 6e 74 6c 79  ed more recently
297a0 20 74 68 61 6e 20 5b 73 71 6c 69 74 65 33 5f 72   than [sqlite3_r
297b0 65 73 65 74 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e  eset()],.** then
297c0 20 74 68 65 20 63 61 6c 6c 20 77 69 6c 6c 20 72   the call will r
297d0 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4d 49  eturn [SQLITE_MI
297e0 53 55 53 45 5d 2e 20 20 49 66 20 61 6e 79 20 73  SUSE].  If any s
297f0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 28 29 0a 2a  qlite3_bind_().*
29800 2a 20 72 6f 75 74 69 6e 65 20 69 73 20 70 61 73  * routine is pas
29810 73 65 64 20 61 20 5b 70 72 65 70 61 72 65 64 20  sed a [prepared 
29820 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20  statement] that 
29830 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a  has been finaliz
29840 65 64 2c 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c  ed, the.** resul
29850 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61  t is undefined a
29860 6e 64 20 70 72 6f 62 61 62 6c 79 20 68 61 72 6d  nd probably harm
29870 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 42 69 6e 64  ful..**.** ^Bind
29880 69 6e 67 73 20 61 72 65 20 6e 6f 74 20 63 6c 65  ings are not cle
29890 61 72 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c  ared by the [sql
298a0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 72 6f  ite3_reset()] ro
298b0 75 74 69 6e 65 2e 0a 2a 2a 20 5e 55 6e 62 6f 75  utine..** ^Unbou
298c0 6e 64 20 70 61 72 61 6d 65 74 65 72 73 20 61 72  nd parameters ar
298d0 65 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  e interpreted as
298e0 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68   NULL..**.** ^Th
298f0 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
29900 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
29910 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20   [SQLITE_OK] on 
29920 73 75 63 63 65 73 73 20 6f 72 20 61 6e 0a 2a 2a  success or an.**
29930 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66   [error code] if
29940 20 61 6e 79 74 68 69 6e 67 20 67 6f 65 73 20 77   anything goes w
29950 72 6f 6e 67 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54  rong..** ^[SQLIT
29960 45 5f 52 41 4e 47 45 5d 20 69 73 20 72 65 74 75  E_RANGE] is retu
29970 72 6e 65 64 20 69 66 20 74 68 65 20 70 61 72 61  rned if the para
29980 6d 65 74 65 72 0a 2a 2a 20 69 6e 64 65 78 20 69  meter.** index i
29990 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2e 20  s out of range. 
299a0 20 5e 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d   ^[SQLITE_NOMEM]
299b0 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20   is returned if 
299c0 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 2e 0a  malloc() fails..
299d0 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
299e0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
299f0 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d  rameter_count()]
29a00 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  ,.** [sqlite3_bi
29a10 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d  nd_parameter_nam
29a20 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74  e()], and [sqlit
29a30 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
29a40 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69  r_index()]..*/.i
29a50 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
29a60 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d  blob(sqlite3_stm
29a70 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76  t*, int, const v
29a80 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69  oid*, int n, voi
29a90 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e  d(*)(void*));.in
29aa0 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64  t sqlite3_bind_d
29ab0 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74  ouble(sqlite3_st
29ac0 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65  mt*, int, double
29ad0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
29ae0 69 6e 64 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f  ind_int(sqlite3_
29af0 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29  stmt*, int, int)
29b00 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
29b10 6e 64 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33  nd_int64(sqlite3
29b20 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c  _stmt*, int, sql
29b30 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 69 6e 74  ite3_int64);.int
29b40 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75   sqlite3_bind_nu
29b50 6c 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ll(sqlite3_stmt*
29b60 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69  , int);.int sqli
29b70 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 73 71  te3_bind_text(sq
29b80 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
29b90 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69  , const char*, i
29ba0 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f  nt n, void(*)(vo
29bb0 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74  id*));.int sqlit
29bc0 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 73  e3_bind_text16(s
29bd0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
29be0 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  t, const void*, 
29bf0 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  int, void(*)(voi
29c00 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  d*));.int sqlite
29c10 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 73 71 6c  3_bind_value(sql
29c20 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
29c30 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 76   const sqlite3_v
29c40 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69  alue*);.int sqli
29c50 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f  te3_bind_zeroblo
29c60 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  b(sqlite3_stmt*,
29c70 20 69 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f   int, int n);../
29c80 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e  *.** CAPI3REF: N
29c90 75 6d 62 65 72 20 4f 66 20 53 51 4c 20 50 61 72  umber Of SQL Par
29ca0 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 5e 54  ameters.**.** ^T
29cb0 68 69 73 20 72 6f 75 74 69 6e 65 20 63 61 6e 20  his routine can 
29cc0 62 65 20 75 73 65 64 20 74 6f 20 66 69 6e 64 20  be used to find 
29cd0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 5b 53  the number of [S
29ce0 51 4c 20 70 61 72 61 6d 65 74 65 72 73 5d 0a 2a  QL parameters].*
29cf0 2a 20 69 6e 20 61 20 5b 70 72 65 70 61 72 65 64  * in a [prepared
29d00 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 53 51   statement].  SQ
29d10 4c 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65  L parameters are
29d20 20 74 6f 6b 65 6e 73 20 6f 66 20 74 68 65 0a 2a   tokens of the.*
29d30 2a 20 66 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e  * form "?", "?NN
29d40 4e 22 2c 20 22 3a 41 41 41 22 2c 20 22 24 41 41  N", ":AAA", "$AA
29d50 41 22 2c 20 6f 72 20 22 40 41 41 41 22 20 74 68  A", or "@AAA" th
29d60 61 74 20 73 65 72 76 65 20 61 73 0a 2a 2a 20 70  at serve as.** p
29d70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20  laceholders for 
29d80 76 61 6c 75 65 73 20 74 68 61 74 20 61 72 65 20  values that are 
29d90 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
29da0 6f 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74  ob | bound].** t
29db0 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 73  o the parameters
29dc0 20 61 74 20 61 20 6c 61 74 65 72 20 74 69 6d 65   at a later time
29dd0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72  ..**.** ^(This r
29de0 6f 75 74 69 6e 65 20 61 63 74 75 61 6c 6c 79 20  outine actually 
29df0 72 65 74 75 72 6e 73 20 74 68 65 20 69 6e 64 65  returns the inde
29e00 78 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74  x of the largest
29e10 20 28 72 69 67 68 74 6d 6f 73 74 29 0a 2a 2a 20   (rightmost).** 
29e20 70 61 72 61 6d 65 74 65 72 2e 20 46 6f 72 20 61  parameter. For a
29e30 6c 6c 20 66 6f 72 6d 73 20 65 78 63 65 70 74 20  ll forms except 
29e40 3f 4e 4e 4e 2c 20 74 68 69 73 20 77 69 6c 6c 20  ?NNN, this will 
29e50 63 6f 72 72 65 73 70 6f 6e 64 20 74 6f 20 74 68  correspond to th
29e60 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 75  e.** number of u
29e70 6e 69 71 75 65 20 70 61 72 61 6d 65 74 65 72 73  nique parameters
29e80 2e 20 20 49 66 20 70 61 72 61 6d 65 74 65 72 73  .  If parameters
29e90 20 6f 66 20 74 68 65 20 3f 4e 4e 4e 20 66 6f 72   of the ?NNN for
29ea0 6d 20 61 72 65 20 75 73 65 64 2c 0a 2a 2a 20 74  m are used,.** t
29eb0 68 65 72 65 20 6d 61 79 20 62 65 20 67 61 70 73  here may be gaps
29ec0 20 69 6e 20 74 68 65 20 6c 69 73 74 2e 29 5e 0a   in the list.)^.
29ed0 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
29ee0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
29ef0 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28  ob|sqlite3_bind(
29f00 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
29f10 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e  bind_parameter_n
29f20 61 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b  ame()], and.** [
29f30 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
29f40 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e  ameter_index()].
29f50 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
29f60 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63  bind_parameter_c
29f70 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  ount(sqlite3_stm
29f80 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
29f90 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 41 20  3REF: Name Of A 
29fa0 48 6f 73 74 20 50 61 72 61 6d 65 74 65 72 0a 2a  Host Parameter.*
29fb0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
29fc0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
29fd0 5f 6e 61 6d 65 28 50 2c 4e 29 20 69 6e 74 65 72  _name(P,N) inter
29fe0 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20  face returns.** 
29ff0 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
2a000 4e 2d 74 68 20 5b 53 51 4c 20 70 61 72 61 6d 65  N-th [SQL parame
2a010 74 65 72 5d 20 69 6e 20 74 68 65 20 5b 70 72 65  ter] in the [pre
2a020 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2a030 20 50 2e 0a 2a 2a 20 5e 28 53 51 4c 20 70 61 72   P..** ^(SQL par
2a040 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 66  ameters of the f
2a050 6f 72 6d 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a  orm "?NNN" or ":
2a060 41 41 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f  AAA" or "@AAA" o
2a070 72 20 22 24 41 41 41 22 0a 2a 2a 20 68 61 76 65  r "$AAA".** have
2a080 20 61 20 6e 61 6d 65 20 77 68 69 63 68 20 69 73   a name which is
2a090 20 74 68 65 20 73 74 72 69 6e 67 20 22 3f 4e 4e   the string "?NN
2a0a0 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20  N" or ":AAA" or 
2a0b0 22 40 41 41 41 22 20 6f 72 20 22 24 41 41 41 22  "@AAA" or "$AAA"
2a0c0 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79  .** respectively
2a0d0 2e 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f  ..** In other wo
2a0e0 72 64 73 2c 20 74 68 65 20 69 6e 69 74 69 61 6c  rds, the initial
2a0f0 20 22 3a 22 20 6f 72 20 22 24 22 20 6f 72 20 22   ":" or "$" or "
2a100 40 22 20 6f 72 20 22 3f 22 0a 2a 2a 20 69 73 20  @" or "?".** is 
2a110 69 6e 63 6c 75 64 65 64 20 61 73 20 70 61 72 74  included as part
2a120 20 6f 66 20 74 68 65 20 6e 61 6d 65 2e 29 5e 0a   of the name.)^.
2a130 2a 2a 20 5e 50 61 72 61 6d 65 74 65 72 73 20 6f  ** ^Parameters o
2a140 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 22 20 77  f the form "?" w
2a150 69 74 68 6f 75 74 20 61 20 66 6f 6c 6c 6f 77 69  ithout a followi
2a160 6e 67 20 69 6e 74 65 67 65 72 20 68 61 76 65 20  ng integer have 
2a170 6e 6f 20 6e 61 6d 65 0a 2a 2a 20 61 6e 64 20 61  no name.** and a
2a180 72 65 20 72 65 66 65 72 72 65 64 20 74 6f 20 61  re referred to a
2a190 73 20 22 6e 61 6d 65 6c 65 73 73 22 20 6f 72 20  s "nameless" or 
2a1a0 22 61 6e 6f 6e 79 6d 6f 75 73 20 70 61 72 61 6d  "anonymous param
2a1b0 65 74 65 72 73 22 2e 0a 2a 2a 0a 2a 2a 20 5e 54  eters"..**.** ^T
2a1c0 68 65 20 66 69 72 73 74 20 68 6f 73 74 20 70 61  he first host pa
2a1d0 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69  rameter has an i
2a1e0 6e 64 65 78 20 6f 66 20 31 2c 20 6e 6f 74 20 30  ndex of 1, not 0
2a1f0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
2a200 76 61 6c 75 65 20 4e 20 69 73 20 6f 75 74 20 6f  value N is out o
2a210 66 20 72 61 6e 67 65 20 6f 72 20 69 66 20 74 68  f range or if th
2a220 65 20 4e 2d 74 68 20 70 61 72 61 6d 65 74 65 72  e N-th parameter
2a230 20 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c   is.** nameless,
2a240 20 74 68 65 6e 20 4e 55 4c 4c 20 69 73 20 72 65   then NULL is re
2a250 74 75 72 6e 65 64 2e 20 20 5e 54 68 65 20 72 65  turned.  ^The re
2a260 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73  turned string is
2a270 0a 2a 2a 20 61 6c 77 61 79 73 20 69 6e 20 55 54  .** always in UT
2a280 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 65 76 65  F-8 encoding eve
2a290 6e 20 69 66 20 74 68 65 20 6e 61 6d 65 64 20 70  n if the named p
2a2a0 61 72 61 6d 65 74 65 72 20 77 61 73 0a 2a 2a 20  arameter was.** 
2a2b0 6f 72 69 67 69 6e 61 6c 6c 79 20 73 70 65 63 69  originally speci
2a2c0 66 69 65 64 20 61 73 20 55 54 46 2d 31 36 20 69  fied as UTF-16 i
2a2d0 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  n [sqlite3_prepa
2a2e0 72 65 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73  re16()] or.** [s
2a2f0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
2a300 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65  _v2()]..**.** Se
2a310 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
2a320 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74  _bind_blob|sqlit
2a330 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b  e3_bind()],.** [
2a340 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
2a350 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c  ameter_count()],
2a360 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
2a370 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
2a380 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e  index()]..*/.con
2a390 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
2a3a0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
2a3b0 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
2a3c0 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  t*, int);../*.**
2a3d0 20 43 41 50 49 33 52 45 46 3a 20 49 6e 64 65 78   CAPI3REF: Index
2a3e0 20 4f 66 20 41 20 50 61 72 61 6d 65 74 65 72 20   Of A Parameter 
2a3f0 57 69 74 68 20 41 20 47 69 76 65 6e 20 4e 61 6d  With A Given Nam
2a400 65 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20  e.**.** ^Return 
2a410 74 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20  the index of an 
2a420 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 67 69  SQL parameter gi
2a430 76 65 6e 20 69 74 73 20 6e 61 6d 65 2e 20 20 5e  ven its name.  ^
2a440 54 68 65 0a 2a 2a 20 69 6e 64 65 78 20 76 61 6c  The.** index val
2a450 75 65 20 72 65 74 75 72 6e 65 64 20 69 73 20 73  ue returned is s
2a460 75 69 74 61 62 6c 65 20 66 6f 72 20 75 73 65 20  uitable for use 
2a470 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a  as the second.**
2a480 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73   parameter to [s
2a490 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
2a4a0 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d  |sqlite3_bind()]
2a4b0 2e 20 20 5e 41 20 7a 65 72 6f 0a 2a 2a 20 69 73  .  ^A zero.** is
2a4c0 20 72 65 74 75 72 6e 65 64 20 69 66 20 6e 6f 20   returned if no 
2a4d0 6d 61 74 63 68 69 6e 67 20 70 61 72 61 6d 65 74  matching paramet
2a4e0 65 72 20 69 73 20 66 6f 75 6e 64 2e 20 20 5e 54  er is found.  ^T
2a4f0 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  he parameter.** 
2a500 6e 61 6d 65 20 6d 75 73 74 20 62 65 20 67 69 76  name must be giv
2a510 65 6e 20 69 6e 20 55 54 46 2d 38 20 65 76 65 6e  en in UTF-8 even
2a520 20 69 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c   if the original
2a530 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 61   statement.** wa
2a540 73 20 70 72 65 70 61 72 65 64 20 66 72 6f 6d 20  s prepared from 
2a550 55 54 46 2d 31 36 20 74 65 78 74 20 75 73 69 6e  UTF-16 text usin
2a560 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  g [sqlite3_prepa
2a570 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a  re16_v2()]..**.*
2a580 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
2a590 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73  ite3_bind_blob|s
2a5a0 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a  qlite3_bind()],.
2a5b0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
2a5c0 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74  _parameter_count
2a5d0 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ()], and.** [sql
2a5e0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
2a5f0 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f  ter_index()]..*/
2a600 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
2a610 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65  d_parameter_inde
2a620 78 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  x(sqlite3_stmt*,
2a630 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
2a640 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  me);../*.** CAPI
2a650 33 52 45 46 3a 20 52 65 73 65 74 20 41 6c 6c 20  3REF: Reset All 
2a660 42 69 6e 64 69 6e 67 73 20 4f 6e 20 41 20 50 72  Bindings On A Pr
2a670 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
2a680 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 74 72 61 72 79  .**.** ^Contrary
2a690 20 74 6f 20 74 68 65 20 69 6e 74 75 69 74 69 6f   to the intuitio
2a6a0 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b 73 71 6c 69  n of many, [sqli
2a6b0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 64 6f 65  te3_reset()] doe
2a6c0 73 20 6e 6f 74 20 72 65 73 65 74 0a 2a 2a 20 74  s not reset.** t
2a6d0 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  he [sqlite3_bind
2a6e0 5f 62 6c 6f 62 20 7c 20 62 69 6e 64 69 6e 67 73  _blob | bindings
2a6f0 5d 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64  ] on a [prepared
2a700 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20   statement]..** 
2a710 5e 55 73 65 20 74 68 69 73 20 72 6f 75 74 69 6e  ^Use this routin
2a720 65 20 74 6f 20 72 65 73 65 74 20 61 6c 6c 20 68  e to reset all h
2a730 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 74  ost parameters t
2a740 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73  o NULL..*/.int s
2a750 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e  qlite3_clear_bin
2a760 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74  dings(sqlite3_st
2a770 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  mt*);../*.** CAP
2a780 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66  I3REF: Number Of
2a790 20 43 6f 6c 75 6d 6e 73 20 49 6e 20 41 20 52 65   Columns In A Re
2a7a0 73 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e  sult Set.**.** ^
2a7b0 52 65 74 75 72 6e 20 74 68 65 20 6e 75 6d 62 65  Return the numbe
2a7c0 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
2a7d0 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 72  the result set r
2a7e0 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a  eturned by the.*
2a7f0 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
2a800 65 6d 65 6e 74 5d 2e 20 5e 54 68 69 73 20 72 6f  ement]. ^This ro
2a810 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30 20  utine returns 0 
2a820 69 66 20 70 53 74 6d 74 20 69 73 20 61 6e 20 53  if pStmt is an S
2a830 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  QL.** statement 
2a840 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 72 65  that does not re
2a850 74 75 72 6e 20 64 61 74 61 20 28 66 6f 72 20 65  turn data (for e
2a860 78 61 6d 70 6c 65 20 61 6e 20 5b 55 50 44 41 54  xample an [UPDAT
2a870 45 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  E])..**.** See a
2a880 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 64 61  lso: [sqlite3_da
2a890 74 61 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69  ta_count()].*/.i
2a8a0 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nt sqlite3_colum
2a8b0 6e 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f  n_count(sqlite3_
2a8c0 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
2a8d0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
2a8e0 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 6e 20 41  olumn Names In A
2a8f0 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a   Result Set.**.*
2a900 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65  * ^These routine
2a910 73 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d  s return the nam
2a920 65 20 61 73 73 69 67 6e 65 64 20 74 6f 20 61 20  e assigned to a 
2a930 70 61 72 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d  particular colum
2a940 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65 73 75  n.** in the resu
2a950 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c  lt set of a [SEL
2a960 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20  ECT] statement. 
2a970 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f   ^The sqlite3_co
2a980 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69  lumn_name().** i
2a990 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
2a9a0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
2a9b0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
2a9c0 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20  UTF-8 string.** 
2a9d0 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  and sqlite3_colu
2a9e0 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 72 65 74 75  mn_name16() retu
2a9f0 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
2aa00 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
2aa10 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72  ed.** UTF-16 str
2aa20 69 6e 67 2e 20 20 5e 54 68 65 20 66 69 72 73 74  ing.  ^The first
2aa30 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
2aa40 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
2aa50 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61 74 20 69  ement].** that i
2aa60 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 5b 53  mplements the [S
2aa70 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74  ELECT] statement
2aa80 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61  . ^The second pa
2aa90 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a  rameter is the.*
2aaa0 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e  * column number.
2aab0 20 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20    ^The leftmost 
2aac0 63 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d 62 65 72  column is number
2aad0 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72   0..**.** ^The r
2aae0 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 70  eturned string p
2aaf0 6f 69 6e 74 65 72 20 69 73 20 76 61 6c 69 64 20  ointer is valid 
2ab00 75 6e 74 69 6c 20 65 69 74 68 65 72 20 74 68 65  until either the
2ab10 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2ab20 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20 64 65 73 74  ment].** is dest
2ab30 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74 65  royed by [sqlite
2ab40 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72  3_finalize()] or
2ab50 20 75 6e 74 69 6c 20 74 68 65 20 73 74 61 74 65   until the state
2ab60 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 69  ment is automati
2ab70 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61  cally.** reprepa
2ab80 72 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74  red by the first
2ab90 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
2aba0 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 61 20  3_step()] for a 
2abb0 70 61 72 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a  particular run.*
2abc0 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 6e  * or until the n
2abd0 65 78 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73  ext call to.** s
2abe0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
2abf0 6d 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  me() or sqlite3_
2ac00 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20  column_name16() 
2ac10 6f 6e 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 75  on the same colu
2ac20 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 73 71  mn..**.** ^If sq
2ac30 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66  lite3_malloc() f
2ac40 61 69 6c 73 20 64 75 72 69 6e 67 20 74 68 65 20  ails during the 
2ac50 70 72 6f 63 65 73 73 69 6e 67 20 6f 66 20 65 69  processing of ei
2ac60 74 68 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a 20  ther routine.** 
2ac70 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 64 75 72  (for example dur
2ac80 69 6e 67 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e  ing a conversion
2ac90 20 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55   from UTF-8 to U
2aca0 54 46 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a 2a  TF-16) then a.**
2acb0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73   NULL pointer is
2acc0 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
2acd0 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 61 20   ^The name of a 
2ace0 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73  result column is
2acf0 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68   the value of th
2ad00 65 20 22 41 53 22 20 63 6c 61 75 73 65 20 66 6f  e "AS" clause fo
2ad10 72 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 75 6d 6e  r.** that column
2ad20 2c 20 69 66 20 74 68 65 72 65 20 69 73 20 61 6e  , if there is an
2ad30 20 41 53 20 63 6c 61 75 73 65 2e 20 20 49 66 20   AS clause.  If 
2ad40 74 68 65 72 65 20 69 73 20 6e 6f 20 41 53 20 63  there is no AS c
2ad50 6c 61 75 73 65 0a 2a 2a 20 74 68 65 6e 20 74 68  lause.** then th
2ad60 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 6f  e name of the co
2ad70 6c 75 6d 6e 20 69 73 20 75 6e 73 70 65 63 69 66  lumn is unspecif
2ad80 69 65 64 20 61 6e 64 20 6d 61 79 20 63 68 61 6e  ied and may chan
2ad90 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72  ge from.** one r
2ada0 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65  elease of SQLite
2adb0 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2f   to the next..*/
2adc0 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
2add0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
2ade0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2adf0 69 6e 74 20 4e 29 3b 0a 63 6f 6e 73 74 20 76 6f  int N);.const vo
2ae00 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
2ae10 6d 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65  mn_name16(sqlite
2ae20 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b  3_stmt*, int N);
2ae30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2ae40 3a 20 53 6f 75 72 63 65 20 4f 66 20 44 61 74 61  : Source Of Data
2ae50 20 49 6e 20 41 20 51 75 65 72 79 20 52 65 73 75   In A Query Resu
2ae60 6c 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  lt.**.** ^These 
2ae70 72 6f 75 74 69 6e 65 73 20 70 72 6f 76 69 64 65  routines provide
2ae80 20 61 20 6d 65 61 6e 73 20 74 6f 20 64 65 74 65   a means to dete
2ae90 72 6d 69 6e 65 20 74 68 65 20 64 61 74 61 62 61  rmine the databa
2aea0 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 0a 2a  se, table, and.*
2aeb0 2a 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74  * table column t
2aec0 68 61 74 20 69 73 20 74 68 65 20 6f 72 69 67 69  hat is the origi
2aed0 6e 20 6f 66 20 61 20 70 61 72 74 69 63 75 6c 61  n of a particula
2aee0 72 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  r result column 
2aef0 69 6e 0a 2a 2a 20 5b 53 45 4c 45 43 54 5d 20 73  in.** [SELECT] s
2af00 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68  tatement..** ^Th
2af10 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61  e name of the da
2af20 74 61 62 61 73 65 20 6f 72 20 74 61 62 6c 65 20  tabase or table 
2af30 6f 72 20 63 6f 6c 75 6d 6e 20 63 61 6e 20 62 65  or column can be
2af40 20 72 65 74 75 72 6e 65 64 20 61 73 0a 2a 2a 20   returned as.** 
2af50 65 69 74 68 65 72 20 61 20 55 54 46 2d 38 20 6f  either a UTF-8 o
2af60 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e  r UTF-16 string.
2af70 20 20 5e 54 68 65 20 5f 64 61 74 61 62 61 73 65    ^The _database
2af80 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  _ routines retur
2af90 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73  n.** the databas
2afa0 65 20 6e 61 6d 65 2c 20 74 68 65 20 5f 74 61 62  e name, the _tab
2afb0 6c 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74  le_ routines ret
2afc0 75 72 6e 20 74 68 65 20 74 61 62 6c 65 20 6e 61  urn the table na
2afd0 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74 68 65 20 6f  me, and.** the o
2afe0 72 69 67 69 6e 5f 20 72 6f 75 74 69 6e 65 73 20  rigin_ routines 
2aff0 72 65 74 75 72 6e 20 74 68 65 20 63 6f 6c 75 6d  return the colum
2b000 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20  n name..** ^The 
2b010 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20  returned string 
2b020 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 74  is valid until t
2b030 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
2b040 74 65 6d 65 6e 74 5d 20 69 73 20 64 65 73 74 72  tement] is destr
2b050 6f 79 65 64 0a 2a 2a 20 75 73 69 6e 67 20 5b 73  oyed.** using [s
2b060 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2b070 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20  )] or until the 
2b080 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 75 74  statement is aut
2b090 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65  omatically.** re
2b0a0 70 72 65 70 61 72 65 64 20 62 79 20 74 68 65 20  prepared by the 
2b0b0 66 69 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73  first call to [s
2b0c0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 66  qlite3_step()] f
2b0d0 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  or a particular 
2b0e0 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20  run.** or until 
2b0f0 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61  the same informa
2b100 74 69 6f 6e 20 69 73 20 72 65 71 75 65 73 74 65  tion is requeste
2b110 64 0a 2a 2a 20 61 67 61 69 6e 20 69 6e 20 61 20  d.** again in a 
2b120 64 69 66 66 65 72 65 6e 74 20 65 6e 63 6f 64 69  different encodi
2b130 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e  ng..**.** ^The n
2b140 61 6d 65 73 20 72 65 74 75 72 6e 65 64 20 61 72  ames returned ar
2b150 65 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 75  e the original u
2b160 6e 2d 61 6c 69 61 73 65 64 20 6e 61 6d 65 73 20  n-aliased names 
2b170 6f 66 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  of the.** databa
2b180 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 20 63  se, table, and c
2b190 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  olumn..**.** ^Th
2b1a0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
2b1b0 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66   to these interf
2b1c0 61 63 65 73 20 69 73 20 61 20 5b 70 72 65 70 61  aces is a [prepa
2b1d0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a  red statement]..
2b1e0 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69  ** ^These functi
2b1f0 6f 6e 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72  ons return infor
2b200 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 74 68 65  mation about the
2b210 20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75   Nth result colu
2b220 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a  mn returned by.*
2b230 2a 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2c  * the statement,
2b240 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20   where N is the 
2b250 73 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20  second function 
2b260 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68  argument..** ^Th
2b270 65 20 6c 65 66 74 2d 6d 6f 73 74 20 63 6f 6c 75  e left-most colu
2b280 6d 6e 20 69 73 20 63 6f 6c 75 6d 6e 20 30 20 66  mn is column 0 f
2b290 6f 72 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  or these routine
2b2a0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  s..**.** ^If the
2b2b0 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75   Nth column retu
2b2c0 72 6e 65 64 20 62 79 20 74 68 65 20 73 74 61 74  rned by the stat
2b2d0 65 6d 65 6e 74 20 69 73 20 61 6e 20 65 78 70 72  ement is an expr
2b2e0 65 73 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62  ession or.** sub
2b2f0 71 75 65 72 79 20 61 6e 64 20 69 73 20 6e 6f 74  query and is not
2b300 20 61 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c   a column value,
2b310 20 74 68 65 6e 20 61 6c 6c 20 6f 66 20 74 68 65   then all of the
2b320 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74  se functions ret
2b330 75 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 5e 54  urn.** NULL.  ^T
2b340 68 65 73 65 20 72 6f 75 74 69 6e 65 20 6d 69 67  hese routine mig
2b350 68 74 20 61 6c 73 6f 20 72 65 74 75 72 6e 20 4e  ht also return N
2b360 55 4c 4c 20 69 66 20 61 20 6d 65 6d 6f 72 79 20  ULL if a memory 
2b370 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72  allocation error
2b380 0a 2a 2a 20 6f 63 63 75 72 73 2e 20 20 5e 4f 74  .** occurs.  ^Ot
2b390 68 65 72 77 69 73 65 2c 20 74 68 65 79 20 72 65  herwise, they re
2b3a0 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66  turn the name of
2b3b0 20 74 68 65 20 61 74 74 61 63 68 65 64 20 64 61   the attached da
2b3c0 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 0a 2a  tabase, table,.*
2b3d0 2a 20 6f 72 20 63 6f 6c 75 6d 6e 20 74 68 61 74  * or column that
2b3e0 20 71 75 65 72 79 20 72 65 73 75 6c 74 20 63 6f   query result co
2b3f0 6c 75 6d 6e 20 77 61 73 20 65 78 74 72 61 63 74  lumn was extract
2b400 65 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e  ed from..**.** ^
2b410 41 73 20 77 69 74 68 20 61 6c 6c 20 6f 74 68 65  As with all othe
2b420 72 20 53 51 4c 69 74 65 20 41 50 49 73 2c 20 74  r SQLite APIs, t
2b430 68 6f 73 65 20 77 68 6f 73 65 20 6e 61 6d 65 73  hose whose names
2b440 20 65 6e 64 20 77 69 74 68 20 22 31 36 22 20 72   end with "16" r
2b450 65 74 75 72 6e 0a 2a 2a 20 55 54 46 2d 31 36 20  eturn.** UTF-16 
2b460 65 6e 63 6f 64 65 64 20 73 74 72 69 6e 67 73 20  encoded strings 
2b470 61 6e 64 20 74 68 65 20 6f 74 68 65 72 20 66 75  and the other fu
2b480 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 55  nctions return U
2b490 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  TF-8..**.** ^The
2b4a0 73 65 20 41 50 49 73 20 61 72 65 20 6f 6e 6c 79  se APIs are only
2b4b0 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 74 68   available if th
2b4c0 65 20 6c 69 62 72 61 72 79 20 77 61 73 20 63 6f  e library was co
2b4d0 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a  mpiled with the.
2b4e0 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c  ** [SQLITE_ENABL
2b4f0 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54  E_COLUMN_METADAT
2b500 41 5d 20 43 2d 70 72 65 70 72 6f 63 65 73 73 6f  A] C-preprocesso
2b510 72 20 73 79 6d 62 6f 6c 2e 0a 2a 2a 0a 2a 2a 20  r symbol..**.** 
2b520 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74  If two or more t
2b530 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20  hreads call one 
2b540 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68 65 73 65  or more of these
2b550 20 72 6f 75 74 69 6e 65 73 20 61 67 61 69 6e 73   routines agains
2b560 74 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 70 72  t the same.** pr
2b570 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2b580 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 61 74 20 74   and column at t
2b590 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65  he same time the
2b5a0 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72  n the results ar
2b5b0 65 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a  e.** undefined..
2b5c0 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20  **.** If two or 
2b5d0 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63 61 6c  more threads cal
2b5e0 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a  l one or more.**
2b5f0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
2b600 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 20 7c  _database_name |
2b610 20 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 74 61   column metadata
2b620 20 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a 2a 20   interfaces].** 
2b630 66 6f 72 20 74 68 65 20 73 61 6d 65 20 5b 70 72  for the same [pr
2b640 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2b650 5d 20 61 6e 64 20 72 65 73 75 6c 74 20 63 6f 6c  ] and result col
2b660 75 6d 6e 0a 2a 2a 20 61 74 20 74 68 65 20 73 61  umn.** at the sa
2b670 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65  me time then the
2b680 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64   results are und
2b690 65 66 69 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e 73 74  efined..*/.const
2b6a0 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
2b6b0 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e  olumn_database_n
2b6c0 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
2b6d0 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f  *,int);.const vo
2b6e0 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
2b6f0 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65  mn_database_name
2b700 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
2b710 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61  ,int);.const cha
2b720 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
2b730 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 73 71 6c  n_table_name(sql
2b740 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
2b750 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
2b760 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c  ite3_column_tabl
2b770 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33  e_name16(sqlite3
2b780 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e  _stmt*,int);.con
2b790 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
2b7a0 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e  _column_origin_n
2b7b0 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
2b7c0 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f  *,int);.const vo
2b7d0 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
2b7e0 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36  mn_origin_name16
2b7f0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
2b800 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
2b810 33 52 45 46 3a 20 44 65 63 6c 61 72 65 64 20 44  3REF: Declared D
2b820 61 74 61 74 79 70 65 20 4f 66 20 41 20 51 75 65  atatype Of A Que
2b830 72 79 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20  ry Result.**.** 
2b840 5e 28 54 68 65 20 66 69 72 73 74 20 70 61 72 61  ^(The first para
2b850 6d 65 74 65 72 20 69 73 20 61 20 5b 70 72 65 70  meter is a [prep
2b860 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
2b870 0a 2a 2a 20 49 66 20 74 68 69 73 20 73 74 61 74  .** If this stat
2b880 65 6d 65 6e 74 20 69 73 20 61 20 5b 53 45 4c 45  ement is a [SELE
2b890 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 6e  CT] statement an
2b8a0 64 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e  d the Nth column
2b8b0 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 74 75 72   of the.** retur
2b8c0 6e 65 64 20 72 65 73 75 6c 74 20 73 65 74 20 6f  ned result set o
2b8d0 66 20 74 68 61 74 20 5b 53 45 4c 45 43 54 5d 20  f that [SELECT] 
2b8e0 69 73 20 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d  is a table colum
2b8f0 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70  n (not an.** exp
2b900 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75  ression or subqu
2b910 65 72 79 29 20 74 68 65 6e 20 74 68 65 20 64 65  ery) then the de
2b920 63 6c 61 72 65 64 20 74 79 70 65 20 6f 66 20 74  clared type of t
2b930 68 65 20 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75  he table.** colu
2b940 6d 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29  mn is returned.)
2b950 5e 20 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63  ^  ^If the Nth c
2b960 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73  olumn of the res
2b970 75 6c 74 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a  ult set is an.**
2b980 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73   expression or s
2b990 75 62 71 75 65 72 79 2c 20 74 68 65 6e 20 61 20  ubquery, then a 
2b9a0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20  NULL pointer is 
2b9b0 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 54 68  returned..** ^Th
2b9c0 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e  e returned strin
2b9d0 67 20 69 73 20 61 6c 77 61 79 73 20 55 54 46 2d  g is always UTF-
2b9e0 38 20 65 6e 63 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a  8 encoded..**.**
2b9f0 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20   ^(For example, 
2ba00 67 69 76 65 6e 20 74 68 65 20 64 61 74 61 62 61  given the databa
2ba10 73 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a  se schema:.**.**
2ba20 20 43 52 45 41 54 45 20 54 41 42 4c 45 20 74 31   CREATE TABLE t1
2ba30 28 63 31 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a  (c1 VARIANT);.**
2ba40 0a 2a 2a 20 61 6e 64 20 74 68 65 20 66 6f 6c 6c  .** and the foll
2ba50 6f 77 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20  owing statement 
2ba60 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 3a 0a  to be compiled:.
2ba70 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63 31 20  **.** SELECT c1 
2ba80 2b 20 31 2c 20 63 31 20 46 52 4f 4d 20 74 31 3b  + 1, c1 FROM t1;
2ba90 0a 2a 2a 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74  .**.** this rout
2baa0 69 6e 65 20 77 6f 75 6c 64 20 72 65 74 75 72 6e  ine would return
2bab0 20 74 68 65 20 73 74 72 69 6e 67 20 22 56 41 52   the string "VAR
2bac0 49 41 4e 54 22 20 66 6f 72 20 74 68 65 20 73 65  IANT" for the se
2bad0 63 6f 6e 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63  cond result.** c
2bae0 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e  olumn (i==1), an
2baf0 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  d a NULL pointer
2bb00 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 72   for the first r
2bb10 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d  esult column (i=
2bb20 3d 30 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51  =0).)^.**.** ^SQ
2bb30 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69  Lite uses dynami
2bb40 63 20 72 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e  c run-time typin
2bb50 67 2e 20 20 5e 53 6f 20 6a 75 73 74 20 62 65 63  g.  ^So just bec
2bb60 61 75 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a  ause a column.**
2bb70 20 69 73 20 64 65 63 6c 61 72 65 64 20 74 6f 20   is declared to 
2bb80 63 6f 6e 74 61 69 6e 20 61 20 70 61 72 74 69 63  contain a partic
2bb90 75 6c 61 72 20 74 79 70 65 20 64 6f 65 73 20 6e  ular type does n
2bba0 6f 74 20 6d 65 61 6e 20 74 68 61 74 20 74 68 65  ot mean that the
2bbb0 0a 2a 2a 20 64 61 74 61 20 73 74 6f 72 65 64 20  .** data stored 
2bbc0 69 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69  in that column i
2bbd0 73 20 6f 66 20 74 68 65 20 64 65 63 6c 61 72 65  s of the declare
2bbe0 64 20 74 79 70 65 2e 20 20 53 51 4c 69 74 65 20  d type.  SQLite 
2bbf0 69 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74  is.** strongly t
2bc00 79 70 65 64 2c 20 62 75 74 20 74 68 65 20 74 79  yped, but the ty
2bc10 70 69 6e 67 20 69 73 20 64 79 6e 61 6d 69 63 20  ping is dynamic 
2bc20 6e 6f 74 20 73 74 61 74 69 63 2e 20 20 5e 54 79  not static.  ^Ty
2bc30 70 65 0a 2a 2a 20 69 73 20 61 73 73 6f 63 69 61  pe.** is associa
2bc40 74 65 64 20 77 69 74 68 20 69 6e 64 69 76 69 64  ted with individ
2bc50 75 61 6c 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20  ual values, not 
2bc60 77 69 74 68 20 74 68 65 20 63 6f 6e 74 61 69 6e  with the contain
2bc70 65 72 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68  ers.** used to h
2bc80 6f 6c 64 20 74 68 6f 73 65 20 76 61 6c 75 65 73  old those values
2bc90 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20  ..*/.const char 
2bca0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
2bcb0 64 65 63 6c 74 79 70 65 28 73 71 6c 69 74 65 33  decltype(sqlite3
2bcc0 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e  _stmt*,int);.con
2bcd0 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
2bce0 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65  _column_decltype
2bcf0 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
2bd00 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ,int);../*.** CA
2bd10 50 49 33 52 45 46 3a 20 45 76 61 6c 75 61 74 65  PI3REF: Evaluate
2bd20 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e   An SQL Statemen
2bd30 74 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61 20  t.**.** After a 
2bd40 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2bd50 65 6e 74 5d 20 68 61 73 20 62 65 65 6e 20 70 72  ent] has been pr
2bd60 65 70 61 72 65 64 20 75 73 69 6e 67 20 65 69 74  epared using eit
2bd70 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  her.** [sqlite3_
2bd80 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
2bd90 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2bda0 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65  e16_v2()] or one
2bdb0 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79 0a 2a   of the legacy.*
2bdc0 2a 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71  * interfaces [sq
2bdd0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d  lite3_prepare()]
2bde0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   or [sqlite3_pre
2bdf0 70 61 72 65 31 36 28 29 5d 2c 20 74 68 69 73 20  pare16()], this 
2be00 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74  function.** must
2be10 20 62 65 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f   be called one o
2be20 72 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f 20  r more times to 
2be30 65 76 61 6c 75 61 74 65 20 74 68 65 20 73 74 61  evaluate the sta
2be40 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68  tement..**.** Th
2be50 65 20 64 65 74 61 69 6c 73 20 6f 66 20 74 68 65  e details of the
2be60 20 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68 65   behavior of the
2be70 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
2be80 69 6e 74 65 72 66 61 63 65 20 64 65 70 65 6e 64  interface depend
2be90 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 74  .** on whether t
2bea0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73  he statement was
2beb0 20 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 20   prepared using 
2bec0 74 68 65 20 6e 65 77 65 72 20 22 76 32 22 20 69  the newer "v2" i
2bed0 6e 74 65 72 66 61 63 65 0a 2a 2a 20 5b 73 71 6c  nterface.** [sql
2bee0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
2bef0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
2bf00 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20  prepare16_v2()] 
2bf10 6f 72 20 74 68 65 20 6f 6c 64 65 72 20 6c 65 67  or the older leg
2bf20 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  acy.** interface
2bf30 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2bf40 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  e()] and [sqlite
2bf50 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2e 20  3_prepare16()]. 
2bf60 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 0a   The use of the.
2bf70 2a 2a 20 6e 65 77 20 22 76 32 22 20 69 6e 74 65  ** new "v2" inte
2bf80 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65  rface is recomme
2bf90 6e 64 65 64 20 66 6f 72 20 6e 65 77 20 61 70 70  nded for new app
2bfa0 6c 69 63 61 74 69 6f 6e 73 20 62 75 74 20 74 68  lications but th
2bfb0 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65  e legacy.** inte
2bfc0 72 66 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74 69  rface will conti
2bfd0 6e 75 65 20 74 6f 20 62 65 20 73 75 70 70 6f 72  nue to be suppor
2bfe0 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74  ted..**.** ^In t
2bff0 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66  he legacy interf
2c000 61 63 65 2c 20 74 68 65 20 72 65 74 75 72 6e 20  ace, the return 
2c010 76 61 6c 75 65 20 77 69 6c 6c 20 62 65 20 65 69  value will be ei
2c020 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 42 55 53  ther [SQLITE_BUS
2c030 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44  Y],.** [SQLITE_D
2c040 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f  ONE], [SQLITE_RO
2c050 57 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  W], [SQLITE_ERRO
2c060 52 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d  R], or [SQLITE_M
2c070 49 53 55 53 45 5d 2e 0a 2a 2a 20 5e 57 69 74 68  ISUSE]..** ^With
2c080 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66   the "v2" interf
2c090 61 63 65 2c 20 61 6e 79 20 6f 66 20 74 68 65 20  ace, any of the 
2c0a0 6f 74 68 65 72 20 5b 72 65 73 75 6c 74 20 63 6f  other [result co
2c0b0 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65  des] or.** [exte
2c0c0 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
2c0d0 73 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74 75  s] might be retu
2c0e0 72 6e 65 64 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a  rned as well..**
2c0f0 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 42 55 53  .** ^[SQLITE_BUS
2c100 59 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  Y] means that th
2c110 65 20 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e  e database engin
2c120 65 20 77 61 73 20 75 6e 61 62 6c 65 20 74 6f 20  e was unable to 
2c130 61 63 71 75 69 72 65 20 74 68 65 0a 2a 2a 20 64  acquire the.** d
2c140 61 74 61 62 61 73 65 20 6c 6f 63 6b 73 20 69 74  atabase locks it
2c150 20 6e 65 65 64 73 20 74 6f 20 64 6f 20 69 74 73   needs to do its
2c160 20 6a 6f 62 2e 20 20 5e 49 66 20 74 68 65 20 73   job.  ^If the s
2c170 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 43  tatement is a [C
2c180 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63  OMMIT].** or occ
2c190 75 72 73 20 6f 75 74 73 69 64 65 20 6f 66 20 61  urs outside of a
2c1a0 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73  n explicit trans
2c1b0 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75  action, then you
2c1c0 20 63 61 6e 20 72 65 74 72 79 20 74 68 65 0a 2a   can retry the.*
2c1d0 2a 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 49 66  * statement.  If
2c1e0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
2c1f0 73 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49 54 5d  s not a [COMMIT]
2c200 20 61 6e 64 20 6f 63 63 75 72 73 20 77 69 74 68   and occurs with
2c210 69 6e 20 61 6e 0a 2a 2a 20 65 78 70 6c 69 63 69  in an.** explici
2c220 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 68  t transaction th
2c230 65 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f  en you should ro
2c240 6c 6c 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73  llback the trans
2c250 61 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a  action before.**
2c260 20 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a   continuing..**.
2c270 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 44 4f 4e 45  ** ^[SQLITE_DONE
2c280 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  ] means that the
2c290 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73 20 66   statement has f
2c2a0 69 6e 69 73 68 65 64 20 65 78 65 63 75 74 69 6e  inished executin
2c2b0 67 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c  g.** successfull
2c2c0 79 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70  y.  sqlite3_step
2c2d0 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65  () should not be
2c2e0 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e   called again on
2c2f0 20 74 68 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a   this virtual.**
2c300 20 6d 61 63 68 69 6e 65 20 77 69 74 68 6f 75 74   machine without
2c310 20 66 69 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b   first calling [
2c320 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
2c330 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 76 69   to reset the vi
2c340 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65  rtual.** machine
2c350 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69   back to its ini
2c360 74 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a  tial state..**.*
2c370 2a 20 5e 49 66 20 74 68 65 20 53 51 4c 20 73 74  * ^If the SQL st
2c380 61 74 65 6d 65 6e 74 20 62 65 69 6e 67 20 65 78  atement being ex
2c390 65 63 75 74 65 64 20 72 65 74 75 72 6e 73 20 61  ecuted returns a
2c3a0 6e 79 20 64 61 74 61 2c 20 74 68 65 6e 20 5b 53  ny data, then [S
2c3b0 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73  QLITE_ROW].** is
2c3c0 20 72 65 74 75 72 6e 65 64 20 65 61 63 68 20 74   returned each t
2c3d0 69 6d 65 20 61 20 6e 65 77 20 72 6f 77 20 6f 66  ime a new row of
2c3e0 20 64 61 74 61 20 69 73 20 72 65 61 64 79 20 66   data is ready f
2c3f0 6f 72 20 70 72 6f 63 65 73 73 69 6e 67 20 62 79  or processing by
2c400 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20   the.** caller. 
2c410 54 68 65 20 76 61 6c 75 65 73 20 6d 61 79 20 62  The values may b
2c420 65 20 61 63 63 65 73 73 65 64 20 75 73 69 6e 67  e accessed using
2c430 20 74 68 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 63   the [column acc
2c440 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a  ess functions]..
2c450 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  ** sqlite3_step(
2c460 29 20 69 73 20 63 61 6c 6c 65 64 20 61 67 61 69  ) is called agai
2c470 6e 20 74 6f 20 72 65 74 72 69 65 76 65 20 74 68  n to retrieve th
2c480 65 20 6e 65 78 74 20 72 6f 77 20 6f 66 20 64 61  e next row of da
2c490 74 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49  ta..**.** ^[SQLI
2c4a0 54 45 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20  TE_ERROR] means 
2c4b0 74 68 61 74 20 61 20 72 75 6e 2d 74 69 6d 65 20  that a run-time 
2c4c0 65 72 72 6f 72 20 28 73 75 63 68 20 61 73 20 61  error (such as a
2c4d0 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76   constraint.** v
2c4e0 69 6f 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f 63  iolation) has oc
2c4f0 63 75 72 72 65 64 2e 20 20 73 71 6c 69 74 65 33  curred.  sqlite3
2c500 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e  _step() should n
2c510 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61  ot be called aga
2c520 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e  in on.** the VM.
2c530 20 4d 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f   More informatio
2c540 6e 20 6d 61 79 20 62 65 20 66 6f 75 6e 64 20 62  n may be found b
2c550 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  y calling [sqlit
2c560 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a  e3_errmsg()]..**
2c570 20 5e 57 69 74 68 20 74 68 65 20 6c 65 67 61 63   ^With the legac
2c580 79 20 69 6e 74 65 72 66 61 63 65 2c 20 61 20 6d  y interface, a m
2c590 6f 72 65 20 73 70 65 63 69 66 69 63 20 65 72 72  ore specific err
2c5a0 6f 72 20 63 6f 64 65 20 28 66 6f 72 20 65 78 61  or code (for exa
2c5b0 6d 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  mple,.** [SQLITE
2c5c0 5f 49 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53 51  _INTERRUPT], [SQ
2c5d0 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53  LITE_SCHEMA], [S
2c5e0 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20  QLITE_CORRUPT], 
2c5f0 61 6e 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a  and so forth).**
2c600 20 63 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 64   can be obtained
2c610 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c   by calling [sql
2c620 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e  ite3_reset()] on
2c630 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
2c640 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 5e  d statement].  ^
2c650 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74 65  In the "v2" inte
2c660 72 66 61 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f  rface,.** the mo
2c670 72 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f  re specific erro
2c680 72 20 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e  r code is return
2c690 65 64 20 64 69 72 65 63 74 6c 79 20 62 79 20 73  ed directly by s
2c6a0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a  qlite3_step()..*
2c6b0 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53  *.** [SQLITE_MIS
2c6c0 55 53 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20  USE] means that 
2c6d0 74 68 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65  the this routine
2c6e0 20 77 61 73 20 63 61 6c 6c 65 64 20 69 6e 61 70   was called inap
2c6f0 70 72 6f 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20  propriately..** 
2c700 50 65 72 68 61 70 73 20 69 74 20 77 61 73 20 63  Perhaps it was c
2c710 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 70 72 65 70  alled on a [prep
2c720 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2c730 74 68 61 74 20 68 61 73 0a 2a 2a 20 61 6c 72 65  that has.** alre
2c740 61 64 79 20 62 65 65 6e 20 5b 73 71 6c 69 74 65  ady been [sqlite
2c750 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e  3_finalize | fin
2c760 61 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e  alized] or on on
2c770 65 20 74 68 61 74 20 68 61 64 0a 2a 2a 20 70 72  e that had.** pr
2c780 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65  eviously returne
2c790 64 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  d [SQLITE_ERROR]
2c7a0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45   or [SQLITE_DONE
2c7b0 5d 2e 20 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a  ].  Or it could.
2c7c0 2a 2a 20 62 65 20 74 68 65 20 63 61 73 65 20 74  ** be the case t
2c7d0 68 61 74 20 74 68 65 20 73 61 6d 65 20 64 61 74  hat the same dat
2c7e0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2c7f0 20 69 73 20 62 65 69 6e 67 20 75 73 65 64 20 62   is being used b
2c800 79 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65  y two or.** more
2c810 20 74 68 72 65 61 64 73 20 61 74 20 74 68 65 20   threads at the 
2c820 73 61 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74  same moment in t
2c830 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 61  ime..**.** For a
2c840 6c 6c 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  ll versions of S
2c850 51 4c 69 74 65 20 75 70 20 74 6f 20 61 6e 64 20  QLite up to and 
2c860 69 6e 63 6c 75 64 69 6e 67 20 33 2e 36 2e 32 33  including 3.6.23
2c870 2e 31 2c 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a  .1, a call to.**
2c880 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2c890 29 5d 20 77 61 73 20 72 65 71 75 69 72 65 64 20  )] was required 
2c8a0 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 73 74  after sqlite3_st
2c8b0 65 70 28 29 20 72 65 74 75 72 6e 65 64 20 61 6e  ep() returned an
2c8c0 79 74 68 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20  ything.** other 
2c8d0 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57  than [SQLITE_ROW
2c8e0 5d 20 62 65 66 6f 72 65 20 61 6e 79 20 73 75 62  ] before any sub
2c8f0 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69  sequent invocati
2c900 6f 6e 20 6f 66 0a 2a 2a 20 73 71 6c 69 74 65 33  on of.** sqlite3
2c910 5f 73 74 65 70 28 29 2e 20 20 46 61 69 6c 75 72  _step().  Failur
2c920 65 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 70  e to reset the p
2c930 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2c940 74 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c  t using .** [sql
2c950 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 77 6f  ite3_reset()] wo
2c960 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61 6e  uld result in an
2c970 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
2c980 20 72 65 74 75 72 6e 20 66 72 6f 6d 0a 2a 2a 20   return from.** 
2c990 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20  sqlite3_step(). 
2c9a0 20 42 75 74 20 61 66 74 65 72 20 76 65 72 73 69   But after versi
2c9b0 6f 6e 20 33 2e 36 2e 32 33 2e 31 2c 20 73 71 6c  on 3.6.23.1, sql
2c9c0 69 74 65 33 5f 73 74 65 70 28 29 20 62 65 67 61  ite3_step() bega
2c9d0 6e 0a 2a 2a 20 63 61 6c 6c 69 6e 67 20 5b 73 71  n.** calling [sq
2c9e0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 61  lite3_reset()] a
2c9f0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e 20  utomatically in 
2ca00 74 68 69 73 20 63 69 72 63 75 6d 73 74 61 6e 63  this circumstanc
2ca10 65 20 72 61 74 68 65 72 0a 2a 2a 20 74 68 61 6e  e rather.** than
2ca20 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49   returning [SQLI
2ca30 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 54 68 69  TE_MISUSE].  Thi
2ca40 73 20 69 73 20 6e 6f 74 20 63 6f 6e 73 69 64 65  s is not conside
2ca50 72 65 64 20 61 20 63 6f 6d 70 61 74 69 62 69 6c  red a compatibil
2ca60 69 74 79 0a 2a 2a 20 62 72 65 61 6b 20 62 65 63  ity.** break bec
2ca70 61 75 73 65 20 61 6e 79 20 61 70 70 6c 69 63 61  ause any applica
2ca80 74 69 6f 6e 20 74 68 61 74 20 65 76 65 72 20 72  tion that ever r
2ca90 65 63 65 69 76 65 73 20 61 6e 20 53 51 4c 49 54  eceives an SQLIT
2caa0 45 5f 4d 49 53 55 53 45 20 65 72 72 6f 72 0a 2a  E_MISUSE error.*
2cab0 2a 20 69 73 20 62 72 6f 6b 65 6e 20 62 79 20 64  * is broken by d
2cac0 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 65 20  efinition.  The 
2cad0 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54  [SQLITE_OMIT_AUT
2cae0 4f 52 45 53 45 54 5d 20 63 6f 6d 70 69 6c 65 2d  ORESET] compile-
2caf0 74 69 6d 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 63  time option.** c
2cb00 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72 65  an be used to re
2cb10 73 74 6f 72 65 20 74 68 65 20 6c 65 67 61 63 79  store the legacy
2cb20 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a   behavior..**.**
2cb30 20 3c 62 3e 47 6f 6f 66 79 20 49 6e 74 65 72 66   <b>Goofy Interf
2cb40 61 63 65 20 41 6c 65 72 74 3a 3c 2f 62 3e 20 49  ace Alert:</b> I
2cb50 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74  n the legacy int
2cb60 65 72 66 61 63 65 2c 20 74 68 65 20 73 71 6c 69  erface, the sqli
2cb70 74 65 33 5f 73 74 65 70 28 29 0a 2a 2a 20 41 50  te3_step().** AP
2cb80 49 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73  I always returns
2cb90 20 61 20 67 65 6e 65 72 69 63 20 65 72 72 6f 72   a generic error
2cba0 20 63 6f 64 65 2c 20 5b 53 51 4c 49 54 45 5f 45   code, [SQLITE_E
2cbb0 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67  RROR], following
2cbc0 20 61 6e 79 0a 2a 2a 20 65 72 72 6f 72 20 6f 74   any.** error ot
2cbd0 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
2cbe0 5f 42 55 53 59 5d 20 61 6e 64 20 5b 53 51 4c 49  _BUSY] and [SQLI
2cbf0 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 59 6f 75  TE_MISUSE].  You
2cc00 20 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73   must call.** [s
2cc10 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
2cc20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  or [sqlite3_fina
2cc30 6c 69 7a 65 28 29 5d 20 69 6e 20 6f 72 64 65 72  lize()] in order
2cc40 20 74 6f 20 66 69 6e 64 20 6f 6e 65 20 6f 66 20   to find one of 
2cc50 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20  the.** specific 
2cc60 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 74 68  [error codes] th
2cc70 61 74 20 62 65 74 74 65 72 20 64 65 73 63 72 69  at better descri
2cc80 62 65 73 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a  bes the error..*
2cc90 2a 20 57 65 20 61 64 6d 69 74 20 74 68 61 74 20  * We admit that 
2cca0 74 68 69 73 20 69 73 20 61 20 67 6f 6f 66 79 20  this is a goofy 
2ccb0 64 65 73 69 67 6e 2e 20 20 54 68 65 20 70 72 6f  design.  The pro
2ccc0 62 6c 65 6d 20 68 61 73 20 62 65 65 6e 20 66 69  blem has been fi
2ccd0 78 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  xed.** with the 
2cce0 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2e 20  "v2" interface. 
2ccf0 20 49 66 20 79 6f 75 20 70 72 65 70 61 72 65 20   If you prepare 
2cd00 61 6c 6c 20 6f 66 20 79 6f 75 72 20 53 51 4c 20  all of your SQL 
2cd10 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 73  statements.** us
2cd20 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69  ing either [sqli
2cd30 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
2cd40 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ] or [sqlite3_pr
2cd50 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 69 6e  epare16_v2()] in
2cd60 73 74 65 61 64 0a 2a 2a 20 6f 66 20 74 68 65 20  stead.** of the 
2cd70 6c 65 67 61 63 79 20 5b 73 71 6c 69 74 65 33 5f  legacy [sqlite3_
2cd80 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b  prepare()] and [
2cd90 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
2cda0 36 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 2c  6()] interfaces,
2cdb0 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6d 6f 72  .** then the mor
2cdc0 65 20 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f  e specific [erro
2cdd0 72 20 63 6f 64 65 73 5d 20 61 72 65 20 72 65 74  r codes] are ret
2cde0 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79 0a 2a  urned directly.*
2cdf0 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65  * by sqlite3_ste
2ce00 70 28 29 2e 20 20 54 68 65 20 75 73 65 20 6f 66  p().  The use of
2ce10 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66   the "v2" interf
2ce20 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64  ace is recommend
2ce30 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ed..*/.int sqlit
2ce40 65 33 5f 73 74 65 70 28 73 71 6c 69 74 65 33 5f  e3_step(sqlite3_
2ce50 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  stmt*);../*.** C
2ce60 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20  API3REF: Number 
2ce70 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20  of columns in a 
2ce80 72 65 73 75 6c 74 20 73 65 74 0a 2a 2a 0a 2a 2a  result set.**.**
2ce90 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61   ^The sqlite3_da
2cea0 74 61 5f 63 6f 75 6e 74 28 50 29 20 69 6e 74 65  ta_count(P) inte
2ceb0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68  rface returns th
2cec0 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  e number of colu
2ced0 6d 6e 73 20 69 6e 20 74 68 65 0a 2a 2a 20 63 75  mns in the.** cu
2cee0 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65  rrent row of the
2cef0 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 5b   result set of [
2cf00 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2cf10 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 49 66 20 70 72  nt] P..** ^If pr
2cf20 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2cf30 20 50 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65   P does not have
2cf40 20 72 65 73 75 6c 74 73 20 72 65 61 64 79 20 74   results ready t
2cf50 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 28 76 69 61  o return.** (via
2cf60 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 5b 73   calls to the [s
2cf70 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e  qlite3_column_in
2cf80 74 20 7c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  t | sqlite3_colu
2cf90 6d 6e 5f 2a 28 29 5d 20 6f 66 0a 2a 2a 20 69 6e  mn_*()] of.** in
2cfa0 74 65 72 66 61 63 65 73 29 20 74 68 65 6e 20 73  terfaces) then s
2cfb0 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e  qlite3_data_coun
2cfc0 74 28 50 29 20 72 65 74 75 72 6e 73 20 30 2e 0a  t(P) returns 0..
2cfd0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2cfe0 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f  data_count(P) ro
2cff0 75 74 69 6e 65 20 61 6c 73 6f 20 72 65 74 75 72  utine also retur
2d000 6e 73 20 30 20 69 66 20 50 20 69 73 20 61 20 4e  ns 0 if P is a N
2d010 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20  ULL pointer..** 
2d020 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74  ^The sqlite3_dat
2d030 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75 74 69  a_count(P) routi
2d040 6e 65 20 72 65 74 75 72 6e 73 20 30 20 69 66 20  ne returns 0 if 
2d050 74 68 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c  the previous cal
2d060 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  l to.** [sqlite3
2d070 5f 73 74 65 70 5d 28 50 29 20 72 65 74 75 72 6e  _step](P) return
2d080 65 64 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d  ed [SQLITE_DONE]
2d090 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
2d0a0 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 0a 2a 2a  data_count(P).**
2d0b0 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6e 6f 6e   will return non
2d0c0 2d 7a 65 72 6f 20 69 66 20 70 72 65 76 69 6f 75  -zero if previou
2d0d0 73 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  s call to [sqlit
2d0e0 65 33 5f 73 74 65 70 5d 28 50 29 20 72 65 74 75  e3_step](P) retu
2d0f0 72 6e 65 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  rned.** [SQLITE_
2d100 52 4f 57 5d 2c 20 65 78 63 65 70 74 20 69 6e 20  ROW], except in 
2d110 74 68 65 20 63 61 73 65 20 6f 66 20 74 68 65 20  the case of the 
2d120 5b 50 52 41 47 4d 41 20 69 6e 63 72 65 6d 65 6e  [PRAGMA incremen
2d130 74 61 6c 5f 76 61 63 75 75 6d 5d 0a 2a 2a 20 77  tal_vacuum].** w
2d140 68 65 72 65 20 69 74 20 61 6c 77 61 79 73 20 72  here it always r
2d150 65 74 75 72 6e 73 20 7a 65 72 6f 20 73 69 6e 63  eturns zero sinc
2d160 65 20 65 61 63 68 20 73 74 65 70 20 6f 66 20 74  e each step of t
2d170 68 61 74 20 6d 75 6c 74 69 2d 73 74 65 70 0a 2a  hat multi-step.*
2d180 2a 20 70 72 61 67 6d 61 20 72 65 74 75 72 6e 73  * pragma returns
2d190 20 30 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 64 61   0 columns of da
2d1a0 74 61 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  ta..**.** See al
2d1b0 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  so: [sqlite3_col
2d1c0 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a  umn_count()].*/.
2d1d0 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 61 74 61  int sqlite3_data
2d1e0 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73  _count(sqlite3_s
2d1f0 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
2d200 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75  .** CAPI3REF: Fu
2d210 6e 64 61 6d 65 6e 74 61 6c 20 44 61 74 61 74 79  ndamental Dataty
2d220 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  pes.** KEYWORDS:
2d230 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 2a 2a 0a   SQLITE_TEXT.**.
2d240 2a 2a 20 5e 28 45 76 65 72 79 20 76 61 6c 75 65  ** ^(Every value
2d250 20 69 6e 20 53 51 4c 69 74 65 20 68 61 73 20 6f   in SQLite has o
2d260 6e 65 20 6f 66 20 66 69 76 65 20 66 75 6e 64 61  ne of five funda
2d270 6d 65 6e 74 61 6c 20 64 61 74 61 74 79 70 65 73  mental datatypes
2d280 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
2d290 3c 6c 69 3e 20 36 34 2d 62 69 74 20 73 69 67 6e  <li> 64-bit sign
2d2a0 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c  ed integer.** <l
2d2b0 69 3e 20 36 34 2d 62 69 74 20 49 45 45 45 20 66  i> 64-bit IEEE f
2d2c0 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75  loating point nu
2d2d0 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72  mber.** <li> str
2d2e0 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42  ing.** <li> BLOB
2d2f0 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a  .** <li> NULL.**
2d300 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54   </ul>)^.**.** T
2d310 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61  hese constants a
2d320 72 65 20 63 6f 64 65 73 20 66 6f 72 20 65 61 63  re codes for eac
2d330 68 20 6f 66 20 74 68 6f 73 65 20 74 79 70 65 73  h of those types
2d340 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ..**.** Note tha
2d350 74 20 74 68 65 20 53 51 4c 49 54 45 5f 54 45 58  t the SQLITE_TEX
2d360 54 20 63 6f 6e 73 74 61 6e 74 20 77 61 73 20 61  T constant was a
2d370 6c 73 6f 20 75 73 65 64 20 69 6e 20 53 51 4c 69  lso used in SQLi
2d380 74 65 20 76 65 72 73 69 6f 6e 20 32 0a 2a 2a 20  te version 2.** 
2d390 66 6f 72 20 61 20 63 6f 6d 70 6c 65 74 65 6c 79  for a completely
2d3a0 20 64 69 66 66 65 72 65 6e 74 20 6d 65 61 6e 69   different meani
2d3b0 6e 67 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68  ng.  Software th
2d3c0 61 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74  at links against
2d3d0 20 62 6f 74 68 0a 2a 2a 20 53 51 4c 69 74 65 20   both.** SQLite 
2d3e0 76 65 72 73 69 6f 6e 20 32 20 61 6e 64 20 53 51  version 2 and SQ
2d3f0 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 20 73  Lite version 3 s
2d400 68 6f 75 6c 64 20 75 73 65 20 53 51 4c 49 54 45  hould use SQLITE
2d410 33 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53  3_TEXT, not.** S
2d420 51 4c 49 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23  QLITE_TEXT..*/.#
2d430 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
2d440 54 45 47 45 52 20 20 31 0a 23 64 65 66 69 6e 65  TEGER  1.#define
2d450 20 53 51 4c 49 54 45 5f 46 4c 4f 41 54 20 20 20   SQLITE_FLOAT   
2d460 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   2.#define SQLIT
2d470 45 5f 42 4c 4f 42 20 20 20 20 20 34 0a 23 64 65  E_BLOB     4.#de
2d480 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 55 4c 4c  fine SQLITE_NULL
2d490 20 20 20 20 20 35 0a 23 69 66 64 65 66 20 53 51       5.#ifdef SQ
2d4a0 4c 49 54 45 5f 54 45 58 54 0a 23 20 75 6e 64 65  LITE_TEXT.# unde
2d4b0 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 65  f SQLITE_TEXT.#e
2d4c0 6c 73 65 0a 23 20 64 65 66 69 6e 65 20 53 51 4c  lse.# define SQL
2d4d0 49 54 45 5f 54 45 58 54 20 20 20 20 20 33 0a 23  ITE_TEXT     3.#
2d4e0 65 6e 64 69 66 0a 23 64 65 66 69 6e 65 20 53 51  endif.#define SQ
2d4f0 4c 49 54 45 33 5f 54 45 58 54 20 20 20 20 20 33  LITE3_TEXT     3
2d500 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2d510 3a 20 52 65 73 75 6c 74 20 56 61 6c 75 65 73 20  : Result Values 
2d520 46 72 6f 6d 20 41 20 51 75 65 72 79 0a 2a 2a 20  From A Query.** 
2d530 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d  KEYWORDS: {colum
2d540 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f  n access functio
2d550 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ns}.**.** These 
2d560 72 6f 75 74 69 6e 65 73 20 66 6f 72 6d 20 74 68  routines form th
2d570 65 20 22 72 65 73 75 6c 74 20 73 65 74 22 20 69  e "result set" i
2d580 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
2d590 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
2d5a0 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69  return informati
2d5b0 6f 6e 20 61 62 6f 75 74 20 61 20 73 69 6e 67 6c  on about a singl
2d5c0 65 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20  e column of the 
2d5d0 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65 73 75 6c  current.** resul
2d5e0 74 20 72 6f 77 20 6f 66 20 61 20 71 75 65 72 79  t row of a query
2d5f0 2e 20 20 5e 49 6e 20 65 76 65 72 79 20 63 61 73  .  ^In every cas
2d600 65 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  e the first argu
2d610 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65  ment is a pointe
2d620 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 70 72 65  r.** to the [pre
2d630 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2d640 20 74 68 61 74 20 69 73 20 62 65 69 6e 67 20 65   that is being e
2d650 76 61 6c 75 61 74 65 64 20 28 74 68 65 20 5b 73  valuated (the [s
2d660 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a 2a  qlite3_stmt*].**
2d670 20 74 68 61 74 20 77 61 73 20 72 65 74 75 72 6e   that was return
2d680 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
2d690 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
2d6a0 72 20 6f 6e 65 20 6f 66 20 69 74 73 20 76 61 72  r one of its var
2d6b0 69 61 6e 74 73 29 0a 2a 2a 20 61 6e 64 20 74 68  iants).** and th
2d6c0 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
2d6d0 74 20 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f  t is the index o
2d6e0 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 66 6f 72  f the column for
2d6f0 20 77 68 69 63 68 20 69 6e 66 6f 72 6d 61 74 69   which informati
2d700 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20  on.** should be 
2d710 72 65 74 75 72 6e 65 64 2e 20 5e 54 68 65 20 6c  returned. ^The l
2d720 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f  eftmost column o
2d730 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
2d740 20 68 61 73 20 74 68 65 20 69 6e 64 65 78 20 30   has the index 0
2d750 2e 0a 2a 2a 20 5e 54 68 65 20 6e 75 6d 62 65 72  ..** ^The number
2d760 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74   of columns in t
2d770 68 65 20 72 65 73 75 6c 74 20 63 61 6e 20 62 65  he result can be
2d780 20 64 65 74 65 72 6d 69 6e 65 64 20 75 73 69 6e   determined usin
2d790 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  g.** [sqlite3_co
2d7a0 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 2e 0a 2a  lumn_count()]..*
2d7b0 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53 51 4c 20  *.** If the SQL 
2d7c0 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e  statement does n
2d7d0 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 70 6f 69  ot currently poi
2d7e0 6e 74 20 74 6f 20 61 20 76 61 6c 69 64 20 72 6f  nt to a valid ro
2d7f0 77 2c 20 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20  w, or if the.** 
2d800 63 6f 6c 75 6d 6e 20 69 6e 64 65 78 20 69 73 20  column index is 
2d810 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c 20 74 68  out of range, th
2d820 65 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65  e result is unde
2d830 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 73 65 20  fined..** These 
2d840 72 6f 75 74 69 6e 65 73 20 6d 61 79 20 6f 6e 6c  routines may onl
2d850 79 20 62 65 20 63 61 6c 6c 65 64 20 77 68 65 6e  y be called when
2d860 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
2d870 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c   call to.** [sql
2d880 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73  ite3_step()] has
2d890 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54   returned [SQLIT
2d8a0 45 5f 52 4f 57 5d 20 61 6e 64 20 6e 65 69 74 68  E_ROW] and neith
2d8b0 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72  er.** [sqlite3_r
2d8c0 65 73 65 74 28 29 5d 20 6e 6f 72 20 5b 73 71 6c  eset()] nor [sql
2d8d0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
2d8e0 20 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c 65   have been calle
2d8f0 64 20 73 75 62 73 65 71 75 65 6e 74 6c 79 2e 0a  d subsequently..
2d900 2a 2a 20 49 66 20 61 6e 79 20 6f 66 20 74 68 65  ** If any of the
2d910 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
2d920 63 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71  called after [sq
2d930 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
2d940 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  r.** [sqlite3_fi
2d950 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74  nalize()] or aft
2d960 65 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  er [sqlite3_step
2d970 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64  ()] has returned
2d980 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74  .** something ot
2d990 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
2d9a0 5f 52 4f 57 5d 2c 20 74 68 65 20 72 65 73 75 6c  _ROW], the resul
2d9b0 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64  ts are undefined
2d9c0 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c 69 74 65 33  ..** If [sqlite3
2d9d0 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c  _step()] or [sql
2d9e0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72  ite3_reset()] or
2d9f0 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
2da00 7a 65 28 29 5d 0a 2a 2a 20 61 72 65 20 63 61 6c  ze()].** are cal
2da10 6c 65 64 20 66 72 6f 6d 20 61 20 64 69 66 66 65  led from a diffe
2da20 72 65 6e 74 20 74 68 72 65 61 64 20 77 68 69 6c  rent thread whil
2da30 65 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72  e any of these r
2da40 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20 70  outines.** are p
2da50 65 6e 64 69 6e 67 2c 20 74 68 65 6e 20 74 68 65  ending, then the
2da60 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64   results are und
2da70 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  efined..**.** ^T
2da80 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  he sqlite3_colum
2da90 6e 5f 74 79 70 65 28 29 20 72 6f 75 74 69 6e 65  n_type() routine
2daa0 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20   returns the.** 
2dab0 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20  [SQLITE_INTEGER 
2dac0 7c 20 64 61 74 61 74 79 70 65 20 63 6f 64 65 5d  | datatype code]
2dad0 20 66 6f 72 20 74 68 65 20 69 6e 69 74 69 61 6c   for the initial
2dae0 20 64 61 74 61 20 74 79 70 65 0a 2a 2a 20 6f 66   data type.** of
2daf0 20 74 68 65 20 72 65 73 75 6c 74 20 63 6f 6c 75   the result colu
2db00 6d 6e 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e  mn.  ^The return
2db10 65 64 20 76 61 6c 75 65 20 69 73 20 6f 6e 65 20  ed value is one 
2db20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47  of [SQLITE_INTEG
2db30 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ER],.** [SQLITE_
2db40 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f  FLOAT], [SQLITE_
2db50 54 45 58 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 42  TEXT], [SQLITE_B
2db60 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  LOB], or [SQLITE
2db70 5f 4e 55 4c 4c 5d 2e 20 20 54 68 65 20 76 61 6c  _NULL].  The val
2db80 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62  ue.** returned b
2db90 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
2dba0 5f 74 79 70 65 28 29 20 69 73 20 6f 6e 6c 79 20  _type() is only 
2dbb0 6d 65 61 6e 69 6e 67 66 75 6c 20 69 66 20 6e 6f  meaningful if no
2dbc0 20 74 79 70 65 0a 2a 2a 20 63 6f 6e 76 65 72 73   type.** convers
2dbd0 69 6f 6e 73 20 68 61 76 65 20 6f 63 63 75 72 72  ions have occurr
2dbe0 65 64 20 61 73 20 64 65 73 63 72 69 62 65 64 20  ed as described 
2dbf0 62 65 6c 6f 77 2e 20 20 41 66 74 65 72 20 61 20  below.  After a 
2dc00 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2c  type conversion,
2dc10 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 72 65  .** the value re
2dc20 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
2dc30 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20  3_column_type() 
2dc40 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 46  is undefined.  F
2dc50 75 74 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e  uture.** version
2dc60 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20  s of SQLite may 
2dc70 63 68 61 6e 67 65 20 74 68 65 20 62 65 68 61 76  change the behav
2dc80 69 6f 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 63  ior of sqlite3_c
2dc90 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20  olumn_type().** 
2dca0 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 74 79 70 65  following a type
2dcb0 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a   conversion..**.
2dcc0 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
2dcd0 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55  t is a BLOB or U
2dce0 54 46 2d 38 20 73 74 72 69 6e 67 20 74 68 65 6e  TF-8 string then
2dcf0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c   the sqlite3_col
2dd00 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20 72  umn_bytes().** r
2dd10 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
2dd20 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
2dd30 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20  es in that BLOB 
2dd40 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49  or string..** ^I
2dd50 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
2dd60 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2c  a UTF-16 string,
2dd70 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f   then sqlite3_co
2dd80 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 63 6f 6e  lumn_bytes() con
2dd90 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72  verts.** the str
2dda0 69 6e 67 20 74 6f 20 55 54 46 2d 38 20 61 6e 64  ing to UTF-8 and
2ddb0 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68   then returns th
2ddc0 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
2ddd0 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  s..** ^If the re
2dde0 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69  sult is a numeri
2ddf0 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c  c value then sql
2de00 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2de10 73 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c  s() uses.** [sql
2de20 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d  ite3_snprintf()]
2de30 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74   to convert that
2de40 20 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d   value to a UTF-
2de50 38 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74  8 string and ret
2de60 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62  urns.** the numb
2de70 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
2de80 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e  hat string..** ^
2de90 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
2dea0 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69   NULL, then sqli
2deb0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2dec0 28 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e  () returns zero.
2ded0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72  .**.** ^If the r
2dee0 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20  esult is a BLOB 
2def0 6f 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67  or UTF-16 string
2df00 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65   then the sqlite
2df10 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
2df20 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65  ().** routine re
2df30 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
2df40 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61   of bytes in tha
2df50 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67  t BLOB or string
2df60 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73  ..** ^If the res
2df70 75 6c 74 20 69 73 20 61 20 55 54 46 2d 38 20 73  ult is a UTF-8 s
2df80 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69  tring, then sqli
2df90 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2dfa0 31 36 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a  16() converts.**
2dfb0 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55   the string to U
2dfc0 54 46 2d 31 36 20 61 6e 64 20 74 68 65 6e 20 72  TF-16 and then r
2dfd0 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
2dfe0 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e  r of bytes..** ^
2dff0 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
2e000 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65   a numeric value
2e010 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f   then sqlite3_co
2e020 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 75  lumn_bytes16() u
2e030 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ses.** [sqlite3_
2e040 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63  snprintf()] to c
2e050 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c 75  onvert that valu
2e060 65 20 74 6f 20 61 20 55 54 46 2d 31 36 20 73 74  e to a UTF-16 st
2e070 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73  ring and returns
2e080 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  .** the number o
2e090 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20  f bytes in that 
2e0a0 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74  string..** ^If t
2e0b0 68 65 20 72 65 73 75 6c 74 20 69 73 20 4e 55 4c  he result is NUL
2e0c0 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  L, then sqlite3_
2e0d0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
2e0e0 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a   returns zero..*
2e0f0 2a 0a 2a 2a 20 5e 54 68 65 20 76 61 6c 75 65 73  *.** ^The values
2e100 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71   returned by [sq
2e110 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2e120 65 73 28 29 5d 20 61 6e 64 20 0a 2a 2a 20 5b 73  es()] and .** [s
2e130 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2e140 74 65 73 31 36 28 29 5d 20 64 6f 20 6e 6f 74 20  tes16()] do not 
2e150 69 6e 63 6c 75 64 65 20 74 68 65 20 7a 65 72 6f  include the zero
2e160 20 74 65 72 6d 69 6e 61 74 6f 72 73 20 61 74 20   terminators at 
2e170 74 68 65 20 65 6e 64 0a 2a 2a 20 6f 66 20 74 68  the end.** of th
2e180 65 20 73 74 72 69 6e 67 2e 20 20 5e 46 6f 72 20  e string.  ^For 
2e190 63 6c 61 72 69 74 79 3a 20 74 68 65 20 76 61 6c  clarity: the val
2e1a0 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 0a  ues returned by.
2e1b0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
2e1c0 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e 64 20  mn_bytes()] and 
2e1d0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
2e1e0 62 79 74 65 73 31 36 28 29 5d 20 61 72 65 20 74  bytes16()] are t
2e1f0 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20  he number of.** 
2e200 62 79 74 65 73 20 69 6e 20 74 68 65 20 73 74 72  bytes in the str
2e210 69 6e 67 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d  ing, not the num
2e220 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72  ber of character
2e230 73 2e 0a 2a 2a 0a 2a 2a 20 5e 53 74 72 69 6e 67  s..**.** ^String
2e240 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  s returned by sq
2e250 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
2e260 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  t() and sqlite3_
2e270 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 2c  column_text16(),
2e280 0a 2a 2a 20 65 76 65 6e 20 65 6d 70 74 79 20 73  .** even empty s
2e290 74 72 69 6e 67 73 2c 20 61 72 65 20 61 6c 77 61  trings, are alwa
2e2a0 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  ys zero-terminat
2e2b0 65 64 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e  ed.  ^The return
2e2c0 0a 2a 2a 20 76 61 6c 75 65 20 66 72 6f 6d 20 73  .** value from s
2e2d0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
2e2e0 6f 62 28 29 20 66 6f 72 20 61 20 7a 65 72 6f 2d  ob() for a zero-
2e2f0 6c 65 6e 67 74 68 20 42 4c 4f 42 20 69 73 20 61  length BLOB is a
2e300 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
2e310 2a 0a 2a 2a 20 5e 54 68 65 20 6f 62 6a 65 63 74  *.** ^The object
2e320 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71   returned by [sq
2e330 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c  lite3_column_val
2e340 75 65 28 29 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b  ue()] is an.** [
2e350 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
2e360 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
2e370 74 2e 20 20 41 6e 20 75 6e 70 72 6f 74 65 63 74  t.  An unprotect
2e380 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
2e390 20 6f 62 6a 65 63 74 0a 2a 2a 20 6d 61 79 20 6f   object.** may o
2e3a0 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69 74 68  nly be used with
2e3b0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76   [sqlite3_bind_v
2e3c0 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  alue()] and [sql
2e3d0 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75  ite3_result_valu
2e3e0 65 28 29 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20  e()]..** If the 
2e3f0 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c  [unprotected sql
2e400 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
2e410 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a  ct returned by.*
2e420 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
2e430 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 73  n_value()] is us
2e440 65 64 20 69 6e 20 61 6e 79 20 6f 74 68 65 72 20  ed in any other 
2e450 77 61 79 2c 20 69 6e 63 6c 75 64 69 6e 67 20 63  way, including c
2e460 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75 74 69  alls.** to routi
2e470 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65  nes like [sqlite
2e480 33 5f 76 61 6c 75 65 5f 69 6e 74 28 29 5d 2c 20  3_value_int()], 
2e490 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
2e4a0 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73  ext()],.** or [s
2e4b0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74  qlite3_value_byt
2e4c0 65 73 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20  es()], then the 
2e4d0 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65  behavior is unde
2e4e0 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  fined..**.** The
2e4f0 73 65 20 72 6f 75 74 69 6e 65 73 20 61 74 74 65  se routines atte
2e500 6d 70 74 20 74 6f 20 63 6f 6e 76 65 72 74 20 74  mpt to convert t
2e510 68 65 20 76 61 6c 75 65 20 77 68 65 72 65 20 61  he value where a
2e520 70 70 72 6f 70 72 69 61 74 65 2e 20 20 5e 46 6f  ppropriate.  ^Fo
2e530 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 69 66  r.** example, if
2e540 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65   the internal re
2e550 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 69 73 20  presentation is 
2e560 46 4c 4f 41 54 20 61 6e 64 20 61 20 74 65 78 74  FLOAT and a text
2e570 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 72 65   result.** is re
2e580 71 75 65 73 74 65 64 2c 20 5b 73 71 6c 69 74 65  quested, [sqlite
2e590 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 69 73  3_snprintf()] is
2e5a0 20 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79   used internally
2e5b0 20 74 6f 20 70 65 72 66 6f 72 6d 20 74 68 65 0a   to perform the.
2e5c0 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 75  ** conversion au
2e5d0 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 5e 28  tomatically.  ^(
2e5e0 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 61  The following ta
2e5f0 62 6c 65 20 64 65 74 61 69 6c 73 20 74 68 65 20  ble details the 
2e600 63 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a 2a 20 74  conversions.** t
2e610 68 61 74 20 61 72 65 20 61 70 70 6c 69 65 64 3a  hat are applied:
2e620 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
2e630 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f  te>.** <table bo
2e640 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72  rder="1">.** <tr
2e650 3e 3c 74 68 3e 20 49 6e 74 65 72 6e 61 6c 3c 62  ><th> Internal<b
2e660 72 3e 54 79 70 65 20 3c 74 68 3e 20 52 65 71 75  r>Type <th> Requ
2e670 65 73 74 65 64 3c 62 72 3e 54 79 70 65 20 3c 74  ested<br>Type <t
2e680 68 3e 20 20 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a  h>  Conversion.*
2e690 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e  *.** <tr><td>  N
2e6a0 55 4c 4c 20 20 20 20 3c 74 64 3e 20 49 4e 54 45  ULL    <td> INTE
2e6b0 47 45 52 20 20 20 3c 74 64 3e 20 52 65 73 75 6c  GER   <td> Resul
2e6c0 74 20 69 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74  t is 0.** <tr><t
2e6d0 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e  d>  NULL    <td>
2e6e0 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20    FLOAT    <td> 
2e6f0 52 65 73 75 6c 74 20 69 73 20 30 2e 30 0a 2a 2a  Result is 0.0.**
2e700 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20   <tr><td>  NULL 
2e710 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20     <td>   TEXT  
2e720 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73    <td> Result is
2e730 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a   a NULL pointer.
2e740 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c  ** <tr><td>  NUL
2e750 4c 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42  L    <td>   BLOB
2e760 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20      <td> Result 
2e770 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
2e780 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e  r.** <tr><td> IN
2e790 54 45 47 45 52 20 20 3c 74 64 3e 20 20 46 4c 4f  TEGER  <td>  FLO
2e7a0 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65  AT    <td> Conve
2e7b0 72 74 20 66 72 6f 6d 20 69 6e 74 65 67 65 72 20  rt from integer 
2e7c0 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e  to float.** <tr>
2e7d0 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74  <td> INTEGER  <t
2e7e0 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64  d>   TEXT    <td
2e7f0 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e  > ASCII renderin
2e800 67 20 6f 66 20 74 68 65 20 69 6e 74 65 67 65 72  g of the integer
2e810 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54  .** <tr><td> INT
2e820 45 47 45 52 20 20 3c 74 64 3e 20 20 20 42 4c 4f  EGER  <td>   BLO
2e830 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20 61  B    <td> Same a
2e840 73 20 49 4e 54 45 47 45 52 2d 3e 54 45 58 54 0a  s INTEGER->TEXT.
2e850 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f  ** <tr><td>  FLO
2e860 41 54 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45  AT   <td> INTEGE
2e870 52 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20  R   <td> [CAST] 
2e880 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74  to INTEGER.** <t
2e890 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20  r><td>  FLOAT   
2e8a0 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c  <td>   TEXT    <
2e8b0 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72  td> ASCII render
2e8c0 69 6e 67 20 6f 66 20 74 68 65 20 66 6c 6f 61 74  ing of the float
2e8d0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c  .** <tr><td>  FL
2e8e0 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f  OAT   <td>   BLO
2e8f0 42 20 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d  B    <td> [CAST]
2e900 20 74 6f 20 42 4c 4f 42 0a 2a 2a 20 3c 74 72 3e   to BLOB.** <tr>
2e910 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74  <td>  TEXT    <t
2e920 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64  d> INTEGER   <td
2e930 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49 4e 54 45  > [CAST] to INTE
2e940 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  GER.** <tr><td> 
2e950 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20 46   TEXT    <td>  F
2e960 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 5b 43 41  LOAT    <td> [CA
2e970 53 54 5d 20 74 6f 20 52 45 41 4c 0a 2a 2a 20 3c  ST] to REAL.** <
2e980 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20  tr><td>  TEXT   
2e990 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20   <td>   BLOB    
2e9a0 3c 74 64 3e 20 4e 6f 20 63 68 61 6e 67 65 0a 2a  <td> No change.*
2e9b0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42  * <tr><td>  BLOB
2e9c0 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52      <td> INTEGER
2e9d0 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74     <td> [CAST] t
2e9e0 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72  o INTEGER.** <tr
2e9f0 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c  ><td>  BLOB    <
2ea00 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74  td>  FLOAT    <t
2ea10 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 52 45 41  d> [CAST] to REA
2ea20 4c 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42  L.** <tr><td>  B
2ea30 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 20 54 45  LOB    <td>   TE
2ea40 58 54 20 20 20 20 3c 74 64 3e 20 41 64 64 20 61  XT    <td> Add a
2ea50 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
2ea60 20 69 66 20 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f   if needed.** </
2ea70 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63  table>.** </bloc
2ea80 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20  kquote>)^.**.** 
2ea90 54 68 65 20 74 61 62 6c 65 20 61 62 6f 76 65 20  The table above 
2eaa0 6d 61 6b 65 73 20 72 65 66 65 72 65 6e 63 65 20  makes reference 
2eab0 74 6f 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69  to standard C li
2eac0 62 72 61 72 79 20 66 75 6e 63 74 69 6f 6e 73 20  brary functions 
2ead0 61 74 6f 69 28 29 0a 2a 2a 20 61 6e 64 20 61 74  atoi().** and at
2eae0 6f 66 28 29 2e 20 20 53 51 4c 69 74 65 20 64 6f  of().  SQLite do
2eaf0 65 73 20 6e 6f 74 20 72 65 61 6c 6c 79 20 75 73  es not really us
2eb00 65 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  e these function
2eb10 73 2e 20 20 49 74 20 68 61 73 20 69 74 73 0a 2a  s.  It has its.*
2eb20 2a 20 6f 77 6e 20 65 71 75 69 76 61 6c 65 6e 74  * own equivalent
2eb30 20 69 6e 74 65 72 6e 61 6c 20 72 6f 75 74 69 6e   internal routin
2eb40 65 73 2e 20 20 54 68 65 20 61 74 6f 69 28 29 20  es.  The atoi() 
2eb50 61 6e 64 20 61 74 6f 66 28 29 20 6e 61 6d 65 73  and atof() names
2eb60 20 61 72 65 0a 2a 2a 20 75 73 65 64 20 69 6e 20   are.** used in 
2eb70 74 68 65 20 74 61 62 6c 65 20 66 6f 72 20 62 72  the table for br
2eb80 65 76 69 74 79 20 61 6e 64 20 62 65 63 61 75 73  evity and becaus
2eb90 65 20 74 68 65 79 20 61 72 65 20 66 61 6d 69 6c  e they are famil
2eba0 69 61 72 20 74 6f 20 6d 6f 73 74 0a 2a 2a 20 43  iar to most.** C
2ebb0 20 70 72 6f 67 72 61 6d 6d 65 72 73 2e 0a 2a 2a   programmers..**
2ebc0 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 77 68  .** Note that wh
2ebd0 65 6e 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69  en type conversi
2ebe0 6f 6e 73 20 6f 63 63 75 72 2c 20 70 6f 69 6e 74  ons occur, point
2ebf0 65 72 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ers returned by 
2ec00 70 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 74  prior.** calls t
2ec10 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  o sqlite3_column
2ec20 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33  _blob(), sqlite3
2ec30 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20  _column_text(), 
2ec40 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  and/or.** sqlite
2ec50 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
2ec60 29 20 6d 61 79 20 62 65 20 69 6e 76 61 6c 69 64  ) may be invalid
2ec70 61 74 65 64 2e 0a 2a 2a 20 54 79 70 65 20 63 6f  ated..** Type co
2ec80 6e 76 65 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f  nversions and po
2ec90 69 6e 74 65 72 20 69 6e 76 61 6c 69 64 61 74 69  inter invalidati
2eca0 6f 6e 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a  ons might occur.
2ecb0 2a 2a 20 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77  ** in the follow
2ecc0 69 6e 67 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a  ing cases:.**.**
2ecd0 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68   <ul>.** <li> Th
2ece0 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e  e initial conten
2ecf0 74 20 69 73 20 61 20 42 4c 4f 42 20 61 6e 64 20  t is a BLOB and 
2ed00 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2ed10 65 78 74 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20  ext() or.**     
2ed20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2ed30 74 65 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c  text16() is call
2ed40 65 64 2e 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d  ed.  A zero-term
2ed50 69 6e 61 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20  inator might.** 
2ed60 20 20 20 20 20 6e 65 65 64 20 74 6f 20 62 65 20       need to be 
2ed70 61 64 64 65 64 20 74 6f 20 74 68 65 20 73 74 72  added to the str
2ed80 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69  ing.</li>.** <li
2ed90 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f  > The initial co
2eda0 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 38 20 74  ntent is UTF-8 t
2edb0 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  ext and sqlite3_
2edc0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
2edd0 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69   or.**      sqli
2ede0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
2edf0 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20  6() is called.  
2ee00 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74  The content must
2ee10 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a   be converted.**
2ee20 20 20 20 20 20 20 74 6f 20 55 54 46 2d 31 36 2e        to UTF-16.
2ee30 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68  </li>.** <li> Th
2ee40 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e  e initial conten
2ee50 74 20 69 73 20 55 54 46 2d 31 36 20 74 65 78 74  t is UTF-16 text
2ee60 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c   and sqlite3_col
2ee70 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a  umn_bytes() or.*
2ee80 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63  *      sqlite3_c
2ee90 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69 73 20  olumn_text() is 
2eea0 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e  called.  The con
2eeb0 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e  tent must be con
2eec0 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74  verted.**      t
2eed0 6f 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a  o UTF-8.</li>.**
2eee0 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 43 6f   </ul>.**.** ^Co
2eef0 6e 76 65 72 73 69 6f 6e 73 20 62 65 74 77 65 65  nversions betwee
2ef00 6e 20 55 54 46 2d 31 36 62 65 20 61 6e 64 20 55  n UTF-16be and U
2ef10 54 46 2d 31 36 6c 65 20 61 72 65 20 61 6c 77 61  TF-16le are alwa
2ef20 79 73 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65  ys done in place
2ef30 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69   and do.** not i
2ef40 6e 76 61 6c 69 64 61 74 65 20 61 20 70 72 69 6f  nvalidate a prio
2ef50 72 20 70 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67  r pointer, thoug
2ef60 68 20 6f 66 20 63 6f 75 72 73 65 20 74 68 65 20  h of course the 
2ef70 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 62  content of the b
2ef80 75 66 66 65 72 0a 2a 2a 20 74 68 61 74 20 74 68  uffer.** that th
2ef90 65 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 20  e prior pointer 
2efa0 72 65 66 65 72 65 6e 63 65 73 20 77 69 6c 6c 20  references will 
2efb0 68 61 76 65 20 62 65 65 6e 20 6d 6f 64 69 66 69  have been modifi
2efc0 65 64 2e 20 20 4f 74 68 65 72 20 6b 69 6e 64 73  ed.  Other kinds
2efd0 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f  .** of conversio
2efe0 6e 20 61 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c  n are done in pl
2eff0 61 63 65 20 77 68 65 6e 20 69 74 20 69 73 20 70  ace when it is p
2f000 6f 73 73 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d  ossible, but som
2f010 65 74 69 6d 65 73 20 74 68 65 79 0a 2a 2a 20 61  etimes they.** a
2f020 72 65 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20  re not possible 
2f030 61 6e 64 20 69 6e 20 74 68 6f 73 65 20 63 61 73  and in those cas
2f040 65 73 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72  es prior pointer
2f050 73 20 61 72 65 20 69 6e 76 61 6c 69 64 61 74 65  s are invalidate
2f060 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 61 66  d..**.** The saf
2f070 65 73 74 20 61 6e 64 20 65 61 73 69 65 73 74 20  est and easiest 
2f080 74 6f 20 72 65 6d 65 6d 62 65 72 20 70 6f 6c 69  to remember poli
2f090 63 79 20 69 73 20 74 6f 20 69 6e 76 6f 6b 65 20  cy is to invoke 
2f0a0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a  these routines.*
2f0b0 2a 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20  * in one of the 
2f0c0 66 6f 6c 6c 6f 77 69 6e 67 20 77 61 79 73 3a 0a  following ways:.
2f0d0 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c  **.** <ul>.**  <
2f0e0 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  li>sqlite3_colum
2f0f0 6e 5f 74 65 78 74 28 29 20 66 6f 6c 6c 6f 77 65  n_text() followe
2f100 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
2f110 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e  umn_bytes()</li>
2f120 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33  .**  <li>sqlite3
2f130 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66  _column_blob() f
2f140 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74  ollowed by sqlit
2f150 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
2f160 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73  )</li>.**  <li>s
2f170 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2f180 78 74 31 36 28 29 20 66 6f 6c 6c 6f 77 65 64 20  xt16() followed 
2f190 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
2f1a0 6e 5f 62 79 74 65 73 31 36 28 29 3c 2f 6c 69 3e  n_bytes16()</li>
2f1b0 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
2f1c0 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  In other words, 
2f1d0 79 6f 75 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20  you should call 
2f1e0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2f1f0 65 78 74 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65  ext(),.** sqlite
2f200 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c  3_column_blob(),
2f210 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   or sqlite3_colu
2f220 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 69 72 73  mn_text16() firs
2f230 74 20 74 6f 20 66 6f 72 63 65 20 74 68 65 20 72  t to force the r
2f240 65 73 75 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74 68  esult.** into th
2f250 65 20 64 65 73 69 72 65 64 20 66 6f 72 6d 61 74  e desired format
2f260 2c 20 74 68 65 6e 20 69 6e 76 6f 6b 65 20 73 71  , then invoke sq
2f270 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2f280 65 73 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74  es() or.** sqlit
2f290 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
2f2a0 36 28 29 20 74 6f 20 66 69 6e 64 20 74 68 65 20  6() to find the 
2f2b0 73 69 7a 65 20 6f 66 20 74 68 65 20 72 65 73 75  size of the resu
2f2c0 6c 74 2e 20 20 44 6f 20 6e 6f 74 20 6d 69 78 20  lt.  Do not mix 
2f2d0 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c 69  calls.** to sqli
2f2e0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
2f2f0 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c  ) or sqlite3_col
2f300 75 6d 6e 5f 62 6c 6f 62 28 29 20 77 69 74 68 20  umn_blob() with 
2f310 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69  calls to.** sqli
2f320 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2f330 31 36 28 29 2c 20 61 6e 64 20 64 6f 20 6e 6f 74  16(), and do not
2f340 20 6d 69 78 20 63 61 6c 6c 73 20 74 6f 20 73 71   mix calls to sq
2f350 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
2f360 74 31 36 28 29 0a 2a 2a 20 77 69 74 68 20 63 61  t16().** with ca
2f370 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  lls to sqlite3_c
2f380 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 2e 0a 2a  olumn_bytes()..*
2f390 2a 0a 2a 2a 20 5e 54 68 65 20 70 6f 69 6e 74 65  *.** ^The pointe
2f3a0 72 73 20 72 65 74 75 72 6e 65 64 20 61 72 65 20  rs returned are 
2f3b0 76 61 6c 69 64 20 75 6e 74 69 6c 20 61 20 74 79  valid until a ty
2f3c0 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63  pe conversion oc
2f3d0 63 75 72 73 20 61 73 0a 2a 2a 20 64 65 73 63 72  curs as.** descr
2f3e0 69 62 65 64 20 61 62 6f 76 65 2c 20 6f 72 20 75  ibed above, or u
2f3f0 6e 74 69 6c 20 5b 73 71 6c 69 74 65 33 5f 73 74  ntil [sqlite3_st
2f400 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  ep()] or [sqlite
2f410 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a  3_reset()] or.**
2f420 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
2f430 7a 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e  ze()] is called.
2f440 20 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 73 70    ^The memory sp
2f450 61 63 65 20 75 73 65 64 20 74 6f 20 68 6f 6c 64  ace used to hold
2f460 20 73 74 72 69 6e 67 73 0a 2a 2a 20 61 6e 64 20   strings.** and 
2f470 42 4c 4f 42 73 20 69 73 20 66 72 65 65 64 20 61  BLOBs is freed a
2f480 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 44  utomatically.  D
2f490 6f 20 3c 62 3e 6e 6f 74 3c 2f 62 3e 20 70 61 73  o <b>not</b> pas
2f4a0 73 20 74 68 65 20 70 6f 69 6e 74 65 72 73 20 72  s the pointers r
2f4b0 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  eturned.** from 
2f4c0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
2f4d0 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65  blob()], [sqlite
2f4e0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d  3_column_text()]
2f4f0 2c 20 65 74 63 2e 20 69 6e 74 6f 0a 2a 2a 20 5b  , etc. into.** [
2f500 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e  sqlite3_free()].
2f510 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 20 6d 65  .**.** ^(If a me
2f520 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
2f530 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72  error occurs dur
2f540 69 6e 67 20 74 68 65 20 65 76 61 6c 75 61 74 69  ing the evaluati
2f550 6f 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20  on of any.** of 
2f560 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2c 20  these routines, 
2f570 61 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20  a default value 
2f580 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68  is returned.  Th
2f590 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 0a  e default value.
2f5a0 2a 2a 20 69 73 20 65 69 74 68 65 72 20 74 68 65  ** is either the
2f5b0 20 69 6e 74 65 67 65 72 20 30 2c 20 74 68 65 20   integer 0, the 
2f5c0 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e  floating point n
2f5d0 75 6d 62 65 72 20 30 2e 30 2c 20 6f 72 20 61 20  umber 0.0, or a 
2f5e0 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e  NULL.** pointer.
2f5f0 20 20 53 75 62 73 65 71 75 65 6e 74 20 63 61 6c    Subsequent cal
2f600 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65  ls to [sqlite3_e
2f610 72 72 63 6f 64 65 28 29 5d 20 77 69 6c 6c 20 72  rrcode()] will r
2f620 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45  eturn.** [SQLITE
2f630 5f 4e 4f 4d 45 4d 5d 2e 29 5e 0a 2a 2f 0a 63 6f  _NOMEM].)^.*/.co
2f640 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
2f650 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71  3_column_blob(sq
2f660 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2f670 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69   iCol);.int sqli
2f680 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2f690 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2f6a0 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73  int iCol);.int s
2f6b0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2f6c0 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f 73 74  tes16(sqlite3_st
2f6d0 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
2f6e0 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 63  double sqlite3_c
2f6f0 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28 73 71 6c  olumn_double(sql
2f700 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
2f710 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74  iCol);.int sqlit
2f720 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71  e3_column_int(sq
2f730 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2f740 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f   iCol);.sqlite3_
2f750 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 63 6f  int64 sqlite3_co
2f760 6c 75 6d 6e 5f 69 6e 74 36 34 28 73 71 6c 69 74  lumn_int64(sqlit
2f770 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
2f780 6f 6c 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67  ol);.const unsig
2f790 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65  ned char *sqlite
2f7a0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 73 71  3_column_text(sq
2f7b0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2f7c0 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 76 6f   iCol);.const vo
2f7d0 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
2f7e0 6d 6e 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65  mn_text16(sqlite
2f7f0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
2f800 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  l);.int sqlite3_
2f810 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 73 71 6c 69  column_type(sqli
2f820 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
2f830 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 76 61  Col);.sqlite3_va
2f840 6c 75 65 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  lue *sqlite3_col
2f850 75 6d 6e 5f 76 61 6c 75 65 28 73 71 6c 69 74 65  umn_value(sqlite
2f860 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
2f870 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  l);../*.** CAPI3
2f880 52 45 46 3a 20 44 65 73 74 72 6f 79 20 41 20 50  REF: Destroy A P
2f890 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
2f8a0 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 5e  t Object.**.** ^
2f8b0 54 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61  The sqlite3_fina
2f8c0 6c 69 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e 20  lize() function 
2f8d0 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 64 65 6c  is called to del
2f8e0 65 74 65 20 61 20 5b 70 72 65 70 61 72 65 64 20  ete a [prepared 
2f8f0 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e  statement]..** ^
2f900 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  If the most rece
2f910 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66  nt evaluation of
2f920 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 65   the statement e
2f930 6e 63 6f 75 6e 74 65 72 65 64 20 6e 6f 20 65 72  ncountered no er
2f940 72 6f 72 73 0a 2a 2a 20 6f 72 20 69 66 20 74 68  rors.** or if th
2f950 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e  e statement is n
2f960 65 76 65 72 20 62 65 65 6e 20 65 76 61 6c 75 61  ever been evalua
2f970 74 65 64 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  ted, then sqlite
2f980 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 72 65 74  3_finalize() ret
2f990 75 72 6e 73 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f  urns.** SQLITE_O
2f9a0 4b 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f 73 74  K.  ^If the most
2f9b0 20 72 65 63 65 6e 74 20 65 76 61 6c 75 61 74 69   recent evaluati
2f9c0 6f 6e 20 6f 66 20 73 74 61 74 65 6d 65 6e 74 20  on of statement 
2f9d0 53 20 66 61 69 6c 65 64 2c 20 74 68 65 6e 0a 2a  S failed, then.*
2f9e0 2a 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69  * sqlite3_finali
2f9f0 7a 65 28 53 29 20 72 65 74 75 72 6e 73 20 74 68  ze(S) returns th
2fa00 65 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65  e appropriate [e
2fa10 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a  rror code] or.**
2fa20 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72   [extended error
2fa30 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54   code]..**.** ^T
2fa40 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  he sqlite3_final
2fa50 69 7a 65 28 53 29 20 72 6f 75 74 69 6e 65 20 63  ize(S) routine c
2fa60 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 74 20  an be called at 
2fa70 61 6e 79 20 70 6f 69 6e 74 20 64 75 72 69 6e 67  any point during
2fa80 0a 2a 2a 20 74 68 65 20 6c 69 66 65 20 63 79 63  .** the life cyc
2fa90 6c 65 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20  le of [prepared 
2faa0 73 74 61 74 65 6d 65 6e 74 5d 20 53 3a 0a 2a 2a  statement] S:.**
2fab0 20 62 65 66 6f 72 65 20 73 74 61 74 65 6d 65 6e   before statemen
2fac0 74 20 53 20 69 73 20 65 76 65 72 20 65 76 61 6c  t S is ever eval
2fad0 75 61 74 65 64 2c 20 61 66 74 65 72 0a 2a 2a 20  uated, after.** 
2fae0 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 63 61 6c 6c  one or more call
2faf0 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65  s to [sqlite3_re
2fb00 73 65 74 28 29 5d 2c 20 6f 72 20 61 66 74 65 72  set()], or after
2fb10 20 61 6e 79 20 63 61 6c 6c 0a 2a 2a 20 74 6f 20   any call.** to 
2fb20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
2fb30 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77   regardless of w
2fb40 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68  hether or not th
2fb50 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73 0a  e statement has.
2fb60 2a 2a 20 63 6f 6d 70 6c 65 74 65 64 20 65 78 65  ** completed exe
2fb70 63 75 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49  cution..**.** ^I
2fb80 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f  nvoking sqlite3_
2fb90 66 69 6e 61 6c 69 7a 65 28 29 20 6f 6e 20 61 20  finalize() on a 
2fba0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20  NULL pointer is 
2fbb0 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70  a harmless no-op
2fbc0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c  ..**.** The appl
2fbd0 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 66 69 6e  ication must fin
2fbe0 61 6c 69 7a 65 20 65 76 65 72 79 20 5b 70 72 65  alize every [pre
2fbf0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2fc00 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 61 76 6f   in order to avo
2fc10 69 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65 20 6c  id.** resource l
2fc20 65 61 6b 73 2e 20 20 49 74 20 69 73 20 61 20 67  eaks.  It is a g
2fc30 72 69 65 76 6f 75 73 20 65 72 72 6f 72 20 66 6f  rievous error fo
2fc40 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  r the applicatio
2fc50 6e 20 74 6f 20 74 72 79 20 74 6f 20 75 73 65 0a  n to try to use.
2fc60 2a 2a 20 61 20 70 72 65 70 61 72 65 64 20 73 74  ** a prepared st
2fc70 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 69 74  atement after it
2fc80 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69   has been finali
2fc90 7a 65 64 2e 20 20 41 6e 79 20 75 73 65 20 6f 66  zed.  Any use of
2fca0 20 61 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73   a prepared.** s
2fcb0 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 69  tatement after i
2fcc0 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c  t has been final
2fcd0 69 7a 65 64 20 63 61 6e 20 72 65 73 75 6c 74 20  ized can result 
2fce0 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64  in undefined and
2fcf0 0a 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c 65 20  .** undesirable 
2fd00 62 65 68 61 76 69 6f 72 20 73 75 63 68 20 61 73  behavior such as
2fd10 20 73 65 67 66 61 75 6c 74 73 20 61 6e 64 20 68   segfaults and h
2fd20 65 61 70 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a  eap corruption..
2fd30 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 66  */.int sqlite3_f
2fd40 69 6e 61 6c 69 7a 65 28 73 71 6c 69 74 65 33 5f  inalize(sqlite3_
2fd50 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
2fd60 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
2fd70 65 73 65 74 20 41 20 50 72 65 70 61 72 65 64 20  eset A Prepared 
2fd80 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74  Statement Object
2fd90 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
2fda0 65 33 5f 72 65 73 65 74 28 29 20 66 75 6e 63 74  e3_reset() funct
2fdb0 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f  ion is called to
2fdc0 20 72 65 73 65 74 20 61 20 5b 70 72 65 70 61 72   reset a [prepar
2fdd0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a  ed statement].**
2fde0 20 6f 62 6a 65 63 74 20 62 61 63 6b 20 74 6f 20   object back to 
2fdf0 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74  its initial stat
2fe00 65 2c 20 72 65 61 64 79 20 74 6f 20 62 65 20 72  e, ready to be r
2fe10 65 2d 65 78 65 63 75 74 65 64 2e 0a 2a 2a 20 5e  e-executed..** ^
2fe20 41 6e 79 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  Any SQL statemen
2fe30 74 20 76 61 72 69 61 62 6c 65 73 20 74 68 61 74  t variables that
2fe40 20 68 61 64 20 76 61 6c 75 65 73 20 62 6f 75 6e   had values boun
2fe50 64 20 74 6f 20 74 68 65 6d 20 75 73 69 6e 67 0a  d to them using.
2fe60 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** the [sqlite3_
2fe70 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69  bind_blob | sqli
2fe80 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 41 50 49  te3_bind_*() API
2fe90 5d 20 72 65 74 61 69 6e 20 74 68 65 69 72 20 76  ] retain their v
2fea0 61 6c 75 65 73 2e 0a 2a 2a 20 55 73 65 20 5b 73  alues..** Use [s
2feb0 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e  qlite3_clear_bin
2fec0 64 69 6e 67 73 28 29 5d 20 74 6f 20 72 65 73 65  dings()] to rese
2fed0 74 20 74 68 65 20 62 69 6e 64 69 6e 67 73 2e 0a  t the bindings..
2fee0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69  **.** ^The [sqli
2fef0 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e  te3_reset(S)] in
2ff00 74 65 72 66 61 63 65 20 72 65 73 65 74 73 20 74  terface resets t
2ff10 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
2ff20 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a 20 62 61 63  tement] S.** bac
2ff30 6b 20 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69  k to the beginni
2ff40 6e 67 20 6f 66 20 69 74 73 20 70 72 6f 67 72 61  ng of its progra
2ff50 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  m..**.** ^If the
2ff60 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c   most recent cal
2ff70 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74  l to [sqlite3_st
2ff80 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a  ep(S)] for the.*
2ff90 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
2ffa0 65 6d 65 6e 74 5d 20 53 20 72 65 74 75 72 6e 65  ement] S returne
2ffb0 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f  d [SQLITE_ROW] o
2ffc0 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c  r [SQLITE_DONE],
2ffd0 0a 2a 2a 20 6f 72 20 69 66 20 5b 73 71 6c 69 74  .** or if [sqlit
2ffe0 65 33 5f 73 74 65 70 28 53 29 5d 20 68 61 73 20  e3_step(S)] has 
2fff0 6e 65 76 65 72 20 62 65 66 6f 72 65 20 62 65 65  never before bee
30000 6e 20 63 61 6c 6c 65 64 20 6f 6e 20 53 2c 0a 2a  n called on S,.*
30010 2a 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f  * then [sqlite3_
30020 72 65 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e  reset(S)] return
30030 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a  s [SQLITE_OK]..*
30040 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73  *.** ^If the mos
30050 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f  t recent call to
30060 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53   [sqlite3_step(S
30070 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70  )] for the.** [p
30080 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
30090 74 5d 20 53 20 69 6e 64 69 63 61 74 65 64 20 61  t] S indicated a
300a0 6e 20 65 72 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a  n error, then.**
300b0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
300c0 53 29 5d 20 72 65 74 75 72 6e 73 20 61 6e 20 61  S)] returns an a
300d0 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f  ppropriate [erro
300e0 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  r code]..**.** ^
300f0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  The [sqlite3_res
30100 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65  et(S)] interface
30110 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65   does not change
30120 20 74 68 65 20 76 61 6c 75 65 73 0a 2a 2a 20 6f   the values.** o
30130 66 20 61 6e 79 20 5b 73 71 6c 69 74 65 33 5f 62  f any [sqlite3_b
30140 69 6e 64 5f 62 6c 6f 62 7c 62 69 6e 64 69 6e 67  ind_blob|binding
30150 73 5d 20 6f 6e 20 74 68 65 20 5b 70 72 65 70 61  s] on the [prepa
30160 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
30170 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
30180 5f 72 65 73 65 74 28 73 71 6c 69 74 65 33 5f 73  _reset(sqlite3_s
30190 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
301a0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 72  .** CAPI3REF: Cr
301b0 65 61 74 65 20 4f 72 20 52 65 64 65 66 69 6e 65  eate Or Redefine
301c0 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 73 0a 2a   SQL Functions.*
301d0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 66 75 6e  * KEYWORDS: {fun
301e0 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72  ction creation r
301f0 6f 75 74 69 6e 65 73 7d 0a 2a 2a 20 4b 45 59 57  outines}.** KEYW
30200 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69  ORDS: {applicati
30210 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
30220 75 6e 63 74 69 6f 6e 7d 0a 2a 2a 20 4b 45 59 57  unction}.** KEYW
30230 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69  ORDS: {applicati
30240 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
30250 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20  unctions}.**.** 
30260 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73  ^These functions
30270 20 28 63 6f 6c 6c 65 63 74 69 76 65 6c 79 20 6b   (collectively k
30280 6e 6f 77 6e 20 61 73 20 22 66 75 6e 63 74 69 6f  nown as "functio
30290 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69  n creation routi
302a0 6e 65 73 22 29 0a 2a 2a 20 61 72 65 20 75 73 65  nes").** are use
302b0 64 20 74 6f 20 61 64 64 20 53 51 4c 20 66 75 6e  d to add SQL fun
302c0 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67  ctions or aggreg
302d0 61 74 65 73 20 6f 72 20 74 6f 20 72 65 64 65 66  ates or to redef
302e0 69 6e 65 20 74 68 65 20 62 65 68 61 76 69 6f 72  ine the behavior
302f0 0a 2a 2a 20 6f 66 20 65 78 69 73 74 69 6e 67 20  .** of existing 
30300 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72  SQL functions or
30310 20 61 67 67 72 65 67 61 74 65 73 2e 20 20 54 68   aggregates.  Th
30320 65 20 6f 6e 6c 79 20 64 69 66 66 65 72 65 6e 63  e only differenc
30330 65 73 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68  es between.** th
30340 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
30350 20 74 68 65 20 74 65 78 74 20 65 6e 63 6f 64 69   the text encodi
30360 6e 67 20 65 78 70 65 63 74 65 64 20 66 6f 72 0a  ng expected for.
30370 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  ** the second pa
30380 72 61 6d 65 74 65 72 20 28 74 68 65 20 6e 61 6d  rameter (the nam
30390 65 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f  e of the functio
303a0 6e 20 62 65 69 6e 67 20 63 72 65 61 74 65 64 29  n being created)
303b0 0a 2a 2a 20 61 6e 64 20 74 68 65 20 70 72 65 73  .** and the pres
303c0 65 6e 63 65 20 6f 72 20 61 62 73 65 6e 63 65 20  ence or absence 
303d0 6f 66 20 61 20 64 65 73 74 72 75 63 74 6f 72 20  of a destructor 
303e0 63 61 6c 6c 62 61 63 6b 20 66 6f 72 0a 2a 2a 20  callback for.** 
303f0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
30400 64 61 74 61 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  data pointer..**
30410 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 70  .** ^The first p
30420 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20  arameter is the 
30430 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
30440 74 69 6f 6e 5d 20 74 6f 20 77 68 69 63 68 20 74  tion] to which t
30450 68 65 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69  he SQL.** functi
30460 6f 6e 20 69 73 20 74 6f 20 62 65 20 61 64 64 65  on is to be adde
30470 64 2e 20 20 5e 49 66 20 61 6e 20 61 70 70 6c 69  d.  ^If an appli
30480 63 61 74 69 6f 6e 20 75 73 65 73 20 6d 6f 72 65  cation uses more
30490 20 74 68 61 6e 20 6f 6e 65 20 64 61 74 61 62 61   than one databa
304a0 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  se.** connection
304b0 20 74 68 65 6e 20 61 70 70 6c 69 63 61 74 69 6f   then applicatio
304c0 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
304d0 6e 63 74 69 6f 6e 73 20 6d 75 73 74 20 62 65 20  nctions must be 
304e0 61 64 64 65 64 0a 2a 2a 20 74 6f 20 65 61 63 68  added.** to each
304f0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
30500 74 69 6f 6e 20 73 65 70 61 72 61 74 65 6c 79 2e  tion separately.
30510 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f  .**.** ^The seco
30520 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
30530 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
30540 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  SQL function to 
30550 62 65 20 63 72 65 61 74 65 64 20 6f 72 0a 2a 2a  be created or.**
30560 20 72 65 64 65 66 69 6e 65 64 2e 20 20 5e 54 68   redefined.  ^Th
30570 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20  e length of the 
30580 6e 61 6d 65 20 69 73 20 6c 69 6d 69 74 65 64 20  name is limited 
30590 74 6f 20 32 35 35 20 62 79 74 65 73 20 69 6e 20  to 255 bytes in 
305a0 61 20 55 54 46 2d 38 0a 2a 2a 20 72 65 70 72 65  a UTF-8.** repre
305b0 73 65 6e 74 61 74 69 6f 6e 2c 20 65 78 63 6c 75  sentation, exclu
305c0 73 69 76 65 20 6f 66 20 74 68 65 20 7a 65 72 6f  sive of the zero
305d0 2d 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 4e  -terminator.  ^N
305e0 6f 74 65 20 74 68 61 74 20 74 68 65 20 6e 61 6d  ote that the nam
305f0 65 0a 2a 2a 20 6c 65 6e 67 74 68 20 6c 69 6d 69  e.** length limi
30600 74 20 69 73 20 69 6e 20 55 54 46 2d 38 20 62 79  t is in UTF-8 by
30610 74 65 73 2c 20 6e 6f 74 20 63 68 61 72 61 63 74  tes, not charact
30620 65 72 73 20 6e 6f 72 20 55 54 46 2d 31 36 20 62  ers nor UTF-16 b
30630 79 74 65 73 2e 20 20 0a 2a 2a 20 5e 41 6e 79 20  ytes.  .** ^Any 
30640 61 74 74 65 6d 70 74 20 74 6f 20 63 72 65 61 74  attempt to creat
30650 65 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 69 74  e a function wit
30660 68 20 61 20 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a  h a longer name.
30670 2a 2a 20 77 69 6c 6c 20 72 65 73 75 6c 74 20 69  ** will result i
30680 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  n [SQLITE_MISUSE
30690 5d 20 62 65 69 6e 67 20 72 65 74 75 72 6e 65 64  ] being returned
306a0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69  ..**.** ^The thi
306b0 72 64 20 70 61 72 61 6d 65 74 65 72 20 28 6e 41  rd parameter (nA
306c0 72 67 29 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75  rg).** is the nu
306d0 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74  mber of argument
306e0 73 20 74 68 61 74 20 74 68 65 20 53 51 4c 20 66  s that the SQL f
306f0 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67  unction or.** ag
30700 67 72 65 67 61 74 65 20 74 61 6b 65 73 2e 20 5e  gregate takes. ^
30710 49 66 20 74 68 69 73 20 70 61 72 61 6d 65 74 65  If this paramete
30720 72 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 74 68  r is -1, then th
30730 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f  e SQL function o
30740 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 6d  r.** aggregate m
30750 61 79 20 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62  ay take any numb
30760 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20  er of arguments 
30770 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20 74 68  between 0 and th
30780 65 20 6c 69 6d 69 74 0a 2a 2a 20 73 65 74 20 62  e limit.** set b
30790 79 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  y [sqlite3_limit
307a0 5d 28 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ]([SQLITE_LIMIT_
307b0 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 29 2e 20  FUNCTION_ARG]). 
307c0 20 49 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a   If the third.**
307d0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6c 65   parameter is le
307e0 73 73 20 74 68 61 6e 20 2d 31 20 6f 72 20 67 72  ss than -1 or gr
307f0 65 61 74 65 72 20 74 68 61 6e 20 31 32 37 20 74  eater than 127 t
30800 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
30810 20 69 73 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64   is.** undefined
30820 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75  ..**.** ^The fou
30830 72 74 68 20 70 61 72 61 6d 65 74 65 72 2c 20 65  rth parameter, e
30840 54 65 78 74 52 65 70 2c 20 73 70 65 63 69 66 69  TextRep, specifi
30850 65 73 20 77 68 61 74 0a 2a 2a 20 5b 53 51 4c 49  es what.** [SQLI
30860 54 45 5f 55 54 46 38 20 7c 20 74 65 78 74 20 65  TE_UTF8 | text e
30870 6e 63 6f 64 69 6e 67 5d 20 74 68 69 73 20 53 51  ncoding] this SQ
30880 4c 20 66 75 6e 63 74 69 6f 6e 20 70 72 65 66 65  L function prefe
30890 72 73 20 66 6f 72 0a 2a 2a 20 69 74 73 20 70 61  rs for.** its pa
308a0 72 61 6d 65 74 65 72 73 2e 20 20 54 68 65 20 61  rameters.  The a
308b0 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
308c0 64 20 73 65 74 20 74 68 69 73 20 70 61 72 61 6d  d set this param
308d0 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 53 51 4c 49  eter to.** [SQLI
308e0 54 45 5f 55 54 46 31 36 4c 45 5d 20 69 66 20 74  TE_UTF16LE] if t
308f0 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c  he function impl
30900 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 76 6f 6b  ementation invok
30910 65 73 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  es .** [sqlite3_
30920 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 29  value_text16le()
30930 5d 20 6f 6e 20 61 6e 20 69 6e 70 75 74 2c 20 6f  ] on an input, o
30940 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42  r [SQLITE_UTF16B
30950 45 5d 20 69 66 20 74 68 65 0a 2a 2a 20 69 6d 70  E] if the.** imp
30960 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 76 6f  lementation invo
30970 6b 65 73 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  kes [sqlite3_val
30980 75 65 5f 74 65 78 74 31 36 62 65 28 29 5d 20 6f  ue_text16be()] o
30990 6e 20 61 6e 20 69 6e 70 75 74 2c 20 6f 72 0a 2a  n an input, or.*
309a0 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d  * [SQLITE_UTF16]
309b0 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c   if [sqlite3_val
309c0 75 65 5f 74 65 78 74 31 36 28 29 5d 20 69 73 20  ue_text16()] is 
309d0 75 73 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45  used, or [SQLITE
309e0 5f 55 54 46 38 5d 0a 2a 2a 20 6f 74 68 65 72 77  _UTF8].** otherw
309f0 69 73 65 2e 20 20 5e 54 68 65 20 73 61 6d 65 20  ise.  ^The same 
30a00 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79  SQL function may
30a10 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20 6d   be registered m
30a20 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 75 73  ultiple times us
30a30 69 6e 67 0a 2a 2a 20 64 69 66 66 65 72 65 6e 74  ing.** different
30a40 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20   preferred text 
30a50 65 6e 63 6f 64 69 6e 67 73 2c 20 77 69 74 68 20  encodings, with 
30a60 64 69 66 66 65 72 65 6e 74 20 69 6d 70 6c 65 6d  different implem
30a70 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 0a 2a 2a  entations for.**
30a80 20 65 61 63 68 20 65 6e 63 6f 64 69 6e 67 2e 0a   each encoding..
30a90 2a 2a 20 5e 57 68 65 6e 20 6d 75 6c 74 69 70 6c  ** ^When multipl
30aa0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
30ab0 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75  s of the same fu
30ac0 6e 63 74 69 6f 6e 20 61 72 65 20 61 76 61 69 6c  nction are avail
30ad0 61 62 6c 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20  able, SQLite.** 
30ae0 77 69 6c 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e  will pick the on
30af0 65 20 74 68 61 74 20 69 6e 76 6f 6c 76 65 73 20  e that involves 
30b00 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74  the least amount
30b10 20 6f 66 20 64 61 74 61 20 63 6f 6e 76 65 72 73   of data convers
30b20 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ion..**.** ^The 
30b30 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
30b40 20 6d 61 79 20 6f 70 74 69 6f 6e 61 6c 6c 79 20   may optionally 
30b50 62 65 20 4f 52 65 64 20 77 69 74 68 20 5b 53 51  be ORed with [SQ
30b60 4c 49 54 45 5f 44 45 54 45 52 4d 49 4e 49 53 54  LITE_DETERMINIST
30b70 49 43 5d 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c  IC].** to signal
30b80 20 74 68 61 74 20 74 68 65 20 66 75 6e 63 74 69   that the functi
30b90 6f 6e 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 72  on will always r
30ba0 65 74 75 72 6e 20 74 68 65 20 73 61 6d 65 20 72  eturn the same r
30bb0 65 73 75 6c 74 20 67 69 76 65 6e 0a 2a 2a 20 74  esult given.** t
30bc0 68 65 20 73 61 6d 65 20 69 6e 70 75 74 73 20 77  he same inputs w
30bd0 69 74 68 69 6e 20 61 20 73 69 6e 67 6c 65 20 53  ithin a single S
30be0 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 4d  QL statement.  M
30bf0 6f 73 74 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ost SQL function
30c00 73 20 61 72 65 0a 2a 2a 20 64 65 74 65 72 6d 69  s are.** determi
30c10 6e 69 73 74 69 63 2e 20 20 54 68 65 20 62 75 69  nistic.  The bui
30c20 6c 74 2d 69 6e 20 5b 72 61 6e 64 6f 6d 28 29 5d  lt-in [random()]
30c30 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73   SQL function is
30c40 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 61   an example of a
30c50 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 68 61  .** function tha
30c60 74 20 69 73 20 6e 6f 74 20 64 65 74 65 72 6d 69  t is not determi
30c70 6e 69 73 74 69 63 2e 20 20 54 68 65 20 53 51 4c  nistic.  The SQL
30c80 69 74 65 20 71 75 65 72 79 20 70 6c 61 6e 6e 65  ite query planne
30c90 72 20 69 73 20 61 62 6c 65 20 74 6f 0a 2a 2a 20  r is able to.** 
30ca0 70 65 72 66 6f 72 6d 20 61 64 64 69 74 69 6f 6e  perform addition
30cb0 61 6c 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 73  al optimizations
30cc0 20 6f 6e 20 64 65 74 65 72 6d 69 6e 69 73 74 69   on deterministi
30cd0 63 20 66 75 6e 63 74 69 6f 6e 73 2c 20 73 6f 20  c functions, so 
30ce0 75 73 65 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 53  use.** of the [S
30cf0 51 4c 49 54 45 5f 44 45 54 45 52 4d 49 4e 49 53  QLITE_DETERMINIS
30d00 54 49 43 5d 20 66 6c 61 67 20 69 73 20 72 65 63  TIC] flag is rec
30d10 6f 6d 6d 65 6e 64 65 64 20 77 68 65 72 65 20 70  ommended where p
30d20 6f 73 73 69 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e  ossible..**.** ^
30d30 28 54 68 65 20 66 69 66 74 68 20 70 61 72 61 6d  (The fifth param
30d40 65 74 65 72 20 69 73 20 61 6e 20 61 72 62 69 74  eter is an arbit
30d50 72 61 72 79 20 70 6f 69 6e 74 65 72 2e 20 20 54  rary pointer.  T
30d60 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
30d70 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63  n of the.** func
30d80 74 69 6f 6e 20 63 61 6e 20 67 61 69 6e 20 61 63  tion can gain ac
30d90 63 65 73 73 20 74 6f 20 74 68 69 73 20 70 6f 69  cess to this poi
30da0 6e 74 65 72 20 75 73 69 6e 67 20 5b 73 71 6c 69  nter using [sqli
30db0 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d  te3_user_data()]
30dc0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  .)^.**.** ^The s
30dd0 69 78 74 68 2c 20 73 65 76 65 6e 74 68 20 61 6e  ixth, seventh an
30de0 64 20 65 69 67 68 74 68 20 70 61 72 61 6d 65 74  d eighth paramet
30df0 65 72 73 2c 20 78 46 75 6e 63 2c 20 78 53 74 65  ers, xFunc, xSte
30e00 70 20 61 6e 64 20 78 46 69 6e 61 6c 2c 20 61 72  p and xFinal, ar
30e10 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f  e.** pointers to
30e20 20 43 2d 6c 61 6e 67 75 61 67 65 20 66 75 6e 63   C-language func
30e30 74 69 6f 6e 73 20 74 68 61 74 20 69 6d 70 6c 65  tions that imple
30e40 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e  ment the SQL fun
30e50 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72  ction or.** aggr
30e60 65 67 61 74 65 2e 20 5e 41 20 73 63 61 6c 61 72  egate. ^A scalar
30e70 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65   SQL function re
30e80 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d  quires an implem
30e90 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  entation of the 
30ea0 78 46 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62 61 63  xFunc.** callbac
30eb0 6b 20 6f 6e 6c 79 3b 20 4e 55 4c 4c 20 70 6f 69  k only; NULL poi
30ec0 6e 74 65 72 73 20 6d 75 73 74 20 62 65 20 70 61  nters must be pa
30ed0 73 73 65 64 20 61 73 20 74 68 65 20 78 53 74 65  ssed as the xSte
30ee0 70 20 61 6e 64 20 78 46 69 6e 61 6c 0a 2a 2a 20  p and xFinal.** 
30ef0 70 61 72 61 6d 65 74 65 72 73 2e 20 5e 41 6e 20  parameters. ^An 
30f00 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75  aggregate SQL fu
30f10 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20  nction requires 
30f20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  an implementatio
30f30 6e 20 6f 66 20 78 53 74 65 70 0a 2a 2a 20 61 6e  n of xStep.** an
30f40 64 20 78 46 69 6e 61 6c 20 61 6e 64 20 4e 55 4c  d xFinal and NUL
30f50 4c 20 70 6f 69 6e 74 65 72 20 6d 75 73 74 20 62  L pointer must b
30f60 65 20 70 61 73 73 65 64 20 66 6f 72 20 78 46 75  e passed for xFu
30f70 6e 63 2e 20 5e 54 6f 20 64 65 6c 65 74 65 20 61  nc. ^To delete a
30f80 6e 20 65 78 69 73 74 69 6e 67 0a 2a 2a 20 53 51  n existing.** SQ
30f90 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67  L function or ag
30fa0 67 72 65 67 61 74 65 2c 20 70 61 73 73 20 4e 55  gregate, pass NU
30fb0 4c 4c 20 70 6f 69 6e 74 65 72 73 20 66 6f 72 20  LL pointers for 
30fc0 61 6c 6c 20 74 68 72 65 65 20 66 75 6e 63 74 69  all three functi
30fd0 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 73 2e  on.** callbacks.
30fe0 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 65 20  .**.** ^(If the 
30ff0 6e 69 6e 74 68 20 70 61 72 61 6d 65 74 65 72 20  ninth parameter 
31000 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  to sqlite3_creat
31010 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20  e_function_v2() 
31020 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a 20  is not NULL,.** 
31030 74 68 65 6e 20 69 74 20 69 73 20 64 65 73 74 72  then it is destr
31040 75 63 74 6f 72 20 66 6f 72 20 74 68 65 20 61 70  uctor for the ap
31050 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70  plication data p
31060 6f 69 6e 74 65 72 2e 20 0a 2a 2a 20 54 68 65 20  ointer. .** The 
31070 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 69 6e  destructor is in
31080 76 6f 6b 65 64 20 77 68 65 6e 20 74 68 65 20 66  voked when the f
31090 75 6e 63 74 69 6f 6e 20 69 73 20 64 65 6c 65 74  unction is delet
310a0 65 64 2c 20 65 69 74 68 65 72 20 62 79 20 62 65  ed, either by be
310b0 69 6e 67 0a 2a 2a 20 6f 76 65 72 6c 6f 61 64 65  ing.** overloade
310c0 64 20 6f 72 20 77 68 65 6e 20 74 68 65 20 64 61  d or when the da
310d0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
310e0 6e 20 63 6c 6f 73 65 73 2e 29 5e 0a 2a 2a 20 5e  n closes.)^.** ^
310f0 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 69  The destructor i
31100 73 20 61 6c 73 6f 20 69 6e 76 6f 6b 65 64 20 69  s also invoked i
31110 66 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a  f the call to.**
31120 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
31130 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20 66 61  function_v2() fa
31140 69 6c 73 2e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68  ils..** ^When th
31150 65 20 64 65 73 74 72 75 63 74 6f 72 20 63 61 6c  e destructor cal
31160 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 74 65 6e  lback of the ten
31170 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  th parameter is 
31180 69 6e 76 6f 6b 65 64 2c 20 69 74 0a 2a 2a 20 69  invoked, it.** i
31190 73 20 70 61 73 73 65 64 20 61 20 73 69 6e 67 6c  s passed a singl
311a0 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
311b0 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68   is a copy of th
311c0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61  e application da
311d0 74 61 20 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 77  ta .** pointer w
311e0 68 69 63 68 20 77 61 73 20 74 68 65 20 66 69 66  hich was the fif
311f0 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
31200 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
31210 75 6e 63 74 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a  unction_v2()..**
31220 0a 2a 2a 20 5e 49 74 20 69 73 20 70 65 72 6d 69  .** ^It is permi
31230 74 74 65 64 20 74 6f 20 72 65 67 69 73 74 65 72  tted to register
31240 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d   multiple implem
31250 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65  entations of the
31260 20 73 61 6d 65 0a 2a 2a 20 66 75 6e 63 74 69 6f   same.** functio
31270 6e 73 20 77 69 74 68 20 74 68 65 20 73 61 6d 65  ns with the same
31280 20 6e 61 6d 65 20 62 75 74 20 77 69 74 68 20 65   name but with e
31290 69 74 68 65 72 20 64 69 66 66 65 72 69 6e 67 20  ither differing 
312a0 6e 75 6d 62 65 72 73 20 6f 66 0a 2a 2a 20 61 72  numbers of.** ar
312b0 67 75 6d 65 6e 74 73 20 6f 72 20 64 69 66 66 65  guments or diffe
312c0 72 69 6e 67 20 70 72 65 66 65 72 72 65 64 20 74  ring preferred t
312d0 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 2e 20 20  ext encodings.  
312e0 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65  ^SQLite will use
312f0 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e  .** the implemen
31300 74 61 74 69 6f 6e 20 74 68 61 74 20 6d 6f 73 74  tation that most
31310 20 63 6c 6f 73 65 6c 79 20 6d 61 74 63 68 65 73   closely matches
31320 20 74 68 65 20 77 61 79 20 69 6e 20 77 68 69 63   the way in whic
31330 68 20 74 68 65 0a 2a 2a 20 53 51 4c 20 66 75 6e  h the.** SQL fun
31340 63 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 20 20  ction is used.  
31350 5e 41 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c  ^A function impl
31360 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 20  ementation with 
31370 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 0a 2a  a non-negative.*
31380 2a 20 6e 41 72 67 20 70 61 72 61 6d 65 74 65 72  * nArg parameter
31390 20 69 73 20 61 20 62 65 74 74 65 72 20 6d 61 74   is a better mat
313a0 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69  ch than a functi
313b0 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  on implementatio
313c0 6e 20 77 69 74 68 0a 2a 2a 20 61 20 6e 65 67 61  n with.** a nega
313d0 74 69 76 65 20 6e 41 72 67 2e 20 20 5e 41 20 66  tive nArg.  ^A f
313e0 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68  unction where th
313f0 65 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74  e preferred text
31400 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 6d 61 74   encoding.** mat
31410 63 68 65 73 20 74 68 65 20 64 61 74 61 62 61 73  ches the databas
31420 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 61 20  e encoding is a 
31430 62 65 74 74 65 72 0a 2a 2a 20 6d 61 74 63 68 20  better.** match 
31440 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20  than a function 
31450 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69  where the encodi
31460 6e 67 20 69 73 20 64 69 66 66 65 72 65 6e 74 2e  ng is different.
31470 20 20 0a 2a 2a 20 5e 41 20 66 75 6e 63 74 69 6f    .** ^A functio
31480 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f  n where the enco
31490 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20  ding difference 
314a0 69 73 20 62 65 74 77 65 65 6e 20 55 54 46 31 36  is between UTF16
314b0 6c 65 20 61 6e 64 20 55 54 46 31 36 62 65 0a 2a  le and UTF16be.*
314c0 2a 20 69 73 20 61 20 63 6c 6f 73 65 72 20 6d 61  * is a closer ma
314d0 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74  tch than a funct
314e0 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e  ion where the en
314f0 63 6f 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63  coding differenc
31500 65 20 69 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20  e is.** between 
31510 55 54 46 38 20 61 6e 64 20 55 54 46 31 36 2e 0a  UTF8 and UTF16..
31520 2a 2a 0a 2a 2a 20 5e 42 75 69 6c 74 2d 69 6e 20  **.** ^Built-in 
31530 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65  functions may be
31540 20 6f 76 65 72 6c 6f 61 64 65 64 20 62 79 20 6e   overloaded by n
31550 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  ew application-d
31560 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73  efined functions
31570 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 61 70 70 6c  ..**.** ^An appl
31580 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
31590 66 75 6e 63 74 69 6f 6e 20 69 73 20 70 65 72 6d  function is perm
315a0 69 74 74 65 64 20 74 6f 20 63 61 6c 6c 20 6f 74  itted to call ot
315b0 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e  her.** SQLite in
315c0 74 65 72 66 61 63 65 73 2e 20 20 48 6f 77 65 76  terfaces.  Howev
315d0 65 72 2c 20 73 75 63 68 20 63 61 6c 6c 73 20 6d  er, such calls m
315e0 75 73 74 20 6e 6f 74 0a 2a 2a 20 63 6c 6f 73 65  ust not.** close
315f0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
31600 6e 6e 65 63 74 69 6f 6e 20 6e 6f 72 20 66 69 6e  nnection nor fin
31610 61 6c 69 7a 65 20 6f 72 20 72 65 73 65 74 20 74  alize or reset t
31620 68 65 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73  he prepared.** s
31630 74 61 74 65 6d 65 6e 74 20 69 6e 20 77 68 69 63  tatement in whic
31640 68 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69  h the function i
31650 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 69 6e  s running..*/.in
31660 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  t sqlite3_create
31670 5f 66 75 6e 63 74 69 6f 6e 28 0a 20 20 73 71 6c  _function(.  sql
31680 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73  ite3 *db,.  cons
31690 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f  t char *zFunctio
316a0 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72  nName,.  int nAr
316b0 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65  g,.  int eTextRe
316c0 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c  p,.  void *pApp,
316d0 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29  .  void (*xFunc)
316e0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
316f0 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61  *,int,sqlite3_va
31700 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28  lue**),.  void (
31710 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f  *xStep)(sqlite3_
31720 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c  context*,int,sql
31730 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20  ite3_value**),. 
31740 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28   void (*xFinal)(
31750 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
31760 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ).);.int sqlite3
31770 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
31780 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  16(.  sqlite3 *d
31790 62 2c 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  b,.  const void 
317a0 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a  *zFunctionName,.
317b0 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e    int nArg,.  in
317c0 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f  t eTextRep,.  vo
317d0 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64  id *pApp,.  void
317e0 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65   (*xFunc)(sqlite
317f0 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73  3_context*,int,s
31800 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c  qlite3_value**),
31810 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29  .  void (*xStep)
31820 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
31830 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61  *,int,sqlite3_va
31840 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28  lue**),.  void (
31850 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33  *xFinal)(sqlite3
31860 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 69 6e  _context*).);.in
31870 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  t sqlite3_create
31880 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 0a 20 20  _function_v2(.  
31890 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63  sqlite3 *db,.  c
318a0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63  onst char *zFunc
318b0 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20  tionName,.  int 
318c0 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78  nArg,.  int eTex
318d0 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41  tRep,.  void *pA
318e0 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75  pp,.  void (*xFu
318f0 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  nc)(sqlite3_cont
31900 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33  ext*,int,sqlite3
31910 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69  _value**),.  voi
31920 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74  d (*xStep)(sqlit
31930 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c  e3_context*,int,
31940 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29  sqlite3_value**)
31950 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61  ,.  void (*xFina
31960 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  l)(sqlite3_conte
31970 78 74 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44  xt*),.  void(*xD
31980 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29  estroy)(void*).)
31990 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
319a0 46 3a 20 54 65 78 74 20 45 6e 63 6f 64 69 6e 67  F: Text Encoding
319b0 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f  s.**.** These co
319c0 6e 73 74 61 6e 74 20 64 65 66 69 6e 65 20 69 6e  nstant define in
319d0 74 65 67 65 72 20 63 6f 64 65 73 20 74 68 61 74  teger codes that
319e0 20 72 65 70 72 65 73 65 6e 74 20 74 68 65 20 76   represent the v
319f0 61 72 69 6f 75 73 0a 2a 2a 20 74 65 78 74 20 65  arious.** text e
31a00 6e 63 6f 64 69 6e 67 73 20 73 75 70 70 6f 72 74  ncodings support
31a10 65 64 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2f  ed by SQLite..*/
31a20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
31a30 55 54 46 38 20 20 20 20 20 20 20 20 20 20 20 31  UTF8           1
31a40 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
31a50 55 54 46 31 36 4c 45 20 20 20 20 20 20 20 20 32  UTF16LE        2
31a60 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
31a70 55 54 46 31 36 42 45 20 20 20 20 20 20 20 20 33  UTF16BE        3
31a80 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
31a90 55 54 46 31 36 20 20 20 20 20 20 20 20 20 20 34  UTF16          4
31aa0 20 20 20 20 2f 2a 20 55 73 65 20 6e 61 74 69 76      /* Use nativ
31ab0 65 20 62 79 74 65 20 6f 72 64 65 72 20 2a 2f 0a  e byte order */.
31ac0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
31ad0 4e 59 20 20 20 20 20 20 20 20 20 20 20 20 35 20  NY            5 
31ae0 20 20 20 2f 2a 20 44 65 70 72 65 63 61 74 65 64     /* Deprecated
31af0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
31b00 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44  TE_UTF16_ALIGNED
31b10 20 20 38 20 20 20 20 2f 2a 20 73 71 6c 69 74 65    8    /* sqlite
31b20 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
31b30 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a  on only */../*.*
31b40 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e 63  * CAPI3REF: Func
31b50 74 69 6f 6e 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a  tion Flags.**.**
31b60 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73   These constants
31b70 20 6d 61 79 20 62 65 20 4f 52 65 64 20 74 6f 67   may be ORed tog
31b80 65 74 68 65 72 20 77 69 74 68 20 74 68 65 20 0a  ether with the .
31b90 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 20  ** [SQLITE_UTF8 
31ba0 7c 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74  | preferred text
31bb0 20 65 6e 63 6f 64 69 6e 67 5d 20 61 73 20 74 68   encoding] as th
31bc0 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e  e fourth argumen
31bd0 74 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33  t.** to [sqlite3
31be0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
31bf0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72  ()], [sqlite3_cr
31c00 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
31c10 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  )], or.** [sqlit
31c20 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
31c30 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 23 64 65  on_v2()]..*/.#de
31c40 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 54 45  fine SQLITE_DETE
31c50 52 4d 49 4e 49 53 54 49 43 20 20 20 20 30 78 38  RMINISTIC    0x8
31c60 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  00../*.** CAPI3R
31c70 45 46 3a 20 44 65 70 72 65 63 61 74 65 64 20 46  EF: Deprecated F
31c80 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 44 45 50 52  unctions.** DEPR
31c90 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68 65  ECATED.**.** The
31ca0 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65  se functions are
31cb0 20 5b 64 65 70 72 65 63 61 74 65 64 5d 2e 20 20   [deprecated].  
31cc0 49 6e 20 6f 72 64 65 72 20 74 6f 20 6d 61 69 6e  In order to main
31cd0 74 61 69 6e 0a 2a 2a 20 62 61 63 6b 77 61 72 64  tain.** backward
31ce0 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20  s compatibility 
31cf0 77 69 74 68 20 6f 6c 64 65 72 20 63 6f 64 65 2c  with older code,
31d00 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   these functions
31d10 20 63 6f 6e 74 69 6e 75 65 20 0a 2a 2a 20 74 6f   continue .** to
31d20 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e 20 20   be supported.  
31d30 48 6f 77 65 76 65 72 2c 20 6e 65 77 20 61 70 70  However, new app
31d40 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64  lications should
31d50 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65 20 75 73   avoid.** the us
31d60 65 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74  e of these funct
31d70 69 6f 6e 73 2e 20 20 54 6f 20 68 65 6c 70 20 65  ions.  To help e
31d80 6e 63 6f 75 72 61 67 65 20 70 65 6f 70 6c 65 20  ncourage people 
31d90 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 75 73 69 6e  to avoid.** usin
31da0 67 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  g these function
31db0 73 2c 20 77 65 20 61 72 65 20 6e 6f 74 20 67 6f  s, we are not go
31dc0 69 6e 67 20 74 6f 20 74 65 6c 6c 20 79 6f 75 20  ing to tell you 
31dd0 77 68 61 74 20 74 68 65 79 20 64 6f 2e 0a 2a 2f  what they do..*/
31de0 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f  .#ifndef SQLITE_
31df0 4f 4d 49 54 5f 44 45 50 52 45 43 41 54 45 44 0a  OMIT_DEPRECATED.
31e00 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45  SQLITE_DEPRECATE
31e10 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 61 67  D int sqlite3_ag
31e20 67 72 65 67 61 74 65 5f 63 6f 75 6e 74 28 73 71  gregate_count(sq
31e30 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b  lite3_context*);
31e40 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54  .SQLITE_DEPRECAT
31e50 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65  ED int sqlite3_e
31e60 78 70 69 72 65 64 28 73 71 6c 69 74 65 33 5f 73  xpired(sqlite3_s
31e70 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45  tmt*);.SQLITE_DE
31e80 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c  PRECATED int sql
31e90 69 74 65 33 5f 74 72 61 6e 73 66 65 72 5f 62 69  ite3_transfer_bi
31ea0 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73  ndings(sqlite3_s
31eb0 74 6d 74 2a 2c 20 73 71 6c 69 74 65 33 5f 73 74  tmt*, sqlite3_st
31ec0 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50  mt*);.SQLITE_DEP
31ed0 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69  RECATED int sqli
31ee0 74 65 33 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f 76  te3_global_recov
31ef0 65 72 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45  er(void);.SQLITE
31f00 5f 44 45 50 52 45 43 41 54 45 44 20 76 6f 69 64  _DEPRECATED void
31f10 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 5f   sqlite3_thread_
31f20 63 6c 65 61 6e 75 70 28 76 6f 69 64 29 3b 0a 53  cleanup(void);.S
31f30 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
31f40 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d   int sqlite3_mem
31f50 6f 72 79 5f 61 6c 61 72 6d 28 76 6f 69 64 28 2a  ory_alarm(void(*
31f60 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f  )(void*,sqlite3_
31f70 69 6e 74 36 34 2c 69 6e 74 29 2c 0a 20 20 20 20  int64,int),.    
31f80 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
31f90 20 20 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f    void*,sqlite3_
31fa0 69 6e 74 36 34 29 3b 0a 23 65 6e 64 69 66 0a 0a  int64);.#endif..
31fb0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
31fc0 4f 62 74 61 69 6e 69 6e 67 20 53 51 4c 20 46 75  Obtaining SQL Fu
31fd0 6e 63 74 69 6f 6e 20 50 61 72 61 6d 65 74 65 72  nction Parameter
31fe0 20 56 61 6c 75 65 73 0a 2a 2a 0a 2a 2a 20 54 68   Values.**.** Th
31ff0 65 20 43 2d 6c 61 6e 67 75 61 67 65 20 69 6d 70  e C-language imp
32000 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 53  lementation of S
32010 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64  QL functions and
32020 20 61 67 67 72 65 67 61 74 65 73 20 75 73 65 73   aggregates uses
32030 0a 2a 2a 20 74 68 69 73 20 73 65 74 20 6f 66 20  .** this set of 
32040 69 6e 74 65 72 66 61 63 65 20 72 6f 75 74 69 6e  interface routin
32050 65 73 20 74 6f 20 61 63 63 65 73 73 20 74 68 65  es to access the
32060 20 70 61 72 61 6d 65 74 65 72 20 76 61 6c 75 65   parameter value
32070 73 20 6f 6e 0a 2a 2a 20 74 68 65 20 66 75 6e 63  s on.** the func
32080 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74  tion or aggregat
32090 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 75  e..**.** The xFu
320a0 6e 63 20 28 66 6f 72 20 73 63 61 6c 61 72 20 66  nc (for scalar f
320b0 75 6e 63 74 69 6f 6e 73 29 20 6f 72 20 78 53 74  unctions) or xSt
320c0 65 70 20 28 66 6f 72 20 61 67 67 72 65 67 61 74  ep (for aggregat
320d0 65 73 29 20 70 61 72 61 6d 65 74 65 72 73 0a 2a  es) parameters.*
320e0 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72  * to [sqlite3_cr
320f0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d  eate_function()]
32100 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72   and [sqlite3_cr
32110 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
32120 29 5d 0a 2a 2a 20 64 65 66 69 6e 65 20 63 61 6c  )].** define cal
32130 6c 62 61 63 6b 73 20 74 68 61 74 20 69 6d 70 6c  lbacks that impl
32140 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75  ement the SQL fu
32150 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72  nctions and aggr
32160 65 67 61 74 65 73 2e 0a 2a 2a 20 54 68 65 20 33  egates..** The 3
32170 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
32180 74 68 65 73 65 20 63 61 6c 6c 62 61 63 6b 73 20  these callbacks 
32190 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70  is an array of p
321a0 6f 69 6e 74 65 72 73 20 74 6f 0a 2a 2a 20 5b 70  ointers to.** [p
321b0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
321c0 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e  _value] objects.
321d0 20 20 54 68 65 72 65 20 69 73 20 6f 6e 65 20 5b    There is one [
321e0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
321f0 62 6a 65 63 74 20 66 6f 72 0a 2a 2a 20 65 61 63  bject for.** eac
32200 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
32210 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e  he SQL function.
32220 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73    These routines
32230 20 61 72 65 20 75 73 65 64 20 74 6f 0a 2a 2a 20   are used to.** 
32240 65 78 74 72 61 63 74 20 76 61 6c 75 65 73 20 66  extract values f
32250 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33  rom the [sqlite3
32260 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e  _value] objects.
32270 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
32280 74 69 6e 65 73 20 77 6f 72 6b 20 6f 6e 6c 79 20  tines work only 
32290 77 69 74 68 20 5b 70 72 6f 74 65 63 74 65 64 20  with [protected 
322a0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
322b0 62 6a 65 63 74 73 2e 0a 2a 2a 20 41 6e 79 20 61  bjects..** Any a
322c0 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68  ttempt to use th
322d0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 20  ese routines on 
322e0 61 6e 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20  an [unprotected 
322f0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a  sqlite3_value].*
32300 2a 20 6f 62 6a 65 63 74 20 72 65 73 75 6c 74 73  * object results
32310 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65   in undefined be
32320 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54  havior..**.** ^T
32330 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f  hese routines wo
32340 72 6b 20 6a 75 73 74 20 6c 69 6b 65 20 74 68 65  rk just like the
32350 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 5b   corresponding [
32360 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75  column access fu
32370 6e 63 74 69 6f 6e 73 5d 0a 2a 2a 20 65 78 63 65  nctions].** exce
32380 70 74 20 74 68 61 74 20 20 74 68 65 73 65 20 72  pt that  these r
32390 6f 75 74 69 6e 65 73 20 74 61 6b 65 20 61 20 73  outines take a s
323a0 69 6e 67 6c 65 20 5b 70 72 6f 74 65 63 74 65 64  ingle [protected
323b0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
323c0 6f 62 6a 65 63 74 0a 2a 2a 20 70 6f 69 6e 74 65  object.** pointe
323d0 72 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 5b  r instead of a [
323e0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 20 70  sqlite3_stmt*] p
323f0 6f 69 6e 74 65 72 20 61 6e 64 20 61 6e 20 69 6e  ointer and an in
32400 74 65 67 65 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d  teger column num
32410 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ber..**.** ^The 
32420 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
32430 78 74 31 36 28 29 20 69 6e 74 65 72 66 61 63 65  xt16() interface
32440 20 65 78 74 72 61 63 74 73 20 61 20 55 54 46 2d   extracts a UTF-
32450 31 36 20 73 74 72 69 6e 67 0a 2a 2a 20 69 6e 20  16 string.** in 
32460 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 2d  the native byte-
32470 6f 72 64 65 72 20 6f 66 20 74 68 65 20 68 6f 73  order of the hos
32480 74 20 6d 61 63 68 69 6e 65 2e 20 20 5e 54 68 65  t machine.  ^The
32490 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  .** sqlite3_valu
324a0 65 5f 74 65 78 74 31 36 62 65 28 29 20 61 6e 64  e_text16be() and
324b0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
324c0 65 78 74 31 36 6c 65 28 29 20 69 6e 74 65 72 66  ext16le() interf
324d0 61 63 65 73 0a 2a 2a 20 65 78 74 72 61 63 74 20  aces.** extract 
324e0 55 54 46 2d 31 36 20 73 74 72 69 6e 67 73 20 61  UTF-16 strings a
324f0 73 20 62 69 67 2d 65 6e 64 69 61 6e 20 61 6e 64  s big-endian and
32500 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 20 72   little-endian r
32510 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a  espectively..**.
32520 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33  ** ^(The sqlite3
32530 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74  _value_numeric_t
32540 79 70 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  ype() interface 
32550 61 74 74 65 6d 70 74 73 20 74 6f 20 61 70 70 6c  attempts to appl
32560 79 0a 2a 2a 20 6e 75 6d 65 72 69 63 20 61 66 66  y.** numeric aff
32570 69 6e 69 74 79 20 74 6f 20 74 68 65 20 76 61 6c  inity to the val
32580 75 65 2e 20 20 54 68 69 73 20 6d 65 61 6e 73 20  ue.  This means 
32590 74 68 61 74 20 61 6e 20 61 74 74 65 6d 70 74 20  that an attempt 
325a0 69 73 0a 2a 2a 20 6d 61 64 65 20 74 6f 20 63 6f  is.** made to co
325b0 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75 65 20  nvert the value 
325c0 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 6f 72  to an integer or
325d0 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 2e   floating point.
325e0 20 20 49 66 0a 2a 2a 20 73 75 63 68 20 61 20 63    If.** such a c
325f0 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 6f 73  onversion is pos
32600 73 69 62 6c 65 20 77 69 74 68 6f 75 74 20 6c 6f  sible without lo
32610 73 73 20 6f 66 20 69 6e 66 6f 72 6d 61 74 69 6f  ss of informatio
32620 6e 20 28 69 6e 20 6f 74 68 65 72 0a 2a 2a 20 77  n (in other.** w
32630 6f 72 64 73 2c 20 69 66 20 74 68 65 20 76 61 6c  ords, if the val
32640 75 65 20 69 73 20 61 20 73 74 72 69 6e 67 20 74  ue is a string t
32650 68 61 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61  hat looks like a
32660 20 6e 75 6d 62 65 72 29 0a 2a 2a 20 74 68 65 6e   number).** then
32670 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20   the conversion 
32680 69 73 20 70 65 72 66 6f 72 6d 65 64 2e 20 20 4f  is performed.  O
32690 74 68 65 72 77 69 73 65 20 6e 6f 20 63 6f 6e 76  therwise no conv
326a0 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 2e 0a 2a  ersion occurs..*
326b0 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 4e  * The [SQLITE_IN
326c0 54 45 47 45 52 20 7c 20 64 61 74 61 74 79 70 65  TEGER | datatype
326d0 5d 20 61 66 74 65 72 20 63 6f 6e 76 65 72 73 69  ] after conversi
326e0 6f 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29  on is returned.)
326f0 5e 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 73 65 20 70  ^.**.** Please p
32700 61 79 20 70 61 72 74 69 63 75 6c 61 72 20 61 74  ay particular at
32710 74 65 6e 74 69 6f 6e 20 74 6f 20 74 68 65 20 66  tention to the f
32720 61 63 74 20 74 68 61 74 20 74 68 65 20 70 6f 69  act that the poi
32730 6e 74 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a  nter returned.**
32740 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 76   from [sqlite3_v
32750 61 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73  alue_blob()], [s
32760 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
32770 74 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c  t()], or.** [sql
32780 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
32790 36 28 29 5d 20 63 61 6e 20 62 65 20 69 6e 76 61  6()] can be inva
327a0 6c 69 64 61 74 65 64 20 62 79 20 61 20 73 75 62  lidated by a sub
327b0 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 0a  sequent call to.
327c0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ** [sqlite3_valu
327d0 65 5f 62 79 74 65 73 28 29 5d 2c 20 5b 73 71 6c  e_bytes()], [sql
327e0 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73  ite3_value_bytes
327f0 31 36 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  16()], [sqlite3_
32800 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a  value_text()],.*
32810 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61  * or [sqlite3_va
32820 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 2e 0a 2a  lue_text16()]..*
32830 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
32840 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c  nes must be call
32850 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65  ed from the same
32860 20 74 68 72 65 61 64 20 61 73 0a 2a 2a 20 74 68   thread as.** th
32870 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74  e SQL function t
32880 68 61 74 20 73 75 70 70 6c 69 65 64 20 74 68 65  hat supplied the
32890 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a   [sqlite3_value*
328a0 5d 20 70 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2f  ] parameters..*/
328b0 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
328c0 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28  ite3_value_blob(
328d0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
328e0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c  .int sqlite3_val
328f0 75 65 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33  ue_bytes(sqlite3
32900 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71  _value*);.int sq
32910 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65  lite3_value_byte
32920 73 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  s16(sqlite3_valu
32930 65 2a 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69  e*);.double sqli
32940 74 65 33 5f 76 61 6c 75 65 5f 64 6f 75 62 6c 65  te3_value_double
32950 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
32960 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61  ;.int sqlite3_va
32970 6c 75 65 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f  lue_int(sqlite3_
32980 76 61 6c 75 65 2a 29 3b 0a 73 71 6c 69 74 65 33  value*);.sqlite3
32990 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 76  _int64 sqlite3_v
329a0 61 6c 75 65 5f 69 6e 74 36 34 28 73 71 6c 69 74  alue_int64(sqlit
329b0 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73  e3_value*);.cons
329c0 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20  t unsigned char 
329d0 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  *sqlite3_value_t
329e0 65 78 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  ext(sqlite3_valu
329f0 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  e*);.const void 
32a00 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  *sqlite3_value_t
32a10 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 76 61  ext16(sqlite3_va
32a20 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  lue*);.const voi
32a30 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  d *sqlite3_value
32a40 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65  _text16le(sqlite
32a50 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74  3_value*);.const
32a60 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76   void *sqlite3_v
32a70 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 73 71  alue_text16be(sq
32a80 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69  lite3_value*);.i
32a90 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt sqlite3_value
32aa0 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61  _type(sqlite3_va
32ab0 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  lue*);.int sqlit
32ac0 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63  e3_value_numeric
32ad0 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61  _type(sqlite3_va
32ae0 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  lue*);../*.** CA
32af0 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 41  PI3REF: Obtain A
32b00 67 67 72 65 67 61 74 65 20 46 75 6e 63 74 69 6f  ggregate Functio
32b10 6e 20 43 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20  n Context.**.** 
32b20 49 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  Implementations 
32b30 6f 66 20 61 67 67 72 65 67 61 74 65 20 53 51 4c  of aggregate SQL
32b40 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 20 74   functions use t
32b50 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 74  his.** routine t
32b60 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72  o allocate memor
32b70 79 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 74 68  y for storing th
32b80 65 69 72 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a  eir state..**.**
32b90 20 5e 54 68 65 20 66 69 72 73 74 20 74 69 6d 65   ^The first time
32ba0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67   the sqlite3_agg
32bb0 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43  regate_context(C
32bc0 2c 4e 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63  ,N) routine is c
32bd0 61 6c 6c 65 64 20 0a 2a 2a 20 66 6f 72 20 61 20  alled .** for a 
32be0 70 61 72 74 69 63 75 6c 61 72 20 61 67 67 72 65  particular aggre
32bf0 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 2c 20 53  gate function, S
32c00 51 4c 69 74 65 0a 2a 2a 20 61 6c 6c 6f 63 61 74  QLite.** allocat
32c10 65 73 20 4e 20 6f 66 20 6d 65 6d 6f 72 79 2c 20  es N of memory, 
32c20 7a 65 72 6f 65 73 20 6f 75 74 20 74 68 61 74 20  zeroes out that 
32c30 6d 65 6d 6f 72 79 2c 20 61 6e 64 20 72 65 74 75  memory, and retu
32c40 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a  rns a pointer.**
32c50 20 74 6f 20 74 68 65 20 6e 65 77 20 6d 65 6d 6f   to the new memo
32c60 72 79 2e 20 5e 4f 6e 20 73 65 63 6f 6e 64 20 61  ry. ^On second a
32c70 6e 64 20 73 75 62 73 65 71 75 65 6e 74 20 63 61  nd subsequent ca
32c80 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  lls to.** sqlite
32c90 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
32ca0 65 78 74 28 29 20 66 6f 72 20 74 68 65 20 73 61  ext() for the sa
32cb0 6d 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e  me aggregate fun
32cc0 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65 2c 0a  ction instance,.
32cd0 2a 2a 20 74 68 65 20 73 61 6d 65 20 62 75 66 66  ** the same buff
32ce0 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  er is returned. 
32cf0 20 53 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   Sqlite3_aggrega
32d00 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 69 73 20  te_context() is 
32d10 6e 6f 72 6d 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c  normally.** call
32d20 65 64 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68  ed once for each
32d30 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 74   invocation of t
32d40 68 65 20 78 53 74 65 70 20 63 61 6c 6c 62 61 63  he xStep callbac
32d50 6b 20 61 6e 64 20 74 68 65 6e 20 6f 6e 65 0a 2a  k and then one.*
32d60 2a 20 6c 61 73 74 20 74 69 6d 65 20 77 68 65 6e  * last time when
32d70 20 74 68 65 20 78 46 69 6e 61 6c 20 63 61 6c 6c   the xFinal call
32d80 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2e  back is invoked.
32d90 20 20 5e 28 57 68 65 6e 20 6e 6f 20 72 6f 77 73    ^(When no rows
32da0 20 6d 61 74 63 68 0a 2a 2a 20 61 6e 20 61 67 67   match.** an agg
32db0 72 65 67 61 74 65 20 71 75 65 72 79 2c 20 74 68  regate query, th
32dc0 65 20 78 53 74 65 70 28 29 20 63 61 6c 6c 62 61  e xStep() callba
32dd0 63 6b 20 6f 66 20 74 68 65 20 61 67 67 72 65 67  ck of the aggreg
32de0 61 74 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  ate function.** 
32df0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69  implementation i
32e00 73 20 6e 65 76 65 72 20 63 61 6c 6c 65 64 20 61  s never called a
32e10 6e 64 20 78 46 69 6e 61 6c 28 29 20 69 73 20 63  nd xFinal() is c
32e20 61 6c 6c 65 64 20 65 78 61 63 74 6c 79 20 6f 6e  alled exactly on
32e30 63 65 2e 0a 2a 2a 20 49 6e 20 74 68 6f 73 65 20  ce..** In those 
32e40 63 61 73 65 73 2c 20 73 71 6c 69 74 65 33 5f 61  cases, sqlite3_a
32e50 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
32e60 28 29 20 6d 69 67 68 74 20 62 65 20 63 61 6c 6c  () might be call
32e70 65 64 20 66 6f 72 20 74 68 65 0a 2a 2a 20 66 69  ed for the.** fi
32e80 72 73 74 20 74 69 6d 65 20 66 72 6f 6d 20 77 69  rst time from wi
32e90 74 68 69 6e 20 78 46 69 6e 61 6c 28 29 2e 29 5e  thin xFinal().)^
32ea0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
32eb0 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
32ec0 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f 75 74 69  ntext(C,N) routi
32ed0 6e 65 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c  ne returns a NUL
32ee0 4c 20 70 6f 69 6e 74 65 72 20 0a 2a 2a 20 77 68  L pointer .** wh
32ef0 65 6e 20 66 69 72 73 74 20 63 61 6c 6c 65 64 20  en first called 
32f00 69 66 20 4e 20 69 73 20 6c 65 73 73 20 74 68 61  if N is less tha
32f10 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65  n or equal to ze
32f20 72 6f 20 6f 72 20 69 66 20 61 20 6d 65 6d 6f 72  ro or if a memor
32f30 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 65 72  y.** allocate er
32f40 72 6f 72 20 6f 63 63 75 72 73 2e 0a 2a 2a 0a 2a  ror occurs..**.*
32f50 2a 20 5e 28 54 68 65 20 61 6d 6f 75 6e 74 20 6f  * ^(The amount o
32f60 66 20 73 70 61 63 65 20 61 6c 6c 6f 63 61 74 65  f space allocate
32f70 64 20 62 79 20 73 71 6c 69 74 65 33 5f 61 67 67  d by sqlite3_agg
32f80 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43  regate_context(C
32f90 2c 4e 29 20 69 73 0a 2a 2a 20 64 65 74 65 72 6d  ,N) is.** determ
32fa0 69 6e 65 64 20 62 79 20 74 68 65 20 4e 20 70 61  ined by the N pa
32fb0 72 61 6d 65 74 65 72 20 6f 6e 20 66 69 72 73 74  rameter on first
32fc0 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c   successful call
32fd0 2e 20 20 43 68 61 6e 67 69 6e 67 20 74 68 65 0a  .  Changing the.
32fe0 2a 2a 20 76 61 6c 75 65 20 6f 66 20 4e 20 69 6e  ** value of N in
32ff0 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   subsequent call
33000 20 74 6f 20 73 71 6c 69 74 65 33 5f 61 67 67 72   to sqlite3_aggr
33010 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20  egate_context() 
33020 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20 73 61  within.** the sa
33030 6d 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e  me aggregate fun
33040 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65 20 77  ction instance w
33050 69 6c 6c 20 6e 6f 74 20 72 65 73 69 7a 65 20 74  ill not resize t
33060 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c  he memory.** all
33070 6f 63 61 74 69 6f 6e 2e 29 5e 20 20 57 69 74 68  ocation.)^  With
33080 69 6e 20 74 68 65 20 78 46 69 6e 61 6c 20 63 61  in the xFinal ca
33090 6c 6c 62 61 63 6b 2c 20 69 74 20 69 73 20 63 75  llback, it is cu
330a0 73 74 6f 6d 61 72 79 20 74 6f 20 73 65 74 0a 2a  stomary to set.*
330b0 2a 20 4e 3d 30 20 69 6e 20 63 61 6c 6c 73 20 74  * N=0 in calls t
330c0 6f 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  o sqlite3_aggreg
330d0 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29  ate_context(C,N)
330e0 20 73 6f 20 74 68 61 74 20 6e 6f 20 0a 2a 2a 20   so that no .** 
330f0 70 6f 69 6e 74 6c 65 73 73 20 6d 65 6d 6f 72 79  pointless memory
33100 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 6f 63 63   allocations occ
33110 75 72 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74  ur..**.** ^SQLit
33120 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  e automatically 
33130 66 72 65 65 73 20 74 68 65 20 6d 65 6d 6f 72 79  frees the memory
33140 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 0a 2a   allocated by .*
33150 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  * sqlite3_aggreg
33160 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 77 68  ate_context() wh
33170 65 6e 20 74 68 65 20 61 67 67 72 65 67 61 74 65  en the aggregate
33180 20 71 75 65 72 79 20 63 6f 6e 63 6c 75 64 65 73   query concludes
33190 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73  ..**.** The firs
331a0 74 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74  t parameter must
331b0 20 62 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68   be a copy of th
331c0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  e.** [sqlite3_co
331d0 6e 74 65 78 74 20 7c 20 53 51 4c 20 66 75 6e 63  ntext | SQL func
331e0 74 69 6f 6e 20 63 6f 6e 74 65 78 74 5d 20 74 68  tion context] th
331f0 61 74 20 69 73 20 74 68 65 20 66 69 72 73 74 20  at is the first 
33200 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20  parameter.** to 
33210 74 68 65 20 78 53 74 65 70 20 6f 72 20 78 46 69  the xStep or xFi
33220 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75  nal callback rou
33230 74 69 6e 65 20 74 68 61 74 20 69 6d 70 6c 65 6d  tine that implem
33240 65 6e 74 73 20 74 68 65 20 61 67 67 72 65 67 61  ents the aggrega
33250 74 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 0a  te.** function..
33260 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  **.** This routi
33270 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65  ne must be calle
33280 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20  d from the same 
33290 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a  thread in which.
332a0 2a 2a 20 74 68 65 20 61 67 67 72 65 67 61 74 65  ** the aggregate
332b0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73   SQL function is
332c0 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69   running..*/.voi
332d0 64 20 2a 73 71 6c 69 74 65 33 5f 61 67 67 72 65  d *sqlite3_aggre
332e0 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 73 71 6c  gate_context(sql
332f0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69  ite3_context*, i
33300 6e 74 20 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a  nt nBytes);../*.
33310 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 55 73 65  ** CAPI3REF: Use
33320 72 20 44 61 74 61 20 46 6f 72 20 46 75 6e 63 74  r Data For Funct
33330 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ions.**.** ^The 
33340 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74  sqlite3_user_dat
33350 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  a() interface re
33360 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a  turns a copy of.
33370 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74  ** the pointer t
33380 68 61 74 20 77 61 73 20 74 68 65 20 70 55 73 65  hat was the pUse
33390 72 44 61 74 61 20 70 61 72 61 6d 65 74 65 72 20  rData parameter 
333a0 28 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74  (the 5th paramet
333b0 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73  er).** of the [s
333c0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
333d0 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64  nction()].** and
333e0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
333f0 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72  _function16()] r
33400 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69  outines that ori
33410 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73  ginally.** regis
33420 74 65 72 65 64 20 74 68 65 20 61 70 70 6c 69 63  tered the applic
33430 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75  ation defined fu
33440 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68  nction..**.** Th
33450 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20  is routine must 
33460 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74  be called from t
33470 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69  he same thread i
33480 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61  n which.** the a
33490 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
334a0 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72  ed function is r
334b0 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20  unning..*/.void 
334c0 2a 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61  *sqlite3_user_da
334d0 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ta(sqlite3_conte
334e0 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  xt*);../*.** CAP
334f0 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 20  I3REF: Database 
33500 43 6f 6e 6e 65 63 74 69 6f 6e 20 46 6f 72 20 46  Connection For F
33510 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e  unctions.**.** ^
33520 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74  The sqlite3_cont
33530 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 20  ext_db_handle() 
33540 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
33550 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74  s a copy of.** t
33560 68 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68  he pointer to th
33570 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
33580 65 63 74 69 6f 6e 5d 20 28 74 68 65 20 31 73 74  ection] (the 1st
33590 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f   parameter).** o
335a0 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  f the [sqlite3_c
335b0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
335c0 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65  ].** and [sqlite
335d0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
335e0 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20  n16()] routines 
335f0 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a  that originally.
33600 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20 74 68  ** registered th
33610 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65  e application de
33620 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a  fined function..
33630 2a 2f 0a 73 71 6c 69 74 65 33 20 2a 73 71 6c 69  */.sqlite3 *sqli
33640 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68  te3_context_db_h
33650 61 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f  andle(sqlite3_co
33660 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ntext*);../*.** 
33670 43 41 50 49 33 52 45 46 3a 20 46 75 6e 63 74 69  CAPI3REF: Functi
33680 6f 6e 20 41 75 78 69 6c 69 61 72 79 20 44 61 74  on Auxiliary Dat
33690 61 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75  a.**.** These fu
336a0 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 75  nctions may be u
336b0 73 65 64 20 62 79 20 28 6e 6f 6e 2d 61 67 67 72  sed by (non-aggr
336c0 65 67 61 74 65 29 20 53 51 4c 20 66 75 6e 63 74  egate) SQL funct
336d0 69 6f 6e 73 20 74 6f 0a 2a 2a 20 61 73 73 6f 63  ions to.** assoc
336e0 69 61 74 65 20 6d 65 74 61 64 61 74 61 20 77 69  iate metadata wi
336f0 74 68 20 61 72 67 75 6d 65 6e 74 20 76 61 6c 75  th argument valu
33700 65 73 2e 20 49 66 20 74 68 65 20 73 61 6d 65 20  es. If the same 
33710 76 61 6c 75 65 20 69 73 20 70 61 73 73 65 64 20  value is passed 
33720 74 6f 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 69  to.** multiple i
33730 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68  nvocations of th
33740 65 20 73 61 6d 65 20 53 51 4c 20 66 75 6e 63 74  e same SQL funct
33750 69 6f 6e 20 64 75 72 69 6e 67 20 71 75 65 72 79  ion during query
33760 20 65 78 65 63 75 74 69 6f 6e 2c 20 75 6e 64 65   execution, unde
33770 72 0a 2a 2a 20 73 6f 6d 65 20 63 69 72 63 75 6d  r.** some circum
33780 73 74 61 6e 63 65 73 20 74 68 65 20 61 73 73 6f  stances the asso
33790 63 69 61 74 65 64 20 6d 65 74 61 64 61 74 61 20  ciated metadata 
337a0 6d 61 79 20 62 65 20 70 72 65 73 65 72 76 65 64  may be preserved
337b0 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 0a 2a 2a  .  An example.**
337c0 20 6f 66 20 77 68 65 72 65 20 74 68 69 73 20 6d   of where this m
337d0 69 67 68 74 20 62 65 20 75 73 65 66 75 6c 20 69  ight be useful i
337e0 73 20 69 6e 20 61 20 72 65 67 75 6c 61 72 2d 65  s in a regular-e
337f0 78 70 72 65 73 73 69 6f 6e 20 6d 61 74 63 68 69  xpression matchi
33800 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 20  ng.** function. 
33810 54 68 65 20 63 6f 6d 70 69 6c 65 64 20 76 65 72  The compiled ver
33820 73 69 6f 6e 20 6f 66 20 74 68 65 20 72 65 67 75  sion of the regu
33830 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20 63  lar expression c
33840 61 6e 20 62 65 20 73 74 6f 72 65 64 20 61 73 0a  an be stored as.
33850 2a 2a 20 6d 65 74 61 64 61 74 61 20 61 73 73 6f  ** metadata asso
33860 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20  ciated with the 
33870 70 61 74 74 65 72 6e 20 73 74 72 69 6e 67 2e 20  pattern string. 
33880 20 0a 2a 2a 20 54 68 65 6e 20 61 73 20 6c 6f 6e   .** Then as lon
33890 67 20 61 73 20 74 68 65 20 70 61 74 74 65 72 6e  g as the pattern
338a0 20 73 74 72 69 6e 67 20 72 65 6d 61 69 6e 73 20   string remains 
338b0 74 68 65 20 73 61 6d 65 2c 0a 2a 2a 20 74 68 65  the same,.** the
338c0 20 63 6f 6d 70 69 6c 65 64 20 72 65 67 75 6c 61   compiled regula
338d0 72 20 65 78 70 72 65 73 73 69 6f 6e 20 63 61 6e  r expression can
338e0 20 62 65 20 72 65 75 73 65 64 20 6f 6e 20 6d 75   be reused on mu
338f0 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f 63 61  ltiple.** invoca
33900 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d  tions of the sam
33910 65 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a  e function..**.*
33920 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67  * ^The sqlite3_g
33930 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74  et_auxdata() int
33940 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
33950 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
33960 6d 65 74 61 64 61 74 61 0a 2a 2a 20 61 73 73 6f  metadata.** asso
33970 63 69 61 74 65 64 20 62 79 20 74 68 65 20 73 71  ciated by the sq
33980 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
33990 61 28 29 20 66 75 6e 63 74 69 6f 6e 20 77 69 74  a() function wit
339a0 68 20 74 68 65 20 4e 74 68 20 61 72 67 75 6d 65  h the Nth argume
339b0 6e 74 0a 2a 2a 20 76 61 6c 75 65 20 74 6f 20 74  nt.** value to t
339c0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
339d0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e  efined function.
339e0 20 5e 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f   ^If there is no
339f0 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 61 73 73   metadata.** ass
33a00 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65  ociated with the
33a10 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65   function argume
33a20 6e 74 2c 20 74 68 69 73 20 73 71 6c 69 74 65 33  nt, this sqlite3
33a30 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 20 69  _get_auxdata() i
33a40 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 65 74 75  nterface.** retu
33a50 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  rns a NULL point
33a60 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  er..**.** ^The s
33a70 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
33a80 74 61 28 43 2c 4e 2c 50 2c 58 29 20 69 6e 74 65  ta(C,N,P,X) inte
33a90 72 66 61 63 65 20 73 61 76 65 73 20 50 20 61 73  rface saves P as
33aa0 20 6d 65 74 61 64 61 74 61 20 66 6f 72 20 74 68   metadata for th
33ab0 65 20 4e 2d 74 68 0a 2a 2a 20 61 72 67 75 6d 65  e N-th.** argume
33ac0 6e 74 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63  nt of the applic
33ad0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
33ae0 6e 63 74 69 6f 6e 2e 20 20 5e 53 75 62 73 65 71  nction.  ^Subseq
33af0 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f  uent.** calls to
33b00 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78   sqlite3_get_aux
33b10 64 61 74 61 28 43 2c 4e 29 20 72 65 74 75 72 6e  data(C,N) return
33b20 20 50 20 66 72 6f 6d 20 74 68 65 20 6d 6f 73 74   P from the most
33b30 20 72 65 63 65 6e 74 0a 2a 2a 20 73 71 6c 69 74   recent.** sqlit
33b40 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 43  e3_set_auxdata(C
33b50 2c 4e 2c 50 2c 58 29 20 63 61 6c 6c 20 69 66 20  ,N,P,X) call if 
33b60 74 68 65 20 6d 65 74 61 64 61 74 61 20 69 73 20  the metadata is 
33b70 73 74 69 6c 6c 20 76 61 6c 69 64 20 6f 72 0a 2a  still valid or.*
33b80 2a 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 6d 65  * NULL if the me
33b90 74 61 64 61 74 61 20 68 61 73 20 62 65 65 6e 20  tadata has been 
33ba0 64 69 73 63 61 72 64 65 64 2e 0a 2a 2a 20 5e 41  discarded..** ^A
33bb0 66 74 65 72 20 65 61 63 68 20 63 61 6c 6c 20 74  fter each call t
33bc0 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  o sqlite3_set_au
33bd0 78 64 61 74 61 28 43 2c 4e 2c 50 2c 58 29 20 77  xdata(C,N,P,X) w
33be0 68 65 72 65 20 58 20 69 73 20 6e 6f 74 20 4e 55  here X is not NU
33bf0 4c 4c 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69  LL,.** SQLite wi
33c00 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20 64 65  ll invoke the de
33c10 73 74 72 75 63 74 6f 72 20 66 75 6e 63 74 69 6f  structor functio
33c20 6e 20 58 20 77 69 74 68 20 70 61 72 61 6d 65 74  n X with paramet
33c30 65 72 20 50 20 65 78 61 63 74 6c 79 0a 2a 2a 20  er P exactly.** 
33c40 6f 6e 63 65 2c 20 77 68 65 6e 20 74 68 65 20 6d  once, when the m
33c50 65 74 61 64 61 74 61 20 69 73 20 64 69 73 63 61  etadata is disca
33c60 72 64 65 64 2e 0a 2a 2a 20 53 51 4c 69 74 65 20  rded..** SQLite 
33c70 69 73 20 66 72 65 65 20 74 6f 20 64 69 73 63 61  is free to disca
33c80 72 64 20 74 68 65 20 6d 65 74 61 64 61 74 61 20  rd the metadata 
33c90 61 74 20 61 6e 79 20 74 69 6d 65 2c 20 69 6e 63  at any time, inc
33ca0 6c 75 64 69 6e 67 3a 20 3c 75 6c 3e 0a 2a 2a 20  luding: <ul>.** 
33cb0 3c 6c 69 3e 20 77 68 65 6e 20 74 68 65 20 63 6f  <li> when the co
33cc0 72 72 65 73 70 6f 6e 64 69 6e 67 20 66 75 6e 63  rresponding func
33cd0 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 20 63  tion parameter c
33ce0 68 61 6e 67 65 73 2c 20 6f 72 0a 2a 2a 20 3c 6c  hanges, or.** <l
33cf0 69 3e 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33  i> when [sqlite3
33d00 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71  _reset()] or [sq
33d10 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
33d20 5d 20 69 73 20 63 61 6c 6c 65 64 20 66 6f 72 20  ] is called for 
33d30 74 68 65 0a 2a 2a 20 20 20 20 20 20 53 51 4c 20  the.**      SQL 
33d40 73 74 61 74 65 6d 65 6e 74 2c 20 6f 72 0a 2a 2a  statement, or.**
33d50 20 3c 6c 69 3e 20 77 68 65 6e 20 73 71 6c 69 74   <li> when sqlit
33d60 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29  e3_set_auxdata()
33d70 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 67 61 69   is invoked agai
33d80 6e 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 70 61  n on the same pa
33d90 72 61 6d 65 74 65 72 2c 20 6f 72 0a 2a 2a 20 3c  rameter, or.** <
33da0 6c 69 3e 20 64 75 72 69 6e 67 20 74 68 65 20 6f  li> during the o
33db0 72 69 67 69 6e 61 6c 20 73 71 6c 69 74 65 33 5f  riginal sqlite3_
33dc0 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 63 61  set_auxdata() ca
33dd0 6c 6c 20 77 68 65 6e 20 61 20 6d 65 6d 6f 72 79  ll when a memory
33de0 20 0a 2a 2a 20 20 20 20 20 20 61 6c 6c 6f 63 61   .**      alloca
33df0 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  tion error occur
33e00 73 2e 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a  s. </ul>)^.**.**
33e10 20 4e 6f 74 65 20 74 68 65 20 6c 61 73 74 20 62   Note the last b
33e20 75 6c 6c 65 74 20 69 6e 20 70 61 72 74 69 63 75  ullet in particu
33e30 6c 61 72 2e 20 20 54 68 65 20 64 65 73 74 72 75  lar.  The destru
33e40 63 74 6f 72 20 58 20 69 6e 20 0a 2a 2a 20 73 71  ctor X in .** sq
33e50 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
33e60 61 28 43 2c 4e 2c 50 2c 58 29 20 6d 69 67 68 74  a(C,N,P,X) might
33e70 20 62 65 20 63 61 6c 6c 65 64 20 69 6d 6d 65 64   be called immed
33e80 69 61 74 65 6c 79 2c 20 62 65 66 6f 72 65 20 74  iately, before t
33e90 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 65  he.** sqlite3_se
33ea0 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74 65  t_auxdata() inte
33eb0 72 66 61 63 65 20 65 76 65 6e 20 72 65 74 75 72  rface even retur
33ec0 6e 73 2e 20 20 48 65 6e 63 65 20 73 71 6c 69 74  ns.  Hence sqlit
33ed0 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29  e3_set_auxdata()
33ee0 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 63 61  .** should be ca
33ef0 6c 6c 65 64 20 6e 65 61 72 20 74 68 65 20 65 6e  lled near the en
33f00 64 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f  d of the functio
33f10 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
33f20 20 61 6e 64 20 74 68 65 0a 2a 2a 20 66 75 6e 63   and the.** func
33f30 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  tion implementat
33f40 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 6f 74 20 6d  ion should not m
33f50 61 6b 65 20 61 6e 79 20 75 73 65 20 6f 66 20 50  ake any use of P
33f60 20 61 66 74 65 72 0a 2a 2a 20 73 71 6c 69 74 65   after.** sqlite
33f70 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20  3_set_auxdata() 
33f80 68 61 73 20 62 65 65 6e 20 63 61 6c 6c 65 64 2e  has been called.
33f90 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 70 72 61 63  .**.** ^(In prac
33fa0 74 69 63 65 2c 20 6d 65 74 61 64 61 74 61 20 69  tice, metadata i
33fb0 73 20 70 72 65 73 65 72 76 65 64 20 62 65 74 77  s preserved betw
33fc0 65 65 6e 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c  een function cal
33fd0 6c 73 20 66 6f 72 0a 2a 2a 20 66 75 6e 63 74 69  ls for.** functi
33fe0 6f 6e 20 70 61 72 61 6d 65 74 65 72 73 20 74 68  on parameters th
33ff0 61 74 20 61 72 65 20 63 6f 6d 70 69 6c 65 2d 74  at are compile-t
34000 69 6d 65 20 63 6f 6e 73 74 61 6e 74 73 2c 20 69  ime constants, i
34010 6e 63 6c 75 64 69 6e 67 20 6c 69 74 65 72 61 6c  ncluding literal
34020 0a 2a 2a 20 76 61 6c 75 65 73 20 61 6e 64 20 5b  .** values and [
34030 70 61 72 61 6d 65 74 65 72 73 5d 20 61 6e 64 20  parameters] and 
34040 65 78 70 72 65 73 73 69 6f 6e 73 20 63 6f 6d 70  expressions comp
34050 6f 73 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61  osed from the sa
34060 6d 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  me.)^.**.** Thes
34070 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20  e routines must 
34080 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74  be called from t
34090 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69  he same thread i
340a0 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 53  n which.** the S
340b0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72  QL function is r
340c0 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20  unning..*/.void 
340d0 2a 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78  *sqlite3_get_aux
340e0 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e  data(sqlite3_con
340f0 74 65 78 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 76  text*, int N);.v
34100 6f 69 64 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  oid sqlite3_set_
34110 61 75 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f  auxdata(sqlite3_
34120 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 2c  context*, int N,
34130 20 76 6f 69 64 2a 2c 20 76 6f 69 64 20 28 2a 29   void*, void (*)
34140 28 76 6f 69 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a  (void*));.../*.*
34150 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 73  * CAPI3REF: Cons
34160 74 61 6e 74 73 20 44 65 66 69 6e 69 6e 67 20 53  tants Defining S
34170 70 65 63 69 61 6c 20 44 65 73 74 72 75 63 74 6f  pecial Destructo
34180 72 20 42 65 68 61 76 69 6f 72 0a 2a 2a 0a 2a 2a  r Behavior.**.**
34190 20 54 68 65 73 65 20 61 72 65 20 73 70 65 63 69   These are speci
341a0 61 6c 20 76 61 6c 75 65 73 20 66 6f 72 20 74 68  al values for th
341b0 65 20 64 65 73 74 72 75 63 74 6f 72 20 74 68 61  e destructor tha
341c0 74 20 69 73 20 70 61 73 73 65 64 20 69 6e 20 61  t is passed in a
341d0 73 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 61  s the.** final a
341e0 72 67 75 6d 65 6e 74 20 74 6f 20 72 6f 75 74 69  rgument to routi
341f0 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65  nes like [sqlite
34200 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 5d  3_result_blob()]
34210 2e 20 20 5e 49 66 20 74 68 65 20 64 65 73 74 72  .  ^If the destr
34220 75 63 74 6f 72 0a 2a 2a 20 61 72 67 75 6d 65 6e  uctor.** argumen
34230 74 20 69 73 20 53 51 4c 49 54 45 5f 53 54 41 54  t is SQLITE_STAT
34240 49 43 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61  IC, it means tha
34250 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 70 6f  t the content po
34260 69 6e 74 65 72 20 69 73 20 63 6f 6e 73 74 61 6e  inter is constan
34270 74 0a 2a 2a 20 61 6e 64 20 77 69 6c 6c 20 6e 65  t.** and will ne
34280 76 65 72 20 63 68 61 6e 67 65 2e 20 20 49 74 20  ver change.  It 
34290 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f  does not need to
342a0 20 62 65 20 64 65 73 74 72 6f 79 65 64 2e 20 20   be destroyed.  
342b0 5e 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 54  ^The.** SQLITE_T
342c0 52 41 4e 53 49 45 4e 54 20 76 61 6c 75 65 20 6d  RANSIENT value m
342d0 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 63 6f  eans that the co
342e0 6e 74 65 6e 74 20 77 69 6c 6c 20 6c 69 6b 65 6c  ntent will likel
342f0 79 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 74  y change in.** t
34300 68 65 20 6e 65 61 72 20 66 75 74 75 72 65 20 61  he near future a
34310 6e 64 20 74 68 61 74 20 53 51 4c 69 74 65 20 73  nd that SQLite s
34320 68 6f 75 6c 64 20 6d 61 6b 65 20 69 74 73 20 6f  hould make its o
34330 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20  wn private copy 
34340 6f 66 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e  of.** the conten
34350 74 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e 69  t before returni
34360 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 79  ng..**.** The ty
34370 70 65 64 65 66 20 69 73 20 6e 65 63 65 73 73 61  pedef is necessa
34380 72 79 20 74 6f 20 77 6f 72 6b 20 61 72 6f 75 6e  ry to work aroun
34390 64 20 70 72 6f 62 6c 65 6d 73 20 69 6e 20 63 65  d problems in ce
343a0 72 74 61 69 6e 0a 2a 2a 20 43 2b 2b 20 63 6f 6d  rtain.** C++ com
343b0 70 69 6c 65 72 73 2e 0a 2a 2f 0a 74 79 70 65 64  pilers..*/.typed
343c0 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 74 65  ef void (*sqlite
343d0 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70  3_destructor_typ
343e0 65 29 28 76 6f 69 64 2a 29 3b 0a 23 64 65 66 69  e)(void*);.#defi
343f0 6e 65 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43  ne SQLITE_STATIC
34400 20 20 20 20 20 20 28 28 73 71 6c 69 74 65 33 5f        ((sqlite3_
34410 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29  destructor_type)
34420 30 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  0).#define SQLIT
34430 45 5f 54 52 41 4e 53 49 45 4e 54 20 20 20 28 28  E_TRANSIENT   ((
34440 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74  sqlite3_destruct
34450 6f 72 5f 74 79 70 65 29 2d 31 29 0a 0a 2f 2a 0a  or_type)-1)../*.
34460 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 74  ** CAPI3REF: Set
34470 74 69 6e 67 20 54 68 65 20 52 65 73 75 6c 74 20  ting The Result 
34480 4f 66 20 41 6e 20 53 51 4c 20 46 75 6e 63 74 69  Of An SQL Functi
34490 6f 6e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  on.**.** These r
344a0 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 64  outines are used
344b0 20 62 79 20 74 68 65 20 78 46 75 6e 63 20 6f 72   by the xFunc or
344c0 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b   xFinal callback
344d0 73 20 74 68 61 74 0a 2a 2a 20 69 6d 70 6c 65 6d  s that.** implem
344e0 65 6e 74 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ent SQL function
344f0 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73  s and aggregates
34500 2e 20 20 53 65 65 0a 2a 2a 20 5b 73 71 6c 69 74  .  See.** [sqlit
34510 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
34520 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  on()] and [sqlit
34530 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
34540 6f 6e 31 36 28 29 5d 0a 2a 2a 20 66 6f 72 20 61  on16()].** for a
34550 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d  dditional inform
34560 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ation..**.** The
34570 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 77 6f 72  se functions wor
34580 6b 20 76 65 72 79 20 6d 75 63 68 20 6c 69 6b 65  k very much like
34590 20 74 68 65 20 5b 70 61 72 61 6d 65 74 65 72 20   the [parameter 
345a0 62 69 6e 64 69 6e 67 5d 20 66 61 6d 69 6c 79 20  binding] family 
345b0 6f 66 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20  of.** functions 
345c0 75 73 65 64 20 74 6f 20 62 69 6e 64 20 76 61 6c  used to bind val
345d0 75 65 73 20 74 6f 20 68 6f 73 74 20 70 61 72 61  ues to host para
345e0 6d 65 74 65 72 73 20 69 6e 20 70 72 65 70 61 72  meters in prepar
345f0 65 64 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a  ed statements..*
34600 2a 20 52 65 66 65 72 20 74 6f 20 74 68 65 20 5b  * Refer to the [
34610 53 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 64  SQL parameter] d
34620 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72  ocumentation for
34630 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f   additional info
34640 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e  rmation..**.** ^
34650 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
34660 6c 74 5f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66  lt_blob() interf
34670 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73  ace sets the res
34680 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61  ult from.** an a
34690 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
346a0 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
346b0 65 20 74 68 65 20 42 4c 4f 42 20 77 68 6f 73 65  e the BLOB whose
346c0 20 63 6f 6e 74 65 6e 74 20 69 73 20 70 6f 69 6e   content is poin
346d0 74 65 64 0a 2a 2a 20 74 6f 20 62 79 20 74 68 65  ted.** to by the
346e0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
346f0 72 20 61 6e 64 20 77 68 69 63 68 20 69 73 20 4e  r and which is N
34700 20 62 79 74 65 73 20 6c 6f 6e 67 20 77 68 65 72   bytes long wher
34710 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20 74 68  e N is the.** th
34720 69 72 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  ird parameter..*
34730 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
34740 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f  3_result_zeroblo
34750 62 28 29 20 69 6e 74 65 72 66 61 63 65 73 20 73  b() interfaces s
34760 65 74 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66  et the result of
34770 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74  .** the applicat
34780 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
34790 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 42 4c 4f  tion to be a BLO
347a0 42 20 63 6f 6e 74 61 69 6e 69 6e 67 20 61 6c 6c  B containing all
347b0 20 7a 65 72 6f 0a 2a 2a 20 62 79 74 65 73 20 61   zero.** bytes a
347c0 6e 64 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69  nd N bytes in si
347d0 7a 65 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74  ze, where N is t
347e0 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  he value of the 
347f0 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  2nd parameter..*
34800 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
34810 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28  3_result_double(
34820 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73  ) interface sets
34830 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d   the result from
34840 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69  .** an applicati
34850 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
34860 69 6f 6e 20 74 6f 20 62 65 20 61 20 66 6c 6f 61  ion to be a floa
34870 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65  ting point value
34880 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79   specified.** by
34890 20 69 74 73 20 32 6e 64 20 61 72 67 75 6d 65 6e   its 2nd argumen
348a0 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  t..**.** ^The sq
348b0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
348c0 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  or() and sqlite3
348d0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
348e0 29 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 63  ) functions.** c
348f0 61 75 73 65 20 74 68 65 20 69 6d 70 6c 65 6d 65  ause the impleme
34900 6e 74 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  nted SQL functio
34910 6e 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 78  n to throw an ex
34920 63 65 70 74 69 6f 6e 2e 0a 2a 2a 20 5e 53 51 4c  ception..** ^SQL
34930 69 74 65 20 75 73 65 73 20 74 68 65 20 73 74 72  ite uses the str
34940 69 6e 67 20 70 6f 69 6e 74 65 64 20 74 6f 20 62  ing pointed to b
34950 79 20 74 68 65 0a 2a 2a 20 32 6e 64 20 70 61 72  y the.** 2nd par
34960 61 6d 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65  ameter of sqlite
34970 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
34980 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75   or sqlite3_resu
34990 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20  lt_error16().** 
349a0 61 73 20 74 68 65 20 74 65 78 74 20 6f 66 20 61  as the text of a
349b0 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e  n error message.
349c0 20 20 5e 53 51 4c 69 74 65 20 69 6e 74 65 72 70    ^SQLite interp
349d0 72 65 74 73 20 74 68 65 20 65 72 72 6f 72 0a 2a  rets the error.*
349e0 2a 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67  * message string
349f0 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65   from sqlite3_re
34a00 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 73 20  sult_error() as 
34a10 55 54 46 2d 38 2e 20 5e 53 51 4c 69 74 65 0a 2a  UTF-8. ^SQLite.*
34a20 2a 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 65  * interprets the
34a30 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c   string from sql
34a40 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
34a50 72 31 36 28 29 20 61 73 20 55 54 46 2d 31 36 20  r16() as UTF-16 
34a60 69 6e 20 6e 61 74 69 76 65 0a 2a 2a 20 62 79 74  in native.** byt
34a70 65 20 6f 72 64 65 72 2e 20 20 5e 49 66 20 74 68  e order.  ^If th
34a80 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
34a90 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73  r to sqlite3_res
34aa0 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f  ult_error().** o
34ab0 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  r sqlite3_result
34ac0 5f 65 72 72 6f 72 31 36 28 29 20 69 73 20 6e 65  _error16() is ne
34ad0 67 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69  gative then SQLi
34ae0 74 65 20 74 61 6b 65 73 20 61 73 20 74 68 65 20  te takes as the 
34af0 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65  error.** message
34b00 20 61 6c 6c 20 74 65 78 74 20 75 70 20 74 68 72   all text up thr
34b10 6f 75 67 68 20 74 68 65 20 66 69 72 73 74 20 7a  ough the first z
34b20 65 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a  ero character..*
34b30 2a 20 5e 49 66 20 74 68 65 20 74 68 69 72 64 20  * ^If the third 
34b40 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
34b50 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
34b60 72 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  r() or.** sqlite
34b70 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
34b80 28 29 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69  () is non-negati
34b90 76 65 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74  ve then SQLite t
34ba0 61 6b 65 73 20 74 68 61 74 20 6d 61 6e 79 0a 2a  akes that many.*
34bb0 2a 20 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61  * bytes (not cha
34bc0 72 61 63 74 65 72 73 29 20 66 72 6f 6d 20 74 68  racters) from th
34bd0 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  e 2nd parameter 
34be0 61 73 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73  as the error mes
34bf0 73 61 67 65 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  sage..** ^The sq
34c00 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
34c10 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  or() and sqlite3
34c20 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
34c30 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 6d 61  ).** routines ma
34c40 6b 65 20 61 20 70 72 69 76 61 74 65 20 63 6f 70  ke a private cop
34c50 79 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20 6d  y of the error m
34c60 65 73 73 61 67 65 20 74 65 78 74 20 62 65 66 6f  essage text befo
34c70 72 65 0a 2a 2a 20 74 68 65 79 20 72 65 74 75 72  re.** they retur
34c80 6e 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20 63  n.  Hence, the c
34c90 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  alling function 
34ca0 63 61 6e 20 64 65 61 6c 6c 6f 63 61 74 65 20 6f  can deallocate o
34cb0 72 0a 2a 2a 20 6d 6f 64 69 66 79 20 74 68 65 20  r.** modify the 
34cc0 74 65 78 74 20 61 66 74 65 72 20 74 68 65 79 20  text after they 
34cd0 72 65 74 75 72 6e 20 77 69 74 68 6f 75 74 20 68  return without h
34ce0 61 72 6d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  arm..** ^The sql
34cf0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
34d00 72 5f 63 6f 64 65 28 29 20 66 75 6e 63 74 69 6f  r_code() functio
34d10 6e 20 63 68 61 6e 67 65 73 20 74 68 65 20 65 72  n changes the er
34d20 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 72 65 74 75  ror code.** retu
34d30 72 6e 65 64 20 62 79 20 53 51 4c 69 74 65 20 61  rned by SQLite a
34d40 73 20 61 20 72 65 73 75 6c 74 20 6f 66 20 61 6e  s a result of an
34d50 20 65 72 72 6f 72 20 69 6e 20 61 20 66 75 6e 63   error in a func
34d60 74 69 6f 6e 2e 20 20 5e 42 79 20 64 65 66 61 75  tion.  ^By defau
34d70 6c 74 2c 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72  lt,.** the error
34d80 20 63 6f 64 65 20 69 73 20 53 51 4c 49 54 45 5f   code is SQLITE_
34d90 45 52 52 4f 52 2e 20 20 5e 41 20 73 75 62 73 65  ERROR.  ^A subse
34da0 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71  quent call to sq
34db0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
34dc0 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74  or().** or sqlit
34dd0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
34de0 36 28 29 20 72 65 73 65 74 73 20 74 68 65 20 65  6() resets the e
34df0 72 72 6f 72 20 63 6f 64 65 20 74 6f 20 53 51 4c  rror code to SQL
34e00 49 54 45 5f 45 52 52 4f 52 2e 0a 2a 2a 0a 2a 2a  ITE_ERROR..**.**
34e10 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
34e20 73 75 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69  sult_error_toobi
34e30 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 63 61  g() interface ca
34e40 75 73 65 73 20 53 51 4c 69 74 65 20 74 6f 20 74  uses SQLite to t
34e50 68 72 6f 77 20 61 6e 0a 2a 2a 20 65 72 72 6f 72  hrow an.** error
34e60 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74   indicating that
34e70 20 61 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f   a string or BLO
34e80 42 20 69 73 20 74 6f 6f 20 6c 6f 6e 67 20 74 6f  B is too long to
34e90 20 72 65 70 72 65 73 65 6e 74 2e 0a 2a 2a 0a 2a   represent..**.*
34ea0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
34eb0 65 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65  esult_error_nome
34ec0 6d 28 29 20 69 6e 74 65 72 66 61 63 65 20 63 61  m() interface ca
34ed0 75 73 65 73 20 53 51 4c 69 74 65 20 74 6f 20 74  uses SQLite to t
34ee0 68 72 6f 77 20 61 6e 0a 2a 2a 20 65 72 72 6f 72  hrow an.** error
34ef0 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74   indicating that
34f00 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
34f10 74 69 6f 6e 20 66 61 69 6c 65 64 2e 0a 2a 2a 0a  tion failed..**.
34f20 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
34f30 72 65 73 75 6c 74 5f 69 6e 74 28 29 20 69 6e 74  result_int() int
34f40 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20  erface sets the 
34f50 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20  return value.** 
34f60 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  of the applicati
34f70 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
34f80 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 33 32  ion to be the 32
34f90 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65  -bit signed inte
34fa0 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76  ger.** value giv
34fb0 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 20 61 72  en in the 2nd ar
34fc0 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20  gument..** ^The 
34fd0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69  sqlite3_result_i
34fe0 6e 74 36 34 28 29 20 69 6e 74 65 72 66 61 63 65  nt64() interface
34ff0 20 73 65 74 73 20 74 68 65 20 72 65 74 75 72 6e   sets the return
35000 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65   value.** of the
35010 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
35020 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f  ined function to
35030 20 62 65 20 74 68 65 20 36 34 2d 62 69 74 20 73   be the 64-bit s
35040 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a  igned integer.**
35050 20 76 61 6c 75 65 20 67 69 76 65 6e 20 69 6e 20   value given in 
35060 74 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74  the 2nd argument
35070 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
35080 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c  ite3_result_null
35090 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74  () interface set
350a0 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  s the return val
350b0 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70  ue.** of the app
350c0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
350d0 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
350e0 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  NULL..**.** ^The
350f0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
35100 74 65 78 74 28 29 2c 20 73 71 6c 69 74 65 33 5f  text(), sqlite3_
35110 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28 29 2c  result_text16(),
35120 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75  .** sqlite3_resu
35130 6c 74 5f 74 65 78 74 31 36 6c 65 28 29 2c 20 61  lt_text16le(), a
35140 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  nd sqlite3_resul
35150 74 5f 74 65 78 74 31 36 62 65 28 29 20 69 6e 74  t_text16be() int
35160 65 72 66 61 63 65 73 0a 2a 2a 20 73 65 74 20 74  erfaces.** set t
35170 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
35180 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  of the applicati
35190 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
351a0 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 61 20 74  ion to be.** a t
351b0 65 78 74 20 73 74 72 69 6e 67 20 77 68 69 63 68  ext string which
351c0 20 69 73 20 72 65 70 72 65 73 65 6e 74 65 64 20   is represented 
351d0 61 73 20 55 54 46 2d 38 2c 20 55 54 46 2d 31 36  as UTF-8, UTF-16
351e0 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
351f0 65 72 2c 0a 2a 2a 20 55 54 46 2d 31 36 20 6c 69  er,.** UTF-16 li
35200 74 74 6c 65 20 65 6e 64 69 61 6e 2c 20 6f 72 20  ttle endian, or 
35210 55 54 46 2d 31 36 20 62 69 67 20 65 6e 64 69 61  UTF-16 big endia
35220 6e 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  n, respectively.
35230 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 74 61 6b 65  .** ^SQLite take
35240 73 20 74 68 65 20 74 65 78 74 20 72 65 73 75 6c  s the text resul
35250 74 20 66 72 6f 6d 20 74 68 65 20 61 70 70 6c 69  t from the appli
35260 63 61 74 69 6f 6e 20 66 72 6f 6d 0a 2a 2a 20 74  cation from.** t
35270 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
35280 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f   of the sqlite3_
35290 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74  result_text* int
352a0 65 72 66 61 63 65 73 2e 0a 2a 2a 20 5e 49 66 20  erfaces..** ^If 
352b0 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65  the 3rd paramete
352c0 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  r to the sqlite3
352d0 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e  _result_text* in
352e0 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e  terfaces.** is n
352f0 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 53 51  egative, then SQ
35300 4c 69 74 65 20 74 61 6b 65 73 20 72 65 73 75 6c  Lite takes resul
35310 74 20 74 65 78 74 20 66 72 6f 6d 20 74 68 65 20  t text from the 
35320 32 6e 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  2nd parameter.**
35330 20 74 68 72 6f 75 67 68 20 74 68 65 20 66 69 72   through the fir
35340 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74 65  st zero characte
35350 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 33 72  r..** ^If the 3r
35360 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
35370 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
35380 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63  t_text* interfac
35390 65 73 0a 2a 2a 20 69 73 20 6e 6f 6e 2d 6e 65 67  es.** is non-neg
353a0 61 74 69 76 65 2c 20 74 68 65 6e 20 61 73 20 6d  ative, then as m
353b0 61 6e 79 20 62 79 74 65 73 20 28 6e 6f 74 20 63  any bytes (not c
353c0 68 61 72 61 63 74 65 72 73 29 20 6f 66 20 74 68  haracters) of th
353d0 65 20 74 65 78 74 0a 2a 2a 20 70 6f 69 6e 74 65  e text.** pointe
353e0 64 20 74 6f 20 62 79 20 74 68 65 20 32 6e 64 20  d to by the 2nd 
353f0 70 61 72 61 6d 65 74 65 72 20 61 72 65 20 74 61  parameter are ta
35400 6b 65 6e 20 61 73 20 74 68 65 20 61 70 70 6c 69  ken as the appli
35410 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 0a 2a  cation-defined.*
35420 2a 20 66 75 6e 63 74 69 6f 6e 20 72 65 73 75 6c  * function resul
35430 74 2e 20 20 49 66 20 74 68 65 20 33 72 64 20 70  t.  If the 3rd p
35440 61 72 61 6d 65 74 65 72 20 69 73 20 6e 6f 6e 2d  arameter is non-
35450 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 69  negative, then i
35460 74 0a 2a 2a 20 6d 75 73 74 20 62 65 20 74 68 65  t.** must be the
35470 20 62 79 74 65 20 6f 66 66 73 65 74 20 69 6e 74   byte offset int
35480 6f 20 74 68 65 20 73 74 72 69 6e 67 20 77 68 65  o the string whe
35490 72 65 20 74 68 65 20 4e 55 4c 20 74 65 72 6d 69  re the NUL termi
354a0 6e 61 74 6f 72 20 77 6f 75 6c 64 0a 2a 2a 20 61  nator would.** a
354b0 70 70 65 61 72 20 69 66 20 74 68 65 20 73 74 72  ppear if the str
354c0 69 6e 67 20 77 68 65 72 65 20 4e 55 4c 20 74 65  ing where NUL te
354d0 72 6d 69 6e 61 74 65 64 2e 20 20 49 66 20 61 6e  rminated.  If an
354e0 79 20 4e 55 4c 20 63 68 61 72 61 63 74 65 72 73  y NUL characters
354f0 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65   occur.** in the
35500 20 73 74 72 69 6e 67 20 61 74 20 61 20 62 79 74   string at a byt
35510 65 20 6f 66 66 73 65 74 20 74 68 61 74 20 69 73  e offset that is
35520 20 6c 65 73 73 20 74 68 61 6e 20 74 68 65 20 76   less than the v
35530 61 6c 75 65 20 6f 66 20 74 68 65 20 33 72 64 0a  alue of the 3rd.
35540 2a 2a 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68  ** parameter, th
35550 65 6e 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67  en the resulting
35560 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 63 6f 6e   string will con
35570 74 61 69 6e 20 65 6d 62 65 64 64 65 64 20 4e 55  tain embedded NU
35580 4c 73 20 61 6e 64 20 74 68 65 0a 2a 2a 20 72 65  Ls and the.** re
35590 73 75 6c 74 20 6f 66 20 65 78 70 72 65 73 73 69  sult of expressi
355a0 6f 6e 73 20 6f 70 65 72 61 74 69 6e 67 20 6f 6e  ons operating on
355b0 20 73 74 72 69 6e 67 73 20 77 69 74 68 20 65 6d   strings with em
355c0 62 65 64 64 65 64 20 4e 55 4c 73 20 69 73 20 75  bedded NULs is u
355d0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e 49 66  ndefined..** ^If
355e0 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74   the 4th paramet
355f0 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  er to the sqlite
35600 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69  3_result_text* i
35610 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20  nterfaces.** or 
35620 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62  sqlite3_result_b
35630 6c 6f 62 20 69 73 20 61 20 6e 6f 6e 2d 4e 55 4c  lob is a non-NUL
35640 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20  L pointer, then 
35650 53 51 4c 69 74 65 20 63 61 6c 6c 73 20 74 68 61  SQLite calls tha
35660 74 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 61 73  t.** function as
35670 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20   the destructor 
35680 6f 6e 20 74 68 65 20 74 65 78 74 20 6f 72 20 42  on the text or B
35690 4c 4f 42 20 72 65 73 75 6c 74 20 77 68 65 6e 20  LOB result when 
356a0 69 74 20 68 61 73 0a 2a 2a 20 66 69 6e 69 73 68  it has.** finish
356b0 65 64 20 75 73 69 6e 67 20 74 68 61 74 20 72 65  ed using that re
356c0 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  sult..** ^If the
356d0 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   4th parameter t
356e0 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65  o the sqlite3_re
356f0 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72  sult_text* inter
35700 66 61 63 65 73 20 6f 72 20 74 6f 0a 2a 2a 20 73  faces or to.** s
35710 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c  qlite3_result_bl
35720 6f 62 20 69 73 20 74 68 65 20 73 70 65 63 69 61  ob is the specia
35730 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54  l constant SQLIT
35740 45 5f 53 54 41 54 49 43 2c 20 74 68 65 6e 20 53  E_STATIC, then S
35750 51 4c 69 74 65 0a 2a 2a 20 61 73 73 75 6d 65 73  QLite.** assumes
35760 20 74 68 61 74 20 74 68 65 20 74 65 78 74 20 6f   that the text o
35770 72 20 42 4c 4f 42 20 72 65 73 75 6c 74 20 69 73  r BLOB result is
35780 20 69 6e 20 63 6f 6e 73 74 61 6e 74 20 73 70 61   in constant spa
35790 63 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 0a  ce and does not.
357a0 2a 2a 20 63 6f 70 79 20 74 68 65 20 63 6f 6e 74  ** copy the cont
357b0 65 6e 74 20 6f 66 20 74 68 65 20 70 61 72 61 6d  ent of the param
357c0 65 74 65 72 20 6e 6f 72 20 63 61 6c 6c 20 61 20  eter nor call a 
357d0 64 65 73 74 72 75 63 74 6f 72 20 6f 6e 20 74 68  destructor on th
357e0 65 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20 77 68 65  e content.** whe
357f0 6e 20 69 74 20 68 61 73 20 66 69 6e 69 73 68 65  n it has finishe
35800 64 20 75 73 69 6e 67 20 74 68 61 74 20 72 65 73  d using that res
35810 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ult..** ^If the 
35820 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  4th parameter to
35830 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   the sqlite3_res
35840 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66  ult_text* interf
35850 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74  aces.** or sqlit
35860 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69  e3_result_blob i
35870 73 20 74 68 65 20 73 70 65 63 69 61 6c 20 63 6f  s the special co
35880 6e 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 54 52  nstant SQLITE_TR
35890 41 4e 53 49 45 4e 54 0a 2a 2a 20 74 68 65 6e 20  ANSIENT.** then 
358a0 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63  SQLite makes a c
358b0 6f 70 79 20 6f 66 20 74 68 65 20 72 65 73 75 6c  opy of the resul
358c0 74 20 69 6e 74 6f 20 73 70 61 63 65 20 6f 62 74  t into space obt
358d0 61 69 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 66 72  ained from.** fr
358e0 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
358f0 6f 63 28 29 5d 20 62 65 66 6f 72 65 20 69 74 20  oc()] before it 
35900 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e  returns..**.** ^
35910 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
35920 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e 74 65 72  lt_value() inter
35930 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65  face sets the re
35940 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61  sult of.** the a
35950 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
35960 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
35970 65 20 61 20 63 6f 70 79 20 74 68 65 0a 2a 2a 20  e a copy the.** 
35980 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c  [unprotected sql
35990 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
359a0 63 74 20 73 70 65 63 69 66 69 65 64 20 62 79 20  ct specified by 
359b0 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
359c0 72 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69  r.  ^The.** sqli
359d0 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65  te3_result_value
359e0 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d 61 6b  () interface mak
359f0 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  es a copy of the
35a00 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d   [sqlite3_value]
35a10 0a 2a 2a 20 73 6f 20 74 68 61 74 20 74 68 65 20  .** so that the 
35a20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20  [sqlite3_value] 
35a30 73 70 65 63 69 66 69 65 64 20 69 6e 20 74 68 65  specified in the
35a40 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 63   parameter may c
35a50 68 61 6e 67 65 20 6f 72 0a 2a 2a 20 62 65 20 64  hange or.** be d
35a60 65 61 6c 6c 6f 63 61 74 65 64 20 61 66 74 65 72  eallocated after
35a70 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
35a80 76 61 6c 75 65 28 29 20 72 65 74 75 72 6e 73 20  value() returns 
35a90 77 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a  without harm..**
35aa0 20 5e 41 20 5b 70 72 6f 74 65 63 74 65 64 20 73   ^A [protected s
35ab0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
35ac0 6a 65 63 74 20 6d 61 79 20 61 6c 77 61 79 73 20  ject may always 
35ad0 62 65 20 75 73 65 64 20 77 68 65 72 65 20 61 6e  be used where an
35ae0 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64  .** [unprotected
35af0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
35b00 6f 62 6a 65 63 74 20 69 73 20 72 65 71 75 69 72  object is requir
35b10 65 64 2c 20 73 6f 20 65 69 74 68 65 72 0a 2a 2a  ed, so either.**
35b20 20 6b 69 6e 64 20 6f 66 20 5b 73 71 6c 69 74 65   kind of [sqlite
35b30 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
35b40 63 61 6e 20 62 65 20 75 73 65 64 20 77 69 74 68  can be used with
35b50 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e   this interface.
35b60 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 73 65 20  .**.** If these 
35b70 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c  routines are cal
35b80 6c 65 64 20 66 72 6f 6d 20 77 69 74 68 69 6e 20  led from within 
35b90 74 68 65 20 64 69 66 66 65 72 65 6e 74 20 74 68  the different th
35ba0 72 65 61 64 0a 2a 2a 20 74 68 61 6e 20 74 68 65  read.** than the
35bb0 20 6f 6e 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20   one containing 
35bc0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
35bd0 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
35be0 20 74 68 61 74 20 72 65 63 65 69 76 65 64 0a 2a   that received.*
35bf0 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  * the [sqlite3_c
35c00 6f 6e 74 65 78 74 5d 20 70 6f 69 6e 74 65 72 2c  ontext] pointer,
35c10 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
35c20 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 76   undefined..*/.v
35c30 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
35c40 6c 74 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f  lt_blob(sqlite3_
35c50 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20  context*, const 
35c60 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64  void*, int, void
35c70 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69  (*)(void*));.voi
35c80 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
35c90 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f  _double(sqlite3_
35ca0 63 6f 6e 74 65 78 74 2a 2c 20 64 6f 75 62 6c 65  context*, double
35cb0 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
35cc0 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 73 71 6c  result_error(sql
35cd0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63  ite3_context*, c
35ce0 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 29  onst char*, int)
35cf0 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
35d00 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 73 71  esult_error16(sq
35d10 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
35d20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
35d30 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
35d40 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f  result_error_too
35d50 62 69 67 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  big(sqlite3_cont
35d60 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69  ext*);.void sqli
35d70 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
35d80 5f 6e 6f 6d 65 6d 28 73 71 6c 69 74 65 33 5f 63  _nomem(sqlite3_c
35d90 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73  ontext*);.void s
35da0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
35db0 72 6f 72 5f 63 6f 64 65 28 73 71 6c 69 74 65 33  ror_code(sqlite3
35dc0 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b  _context*, int);
35dd0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
35de0 73 75 6c 74 5f 69 6e 74 28 73 71 6c 69 74 65 33  sult_int(sqlite3
35df0 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b  _context*, int);
35e00 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
35e10 73 75 6c 74 5f 69 6e 74 36 34 28 73 71 6c 69 74  sult_int64(sqlit
35e20 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c  e3_context*, sql
35e30 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 76 6f 69  ite3_int64);.voi
35e40 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
35e50 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 63 6f  _null(sqlite3_co
35e60 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71  ntext*);.void sq
35e70 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
35e80 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  t(sqlite3_contex
35e90 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c  t*, const char*,
35ea0 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f   int, void(*)(vo
35eb0 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69  id*));.void sqli
35ec0 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
35ed0 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  6(sqlite3_contex
35ee0 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  t*, const void*,
35ef0 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f   int, void(*)(vo
35f00 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69  id*));.void sqli
35f10 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
35f20 36 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  6le(sqlite3_cont
35f30 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64  ext*, const void
35f40 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76  *, int,void(*)(v
35f50 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c  oid*));.void sql
35f60 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
35f70 31 36 62 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e  16be(sqlite3_con
35f80 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  text*, const voi
35f90 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28  d*, int,void(*)(
35fa0 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71  void*));.void sq
35fb0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c  lite3_result_val
35fc0 75 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ue(sqlite3_conte
35fd0 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c  xt*, sqlite3_val
35fe0 75 65 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  ue*);.void sqlit
35ff0 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c  e3_result_zerobl
36000 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ob(sqlite3_conte
36010 78 74 2a 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a  xt*, int n);../*
36020 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
36030 66 69 6e 65 20 4e 65 77 20 43 6f 6c 6c 61 74 69  fine New Collati
36040 6e 67 20 53 65 71 75 65 6e 63 65 73 0a 2a 2a 0a  ng Sequences.**.
36050 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69  ** ^These functi
36060 6f 6e 73 20 61 64 64 2c 20 72 65 6d 6f 76 65 2c  ons add, remove,
36070 20 6f 72 20 6d 6f 64 69 66 79 20 61 20 5b 63 6f   or modify a [co
36080 6c 6c 61 74 69 6f 6e 5d 20 61 73 73 6f 63 69 61  llation] associa
36090 74 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  ted.** with the 
360a0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
360b0 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20  tion] specified 
360c0 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67  as the first arg
360d0 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ument..**.** ^Th
360e0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 6f  e name of the co
360f0 6c 6c 61 74 69 6f 6e 20 69 73 20 61 20 55 54 46  llation is a UTF
36100 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 66 6f 72  -8 string.** for
36110 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
36120 63 6f 6c 6c 61 74 69 6f 6e 28 29 20 61 6e 64 20  collation() and 
36130 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
36140 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 0a 2a 2a  ollation_v2().**
36150 20 61 6e 64 20 61 20 55 54 46 2d 31 36 20 73 74   and a UTF-16 st
36160 72 69 6e 67 20 69 6e 20 6e 61 74 69 76 65 20 62  ring in native b
36170 79 74 65 20 6f 72 64 65 72 20 66 6f 72 20 73 71  yte order for sq
36180 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
36190 6c 61 74 69 6f 6e 31 36 28 29 2e 0a 2a 2a 20 5e  lation16()..** ^
361a0 43 6f 6c 6c 61 74 69 6f 6e 20 6e 61 6d 65 73 20  Collation names 
361b0 74 68 61 74 20 63 6f 6d 70 61 72 65 20 65 71 75  that compare equ
361c0 61 6c 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20  al according to 
361d0 5b 73 71 6c 69 74 65 33 5f 73 74 72 6e 69 63 6d  [sqlite3_strnicm
361e0 70 28 29 5d 20 61 72 65 0a 2a 2a 20 63 6f 6e 73  p()] are.** cons
361f0 69 64 65 72 65 64 20 74 6f 20 62 65 20 74 68 65  idered to be the
36200 20 73 61 6d 65 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a   same name..**.*
36210 2a 20 5e 28 54 68 65 20 74 68 69 72 64 20 61 72  * ^(The third ar
36220 67 75 6d 65 6e 74 20 28 65 54 65 78 74 52 65 70  gument (eTextRep
36230 29 20 6d 75 73 74 20 62 65 20 6f 6e 65 20 6f 66  ) must be one of
36240 20 74 68 65 20 63 6f 6e 73 74 61 6e 74 73 3a 0a   the constants:.
36250 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
36260 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 0a 2a  [SQLITE_UTF8],.*
36270 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55  * <li> [SQLITE_U
36280 54 46 31 36 4c 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e  TF16LE],.** <li>
36290 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45   [SQLITE_UTF16BE
362a0 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  ],.** <li> [SQLI
362b0 54 45 5f 55 54 46 31 36 5d 2c 20 6f 72 0a 2a 2a  TE_UTF16], or.**
362c0 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54   <li> [SQLITE_UT
362d0 46 31 36 5f 41 4c 49 47 4e 45 44 5d 2e 0a 2a 2a  F16_ALIGNED]..**
362e0 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 54 68 65   </ul>)^.** ^The
362f0 20 65 54 65 78 74 52 65 70 20 61 72 67 75 6d 65   eTextRep argume
36300 6e 74 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68  nt determines th
36310 65 20 65 6e 63 6f 64 69 6e 67 20 6f 66 20 73 74  e encoding of st
36320 72 69 6e 67 73 20 70 61 73 73 65 64 0a 2a 2a 20  rings passed.** 
36330 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67  to the collating
36340 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61   function callba
36350 63 6b 2c 20 78 43 61 6c 6c 62 61 63 6b 2e 0a 2a  ck, xCallback..*
36360 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 55  * ^The [SQLITE_U
36370 54 46 31 36 5d 20 61 6e 64 20 5b 53 51 4c 49 54  TF16] and [SQLIT
36380 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d  E_UTF16_ALIGNED]
36390 20 76 61 6c 75 65 73 20 66 6f 72 20 65 54 65 78   values for eTex
363a0 74 52 65 70 0a 2a 2a 20 66 6f 72 63 65 20 73 74  tRep.** force st
363b0 72 69 6e 67 73 20 74 6f 20 62 65 20 55 54 46 31  rings to be UTF1
363c0 36 20 77 69 74 68 20 6e 61 74 69 76 65 20 62 79  6 with native by
363d0 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 20 5e 54 68  te order..** ^Th
363e0 65 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5f  e [SQLITE_UTF16_
363f0 41 4c 49 47 4e 45 44 5d 20 76 61 6c 75 65 20 66  ALIGNED] value f
36400 6f 72 20 65 54 65 78 74 52 65 70 20 66 6f 72 63  or eTextRep forc
36410 65 73 20 73 74 72 69 6e 67 73 20 74 6f 20 62 65  es strings to be
36420 67 69 6e 0a 2a 2a 20 6f 6e 20 61 6e 20 65 76 65  gin.** on an eve
36430 6e 20 62 79 74 65 20 61 64 64 72 65 73 73 2e 0a  n byte address..
36440 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74  **.** ^The fourt
36450 68 20 61 72 67 75 6d 65 6e 74 2c 20 70 41 72 67  h argument, pArg
36460 2c 20 69 73 20 61 6e 20 61 70 70 6c 69 63 61 74  , is an applicat
36470 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72  ion data pointer
36480 20 74 68 61 74 20 69 73 20 70 61 73 73 65 64 0a   that is passed.
36490 2a 2a 20 74 68 72 6f 75 67 68 20 61 73 20 74 68  ** through as th
364a0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
364b0 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e   to the collatin
364c0 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62  g function callb
364d0 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ack..**.** ^The 
364e0 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 2c 20  fifth argument, 
364f0 78 43 61 6c 6c 62 61 63 6b 2c 20 69 73 20 61 20  xCallback, is a 
36500 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 63  pointer to the c
36510 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
36520 6e 2e 0a 2a 2a 20 5e 4d 75 6c 74 69 70 6c 65 20  n..** ^Multiple 
36530 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
36540 6f 6e 73 20 63 61 6e 20 62 65 20 72 65 67 69 73  ons can be regis
36550 74 65 72 65 64 20 75 73 69 6e 67 20 74 68 65 20  tered using the 
36560 73 61 6d 65 20 6e 61 6d 65 20 62 75 74 0a 2a 2a  same name but.**
36570 20 77 69 74 68 20 64 69 66 66 65 72 65 6e 74 20   with different 
36580 65 54 65 78 74 52 65 70 20 70 61 72 61 6d 65 74  eTextRep paramet
36590 65 72 73 20 61 6e 64 20 53 51 4c 69 74 65 20 77  ers and SQLite w
365a0 69 6c 6c 20 75 73 65 20 77 68 69 63 68 65 76 65  ill use whicheve
365b0 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 72 65  r.** function re
365c0 71 75 69 72 65 73 20 74 68 65 20 6c 65 61 73 74  quires the least
365d0 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74 61 20   amount of data 
365e0 74 72 61 6e 73 66 6f 72 6d 61 74 69 6f 6e 2e 0a  transformation..
365f0 2a 2a 20 5e 49 66 20 74 68 65 20 78 43 61 6c 6c  ** ^If the xCall
36600 62 61 63 6b 20 61 72 67 75 6d 65 6e 74 20 69 73  back argument is
36610 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65 20 63   NULL then the c
36620 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
36630 6e 20 69 73 0a 2a 2a 20 64 65 6c 65 74 65 64 2e  n is.** deleted.
36640 20 20 5e 57 68 65 6e 20 61 6c 6c 20 63 6f 6c 6c    ^When all coll
36650 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20  ating functions 
36660 68 61 76 69 6e 67 20 74 68 65 20 73 61 6d 65 20  having the same 
36670 6e 61 6d 65 20 61 72 65 20 64 65 6c 65 74 65 64  name are deleted
36680 2c 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 6c 61 74  ,.** that collat
36690 69 6f 6e 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72  ion is no longer
366a0 20 75 73 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e   usable..**.** ^
366b0 54 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75  The collating fu
366c0 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 20  nction callback 
366d0 69 73 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20  is invoked with 
366e0 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 70 41  a copy of the pA
366f0 72 67 20 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69  rg .** applicati
36700 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 20  on data pointer 
36710 61 6e 64 20 77 69 74 68 20 74 77 6f 20 73 74 72  and with two str
36720 69 6e 67 73 20 69 6e 20 74 68 65 20 65 6e 63 6f  ings in the enco
36730 64 69 6e 67 20 73 70 65 63 69 66 69 65 64 0a 2a  ding specified.*
36740 2a 20 62 79 20 74 68 65 20 65 54 65 78 74 52 65  * by the eTextRe
36750 70 20 61 72 67 75 6d 65 6e 74 2e 20 20 54 68 65  p argument.  The
36760 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
36770 69 6f 6e 20 6d 75 73 74 20 72 65 74 75 72 6e 20  ion must return 
36780 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20 74 68  an.** integer th
36790 61 74 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20  at is negative, 
367a0 7a 65 72 6f 2c 20 6f 72 20 70 6f 73 69 74 69 76  zero, or positiv
367b0 65 0a 2a 2a 20 69 66 20 74 68 65 20 66 69 72 73  e.** if the firs
367c0 74 20 73 74 72 69 6e 67 20 69 73 20 6c 65 73 73  t string is less
367d0 20 74 68 61 6e 2c 20 65 71 75 61 6c 20 74 6f 2c   than, equal to,
367e0 20 6f 72 20 67 72 65 61 74 65 72 20 74 68 61 6e   or greater than
367f0 20 74 68 65 20 73 65 63 6f 6e 64 2c 0a 2a 2a 20   the second,.** 
36800 72 65 73 70 65 63 74 69 76 65 6c 79 2e 20 20 41  respectively.  A
36810 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
36820 69 6f 6e 20 6d 75 73 74 20 61 6c 77 61 79 73 20  ion must always 
36830 72 65 74 75 72 6e 20 74 68 65 20 73 61 6d 65 20  return the same 
36840 61 6e 73 77 65 72 0a 2a 2a 20 67 69 76 65 6e 20  answer.** given 
36850 74 68 65 20 73 61 6d 65 20 69 6e 70 75 74 73 2e  the same inputs.
36860 20 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65    If two or more
36870 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
36880 69 6f 6e 73 20 61 72 65 20 72 65 67 69 73 74 65  ions are registe
36890 72 65 64 0a 2a 2a 20 74 6f 20 74 68 65 20 73 61  red.** to the sa
368a0 6d 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 6e 61 6d  me collation nam
368b0 65 20 28 75 73 69 6e 67 20 64 69 66 66 65 72 65  e (using differe
368c0 6e 74 20 65 54 65 78 74 52 65 70 20 76 61 6c 75  nt eTextRep valu
368d0 65 73 29 20 74 68 65 6e 20 61 6c 6c 0a 2a 2a 20  es) then all.** 
368e0 6d 75 73 74 20 67 69 76 65 20 61 6e 20 65 71 75  must give an equ
368f0 69 76 61 6c 65 6e 74 20 61 6e 73 77 65 72 20 77  ivalent answer w
36900 68 65 6e 20 69 6e 76 6f 6b 65 64 20 77 69 74 68  hen invoked with
36910 20 65 71 75 69 76 61 6c 65 6e 74 20 73 74 72 69   equivalent stri
36920 6e 67 73 2e 0a 2a 2a 20 54 68 65 20 63 6f 6c 6c  ngs..** The coll
36930 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d  ating function m
36940 75 73 74 20 6f 62 65 79 20 74 68 65 20 66 6f 6c  ust obey the fol
36950 6c 6f 77 69 6e 67 20 70 72 6f 70 65 72 74 69 65  lowing propertie
36960 73 20 66 6f 72 20 61 6c 6c 0a 2a 2a 20 73 74 72  s for all.** str
36970 69 6e 67 73 20 41 2c 20 42 2c 20 61 6e 64 20 43  ings A, B, and C
36980 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20  :.**.** <ol>.** 
36990 3c 6c 69 3e 20 49 66 20 41 3d 3d 42 20 74 68 65  <li> If A==B the
369a0 6e 20 42 3d 3d 41 2e 0a 2a 2a 20 3c 6c 69 3e 20  n B==A..** <li> 
369b0 49 66 20 41 3d 3d 42 20 61 6e 64 20 42 3d 3d 43  If A==B and B==C
369c0 20 74 68 65 6e 20 41 3d 3d 43 2e 0a 2a 2a 20 3c   then A==C..** <
369d0 6c 69 3e 20 49 66 20 41 26 6c 74 3b 42 20 54 48  li> If A&lt;B TH
369e0 45 4e 20 42 26 67 74 3b 41 2e 0a 2a 2a 20 3c 6c  EN B&gt;A..** <l
369f0 69 3e 20 49 66 20 41 26 6c 74 3b 42 20 61 6e 64  i> If A&lt;B and
36a00 20 42 26 6c 74 3b 43 20 74 68 65 6e 20 41 26 6c   B&lt;C then A&l
36a10 74 3b 43 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a  t;C..** </ol>.**
36a20 0a 2a 2a 20 49 66 20 61 20 63 6f 6c 6c 61 74 69  .** If a collati
36a30 6e 67 20 66 75 6e 63 74 69 6f 6e 20 66 61 69 6c  ng function fail
36a40 73 20 61 6e 79 20 6f 66 20 74 68 65 20 61 62 6f  s any of the abo
36a50 76 65 20 63 6f 6e 73 74 72 61 69 6e 74 73 20 61  ve constraints a
36a60 6e 64 20 74 68 61 74 0a 2a 2a 20 63 6f 6c 6c 61  nd that.** colla
36a70 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73  ting function is
36a80 20 20 72 65 67 69 73 74 65 72 65 64 20 61 6e 64    registered and
36a90 20 75 73 65 64 2c 20 74 68 65 6e 20 74 68 65 20   used, then the 
36aa0 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69  behavior of SQLi
36ab0 74 65 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e  te.** is undefin
36ac0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ed..**.** ^The s
36ad0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
36ae0 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 77 6f 72  llation_v2() wor
36af0 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f  ks like sqlite3_
36b00 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
36b10 28 29 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 61  ().** with the a
36b20 64 64 69 74 69 6f 6e 20 74 68 61 74 20 74 68 65  ddition that the
36b30 20 78 44 65 73 74 72 6f 79 20 63 61 6c 6c 62 61   xDestroy callba
36b40 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e  ck is invoked on
36b50 20 70 41 72 67 20 77 68 65 6e 0a 2a 2a 20 74 68   pArg when.** th
36b60 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63  e collating func
36b70 74 69 6f 6e 20 69 73 20 64 65 6c 65 74 65 64 2e  tion is deleted.
36b80 0a 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6e 67 20 66  .** ^Collating f
36b90 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 64 65 6c  unctions are del
36ba0 65 74 65 64 20 77 68 65 6e 20 74 68 65 79 20 61  eted when they a
36bb0 72 65 20 6f 76 65 72 72 69 64 64 65 6e 20 62 79  re overridden by
36bc0 20 6c 61 74 65 72 0a 2a 2a 20 63 61 6c 6c 73 20   later.** calls 
36bd0 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e  to the collation
36be0 20 63 72 65 61 74 69 6f 6e 20 66 75 6e 63 74 69   creation functi
36bf0 6f 6e 73 20 6f 72 20 77 68 65 6e 20 74 68 65 0a  ons or when the.
36c00 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
36c10 6e 65 63 74 69 6f 6e 5d 20 69 73 20 63 6c 6f 73  nection] is clos
36c20 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
36c30 33 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 0a 2a  3_close()]..**.*
36c40 2a 20 5e 54 68 65 20 78 44 65 73 74 72 6f 79 20  * ^The xDestroy 
36c50 63 61 6c 6c 62 61 63 6b 20 69 73 20 3c 75 3e 6e  callback is <u>n
36c60 6f 74 3c 2f 75 3e 20 63 61 6c 6c 65 64 20 69 66  ot</u> called if
36c70 20 74 68 65 20 0a 2a 2a 20 73 71 6c 69 74 65 33   the .** sqlite3
36c80 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
36c90 6e 5f 76 32 28 29 20 66 75 6e 63 74 69 6f 6e 20  n_v2() function 
36ca0 66 61 69 6c 73 2e 20 20 41 70 70 6c 69 63 61 74  fails.  Applicat
36cb0 69 6f 6e 73 20 74 68 61 74 20 69 6e 76 6f 6b 65  ions that invoke
36cc0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61  .** sqlite3_crea
36cd0 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28  te_collation_v2(
36ce0 29 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c  ) with a non-NUL
36cf0 4c 20 78 44 65 73 74 72 6f 79 20 61 72 67 75 6d  L xDestroy argum
36d00 65 6e 74 20 73 68 6f 75 6c 64 20 0a 2a 2a 20 63  ent should .** c
36d10 68 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20  heck the return 
36d20 63 6f 64 65 20 61 6e 64 20 64 69 73 70 6f 73 65  code and dispose
36d30 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74   of the applicat
36d40 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72  ion data pointer
36d50 0a 2a 2a 20 74 68 65 6d 73 65 6c 76 65 73 20 72  .** themselves r
36d60 61 74 68 65 72 20 74 68 61 6e 20 65 78 70 65 63  ather than expec
36d70 74 69 6e 67 20 53 51 4c 69 74 65 20 74 6f 20 64  ting SQLite to d
36d80 65 61 6c 20 77 69 74 68 20 69 74 20 66 6f 72 20  eal with it for 
36d90 74 68 65 6d 2e 0a 2a 2a 20 54 68 69 73 20 69 73  them..** This is
36da0 20 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20   different from 
36db0 65 76 65 72 79 20 6f 74 68 65 72 20 53 51 4c 69  every other SQLi
36dc0 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20 54  te interface.  T
36dd0 68 65 20 69 6e 63 6f 6e 73 69 73 74 65 6e 63 79  he inconsistency
36de0 20 0a 2a 2a 20 69 73 20 75 6e 66 6f 72 74 75 6e   .** is unfortun
36df0 61 74 65 20 62 75 74 20 63 61 6e 6e 6f 74 20 62  ate but cannot b
36e00 65 20 63 68 61 6e 67 65 64 20 77 69 74 68 6f 75  e changed withou
36e10 74 20 62 72 65 61 6b 69 6e 67 20 62 61 63 6b 77  t breaking backw
36e20 61 72 64 73 20 0a 2a 2a 20 63 6f 6d 70 61 74 69  ards .** compati
36e30 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 53 65  bility..**.** Se
36e40 65 20 61 6c 73 6f 3a 20 20 5b 73 71 6c 69 74 65  e also:  [sqlite
36e50 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
36e60 65 64 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  ed()] and [sqlit
36e70 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
36e80 64 65 64 31 36 28 29 5d 2e 0a 2a 2f 0a 69 6e 74  ded16()]..*/.int
36e90 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
36ea0 63 6f 6c 6c 61 74 69 6f 6e 28 0a 20 20 73 71 6c  collation(.  sql
36eb0 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20  ite3*, .  const 
36ec0 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20  char *zName, .  
36ed0 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20  int eTextRep, . 
36ee0 20 76 6f 69 64 20 2a 70 41 72 67 2c 0a 20 20 69   void *pArg,.  i
36ef0 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f  nt(*xCompare)(vo
36f00 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f  id*,int,const vo
36f10 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f  id*,int,const vo
36f20 69 64 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  id*).);.int sqli
36f30 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
36f40 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74  tion_v2(.  sqlit
36f50 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68  e3*, .  const ch
36f60 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e  ar *zName, .  in
36f70 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76  t eTextRep, .  v
36f80 6f 69 64 20 2a 70 41 72 67 2c 0a 20 20 69 6e 74  oid *pArg,.  int
36f90 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64  (*xCompare)(void
36fa0 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64  *,int,const void
36fb0 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64  *,int,const void
36fc0 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65 73  *),.  void(*xDes
36fd0 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a  troy)(void*).);.
36fe0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61  int sqlite3_crea
36ff0 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 0a  te_collation16(.
37000 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63    sqlite3*, .  c
37010 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 4e 61 6d 65  onst void *zName
37020 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70  ,.  int eTextRep
37030 2c 20 0a 20 20 76 6f 69 64 20 2a 70 41 72 67 2c  , .  void *pArg,
37040 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65  .  int(*xCompare
37050 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  )(void*,int,cons
37060 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  t void*,int,cons
37070 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a  t void*).);../*.
37080 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c  ** CAPI3REF: Col
37090 6c 61 74 69 6f 6e 20 4e 65 65 64 65 64 20 43 61  lation Needed Ca
370a0 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54  llbacks.**.** ^T
370b0 6f 20 61 76 6f 69 64 20 68 61 76 69 6e 67 20 74  o avoid having t
370c0 6f 20 72 65 67 69 73 74 65 72 20 61 6c 6c 20 63  o register all c
370d0 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63  ollation sequenc
370e0 65 73 20 62 65 66 6f 72 65 20 61 20 64 61 74 61  es before a data
370f0 62 61 73 65 0a 2a 2a 20 63 61 6e 20 62 65 20 75  base.** can be u
37100 73 65 64 2c 20 61 20 73 69 6e 67 6c 65 20 63 61  sed, a single ca
37110 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
37120 6d 61 79 20 62 65 20 72 65 67 69 73 74 65 72 65  may be registere
37130 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 64  d with the.** [d
37140 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
37150 6f 6e 5d 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65  on] to be invoke
37160 64 20 77 68 65 6e 65 76 65 72 20 61 6e 20 75 6e  d whenever an un
37170 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f  defined collatio
37180 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 69 73  n.** sequence is
37190 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a   required..**.**
371a0 20 5e 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f   ^If the functio
371b0 6e 20 69 73 20 72 65 67 69 73 74 65 72 65 64 20  n is registered 
371c0 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65  using the sqlite
371d0 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
371e0 65 64 28 29 20 41 50 49 2c 0a 2a 2a 20 74 68 65  ed() API,.** the
371f0 6e 20 69 74 20 69 73 20 70 61 73 73 65 64 20 74  n it is passed t
37200 68 65 20 6e 61 6d 65 73 20 6f 66 20 75 6e 64 65  he names of unde
37210 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20  fined collation 
37220 73 65 71 75 65 6e 63 65 73 20 61 73 20 73 74 72  sequences as str
37230 69 6e 67 73 0a 2a 2a 20 65 6e 63 6f 64 65 64 20  ings.** encoded 
37240 69 6e 20 55 54 46 2d 38 2e 20 5e 49 66 20 73 71  in UTF-8. ^If sq
37250 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  lite3_collation_
37260 6e 65 65 64 65 64 31 36 28 29 20 69 73 20 75 73  needed16() is us
37270 65 64 2c 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 73  ed,.** the names
37280 20 61 72 65 20 70 61 73 73 65 64 20 61 73 20 55   are passed as U
37290 54 46 2d 31 36 20 69 6e 20 6d 61 63 68 69 6e 65  TF-16 in machine
372a0 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
372b0 65 72 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74  er..** ^A call t
372c0 6f 20 65 69 74 68 65 72 20 66 75 6e 63 74 69 6f  o either functio
372d0 6e 20 72 65 70 6c 61 63 65 73 20 74 68 65 20 65  n replaces the e
372e0 78 69 73 74 69 6e 67 20 63 6f 6c 6c 61 74 69 6f  xisting collatio
372f0 6e 2d 6e 65 65 64 65 64 20 63 61 6c 6c 62 61 63  n-needed callbac
37300 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 28 57 68 65 6e 20  k..**.** ^(When 
37310 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  the callback is 
37320 69 6e 76 6f 6b 65 64 2c 20 74 68 65 20 66 69 72  invoked, the fir
37330 73 74 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73  st argument pass
37340 65 64 20 69 73 20 61 20 63 6f 70 79 0a 2a 2a 20  ed is a copy.** 
37350 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  of the second ar
37360 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
37370 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
37380 65 64 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74  ed() or.** sqlit
37390 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
373a0 64 65 64 31 36 28 29 2e 20 20 54 68 65 20 73 65  ded16().  The se
373b0 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73  cond argument is
373c0 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   the database.**
373d0 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 54 68   connection.  Th
373e0 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
373f0 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49   is one of [SQLI
37400 54 45 5f 55 54 46 38 5d 2c 20 5b 53 51 4c 49 54  TE_UTF8], [SQLIT
37410 45 5f 55 54 46 31 36 42 45 5d 2c 0a 2a 2a 20 6f  E_UTF16BE],.** o
37420 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c  r [SQLITE_UTF16L
37430 45 5d 2c 20 69 6e 64 69 63 61 74 69 6e 67 20 74  E], indicating t
37440 68 65 20 6d 6f 73 74 20 64 65 73 69 72 61 62 6c  he most desirabl
37450 65 20 66 6f 72 6d 20 6f 66 20 74 68 65 20 63 6f  e form of the co
37460 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65  llation.** seque
37470 6e 63 65 20 66 75 6e 63 74 69 6f 6e 20 72 65 71  nce function req
37480 75 69 72 65 64 2e 20 20 54 68 65 20 66 6f 75 72  uired.  The four
37490 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  th parameter is 
374a0 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a  the name of the.
374b0 2a 2a 20 72 65 71 75 69 72 65 64 20 63 6f 6c 6c  ** required coll
374c0 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 2e 29  ation sequence.)
374d0 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c  ^.**.** The call
374e0 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 73 68  back function sh
374f0 6f 75 6c 64 20 72 65 67 69 73 74 65 72 20 74 68  ould register th
37500 65 20 64 65 73 69 72 65 64 20 63 6f 6c 6c 61 74  e desired collat
37510 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71  ion using.** [sq
37520 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
37530 6c 61 74 69 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69  lation()], [sqli
37540 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
37550 74 69 6f 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a  tion16()], or.**
37560 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
37570 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 5d  _collation_v2()]
37580 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
37590 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
375a0 64 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a  d(.  sqlite3*, .
375b0 20 20 76 6f 69 64 2a 2c 20 0a 20 20 76 6f 69 64    void*, .  void
375c0 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65  (*)(void*,sqlite
375d0 33 2a 2c 69 6e 74 20 65 54 65 78 74 52 65 70 2c  3*,int eTextRep,
375e0 63 6f 6e 73 74 20 63 68 61 72 2a 29 0a 29 3b 0a  const char*).);.
375f0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c  int sqlite3_coll
37600 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 0a  ation_needed16(.
37610 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76    sqlite3*, .  v
37620 6f 69 64 2a 2c 0a 20 20 76 6f 69 64 28 2a 29 28  oid*,.  void(*)(
37630 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69  void*,sqlite3*,i
37640 6e 74 20 65 54 65 78 74 52 65 70 2c 63 6f 6e 73  nt eTextRep,cons
37650 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 23 69 66  t void*).);..#if
37660 64 65 66 20 53 51 4c 49 54 45 5f 48 41 53 5f 43  def SQLITE_HAS_C
37670 4f 44 45 43 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69  ODEC./*.** Speci
37680 66 79 20 74 68 65 20 6b 65 79 20 66 6f 72 20 61  fy the key for a
37690 6e 20 65 6e 63 72 79 70 74 65 64 20 64 61 74 61  n encrypted data
376a0 62 61 73 65 2e 20 20 54 68 69 73 20 72 6f 75 74  base.  This rout
376b0 69 6e 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a  ine should be.**
376c0 20 63 61 6c 6c 65 64 20 72 69 67 68 74 20 61 66   called right af
376d0 74 65 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ter sqlite3_open
376e0 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f  ()..**.** The co
376f0 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20  de to implement 
37700 74 68 69 73 20 41 50 49 20 69 73 20 6e 6f 74 20  this API is not 
37710 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 65  available in the
37720 20 70 75 62 6c 69 63 20 72 65 6c 65 61 73 65 0a   public release.
37730 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f  ** of SQLite..*/
37740 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6b 65 79  .int sqlite3_key
37750 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
37760 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
37770 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74     /* Database t
37780 6f 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a  o be rekeyed */.
37790 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b    const void *pK
377a0 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20  ey, int nKey    
377b0 20 2f 2a 20 54 68 65 20 6b 65 79 20 2a 2f 0a 29   /* The key */.)
377c0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6b 65  ;.int sqlite3_ke
377d0 79 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20  y_v2(.  sqlite3 
377e0 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
377f0 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
37800 73 65 20 74 6f 20 62 65 20 72 65 6b 65 79 65 64  se to be rekeyed
37810 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
37820 20 2a 7a 44 62 4e 61 6d 65 2c 20 20 20 20 20 20   *zDbName,      
37830 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20       /* Name of 
37840 74 68 65 20 64 61 74 61 62 61 73 65 20 2a 2f 0a  the database */.
37850 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b    const void *pK
37860 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20  ey, int nKey    
37870 20 2f 2a 20 54 68 65 20 6b 65 79 20 2a 2f 0a 29   /* The key */.)
37880 3b 0a 0a 2f 2a 0a 2a 2a 20 43 68 61 6e 67 65 20  ;../*.** Change 
37890 74 68 65 20 6b 65 79 20 6f 6e 20 61 6e 20 6f 70  the key on an op
378a0 65 6e 20 64 61 74 61 62 61 73 65 2e 20 20 49 66  en database.  If
378b0 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 61 74   the current dat
378c0 61 62 61 73 65 20 69 73 20 6e 6f 74 0a 2a 2a 20  abase is not.** 
378d0 65 6e 63 72 79 70 74 65 64 2c 20 74 68 69 73 20  encrypted, this 
378e0 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20 65 6e 63  routine will enc
378f0 72 79 70 74 20 69 74 2e 20 20 49 66 20 70 4e 65  rypt it.  If pNe
37900 77 3d 3d 30 20 6f 72 20 6e 4e 65 77 3d 3d 30 2c  w==0 or nNew==0,
37910 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
37920 20 69 73 20 64 65 63 72 79 70 74 65 64 2e 0a 2a   is decrypted..*
37930 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 74 6f  *.** The code to
37940 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73 20   implement this 
37950 41 50 49 20 69 73 20 6e 6f 74 20 61 76 61 69 6c  API is not avail
37960 61 62 6c 65 20 69 6e 20 74 68 65 20 70 75 62 6c  able in the publ
37970 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66  ic release.** of
37980 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20   SQLite..*/.int 
37990 73 71 6c 69 74 65 33 5f 72 65 6b 65 79 28 0a 20  sqlite3_rekey(. 
379a0 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
379b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
379c0 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20 62  /* Database to b
379d0 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63  e rekeyed */.  c
379e0 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c  onst void *pKey,
379f0 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a   int nKey     /*
37a00 20 54 68 65 20 6e 65 77 20 6b 65 79 20 2a 2f 0a   The new key */.
37a10 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72  );.int sqlite3_r
37a20 65 6b 65 79 5f 76 32 28 0a 20 20 73 71 6c 69 74  ekey_v2(.  sqlit
37a30 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
37a40 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
37a50 61 62 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65  abase to be reke
37a60 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  yed */.  const c
37a70 68 61 72 20 2a 7a 44 62 4e 61 6d 65 2c 20 20 20  har *zDbName,   
37a80 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20          /* Name 
37a90 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  of the database 
37aa0 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
37ab0 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20  *pKey, int nKey 
37ac0 20 20 20 20 2f 2a 20 54 68 65 20 6e 65 77 20 6b      /* The new k
37ad0 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ey */.);../*.** 
37ae0 53 70 65 63 69 66 79 20 74 68 65 20 61 63 74 69  Specify the acti
37af0 76 61 74 69 6f 6e 20 6b 65 79 20 66 6f 72 20 61  vation key for a
37b00 20 53 45 45 20 64 61 74 61 62 61 73 65 2e 20 20   SEE database.  
37b10 55 6e 6c 65 73 73 20 0a 2a 2a 20 61 63 74 69 76  Unless .** activ
37b20 61 74 65 64 2c 20 6e 6f 6e 65 20 6f 66 20 74 68  ated, none of th
37b30 65 20 53 45 45 20 72 6f 75 74 69 6e 65 73 20 77  e SEE routines w
37b40 69 6c 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a 76 6f 69  ill work..*/.voi
37b50 64 20 73 71 6c 69 74 65 33 5f 61 63 74 69 76 61  d sqlite3_activa
37b60 74 65 5f 73 65 65 28 0a 20 20 63 6f 6e 73 74 20  te_see(.  const 
37b70 63 68 61 72 20 2a 7a 50 61 73 73 50 68 72 61 73  char *zPassPhras
37b80 65 20 20 20 20 20 20 20 20 2f 2a 20 41 63 74 69  e        /* Acti
37b90 76 61 74 69 6f 6e 20 70 68 72 61 73 65 20 2a 2f  vation phrase */
37ba0 0a 29 3b 0a 23 65 6e 64 69 66 0a 0a 23 69 66 64  .);.#endif..#ifd
37bb0 65 66 20 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  ef SQLITE_ENABLE
37bc0 5f 43 45 52 4f 44 0a 2f 2a 0a 2a 2a 20 53 70 65  _CEROD./*.** Spe
37bd0 63 69 66 79 20 74 68 65 20 61 63 74 69 76 61 74  cify the activat
37be0 69 6f 6e 20 6b 65 79 20 66 6f 72 20 61 20 43 45  ion key for a CE
37bf0 52 4f 44 20 64 61 74 61 62 61 73 65 2e 20 20 55  ROD database.  U
37c00 6e 6c 65 73 73 20 0a 2a 2a 20 61 63 74 69 76 61  nless .** activa
37c10 74 65 64 2c 20 6e 6f 6e 65 20 6f 66 20 74 68 65  ted, none of the
37c20 20 43 45 52 4f 44 20 72 6f 75 74 69 6e 65 73 20   CEROD routines 
37c30 77 69 6c 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a 76 6f  will work..*/.vo
37c40 69 64 20 73 71 6c 69 74 65 33 5f 61 63 74 69 76  id sqlite3_activ
37c50 61 74 65 5f 63 65 72 6f 64 28 0a 20 20 63 6f 6e  ate_cerod(.  con
37c60 73 74 20 63 68 61 72 20 2a 7a 50 61 73 73 50 68  st char *zPassPh
37c70 72 61 73 65 20 20 20 20 20 20 20 20 2f 2a 20 41  rase        /* A
37c80 63 74 69 76 61 74 69 6f 6e 20 70 68 72 61 73 65  ctivation phrase
37c90 20 2a 2f 0a 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f   */.);.#endif../
37ca0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
37cb0 75 73 70 65 6e 64 20 45 78 65 63 75 74 69 6f 6e  uspend Execution
37cc0 20 46 6f 72 20 41 20 53 68 6f 72 74 20 54 69 6d   For A Short Tim
37cd0 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  e.**.** The sqli
37ce0 74 65 33 5f 73 6c 65 65 70 28 29 20 66 75 6e 63  te3_sleep() func
37cf0 74 69 6f 6e 20 63 61 75 73 65 73 20 74 68 65 20  tion causes the 
37d00 63 75 72 72 65 6e 74 20 74 68 72 65 61 64 20 74  current thread t
37d10 6f 20 73 75 73 70 65 6e 64 20 65 78 65 63 75 74  o suspend execut
37d20 69 6f 6e 0a 2a 2a 20 66 6f 72 20 61 74 20 6c 65  ion.** for at le
37d30 61 73 74 20 61 20 6e 75 6d 62 65 72 20 6f 66 20  ast a number of 
37d40 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 73 70 65  milliseconds spe
37d50 63 69 66 69 65 64 20 69 6e 20 69 74 73 20 70 61  cified in its pa
37d60 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49  rameter..**.** I
37d70 66 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20  f the operating 
37d80 73 79 73 74 65 6d 20 64 6f 65 73 20 6e 6f 74 20  system does not 
37d90 73 75 70 70 6f 72 74 20 73 6c 65 65 70 20 72 65  support sleep re
37da0 71 75 65 73 74 73 20 77 69 74 68 0a 2a 2a 20 6d  quests with.** m
37db0 69 6c 6c 69 73 65 63 6f 6e 64 20 74 69 6d 65 20  illisecond time 
37dc0 72 65 73 6f 6c 75 74 69 6f 6e 2c 20 74 68 65 6e  resolution, then
37dd0 20 74 68 65 20 74 69 6d 65 20 77 69 6c 6c 20 62   the time will b
37de0 65 20 72 6f 75 6e 64 65 64 20 75 70 20 74 6f 0a  e rounded up to.
37df0 2a 2a 20 74 68 65 20 6e 65 61 72 65 73 74 20 73  ** the nearest s
37e00 65 63 6f 6e 64 2e 20 54 68 65 20 6e 75 6d 62 65  econd. The numbe
37e10 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  r of millisecond
37e20 73 20 6f 66 20 73 6c 65 65 70 20 61 63 74 75 61  s of sleep actua
37e30 6c 6c 79 0a 2a 2a 20 72 65 71 75 65 73 74 65 64  lly.** requested
37e40 20 66 72 6f 6d 20 74 68 65 20 6f 70 65 72 61 74   from the operat
37e50 69 6e 67 20 73 79 73 74 65 6d 20 69 73 20 72 65  ing system is re
37e60 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53  turned..**.** ^S
37e70 51 4c 69 74 65 20 69 6d 70 6c 65 6d 65 6e 74 73  QLite implements
37e80 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   this interface 
37e90 62 79 20 63 61 6c 6c 69 6e 67 20 74 68 65 20 78  by calling the x
37ea0 53 6c 65 65 70 28 29 0a 2a 2a 20 6d 65 74 68 6f  Sleep().** metho
37eb0 64 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74  d of the default
37ec0 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f   [sqlite3_vfs] o
37ed0 62 6a 65 63 74 2e 20 20 49 66 20 74 68 65 20 78  bject.  If the x
37ee0 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 0a 2a  Sleep() method.*
37ef0 2a 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74  * of the default
37f00 20 56 46 53 20 69 73 20 6e 6f 74 20 69 6d 70 6c   VFS is not impl
37f10 65 6d 65 6e 74 65 64 20 63 6f 72 72 65 63 74 6c  emented correctl
37f20 79 2c 20 6f 72 20 6e 6f 74 20 69 6d 70 6c 65 6d  y, or not implem
37f30 65 6e 74 65 64 20 61 74 0a 2a 2a 20 61 6c 6c 2c  ented at.** all,
37f40 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
37f50 6f 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6c  or of sqlite3_sl
37f60 65 65 70 28 29 20 6d 61 79 20 64 65 76 69 61 74  eep() may deviat
37f70 65 20 66 72 6f 6d 20 74 68 65 20 64 65 73 63 72  e from the descr
37f80 69 70 74 69 6f 6e 0a 2a 2a 20 69 6e 20 74 68 65  iption.** in the
37f90 20 70 72 65 76 69 6f 75 73 20 70 61 72 61 67 72   previous paragr
37fa0 61 70 68 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  aphs..*/.int sql
37fb0 69 74 65 33 5f 73 6c 65 65 70 28 69 6e 74 29 3b  ite3_sleep(int);
37fc0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
37fd0 3a 20 4e 61 6d 65 20 4f 66 20 54 68 65 20 46 6f  : Name Of The Fo
37fe0 6c 64 65 72 20 48 6f 6c 64 69 6e 67 20 54 65 6d  lder Holding Tem
37ff0 70 6f 72 61 72 79 20 46 69 6c 65 73 0a 2a 2a 0a  porary Files.**.
38000 2a 2a 20 5e 28 49 66 20 74 68 69 73 20 67 6c 6f  ** ^(If this glo
38010 62 61 6c 20 76 61 72 69 61 62 6c 65 20 69 73 20  bal variable is 
38020 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f  made to point to
38030 20 61 20 73 74 72 69 6e 67 20 77 68 69 63 68 20   a string which 
38040 69 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f  is.** the name o
38050 66 20 61 20 66 6f 6c 64 65 72 20 28 61 2e 6b 2e  f a folder (a.k.
38060 61 2e 20 64 69 72 65 63 74 6f 72 79 29 2c 20 74  a. directory), t
38070 68 65 6e 20 61 6c 6c 20 74 65 6d 70 6f 72 61 72  hen all temporar
38080 79 20 66 69 6c 65 73 0a 2a 2a 20 63 72 65 61 74  y files.** creat
38090 65 64 20 62 79 20 53 51 4c 69 74 65 20 77 68 65  ed by SQLite whe
380a0 6e 20 75 73 69 6e 67 20 61 20 62 75 69 6c 74 2d  n using a built-
380b0 69 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20  in [sqlite3_vfs 
380c0 7c 20 56 46 53 5d 0a 2a 2a 20 77 69 6c 6c 20 62  | VFS].** will b
380d0 65 20 70 6c 61 63 65 64 20 69 6e 20 74 68 61 74  e placed in that
380e0 20 64 69 72 65 63 74 6f 72 79 2e 29 5e 20 20 5e   directory.)^  ^
380f0 49 66 20 74 68 69 73 20 76 61 72 69 61 62 6c 65  If this variable
38100 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  .** is a NULL po
38110 69 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 4c 69  inter, then SQLi
38120 74 65 20 70 65 72 66 6f 72 6d 73 20 61 20 73 65  te performs a se
38130 61 72 63 68 20 66 6f 72 20 61 6e 20 61 70 70 72  arch for an appr
38140 6f 70 72 69 61 74 65 0a 2a 2a 20 74 65 6d 70 6f  opriate.** tempo
38150 72 61 72 79 20 66 69 6c 65 20 64 69 72 65 63 74  rary file direct
38160 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73  ory..**.** It is
38170 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 72 65 61   not safe to rea
38180 64 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73  d or modify this
38190 20 76 61 72 69 61 62 6c 65 20 69 6e 20 6d 6f 72   variable in mor
381a0 65 20 74 68 61 6e 20 6f 6e 65 0a 2a 2a 20 74 68  e than one.** th
381b0 72 65 61 64 20 61 74 20 61 20 74 69 6d 65 2e 20  read at a time. 
381c0 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20   It is not safe 
381d0 74 6f 20 72 65 61 64 20 6f 72 20 6d 6f 64 69 66  to read or modif
381e0 79 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 0a  y this variable.
381f0 2a 2a 20 69 66 20 61 20 5b 64 61 74 61 62 61 73  ** if a [databas
38200 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73  e connection] is
38210 20 62 65 69 6e 67 20 75 73 65 64 20 61 74 20 74   being used at t
38220 68 65 20 73 61 6d 65 20 74 69 6d 65 20 69 6e 20  he same time in 
38230 61 20 73 65 70 61 72 61 74 65 0a 2a 2a 20 74 68  a separate.** th
38240 72 65 61 64 2e 0a 2a 2a 20 49 74 20 69 73 20 69  read..** It is i
38250 6e 74 65 6e 64 65 64 20 74 68 61 74 20 74 68 69  ntended that thi
38260 73 20 76 61 72 69 61 62 6c 65 20 62 65 20 73 65  s variable be se
38270 74 20 6f 6e 63 65 0a 2a 2a 20 61 73 20 70 61 72  t once.** as par
38280 74 20 6f 66 20 70 72 6f 63 65 73 73 20 69 6e 69  t of process ini
38290 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 20  tialization and 
382a0 62 65 66 6f 72 65 20 61 6e 79 20 53 51 4c 69 74  before any SQLit
382b0 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72  e interface.** r
382c0 6f 75 74 69 6e 65 73 20 68 61 76 65 20 62 65 65  outines have bee
382d0 6e 20 63 61 6c 6c 65 64 20 61 6e 64 20 74 68 61  n called and tha
382e0 74 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20  t this variable 
382f0 72 65 6d 61 69 6e 20 75 6e 63 68 61 6e 67 65 64  remain unchanged
38300 0a 2a 2a 20 74 68 65 72 65 61 66 74 65 72 2e 0a  .** thereafter..
38310 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 74 65 6d 70  **.** ^The [temp
38320 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79  _store_directory
38330 20 70 72 61 67 6d 61 5d 20 6d 61 79 20 6d 6f 64   pragma] may mod
38340 69 66 79 20 74 68 69 73 20 76 61 72 69 61 62 6c  ify this variabl
38350 65 20 61 6e 64 20 63 61 75 73 65 0a 2a 2a 20 69  e and cause.** i
38360 74 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 6d 65  t to point to me
38370 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72  mory obtained fr
38380 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
38390 6f 63 5d 2e 20 20 5e 46 75 72 74 68 65 72 6d 6f  oc].  ^Furthermo
383a0 72 65 2c 0a 2a 2a 20 74 68 65 20 5b 74 65 6d 70  re,.** the [temp
383b0 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79  _store_directory
383c0 20 70 72 61 67 6d 61 5d 20 61 6c 77 61 79 73 20   pragma] always 
383d0 61 73 73 75 6d 65 73 20 74 68 61 74 20 61 6e 79  assumes that any
383e0 20 73 74 72 69 6e 67 0a 2a 2a 20 74 68 61 74 20   string.** that 
383f0 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 70 6f  this variable po
38400 69 6e 74 73 20 74 6f 20 69 73 20 68 65 6c 64 20  ints to is held 
38410 69 6e 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e  in memory obtain
38420 65 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c  ed from .** [sql
38430 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 20 61 6e 64  ite3_malloc] and
38440 20 74 68 65 20 70 72 61 67 6d 61 20 6d 61 79 20   the pragma may 
38450 61 74 74 65 6d 70 74 20 74 6f 20 66 72 65 65 20  attempt to free 
38460 74 68 61 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 75  that memory.** u
38470 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72  sing [sqlite3_fr
38480 65 65 5d 2e 0a 2a 2a 20 48 65 6e 63 65 2c 20 69  ee]..** Hence, i
38490 66 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20  f this variable 
384a0 69 73 20 6d 6f 64 69 66 69 65 64 20 64 69 72 65  is modified dire
384b0 63 74 6c 79 2c 20 65 69 74 68 65 72 20 69 74 20  ctly, either it 
384c0 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 6d 61 64  should be.** mad
384d0 65 20 4e 55 4c 4c 20 6f 72 20 6d 61 64 65 20 74  e NULL or made t
384e0 6f 20 70 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72  o point to memor
384f0 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
38500 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d  [sqlite3_malloc]
38510 0a 2a 2a 20 6f 72 20 65 6c 73 65 20 74 68 65 20  .** or else the 
38520 75 73 65 20 6f 66 20 74 68 65 20 5b 74 65 6d 70  use of the [temp
38530 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79  _store_directory
38540 20 70 72 61 67 6d 61 5d 20 73 68 6f 75 6c 64 20   pragma] should 
38550 62 65 20 61 76 6f 69 64 65 64 2e 0a 2a 2a 0a 2a  be avoided..**.*
38560 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e  * <b>Note to Win
38570 64 6f 77 73 20 52 75 6e 74 69 6d 65 20 75 73 65  dows Runtime use
38580 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 74 65 6d  rs:</b>  The tem
38590 70 6f 72 61 72 79 20 64 69 72 65 63 74 6f 72 79  porary directory
385a0 20 6d 75 73 74 20 62 65 20 73 65 74 0a 2a 2a 20   must be set.** 
385b0 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67  prior to calling
385c0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5d 20   [sqlite3_open] 
385d0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  or [sqlite3_open
385e0 5f 76 32 5d 2e 20 20 4f 74 68 65 72 77 69 73 65  _v2].  Otherwise
385f0 2c 20 76 61 72 69 6f 75 73 0a 2a 2a 20 66 65 61  , various.** fea
38600 74 75 72 65 73 20 74 68 61 74 20 72 65 71 75 69  tures that requi
38610 72 65 20 74 68 65 20 75 73 65 20 6f 66 20 74 65  re the use of te
38620 6d 70 6f 72 61 72 79 20 66 69 6c 65 73 20 6d 61  mporary files ma
38630 79 20 66 61 69 6c 2e 20 20 48 65 72 65 20 69 73  y fail.  Here is
38640 20 61 6e 0a 2a 2a 20 65 78 61 6d 70 6c 65 20 6f   an.** example o
38650 66 20 68 6f 77 20 74 6f 20 64 6f 20 74 68 69 73  f how to do this
38660 20 75 73 69 6e 67 20 43 2b 2b 20 77 69 74 68 20   using C++ with 
38670 74 68 65 20 57 69 6e 64 6f 77 73 20 52 75 6e 74  the Windows Runt
38680 69 6d 65 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ime:.**.** <bloc
38690 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
386a0 4c 50 43 57 53 54 52 20 7a 50 61 74 68 20 3d 20  LPCWSTR zPath = 
386b0 57 69 6e 64 6f 77 73 3a 3a 53 74 6f 72 61 67 65  Windows::Storage
386c0 3a 3a 41 70 70 6c 69 63 61 74 69 6f 6e 44 61 74  ::ApplicationDat
386d0 61 3a 3a 43 75 72 72 65 6e 74 2d 3e 0a 2a 2a 20  a::Current->.** 
386e0 26 6e 62 73 70 3b 20 20 20 20 20 54 65 6d 70 6f  &nbsp;     Tempo
386f0 72 61 72 79 46 6f 6c 64 65 72 2d 3e 50 61 74 68  raryFolder->Path
38700 2d 3e 44 61 74 61 28 29 3b 0a 2a 2a 20 63 68 61  ->Data();.** cha
38710 72 20 7a 50 61 74 68 42 75 66 26 23 39 31 3b 4d  r zPathBuf&#91;M
38720 41 58 5f 50 41 54 48 20 2b 20 31 26 23 39 33 3b  AX_PATH + 1&#93;
38730 3b 0a 2a 2a 20 6d 65 6d 73 65 74 28 7a 50 61 74  ;.** memset(zPat
38740 68 42 75 66 2c 20 30 2c 20 73 69 7a 65 6f 66 28  hBuf, 0, sizeof(
38750 7a 50 61 74 68 42 75 66 29 29 3b 0a 2a 2a 20 57  zPathBuf));.** W
38760 69 64 65 43 68 61 72 54 6f 4d 75 6c 74 69 42 79  ideCharToMultiBy
38770 74 65 28 43 50 5f 55 54 46 38 2c 20 30 2c 20 7a  te(CP_UTF8, 0, z
38780 50 61 74 68 2c 20 2d 31 2c 20 7a 50 61 74 68 42  Path, -1, zPathB
38790 75 66 2c 20 73 69 7a 65 6f 66 28 7a 50 61 74 68  uf, sizeof(zPath
387a0 42 75 66 29 2c 0a 2a 2a 20 26 6e 62 73 70 3b 20  Buf),.** &nbsp; 
387b0 20 20 20 20 4e 55 4c 4c 2c 20 4e 55 4c 4c 29 3b      NULL, NULL);
387c0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 74 65 6d 70  .** sqlite3_temp
387d0 5f 64 69 72 65 63 74 6f 72 79 20 3d 20 73 71 6c  _directory = sql
387e0 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 25 73  ite3_mprintf("%s
387f0 22 2c 20 7a 50 61 74 68 42 75 66 29 3b 0a 2a 2a  ", zPathBuf);.**
38800 20 3c 2f