/ Hex Artifact Content
Login

Artifact 238059420ea5e60deb6dacc3c46a44f47739060d:


0000: 2f 2a 0a 2a 2a 20 32 30 30 31 20 53 65 70 74 65  /*.** 2001 Septe
0010: 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68  mber 15.**.** Th
0020: 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69  e author disclai
0030: 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20  ms copyright to 
0040: 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65  this source code
0050: 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  .  In place of.*
0060: 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65  * a legal notice
0070: 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 73  , here is a bles
0080: 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d  sing:.**.**    M
0090: 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61  ay you do good a
00a0: 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20  nd not evil..** 
00b0: 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20     May you find 
00c0: 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20  forgiveness for 
00d0: 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72  yourself and for
00e0: 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20  give others..** 
00f0: 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65     May you share
0100: 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74   freely, never t
0110: 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20  aking more than 
0120: 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a  you give..**.***
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0170: 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 68  ******.** This h
0180: 65 61 64 65 72 20 66 69 6c 65 20 64 65 66 69 6e  eader file defin
0190: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
01a0: 20 74 68 61 74 20 74 68 65 20 53 51 4c 69 74 65   that the SQLite
01b0: 20 6c 69 62 72 61 72 79 0a 2a 2a 20 70 72 65 73   library.** pres
01c0: 65 6e 74 73 20 74 6f 20 63 6c 69 65 6e 74 20 70  ents to client p
01d0: 72 6f 67 72 61 6d 73 2e 20 20 49 66 20 61 20 43  rograms.  If a C
01e0: 2d 66 75 6e 63 74 69 6f 6e 2c 20 73 74 72 75 63  -function, struc
01f0: 74 75 72 65 2c 20 64 61 74 61 74 79 70 65 2c 0a  ture, datatype,.
0200: 2a 2a 20 6f 72 20 63 6f 6e 73 74 61 6e 74 20 64  ** or constant d
0210: 65 66 69 6e 69 74 69 6f 6e 20 64 6f 65 73 20 6e  efinition does n
0220: 6f 74 20 61 70 70 65 61 72 20 69 6e 20 74 68 69  ot appear in thi
0230: 73 20 66 69 6c 65 2c 20 74 68 65 6e 20 69 74 20  s file, then it 
0240: 69 73 0a 2a 2a 20 6e 6f 74 20 61 20 70 75 62 6c  is.** not a publ
0250: 69 73 68 65 64 20 41 50 49 20 6f 66 20 53 51 4c  ished API of SQL
0260: 69 74 65 2c 20 69 73 20 73 75 62 6a 65 63 74 20  ite, is subject 
0270: 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75  to change withou
0280: 74 0a 2a 2a 20 6e 6f 74 69 63 65 2c 20 61 6e 64  t.** notice, and
0290: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 72   should not be r
02a0: 65 66 65 72 65 6e 63 65 64 20 62 79 20 70 72 6f  eferenced by pro
02b0: 67 72 61 6d 73 20 74 68 61 74 20 75 73 65 20 53  grams that use S
02c0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d  QLite..**.** Som
02d0: 65 20 6f 66 20 74 68 65 20 64 65 66 69 6e 69 74  e of the definit
02e0: 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 69 6e  ions that are in
02f0: 20 74 68 69 73 20 66 69 6c 65 20 61 72 65 20 6d   this file are m
0300: 61 72 6b 65 64 20 61 73 0a 2a 2a 20 22 65 78 70  arked as.** "exp
0310: 65 72 69 6d 65 6e 74 61 6c 22 2e 20 20 45 78 70  erimental".  Exp
0320: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
0330: 61 63 65 73 20 61 72 65 20 6e 6f 72 6d 61 6c 6c  aces are normall
0340: 79 20 6e 65 77 0a 2a 2a 20 66 65 61 74 75 72 65  y new.** feature
0350: 73 20 72 65 63 65 6e 74 6c 79 20 61 64 64 65 64  s recently added
0360: 20 74 6f 20 53 51 4c 69 74 65 2e 20 20 57 65 20   to SQLite.  We 
0370: 64 6f 20 6e 6f 74 20 61 6e 74 69 63 69 70 61 74  do not anticipat
0380: 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20  e changes.** to 
0390: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
03a0: 65 72 66 61 63 65 73 20 62 75 74 20 72 65 73 65  erfaces but rese
03b0: 72 76 65 20 74 68 65 20 72 69 67 68 74 20 74 6f  rve the right to
03c0: 20 6d 61 6b 65 20 6d 69 6e 6f 72 20 63 68 61 6e   make minor chan
03d0: 67 65 73 0a 2a 2a 20 69 66 20 65 78 70 65 72 69  ges.** if experi
03e0: 65 6e 63 65 20 66 72 6f 6d 20 75 73 65 20 22 69  ence from use "i
03f0: 6e 20 74 68 65 20 77 69 6c 64 22 20 73 75 67 67  n the wild" sugg
0400: 65 73 74 20 73 75 63 68 20 63 68 61 6e 67 65 73  est such changes
0410: 20 61 72 65 20 70 72 75 64 65 6e 74 2e 0a 2a 2a   are prudent..**
0420: 0a 2a 2a 20 54 68 65 20 6f 66 66 69 63 69 61 6c  .** The official
0430: 20 43 2d 6c 61 6e 67 75 61 67 65 20 41 50 49 20   C-language API 
0440: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  documentation fo
0450: 72 20 53 51 4c 69 74 65 20 69 73 20 64 65 72 69  r SQLite is deri
0460: 76 65 64 0a 2a 2a 20 66 72 6f 6d 20 63 6f 6d 6d  ved.** from comm
0470: 65 6e 74 73 20 69 6e 20 74 68 69 73 20 66 69 6c  ents in this fil
0480: 65 2e 20 20 54 68 69 73 20 66 69 6c 65 20 69 73  e.  This file is
0490: 20 74 68 65 20 61 75 74 68 6f 72 69 74 61 74 69   the authoritati
04a0: 76 65 20 73 6f 75 72 63 65 0a 2a 2a 20 6f 6e 20  ve source.** on 
04b0: 68 6f 77 20 53 51 4c 69 74 65 20 69 6e 74 65 72  how SQLite inter
04c0: 66 61 63 65 73 20 61 72 65 20 73 75 70 70 6f 73  faces are suppos
04d0: 65 20 74 6f 20 6f 70 65 72 61 74 65 2e 0a 2a 2a  e to operate..**
04e0: 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20  .** The name of 
04f0: 74 68 69 73 20 66 69 6c 65 20 75 6e 64 65 72 20  this file under 
0500: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61  configuration ma
0510: 6e 61 67 65 6d 65 6e 74 20 69 73 20 22 73 71 6c  nagement is "sql
0520: 69 74 65 2e 68 2e 69 6e 22 2e 0a 2a 2a 20 54 68  ite.h.in"..** Th
0530: 65 20 6d 61 6b 65 66 69 6c 65 20 6d 61 6b 65 73  e makefile makes
0540: 20 73 6f 6d 65 20 6d 69 6e 6f 72 20 63 68 61 6e   some minor chan
0550: 67 65 73 20 74 6f 20 74 68 69 73 20 66 69 6c 65  ges to this file
0560: 20 28 73 75 63 68 20 61 73 20 69 6e 73 65 72 74   (such as insert
0570: 69 6e 67 0a 2a 2a 20 74 68 65 20 76 65 72 73 69  ing.** the versi
0580: 6f 6e 20 6e 75 6d 62 65 72 29 20 61 6e 64 20 63  on number) and c
0590: 68 61 6e 67 65 73 20 69 74 73 20 6e 61 6d 65 20  hanges its name 
05a0: 74 6f 20 22 73 71 6c 69 74 65 33 2e 68 22 20 61  to "sqlite3.h" a
05b0: 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74 68 65  s.** part of the
05c0: 20 62 75 69 6c 64 20 70 72 6f 63 65 73 73 2e 0a   build process..
05d0: 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 53 51 4c 49  */.#ifndef _SQLI
05e0: 54 45 33 5f 48 5f 0a 23 64 65 66 69 6e 65 20 5f  TE3_H_.#define _
05f0: 53 51 4c 49 54 45 33 5f 48 5f 0a 23 69 6e 63 6c  SQLITE3_H_.#incl
0600: 75 64 65 20 3c 73 74 64 61 72 67 2e 68 3e 20 20  ude <stdarg.h>  
0610: 20 20 20 2f 2a 20 4e 65 65 64 65 64 20 66 6f 72     /* Needed for
0620: 20 74 68 65 20 64 65 66 69 6e 69 74 69 6f 6e 20   the definition 
0630: 6f 66 20 76 61 5f 6c 69 73 74 20 2a 2f 0a 0a 2f  of va_list */../
0640: 2a 0a 2a 2a 20 4d 61 6b 65 20 73 75 72 65 20 77  *.** Make sure w
0650: 65 20 63 61 6e 20 63 61 6c 6c 20 74 68 69 73 20  e can call this 
0660: 73 74 75 66 66 20 66 72 6f 6d 20 43 2b 2b 2e 0a  stuff from C++..
0670: 2a 2f 0a 23 69 66 64 65 66 20 5f 5f 63 70 6c 75  */.#ifdef __cplu
0680: 73 70 6c 75 73 0a 65 78 74 65 72 6e 20 22 43 22  splus.extern "C"
0690: 20 7b 0a 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a   {.#endif.../*.*
06a0: 2a 20 41 64 64 20 74 68 65 20 61 62 69 6c 69 74  * Add the abilit
06b0: 79 20 74 6f 20 6f 76 65 72 72 69 64 65 20 27 65  y to override 'e
06c0: 78 74 65 72 6e 27 0a 2a 2f 0a 23 69 66 6e 64 65  xtern'.*/.#ifnde
06d0: 66 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 0a  f SQLITE_EXTERN.
06e0: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
06f0: 45 58 54 45 52 4e 20 65 78 74 65 72 6e 0a 23 65  EXTERN extern.#e
0700: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 73  ndif../*.** Thes
0710: 65 20 6e 6f 2d 6f 70 20 6d 61 63 72 6f 73 20 61  e no-op macros a
0720: 72 65 20 75 73 65 64 20 69 6e 20 66 72 6f 6e 74  re used in front
0730: 20 6f 66 20 69 6e 74 65 72 66 61 63 65 73 20 74   of interfaces t
0740: 6f 20 6d 61 72 6b 20 74 68 6f 73 65 0a 2a 2a 20  o mark those.** 
0750: 69 6e 74 65 72 66 61 63 65 73 20 61 73 20 65 69  interfaces as ei
0760: 74 68 65 72 20 64 65 70 72 65 63 61 74 65 64 20  ther deprecated 
0770: 6f 72 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e  or experimental.
0780: 20 20 4e 65 77 20 61 70 70 6c 69 63 61 74 69 6f    New applicatio
0790: 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f 74  ns.** should not
07a0: 20 75 73 65 20 64 65 70 72 65 63 61 74 65 64 20   use deprecated 
07b0: 69 6e 74 65 72 66 61 63 65 73 20 2d 20 74 68 65  interfaces - the
07c0: 79 20 61 72 65 20 73 75 70 70 6f 72 74 20 66 6f  y are support fo
07d0: 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63  r backwards.** c
07e0: 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c  ompatibility onl
07f0: 79 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 20  y.  Application 
0800: 77 72 69 74 65 72 73 20 73 68 6f 75 6c 64 20 62  writers should b
0810: 65 20 61 77 61 72 65 20 74 68 61 74 0a 2a 2a 20  e aware that.** 
0820: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
0830: 65 72 66 61 63 65 73 20 61 72 65 20 73 75 62 6a  erfaces are subj
0840: 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 69 6e  ect to change in
0850: 20 70 6f 69 6e 74 20 72 65 6c 65 61 73 65 73 2e   point releases.
0860: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 6d 61 63  .**.** These mac
0870: 72 6f 73 20 75 73 65 64 20 74 6f 20 72 65 73 6f  ros used to reso
0880: 6c 76 65 20 74 6f 20 76 61 72 69 6f 75 73 20 6b  lve to various k
0890: 69 6e 64 73 20 6f 66 20 63 6f 6d 70 69 6c 65 72  inds of compiler
08a0: 20 6d 61 67 69 63 20 74 68 61 74 0a 2a 2a 20 77   magic that.** w
08b0: 6f 75 6c 64 20 67 65 6e 65 72 61 74 65 20 77 61  ould generate wa
08c0: 72 6e 69 6e 67 20 6d 65 73 73 61 67 65 73 20 77  rning messages w
08d0: 68 65 6e 20 74 68 65 79 20 77 65 72 65 20 75 73  hen they were us
08e0: 65 64 2e 20 20 42 75 74 20 74 68 61 74 0a 2a 2a  ed.  But that.**
08f0: 20 63 6f 6d 70 69 6c 65 72 20 6d 61 67 69 63 20   compiler magic 
0900: 65 6e 64 65 64 20 75 70 20 67 65 6e 65 72 61 74  ended up generat
0910: 69 6e 67 20 73 75 63 68 20 61 20 66 6c 75 72 72  ing such a flurr
0920: 79 20 6f 66 20 62 75 67 20 72 65 70 6f 72 74 73  y of bug reports
0930: 0a 2a 2a 20 74 68 61 74 20 77 65 20 68 61 76 65  .** that we have
0940: 20 74 61 6b 65 6e 20 69 74 20 61 6c 6c 20 6f 75   taken it all ou
0950: 74 20 61 6e 64 20 67 6f 6e 65 20 62 61 63 6b 20  t and gone back 
0960: 74 6f 20 75 73 69 6e 67 20 73 69 6d 70 6c 65 0a  to using simple.
0970: 2a 2a 20 6e 6f 6f 70 20 6d 61 63 72 6f 73 2e 0a  ** noop macros..
0980: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
0990: 45 5f 44 45 50 52 45 43 41 54 45 44 0a 23 64 65  E_DEPRECATED.#de
09a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 58 50 45  fine SQLITE_EXPE
09b0: 52 49 4d 45 4e 54 41 4c 0a 0a 2f 2a 0a 2a 2a 20  RIMENTAL../*.** 
09c0: 45 6e 73 75 72 65 20 74 68 65 73 65 20 73 79 6d  Ensure these sym
09d0: 62 6f 6c 73 20 77 65 72 65 20 6e 6f 74 20 64 65  bols were not de
09e0: 66 69 6e 65 64 20 62 79 20 73 6f 6d 65 20 70 72  fined by some pr
09f0: 65 76 69 6f 75 73 20 68 65 61 64 65 72 20 66 69  evious header fi
0a00: 6c 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51  le..*/.#ifdef SQ
0a10: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 0a 23 20 75  LITE_VERSION.# u
0a20: 6e 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53  ndef SQLITE_VERS
0a30: 49 4f 4e 0a 23 65 6e 64 69 66 0a 23 69 66 64 65  ION.#endif.#ifde
0a40: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  f SQLITE_VERSION
0a50: 5f 4e 55 4d 42 45 52 0a 23 20 75 6e 64 65 66 20  _NUMBER.# undef 
0a60: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e  SQLITE_VERSION_N
0a70: 55 4d 42 45 52 0a 23 65 6e 64 69 66 0a 0a 2f 2a  UMBER.#endif../*
0a80: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
0a90: 6d 70 69 6c 65 2d 54 69 6d 65 20 4c 69 62 72 61  mpile-Time Libra
0aa0: 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65  ry Version Numbe
0ab0: 72 73 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 5b  rs.**.** ^(The [
0ac0: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 20  SQLITE_VERSION] 
0ad0: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
0ae0: 61 63 72 6f 20 69 6e 20 74 68 65 20 73 71 6c 69  acro in the sqli
0af0: 74 65 33 2e 68 20 68 65 61 64 65 72 0a 2a 2a 20  te3.h header.** 
0b00: 65 76 61 6c 75 61 74 65 73 20 74 6f 20 61 20 73  evaluates to a s
0b10: 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 20 74 68  tring literal th
0b20: 61 74 20 69 73 20 74 68 65 20 53 51 4c 69 74 65  at is the SQLite
0b30: 20 76 65 72 73 69 6f 6e 20 69 6e 20 74 68 65 0a   version in the.
0b40: 2a 2a 20 66 6f 72 6d 61 74 20 22 58 2e 59 2e 5a  ** format "X.Y.Z
0b50: 22 20 77 68 65 72 65 20 58 20 69 73 20 74 68 65  " where X is the
0b60: 20 6d 61 6a 6f 72 20 76 65 72 73 69 6f 6e 20 6e   major version n
0b70: 75 6d 62 65 72 20 28 61 6c 77 61 79 73 20 33 20  umber (always 3 
0b80: 66 6f 72 0a 2a 2a 20 53 51 4c 69 74 65 33 29 20  for.** SQLite3) 
0b90: 61 6e 64 20 59 20 69 73 20 74 68 65 20 6d 69 6e  and Y is the min
0ba0: 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65  or version numbe
0bb0: 72 20 61 6e 64 20 5a 20 69 73 20 74 68 65 20 72  r and Z is the r
0bc0: 65 6c 65 61 73 65 20 6e 75 6d 62 65 72 2e 29 5e  elease number.)^
0bd0: 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c 49 54  .** ^(The [SQLIT
0be0: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
0bf0: 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C preprocessor
0c00: 20 6d 61 63 72 6f 20 72 65 73 6f 6c 76 65 73 20   macro resolves 
0c10: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a  to an integer.**
0c20: 20 77 69 74 68 20 74 68 65 20 76 61 6c 75 65 20   with the value 
0c30: 28 58 2a 31 30 30 30 30 30 30 20 2b 20 59 2a 31  (X*1000000 + Y*1
0c40: 30 30 30 20 2b 20 5a 29 20 77 68 65 72 65 20 58  000 + Z) where X
0c50: 2c 20 59 2c 20 61 6e 64 20 5a 20 61 72 65 20 74  , Y, and Z are t
0c60: 68 65 20 73 61 6d 65 0a 2a 2a 20 6e 75 6d 62 65  he same.** numbe
0c70: 72 73 20 75 73 65 64 20 69 6e 20 5b 53 51 4c 49  rs used in [SQLI
0c80: 54 45 5f 56 45 52 53 49 4f 4e 5d 2e 29 5e 0a 2a  TE_VERSION].)^.*
0c90: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 56 45 52  * The SQLITE_VER
0ca0: 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 66 6f 72 20  SION_NUMBER for 
0cb0: 61 6e 79 20 67 69 76 65 6e 20 72 65 6c 65 61 73  any given releas
0cc0: 65 20 6f 66 20 53 51 4c 69 74 65 20 77 69 6c 6c  e of SQLite will
0cd0: 20 61 6c 73 6f 0a 2a 2a 20 62 65 20 6c 61 72 67   also.** be larg
0ce0: 65 72 20 74 68 61 6e 20 74 68 65 20 72 65 6c 65  er than the rele
0cf0: 61 73 65 20 66 72 6f 6d 20 77 68 69 63 68 20 69  ase from which i
0d00: 74 20 69 73 20 64 65 72 69 76 65 64 2e 20 20 45  t is derived.  E
0d10: 69 74 68 65 72 20 59 20 77 69 6c 6c 0a 2a 2a 20  ither Y will.** 
0d20: 62 65 20 68 65 6c 64 20 63 6f 6e 73 74 61 6e 74  be held constant
0d30: 20 61 6e 64 20 5a 20 77 69 6c 6c 20 62 65 20 69   and Z will be i
0d40: 6e 63 72 65 6d 65 6e 74 65 64 20 6f 72 20 65 6c  ncremented or el
0d50: 73 65 20 59 20 77 69 6c 6c 20 62 65 20 69 6e 63  se Y will be inc
0d60: 72 65 6d 65 6e 74 65 64 0a 2a 2a 20 61 6e 64 20  remented.** and 
0d70: 5a 20 77 69 6c 6c 20 62 65 20 72 65 73 65 74 20  Z will be reset 
0d80: 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53  to zero..**.** S
0d90: 69 6e 63 65 20 76 65 72 73 69 6f 6e 20 33 2e 36  ince version 3.6
0da0: 2e 31 38 2c 20 53 51 4c 69 74 65 20 73 6f 75 72  .18, SQLite sour
0db0: 63 65 20 63 6f 64 65 20 68 61 73 20 62 65 65 6e  ce code has been
0dc0: 20 73 74 6f 72 65 64 20 69 6e 20 74 68 65 0a 2a   stored in the.*
0dd0: 2a 20 3c 61 20 68 72 65 66 3d 22 68 74 74 70 3a  * <a href="http:
0de0: 2f 2f 77 77 77 2e 66 6f 73 73 69 6c 2d 73 63 6d  //www.fossil-scm
0df0: 2e 6f 72 67 2f 22 3e 46 6f 73 73 69 6c 20 63 6f  .org/">Fossil co
0e00: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61  nfiguration mana
0e10: 67 65 6d 65 6e 74 0a 2a 2a 20 73 79 73 74 65 6d  gement.** system
0e20: 3c 2f 61 3e 2e 20 20 5e 54 68 65 20 53 51 4c 49  </a>.  ^The SQLI
0e30: 54 45 5f 53 4f 55 52 43 45 5f 49 44 20 6d 61 63  TE_SOURCE_ID mac
0e40: 72 6f 20 65 76 61 6c 75 61 74 65 73 20 74 6f 0a  ro evaluates to.
0e50: 2a 2a 20 61 20 73 74 72 69 6e 67 20 77 68 69 63  ** a string whic
0e60: 68 20 69 64 65 6e 74 69 66 69 65 73 20 61 20 70  h identifies a p
0e70: 61 72 74 69 63 75 6c 61 72 20 63 68 65 63 6b 2d  articular check-
0e80: 69 6e 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20  in of SQLite.** 
0e90: 77 69 74 68 69 6e 20 69 74 73 20 63 6f 6e 66 69  within its confi
0ea0: 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d  guration managem
0eb0: 65 6e 74 20 73 79 73 74 65 6d 2e 20 20 5e 54 68  ent system.  ^Th
0ec0: 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f  e SQLITE_SOURCE_
0ed0: 49 44 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e  ID.** string con
0ee0: 74 61 69 6e 73 20 74 68 65 20 64 61 74 65 20 61  tains the date a
0ef0: 6e 64 20 74 69 6d 65 20 6f 66 20 74 68 65 20 63  nd time of the c
0f00: 68 65 63 6b 2d 69 6e 20 28 55 54 43 29 20 61 6e  heck-in (UTC) an
0f10: 64 20 61 6e 20 53 48 41 31 0a 2a 2a 20 68 61 73  d an SHA1.** has
0f20: 68 20 6f 66 20 74 68 65 20 65 6e 74 69 72 65 20  h of the entire 
0f30: 73 6f 75 72 63 65 20 74 72 65 65 2e 0a 2a 2a 0a  source tree..**.
0f40: 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
0f50: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
0f60: 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
0f70: 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62  _libversion_numb
0f80: 65 72 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  er()], [sqlite3_
0f90: 73 6f 75 72 63 65 69 64 28 29 5d 2c 0a 2a 2a 20  sourceid()],.** 
0fa0: 5b 73 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28  [sqlite_version(
0fb0: 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73  )] and [sqlite_s
0fc0: 6f 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a  ource_id()]..*/.
0fd0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56  #define SQLITE_V
0fe0: 45 52 53 49 4f 4e 20 20 20 20 20 20 20 20 22 2d  ERSION        "-
0ff0: 2d 56 45 52 53 2d 2d 22 0a 23 64 65 66 69 6e 65  -VERS--".#define
1000: 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f   SQLITE_VERSION_
1010: 4e 55 4d 42 45 52 20 2d 2d 56 45 52 53 49 4f 4e  NUMBER --VERSION
1020: 2d 4e 55 4d 42 45 52 2d 2d 0a 23 64 65 66 69 6e  -NUMBER--.#defin
1030: 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f  e SQLITE_SOURCE_
1040: 49 44 20 20 20 20 20 20 22 2d 2d 53 4f 55 52 43  ID      "--SOURC
1050: 45 2d 49 44 2d 2d 22 0a 0a 2f 2a 0a 2a 2a 20 43  E-ID--"../*.** C
1060: 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d  API3REF: Run-Tim
1070: 65 20 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f  e Library Versio
1080: 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 20 4b 45 59  n Numbers.** KEY
1090: 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76  WORDS: sqlite3_v
10a0: 65 72 73 69 6f 6e 2c 20 73 71 6c 69 74 65 33 5f  ersion, sqlite3_
10b0: 73 6f 75 72 63 65 69 64 0a 2a 2a 0a 2a 2a 20 54  sourceid.**.** T
10c0: 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20  hese interfaces 
10d0: 70 72 6f 76 69 64 65 20 74 68 65 20 73 61 6d 65  provide the same
10e0: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20   information as 
10f0: 74 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 53  the [SQLITE_VERS
1100: 49 4f 4e 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  ION],.** [SQLITE
1110: 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d  _VERSION_NUMBER]
1120: 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 53 4f  , and [SQLITE_SO
1130: 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65 70 72  URCE_ID] C prepr
1140: 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 73 0a 2a  ocessor macros.*
1150: 2a 20 62 75 74 20 61 72 65 20 61 73 73 6f 63 69  * but are associ
1160: 61 74 65 64 20 77 69 74 68 20 74 68 65 20 6c 69  ated with the li
1170: 62 72 61 72 79 20 69 6e 73 74 65 61 64 20 6f 66  brary instead of
1180: 20 74 68 65 20 68 65 61 64 65 72 20 66 69 6c 65   the header file
1190: 2e 20 20 5e 28 43 61 75 74 69 6f 75 73 0a 2a 2a  .  ^(Cautious.**
11a0: 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67   programmers mig
11b0: 68 74 20 69 6e 63 6c 75 64 65 20 61 73 73 65 72  ht include asser
11c0: 74 28 29 20 73 74 61 74 65 6d 65 6e 74 73 20 69  t() statements i
11d0: 6e 20 74 68 65 69 72 20 61 70 70 6c 69 63 61 74  n their applicat
11e0: 69 6f 6e 20 74 6f 0a 2a 2a 20 76 65 72 69 66 79  ion to.** verify
11f0: 20 74 68 61 74 20 76 61 6c 75 65 73 20 72 65 74   that values ret
1200: 75 72 6e 65 64 20 62 79 20 74 68 65 73 65 20 69  urned by these i
1210: 6e 74 65 72 66 61 63 65 73 20 6d 61 74 63 68 20  nterfaces match 
1220: 74 68 65 20 6d 61 63 72 6f 73 20 69 6e 0a 2a 2a  the macros in.**
1230: 20 74 68 65 20 68 65 61 64 65 72 2c 20 61 6e 64   the header, and
1240: 20 74 68 75 73 20 69 6e 73 75 72 65 20 74 68 61   thus insure tha
1250: 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  t the applicatio
1260: 6e 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64  n is.** compiled
1270: 20 77 69 74 68 20 6d 61 74 63 68 69 6e 67 20 6c   with matching l
1280: 69 62 72 61 72 79 20 61 6e 64 20 68 65 61 64 65  ibrary and heade
1290: 72 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 3c  r files..**.** <
12a0: 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
12b0: 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 71 6c 69  .** assert( sqli
12c0: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e  te3_libversion_n
12d0: 75 6d 62 65 72 28 29 3d 3d 53 51 4c 49 54 45 5f  umber()==SQLITE_
12e0: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 29  VERSION_NUMBER )
12f0: 3b 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 74 72  ;.** assert( str
1300: 63 6d 70 28 73 71 6c 69 74 65 33 5f 73 6f 75 72  cmp(sqlite3_sour
1310: 63 65 69 64 28 29 2c 53 51 4c 49 54 45 5f 53 4f  ceid(),SQLITE_SO
1320: 55 52 43 45 5f 49 44 29 3d 3d 30 20 29 3b 0a 2a  URCE_ID)==0 );.*
1330: 2a 20 61 73 73 65 72 74 28 20 73 74 72 63 6d 70  * assert( strcmp
1340: 28 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73  (sqlite3_libvers
1350: 69 6f 6e 28 29 2c 53 51 4c 49 54 45 5f 56 45 52  ion(),SQLITE_VER
1360: 53 49 4f 4e 29 3d 3d 30 20 29 3b 0a 2a 2a 20 3c  SION)==0 );.** <
1370: 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
1380: 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  e>)^.**.** ^The 
1390: 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b  sqlite3_version[
13a0: 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e  ] string constan
13b0: 74 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 74  t contains the t
13c0: 65 78 74 20 6f 66 20 5b 53 51 4c 49 54 45 5f 56  ext of [SQLITE_V
13d0: 45 52 53 49 4f 4e 5d 0a 2a 2a 20 6d 61 63 72 6f  ERSION].** macro
13e0: 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
13f0: 6c 69 62 76 65 72 73 69 6f 6e 28 29 20 66 75 6e  libversion() fun
1400: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 20  ction returns a 
1410: 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a  pointer to the.*
1420: 2a 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  * to the sqlite3
1430: 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e  _version[] strin
1440: 67 20 63 6f 6e 73 74 61 6e 74 2e 20 20 54 68 65  g constant.  The
1450: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73   sqlite3_libvers
1460: 69 6f 6e 28 29 0a 2a 2a 20 66 75 6e 63 74 69 6f  ion().** functio
1470: 6e 20 69 73 20 70 72 6f 76 69 64 65 64 20 66 6f  n is provided fo
1480: 72 20 75 73 65 20 69 6e 20 44 4c 4c 73 20 73 69  r use in DLLs si
1490: 6e 63 65 20 44 4c 4c 20 75 73 65 72 73 20 75 73  nce DLL users us
14a0: 75 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 68 61 76  ually do not hav
14b0: 65 0a 2a 2a 20 64 69 72 65 63 74 20 61 63 63 65  e.** direct acce
14c0: 73 73 20 74 6f 20 73 74 72 69 6e 67 20 63 6f 6e  ss to string con
14d0: 73 74 61 6e 74 73 20 77 69 74 68 69 6e 20 74 68  stants within th
14e0: 65 20 44 4c 4c 2e 20 20 5e 54 68 65 0a 2a 2a 20  e DLL.  ^The.** 
14f0: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
1500: 6f 6e 5f 6e 75 6d 62 65 72 28 29 20 66 75 6e 63  on_number() func
1510: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 6e 20  tion returns an 
1520: 69 6e 74 65 67 65 72 20 65 71 75 61 6c 20 74 6f  integer equal to
1530: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52 53  .** [SQLITE_VERS
1540: 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 20 20 5e 54  ION_NUMBER].  ^T
1550: 68 65 20 73 71 6c 69 74 65 33 5f 73 6f 75 72 63  he sqlite3_sourc
1560: 65 69 64 28 29 20 66 75 6e 63 74 69 6f 6e 20 72  eid() function r
1570: 65 74 75 72 6e 73 20 0a 2a 2a 20 61 20 70 6f 69  eturns .** a poi
1580: 6e 74 65 72 20 74 6f 20 61 20 73 74 72 69 6e 67  nter to a string
1590: 20 63 6f 6e 73 74 61 6e 74 20 77 68 6f 73 65 20   constant whose 
15a0: 76 61 6c 75 65 20 69 73 20 74 68 65 20 73 61 6d  value is the sam
15b0: 65 20 61 73 20 74 68 65 20 0a 2a 2a 20 5b 53 51  e as the .** [SQ
15c0: 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20  LITE_SOURCE_ID] 
15d0: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
15e0: 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  acro..**.** See 
15f0: 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 5f 76 65  also: [sqlite_ve
1600: 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71  rsion()] and [sq
1610: 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29  lite_source_id()
1620: 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54  ]..*/.SQLITE_EXT
1630: 45 52 4e 20 63 6f 6e 73 74 20 63 68 61 72 20 73  ERN const char s
1640: 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d  qlite3_version[]
1650: 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  ;.const char *sq
1660: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
1670: 28 76 6f 69 64 29 3b 0a 63 6f 6e 73 74 20 63 68  (void);.const ch
1680: 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6f 75 72  ar *sqlite3_sour
1690: 63 65 69 64 28 76 6f 69 64 29 3b 0a 69 6e 74 20  ceid(void);.int 
16a0: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
16b0: 6f 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b  on_number(void);
16c0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
16d0: 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61  : Run-Time Libra
16e0: 72 79 20 43 6f 6d 70 69 6c 61 74 69 6f 6e 20 4f  ry Compilation O
16f0: 70 74 69 6f 6e 73 20 44 69 61 67 6e 6f 73 74 69  ptions Diagnosti
1700: 63 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  cs.**.** ^The sq
1710: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
1720: 69 6f 6e 5f 75 73 65 64 28 29 20 66 75 6e 63 74  ion_used() funct
1730: 69 6f 6e 20 72 65 74 75 72 6e 73 20 30 20 6f 72  ion returns 0 or
1740: 20 31 20 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e   1 .** indicatin
1750: 67 20 77 68 65 74 68 65 72 20 74 68 65 20 73 70  g whether the sp
1760: 65 63 69 66 69 65 64 20 6f 70 74 69 6f 6e 20 77  ecified option w
1770: 61 73 20 64 65 66 69 6e 65 64 20 61 74 20 0a 2a  as defined at .*
1780: 2a 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20  * compile time. 
1790: 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 70 72   ^The SQLITE_ pr
17a0: 65 66 69 78 20 6d 61 79 20 62 65 20 6f 6d 69 74  efix may be omit
17b0: 74 65 64 20 66 72 6f 6d 20 74 68 65 20 0a 2a 2a  ted from the .**
17c0: 20 6f 70 74 69 6f 6e 20 6e 61 6d 65 20 70 61 73   option name pas
17d0: 73 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  sed to sqlite3_c
17e0: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
17f0: 64 28 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68  d().  .**.** ^Th
1800: 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c  e sqlite3_compil
1810: 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 66 75  eoption_get() fu
1820: 6e 63 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 69 74  nction allows it
1830: 65 72 61 74 69 6e 67 0a 2a 2a 20 6f 76 65 72 20  erating.** over 
1840: 74 68 65 20 6c 69 73 74 20 6f 66 20 6f 70 74 69  the list of opti
1850: 6f 6e 73 20 74 68 61 74 20 77 65 72 65 20 64 65  ons that were de
1860: 66 69 6e 65 64 20 61 74 20 63 6f 6d 70 69 6c 65  fined at compile
1870: 20 74 69 6d 65 20 62 79 0a 2a 2a 20 72 65 74 75   time by.** retu
1880: 72 6e 69 6e 67 20 74 68 65 20 4e 2d 74 68 20 63  rning the N-th c
1890: 6f 6d 70 69 6c 65 20 74 69 6d 65 20 6f 70 74 69  ompile time opti
18a0: 6f 6e 20 73 74 72 69 6e 67 2e 20 20 5e 49 66 20  on string.  ^If 
18b0: 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67  N is out of rang
18c0: 65 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  e,.** sqlite3_co
18d0: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28  mpileoption_get(
18e0: 29 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c  ) returns a NULL
18f0: 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20   pointer.  ^The 
1900: 53 51 4c 49 54 45 5f 20 0a 2a 2a 20 70 72 65 66  SQLITE_ .** pref
1910: 69 78 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72  ix is omitted fr
1920: 6f 6d 20 61 6e 79 20 73 74 72 69 6e 67 73 20 72  om any strings r
1930: 65 74 75 72 6e 65 64 20 62 79 20 0a 2a 2a 20 73  eturned by .** s
1940: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70  qlite3_compileop
1950: 74 69 6f 6e 5f 67 65 74 28 29 2e 0a 2a 2a 0a 2a  tion_get()..**.*
1960: 2a 20 5e 53 75 70 70 6f 72 74 20 66 6f 72 20 74  * ^Support for t
1970: 68 65 20 64 69 61 67 6e 6f 73 74 69 63 20 66 75  he diagnostic fu
1980: 6e 63 74 69 6f 6e 73 20 73 71 6c 69 74 65 33 5f  nctions sqlite3_
1990: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73  compileoption_us
19a0: 65 64 28 29 0a 2a 2a 20 61 6e 64 20 73 71 6c 69  ed().** and sqli
19b0: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  te3_compileoptio
19c0: 6e 5f 67 65 74 28 29 20 6d 61 79 20 62 65 20 6f  n_get() may be o
19d0: 6d 69 74 74 65 64 20 62 79 20 73 70 65 63 69 66  mitted by specif
19e0: 79 69 6e 67 20 74 68 65 20 0a 2a 2a 20 5b 53 51  ying the .** [SQ
19f0: 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c  LITE_OMIT_COMPIL
1a00: 45 4f 50 54 49 4f 4e 5f 44 49 41 47 53 5d 20 6f  EOPTION_DIAGS] o
1a10: 70 74 69 6f 6e 20 61 74 20 63 6f 6d 70 69 6c 65  ption at compile
1a20: 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65   time..**.** See
1a30: 20 61 6c 73 6f 3a 20 53 51 4c 20 66 75 6e 63 74   also: SQL funct
1a40: 69 6f 6e 73 20 5b 73 71 6c 69 74 65 5f 63 6f 6d  ions [sqlite_com
1a50: 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28  pileoption_used(
1a60: 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  )] and.** [sqlit
1a70: 65 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f  e_compileoption_
1a80: 67 65 74 28 29 5d 20 61 6e 64 20 74 68 65 20 5b  get()] and the [
1a90: 63 6f 6d 70 69 6c 65 5f 6f 70 74 69 6f 6e 73 20  compile_options 
1aa0: 70 72 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 69 66 6e  pragma]..*/.#ifn
1ab0: 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  def SQLITE_OMIT_
1ac0: 43 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49  COMPILEOPTION_DI
1ad0: 41 47 53 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  AGS.int sqlite3_
1ae0: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73  compileoption_us
1af0: 65 64 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  ed(const char *z
1b00: 4f 70 74 4e 61 6d 65 29 3b 0a 63 6f 6e 73 74 20  OptName);.const 
1b10: 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
1b20: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28  mpileoption_get(
1b30: 69 6e 74 20 4e 29 3b 0a 23 65 6e 64 69 66 0a 0a  int N);.#endif..
1b40: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1b50: 54 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 54  Test To See If T
1b60: 68 65 20 4c 69 62 72 61 72 79 20 49 73 20 54 68  he Library Is Th
1b70: 72 65 61 64 73 61 66 65 0a 2a 2a 0a 2a 2a 20 5e  readsafe.**.** ^
1b80: 54 68 65 20 73 71 6c 69 74 65 33 5f 74 68 72 65  The sqlite3_thre
1b90: 61 64 73 61 66 65 28 29 20 66 75 6e 63 74 69 6f  adsafe() functio
1ba0: 6e 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 69  n returns zero i
1bb0: 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a  f and only if.**
1bc0: 20 53 51 4c 69 74 65 20 77 61 73 20 63 6f 6d 70   SQLite was comp
1bd0: 69 6c 65 64 20 77 69 74 68 20 6d 75 74 65 78 69  iled with mutexi
1be0: 6e 67 20 63 6f 64 65 20 6f 6d 69 74 74 65 64 20  ng code omitted 
1bf0: 64 75 65 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 53  due to the.** [S
1c00: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
1c10: 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
1c20: 70 74 69 6f 6e 20 62 65 69 6e 67 20 73 65 74 20  ption being set 
1c30: 74 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  to 0..**.** SQLi
1c40: 74 65 20 63 61 6e 20 62 65 20 63 6f 6d 70 69 6c  te can be compil
1c50: 65 64 20 77 69 74 68 20 6f 72 20 77 69 74 68 6f  ed with or witho
1c60: 75 74 20 6d 75 74 65 78 65 73 2e 20 20 57 68 65  ut mutexes.  Whe
1c70: 6e 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  n.** the [SQLITE
1c80: 5f 54 48 52 45 41 44 53 41 46 45 5d 20 43 20 70  _THREADSAFE] C p
1c90: 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  reprocessor macr
1ca0: 6f 20 69 73 20 31 20 6f 72 20 32 2c 20 6d 75 74  o is 1 or 2, mut
1cb0: 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62  exes.** are enab
1cc0: 6c 65 64 20 61 6e 64 20 53 51 4c 69 74 65 20 69  led and SQLite i
1cd0: 73 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 57  s threadsafe.  W
1ce0: 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  hen the.** [SQLI
1cf0: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d  TE_THREADSAFE] m
1d00: 61 63 72 6f 20 69 73 20 30 2c 20 0a 2a 2a 20 74  acro is 0, .** t
1d10: 68 65 20 6d 75 74 65 78 65 73 20 61 72 65 20 6f  he mutexes are o
1d20: 6d 69 74 74 65 64 2e 20 20 57 69 74 68 6f 75 74  mitted.  Without
1d30: 20 74 68 65 20 6d 75 74 65 78 65 73 2c 20 69 74   the mutexes, it
1d40: 20 69 73 20 6e 6f 74 20 73 61 66 65 0a 2a 2a 20   is not safe.** 
1d50: 74 6f 20 75 73 65 20 53 51 4c 69 74 65 20 63 6f  to use SQLite co
1d60: 6e 63 75 72 72 65 6e 74 6c 79 20 66 72 6f 6d 20  ncurrently from 
1d70: 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 74 68  more than one th
1d80: 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e 61 62  read..**.** Enab
1d90: 6c 69 6e 67 20 6d 75 74 65 78 65 73 20 69 6e 63  ling mutexes inc
1da0: 75 72 73 20 61 20 6d 65 61 73 75 72 61 62 6c 65  urs a measurable
1db0: 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 70 65 6e   performance pen
1dc0: 61 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69 66 20 73  alty..** So if s
1dd0: 70 65 65 64 20 69 73 20 6f 66 20 75 74 6d 6f 73  peed is of utmos
1de0: 74 20 69 6d 70 6f 72 74 61 6e 63 65 2c 20 69 74  t importance, it
1df0: 20 6d 61 6b 65 73 20 73 65 6e 73 65 20 74 6f 20   makes sense to 
1e00: 64 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 6d  disable.** the m
1e10: 75 74 65 78 65 73 2e 20 20 42 75 74 20 66 6f 72  utexes.  But for
1e20: 20 6d 61 78 69 6d 75 6d 20 73 61 66 65 74 79 2c   maximum safety,
1e30: 20 6d 75 74 65 78 65 73 20 73 68 6f 75 6c 64 20   mutexes should 
1e40: 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 5e  be enabled..** ^
1e50: 54 68 65 20 64 65 66 61 75 6c 74 20 62 65 68 61  The default beha
1e60: 76 69 6f 72 20 69 73 20 66 6f 72 20 6d 75 74 65  vior is for mute
1e70: 78 65 73 20 74 6f 20 62 65 20 65 6e 61 62 6c 65  xes to be enable
1e80: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e  d..**.** This in
1e90: 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75  terface can be u
1ea0: 73 65 64 20 62 79 20 61 6e 20 61 70 70 6c 69 63  sed by an applic
1eb0: 61 74 69 6f 6e 20 74 6f 20 6d 61 6b 65 20 73 75  ation to make su
1ec0: 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 76  re that the.** v
1ed0: 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65  ersion of SQLite
1ee0: 20 74 68 61 74 20 69 74 20 69 73 20 6c 69 6e 6b   that it is link
1ef0: 69 6e 67 20 61 67 61 69 6e 73 74 20 77 61 73 20  ing against was 
1f00: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
1f10: 20 74 68 65 20 64 65 73 69 72 65 64 20 73 65 74   the desired set
1f20: 74 69 6e 67 20 6f 66 20 74 68 65 20 5b 53 51 4c  ting of the [SQL
1f30: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20  ITE_THREADSAFE] 
1f40: 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  macro..**.** Thi
1f50: 73 20 69 6e 74 65 72 66 61 63 65 20 6f 6e 6c 79  s interface only
1f60: 20 72 65 70 6f 72 74 73 20 6f 6e 20 74 68 65 20   reports on the 
1f70: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 75 74  compile-time mut
1f80: 65 78 20 73 65 74 74 69 6e 67 0a 2a 2a 20 6f 66  ex setting.** of
1f90: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
1fa0: 45 41 44 53 41 46 45 5d 20 66 6c 61 67 2e 20 20  EADSAFE] flag.  
1fb0: 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
1fc0: 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 53 51  piled with.** SQ
1fd0: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
1fe0: 31 20 6f 72 20 3d 32 20 74 68 65 6e 20 6d 75 74  1 or =2 then mut
1ff0: 65 78 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64  exes are enabled
2000: 20 62 79 20 64 65 66 61 75 6c 74 20 62 75 74 0a   by default but.
2010: 2a 2a 20 63 61 6e 20 62 65 20 66 75 6c 6c 79 20  ** can be fully 
2020: 6f 72 20 70 61 72 74 69 61 6c 6c 79 20 64 69 73  or partially dis
2030: 61 62 6c 65 64 20 75 73 69 6e 67 20 61 20 63 61  abled using a ca
2040: 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ll to [sqlite3_c
2050: 6f 6e 66 69 67 28 29 5d 0a 2a 2a 20 77 69 74 68  onfig()].** with
2060: 20 74 68 65 20 76 65 72 62 73 20 5b 53 51 4c 49   the verbs [SQLI
2070: 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
2080: 54 48 52 45 41 44 5d 2c 20 5b 53 51 4c 49 54 45  THREAD], [SQLITE
2090: 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
20a0: 45 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c  EAD],.** or [SQL
20b0: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
20c0: 5d 2e 20 20 5e 28 54 68 65 20 72 65 74 75 72 6e  ].  ^(The return
20d0: 20 76 61 6c 75 65 20 6f 66 20 74 68 65 0a 2a 2a   value of the.**
20e0: 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73   sqlite3_threads
20f0: 61 66 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 73  afe() function s
2100: 68 6f 77 73 20 6f 6e 6c 79 20 74 68 65 20 63 6f  hows only the co
2110: 6d 70 69 6c 65 2d 74 69 6d 65 20 73 65 74 74 69  mpile-time setti
2120: 6e 67 20 6f 66 0a 2a 2a 20 74 68 72 65 61 64 20  ng of.** thread 
2130: 73 61 66 65 74 79 2c 20 6e 6f 74 20 61 6e 79 20  safety, not any 
2140: 72 75 6e 2d 74 69 6d 65 20 63 68 61 6e 67 65 73  run-time changes
2150: 20 74 6f 20 74 68 61 74 20 73 65 74 74 69 6e 67   to that setting
2160: 20 6d 61 64 65 20 62 79 0a 2a 2a 20 73 71 6c 69   made by.** sqli
2170: 74 65 33 5f 63 6f 6e 66 69 67 28 29 2e 20 49 6e  te3_config(). In
2180: 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
2190: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66  e return value f
21a0: 72 6f 6d 20 73 71 6c 69 74 65 33 5f 74 68 72 65  rom sqlite3_thre
21b0: 61 64 73 61 66 65 28 29 0a 2a 2a 20 69 73 20 75  adsafe().** is u
21c0: 6e 63 68 61 6e 67 65 64 20 62 79 20 63 61 6c 6c  nchanged by call
21d0: 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e  s to sqlite3_con
21e0: 66 69 67 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53  fig().)^.**.** S
21f0: 65 65 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e  ee the [threadin
2200: 67 20 6d 6f 64 65 5d 20 64 6f 63 75 6d 65 6e 74  g mode] document
2210: 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69  ation for additi
2220: 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
2230: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
2240: 5f 74 68 72 65 61 64 73 61 66 65 28 76 6f 69 64  _threadsafe(void
2250: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2260: 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e  EF: Database Con
2270: 6e 65 63 74 69 6f 6e 20 48 61 6e 64 6c 65 0a 2a  nection Handle.*
2280: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 64 61 74  * KEYWORDS: {dat
2290: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
22a0: 7d 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  } {database conn
22b0: 65 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45  ections}.**.** E
22c0: 61 63 68 20 6f 70 65 6e 20 53 51 4c 69 74 65 20  ach open SQLite 
22d0: 64 61 74 61 62 61 73 65 20 69 73 20 72 65 70 72  database is repr
22e0: 65 73 65 6e 74 65 64 20 62 79 20 61 20 70 6f 69  esented by a poi
22f0: 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61  nter to an insta
2300: 6e 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6f 70  nce of.** the op
2310: 61 71 75 65 20 73 74 72 75 63 74 75 72 65 20 6e  aque structure n
2320: 61 6d 65 64 20 22 73 71 6c 69 74 65 33 22 2e 20  amed "sqlite3". 
2330: 20 49 74 20 69 73 20 75 73 65 66 75 6c 20 74 6f   It is useful to
2340: 20 74 68 69 6e 6b 20 6f 66 20 61 6e 20 73 71 6c   think of an sql
2350: 69 74 65 33 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  ite3.** pointer 
2360: 61 73 20 61 6e 20 6f 62 6a 65 63 74 2e 20 20 54  as an object.  T
2370: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  he [sqlite3_open
2380: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
2390: 65 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20  en16()], and.** 
23a0: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
23b0: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 61  ()] interfaces a
23c0: 72 65 20 69 74 73 20 63 6f 6e 73 74 72 75 63 74  re its construct
23d0: 6f 72 73 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65  ors, and [sqlite
23e0: 33 5f 63 6c 6f 73 65 28 29 5d 0a 2a 2a 20 61 6e  3_close()].** an
23f0: 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  d [sqlite3_close
2400: 5f 76 32 28 29 5d 20 61 72 65 20 69 74 73 20 64  _v2()] are its d
2410: 65 73 74 72 75 63 74 6f 72 73 2e 20 20 54 68 65  estructors.  The
2420: 72 65 20 61 72 65 20 6d 61 6e 79 20 6f 74 68 65  re are many othe
2430: 72 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  r.** interfaces 
2440: 28 73 75 63 68 20 61 73 0a 2a 2a 20 5b 73 71 6c  (such as.** [sql
2450: 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
2460: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  )], [sqlite3_cre
2470: 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 2c  ate_function()],
2480: 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
2490: 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d  _busy_timeout()]
24a0: 20 74 6f 20 6e 61 6d 65 20 62 75 74 20 74 68 72   to name but thr
24b0: 65 65 29 20 74 68 61 74 20 61 72 65 20 6d 65 74  ee) that are met
24c0: 68 6f 64 73 20 6f 6e 20 61 6e 0a 2a 2a 20 73 71  hods on an.** sq
24d0: 6c 69 74 65 33 20 6f 62 6a 65 63 74 2e 0a 2a 2f  lite3 object..*/
24e0: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
24f0: 73 71 6c 69 74 65 33 20 73 71 6c 69 74 65 33 3b  sqlite3 sqlite3;
2500: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2510: 3a 20 36 34 2d 42 69 74 20 49 6e 74 65 67 65 72  : 64-Bit Integer
2520: 20 54 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52   Types.** KEYWOR
2530: 44 53 3a 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  DS: sqlite_int64
2540: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 0a 2a   sqlite_uint64.*
2550: 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65  *.** Because the
2560: 72 65 20 69 73 20 6e 6f 20 63 72 6f 73 73 2d 70  re is no cross-p
2570: 6c 61 74 66 6f 72 6d 20 77 61 79 20 74 6f 20 73  latform way to s
2580: 70 65 63 69 66 79 20 36 34 2d 62 69 74 20 69 6e  pecify 64-bit in
2590: 74 65 67 65 72 20 74 79 70 65 73 0a 2a 2a 20 53  teger types.** S
25a0: 51 4c 69 74 65 20 69 6e 63 6c 75 64 65 73 20 74  QLite includes t
25b0: 79 70 65 64 65 66 73 20 66 6f 72 20 36 34 2d 62  ypedefs for 64-b
25c0: 69 74 20 73 69 67 6e 65 64 20 61 6e 64 20 75 6e  it signed and un
25d0: 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 73 2e  signed integers.
25e0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
25f0: 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c  e3_int64 and sql
2600: 69 74 65 33 5f 75 69 6e 74 36 34 20 61 72 65 20  ite3_uint64 are 
2610: 74 68 65 20 70 72 65 66 65 72 72 65 64 20 74 79  the preferred ty
2620: 70 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 2e 0a  pe definitions..
2630: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 5f 69 6e  ** The sqlite_in
2640: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 75  t64 and sqlite_u
2650: 69 6e 74 36 34 20 74 79 70 65 73 20 61 72 65 20  int64 types are 
2660: 73 75 70 70 6f 72 74 65 64 20 66 6f 72 20 62 61  supported for ba
2670: 63 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d 70 61  ckwards.** compa
2680: 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e 0a 2a  tibility only..*
2690: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
26a0: 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69  3_int64 and sqli
26b0: 74 65 5f 69 6e 74 36 34 20 74 79 70 65 73 20 63  te_int64 types c
26c0: 61 6e 20 73 74 6f 72 65 20 69 6e 74 65 67 65 72  an store integer
26d0: 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65   values.** betwe
26e0: 65 6e 20 2d 39 32 32 33 33 37 32 30 33 36 38 35  en -922337203685
26f0: 34 37 37 35 38 30 38 20 61 6e 64 20 2b 39 32 32  4775808 and +922
2700: 33 33 37 32 30 33 36 38 35 34 37 37 35 38 30 37  3372036854775807
2710: 20 69 6e 63 6c 75 73 69 76 65 2e 20 20 5e 54 68   inclusive.  ^Th
2720: 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 69 6e  e.** sqlite3_uin
2730: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 75  t64 and sqlite_u
2740: 69 6e 74 36 34 20 74 79 70 65 73 20 63 61 6e 20  int64 types can 
2750: 73 74 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61  store integer va
2760: 6c 75 65 73 20 0a 2a 2a 20 62 65 74 77 65 65 6e  lues .** between
2770: 20 30 20 61 6e 64 20 2b 31 38 34 34 36 37 34 34   0 and +18446744
2780: 30 37 33 37 30 39 35 35 31 36 31 35 20 69 6e 63  073709551615 inc
2790: 6c 75 73 69 76 65 2e 0a 2a 2f 0a 23 69 66 64 65  lusive..*/.#ifde
27a0: 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54  f SQLITE_INT64_T
27b0: 59 50 45 0a 20 20 74 79 70 65 64 65 66 20 53 51  YPE.  typedef SQ
27c0: 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20  LITE_INT64_TYPE 
27d0: 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20  sqlite_int64;.  
27e0: 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64  typedef unsigned
27f0: 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59   SQLITE_INT64_TY
2800: 50 45 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  PE sqlite_uint64
2810: 3b 0a 23 65 6c 69 66 20 64 65 66 69 6e 65 64 28  ;.#elif defined(
2820: 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64 65 66  _MSC_VER) || def
2830: 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f  ined(__BORLANDC_
2840: 5f 29 0a 20 20 74 79 70 65 64 65 66 20 5f 5f 69  _).  typedef __i
2850: 6e 74 36 34 20 73 71 6c 69 74 65 5f 69 6e 74 36  nt64 sqlite_int6
2860: 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73  4;.  typedef uns
2870: 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20 73 71  igned __int64 sq
2880: 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c  lite_uint64;.#el
2890: 73 65 0a 20 20 74 79 70 65 64 65 66 20 6c 6f 6e  se.  typedef lon
28a0: 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74  g long int sqlit
28b0: 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64  e_int64;.  typed
28c0: 65 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f 6e 67  ef unsigned long
28d0: 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65   long int sqlite
28e0: 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69 66 0a  _uint64;.#endif.
28f0: 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f 69  typedef sqlite_i
2900: 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 69 6e 74  nt64 sqlite3_int
2910: 36 34 3b 0a 74 79 70 65 64 65 66 20 73 71 6c 69  64;.typedef sqli
2920: 74 65 5f 75 69 6e 74 36 34 20 73 71 6c 69 74 65  te_uint64 sqlite
2930: 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a  3_uint64;../*.**
2940: 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20 66 6f   If compiling fo
2950: 72 20 61 20 70 72 6f 63 65 73 73 6f 72 20 74 68  r a processor th
2960: 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74 69 6e  at lacks floatin
2970: 67 20 70 6f 69 6e 74 20 73 75 70 70 6f 72 74 2c  g point support,
2980: 0a 2a 2a 20 73 75 62 73 74 69 74 75 74 65 20 69  .** substitute i
2990: 6e 74 65 67 65 72 20 66 6f 72 20 66 6c 6f 61 74  nteger for float
29a0: 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69  ing-point..*/.#i
29b0: 66 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54  fdef SQLITE_OMIT
29c0: 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a  _FLOATING_POINT.
29d0: 23 20 64 65 66 69 6e 65 20 64 6f 75 62 6c 65 20  # define double 
29e0: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a 23 65  sqlite3_int64.#e
29f0: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ndif../*.** CAPI
2a00: 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20 41 20  3REF: Closing A 
2a10: 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
2a20: 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ion.**.** ^The s
2a30: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 61  qlite3_close() a
2a40: 6e 64 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  nd sqlite3_close
2a50: 5f 76 32 28 29 20 72 6f 75 74 69 6e 65 73 20 61  _v2() routines a
2a60: 72 65 20 64 65 73 74 72 75 63 74 6f 72 73 0a 2a  re destructors.*
2a70: 2a 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74  * for the [sqlit
2a80: 65 33 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e  e3] object..** ^
2a90: 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  Calls to sqlite3
2aa0: 5f 63 6c 6f 73 65 28 29 20 61 6e 64 20 73 71 6c  _close() and sql
2ab0: 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20  ite3_close_v2() 
2ac0: 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b  return SQLITE_OK
2ad0: 20 69 66 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69   if.** the [sqli
2ae0: 74 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 73  te3] object is s
2af0: 75 63 63 65 73 73 66 75 6c 6c 79 20 64 65 73 74  uccessfully dest
2b00: 72 6f 79 65 64 20 61 6e 64 20 61 6c 6c 20 61 73  royed and all as
2b10: 73 6f 63 69 61 74 65 64 0a 2a 2a 20 72 65 73 6f  sociated.** reso
2b20: 75 72 63 65 73 20 61 72 65 20 64 65 61 6c 6c 6f  urces are deallo
2b30: 63 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  cated..**.** ^If
2b40: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
2b50: 6e 6e 65 63 74 69 6f 6e 20 69 73 20 61 73 73 6f  nnection is asso
2b60: 63 69 61 74 65 64 20 77 69 74 68 20 75 6e 66 69  ciated with unfi
2b70: 6e 61 6c 69 7a 65 64 20 70 72 65 70 61 72 65 64  nalized prepared
2b80: 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 20 6f  .** statements o
2b90: 72 20 75 6e 66 69 6e 69 73 68 65 64 20 73 71 6c  r unfinished sql
2ba0: 69 74 65 33 5f 62 61 63 6b 75 70 20 6f 62 6a 65  ite3_backup obje
2bb0: 63 74 73 20 74 68 65 6e 20 73 71 6c 69 74 65 33  cts then sqlite3
2bc0: 5f 63 6c 6f 73 65 28 29 0a 2a 2a 20 77 69 6c 6c  _close().** will
2bd0: 20 6c 65 61 76 65 20 74 68 65 20 64 61 74 61 62   leave the datab
2be0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f  ase connection o
2bf0: 70 65 6e 20 61 6e 64 20 72 65 74 75 72 6e 20 5b  pen and return [
2c00: 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a  SQLITE_BUSY]..**
2c10: 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6c 6f   ^If sqlite3_clo
2c20: 73 65 5f 76 32 28 29 20 69 73 20 63 61 6c 6c 65  se_v2() is calle
2c30: 64 20 77 69 74 68 20 75 6e 66 69 6e 61 6c 69 7a  d with unfinaliz
2c40: 65 64 20 70 72 65 70 61 72 65 64 20 73 74 61 74  ed prepared stat
2c50: 65 6d 65 6e 74 73 0a 2a 2a 20 61 6e 64 20 75 6e  ements.** and un
2c60: 66 69 6e 69 73 68 65 64 20 73 71 6c 69 74 65 33  finished sqlite3
2c70: 5f 62 61 63 6b 75 70 73 2c 20 74 68 65 6e 20 74  _backups, then t
2c80: 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
2c90: 65 63 74 69 6f 6e 20 62 65 63 6f 6d 65 73 0a 2a  ection becomes.*
2ca0: 2a 20 61 6e 20 75 6e 75 73 61 62 6c 65 20 22 7a  * an unusable "z
2cb0: 6f 6d 62 69 65 22 20 77 68 69 63 68 20 77 69 6c  ombie" which wil
2cc0: 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  l automatically 
2cd0: 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 77  be deallocated w
2ce0: 68 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 73 74 20  hen the.** last 
2cf0: 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2d00: 6e 74 20 69 73 20 66 69 6e 61 6c 69 7a 65 64 20  nt is finalized 
2d10: 6f 72 20 74 68 65 20 6c 61 73 74 20 73 71 6c 69  or the last sqli
2d20: 74 65 33 5f 62 61 63 6b 75 70 20 69 73 0a 2a 2a  te3_backup is.**
2d30: 20 66 69 6e 69 73 68 65 64 2e 20 20 54 68 65 20   finished.  The 
2d40: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32  sqlite3_close_v2
2d50: 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
2d60: 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65  intended for use
2d70: 20 77 69 74 68 0a 2a 2a 20 68 6f 73 74 20 6c 61   with.** host la
2d80: 6e 67 75 61 67 65 73 20 74 68 61 74 20 61 72 65  nguages that are
2d90: 20 67 61 72 62 61 67 65 20 63 6f 6c 6c 65 63 74   garbage collect
2da0: 65 64 2c 20 61 6e 64 20 77 68 65 72 65 20 74 68  ed, and where th
2db0: 65 20 6f 72 64 65 72 20 69 6e 20 77 68 69 63 68  e order in which
2dc0: 0a 2a 2a 20 64 65 73 74 72 75 63 74 6f 72 73 20  .** destructors 
2dd0: 61 72 65 20 63 61 6c 6c 65 64 20 69 73 20 61 72  are called is ar
2de0: 62 69 74 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 41  bitrary..**.** A
2df0: 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75  pplications shou
2e00: 6c 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ld [sqlite3_fina
2e10: 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 5d  lize | finalize]
2e20: 20 61 6c 6c 20 5b 70 72 65 70 61 72 65 64 20 73   all [prepared s
2e30: 74 61 74 65 6d 65 6e 74 73 5d 2c 0a 2a 2a 20 5b  tatements],.** [
2e40: 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f  sqlite3_blob_clo
2e50: 73 65 20 7c 20 63 6c 6f 73 65 5d 20 61 6c 6c 20  se | close] all 
2e60: 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20  [BLOB handles], 
2e70: 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  and .** [sqlite3
2e80: 5f 62 61 63 6b 75 70 5f 66 69 6e 69 73 68 20 7c  _backup_finish |
2e90: 20 66 69 6e 69 73 68 5d 20 61 6c 6c 20 5b 73 71   finish] all [sq
2ea0: 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62  lite3_backup] ob
2eb0: 6a 65 63 74 73 20 61 73 73 6f 63 69 61 74 65 64  jects associated
2ec0: 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 73 71  .** with the [sq
2ed0: 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 70 72  lite3] object pr
2ee0: 69 6f 72 20 74 6f 20 61 74 74 65 6d 70 74 69 6e  ior to attemptin
2ef0: 67 20 74 6f 20 63 6c 6f 73 65 20 74 68 65 20 6f  g to close the o
2f00: 62 6a 65 63 74 2e 20 20 5e 49 66 0a 2a 2a 20 73  bject.  ^If.** s
2f10: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 69  qlite3_close() i
2f20: 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 64  s called on a [d
2f30: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2f40: 6f 6e 5d 20 74 68 61 74 20 73 74 69 6c 6c 20 68  on] that still h
2f50: 61 73 0a 2a 2a 20 6f 75 74 73 74 61 6e 64 69 6e  as.** outstandin
2f60: 67 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  g [prepared stat
2f70: 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68  ements], [BLOB h
2f80: 61 6e 64 6c 65 73 5d 2c 20 61 6e 64 2f 6f 72 0a  andles], and/or.
2f90: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b  ** [sqlite3_back
2fa0: 75 70 5d 20 6f 62 6a 65 63 74 73 20 74 68 65 6e  up] objects then
2fb0: 20 69 74 20 72 65 74 75 72 6e 73 20 53 51 4c 49   it returns SQLI
2fc0: 54 45 5f 4f 4b 20 62 75 74 20 74 68 65 20 64 65  TE_OK but the de
2fd0: 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66  allocation.** of
2fe0: 20 72 65 73 6f 75 72 63 65 73 20 69 73 20 64 65   resources is de
2ff0: 66 65 72 72 65 64 20 75 6e 74 69 6c 20 61 6c 6c  ferred until all
3000: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
3010: 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68 61  ments], [BLOB ha
3020: 6e 64 6c 65 73 5d 2c 0a 2a 2a 20 61 6e 64 20 5b  ndles],.** and [
3030: 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d 20  sqlite3_backup] 
3040: 6f 62 6a 65 63 74 73 20 61 72 65 20 61 6c 73 6f  objects are also
3050: 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a 0a 2a   destroyed..**.*
3060: 2a 20 5e 49 66 20 61 6e 20 5b 73 71 6c 69 74 65  * ^If an [sqlite
3070: 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 64 65 73  3] object is des
3080: 74 72 6f 79 65 64 20 77 68 69 6c 65 20 61 20 74  troyed while a t
3090: 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 6f 70  ransaction is op
30a0: 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72 61 6e 73  en,.** the trans
30b0: 61 63 74 69 6f 6e 20 69 73 20 61 75 74 6f 6d 61  action is automa
30c0: 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62  tically rolled b
30d0: 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43  ack..**.** The C
30e0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73   parameter to [s
30f0: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d  qlite3_close(C)]
3100: 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c   and [sqlite3_cl
3110: 6f 73 65 5f 76 32 28 43 29 5d 0a 2a 2a 20 6d 75  ose_v2(C)].** mu
3120: 73 74 20 62 65 20 65 69 74 68 65 72 20 61 20 4e  st be either a N
3130: 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 6f  ULL.** pointer o
3140: 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f  r an [sqlite3] o
3150: 62 6a 65 63 74 20 70 6f 69 6e 74 65 72 20 6f 62  bject pointer ob
3160: 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b  tained.** from [
3170: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
3180: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
3190: 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  ()], or.** [sqli
31a0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20  te3_open_v2()], 
31b0: 61 6e 64 20 6e 6f 74 20 70 72 65 76 69 6f 75 73  and not previous
31c0: 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 5e 43  ly closed..** ^C
31d0: 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 63  alling sqlite3_c
31e0: 6c 6f 73 65 28 29 20 6f 72 20 73 71 6c 69 74 65  lose() or sqlite
31f0: 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 77 69 74  3_close_v2() wit
3200: 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  h a NULL pointer
3210: 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73 20  .** argument is 
3220: 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70  a harmless no-op
3230: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
3240: 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65 33 2a 29  _close(sqlite3*)
3250: 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c  ;.int sqlite3_cl
3260: 6f 73 65 5f 76 32 28 73 71 6c 69 74 65 33 2a 29  ose_v2(sqlite3*)
3270: 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74 79 70  ;../*.** The typ
3280: 65 20 66 6f 72 20 61 20 63 61 6c 6c 62 61 63 6b  e for a callback
3290: 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68   function..** Th
32a0: 69 73 20 69 73 20 6c 65 67 61 63 79 20 61 6e 64  is is legacy and
32b0: 20 64 65 70 72 65 63 61 74 65 64 2e 20 20 49 74   deprecated.  It
32c0: 20 69 73 20 69 6e 63 6c 75 64 65 64 20 66 6f 72   is included for
32d0: 20 68 69 73 74 6f 72 69 63 61 6c 0a 2a 2a 20 63   historical.** c
32e0: 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 61 6e 64  ompatibility and
32f0: 20 69 73 20 6e 6f 74 20 64 6f 63 75 6d 65 6e 74   is not document
3300: 65 64 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 69  ed..*/.typedef i
3310: 6e 74 20 28 2a 73 71 6c 69 74 65 33 5f 63 61 6c  nt (*sqlite3_cal
3320: 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74  lback)(void*,int
3330: 2c 63 68 61 72 2a 2a 2c 20 63 68 61 72 2a 2a 29  ,char**, char**)
3340: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
3350: 46 3a 20 4f 6e 65 2d 53 74 65 70 20 51 75 65 72  F: One-Step Quer
3360: 79 20 45 78 65 63 75 74 69 6f 6e 20 49 6e 74 65  y Execution Inte
3370: 72 66 61 63 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20  rface.**.** The 
3380: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69  sqlite3_exec() i
3390: 6e 74 65 72 66 61 63 65 20 69 73 20 61 20 63 6f  nterface is a co
33a0: 6e 76 65 6e 69 65 6e 63 65 20 77 72 61 70 70 65  nvenience wrappe
33b0: 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c  r around.** [sql
33c0: 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
33d0: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  )], [sqlite3_ste
33e0: 70 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74  p()], and [sqlit
33f0: 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2c 0a  e3_finalize()],.
3400: 2a 2a 20 74 68 61 74 20 61 6c 6c 6f 77 73 20 61  ** that allows a
3410: 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f  n application to
3420: 20 72 75 6e 20 6d 75 6c 74 69 70 6c 65 20 73 74   run multiple st
3430: 61 74 65 6d 65 6e 74 73 20 6f 66 20 53 51 4c 0a  atements of SQL.
3440: 2a 2a 20 77 69 74 68 6f 75 74 20 68 61 76 69 6e  ** without havin
3450: 67 20 74 6f 20 75 73 65 20 61 20 6c 6f 74 20 6f  g to use a lot o
3460: 66 20 43 20 63 6f 64 65 2e 20 0a 2a 2a 0a 2a 2a  f C code. .**.**
3470: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78   ^The sqlite3_ex
3480: 65 63 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  ec() interface r
3490: 75 6e 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65  uns zero or more
34a0: 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2c 0a   UTF-8 encoded,.
34b0: 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70  ** semicolon-sep
34c0: 61 72 61 74 65 20 53 51 4c 20 73 74 61 74 65 6d  arate SQL statem
34d0: 65 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74 6f  ents passed into
34e0: 20 69 74 73 20 32 6e 64 20 61 72 67 75 6d 65 6e   its 2nd argumen
34f0: 74 2c 0a 2a 2a 20 69 6e 20 74 68 65 20 63 6f 6e  t,.** in the con
3500: 74 65 78 74 20 6f 66 20 74 68 65 20 5b 64 61 74  text of the [dat
3510: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
3520: 5d 20 70 61 73 73 65 64 20 69 6e 20 61 73 20 69  ] passed in as i
3530: 74 73 20 31 73 74 0a 2a 2a 20 61 72 67 75 6d 65  ts 1st.** argume
3540: 6e 74 2e 20 20 5e 49 66 20 74 68 65 20 63 61 6c  nt.  ^If the cal
3550: 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6f  lback function o
3560: 66 20 74 68 65 20 33 72 64 20 61 72 67 75 6d 65  f the 3rd argume
3570: 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  nt to.** sqlite3
3580: 5f 65 78 65 63 28 29 20 69 73 20 6e 6f 74 20 4e  _exec() is not N
3590: 55 4c 4c 2c 20 74 68 65 6e 20 69 74 20 69 73 20  ULL, then it is 
35a0: 69 6e 76 6f 6b 65 64 20 66 6f 72 20 65 61 63 68  invoked for each
35b0: 20 72 65 73 75 6c 74 20 72 6f 77 0a 2a 2a 20 63   result row.** c
35c0: 6f 6d 69 6e 67 20 6f 75 74 20 6f 66 20 74 68 65  oming out of the
35d0: 20 65 76 61 6c 75 61 74 65 64 20 53 51 4c 20 73   evaluated SQL s
35e0: 74 61 74 65 6d 65 6e 74 73 2e 20 20 5e 54 68 65  tatements.  ^The
35f0: 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f   4th argument to
3600: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63  .** sqlite3_exec
3610: 28 29 20 69 73 20 72 65 6c 61 79 65 64 20 74 68  () is relayed th
3620: 72 6f 75 67 68 20 74 6f 20 74 68 65 20 31 73 74  rough to the 1st
3630: 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 65 61 63   argument of eac
3640: 68 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 6e  h.** callback in
3650: 76 6f 63 61 74 69 6f 6e 2e 20 20 5e 49 66 20 74  vocation.  ^If t
3660: 68 65 20 63 61 6c 6c 62 61 63 6b 20 70 6f 69 6e  he callback poin
3670: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65  ter to sqlite3_e
3680: 78 65 63 28 29 0a 2a 2a 20 69 73 20 4e 55 4c 4c  xec().** is NULL
3690: 2c 20 74 68 65 6e 20 6e 6f 20 63 61 6c 6c 62 61  , then no callba
36a0: 63 6b 20 69 73 20 65 76 65 72 20 69 6e 76 6f 6b  ck is ever invok
36b0: 65 64 20 61 6e 64 20 72 65 73 75 6c 74 20 72 6f  ed and result ro
36c0: 77 73 20 61 72 65 0a 2a 2a 20 69 67 6e 6f 72 65  ws are.** ignore
36d0: 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20  d..**.** ^If an 
36e0: 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68 69  error occurs whi
36f0: 6c 65 20 65 76 61 6c 75 61 74 69 6e 67 20 74 68  le evaluating th
3700: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  e SQL statements
3710: 20 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20   passed into.** 
3720: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 2c 20  sqlite3_exec(), 
3730: 74 68 65 6e 20 65 78 65 63 75 74 69 6f 6e 20 6f  then execution o
3740: 66 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74  f the current st
3750: 61 74 65 6d 65 6e 74 20 73 74 6f 70 73 20 61 6e  atement stops an
3760: 64 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20  d.** subsequent 
3770: 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 73  statements are s
3780: 6b 69 70 70 65 64 2e 20 20 5e 49 66 20 74 68 65  kipped.  ^If the
3790: 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   5th parameter t
37a0: 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  o sqlite3_exec()
37b0: 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20  .** is not NULL 
37c0: 74 68 65 6e 20 61 6e 79 20 65 72 72 6f 72 20 6d  then any error m
37d0: 65 73 73 61 67 65 20 69 73 20 77 72 69 74 74 65  essage is writte
37e0: 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62  n into memory ob
37f0: 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b  tained.** from [
3800: 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
3810: 5d 20 61 6e 64 20 70 61 73 73 65 64 20 62 61 63  ] and passed bac
3820: 6b 20 74 68 72 6f 75 67 68 20 74 68 65 20 35 74  k through the 5t
3830: 68 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20  h parameter..** 
3840: 54 6f 20 61 76 6f 69 64 20 6d 65 6d 6f 72 79 20  To avoid memory 
3850: 6c 65 61 6b 73 2c 20 74 68 65 20 61 70 70 6c 69  leaks, the appli
3860: 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 69 6e  cation should in
3870: 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66 72  voke [sqlite3_fr
3880: 65 65 28 29 5d 0a 2a 2a 20 6f 6e 20 65 72 72 6f  ee()].** on erro
3890: 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67  r message string
38a0: 73 20 72 65 74 75 72 6e 65 64 20 74 68 72 6f 75  s returned throu
38b0: 67 68 20 74 68 65 20 35 74 68 20 70 61 72 61 6d  gh the 5th param
38c0: 65 74 65 72 20 6f 66 0a 2a 2a 20 6f 66 20 73 71  eter of.** of sq
38d0: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 61 66 74  lite3_exec() aft
38e0: 65 72 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73  er the error mes
38f0: 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 6e  sage string is n
3900: 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65 64 2e  o longer needed.
3910: 0a 2a 2a 20 5e 49 66 20 74 68 65 20 35 74 68 20  .** ^If the 5th 
3920: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
3930: 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 6e  ite3_exec() is n
3940: 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 6e 6f 20 65  ot NULL and no e
3950: 72 72 6f 72 73 0a 2a 2a 20 6f 63 63 75 72 2c 20  rrors.** occur, 
3960: 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 65 78 65  then sqlite3_exe
3970: 63 28 29 20 73 65 74 73 20 74 68 65 20 70 6f 69  c() sets the poi
3980: 6e 74 65 72 20 69 6e 20 69 74 73 20 35 74 68 20  nter in its 5th 
3990: 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
39a0: 4e 55 4c 4c 20 62 65 66 6f 72 65 20 72 65 74 75  NULL before retu
39b0: 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  rning..**.** ^If
39c0: 20 61 6e 20 73 71 6c 69 74 65 33 5f 65 78 65 63   an sqlite3_exec
39d0: 28 29 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  () callback retu
39e0: 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68  rns non-zero, th
39f0: 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  e sqlite3_exec()
3a00: 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75  .** routine retu
3a10: 72 6e 73 20 53 51 4c 49 54 45 5f 41 42 4f 52 54  rns SQLITE_ABORT
3a20: 20 77 69 74 68 6f 75 74 20 69 6e 76 6f 6b 69 6e   without invokin
3a30: 67 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61  g the callback a
3a40: 67 61 69 6e 20 61 6e 64 0a 2a 2a 20 77 69 74 68  gain and.** with
3a50: 6f 75 74 20 72 75 6e 6e 69 6e 67 20 61 6e 79 20  out running any 
3a60: 73 75 62 73 65 71 75 65 6e 74 20 53 51 4c 20 73  subsequent SQL s
3a70: 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a  tatements..**.**
3a80: 20 5e 54 68 65 20 32 6e 64 20 61 72 67 75 6d 65   ^The 2nd argume
3a90: 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  nt to the sqlite
3aa0: 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63  3_exec() callbac
3ab0: 6b 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 68  k function is th
3ac0: 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63  e.** number of c
3ad0: 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65  olumns in the re
3ae0: 73 75 6c 74 2e 20 20 5e 54 68 65 20 33 72 64 20  sult.  ^The 3rd 
3af0: 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
3b00: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a  sqlite3_exec().*
3b10: 2a 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e  * callback is an
3b20: 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65   array of pointe
3b30: 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 6f 62  rs to strings ob
3b40: 74 61 69 6e 65 64 20 61 73 20 69 66 20 66 72 6f  tained as if fro
3b50: 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  m.** [sqlite3_co
3b60: 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 6f 6e  lumn_text()], on
3b70: 65 20 66 6f 72 20 65 61 63 68 20 63 6f 6c 75 6d  e for each colum
3b80: 6e 2e 20 20 5e 49 66 20 61 6e 20 65 6c 65 6d 65  n.  ^If an eleme
3b90: 6e 74 20 6f 66 20 61 0a 2a 2a 20 72 65 73 75 6c  nt of a.** resul
3ba0: 74 20 72 6f 77 20 69 73 20 4e 55 4c 4c 20 74 68  t row is NULL th
3bb0: 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  en the correspon
3bc0: 64 69 6e 67 20 73 74 72 69 6e 67 20 70 6f 69 6e  ding string poin
3bd0: 74 65 72 20 66 6f 72 20 74 68 65 0a 2a 2a 20 73  ter for the.** s
3be0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61  qlite3_exec() ca
3bf0: 6c 6c 62 61 63 6b 20 69 73 20 61 20 4e 55 4c 4c  llback is a NULL
3c00: 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20   pointer.  ^The 
3c10: 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  4th argument to 
3c20: 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65  the.** sqlite3_e
3c30: 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 69  xec() callback i
3c40: 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f  s an array of po
3c50: 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67  inters to string
3c60: 73 20 77 68 65 72 65 20 65 61 63 68 0a 2a 2a 20  s where each.** 
3c70: 65 6e 74 72 79 20 72 65 70 72 65 73 65 6e 74 73  entry represents
3c80: 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 63 6f 72   the name of cor
3c90: 72 65 73 70 6f 6e 64 69 6e 67 20 72 65 73 75 6c  responding resul
3ca0: 74 20 63 6f 6c 75 6d 6e 20 61 73 20 6f 62 74 61  t column as obta
3cb0: 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71  ined.** from [sq
3cc0: 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
3cd0: 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  e()]..**.** ^If 
3ce0: 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
3cf0: 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65  r to sqlite3_exe
3d00: 63 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  c() is a NULL po
3d10: 69 6e 74 65 72 2c 20 61 20 70 6f 69 6e 74 65 72  inter, a pointer
3d20: 0a 2a 2a 20 74 6f 20 61 6e 20 65 6d 70 74 79 20  .** to an empty 
3d30: 73 74 72 69 6e 67 2c 20 6f 72 20 61 20 70 6f 69  string, or a poi
3d40: 6e 74 65 72 20 74 68 61 74 20 63 6f 6e 74 61 69  nter that contai
3d50: 6e 73 20 6f 6e 6c 79 20 77 68 69 74 65 73 70 61  ns only whitespa
3d60: 63 65 20 61 6e 64 2f 6f 72 20 0a 2a 2a 20 53 51  ce and/or .** SQ
3d70: 4c 20 63 6f 6d 6d 65 6e 74 73 2c 20 74 68 65 6e  L comments, then
3d80: 20 6e 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   no SQL statemen
3d90: 74 73 20 61 72 65 20 65 76 61 6c 75 61 74 65 64  ts are evaluated
3da0: 20 61 6e 64 20 74 68 65 20 64 61 74 61 62 61 73   and the databas
3db0: 65 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e  e.** is not chan
3dc0: 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 73 74 72  ged..**.** Restr
3dd0: 69 63 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20 3c  ictions:.**.** <
3de0: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20  ul>.** <li> The 
3df0: 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
3e00: 20 69 6e 73 75 72 65 20 74 68 61 74 20 74 68 65   insure that the
3e10: 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 20 74   1st parameter t
3e20: 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  o sqlite3_exec()
3e30: 0a 2a 2a 20 20 20 20 20 20 69 73 20 61 20 76 61  .**      is a va
3e40: 6c 69 64 20 61 6e 64 20 6f 70 65 6e 20 5b 64 61  lid and open [da
3e50: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
3e60: 6e 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20  n]..** <li> The 
3e70: 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
3e80: 20 6e 6f 74 20 63 6c 6f 73 65 20 5b 64 61 74 61   not close [data
3e90: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
3ea0: 20 73 70 65 63 69 66 69 65 64 20 62 79 0a 2a 2a   specified by.**
3eb0: 20 20 20 20 20 20 74 68 65 20 31 73 74 20 70 61        the 1st pa
3ec0: 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
3ed0: 65 33 5f 65 78 65 63 28 29 20 77 68 69 6c 65 20  e3_exec() while 
3ee0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69  sqlite3_exec() i
3ef0: 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 6c  s running..** <l
3f00: 69 3e 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  i> The applicati
3f10: 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 6d 6f 64 69  on must not modi
3f20: 66 79 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  fy the SQL state
3f30: 6d 65 6e 74 20 74 65 78 74 20 70 61 73 73 65 64  ment text passed
3f40: 20 69 6e 74 6f 0a 2a 2a 20 20 20 20 20 20 74 68   into.**      th
3f50: 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  e 2nd parameter 
3f60: 6f 66 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  of sqlite3_exec(
3f70: 29 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f  ) while sqlite3_
3f80: 65 78 65 63 28 29 20 69 73 20 72 75 6e 6e 69 6e  exec() is runnin
3f90: 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 69  g..** </ul>.*/.i
3fa0: 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  nt sqlite3_exec(
3fb0: 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 20 20 20  .  sqlite3*,    
3fc0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3fd0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
3fe0: 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73   An open databas
3ff0: 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
4000: 72 20 2a 73 71 6c 2c 20 20 20 20 20 20 20 20 20  r *sql,         
4010: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4020: 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65    /* SQL to be e
4030: 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 69 6e  valuated */.  in
4040: 74 20 28 2a 63 61 6c 6c 62 61 63 6b 29 28 76 6f  t (*callback)(vo
4050: 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 63  id*,int,char**,c
4060: 68 61 72 2a 2a 29 2c 20 20 2f 2a 20 43 61 6c 6c  har**),  /* Call
4070: 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2a 2f  back function */
4080: 0a 20 20 76 6f 69 64 20 2a 2c 20 20 20 20 20 20  .  void *,      
4090: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
40a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
40b0: 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f   1st argument to
40c0: 20 63 61 6c 6c 62 61 63 6b 20 2a 2f 0a 20 20 63   callback */.  c
40d0: 68 61 72 20 2a 2a 65 72 72 6d 73 67 20 20 20 20  har **errmsg    
40e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
40f0: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 45 72 72            /* Err
4100: 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68  or msg written h
4110: 65 72 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  ere */.);../*.**
4120: 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c   CAPI3REF: Resul
4130: 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f  t Codes.** KEYWO
4140: 52 44 53 3a 20 53 51 4c 49 54 45 5f 4f 4b 20 7b  RDS: SQLITE_OK {
4150: 65 72 72 6f 72 20 63 6f 64 65 7d 20 7b 65 72 72  error code} {err
4160: 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59  or codes}.** KEY
4170: 57 4f 52 44 53 3a 20 7b 72 65 73 75 6c 74 20 63  WORDS: {result c
4180: 6f 64 65 7d 20 7b 72 65 73 75 6c 74 20 63 6f 64  ode} {result cod
4190: 65 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53  es}.**.** Many S
41a0: 51 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73 20  QLite functions 
41b0: 72 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67 65  return an intege
41c0: 72 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66 72  r result code fr
41d0: 6f 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77 6e  om the set shown
41e0: 0a 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 64 65  .** here in orde
41f0: 72 20 74 6f 20 69 6e 64 69 63 61 74 65 20 73 75  r to indicate su
4200: 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72 65  ccess or failure
4210: 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72 72 6f  ..**.** New erro
4220: 72 20 63 6f 64 65 73 20 6d 61 79 20 62 65 20 61  r codes may be a
4230: 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 76  dded in future v
4240: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
4250: 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  e..**.** See als
4260: 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  o: [SQLITE_IOERR
4270: 5f 52 45 41 44 20 7c 20 65 78 74 65 6e 64 65 64  _READ | extended
4280: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 2c 0a   result codes],.
4290: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 74 61 62  ** [sqlite3_vtab
42a0: 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28 29 5d 20  _on_conflict()] 
42b0: 5b 53 51 4c 49 54 45 5f 52 4f 4c 4c 42 41 43 4b  [SQLITE_ROLLBACK
42c0: 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d   | result codes]
42d0: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
42e0: 49 54 45 5f 4f 4b 20 20 20 20 20 20 20 20 20 20  ITE_OK          
42f0: 20 30 20 20 20 2f 2a 20 53 75 63 63 65 73 73 66   0   /* Successf
4300: 75 6c 20 72 65 73 75 6c 74 20 2a 2f 0a 2f 2a 20  ul result */./* 
4310: 62 65 67 69 6e 6e 69 6e 67 2d 6f 66 2d 65 72 72  beginning-of-err
4320: 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 23 64 65 66  or-codes */.#def
4330: 69 6e 65 20 53 51 4c 49 54 45 5f 45 52 52 4f 52  ine SQLITE_ERROR
4340: 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20 53          1   /* S
4350: 51 4c 20 65 72 72 6f 72 20 6f 72 20 6d 69 73 73  QL error or miss
4360: 69 6e 67 20 64 61 74 61 62 61 73 65 20 2a 2f 0a  ing database */.
4370: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4380: 4e 54 45 52 4e 41 4c 20 20 20 20 20 32 20 20 20  NTERNAL     2   
4390: 2f 2a 20 49 6e 74 65 72 6e 61 6c 20 6c 6f 67 69  /* Internal logi
43a0: 63 20 65 72 72 6f 72 20 69 6e 20 53 51 4c 69 74  c error in SQLit
43b0: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e */.#define SQL
43c0: 49 54 45 5f 50 45 52 4d 20 20 20 20 20 20 20 20  ITE_PERM        
43d0: 20 33 20 20 20 2f 2a 20 41 63 63 65 73 73 20 70   3   /* Access p
43e0: 65 72 6d 69 73 73 69 6f 6e 20 64 65 6e 69 65 64  ermission denied
43f0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4400: 54 45 5f 41 42 4f 52 54 20 20 20 20 20 20 20 20  TE_ABORT        
4410: 34 20 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20  4   /* Callback 
4420: 72 6f 75 74 69 6e 65 20 72 65 71 75 65 73 74 65  routine requeste
4430: 64 20 61 6e 20 61 62 6f 72 74 20 2a 2f 0a 23 64  d an abort */.#d
4440: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53  efine SQLITE_BUS
4450: 59 20 20 20 20 20 20 20 20 20 35 20 20 20 2f 2a  Y         5   /*
4460: 20 54 68 65 20 64 61 74 61 62 61 73 65 20 66 69   The database fi
4470: 6c 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a  le is locked */.
4480: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
4490: 4f 43 4b 45 44 20 20 20 20 20 20 20 36 20 20 20  OCKED       6   
44a0: 2f 2a 20 41 20 74 61 62 6c 65 20 69 6e 20 74 68  /* A table in th
44b0: 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6c 6f  e database is lo
44c0: 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  cked */.#define 
44d0: 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 20 20 20  SQLITE_NOMEM    
44e0: 20 20 20 20 37 20 20 20 2f 2a 20 41 20 6d 61 6c      7   /* A mal
44f0: 6c 6f 63 28 29 20 66 61 69 6c 65 64 20 2a 2f 0a  loc() failed */.
4500: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
4510: 45 41 44 4f 4e 4c 59 20 20 20 20 20 38 20 20 20  EADONLY     8   
4520: 2f 2a 20 41 74 74 65 6d 70 74 20 74 6f 20 77 72  /* Attempt to wr
4530: 69 74 65 20 61 20 72 65 61 64 6f 6e 6c 79 20 64  ite a readonly d
4540: 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65 66 69  atabase */.#defi
4550: 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 52 52  ne SQLITE_INTERR
4560: 55 50 54 20 20 20 20 39 20 20 20 2f 2a 20 4f 70  UPT    9   /* Op
4570: 65 72 61 74 69 6f 6e 20 74 65 72 6d 69 6e 61 74  eration terminat
4580: 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e  ed by sqlite3_in
4590: 74 65 72 72 75 70 74 28 29 2a 2f 0a 23 64 65 66  terrupt()*/.#def
45a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
45b0: 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20 53         10   /* S
45c0: 6f 6d 65 20 6b 69 6e 64 20 6f 66 20 64 69 73 6b  ome kind of disk
45d0: 20 49 2f 4f 20 65 72 72 6f 72 20 6f 63 63 75 72   I/O error occur
45e0: 72 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  red */.#define S
45f0: 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 20 20  QLITE_CORRUPT   
4600: 20 20 31 31 20 20 20 2f 2a 20 54 68 65 20 64 61    11   /* The da
4610: 74 61 62 61 73 65 20 64 69 73 6b 20 69 6d 61 67  tabase disk imag
4620: 65 20 69 73 20 6d 61 6c 66 6f 72 6d 65 64 20 2a  e is malformed *
4630: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4640: 5f 4e 4f 54 46 4f 55 4e 44 20 20 20 20 31 32 20  _NOTFOUND    12 
4650: 20 20 2f 2a 20 55 6e 6b 6e 6f 77 6e 20 6f 70 63    /* Unknown opc
4660: 6f 64 65 20 69 6e 20 73 71 6c 69 74 65 33 5f 66  ode in sqlite3_f
4670: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 20 2a 2f  ile_control() */
4680: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4690: 46 55 4c 4c 20 20 20 20 20 20 20 20 31 33 20 20  FULL        13  
46a0: 20 2f 2a 20 49 6e 73 65 72 74 69 6f 6e 20 66 61   /* Insertion fa
46b0: 69 6c 65 64 20 62 65 63 61 75 73 65 20 64 61 74  iled because dat
46c0: 61 62 61 73 65 20 69 73 20 66 75 6c 6c 20 2a 2f  abase is full */
46d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
46e0: 43 41 4e 54 4f 50 45 4e 20 20 20 20 31 34 20 20  CANTOPEN    14  
46f0: 20 2f 2a 20 55 6e 61 62 6c 65 20 74 6f 20 6f 70   /* Unable to op
4700: 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
4710: 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  file */.#define 
4720: 53 51 4c 49 54 45 5f 50 52 4f 54 4f 43 4f 4c 20  SQLITE_PROTOCOL 
4730: 20 20 20 31 35 20 20 20 2f 2a 20 44 61 74 61 62     15   /* Datab
4740: 61 73 65 20 6c 6f 63 6b 20 70 72 6f 74 6f 63 6f  ase lock protoco
4750: 6c 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69  l error */.#defi
4760: 6e 65 20 53 51 4c 49 54 45 5f 45 4d 50 54 59 20  ne SQLITE_EMPTY 
4770: 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20 44 61        16   /* Da
4780: 74 61 62 61 73 65 20 69 73 20 65 6d 70 74 79 20  tabase is empty 
4790: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
47a0: 45 5f 53 43 48 45 4d 41 20 20 20 20 20 20 31 37  E_SCHEMA      17
47b0: 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61     /* The databa
47c0: 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65  se schema change
47d0: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
47e0: 49 54 45 5f 54 4f 4f 42 49 47 20 20 20 20 20 20  ITE_TOOBIG      
47f0: 31 38 20 20 20 2f 2a 20 53 74 72 69 6e 67 20 6f  18   /* String o
4800: 72 20 42 4c 4f 42 20 65 78 63 65 65 64 73 20 73  r BLOB exceeds s
4810: 69 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a 23 64 65  ize limit */.#de
4820: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
4830: 54 52 41 49 4e 54 20 20 31 39 20 20 20 2f 2a 20  TRAINT  19   /* 
4840: 41 62 6f 72 74 20 64 75 65 20 74 6f 20 63 6f 6e  Abort due to con
4850: 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f  straint violatio
4860: 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  n */.#define SQL
4870: 49 54 45 5f 4d 49 53 4d 41 54 43 48 20 20 20 20  ITE_MISMATCH    
4880: 32 30 20 20 20 2f 2a 20 44 61 74 61 20 74 79 70  20   /* Data typ
4890: 65 20 6d 69 73 6d 61 74 63 68 20 2a 2f 0a 23 64  e mismatch */.#d
48a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53  efine SQLITE_MIS
48b0: 55 53 45 20 20 20 20 20 20 32 31 20 20 20 2f 2a  USE      21   /*
48c0: 20 4c 69 62 72 61 72 79 20 75 73 65 64 20 69 6e   Library used in
48d0: 63 6f 72 72 65 63 74 6c 79 20 2a 2f 0a 23 64 65  correctly */.#de
48e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4c 46  fine SQLITE_NOLF
48f0: 53 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20  S       22   /* 
4900: 55 73 65 73 20 4f 53 20 66 65 61 74 75 72 65 73  Uses OS features
4910: 20 6e 6f 74 20 73 75 70 70 6f 72 74 65 64 20 6f   not supported o
4920: 6e 20 68 6f 73 74 20 2a 2f 0a 23 64 65 66 69 6e  n host */.#defin
4930: 65 20 53 51 4c 49 54 45 5f 41 55 54 48 20 20 20  e SQLITE_AUTH   
4940: 20 20 20 20 20 32 33 20 20 20 2f 2a 20 41 75 74       23   /* Aut
4950: 68 6f 72 69 7a 61 74 69 6f 6e 20 64 65 6e 69 65  horization denie
4960: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
4970: 49 54 45 5f 46 4f 52 4d 41 54 20 20 20 20 20 20  ITE_FORMAT      
4980: 32 34 20 20 20 2f 2a 20 41 75 78 69 6c 69 61 72  24   /* Auxiliar
4990: 79 20 64 61 74 61 62 61 73 65 20 66 6f 72 6d 61  y database forma
49a0: 74 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69  t error */.#defi
49b0: 6e 65 20 53 51 4c 49 54 45 5f 52 41 4e 47 45 20  ne SQLITE_RANGE 
49c0: 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20 32 6e        25   /* 2n
49d0: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
49e0: 71 6c 69 74 65 33 5f 62 69 6e 64 20 6f 75 74 20  qlite3_bind out 
49f0: 6f 66 20 72 61 6e 67 65 20 2a 2f 0a 23 64 65 66  of range */.#def
4a00: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 41 44  ine SQLITE_NOTAD
4a10: 42 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20 46  B      26   /* F
4a20: 69 6c 65 20 6f 70 65 6e 65 64 20 74 68 61 74 20  ile opened that 
4a30: 69 73 20 6e 6f 74 20 61 20 64 61 74 61 62 61 73  is not a databas
4a40: 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e  e file */.#defin
4a50: 65 20 53 51 4c 49 54 45 5f 52 4f 57 20 20 20 20  e SQLITE_ROW    
4a60: 20 20 20 20 20 31 30 30 20 20 2f 2a 20 73 71 6c       100  /* sql
4a70: 69 74 65 33 5f 73 74 65 70 28 29 20 68 61 73 20  ite3_step() has 
4a80: 61 6e 6f 74 68 65 72 20 72 6f 77 20 72 65 61 64  another row read
4a90: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
4aa0: 49 54 45 5f 44 4f 4e 45 20 20 20 20 20 20 20 20  ITE_DONE        
4ab0: 31 30 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f  101  /* sqlite3_
4ac0: 73 74 65 70 28 29 20 68 61 73 20 66 69 6e 69 73  step() has finis
4ad0: 68 65 64 20 65 78 65 63 75 74 69 6e 67 20 2a 2f  hed executing */
4ae0: 0a 2f 2a 20 65 6e 64 2d 6f 66 2d 65 72 72 6f 72  ./* end-of-error
4af0: 2d 63 6f 64 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a  -codes */../*.**
4b00: 20 43 41 50 49 33 52 45 46 3a 20 45 78 74 65 6e   CAPI3REF: Exten
4b10: 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73  ded Result Codes
4b20: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 65  .** KEYWORDS: {e
4b30: 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f  xtended error co
4b40: 64 65 7d 20 7b 65 78 74 65 6e 64 65 64 20 65 72  de} {extended er
4b50: 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45  ror codes}.** KE
4b60: 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e 64 65  YWORDS: {extende
4b70: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 7d 20 7b  d result code} {
4b80: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
4b90: 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20  codes}.**.** In 
4ba0: 69 74 73 20 64 65 66 61 75 6c 74 20 63 6f 6e 66  its default conf
4bb0: 69 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69 74  iguration, SQLit
4bc0: 65 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20 72  e API routines r
4bd0: 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 32 36 20  eturn one of 26 
4be0: 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 53 51 4c 49  integer.** [SQLI
4bf0: 54 45 5f 4f 4b 20 7c 20 72 65 73 75 6c 74 20 63  TE_OK | result c
4c00: 6f 64 65 73 5d 2e 20 20 48 6f 77 65 76 65 72 2c  odes].  However,
4c10: 20 65 78 70 65 72 69 65 6e 63 65 20 68 61 73 20   experience has 
4c20: 73 68 6f 77 6e 20 74 68 61 74 20 6d 61 6e 79 20  shown that many 
4c30: 6f 66 0a 2a 2a 20 74 68 65 73 65 20 72 65 73 75  of.** these resu
4c40: 6c 74 20 63 6f 64 65 73 20 61 72 65 20 74 6f 6f  lt codes are too
4c50: 20 63 6f 61 72 73 65 2d 67 72 61 69 6e 65 64 2e   coarse-grained.
4c60: 20 20 54 68 65 79 20 64 6f 20 6e 6f 74 20 70 72    They do not pr
4c70: 6f 76 69 64 65 20 61 73 0a 2a 2a 20 6d 75 63 68  ovide as.** much
4c80: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f   information abo
4c90: 75 74 20 70 72 6f 62 6c 65 6d 73 20 61 73 20 70  ut problems as p
4ca0: 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 68 74  rogrammers might
4cb0: 20 6c 69 6b 65 2e 20 20 49 6e 20 61 6e 20 65 66   like.  In an ef
4cc0: 66 6f 72 74 20 74 6f 0a 2a 2a 20 61 64 64 72 65  fort to.** addre
4cd0: 73 73 20 74 68 69 73 2c 20 6e 65 77 65 72 20 76  ss this, newer v
4ce0: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
4cf0: 65 20 28 76 65 72 73 69 6f 6e 20 33 2e 33 2e 38  e (version 3.3.8
4d00: 20 61 6e 64 20 6c 61 74 65 72 29 20 69 6e 63 6c   and later) incl
4d10: 75 64 65 0a 2a 2a 20 73 75 70 70 6f 72 74 20 66  ude.** support f
4d20: 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 72 65  or additional re
4d30: 73 75 6c 74 20 63 6f 64 65 73 20 74 68 61 74 20  sult codes that 
4d40: 70 72 6f 76 69 64 65 20 6d 6f 72 65 20 64 65 74  provide more det
4d50: 61 69 6c 65 64 20 69 6e 66 6f 72 6d 61 74 69 6f  ailed informatio
4d60: 6e 0a 2a 2a 20 61 62 6f 75 74 20 65 72 72 6f 72  n.** about error
4d70: 73 2e 20 54 68 65 20 65 78 74 65 6e 64 65 64 20  s. The extended 
4d80: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65  result codes are
4d90: 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61   enabled or disa
4da0: 62 6c 65 64 0a 2a 2a 20 6f 6e 20 61 20 70 65 72  bled.** on a per
4db0: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
4dc0: 74 69 6f 6e 20 62 61 73 69 73 20 75 73 69 6e 67  tion basis using
4dd0: 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
4de0: 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74  _extended_result
4df0: 5f 63 6f 64 65 73 28 29 5d 20 41 50 49 2e 0a 2a  _codes()] API..*
4e00: 2a 0a 2a 2a 20 53 6f 6d 65 20 6f 66 20 74 68 65  *.** Some of the
4e10: 20 61 76 61 69 6c 61 62 6c 65 20 65 78 74 65 6e   available exten
4e20: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
4e30: 20 61 72 65 20 6c 69 73 74 65 64 20 68 65 72 65   are listed here
4e40: 2e 0a 2a 2a 20 4f 6e 65 20 6d 61 79 20 65 78 70  ..** One may exp
4e50: 65 63 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  ect the number o
4e60: 66 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c  f extended resul
4e70: 74 20 63 6f 64 65 73 20 77 69 6c 6c 20 62 65 20  t codes will be 
4e80: 65 78 70 61 6e 64 0a 2a 2a 20 6f 76 65 72 20 74  expand.** over t
4e90: 69 6d 65 2e 20 20 53 6f 66 74 77 61 72 65 20 74  ime.  Software t
4ea0: 68 61 74 20 75 73 65 73 20 65 78 74 65 6e 64 65  hat uses extende
4eb0: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 73  d result codes s
4ec0: 68 6f 75 6c 64 20 65 78 70 65 63 74 0a 2a 2a 20  hould expect.** 
4ed0: 74 6f 20 73 65 65 20 6e 65 77 20 72 65 73 75 6c  to see new resul
4ee0: 74 20 63 6f 64 65 73 20 69 6e 20 66 75 74 75 72  t codes in futur
4ef0: 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51  e releases of SQ
4f00: 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  Lite..**.** The 
4f10: 53 51 4c 49 54 45 5f 4f 4b 20 72 65 73 75 6c 74  SQLITE_OK result
4f20: 20 63 6f 64 65 20 77 69 6c 6c 20 6e 65 76 65 72   code will never
4f30: 20 62 65 20 65 78 74 65 6e 64 65 64 2e 20 20 49   be extended.  I
4f40: 74 20 77 69 6c 6c 20 61 6c 77 61 79 73 0a 2a 2a  t will always.**
4f50: 20 62 65 20 65 78 61 63 74 6c 79 20 7a 65 72 6f   be exactly zero
4f60: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
4f70: 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 20  ITE_IOERR_READ  
4f80: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
4f90: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 3c 3c  ITE_IOERR | (1<<
4fa0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4fb0: 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52  TE_IOERR_SHORT_R
4fc0: 45 41 44 20 20 20 20 20 20 20 20 28 53 51 4c 49  EAD        (SQLI
4fd0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c 3c 38  TE_IOERR | (2<<8
4fe0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
4ff0: 45 5f 49 4f 45 52 52 5f 57 52 49 54 45 20 20 20  E_IOERR_WRITE   
5000: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5010: 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c 38 29  E_IOERR | (3<<8)
5020: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5030: 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20 20 20 20  _IOERR_FSYNC    
5040: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5050: 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38 29 29  _IOERR | (4<<8))
5060: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5070: 49 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e 43 20  IOERR_DIR_FSYNC 
5080: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5090: 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29 29 0a  IOERR | (5<<8)).
50a0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
50b0: 4f 45 52 52 5f 54 52 55 4e 43 41 54 45 20 20 20  OERR_TRUNCATE   
50c0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
50d0: 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29 29 0a 23  OERR | (6<<8)).#
50e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
50f0: 45 52 52 5f 46 53 54 41 54 20 20 20 20 20 20 20  ERR_FSTAT       
5100: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5110: 45 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64  ERR | (7<<8)).#d
5120: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5130: 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20  RR_UNLOCK       
5140: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5150: 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65  RR | (8<<8)).#de
5160: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
5170: 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20 20 20  R_RDLOCK        
5180: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
5190: 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66  R | (9<<8)).#def
51a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
51b0: 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20  _DELETE         
51c0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
51d0: 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64 65 66   | (10<<8)).#def
51e0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
51f0: 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 20  _BLOCKED        
5200: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5210: 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64 65 66   | (11<<8)).#def
5220: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5230: 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 20 20  _NOMEM          
5240: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5250: 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64 65 66   | (12<<8)).#def
5260: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5270: 5f 41 43 43 45 53 53 20 20 20 20 20 20 20 20 20  _ACCESS         
5280: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5290: 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64 65 66   | (13<<8)).#def
52a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
52b0: 5f 43 48 45 43 4b 52 45 53 45 52 56 45 44 4c 4f  _CHECKRESERVEDLO
52c0: 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52  CK (SQLITE_IOERR
52d0: 20 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64 65 66   | (14<<8)).#def
52e0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
52f0: 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20  _LOCK           
5300: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5310: 20 7c 20 28 31 35 3c 3c 38 29 29 0a 23 64 65 66   | (15<<8)).#def
5320: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5330: 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20 20  _CLOSE          
5340: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5350: 20 7c 20 28 31 36 3c 3c 38 29 29 0a 23 64 65 66   | (16<<8)).#def
5360: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5370: 5f 44 49 52 5f 43 4c 4f 53 45 20 20 20 20 20 20  _DIR_CLOSE      
5380: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5390: 20 7c 20 28 31 37 3c 3c 38 29 29 0a 23 64 65 66   | (17<<8)).#def
53a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
53b0: 5f 53 48 4d 4f 50 45 4e 20 20 20 20 20 20 20 20  _SHMOPEN        
53c0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
53d0: 20 7c 20 28 31 38 3c 3c 38 29 29 0a 23 64 65 66   | (18<<8)).#def
53e0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
53f0: 5f 53 48 4d 53 49 5a 45 20 20 20 20 20 20 20 20  _SHMSIZE        
5400: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5410: 20 7c 20 28 31 39 3c 3c 38 29 29 0a 23 64 65 66   | (19<<8)).#def
5420: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5430: 5f 53 48 4d 4c 4f 43 4b 20 20 20 20 20 20 20 20  _SHMLOCK        
5440: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5450: 20 7c 20 28 32 30 3c 3c 38 29 29 0a 23 64 65 66   | (20<<8)).#def
5460: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5470: 5f 53 48 4d 4d 41 50 20 20 20 20 20 20 20 20 20  _SHMMAP         
5480: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5490: 20 7c 20 28 32 31 3c 3c 38 29 29 0a 23 64 65 66   | (21<<8)).#def
54a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
54b0: 5f 53 45 45 4b 20 20 20 20 20 20 20 20 20 20 20  _SEEK           
54c0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
54d0: 20 7c 20 28 32 32 3c 3c 38 29 29 0a 23 64 65 66   | (22<<8)).#def
54e0: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45  ine SQLITE_LOCKE
54f0: 44 5f 53 48 41 52 45 44 43 41 43 48 45 20 20 20  D_SHAREDCACHE   
5500: 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b 45     (SQLITE_LOCKE
5510: 44 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65  D |  (1<<8)).#de
5520: 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59  fine SQLITE_BUSY
5530: 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20 20 20  _RECOVERY       
5540: 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53 59      (SQLITE_BUSY
5550: 20 20 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64     |  (1<<8)).#d
5560: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e  efine SQLITE_CAN
5570: 54 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44 49 52 20  TOPEN_NOTEMPDIR 
5580: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e       (SQLITE_CAN
5590: 54 4f 50 45 4e 20 7c 20 28 31 3c 3c 38 29 29 0a  TOPEN | (1<<8)).
55a0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
55b0: 41 4e 54 4f 50 45 4e 5f 49 53 44 49 52 20 20 20  ANTOPEN_ISDIR   
55c0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43         (SQLITE_C
55d0: 41 4e 54 4f 50 45 4e 20 7c 20 28 32 3c 3c 38 29  ANTOPEN | (2<<8)
55e0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
55f0: 5f 43 4f 52 52 55 50 54 5f 56 54 41 42 20 20 20  _CORRUPT_VTAB   
5600: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5610: 5f 43 4f 52 52 55 50 54 20 7c 20 28 31 3c 3c 38  _CORRUPT | (1<<8
5620: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5630: 45 5f 52 45 41 44 4f 4e 4c 59 5f 52 45 43 4f 56  E_READONLY_RECOV
5640: 45 52 59 20 20 20 20 20 20 20 28 53 51 4c 49 54  ERY       (SQLIT
5650: 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 31 3c  E_READONLY | (1<
5660: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5670: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 43 41 4e  ITE_READONLY_CAN
5680: 54 4c 4f 43 4b 20 20 20 20 20 20 20 28 53 51 4c  TLOCK       (SQL
5690: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28  ITE_READONLY | (
56a0: 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  2<<8)).#define S
56b0: 51 4c 49 54 45 5f 41 42 4f 52 54 5f 52 4f 4c 4c  QLITE_ABORT_ROLL
56c0: 42 41 43 4b 20 20 20 20 20 20 20 20 20 20 28 53  BACK          (S
56d0: 51 4c 49 54 45 5f 41 42 4f 52 54 20 7c 20 28 32  QLITE_ABORT | (2
56e0: 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  <<8))../*.** CAP
56f0: 49 33 52 45 46 3a 20 46 6c 61 67 73 20 46 6f 72  I3REF: Flags For
5700: 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65 72 61   File Open Opera
5710: 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  tions.**.** Thes
5720: 65 20 62 69 74 20 76 61 6c 75 65 73 20 61 72 65  e bit values are
5730: 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73   intended for us
5740: 65 20 69 6e 20 74 68 65 0a 2a 2a 20 33 72 64 20  e in the.** 3rd 
5750: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
5760: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
5770: 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 61  2()] interface a
5780: 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20 34 74 68  nd.** in the 4th
5790: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
57a0: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78  e [sqlite3_vfs.x
57b0: 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 2e 0a 2a 2f  Open] method..*/
57c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
57d0: 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 20 20  OPEN_READONLY   
57e0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 31        0x00000001
57f0: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
5800: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
5810: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5820: 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 20  OPEN_READWRITE  
5830: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 32        0x00000002
5840: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
5850: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
5860: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5870: 4f 50 45 4e 5f 43 52 45 41 54 45 20 20 20 20 20  OPEN_CREATE     
5880: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 34        0x00000004
5890: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
58a0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
58b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
58c0: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f  OPEN_DELETEONCLO
58d0: 53 45 20 20 20 20 30 78 30 30 30 30 30 30 30 38  SE    0x00000008
58e0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
58f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5900: 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 20  OPEN_EXCLUSIVE  
5910: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 31 30        0x00000010
5920: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
5930: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5940: 4f 50 45 4e 5f 41 55 54 4f 50 52 4f 58 59 20 20  OPEN_AUTOPROXY  
5950: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 32 30        0x00000020
5960: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
5970: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5980: 4f 50 45 4e 5f 55 52 49 20 20 20 20 20 20 20 20  OPEN_URI        
5990: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 34 30        0x00000040
59a0: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
59b0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
59c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
59d0: 4f 50 45 4e 5f 4d 45 4d 4f 52 59 20 20 20 20 20  OPEN_MEMORY     
59e0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 38 30        0x00000080
59f0: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
5a00: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
5a10: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5a20: 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20 20 20 20  OPEN_MAIN_DB    
5a30: 20 20 20 20 20 20 30 78 30 30 30 30 30 31 30 30        0x00000100
5a40: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
5a50: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5a60: 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20 20 20 20  OPEN_TEMP_DB    
5a70: 20 20 20 20 20 20 30 78 30 30 30 30 30 32 30 30        0x00000200
5a80: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
5a90: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5aa0: 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44  OPEN_TRANSIENT_D
5ab0: 42 20 20 20 20 20 30 78 30 30 30 30 30 34 30 30  B     0x00000400
5ac0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
5ad0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5ae0: 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41  OPEN_MAIN_JOURNA
5af0: 4c 20 20 20 20 20 30 78 30 30 30 30 30 38 30 30  L     0x00000800
5b00: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
5b10: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5b20: 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41  OPEN_TEMP_JOURNA
5b30: 4c 20 20 20 20 20 30 78 30 30 30 30 31 30 30 30  L     0x00001000
5b40: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
5b50: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5b60: 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 20  OPEN_SUBJOURNAL 
5b70: 20 20 20 20 20 20 30 78 30 30 30 30 32 30 30 30        0x00002000
5b80: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
5b90: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5ba0: 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52  OPEN_MASTER_JOUR
5bb0: 4e 41 4c 20 20 20 30 78 30 30 30 30 34 30 30 30  NAL   0x00004000
5bc0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
5bd0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5be0: 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 20 20 20 20  OPEN_NOMUTEX    
5bf0: 20 20 20 20 20 20 30 78 30 30 30 30 38 30 30 30        0x00008000
5c00: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
5c10: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
5c20: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5c30: 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 20 20  OPEN_FULLMUTEX  
5c40: 20 20 20 20 20 20 30 78 30 30 30 31 30 30 30 30        0x00010000
5c50: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
5c60: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
5c70: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5c80: 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45  OPEN_SHAREDCACHE
5c90: 20 20 20 20 20 20 30 78 30 30 30 32 30 30 30 30        0x00020000
5ca0: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
5cb0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
5cc0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5cd0: 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48  OPEN_PRIVATECACH
5ce0: 45 20 20 20 20 20 30 78 30 30 30 34 30 30 30 30  E     0x00040000
5cf0: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
5d00: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
5d10: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5d20: 4f 50 45 4e 5f 57 41 4c 20 20 20 20 20 20 20 20  OPEN_WAL        
5d30: 20 20 20 20 20 20 30 78 30 30 30 38 30 30 30 30        0x00080000
5d40: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
5d50: 0a 0a 2f 2a 20 52 65 73 65 72 76 65 64 3a 20 20  ../* Reserved:  
5d60: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
5d70: 20 20 20 20 20 20 20 30 78 30 30 46 30 30 30 30         0x00F0000
5d80: 30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  0 */../*.** CAPI
5d90: 33 52 45 46 3a 20 44 65 76 69 63 65 20 43 68 61  3REF: Device Cha
5da0: 72 61 63 74 65 72 69 73 74 69 63 73 0a 2a 2a 0a  racteristics.**.
5db0: 2a 2a 20 54 68 65 20 78 44 65 76 69 63 65 43 68  ** The xDeviceCh
5dc0: 61 72 61 63 74 65 72 69 73 74 69 63 73 20 6d 65  aracteristics me
5dd0: 74 68 6f 64 20 6f 66 20 74 68 65 20 5b 73 71 6c  thod of the [sql
5de0: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
5df0: 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74 75 72  .** object retur
5e00: 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68  ns an integer wh
5e10: 69 63 68 20 69 73 20 61 20 76 65 63 74 6f 72 20  ich is a vector 
5e20: 6f 66 20 74 68 65 20 74 68 65 73 65 0a 2a 2a 20  of the these.** 
5e30: 62 69 74 20 76 61 6c 75 65 73 20 65 78 70 72 65  bit values expre
5e40: 73 73 69 6e 67 20 49 2f 4f 20 63 68 61 72 61 63  ssing I/O charac
5e50: 74 65 72 69 73 74 69 63 73 20 6f 66 20 74 68 65  teristics of the
5e60: 20 6d 61 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a   mass storage.**
5e70: 20 64 65 76 69 63 65 20 74 68 61 74 20 68 6f 6c   device that hol
5e80: 64 73 20 74 68 65 20 66 69 6c 65 20 74 68 61 74  ds the file that
5e90: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f   the [sqlite3_io
5ea0: 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66  _methods].** ref
5eb0: 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68  ers to..**.** Th
5ec0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
5ed0: 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d  TOMIC property m
5ee0: 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72  eans that all wr
5ef0: 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73  ites of.** any s
5f00: 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20  ize are atomic. 
5f10: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
5f20: 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75  P_ATOMICnnn valu
5f30: 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20  es.** mean that 
5f40: 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73  writes of blocks
5f50: 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79   that are nnn by
5f60: 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a  tes in size and.
5f70: 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74  ** are aligned t
5f80: 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69  o an address whi
5f90: 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  ch is an integer
5fa0: 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20   multiple of.** 
5fb0: 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20  nnn are atomic. 
5fc0: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
5fd0: 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61  P_SAFE_APPEND va
5fe0: 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61  lue means.** tha
5ff0: 74 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61  t when data is a
6000: 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c  ppended to a fil
6010: 65 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61  e, the data is a
6020: 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74  ppended.** first
6030: 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f   then the size o
6040: 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78  f the file is ex
6050: 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68  tended, never th
6060: 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61  e other.** way a
6070: 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49  round.  The SQLI
6080: 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54  TE_IOCAP_SEQUENT
6090: 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61  IAL property mea
60a0: 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72  ns that.** infor
60b0: 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65  mation is writte
60c0: 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65  n to disk in the
60d0: 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63   same order as c
60e0: 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74  alls.** to xWrit
60f0: 65 28 29 2e 20 20 54 68 65 20 53 51 4c 49 54 45  e().  The SQLITE
6100: 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45  _IOCAP_POWERSAFE
6110: 5f 4f 56 45 52 57 52 49 54 45 20 70 72 6f 70 65  _OVERWRITE prope
6120: 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a  rty means that.*
6130: 2a 20 61 66 74 65 72 20 72 65 62 6f 6f 74 20 66  * after reboot f
6140: 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 72 61 73 68  ollowing a crash
6150: 20 6f 72 20 70 6f 77 65 72 20 6c 6f 73 73 2c 20   or power loss, 
6160: 74 68 65 20 6f 6e 6c 79 20 62 79 74 65 73 20 69  the only bytes i
6170: 6e 20 61 0a 2a 2a 20 66 69 6c 65 20 74 68 61 74  n a.** file that
6180: 20 77 65 72 65 20 77 72 69 74 74 65 6e 20 61 74   were written at
6190: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
61a0: 20 6c 65 76 65 6c 20 6d 69 67 68 74 20 68 61 76   level might hav
61b0: 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20 61 6e 64  e changed.** and
61c0: 20 74 68 61 74 20 61 64 6a 61 63 65 6e 74 20 62   that adjacent b
61d0: 79 74 65 73 2c 20 65 76 65 6e 20 62 79 74 65 73  ytes, even bytes
61e0: 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65   within the same
61f0: 20 73 65 63 74 6f 72 20 61 72 65 0a 2a 2a 20 67   sector are.** g
6200: 75 61 72 61 6e 74 65 65 64 20 74 6f 20 62 65 20  uaranteed to be 
6210: 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2f 0a 23 64  unchanged..*/.#d
6220: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
6230: 41 50 5f 41 54 4f 4d 49 43 20 20 20 20 20 20 20  AP_ATOMIC       
6240: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
6250: 30 30 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c  0001.#define SQL
6260: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
6270: 35 31 32 20 20 20 20 20 20 20 20 20 20 20 20 20  512             
6280: 20 30 78 30 30 30 30 30 30 30 32 0a 23 64 65 66   0x00000002.#def
6290: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
62a0: 5f 41 54 4f 4d 49 43 31 4b 20 20 20 20 20 20 20  _ATOMIC1K       
62b0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
62c0: 30 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  04.#define SQLIT
62d0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b  E_IOCAP_ATOMIC2K
62e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
62f0: 78 30 30 30 30 30 30 30 38 0a 23 64 65 66 69 6e  x00000008.#defin
6300: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
6310: 54 4f 4d 49 43 34 4b 20 20 20 20 20 20 20 20 20  TOMIC4K         
6320: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 31 30        0x00000010
6330: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6340: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 20 20  IOCAP_ATOMIC8K  
6350: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
6360: 30 30 30 30 30 32 30 0a 23 64 65 66 69 6e 65 20  0000020.#define 
6370: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
6380: 4d 49 43 31 36 4b 20 20 20 20 20 20 20 20 20 20  MIC16K          
6390: 20 20 20 20 30 78 30 30 30 30 30 30 34 30 0a 23      0x00000040.#
63a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
63b0: 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 20 20 20  CAP_ATOMIC32K   
63c0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
63d0: 30 30 30 38 30 0a 23 64 65 66 69 6e 65 20 53 51  00080.#define SQ
63e0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
63f0: 43 36 34 4b 20 20 20 20 20 20 20 20 20 20 20 20  C64K            
6400: 20 20 30 78 30 30 30 30 30 31 30 30 0a 23 64 65    0x00000100.#de
6410: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
6420: 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 20 20  P_SAFE_APPEND   
6430: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6440: 32 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  200.#define SQLI
6450: 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54  TE_IOCAP_SEQUENT
6460: 49 41 4c 20 20 20 20 20 20 20 20 20 20 20 20 20  IAL             
6470: 30 78 30 30 30 30 30 34 30 30 0a 23 64 65 66 69  0x00000400.#defi
6480: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
6490: 55 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e  UNDELETABLE_WHEN
64a0: 5f 4f 50 45 4e 20 20 30 78 30 30 30 30 30 38 30  _OPEN  0x0000080
64b0: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
64c0: 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45  _IOCAP_POWERSAFE
64d0: 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20 30 78  _OVERWRITE    0x
64e0: 30 30 30 30 31 30 30 30 0a 0a 2f 2a 0a 2a 2a 20  00001000../*.** 
64f0: 43 41 50 49 33 52 45 46 3a 20 46 69 6c 65 20 4c  CAPI3REF: File L
6500: 6f 63 6b 69 6e 67 20 4c 65 76 65 6c 73 0a 2a 2a  ocking Levels.**
6510: 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20  .** SQLite uses 
6520: 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 69 6e 74  one of these int
6530: 65 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74  eger values as t
6540: 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67  he second.** arg
6550: 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73 20 69  ument to calls i
6560: 74 20 6d 61 6b 65 73 20 74 6f 20 74 68 65 20 78  t makes to the x
6570: 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f  Lock() and xUnlo
6580: 63 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a 2a 20  ck() methods.** 
6590: 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69  of an [sqlite3_i
65a0: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63  o_methods] objec
65b0: 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  t..*/.#define SQ
65c0: 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20  LITE_LOCK_NONE  
65d0: 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e          0.#defin
65e0: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48  e SQLITE_LOCK_SH
65f0: 41 52 45 44 20 20 20 20 20 20 20 20 31 0a 23 64  ARED        1.#d
6600: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43  efine SQLITE_LOC
6610: 4b 5f 52 45 53 45 52 56 45 44 20 20 20 20 20 20  K_RESERVED      
6620: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
6630: 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 20 20  _LOCK_PENDING   
6640: 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51      3.#define SQ
6650: 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53  LITE_LOCK_EXCLUS
6660: 49 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a  IVE     4../*.**
6670: 20 43 41 50 49 33 52 45 46 3a 20 53 79 6e 63 68   CAPI3REF: Synch
6680: 72 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70 65 20  ronization Type 
6690: 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  Flags.**.** When
66a0: 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20   SQLite invokes 
66b0: 74 68 65 20 78 53 79 6e 63 28 29 20 6d 65 74 68  the xSync() meth
66c0: 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c  od of an.** [sql
66d0: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
66e0: 20 6f 62 6a 65 63 74 20 69 74 20 75 73 65 73 20   object it uses 
66f0: 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66  a combination of
6700: 0a 2a 2a 20 74 68 65 73 65 20 69 6e 74 65 67 65  .** these intege
6710: 72 20 76 61 6c 75 65 73 20 61 73 20 74 68 65 20  r values as the 
6720: 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e  second argument.
6730: 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20  .**.** When the 
6740: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41  SQLITE_SYNC_DATA
6750: 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20 75 73 65  ONLY flag is use
6760: 64 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74  d, it means that
6770: 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f 70 65   the.** sync ope
6780: 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64  ration only need
6790: 73 20 74 6f 20 66 6c 75 73 68 20 64 61 74 61 20  s to flush data 
67a0: 74 6f 20 6d 61 73 73 20 73 74 6f 72 61 67 65 2e  to mass storage.
67b0: 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72    Inode.** infor
67c0: 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f 74 20  mation need not 
67d0: 62 65 20 66 6c 75 73 68 65 64 2e 20 49 66 20 74  be flushed. If t
67e0: 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69  he lower four bi
67f0: 74 73 20 6f 66 20 74 68 65 20 66 6c 61 67 0a 2a  ts of the flag.*
6800: 2a 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53  * equal SQLITE_S
6810: 59 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68 61 74  YNC_NORMAL, that
6820: 20 6d 65 61 6e 73 20 74 6f 20 75 73 65 20 6e 6f   means to use no
6830: 72 6d 61 6c 20 66 73 79 6e 63 28 29 20 73 65 6d  rmal fsync() sem
6840: 61 6e 74 69 63 73 2e 0a 2a 2a 20 49 66 20 74 68  antics..** If th
6850: 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74  e lower four bit
6860: 73 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53  s equal SQLITE_S
6870: 59 4e 43 5f 46 55 4c 4c 2c 20 74 68 61 74 20 6d  YNC_FULL, that m
6880: 65 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65 20 4d  eans.** to use M
6890: 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75  ac OS X style fu
68a0: 6c 6c 73 79 6e 63 20 69 6e 73 74 65 61 64 20 6f  llsync instead o
68b0: 66 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a  f fsync()..**.**
68c0: 20 44 6f 20 6e 6f 74 20 63 6f 6e 66 75 73 65 20   Do not confuse 
68d0: 74 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  the SQLITE_SYNC_
68e0: 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54  NORMAL and SQLIT
68f0: 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67  E_SYNC_FULL flag
6900: 73 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 50  s.** with the [P
6910: 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75  RAGMA synchronou
6920: 73 5d 3d 4e 4f 52 4d 41 4c 20 61 6e 64 20 5b 50  s]=NORMAL and [P
6930: 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75  RAGMA synchronou
6940: 73 5d 3d 46 55 4c 4c 0a 2a 2a 20 73 65 74 74 69  s]=FULL.** setti
6950: 6e 67 73 2e 20 20 54 68 65 20 5b 73 79 6e 63 68  ngs.  The [synch
6960: 72 6f 6e 6f 75 73 20 70 72 61 67 6d 61 5d 20 64  ronous pragma] d
6970: 65 74 65 72 6d 69 6e 65 73 20 77 68 65 6e 20 63  etermines when c
6980: 61 6c 6c 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78  alls to the.** x
6990: 53 79 6e 63 20 56 46 53 20 6d 65 74 68 6f 64 20  Sync VFS method 
69a0: 6f 63 63 75 72 20 61 6e 64 20 61 70 70 6c 69 65  occur and applie
69b0: 73 20 75 6e 69 66 6f 72 6d 6c 79 20 61 63 72 6f  s uniformly acro
69c0: 73 73 20 61 6c 6c 20 70 6c 61 74 66 6f 72 6d 73  ss all platforms
69d0: 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f  ..** The SQLITE_
69e0: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20  SYNC_NORMAL and 
69f0: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c  SQLITE_SYNC_FULL
6a00: 20 66 6c 61 67 73 20 64 65 74 65 72 6d 69 6e 65   flags determine
6a10: 20 68 6f 77 0a 2a 2a 20 65 6e 65 72 67 65 74 69   how.** energeti
6a20: 63 20 6f 72 20 72 69 67 6f 72 6f 75 73 20 6f 72  c or rigorous or
6a30: 20 66 6f 72 63 65 66 75 6c 20 74 68 65 20 73 79   forceful the sy
6a40: 6e 63 20 6f 70 65 72 61 74 69 6f 6e 73 20 61 72  nc operations ar
6a50: 65 20 61 6e 64 0a 2a 2a 20 6f 6e 6c 79 20 6d 61  e and.** only ma
6a60: 6b 65 20 61 20 64 69 66 66 65 72 65 6e 63 65 20  ke a difference 
6a70: 6f 6e 20 4d 61 63 20 4f 53 58 20 66 6f 72 20 74  on Mac OSX for t
6a80: 68 65 20 64 65 66 61 75 6c 74 20 53 51 4c 69 74  he default SQLit
6a90: 65 20 63 6f 64 65 2e 0a 2a 2a 20 28 54 68 69 72  e code..** (Thir
6aa0: 64 2d 70 61 72 74 79 20 56 46 53 20 69 6d 70 6c  d-party VFS impl
6ab0: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 69 67 68  ementations migh
6ac0: 74 20 61 6c 73 6f 20 6d 61 6b 65 20 74 68 65 20  t also make the 
6ad0: 64 69 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62  distinction.** b
6ae0: 65 74 77 65 65 6e 20 53 51 4c 49 54 45 5f 53 59  etween SQLITE_SY
6af0: 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51  NC_NORMAL and SQ
6b00: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20  LITE_SYNC_FULL, 
6b10: 62 75 74 20 61 6d 6f 6e 67 20 74 68 65 0a 2a 2a  but among the.**
6b20: 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
6b30: 6d 73 20 6e 61 74 69 76 65 6c 79 20 73 75 70 70  ms natively supp
6b40: 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74 65 2c  orted by SQLite,
6b50: 20 6f 6e 6c 79 20 4d 61 63 20 4f 53 58 0a 2a 2a   only Mac OSX.**
6b60: 20 63 61 72 65 73 20 61 62 6f 75 74 20 74 68 65   cares about the
6b70: 20 64 69 66 66 65 72 65 6e 63 65 2e 29 0a 2a 2f   difference.).*/
6b80: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6b90: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20  SYNC_NORMAL     
6ba0: 20 20 20 30 78 30 30 30 30 32 0a 23 64 65 66 69     0x00002.#defi
6bb0: 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46  ne SQLITE_SYNC_F
6bc0: 55 4c 4c 20 20 20 20 20 20 20 20 20 20 30 78 30  ULL          0x0
6bd0: 30 30 30 33 0a 23 64 65 66 69 6e 65 20 53 51 4c  0003.#define SQL
6be0: 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c  ITE_SYNC_DATAONL
6bf0: 59 20 20 20 20 20 20 30 78 30 30 30 31 30 0a 0a  Y      0x00010..
6c00: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
6c10: 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f 70 65  OS Interface Ope
6c20: 6e 20 46 69 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a  n File Handle.**
6c30: 0a 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f  .** An [sqlite3_
6c40: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65 70  file] object rep
6c50: 72 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20  resents an open 
6c60: 66 69 6c 65 20 69 6e 20 74 68 65 20 0a 2a 2a 20  file in the .** 
6c70: 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 4f  [sqlite3_vfs | O
6c80: 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65  S interface laye
6c90: 72 5d 2e 20 20 49 6e 64 69 76 69 64 75 61 6c 20  r].  Individual 
6ca0: 4f 53 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  OS interface.** 
6cb0: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
6cc0: 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f 20  will.** want to 
6cd0: 73 75 62 63 6c 61 73 73 20 74 68 69 73 20 6f 62  subclass this ob
6ce0: 6a 65 63 74 20 62 79 20 61 70 70 65 6e 64 69 6e  ject by appendin
6cf0: 67 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65  g additional fie
6d00: 6c 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65 69 72  lds.** for their
6d10: 20 6f 77 6e 20 75 73 65 2e 20 20 54 68 65 20 70   own use.  The p
6d20: 4d 65 74 68 6f 64 73 20 65 6e 74 72 79 20 69 73  Methods entry is
6d30: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
6d40: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  .** [sqlite3_io_
6d50: 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20  methods] object 
6d60: 74 68 61 74 20 64 65 66 69 6e 65 73 20 6d 65 74  that defines met
6d70: 68 6f 64 73 20 66 6f 72 20 70 65 72 66 6f 72 6d  hods for perform
6d80: 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72 61  ing.** I/O opera
6d90: 74 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70 65  tions on the ope
6da0: 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64  n file..*/.typed
6db0: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
6dc0: 33 5f 66 69 6c 65 20 73 71 6c 69 74 65 33 5f 66  3_file sqlite3_f
6dd0: 69 6c 65 3b 0a 73 74 72 75 63 74 20 73 71 6c 69  ile;.struct sqli
6de0: 74 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f 6e  te3_file {.  con
6df0: 73 74 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  st struct sqlite
6e00: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70 4d  3_io_methods *pM
6e10: 65 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74 68  ethods;  /* Meth
6e20: 6f 64 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e 20  ods for an open 
6e30: 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a  file */.};../*.*
6e40: 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49  * CAPI3REF: OS I
6e50: 6e 74 65 72 66 61 63 65 20 46 69 6c 65 20 56 69  nterface File Vi
6e60: 72 74 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f 62  rtual Methods Ob
6e70: 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79  ject.**.** Every
6e80: 20 66 69 6c 65 20 6f 70 65 6e 65 64 20 62 79 20   file opened by 
6e90: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  the [sqlite3_vfs
6ea0: 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20 70  .xOpen] method p
6eb0: 6f 70 75 6c 61 74 65 73 20 61 6e 0a 2a 2a 20 5b  opulates an.** [
6ec0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62  sqlite3_file] ob
6ed0: 6a 65 63 74 20 28 6f 72 2c 20 6d 6f 72 65 20 63  ject (or, more c
6ee0: 6f 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 63 6c  ommonly, a subcl
6ef0: 61 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73  ass of the.** [s
6f00: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a  qlite3_file] obj
6f10: 65 63 74 29 20 77 69 74 68 20 61 20 70 6f 69 6e  ect) with a poin
6f20: 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e  ter to an instan
6f30: 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63  ce of this objec
6f40: 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63  t..** This objec
6f50: 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 6d 65  t defines the me
6f60: 74 68 6f 64 73 20 75 73 65 64 20 74 6f 20 70 65  thods used to pe
6f70: 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f 70  rform various op
6f80: 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 61 69  erations.** agai
6f90: 6e 73 74 20 74 68 65 20 6f 70 65 6e 20 66 69 6c  nst the open fil
6fa0: 65 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79  e represented by
6fb0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69   the [sqlite3_fi
6fc0: 6c 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a  le] object..**.*
6fd0: 2a 20 49 66 20 74 68 65 20 5b 73 71 6c 69 74 65  * If the [sqlite
6fe0: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74  3_vfs.xOpen] met
6ff0: 68 6f 64 20 73 65 74 73 20 74 68 65 20 73 71 6c  hod sets the sql
7000: 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f  ite3_file.pMetho
7010: 64 73 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20 74  ds element .** t
7020: 6f 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69  o a non-NULL poi
7030: 6e 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20 73  nter, then the s
7040: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
7050: 73 2e 78 43 6c 6f 73 65 20 6d 65 74 68 6f 64 0a  s.xClose method.
7060: 2a 2a 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65  ** may be invoke
7070: 64 20 65 76 65 6e 20 69 66 20 74 68 65 20 5b 73  d even if the [s
7080: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e  qlite3_vfs.xOpen
7090: 5d 20 72 65 70 6f 72 74 65 64 20 74 68 61 74 20  ] reported that 
70a0: 69 74 20 66 61 69 6c 65 64 2e 20 20 54 68 65 0a  it failed.  The.
70b0: 2a 2a 20 6f 6e 6c 79 20 77 61 79 20 74 6f 20 70  ** only way to p
70c0: 72 65 76 65 6e 74 20 61 20 63 61 6c 6c 20 74 6f  revent a call to
70d0: 20 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f 77 69 6e   xClose followin
70e0: 67 20 61 20 66 61 69 6c 65 64 20 5b 73 71 6c 69  g a failed [sqli
70f0: 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 0a 2a  te3_vfs.xOpen].*
7100: 2a 20 69 73 20 66 6f 72 20 74 68 65 20 5b 73 71  * is for the [sq
7110: 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d  lite3_vfs.xOpen]
7120: 20 74 6f 20 73 65 74 20 74 68 65 20 73 71 6c 69   to set the sqli
7130: 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64  te3_file.pMethod
7140: 73 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 74 6f 20  s element.** to 
7150: 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  NULL..**.** The 
7160: 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74  flags argument t
7170: 6f 20 78 53 79 6e 63 20 6d 61 79 20 62 65 20 6f  o xSync may be o
7180: 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53 59  ne of [SQLITE_SY
7190: 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a  NC_NORMAL] or.**
71a0: 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55   [SQLITE_SYNC_FU
71b0: 4c 4c 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20  LL].  The first 
71c0: 63 68 6f 69 63 65 20 69 73 20 74 68 65 20 6e 6f  choice is the no
71d0: 72 6d 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a 2a  rmal fsync()..**
71e0: 20 54 68 65 20 73 65 63 6f 6e 64 20 63 68 6f 69   The second choi
71f0: 63 65 20 69 73 20 61 20 4d 61 63 20 4f 53 20 58  ce is a Mac OS X
7200: 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 2e   style fullsync.
7210: 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 53 59    The [SQLITE_SY
7220: 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20  NC_DATAONLY].** 
7230: 66 6c 61 67 20 6d 61 79 20 62 65 20 4f 52 65 64  flag may be ORed
7240: 20 69 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20   in to indicate 
7250: 74 68 61 74 20 6f 6e 6c 79 20 74 68 65 20 64 61  that only the da
7260: 74 61 20 6f 66 20 74 68 65 20 66 69 6c 65 0a 2a  ta of the file.*
7270: 2a 20 61 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e  * and not its in
7280: 6f 64 65 20 6e 65 65 64 73 20 74 6f 20 62 65 20  ode needs to be 
7290: 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  synced..**.** Th
72a0: 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73  e integer values
72b0: 20 74 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20   to xLock() and 
72c0: 78 55 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f 6e  xUnlock() are on
72d0: 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  e of.** <ul>.** 
72e0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
72f0: 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e  K_NONE],.** <li>
7300: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48   [SQLITE_LOCK_SH
7310: 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b  ARED],.** <li> [
7320: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45  SQLITE_LOCK_RESE
7330: 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b  RVED],.** <li> [
7340: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44  SQLITE_LOCK_PEND
7350: 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e  ING], or.** <li>
7360: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58   [SQLITE_LOCK_EX
7370: 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75  CLUSIVE]..** </u
7380: 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 6e  l>.** xLock() in
7390: 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b  creases the lock
73a0: 2e 20 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63 72  . xUnlock() decr
73b0: 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 0a  eases the lock..
73c0: 2a 2a 20 54 68 65 20 78 43 68 65 63 6b 52 65 73  ** The xCheckRes
73d0: 65 72 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74 68  ervedLock() meth
73e0: 6f 64 20 63 68 65 63 6b 73 20 77 68 65 74 68 65  od checks whethe
73f0: 72 20 61 6e 79 20 64 61 74 61 62 61 73 65 20 63  r any database c
7400: 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69  onnection,.** ei
7410: 74 68 65 72 20 69 6e 20 74 68 69 73 20 70 72 6f  ther in this pro
7420: 63 65 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65 20  cess or in some 
7430: 6f 74 68 65 72 20 70 72 6f 63 65 73 73 2c 20 69  other process, i
7440: 73 20 68 6f 6c 64 69 6e 67 20 61 20 52 45 53 45  s holding a RESE
7450: 52 56 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47  RVED,.** PENDING
7460: 2c 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 6c  , or EXCLUSIVE l
7470: 6f 63 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65 2e  ock on the file.
7480: 20 20 49 74 20 72 65 74 75 72 6e 73 20 74 72 75    It returns tru
7490: 65 0a 2a 2a 20 69 66 20 73 75 63 68 20 61 20 6c  e.** if such a l
74a0: 6f 63 6b 20 65 78 69 73 74 73 20 61 6e 64 20 66  ock exists and f
74b0: 61 6c 73 65 20 6f 74 68 65 72 77 69 73 65 2e 0a  alse otherwise..
74c0: 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65 43  **.** The xFileC
74d0: 6f 6e 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64 20  ontrol() method 
74e0: 69 73 20 61 20 67 65 6e 65 72 69 63 20 69 6e 74  is a generic int
74f0: 65 72 66 61 63 65 20 74 68 61 74 20 61 6c 6c 6f  erface that allo
7500: 77 73 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 53  ws custom.** VFS
7510: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
7520: 20 74 6f 20 64 69 72 65 63 74 6c 79 20 63 6f 6e   to directly con
7530: 74 72 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69 6c  trol an open fil
7540: 65 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b  e using the.** [
7550: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
7560: 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61 63  trol()] interfac
7570: 65 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 22  e.  The second "
7580: 6f 70 22 20 61 72 67 75 6d 65 6e 74 20 69 73 20  op" argument is 
7590: 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6f 70  an.** integer op
75a0: 63 6f 64 65 2e 20 20 54 68 65 20 74 68 69 72 64  code.  The third
75b0: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 67   argument is a g
75c0: 65 6e 65 72 69 63 20 70 6f 69 6e 74 65 72 20 69  eneric pointer i
75d0: 6e 74 65 6e 64 65 64 20 74 6f 0a 2a 2a 20 70 6f  ntended to.** po
75e0: 69 6e 74 20 74 6f 20 61 20 73 74 72 75 63 74 75  int to a structu
75f0: 72 65 20 74 68 61 74 20 6d 61 79 20 63 6f 6e 74  re that may cont
7600: 61 69 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f 72  ain arguments or
7610: 20 73 70 61 63 65 20 69 6e 20 77 68 69 63 68 20   space in which 
7620: 74 6f 0a 2a 2a 20 77 72 69 74 65 20 72 65 74 75  to.** write retu
7630: 72 6e 20 76 61 6c 75 65 73 2e 20 20 50 6f 74 65  rn values.  Pote
7640: 6e 74 69 61 6c 20 75 73 65 73 20 66 6f 72 20 78  ntial uses for x
7650: 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 69  FileControl() mi
7660: 67 68 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74 69  ght be.** functi
7670: 6f 6e 73 20 74 6f 20 65 6e 61 62 6c 65 20 62 6c  ons to enable bl
7680: 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69 74  ocking locks wit
7690: 68 20 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20 63  h timeouts, to c
76a0: 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f 63  hange the.** loc
76b0: 6b 69 6e 67 20 73 74 72 61 74 65 67 79 20 28 66  king strategy (f
76c0: 6f 72 20 65 78 61 6d 70 6c 65 20 74 6f 20 75 73  or example to us
76d0: 65 20 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 73  e dot-file locks
76e0: 29 2c 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a 2a  ), to inquire.**
76f0: 20 61 62 6f 75 74 20 74 68 65 20 73 74 61 74 75   about the statu
7700: 73 20 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 20  s of a lock, or 
7710: 74 6f 20 62 72 65 61 6b 20 73 74 61 6c 65 20 6c  to break stale l
7720: 6f 63 6b 73 2e 20 20 54 68 65 20 53 51 4c 69 74  ocks.  The SQLit
7730: 65 0a 2a 2a 20 63 6f 72 65 20 72 65 73 65 72 76  e.** core reserv
7740: 65 73 20 61 6c 6c 20 6f 70 63 6f 64 65 73 20 6c  es all opcodes l
7750: 65 73 73 20 74 68 61 6e 20 31 30 30 20 66 6f 72  ess than 100 for
7760: 20 69 74 73 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a   its own use..**
7770: 20 41 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c   A [SQLITE_FCNTL
7780: 5f 4c 4f 43 4b 53 54 41 54 45 20 7c 20 6c 69 73  _LOCKSTATE | lis
7790: 74 20 6f 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65  t of opcodes] le
77a0: 73 73 20 74 68 61 6e 20 31 30 30 20 69 73 20 61  ss than 100 is a
77b0: 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 70  vailable..** App
77c0: 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 64  lications that d
77d0: 65 66 69 6e 65 20 61 20 63 75 73 74 6f 6d 20 78  efine a custom x
77e0: 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68  FileControl meth
77f0: 6f 64 20 73 68 6f 75 6c 64 20 75 73 65 20 6f 70  od should use op
7800: 63 6f 64 65 73 0a 2a 2a 20 67 72 65 61 74 65 72  codes.** greater
7810: 20 74 68 61 6e 20 31 30 30 20 74 6f 20 61 76 6f   than 100 to avo
7820: 69 64 20 63 6f 6e 66 6c 69 63 74 73 2e 20 20 56  id conflicts.  V
7830: 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  FS implementatio
7840: 6e 73 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74  ns should.** ret
7850: 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46  urn [SQLITE_NOTF
7860: 4f 55 4e 44 5d 20 66 6f 72 20 66 69 6c 65 20 63  OUND] for file c
7870: 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20 74  ontrol opcodes t
7880: 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a  hat they do not.
7890: 2a 2a 20 72 65 63 6f 67 6e 69 7a 65 2e 0a 2a 2a  ** recognize..**
78a0: 0a 2a 2a 20 54 68 65 20 78 53 65 63 74 6f 72 53  .** The xSectorS
78b0: 69 7a 65 28 29 20 6d 65 74 68 6f 64 20 72 65 74  ize() method ret
78c0: 75 72 6e 73 20 74 68 65 20 73 65 63 74 6f 72 20  urns the sector 
78d0: 73 69 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20 64  size of the.** d
78e0: 65 76 69 63 65 20 74 68 61 74 20 75 6e 64 65 72  evice that under
78f0: 6c 69 65 73 20 74 68 65 20 66 69 6c 65 2e 20 20  lies the file.  
7900: 54 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20  The sector size 
7910: 69 73 20 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75  is the.** minimu
7920: 6d 20 77 72 69 74 65 20 74 68 61 74 20 63 61 6e  m write that can
7930: 20 62 65 20 70 65 72 66 6f 72 6d 65 64 20 77 69   be performed wi
7940: 74 68 6f 75 74 20 64 69 73 74 75 72 62 69 6e 67  thout disturbing
7950: 0a 2a 2a 20 6f 74 68 65 72 20 62 79 74 65 73 20  .** other bytes 
7960: 69 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68  in the file.  Th
7970: 65 20 78 44 65 76 69 63 65 43 68 61 72 61 63 74  e xDeviceCharact
7980: 65 72 69 73 74 69 63 73 28 29 0a 2a 2a 20 6d 65  eristics().** me
7990: 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 62  thod returns a b
79a0: 69 74 20 76 65 63 74 6f 72 20 64 65 73 63 72 69  it vector descri
79b0: 62 69 6e 67 20 62 65 68 61 76 69 6f 72 73 20 6f  bing behaviors o
79c0: 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79  f the.** underly
79d0: 69 6e 67 20 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a  ing device:.**.*
79e0: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b  * <ul>.** <li> [
79f0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
7a00: 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  MIC].** <li> [SQ
7a10: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
7a20: 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  C512].** <li> [S
7a30: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
7a40: 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  IC1K].** <li> [S
7a50: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
7a60: 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  IC2K].** <li> [S
7a70: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
7a80: 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  IC4K].** <li> [S
7a90: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
7aa0: 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  IC8K].** <li> [S
7ab0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
7ac0: 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  IC16K].** <li> [
7ad0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
7ae0: 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  MIC32K].** <li> 
7af0: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
7b00: 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e  OMIC64K].** <li>
7b10: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53   [SQLITE_IOCAP_S
7b20: 41 46 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c  AFE_APPEND].** <
7b30: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
7b40: 50 5f 53 45 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a  P_SEQUENTIAL].**
7b50: 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65   </ul>.**.** The
7b60: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
7b70: 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65  OMIC property me
7b80: 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69  ans that all wri
7b90: 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69  tes of.** any si
7ba0: 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  ze are atomic.  
7bb0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
7bc0: 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65  _ATOMICnnn value
7bd0: 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77  s.** mean that w
7be0: 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20  rites of blocks 
7bf0: 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74  that are nnn byt
7c00: 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a  es in size and.*
7c10: 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f  * are aligned to
7c20: 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63   an address whic
7c30: 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  h is an integer 
7c40: 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e  multiple of.** n
7c50: 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  nn are atomic.  
7c60: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
7c70: 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c  _SAFE_APPEND val
7c80: 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74  ue means.** that
7c90: 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70   when data is ap
7ca0: 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65  pended to a file
7cb0: 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70  , the data is ap
7cc0: 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20  pended.** first 
7cd0: 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66  then the size of
7ce0: 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74   the file is ext
7cf0: 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65  ended, never the
7d00: 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72   other.** way ar
7d10: 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54  ound.  The SQLIT
7d20: 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49  E_IOCAP_SEQUENTI
7d30: 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e  AL property mean
7d40: 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d  s that.** inform
7d50: 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e  ation is written
7d60: 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20   to disk in the 
7d70: 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61  same order as ca
7d80: 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65  lls.** to xWrite
7d90: 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 78 52 65  ()..**.** If xRe
7da0: 61 64 28 29 20 72 65 74 75 72 6e 73 20 53 51 4c  ad() returns SQL
7db0: 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f  ITE_IOERR_SHORT_
7dc0: 52 45 41 44 20 69 74 20 6d 75 73 74 20 61 6c 73  READ it must als
7dd0: 6f 20 66 69 6c 6c 0a 2a 2a 20 69 6e 20 74 68 65  o fill.** in the
7de0: 20 75 6e 72 65 61 64 20 70 6f 72 74 69 6f 6e 73   unread portions
7df0: 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 20 77   of the buffer w
7e00: 69 74 68 20 7a 65 72 6f 73 2e 20 20 41 20 56 46  ith zeros.  A VF
7e10: 53 20 74 68 61 74 0a 2a 2a 20 66 61 69 6c 73 20  S that.** fails 
7e20: 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f  to zero-fill sho
7e30: 72 74 20 72 65 61 64 73 20 6d 69 67 68 74 20 73  rt reads might s
7e40: 65 65 6d 20 74 6f 20 77 6f 72 6b 2e 20 20 48 6f  eem to work.  Ho
7e50: 77 65 76 65 72 2c 0a 2a 2a 20 66 61 69 6c 75 72  wever,.** failur
7e60: 65 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73  e to zero-fill s
7e70: 68 6f 72 74 20 72 65 61 64 73 20 77 69 6c 6c 20  hort reads will 
7e80: 65 76 65 6e 74 75 61 6c 6c 79 20 6c 65 61 64 20  eventually lead 
7e90: 74 6f 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  to.** database c
7ea0: 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 74 79  orruption..*/.ty
7eb0: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
7ec0: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20  ite3_io_methods 
7ed0: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
7ee0: 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74  ds;.struct sqlit
7ef0: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a  e3_io_methods {.
7f00: 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a    int iVersion;.
7f10: 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28    int (*xClose)(
7f20: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a  sqlite3_file*);.
7f30: 20 20 69 6e 74 20 28 2a 78 52 65 61 64 29 28 73    int (*xRead)(s
7f40: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 76 6f  qlite3_file*, vo
7f50: 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73  id*, int iAmt, s
7f60: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66  qlite3_int64 iOf
7f70: 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 57 72  st);.  int (*xWr
7f80: 69 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ite)(sqlite3_fil
7f90: 65 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  e*, const void*,
7fa0: 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74   int iAmt, sqlit
7fb0: 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b  e3_int64 iOfst);
7fc0: 0a 20 20 69 6e 74 20 28 2a 78 54 72 75 6e 63 61  .  int (*xTrunca
7fd0: 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  te)(sqlite3_file
7fe0: 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
7ff0: 20 73 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a   size);.  int (*
8000: 78 53 79 6e 63 29 28 73 71 6c 69 74 65 33 5f 66  xSync)(sqlite3_f
8010: 69 6c 65 2a 2c 20 69 6e 74 20 66 6c 61 67 73 29  ile*, int flags)
8020: 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 53  ;.  int (*xFileS
8030: 69 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ize)(sqlite3_fil
8040: 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  e*, sqlite3_int6
8050: 34 20 2a 70 53 69 7a 65 29 3b 0a 20 20 69 6e 74  4 *pSize);.  int
8060: 20 28 2a 78 4c 6f 63 6b 29 28 73 71 6c 69 74 65   (*xLock)(sqlite
8070: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20  3_file*, int);. 
8080: 20 69 6e 74 20 28 2a 78 55 6e 6c 6f 63 6b 29 28   int (*xUnlock)(
8090: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
80a0: 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 68  nt);.  int (*xCh
80b0: 65 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 29  eckReservedLock)
80c0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
80d0: 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20  int *pResOut);. 
80e0: 20 69 6e 74 20 28 2a 78 46 69 6c 65 43 6f 6e 74   int (*xFileCont
80f0: 72 6f 6c 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  rol)(sqlite3_fil
8100: 65 2a 2c 20 69 6e 74 20 6f 70 2c 20 76 6f 69 64  e*, int op, void
8110: 20 2a 70 41 72 67 29 3b 0a 20 20 69 6e 74 20 28   *pArg);.  int (
8120: 2a 78 53 65 63 74 6f 72 53 69 7a 65 29 28 73 71  *xSectorSize)(sq
8130: 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20  lite3_file*);.  
8140: 69 6e 74 20 28 2a 78 44 65 76 69 63 65 43 68 61  int (*xDeviceCha
8150: 72 61 63 74 65 72 69 73 74 69 63 73 29 28 73 71  racteristics)(sq
8160: 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20  lite3_file*);.  
8170: 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65  /* Methods above
8180: 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76   are valid for v
8190: 65 72 73 69 6f 6e 20 31 20 2a 2f 0a 20 20 69 6e  ersion 1 */.  in
81a0: 74 20 28 2a 78 53 68 6d 4d 61 70 29 28 73 71 6c  t (*xShmMap)(sql
81b0: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20  ite3_file*, int 
81c0: 69 50 67 2c 20 69 6e 74 20 70 67 73 7a 2c 20 69  iPg, int pgsz, i
81d0: 6e 74 2c 20 76 6f 69 64 20 76 6f 6c 61 74 69 6c  nt, void volatil
81e0: 65 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53  e**);.  int (*xS
81f0: 68 6d 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f  hmLock)(sqlite3_
8200: 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 66 66 73 65  file*, int offse
8210: 74 2c 20 69 6e 74 20 6e 2c 20 69 6e 74 20 66 6c  t, int n, int fl
8220: 61 67 73 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78  ags);.  void (*x
8230: 53 68 6d 42 61 72 72 69 65 72 29 28 73 71 6c 69  ShmBarrier)(sqli
8240: 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e  te3_file*);.  in
8250: 74 20 28 2a 78 53 68 6d 55 6e 6d 61 70 29 28 73  t (*xShmUnmap)(s
8260: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
8270: 74 20 64 65 6c 65 74 65 46 6c 61 67 29 3b 0a 20  t deleteFlag);. 
8280: 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76   /* Methods abov
8290: 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20  e are valid for 
82a0: 76 65 72 73 69 6f 6e 20 32 20 2a 2f 0a 20 20 2f  version 2 */.  /
82b0: 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65 74  * Additional met
82c0: 68 6f 64 73 20 6d 61 79 20 62 65 20 61 64 64 65  hods may be adde
82d0: 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  d in future rele
82e0: 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a  ases */.};../*.*
82f0: 2a 20 43 41 50 49 33 52 45 46 3a 20 53 74 61 6e  * CAPI3REF: Stan
8300: 64 61 72 64 20 46 69 6c 65 20 43 6f 6e 74 72 6f  dard File Contro
8310: 6c 20 4f 70 63 6f 64 65 73 0a 2a 2a 0a 2a 2a 20  l Opcodes.**.** 
8320: 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f  These integer co
8330: 6e 73 74 61 6e 74 73 20 61 72 65 20 6f 70 63 6f  nstants are opco
8340: 64 65 73 20 66 6f 72 20 74 68 65 20 78 46 69 6c  des for the xFil
8350: 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a  eControl method.
8360: 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ** of the [sqlit
8370: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f  e3_io_methods] o
8380: 62 6a 65 63 74 20 61 6e 64 20 66 6f 72 20 74 68  bject and for th
8390: 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  e [sqlite3_file_
83a0: 63 6f 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e  control()].** in
83b0: 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54  terface..**.** T
83c0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
83d0: 5f 4c 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63 6f  _LOCKSTATE] opco
83e0: 64 65 20 69 73 20 75 73 65 64 20 66 6f 72 20 64  de is used for d
83f0: 65 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a  ebugging.  This.
8400: 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73  ** opcode causes
8410: 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f   the xFileContro
8420: 6c 20 6d 65 74 68 6f 64 20 74 6f 20 77 72 69 74  l method to writ
8430: 65 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74  e the current st
8440: 61 74 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f  ate of.** the lo
8450: 63 6b 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c 49  ck (one of [SQLI
8460: 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b  TE_LOCK_NONE], [
8470: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52  SQLITE_LOCK_SHAR
8480: 45 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ED],.** [SQLITE_
8490: 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 20  LOCK_RESERVED], 
84a0: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e  [SQLITE_LOCK_PEN
84b0: 44 49 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c 49 54  DING], or [SQLIT
84c0: 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45  E_LOCK_EXCLUSIVE
84d0: 5d 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69 6e  ]).** into an in
84e0: 74 65 67 65 72 20 74 68 61 74 20 74 68 65 20 70  teger that the p
84f0: 41 72 67 20 61 72 67 75 6d 65 6e 74 20 70 6f 69  Arg argument poi
8500: 6e 74 73 20 74 6f 2e 20 54 68 69 73 20 63 61 70  nts to. This cap
8510: 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 75 73  ability.** is us
8520: 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e  ed during testin
8530: 67 20 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64 73  g and only needs
8540: 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64   to be supported
8550: 20 77 68 65 6e 20 53 51 4c 49 54 45 5f 54 45 53   when SQLITE_TES
8560: 54 0a 2a 2a 20 69 73 20 64 65 66 69 6e 65 64 2e  T.** is defined.
8570: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
8580: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53  [[SQLITE_FCNTL_S
8590: 49 5a 45 5f 48 49 4e 54 5d 5d 0a 2a 2a 20 54 68  IZE_HINT]].** Th
85a0: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
85b0: 53 49 5a 45 5f 48 49 4e 54 5d 20 6f 70 63 6f 64  SIZE_HINT] opcod
85c0: 65 20 69 73 20 75 73 65 64 20 62 79 20 53 51 4c  e is used by SQL
85d0: 69 74 65 20 74 6f 20 67 69 76 65 20 74 68 65 20  ite to give the 
85e0: 56 46 53 0a 2a 2a 20 6c 61 79 65 72 20 61 20 68  VFS.** layer a h
85f0: 69 6e 74 20 6f 66 20 68 6f 77 20 6c 61 72 67 65  int of how large
8600: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
8610: 6c 65 20 77 69 6c 6c 20 67 72 6f 77 20 74 6f 20  le will grow to 
8620: 62 65 20 64 75 72 69 6e 67 20 74 68 65 0a 2a 2a  be during the.**
8630: 20 63 75 72 72 65 6e 74 20 74 72 61 6e 73 61 63   current transac
8640: 74 69 6f 6e 2e 20 20 54 68 69 73 20 68 69 6e 74  tion.  This hint
8650: 20 69 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65   is not guarante
8660: 65 64 20 74 6f 20 62 65 20 61 63 63 75 72 61 74  ed to be accurat
8670: 65 20 62 75 74 20 69 74 0a 2a 2a 20 69 73 20 6f  e but it.** is o
8680: 66 74 65 6e 20 63 6c 6f 73 65 2e 20 20 54 68 65  ften close.  The
8690: 20 75 6e 64 65 72 6c 79 69 6e 67 20 56 46 53 20   underlying VFS 
86a0: 6d 69 67 68 74 20 63 68 6f 6f 73 65 20 74 6f 20  might choose to 
86b0: 70 72 65 61 6c 6c 6f 63 61 74 65 20 64 61 74 61  preallocate data
86c0: 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 73 70 61  base.** file spa
86d0: 63 65 20 62 61 73 65 64 20 6f 6e 20 74 68 69 73  ce based on this
86e0: 20 68 69 6e 74 20 69 6e 20 6f 72 64 65 72 20 74   hint in order t
86f0: 6f 20 68 65 6c 70 20 77 72 69 74 65 73 20 74 6f  o help writes to
8700: 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   the database.**
8710: 20 66 69 6c 65 20 72 75 6e 20 66 61 73 74 65 72   file run faster
8720: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
8730: 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b  LITE_FCNTL_CHUNK
8740: 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b  _SIZE]].** The [
8750: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55  SQLITE_FCNTL_CHU
8760: 4e 4b 5f 53 49 5a 45 5d 20 6f 70 63 6f 64 65 20  NK_SIZE] opcode 
8770: 69 73 20 75 73 65 64 20 74 6f 20 72 65 71 75 65  is used to reque
8780: 73 74 20 74 68 61 74 20 74 68 65 20 56 46 53 0a  st that the VFS.
8790: 2a 2a 20 65 78 74 65 6e 64 73 20 61 6e 64 20 74  ** extends and t
87a0: 72 75 6e 63 61 74 65 73 20 74 68 65 20 64 61 74  runcates the dat
87b0: 61 62 61 73 65 20 66 69 6c 65 20 69 6e 20 63 68  abase file in ch
87c0: 75 6e 6b 73 20 6f 66 20 61 20 73 69 7a 65 20 73  unks of a size s
87d0: 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 74  pecified.** by t
87e0: 68 65 20 75 73 65 72 2e 20 54 68 65 20 66 6f 75  he user. The fou
87f0: 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rth argument to 
8800: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
8810: 6e 74 72 6f 6c 28 29 5d 20 73 68 6f 75 6c 64 20  ntrol()] should 
8820: 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20  .** point to an 
8830: 69 6e 74 65 67 65 72 20 28 74 79 70 65 20 69 6e  integer (type in
8840: 74 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68  t) containing th
8850: 65 20 6e 65 77 20 63 68 75 6e 6b 2d 73 69 7a 65  e new chunk-size
8860: 20 74 6f 20 75 73 65 0a 2a 2a 20 66 6f 72 20 74   to use.** for t
8870: 68 65 20 6e 6f 6d 69 6e 61 74 65 64 20 64 61 74  he nominated dat
8880: 61 62 61 73 65 2e 20 41 6c 6c 6f 63 61 74 69 6e  abase. Allocatin
8890: 67 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  g database file 
88a0: 73 70 61 63 65 20 69 6e 20 6c 61 72 67 65 0a 2a  space in large.*
88b0: 2a 20 63 68 75 6e 6b 73 20 28 73 61 79 20 31 4d  * chunks (say 1M
88c0: 42 20 61 74 20 61 20 74 69 6d 65 29 2c 20 6d 61  B at a time), ma
88d0: 79 20 72 65 64 75 63 65 20 66 69 6c 65 2d 73 79  y reduce file-sy
88e0: 73 74 65 6d 20 66 72 61 67 6d 65 6e 74 61 74 69  stem fragmentati
88f0: 6f 6e 20 61 6e 64 0a 2a 2a 20 69 6d 70 72 6f 76  on and.** improv
8900: 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 6f 6e  e performance on
8910: 20 73 6f 6d 65 20 73 79 73 74 65 6d 73 2e 0a 2a   some systems..*
8920: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
8930: 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49  E_FCNTL_FILE_POI
8940: 4e 54 45 52 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53  NTER]].** The [S
8950: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45  QLITE_FCNTL_FILE
8960: 5f 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65  _POINTER] opcode
8970: 20 69 73 20 75 73 65 64 20 74 6f 20 6f 62 74 61   is used to obta
8980: 69 6e 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  in a pointer.** 
8990: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
89a0: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 61 73 73  file] object ass
89b0: 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 20 70  ociated with a p
89c0: 61 72 74 69 63 75 6c 61 72 20 64 61 74 61 62 61  articular databa
89d0: 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  se.** connection
89e0: 2e 20 20 53 65 65 20 74 68 65 20 5b 73 71 6c 69  .  See the [sqli
89f0: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
8a00: 28 29 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f  ()] documentatio
8a10: 6e 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f  n for.** additio
8a20: 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  nal information.
8a30: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
8a40: 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f  ITE_FCNTL_SYNC_O
8a50: 4d 49 54 54 45 44 5d 5d 0a 2a 2a 20 5e 28 54 68  MITTED]].** ^(Th
8a60: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
8a70: 53 59 4e 43 5f 4f 4d 49 54 54 45 44 5d 20 6f 70  SYNC_OMITTED] op
8a80: 63 6f 64 65 20 69 73 20 67 65 6e 65 72 61 74 65  code is generate
8a90: 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 0a  d internally by.
8aa0: 2a 2a 20 53 51 4c 69 74 65 20 61 6e 64 20 73 65  ** SQLite and se
8ab0: 6e 74 20 74 6f 20 61 6c 6c 20 56 46 53 65 73 20  nt to all VFSes 
8ac0: 69 6e 20 70 6c 61 63 65 20 6f 66 20 61 20 63 61  in place of a ca
8ad0: 6c 6c 20 74 6f 20 74 68 65 20 78 53 79 6e 63 20  ll to the xSync 
8ae0: 6d 65 74 68 6f 64 0a 2a 2a 20 77 68 65 6e 20 74  method.** when t
8af0: 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
8b00: 65 63 74 69 6f 6e 20 68 61 73 20 5b 50 52 41 47  ection has [PRAG
8b10: 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 20  MA synchronous] 
8b20: 73 65 74 20 74 6f 20 4f 46 46 2e 29 5e 0a 2a 2a  set to OFF.)^.**
8b30: 20 53 6f 6d 65 20 73 70 65 63 69 61 6c 69 7a 65   Some specialize
8b40: 64 20 56 46 53 65 73 20 6e 65 65 64 20 74 68 69  d VFSes need thi
8b50: 73 20 73 69 67 6e 61 6c 20 69 6e 20 6f 72 64 65  s signal in orde
8b60: 72 20 74 6f 20 6f 70 65 72 61 74 65 20 63 6f 72  r to operate cor
8b70: 72 65 63 74 6c 79 0a 2a 2a 20 77 68 65 6e 20 5b  rectly.** when [
8b80: 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f  PRAGMA synchrono
8b90: 75 73 20 7c 20 50 52 41 47 4d 41 20 73 79 6e 63  us | PRAGMA sync
8ba0: 68 72 6f 6e 6f 75 73 3d 4f 46 46 5d 20 69 73 20  hronous=OFF] is 
8bb0: 73 65 74 2c 20 62 75 74 20 6d 6f 73 74 20 0a 2a  set, but most .*
8bc0: 2a 20 56 46 53 65 73 20 64 6f 20 6e 6f 74 20 6e  * VFSes do not n
8bd0: 65 65 64 20 74 68 69 73 20 73 69 67 6e 61 6c 20  eed this signal 
8be0: 61 6e 64 20 73 68 6f 75 6c 64 20 73 69 6c 65 6e  and should silen
8bf0: 74 6c 79 20 69 67 6e 6f 72 65 20 74 68 69 73 20  tly ignore this 
8c00: 6f 70 63 6f 64 65 2e 0a 2a 2a 20 41 70 70 6c 69  opcode..** Appli
8c10: 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 6e  cations should n
8c20: 6f 74 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33  ot call [sqlite3
8c30: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d  _file_control()]
8c40: 20 77 69 74 68 20 74 68 69 73 0a 2a 2a 20 6f 70   with this.** op
8c50: 63 6f 64 65 20 61 73 20 64 6f 69 6e 67 20 73 6f  code as doing so
8c60: 20 6d 61 79 20 64 69 73 72 75 70 74 20 74 68 65   may disrupt the
8c70: 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66 20 74 68   operation of th
8c80: 65 20 73 70 65 63 69 61 6c 69 7a 65 64 20 56 46  e specialized VF
8c90: 53 65 73 0a 2a 2a 20 74 68 61 74 20 64 6f 20 72  Ses.** that do r
8ca0: 65 71 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a 0a  equire it.  .**.
8cb0: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
8cc0: 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52  FCNTL_WIN32_AV_R
8cd0: 45 54 52 59 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b  ETRY]].** ^The [
8ce0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e  SQLITE_FCNTL_WIN
8cf0: 33 32 5f 41 56 5f 52 45 54 52 59 5d 20 6f 70 63  32_AV_RETRY] opc
8d00: 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 63  ode is used to c
8d10: 6f 6e 66 69 67 75 72 65 20 61 75 74 6f 6d 61 74  onfigure automat
8d20: 69 63 0a 2a 2a 20 72 65 74 72 79 20 63 6f 75 6e  ic.** retry coun
8d30: 74 73 20 61 6e 64 20 69 6e 74 65 72 76 61 6c 73  ts and intervals
8d40: 20 66 6f 72 20 63 65 72 74 61 69 6e 20 64 69 73   for certain dis
8d50: 6b 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73  k I/O operations
8d60: 20 66 6f 72 20 74 68 65 0a 2a 2a 20 77 69 6e 64   for the.** wind
8d70: 6f 77 73 20 5b 56 46 53 5d 20 69 6e 20 6f 72 64  ows [VFS] in ord
8d80: 65 72 20 74 6f 20 70 72 6f 76 69 64 65 20 72 6f  er to provide ro
8d90: 62 75 73 74 6e 65 73 73 20 69 6e 20 74 68 65 20  bustness in the 
8da0: 70 72 65 73 65 6e 63 65 20 6f 66 0a 2a 2a 20 61  presence of.** a
8db0: 6e 74 69 2d 76 69 72 75 73 20 70 72 6f 67 72 61  nti-virus progra
8dc0: 6d 73 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c  ms.  By default,
8dd0: 20 74 68 65 20 77 69 6e 64 6f 77 73 20 56 46 53   the windows VFS
8de0: 20 77 69 6c 6c 20 72 65 74 72 79 20 66 69 6c 65   will retry file
8df0: 20 72 65 61 64 2c 0a 2a 2a 20 66 69 6c 65 20 77   read,.** file w
8e00: 72 69 74 65 2c 20 61 6e 64 20 66 69 6c 65 20 64  rite, and file d
8e10: 65 6c 65 74 65 20 6f 70 65 72 61 74 69 6f 6e 73  elete operations
8e20: 20 75 70 20 74 6f 20 31 30 20 74 69 6d 65 73 2c   up to 10 times,
8e30: 20 77 69 74 68 20 61 20 64 65 6c 61 79 0a 2a 2a   with a delay.**
8e40: 20 6f 66 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f   of 25 milliseco
8e50: 6e 64 73 20 62 65 66 6f 72 65 20 74 68 65 20 66  nds before the f
8e60: 69 72 73 74 20 72 65 74 72 79 20 61 6e 64 20 77  irst retry and w
8e70: 69 74 68 20 74 68 65 20 64 65 6c 61 79 20 69 6e  ith the delay in
8e80: 63 72 65 61 73 69 6e 67 0a 2a 2a 20 62 79 20 61  creasing.** by a
8e90: 6e 20 61 64 64 69 74 69 6f 6e 61 6c 20 32 35 20  n additional 25 
8ea0: 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 77 69 74  milliseconds wit
8eb0: 68 20 65 61 63 68 20 73 75 62 73 65 71 75 65 6e  h each subsequen
8ec0: 74 20 72 65 74 72 79 2e 20 20 54 68 69 73 0a 2a  t retry.  This.*
8ed0: 2a 20 6f 70 63 6f 64 65 20 61 6c 6c 6f 77 73 20  * opcode allows 
8ee0: 74 68 65 73 65 20 74 77 6f 20 76 61 6c 75 65 73  these two values
8ef0: 20 28 31 30 20 72 65 74 72 69 65 73 20 61 6e 64   (10 retries and
8f00: 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73   25 milliseconds
8f10: 20 6f 66 20 64 65 6c 61 79 29 0a 2a 2a 20 74 6f   of delay).** to
8f20: 20 62 65 20 61 64 6a 75 73 74 65 64 2e 20 20 54   be adjusted.  T
8f30: 68 65 20 76 61 6c 75 65 73 20 61 72 65 20 63 68  he values are ch
8f40: 61 6e 67 65 64 20 66 6f 72 20 61 6c 6c 20 64 61  anged for all da
8f50: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
8f60: 6e 73 0a 2a 2a 20 77 69 74 68 69 6e 20 74 68 65  ns.** within the
8f70: 20 73 61 6d 65 20 70 72 6f 63 65 73 73 2e 20 20   same process.  
8f80: 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  The argument is 
8f90: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
8fa0: 61 72 72 61 79 20 6f 66 20 74 77 6f 0a 2a 2a 20  array of two.** 
8fb0: 69 6e 74 65 67 65 72 73 20 77 68 65 72 65 20 74  integers where t
8fc0: 68 65 20 66 69 72 73 74 20 69 6e 74 65 67 65 72  he first integer
8fd0: 20 69 20 74 68 65 20 6e 65 77 20 72 65 74 72 79   i the new retry
8fe0: 20 63 6f 75 6e 74 20 61 6e 64 20 74 68 65 20 73   count and the s
8ff0: 65 63 6f 6e 64 0a 2a 2a 20 69 6e 74 65 67 65 72  econd.** integer
9000: 20 69 73 20 74 68 65 20 64 65 6c 61 79 2e 20 20   is the delay.  
9010: 49 66 20 65 69 74 68 65 72 20 69 6e 74 65 67 65  If either intege
9020: 72 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74  r is negative, t
9030: 68 65 6e 20 74 68 65 20 73 65 74 74 69 6e 67 0a  hen the setting.
9040: 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65  ** is not change
9050: 64 20 62 75 74 20 69 6e 73 74 65 61 64 20 74 68  d but instead th
9060: 65 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66  e prior value of
9070: 20 74 68 61 74 20 73 65 74 74 69 6e 67 20 69 73   that setting is
9080: 20 77 72 69 74 74 65 6e 0a 2a 2a 20 69 6e 74 6f   written.** into
9090: 20 74 68 65 20 61 72 72 61 79 20 65 6e 74 72 79   the array entry
90a0: 2c 20 61 6c 6c 6f 77 69 6e 67 20 74 68 65 20 63  , allowing the c
90b0: 75 72 72 65 6e 74 20 72 65 74 72 79 20 73 65 74  urrent retry set
90c0: 74 69 6e 67 73 20 74 6f 20 62 65 0a 2a 2a 20 69  tings to be.** i
90d0: 6e 74 65 72 72 6f 67 61 74 65 64 2e 20 20 54 68  nterrogated.  Th
90e0: 65 20 7a 44 62 4e 61 6d 65 20 70 61 72 61 6d 65  e zDbName parame
90f0: 74 65 72 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a  ter is ignored..
9100: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
9110: 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54  TE_FCNTL_PERSIST
9120: 5f 57 41 4c 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b  _WAL]].** ^The [
9130: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52  SQLITE_FCNTL_PER
9140: 53 49 53 54 5f 57 41 4c 5d 20 6f 70 63 6f 64 65  SIST_WAL] opcode
9150: 20 69 73 20 75 73 65 64 20 74 6f 20 73 65 74 20   is used to set 
9160: 6f 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a 20  or query the.** 
9170: 70 65 72 73 69 73 74 65 6e 74 20 5b 57 41 4c 20  persistent [WAL 
9180: 7c 20 57 72 69 74 65 20 41 68 65 61 64 20 4c 6f  | Write Ahead Lo
9190: 67 5d 20 73 65 74 74 69 6e 67 2e 20 20 42 79 20  g] setting.  By 
91a0: 64 65 66 61 75 6c 74 2c 20 74 68 65 20 61 75 78  default, the aux
91b0: 69 6c 69 61 72 79 0a 2a 2a 20 77 72 69 74 65 20  iliary.** write 
91c0: 61 68 65 61 64 20 6c 6f 67 20 61 6e 64 20 73 68  ahead log and sh
91d0: 61 72 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c 65  ared memory file
91e0: 73 20 75 73 65 64 20 66 6f 72 20 74 72 61 6e 73  s used for trans
91f0: 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 0a 2a  action control.*
9200: 2a 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61  * are automatica
9210: 6c 6c 79 20 64 65 6c 65 74 65 64 20 77 68 65 6e  lly deleted when
9220: 20 74 68 65 20 6c 61 74 65 73 74 20 63 6f 6e 6e   the latest conn
9230: 65 63 74 69 6f 6e 20 74 6f 20 74 68 65 20 64 61  ection to the da
9240: 74 61 62 61 73 65 0a 2a 2a 20 63 6c 6f 73 65 73  tabase.** closes
9250: 2e 20 20 53 65 74 74 69 6e 67 20 70 65 72 73 69  .  Setting persi
9260: 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 63  stent WAL mode c
9270: 61 75 73 65 73 20 74 68 6f 73 65 20 66 69 6c 65  auses those file
9280: 73 20 74 6f 20 70 65 72 73 69 73 74 20 61 66 74  s to persist aft
9290: 65 72 0a 2a 2a 20 63 6c 6f 73 65 2e 20 20 50 65  er.** close.  Pe
92a0: 72 73 69 73 74 69 6e 67 20 74 68 65 20 66 69 6c  rsisting the fil
92b0: 65 73 20 69 73 20 75 73 65 66 75 6c 20 77 68 65  es is useful whe
92c0: 6e 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73 65  n other processe
92d0: 73 20 74 68 61 74 20 64 6f 20 6e 6f 74 0a 2a 2a  s that do not.**
92e0: 20 68 61 76 65 20 77 72 69 74 65 20 70 65 72 6d   have write perm
92f0: 69 73 73 69 6f 6e 20 6f 6e 20 74 68 65 20 64 69  ission on the di
9300: 72 65 63 74 6f 72 79 20 63 6f 6e 74 61 69 6e 69  rectory containi
9310: 6e 67 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ng the database 
9320: 66 69 6c 65 20 77 61 6e 74 0a 2a 2a 20 74 6f 20  file want.** to 
9330: 72 65 61 64 20 74 68 65 20 64 61 74 61 62 61 73  read the databas
9340: 65 20 66 69 6c 65 2c 20 61 73 20 74 68 65 20 57  e file, as the W
9350: 41 4c 20 61 6e 64 20 73 68 61 72 65 64 20 6d 65  AL and shared me
9360: 6d 6f 72 79 20 66 69 6c 65 73 20 6d 75 73 74 20  mory files must 
9370: 65 78 69 73 74 0a 2a 2a 20 69 6e 20 6f 72 64 65  exist.** in orde
9380: 72 20 66 6f 72 20 74 68 65 20 64 61 74 61 62 61  r for the databa
9390: 73 65 20 74 6f 20 62 65 20 72 65 61 64 61 62 6c  se to be readabl
93a0: 65 2e 20 20 54 68 65 20 66 6f 75 72 74 68 20 70  e.  The fourth p
93b0: 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b  arameter to.** [
93c0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
93d0: 74 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 73  trol()] for this
93e0: 20 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 62   opcode should b
93f0: 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  e a pointer to a
9400: 6e 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68  n integer..** Th
9410: 61 74 20 69 6e 74 65 67 65 72 20 69 73 20 30 20  at integer is 0 
9420: 74 6f 20 64 69 73 61 62 6c 65 20 70 65 72 73 69  to disable persi
9430: 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 6f  stent WAL mode o
9440: 72 20 31 20 74 6f 20 65 6e 61 62 6c 65 20 70 65  r 1 to enable pe
9450: 72 73 69 73 74 65 6e 74 0a 2a 2a 20 57 41 4c 20  rsistent.** WAL 
9460: 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e  mode.  If the in
9470: 74 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65  teger is -1, the
9480: 6e 20 69 74 20 69 73 20 6f 76 65 72 77 72 69 74  n it is overwrit
9490: 74 65 6e 20 77 69 74 68 20 74 68 65 20 63 75 72  ten with the cur
94a0: 72 65 6e 74 0a 2a 2a 20 57 41 4c 20 70 65 72 73  rent.** WAL pers
94b0: 69 73 74 65 6e 63 65 20 73 65 74 74 69 6e 67 2e  istence setting.
94c0: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
94d0: 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53  ITE_FCNTL_POWERS
94e0: 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a  AFE_OVERWRITE]].
94f0: 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
9500: 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f  FCNTL_POWERSAFE_
9510: 4f 56 45 52 57 52 49 54 45 5d 20 6f 70 63 6f 64  OVERWRITE] opcod
9520: 65 20 69 73 20 75 73 65 64 20 74 6f 20 73 65 74  e is used to set
9530: 20 6f 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a   or query the.**
9540: 20 70 65 72 73 69 73 74 65 6e 74 20 22 70 6f 77   persistent "pow
9550: 65 72 73 61 66 65 2d 6f 76 65 72 77 72 69 74 65  ersafe-overwrite
9560: 22 20 6f 72 20 22 50 53 4f 57 22 20 73 65 74 74  " or "PSOW" sett
9570: 69 6e 67 2e 20 20 54 68 65 20 50 53 4f 57 20 73  ing.  The PSOW s
9580: 65 74 74 69 6e 67 0a 2a 2a 20 64 65 74 65 72 6d  etting.** determ
9590: 69 6e 65 73 20 74 68 65 20 5b 53 51 4c 49 54 45  ines the [SQLITE
95a0: 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45  _IOCAP_POWERSAFE
95b0: 5f 4f 56 45 52 57 52 49 54 45 5d 20 62 69 74 20  _OVERWRITE] bit 
95c0: 6f 66 20 74 68 65 0a 2a 2a 20 78 44 65 76 69 63  of the.** xDevic
95d0: 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73  eCharacteristics
95e0: 20 6d 65 74 68 6f 64 73 2e 20 54 68 65 20 66 6f   methods. The fo
95f0: 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  urth parameter t
9600: 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  o.** [sqlite3_fi
9610: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f  le_control()] fo
9620: 72 20 74 68 69 73 20 6f 70 63 6f 64 65 20 73 68  r this opcode sh
9630: 6f 75 6c 64 20 62 65 20 61 20 70 6f 69 6e 74 65  ould be a pointe
9640: 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e  r to an integer.
9650: 0a 2a 2a 20 54 68 61 74 20 69 6e 74 65 67 65 72  .** That integer
9660: 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65   is 0 to disable
9670: 20 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64   zero-damage mod
9680: 65 20 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c 65  e or 1 to enable
9690: 20 7a 65 72 6f 2d 64 61 6d 61 67 65 0a 2a 2a 20   zero-damage.** 
96a0: 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e  mode.  If the in
96b0: 74 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65  teger is -1, the
96c0: 6e 20 69 74 20 69 73 20 6f 76 65 72 77 72 69 74  n it is overwrit
96d0: 74 65 6e 20 77 69 74 68 20 74 68 65 20 63 75 72  ten with the cur
96e0: 72 65 6e 74 0a 2a 2a 20 7a 65 72 6f 2d 64 61 6d  rent.** zero-dam
96f0: 61 67 65 20 6d 6f 64 65 20 73 65 74 74 69 6e 67  age mode setting
9700: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
9710: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57  LITE_FCNTL_OVERW
9720: 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b  RITE]].** ^The [
9730: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45  SQLITE_FCNTL_OVE
9740: 52 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 69  RWRITE] opcode i
9750: 73 20 69 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c  s invoked by SQL
9760: 69 74 65 20 61 66 74 65 72 20 6f 70 65 6e 69 6e  ite after openin
9770: 67 0a 2a 2a 20 61 20 77 72 69 74 65 20 74 72 61  g.** a write tra
9780: 6e 73 61 63 74 69 6f 6e 20 74 6f 20 69 6e 64 69  nsaction to indi
9790: 63 61 74 65 20 74 68 61 74 2c 20 75 6e 6c 65 73  cate that, unles
97a0: 73 20 69 74 20 69 73 20 72 6f 6c 6c 65 64 20 62  s it is rolled b
97b0: 61 63 6b 20 66 6f 72 20 73 6f 6d 65 0a 2a 2a 20  ack for some.** 
97c0: 72 65 61 73 6f 6e 2c 20 74 68 65 20 65 6e 74 69  reason, the enti
97d0: 72 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  re database file
97e0: 20 77 69 6c 6c 20 62 65 20 6f 76 65 72 77 72 69   will be overwri
97f0: 74 74 65 6e 20 62 79 20 74 68 65 20 63 75 72 72  tten by the curr
9800: 65 6e 74 20 0a 2a 2a 20 74 72 61 6e 73 61 63 74  ent .** transact
9810: 69 6f 6e 2e 20 54 68 69 73 20 69 73 20 75 73 65  ion. This is use
9820: 64 20 62 79 20 56 41 43 55 55 4d 20 6f 70 65 72  d by VACUUM oper
9830: 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  ations..**.** <l
9840: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
9850: 5f 56 46 53 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 54  _VFSNAME]].** ^T
9860: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
9870: 5f 56 46 53 4e 41 4d 45 5d 20 6f 70 63 6f 64 65  _VFSNAME] opcode
9880: 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
9890: 6f 62 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73  obtain the names
98a0: 20 6f 66 0a 2a 2a 20 61 6c 6c 20 5b 56 46 53 65   of.** all [VFSe
98b0: 73 5d 20 69 6e 20 74 68 65 20 56 46 53 20 73 74  s] in the VFS st
98c0: 61 63 6b 2e 20 20 54 68 65 20 6e 61 6d 65 73 20  ack.  The names 
98d0: 61 72 65 20 6f 66 20 61 6c 6c 20 56 46 53 20 73  are of all VFS s
98e0: 68 69 6d 73 20 61 6e 64 20 74 68 65 0a 2a 2a 20  hims and the.** 
98f0: 66 69 6e 61 6c 20 62 6f 74 74 6f 6d 2d 6c 65 76  final bottom-lev
9900: 65 6c 20 56 46 53 20 61 72 65 20 77 72 69 74 74  el VFS are writt
9910: 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f  en into memory o
9920: 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a  btained from .**
9930: 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
9940: 28 29 5d 20 61 6e 64 20 74 68 65 20 72 65 73 75  ()] and the resu
9950: 6c 74 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20  lt is stored in 
9960: 74 68 65 20 63 68 61 72 2a 20 76 61 72 69 61 62  the char* variab
9970: 6c 65 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 66  le.** that the f
9980: 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
9990: 6f 66 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  of [sqlite3_file
99a0: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 70 6f 69 6e  _control()] poin
99b0: 74 73 20 74 6f 2e 0a 2a 2a 20 54 68 65 20 63 61  ts to..** The ca
99c0: 6c 6c 65 72 20 69 73 20 72 65 73 70 6f 6e 73 69  ller is responsi
99d0: 62 6c 65 20 66 6f 72 20 66 72 65 65 69 6e 67 20  ble for freeing 
99e0: 74 68 65 20 6d 65 6d 6f 72 79 20 77 68 65 6e 20  the memory when 
99f0: 64 6f 6e 65 2e 20 20 41 73 20 77 69 74 68 0a 2a  done.  As with.*
9a00: 2a 20 61 6c 6c 20 66 69 6c 65 2d 63 6f 6e 74 72  * all file-contr
9a10: 6f 6c 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 72  ol actions, ther
9a20: 65 20 69 73 20 6e 6f 20 67 75 61 72 61 6e 74 65  e is no guarante
9a30: 65 20 74 68 61 74 20 74 68 69 73 20 77 69 6c 6c  e that this will
9a40: 20 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 64 6f 20   actually.** do 
9a50: 61 6e 79 74 68 69 6e 67 2e 20 20 43 61 6c 6c 65  anything.  Calle
9a60: 72 73 20 73 68 6f 75 6c 64 20 69 6e 69 74 69 61  rs should initia
9a70: 6c 69 7a 65 20 74 68 65 20 63 68 61 72 2a 20 76  lize the char* v
9a80: 61 72 69 61 62 6c 65 20 74 6f 20 61 20 4e 55 4c  ariable to a NUL
9a90: 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 20  L.** pointer in 
9aa0: 63 61 73 65 20 74 68 69 73 20 66 69 6c 65 2d 63  case this file-c
9ab0: 6f 6e 74 72 6f 6c 20 69 73 20 6e 6f 74 20 69 6d  ontrol is not im
9ac0: 70 6c 65 6d 65 6e 74 65 64 2e 20 20 54 68 69 73  plemented.  This
9ad0: 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a   file-control.**
9ae0: 20 69 73 20 69 6e 74 65 6e 64 65 64 20 66 6f 72   is intended for
9af0: 20 64 69 61 67 6e 6f 73 74 69 63 20 75 73 65 20   diagnostic use 
9b00: 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  only..**.** <li>
9b10: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50  [[SQLITE_FCNTL_P
9b20: 52 41 47 4d 41 5d 5d 0a 2a 2a 20 5e 57 68 65 6e  RAGMA]].** ^When
9b30: 65 76 65 72 20 61 20 5b 50 52 41 47 4d 41 5d 20  ever a [PRAGMA] 
9b40: 73 74 61 74 65 6d 65 6e 74 20 69 73 20 70 61 72  statement is par
9b50: 73 65 64 2c 20 61 6e 20 5b 53 51 4c 49 54 45 5f  sed, an [SQLITE_
9b60: 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 0a 2a  FCNTL_PRAGMA] .*
9b70: 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69  * file control i
9b80: 73 20 73 65 6e 74 20 74 6f 20 74 68 65 20 6f 70  s sent to the op
9b90: 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  en [sqlite3_file
9ba0: 5d 20 6f 62 6a 65 63 74 20 63 6f 72 72 65 73 70  ] object corresp
9bb0: 6f 6e 64 69 6e 67 0a 2a 2a 20 74 6f 20 74 68 65  onding.** to the
9bc0: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 74   database file t
9bd0: 6f 20 77 68 69 63 68 20 74 68 65 20 70 72 61 67  o which the prag
9be0: 6d 61 20 73 74 61 74 65 6d 65 6e 74 20 72 65 66  ma statement ref
9bf0: 65 72 73 2e 20 5e 54 68 65 20 61 72 67 75 6d 65  ers. ^The argume
9c00: 6e 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 53 51  nt.** to the [SQ
9c10: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d  LITE_FCNTL_PRAGM
9c20: 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  A] file control 
9c30: 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 0a 2a  is an array of.*
9c40: 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74  * pointers to st
9c50: 72 69 6e 67 73 20 28 63 68 61 72 2a 2a 29 20 69  rings (char**) i
9c60: 6e 20 77 68 69 63 68 20 74 68 65 20 73 65 63 6f  n which the seco
9c70: 6e 64 20 65 6c 65 6d 65 6e 74 20 6f 66 20 74 68  nd element of th
9c80: 65 20 61 72 72 61 79 0a 2a 2a 20 69 73 20 74 68  e array.** is th
9c90: 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 70 72  e name of the pr
9ca0: 61 67 6d 61 20 61 6e 64 20 74 68 65 20 74 68 69  agma and the thi
9cb0: 72 64 20 65 6c 65 6d 65 6e 74 20 69 73 20 74 68  rd element is th
9cc0: 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  e argument to th
9cd0: 65 0a 2a 2a 20 70 72 61 67 6d 61 20 6f 72 20 4e  e.** pragma or N
9ce0: 55 4c 4c 20 69 66 20 74 68 65 20 70 72 61 67 6d  ULL if the pragm
9cf0: 61 20 68 61 73 20 6e 6f 20 61 72 67 75 6d 65 6e  a has no argumen
9d00: 74 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 72  t.  ^The handler
9d10: 20 66 6f 72 20 61 6e 0a 2a 2a 20 5b 53 51 4c 49   for an.** [SQLI
9d20: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d  TE_FCNTL_PRAGMA]
9d30: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 63 61   file control ca
9d40: 6e 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 6d 61 6b  n optionally mak
9d50: 65 20 74 68 65 20 66 69 72 73 74 20 65 6c 65 6d  e the first elem
9d60: 65 6e 74 0a 2a 2a 20 6f 66 20 74 68 65 20 63 68  ent.** of the ch
9d70: 61 72 2a 2a 20 61 72 67 75 6d 65 6e 74 20 70 6f  ar** argument po
9d80: 69 6e 74 20 74 6f 20 61 20 73 74 72 69 6e 67 20  int to a string 
9d90: 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73  obtained from [s
9da0: 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29  qlite3_mprintf()
9db0: 5d 0a 2a 2a 20 6f 72 20 74 68 65 20 65 71 75 69  ].** or the equi
9dc0: 76 61 6c 65 6e 74 20 61 6e 64 20 74 68 61 74 20  valent and that 
9dd0: 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 63 6f  string will beco
9de0: 6d 65 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66  me the result of
9df0: 20 74 68 65 20 70 72 61 67 6d 61 20 6f 72 0a 2a   the pragma or.*
9e00: 2a 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73  * the error mess
9e10: 61 67 65 20 69 66 20 74 68 65 20 70 72 61 67 6d  age if the pragm
9e20: 61 20 66 61 69 6c 73 2e 20 5e 49 66 20 74 68 65  a fails. ^If the
9e30: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  .** [SQLITE_FCNT
9e40: 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63  L_PRAGMA] file c
9e50: 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b  ontrol returns [
9e60: 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d  SQLITE_NOTFOUND]
9e70: 2c 20 74 68 65 6e 20 6e 6f 72 6d 61 6c 20 0a 2a  , then normal .*
9e80: 2a 20 5b 50 52 41 47 4d 41 5d 20 70 72 6f 63 65  * [PRAGMA] proce
9e90: 73 73 69 6e 67 20 63 6f 6e 74 69 6e 75 65 73 2e  ssing continues.
9ea0: 20 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54    ^If the [SQLIT
9eb0: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a  E_FCNTL_PRAGMA].
9ec0: 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  ** file control 
9ed0: 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
9ee0: 4f 4b 5d 2c 20 74 68 65 6e 20 74 68 65 20 70 61  OK], then the pa
9ef0: 72 73 65 72 20 61 73 73 75 6d 65 73 20 74 68 61  rser assumes tha
9f00: 74 20 74 68 65 0a 2a 2a 20 56 46 53 20 68 61 73  t the.** VFS has
9f10: 20 68 61 6e 64 6c 65 64 20 74 68 65 20 50 52 41   handled the PRA
9f20: 47 4d 41 20 69 74 73 65 6c 66 20 61 6e 64 20 74  GMA itself and t
9f30: 68 65 20 70 61 72 73 65 72 20 67 65 6e 65 72 61  he parser genera
9f40: 74 65 73 20 61 20 6e 6f 2d 6f 70 0a 2a 2a 20 70  tes a no-op.** p
9f50: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
9f60: 74 2e 20 20 5e 49 66 20 74 68 65 20 5b 53 51 4c  t.  ^If the [SQL
9f70: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41  ITE_FCNTL_PRAGMA
9f80: 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72  ] file control r
9f90: 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 72 65  eturns.** any re
9fa0: 73 75 6c 74 20 63 6f 64 65 20 6f 74 68 65 72 20  sult code other 
9fb0: 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  than [SQLITE_OK]
9fc0: 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46   or [SQLITE_NOTF
9fd0: 4f 55 4e 44 5d 2c 20 74 68 61 74 20 6d 65 61 6e  OUND], that mean
9fe0: 73 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 56 46  s.** that the VF
9ff0: 53 20 65 6e 63 6f 75 6e 74 65 72 65 64 20 61 6e  S encountered an
a000: 20 65 72 72 6f 72 20 77 68 69 6c 65 20 68 61 6e   error while han
a010: 64 6c 69 6e 67 20 74 68 65 20 5b 50 52 41 47 4d  dling the [PRAGM
a020: 41 5d 20 61 6e 64 20 74 68 65 0a 2a 2a 20 63 6f  A] and the.** co
a030: 6d 70 69 6c 61 74 69 6f 6e 20 6f 66 20 74 68 65  mpilation of the
a040: 20 50 52 41 47 4d 41 20 66 61 69 6c 73 20 77 69   PRAGMA fails wi
a050: 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e 54  th an error.  ^T
a060: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
a070: 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65  _PRAGMA].** file
a080: 20 63 6f 6e 74 72 6f 6c 20 6f 63 63 75 72 73 20   control occurs 
a090: 61 74 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67  at the beginning
a0a0: 20 6f 66 20 70 72 61 67 6d 61 20 73 74 61 74 65   of pragma state
a0b0: 6d 65 6e 74 20 61 6e 61 6c 79 73 69 73 20 61 6e  ment analysis an
a0c0: 64 20 73 6f 0a 2a 2a 20 69 74 20 69 73 20 61 62  d so.** it is ab
a0d0: 6c 65 20 74 6f 20 6f 76 65 72 72 69 64 65 20 62  le to override b
a0e0: 75 69 6c 74 2d 69 6e 20 5b 50 52 41 47 4d 41 5d  uilt-in [PRAGMA]
a0f0: 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20   statements..** 
a100: 3c 2f 75 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65  </ul>.*/.#define
a110: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f   SQLITE_FCNTL_LO
a120: 43 4b 53 54 41 54 45 20 20 20 20 20 20 20 20 20  CKSTATE         
a130: 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20        1.#define 
a140: 53 51 4c 49 54 45 5f 47 45 54 5f 4c 4f 43 4b 50  SQLITE_GET_LOCKP
a150: 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20 20 20  ROXYFILE        
a160: 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53       2.#define S
a170: 51 4c 49 54 45 5f 53 45 54 5f 4c 4f 43 4b 50 52  QLITE_SET_LOCKPR
a180: 4f 58 59 46 49 4c 45 20 20 20 20 20 20 20 20 20  OXYFILE         
a190: 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51      3.#define SQ
a1a0: 4c 49 54 45 5f 4c 41 53 54 5f 45 52 52 4e 4f 20  LITE_LAST_ERRNO 
a1b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
a1c0: 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c     4.#define SQL
a1d0: 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48  ITE_FCNTL_SIZE_H
a1e0: 49 4e 54 20 20 20 20 20 20 20 20 20 20 20 20 20  INT             
a1f0: 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    5.#define SQLI
a200: 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53  TE_FCNTL_CHUNK_S
a210: 49 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 20  IZE             
a220: 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   6.#define SQLIT
a230: 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49  E_FCNTL_FILE_POI
a240: 4e 54 45 52 20 20 20 20 20 20 20 20 20 20 20 20  NTER            
a250: 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  7.#define SQLITE
a260: 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54  _FCNTL_SYNC_OMIT
a270: 54 45 44 20 20 20 20 20 20 20 20 20 20 20 20 38  TED            8
a280: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
a290: 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52  FCNTL_WIN32_AV_R
a2a0: 45 54 52 59 20 20 20 20 20 20 20 20 20 20 39 0a  ETRY          9.
a2b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
a2c0: 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c  CNTL_PERSIST_WAL
a2d0: 20 20 20 20 20 20 20 20 20 20 20 20 31 30 0a 23              10.#
a2e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
a2f0: 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 20 20 20  NTL_OVERWRITE   
a300: 20 20 20 20 20 20 20 20 20 20 20 31 31 0a 23 64             11.#d
a310: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
a320: 54 4c 5f 56 46 53 4e 41 4d 45 20 20 20 20 20 20  TL_VFSNAME      
a330: 20 20 20 20 20 20 20 20 20 20 31 32 0a 23 64 65            12.#de
a340: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
a350: 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52  L_POWERSAFE_OVER
a360: 57 52 49 54 45 20 20 20 20 31 33 0a 23 64 65 66  WRITE    13.#def
a370: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
a380: 5f 50 52 41 47 4d 41 20 20 20 20 20 20 20 20 20  _PRAGMA         
a390: 20 20 20 20 20 20 20 20 31 34 0a 0a 2f 2a 0a 2a          14../*.*
a3a0: 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65  * CAPI3REF: Mute
a3b0: 78 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 54  x Handle.**.** T
a3c0: 68 65 20 6d 75 74 65 78 20 6d 6f 64 75 6c 65 20  he mutex module 
a3d0: 77 69 74 68 69 6e 20 53 51 4c 69 74 65 20 64 65  within SQLite de
a3e0: 66 69 6e 65 73 20 5b 73 71 6c 69 74 65 33 5f 6d  fines [sqlite3_m
a3f0: 75 74 65 78 5d 20 74 6f 20 62 65 20 61 6e 0a 2a  utex] to be an.*
a400: 2a 20 61 62 73 74 72 61 63 74 20 74 79 70 65 20  * abstract type 
a410: 66 6f 72 20 61 20 6d 75 74 65 78 20 6f 62 6a 65  for a mutex obje
a420: 63 74 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20  ct.  The SQLite 
a430: 63 6f 72 65 20 6e 65 76 65 72 20 6c 6f 6f 6b 73  core never looks
a440: 0a 2a 2a 20 61 74 20 74 68 65 20 69 6e 74 65 72  .** at the inter
a450: 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69  nal representati
a460: 6f 6e 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65  on of an [sqlite
a470: 33 5f 6d 75 74 65 78 5d 2e 20 20 49 74 20 6f 6e  3_mutex].  It on
a480: 6c 79 0a 2a 2a 20 64 65 61 6c 73 20 77 69 74 68  ly.** deals with
a490: 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 65   pointers to the
a4a0: 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d   [sqlite3_mutex]
a4b0: 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d   object..**.** M
a4c0: 75 74 65 78 65 73 20 61 72 65 20 63 72 65 61 74  utexes are creat
a4d0: 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
a4e0: 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d  3_mutex_alloc()]
a4f0: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
a500: 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  uct sqlite3_mute
a510: 78 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 3b  x sqlite3_mutex;
a520: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
a530: 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f  : OS Interface O
a540: 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 41 6e 20 69  bject.**.** An i
a550: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 73  nstance of the s
a560: 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63  qlite3_vfs objec
a570: 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e  t defines the in
a580: 74 65 72 66 61 63 65 20 62 65 74 77 65 65 6e 0a  terface between.
a590: 2a 2a 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f  ** the SQLite co
a5a0: 72 65 20 61 6e 64 20 74 68 65 20 75 6e 64 65 72  re and the under
a5b0: 6c 79 69 6e 67 20 6f 70 65 72 61 74 69 6e 67 20  lying operating 
a5c0: 73 79 73 74 65 6d 2e 20 20 54 68 65 20 22 76 66  system.  The "vf
a5d0: 73 22 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 6d  s".** in the nam
a5e0: 65 20 6f 66 20 74 68 65 20 6f 62 6a 65 63 74 20  e of the object 
a5f0: 73 74 61 6e 64 73 20 66 6f 72 20 22 76 69 72 74  stands for "virt
a600: 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 22  ual file system"
a610: 2e 20 20 53 65 65 0a 2a 2a 20 74 68 65 20 5b 56  .  See.** the [V
a620: 46 53 20 7c 20 56 46 53 20 64 6f 63 75 6d 65 6e  FS | VFS documen
a630: 74 61 74 69 6f 6e 5d 20 66 6f 72 20 66 75 72 74  tation] for furt
a640: 68 65 72 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  her information.
a650: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65  .**.** The value
a660: 20 6f 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e   of the iVersion
a670: 20 66 69 65 6c 64 20 69 73 20 69 6e 69 74 69 61   field is initia
a680: 6c 6c 79 20 31 20 62 75 74 20 6d 61 79 20 62 65  lly 1 but may be
a690: 20 6c 61 72 67 65 72 20 69 6e 0a 2a 2a 20 66 75   larger in.** fu
a6a0: 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66  ture versions of
a6b0: 20 53 51 4c 69 74 65 2e 20 20 41 64 64 69 74 69   SQLite.  Additi
a6c0: 6f 6e 61 6c 20 66 69 65 6c 64 73 20 6d 61 79 20  onal fields may 
a6d0: 62 65 20 61 70 70 65 6e 64 65 64 20 74 6f 20 74  be appended to t
a6e0: 68 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 77 68  his.** object wh
a6f0: 65 6e 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20  en the iVersion 
a700: 76 61 6c 75 65 20 69 73 20 69 6e 63 72 65 61 73  value is increas
a710: 65 64 2e 20 20 4e 6f 74 65 20 74 68 61 74 20 74  ed.  Note that t
a720: 68 65 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20  he structure.** 
a730: 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76  of the sqlite3_v
a740: 66 73 20 6f 62 6a 65 63 74 20 63 68 61 6e 67 65  fs object change
a750: 73 20 69 6e 20 74 68 65 20 74 72 61 6e 73 61 63  s in the transac
a760: 74 69 6f 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20  tion between.** 
a770: 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33  SQLite version 3
a780: 2e 35 2e 39 20 61 6e 64 20 33 2e 36 2e 30 20 61  .5.9 and 3.6.0 a
a790: 6e 64 20 79 65 74 20 74 68 65 20 69 56 65 72 73  nd yet the iVers
a7a0: 69 6f 6e 20 66 69 65 6c 64 20 77 61 73 20 6e 6f  ion field was no
a7b0: 74 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 2e 0a 2a  t.** modified..*
a7c0: 2a 0a 2a 2a 20 54 68 65 20 73 7a 4f 73 46 69 6c  *.** The szOsFil
a7d0: 65 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 73  e field is the s
a7e0: 69 7a 65 20 6f 66 20 74 68 65 20 73 75 62 63 6c  ize of the subcl
a7f0: 61 73 73 65 64 20 5b 73 71 6c 69 74 65 33 5f 66  assed [sqlite3_f
a800: 69 6c 65 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72  ile].** structur
a810: 65 20 75 73 65 64 20 62 79 20 74 68 69 73 20 56  e used by this V
a820: 46 53 2e 20 20 6d 78 50 61 74 68 6e 61 6d 65 20  FS.  mxPathname 
a830: 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6c  is the maximum l
a840: 65 6e 67 74 68 20 6f 66 0a 2a 2a 20 61 20 70 61  ength of.** a pa
a850: 74 68 6e 61 6d 65 20 69 6e 20 74 68 69 73 20 56  thname in this V
a860: 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74  FS..**.** Regist
a870: 65 72 65 64 20 73 71 6c 69 74 65 33 5f 76 66 73  ered sqlite3_vfs
a880: 20 6f 62 6a 65 63 74 73 20 61 72 65 20 6b 65 70   objects are kep
a890: 74 20 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 6c 69  t on a linked li
a8a0: 73 74 20 66 6f 72 6d 65 64 20 62 79 0a 2a 2a 20  st formed by.** 
a8b0: 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65  the pNext pointe
a8c0: 72 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33  r.  The [sqlite3
a8d0: 5f 76 66 73 5f 72 65 67 69 73 74 65 72 28 29 5d  _vfs_register()]
a8e0: 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  .** and [sqlite3
a8f0: 5f 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28  _vfs_unregister(
a900: 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61  )] interfaces ma
a910: 6e 61 67 65 20 74 68 69 73 20 6c 69 73 74 0a 2a  nage this list.*
a920: 2a 20 69 6e 20 61 20 74 68 72 65 61 64 2d 73 61  * in a thread-sa
a930: 66 65 20 77 61 79 2e 20 20 54 68 65 20 5b 73 71  fe way.  The [sq
a940: 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 29  lite3_vfs_find()
a950: 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 73  ] interface.** s
a960: 65 61 72 63 68 65 73 20 74 68 65 20 6c 69 73 74  earches the list
a970: 2e 20 20 4e 65 69 74 68 65 72 20 74 68 65 20 61  .  Neither the a
a980: 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20  pplication code 
a990: 6e 6f 72 20 74 68 65 20 56 46 53 0a 2a 2a 20 69  nor the VFS.** i
a9a0: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68  mplementation sh
a9b0: 6f 75 6c 64 20 75 73 65 20 74 68 65 20 70 4e 65  ould use the pNe
a9c0: 78 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  xt pointer..**.*
a9d0: 2a 20 54 68 65 20 70 4e 65 78 74 20 66 69 65 6c  * The pNext fiel
a9e0: 64 20 69 73 20 74 68 65 20 6f 6e 6c 79 20 66 69  d is the only fi
a9f0: 65 6c 64 20 69 6e 20 74 68 65 20 73 71 6c 69 74  eld in the sqlit
aa00: 65 33 5f 76 66 73 0a 2a 2a 20 73 74 72 75 63 74  e3_vfs.** struct
aa10: 75 72 65 20 74 68 61 74 20 53 51 4c 69 74 65 20  ure that SQLite 
aa20: 77 69 6c 6c 20 65 76 65 72 20 6d 6f 64 69 66 79  will ever modify
aa30: 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f  .  SQLite will o
aa40: 6e 6c 79 20 61 63 63 65 73 73 0a 2a 2a 20 6f 72  nly access.** or
aa50: 20 6d 6f 64 69 66 79 20 74 68 69 73 20 66 69 65   modify this fie
aa60: 6c 64 20 77 68 69 6c 65 20 68 6f 6c 64 69 6e 67  ld while holding
aa70: 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 73 74   a particular st
aa80: 61 74 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 20 54  atic mutex..** T
aa90: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73  he application s
aaa0: 68 6f 75 6c 64 20 6e 65 76 65 72 20 6d 6f 64 69  hould never modi
aab0: 66 79 20 61 6e 79 74 68 69 6e 67 20 77 69 74 68  fy anything with
aac0: 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76  in the sqlite3_v
aad0: 66 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e 63  fs.** object onc
aae0: 65 20 74 68 65 20 6f 62 6a 65 63 74 20 68 61 73  e the object has
aaf0: 20 62 65 65 6e 20 72 65 67 69 73 74 65 72 65 64   been registered
ab00: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d  ..**.** The zNam
ab10: 65 20 66 69 65 6c 64 20 68 6f 6c 64 73 20 74 68  e field holds th
ab20: 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 56 46  e name of the VF
ab30: 53 20 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20 6e  S module.  The n
ab40: 61 6d 65 20 6d 75 73 74 0a 2a 2a 20 62 65 20 75  ame must.** be u
ab50: 6e 69 71 75 65 20 61 63 72 6f 73 73 20 61 6c 6c  nique across all
ab60: 20 56 46 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a   VFS modules..**
ab70: 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66  .** [[sqlite3_vf
ab80: 73 2e 78 4f 70 65 6e 5d 5d 0a 2a 2a 20 5e 53 51  s.xOpen]].** ^SQ
ab90: 4c 69 74 65 20 67 75 61 72 61 6e 74 65 65 73 20  Lite guarantees 
aba0: 74 68 61 74 20 74 68 65 20 7a 46 69 6c 65 6e 61  that the zFilena
abb0: 6d 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  me parameter to 
abc0: 78 4f 70 65 6e 0a 2a 2a 20 69 73 20 65 69 74 68  xOpen.** is eith
abd0: 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  er a NULL pointe
abe0: 72 20 6f 72 20 73 74 72 69 6e 67 20 6f 62 74 61  r or string obta
abf0: 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 78 46 75  ined.** from xFu
ac00: 6c 6c 50 61 74 68 6e 61 6d 65 28 29 20 77 69 74  llPathname() wit
ac10: 68 20 61 6e 20 6f 70 74 69 6f 6e 61 6c 20 73 75  h an optional su
ac20: 66 66 69 78 20 61 64 64 65 64 2e 0a 2a 2a 20 5e  ffix added..** ^
ac30: 49 66 20 61 20 73 75 66 66 69 78 20 69 73 20 61  If a suffix is a
ac40: 64 64 65 64 20 74 6f 20 74 68 65 20 7a 46 69 6c  dded to the zFil
ac50: 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 2c  ename parameter,
ac60: 20 69 74 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 73   it will.** cons
ac70: 69 73 74 20 6f 66 20 61 20 73 69 6e 67 6c 65 20  ist of a single 
ac80: 22 2d 22 20 63 68 61 72 61 63 74 65 72 20 66 6f  "-" character fo
ac90: 6c 6c 6f 77 65 64 20 62 79 20 6e 6f 20 6d 6f 72  llowed by no mor
aca0: 65 20 74 68 61 6e 0a 2a 2a 20 31 31 20 61 6c 70  e than.** 11 alp
acb0: 68 61 6e 75 6d 65 72 69 63 20 61 6e 64 2f 6f 72  hanumeric and/or
acc0: 20 22 2d 22 20 63 68 61 72 61 63 74 65 72 73 2e   "-" characters.
acd0: 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 66 75 72 74  .** ^SQLite furt
ace0: 68 65 72 20 67 75 61 72 61 6e 74 65 65 73 20 74  her guarantees t
acf0: 68 61 74 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e  hat.** the strin
ad00: 67 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20  g will be valid 
ad10: 61 6e 64 20 75 6e 63 68 61 6e 67 65 64 20 75 6e  and unchanged un
ad20: 74 69 6c 20 78 43 6c 6f 73 65 28 29 20 69 73 0a  til xClose() is.
ad30: 2a 2a 20 63 61 6c 6c 65 64 2e 20 42 65 63 61 75  ** called. Becau
ad40: 73 65 20 6f 66 20 74 68 65 20 70 72 65 76 69 6f  se of the previo
ad50: 75 73 20 73 65 6e 74 65 6e 63 65 2c 0a 2a 2a 20  us sentence,.** 
ad60: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  the [sqlite3_fil
ad70: 65 5d 20 63 61 6e 20 73 61 66 65 6c 79 20 73 74  e] can safely st
ad80: 6f 72 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  ore a pointer to
ad90: 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65   the.** filename
ada0: 20 69 66 20 69 74 20 6e 65 65 64 73 20 74 6f 20   if it needs to 
adb0: 72 65 6d 65 6d 62 65 72 20 74 68 65 20 66 69 6c  remember the fil
adc0: 65 6e 61 6d 65 20 66 6f 72 20 73 6f 6d 65 20 72  ename for some r
add0: 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65  eason..** If the
ade0: 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d   zFilename param
adf0: 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 20 69 73  eter to xOpen is
ae00: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
ae10: 74 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a 20 6d 75  then xOpen.** mu
ae20: 73 74 20 69 6e 76 65 6e 74 20 69 74 73 20 6f 77  st invent its ow
ae30: 6e 20 74 65 6d 70 6f 72 61 72 79 20 6e 61 6d 65  n temporary name
ae40: 20 66 6f 72 20 74 68 65 20 66 69 6c 65 2e 20 20   for the file.  
ae50: 5e 57 68 65 6e 65 76 65 72 20 74 68 65 20 0a 2a  ^Whenever the .*
ae60: 2a 20 78 46 69 6c 65 6e 61 6d 65 20 70 61 72 61  * xFilename para
ae70: 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c 20 69 74  meter is NULL it
ae80: 20 77 69 6c 6c 20 61 6c 73 6f 20 62 65 20 74 68   will also be th
ae90: 65 20 63 61 73 65 20 74 68 61 74 20 74 68 65 0a  e case that the.
aea0: 2a 2a 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74  ** flags paramet
aeb0: 65 72 20 77 69 6c 6c 20 69 6e 63 6c 75 64 65 20  er will include 
aec0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c  [SQLITE_OPEN_DEL
aed0: 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a  ETEONCLOSE]..**.
aee0: 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72 67  ** The flags arg
aef0: 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 28 29  ument to xOpen()
af00: 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 62 69   includes all bi
af10: 74 73 20 73 65 74 20 69 6e 0a 2a 2a 20 74 68 65  ts set in.** the
af20: 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20   flags argument 
af30: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  to [sqlite3_open
af40: 5f 76 32 28 29 5d 2e 20 20 4f 72 20 69 66 20 5b  _v2()].  Or if [
af50: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a  sqlite3_open()].
af60: 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f  ** or [sqlite3_o
af70: 70 65 6e 31 36 28 29 5d 20 69 73 20 75 73 65 64  pen16()] is used
af80: 2c 20 74 68 65 6e 20 66 6c 61 67 73 20 69 6e 63  , then flags inc
af90: 6c 75 64 65 73 20 61 74 20 6c 65 61 73 74 0a 2a  ludes at least.*
afa0: 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  * [SQLITE_OPEN_R
afb0: 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c  EADWRITE] | [SQL
afc0: 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d  ITE_OPEN_CREATE]
afd0: 2e 20 0a 2a 2a 20 49 66 20 78 4f 70 65 6e 28 29  . .** If xOpen()
afe0: 20 6f 70 65 6e 73 20 61 20 66 69 6c 65 20 72 65   opens a file re
aff0: 61 64 2d 6f 6e 6c 79 20 74 68 65 6e 20 69 74 20  ad-only then it 
b000: 73 65 74 73 20 2a 70 4f 75 74 46 6c 61 67 73 20  sets *pOutFlags 
b010: 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 5b 53  to.** include [S
b020: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f  QLITE_OPEN_READO
b030: 4e 4c 59 5d 2e 20 20 4f 74 68 65 72 20 62 69 74  NLY].  Other bit
b040: 73 20 69 6e 20 2a 70 4f 75 74 46 6c 61 67 73 20  s in *pOutFlags 
b050: 6d 61 79 20 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a  may be set..**.*
b060: 2a 20 5e 28 53 51 4c 69 74 65 20 77 69 6c 6c 20  * ^(SQLite will 
b070: 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20  also add one of 
b080: 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c  the following fl
b090: 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e  ags to the xOpen
b0a0: 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 70 65  ().** call, depe
b0b0: 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 62 6a  nding on the obj
b0c0: 65 63 74 20 62 65 69 6e 67 20 6f 70 65 6e 65 64  ect being opened
b0d0: 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
b0e0: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
b0f0: 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c  EN_MAIN_DB].** <
b100: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
b110: 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a  N_MAIN_JOURNAL].
b120: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
b130: 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a  _OPEN_TEMP_DB].*
b140: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
b150: 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41  OPEN_TEMP_JOURNA
b160: 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  L].** <li>  [SQL
b170: 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45  ITE_OPEN_TRANSIE
b180: 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  NT_DB].** <li>  
b190: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42  [SQLITE_OPEN_SUB
b1a0: 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e  JOURNAL].** <li>
b1b0: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d    [SQLITE_OPEN_M
b1c0: 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a  ASTER_JOURNAL].*
b1d0: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
b1e0: 4f 50 45 4e 5f 57 41 4c 5d 0a 2a 2a 20 3c 2f 75  OPEN_WAL].** </u
b1f0: 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  l>)^.**.** The f
b200: 69 6c 65 20 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e  ile I/O implemen
b210: 74 61 74 69 6f 6e 20 63 61 6e 20 75 73 65 20 74  tation can use t
b220: 68 65 20 6f 62 6a 65 63 74 20 74 79 70 65 20 66  he object type f
b230: 6c 61 67 73 20 74 6f 0a 2a 2a 20 63 68 61 6e 67  lags to.** chang
b240: 65 20 74 68 65 20 77 61 79 20 69 74 20 64 65 61  e the way it dea
b250: 6c 73 20 77 69 74 68 20 66 69 6c 65 73 2e 20 20  ls with files.  
b260: 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20  For example, an 
b270: 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 74  application.** t
b280: 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 63 61 72  hat does not car
b290: 65 20 61 62 6f 75 74 20 63 72 61 73 68 20 72 65  e about crash re
b2a0: 63 6f 76 65 72 79 20 6f 72 20 72 6f 6c 6c 62 61  covery or rollba
b2b0: 63 6b 20 6d 69 67 68 74 20 6d 61 6b 65 0a 2a 2a  ck might make.**
b2c0: 20 74 68 65 20 6f 70 65 6e 20 6f 66 20 61 20 6a   the open of a j
b2d0: 6f 75 72 6e 61 6c 20 66 69 6c 65 20 61 20 6e 6f  ournal file a no
b2e0: 2d 6f 70 2e 20 20 57 72 69 74 65 73 20 74 6f 20  -op.  Writes to 
b2f0: 74 68 69 73 20 6a 6f 75 72 6e 61 6c 20 77 6f 75  this journal wou
b300: 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62 65 20 6e 6f  ld.** also be no
b310: 2d 6f 70 73 2c 20 61 6e 64 20 61 6e 79 20 61 74  -ops, and any at
b320: 74 65 6d 70 74 20 74 6f 20 72 65 61 64 20 74 68  tempt to read th
b330: 65 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 20  e journal would 
b340: 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54 45  return.** SQLITE
b350: 5f 49 4f 45 52 52 2e 20 20 4f 72 20 74 68 65 20  _IOERR.  Or the 
b360: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d  implementation m
b370: 69 67 68 74 20 72 65 63 6f 67 6e 69 7a 65 20 74  ight recognize t
b380: 68 61 74 20 61 20 64 61 74 61 62 61 73 65 0a 2a  hat a database.*
b390: 2a 20 66 69 6c 65 20 77 69 6c 6c 20 62 65 20 64  * file will be d
b3a0: 6f 69 6e 67 20 70 61 67 65 2d 61 6c 69 67 6e 65  oing page-aligne
b3b0: 64 20 73 65 63 74 6f 72 20 72 65 61 64 73 20 61  d sector reads a
b3c0: 6e 64 20 77 72 69 74 65 73 20 69 6e 20 61 20 72  nd writes in a r
b3d0: 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20 61  andom.** order a
b3e0: 6e 64 20 73 65 74 20 75 70 20 69 74 73 20 49 2f  nd set up its I/
b3f0: 4f 20 73 75 62 73 79 73 74 65 6d 20 61 63 63 6f  O subsystem acco
b400: 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53  rdingly..**.** S
b410: 51 4c 69 74 65 20 6d 69 67 68 74 20 61 6c 73 6f  QLite might also
b420: 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20   add one of the 
b430: 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20  following flags 
b440: 74 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74  to the xOpen met
b450: 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  hod:.**.** <ul>.
b460: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
b470: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f  OPEN_DELETEONCLO
b480: 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  SE].** <li> [SQL
b490: 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49  ITE_OPEN_EXCLUSI
b4a0: 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a  VE].** </ul>.**.
b4b0: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f  ** The [SQLITE_O
b4c0: 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53  PEN_DELETEONCLOS
b4d0: 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73 20 74 68  E] flag means th
b4e0: 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65  e file should be
b4f0: 0a 2a 2a 20 64 65 6c 65 74 65 64 20 77 68 65 6e  .** deleted when
b500: 20 69 74 20 69 73 20 63 6c 6f 73 65 64 2e 20 20   it is closed.  
b510: 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45  ^The [SQLITE_OPE
b520: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d  N_DELETEONCLOSE]
b530: 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73 65 74 20  .** will be set 
b540: 66 6f 72 20 54 45 4d 50 20 64 61 74 61 62 61 73  for TEMP databas
b550: 65 73 20 61 6e 64 20 74 68 65 69 72 20 6a 6f 75  es and their jou
b560: 72 6e 61 6c 73 2c 20 74 72 61 6e 73 69 65 6e 74  rnals, transient
b570: 0a 2a 2a 20 64 61 74 61 62 61 73 65 73 2c 20 61  .** databases, a
b580: 6e 64 20 73 75 62 6a 6f 75 72 6e 61 6c 73 2e 0a  nd subjournals..
b590: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  **.** ^The [SQLI
b5a0: 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56  TE_OPEN_EXCLUSIV
b5b0: 45 5d 20 66 6c 61 67 20 69 73 20 61 6c 77 61 79  E] flag is alway
b5c0: 73 20 75 73 65 64 20 69 6e 20 63 6f 6e 6a 75 6e  s used in conjun
b5d0: 63 74 69 6f 6e 0a 2a 2a 20 77 69 74 68 20 74 68  ction.** with th
b5e0: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  e [SQLITE_OPEN_C
b5f0: 52 45 41 54 45 5d 20 66 6c 61 67 2c 20 77 68 69  REATE] flag, whi
b600: 63 68 20 61 72 65 20 62 6f 74 68 20 64 69 72 65  ch are both dire
b610: 63 74 6c 79 0a 2a 2a 20 61 6e 61 6c 6f 67 6f 75  ctly.** analogou
b620: 73 20 74 6f 20 74 68 65 20 4f 5f 45 58 43 4c 20  s to the O_EXCL 
b630: 61 6e 64 20 4f 5f 43 52 45 41 54 20 66 6c 61 67  and O_CREAT flag
b640: 73 20 6f 66 20 74 68 65 20 50 4f 53 49 58 20 6f  s of the POSIX o
b650: 70 65 6e 28 29 0a 2a 2a 20 41 50 49 2e 20 20 54  pen().** API.  T
b660: 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45  he SQLITE_OPEN_E
b670: 58 43 4c 55 53 49 56 45 20 66 6c 61 67 2c 20 77  XCLUSIVE flag, w
b680: 68 65 6e 20 70 61 69 72 65 64 20 77 69 74 68 20  hen paired with 
b690: 74 68 65 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f  the .** SQLITE_O
b6a0: 50 45 4e 5f 43 52 45 41 54 45 2c 20 69 73 20 75  PEN_CREATE, is u
b6b0: 73 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20  sed to indicate 
b6c0: 74 68 61 74 20 66 69 6c 65 20 73 68 6f 75 6c 64  that file should
b6d0: 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65 20 63 72   always.** be cr
b6e0: 65 61 74 65 64 2c 20 61 6e 64 20 74 68 61 74 20  eated, and that 
b6f0: 69 74 20 69 73 20 61 6e 20 65 72 72 6f 72 20 69  it is an error i
b700: 66 20 69 74 20 61 6c 72 65 61 64 79 20 65 78 69  f it already exi
b710: 73 74 73 2e 0a 2a 2a 20 49 74 20 69 73 20 3c 69  sts..** It is <i
b720: 3e 6e 6f 74 3c 2f 69 3e 20 75 73 65 64 20 74 6f  >not</i> used to
b730: 20 69 6e 64 69 63 61 74 65 20 74 68 65 20 66 69   indicate the fi
b740: 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 6f 70 65  le should be ope
b750: 6e 65 64 20 0a 2a 2a 20 66 6f 72 20 65 78 63 6c  ned .** for excl
b760: 75 73 69 76 65 20 61 63 63 65 73 73 2e 0a 2a 2a  usive access..**
b770: 0a 2a 2a 20 5e 41 74 20 6c 65 61 73 74 20 73 7a  .** ^At least sz
b780: 4f 73 46 69 6c 65 20 62 79 74 65 73 20 6f 66 20  OsFile bytes of 
b790: 6d 65 6d 6f 72 79 20 61 72 65 20 61 6c 6c 6f 63  memory are alloc
b7a0: 61 74 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a  ated by SQLite.*
b7b0: 2a 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 20 5b  * to hold the  [
b7c0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 73 74  sqlite3_file] st
b7d0: 72 75 63 74 75 72 65 20 70 61 73 73 65 64 20 61  ructure passed a
b7e0: 73 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 61  s the third.** a
b7f0: 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e  rgument to xOpen
b800: 2e 20 20 54 68 65 20 78 4f 70 65 6e 20 6d 65 74  .  The xOpen met
b810: 68 6f 64 20 64 6f 65 73 20 6e 6f 74 20 68 61 76  hod does not hav
b820: 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65  e to.** allocate
b830: 20 74 68 65 20 73 74 72 75 63 74 75 72 65 3b 20   the structure; 
b840: 69 74 20 73 68 6f 75 6c 64 20 6a 75 73 74 20 66  it should just f
b850: 69 6c 6c 20 69 74 20 69 6e 2e 20 20 4e 6f 74 65  ill it in.  Note
b860: 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 78 4f 70   that.** the xOp
b870: 65 6e 20 6d 65 74 68 6f 64 20 6d 75 73 74 20 73  en method must s
b880: 65 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66  et the sqlite3_f
b890: 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 74 6f 20  ile.pMethods to 
b8a0: 65 69 74 68 65 72 0a 2a 2a 20 61 20 76 61 6c 69  either.** a vali
b8b0: 64 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  d [sqlite3_io_me
b8c0: 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 6f 72  thods] object or
b8d0: 20 74 6f 20 4e 55 4c 4c 2e 20 20 78 4f 70 65 6e   to NULL.  xOpen
b8e0: 20 6d 75 73 74 20 64 6f 0a 2a 2a 20 74 68 69 73   must do.** this
b8f0: 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f 70 65   even if the ope
b900: 6e 20 66 61 69 6c 73 2e 20 20 53 51 4c 69 74 65  n fails.  SQLite
b910: 20 65 78 70 65 63 74 73 20 74 68 61 74 20 74 68   expects that th
b920: 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70  e sqlite3_file.p
b930: 4d 65 74 68 6f 64 73 0a 2a 2a 20 65 6c 65 6d 65  Methods.** eleme
b940: 6e 74 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64  nt will be valid
b950: 20 61 66 74 65 72 20 78 4f 70 65 6e 20 72 65 74   after xOpen ret
b960: 75 72 6e 73 20 72 65 67 61 72 64 6c 65 73 73 20  urns regardless 
b970: 6f 66 20 74 68 65 20 73 75 63 63 65 73 73 0a 2a  of the success.*
b980: 2a 20 6f 72 20 66 61 69 6c 75 72 65 20 6f 66 20  * or failure of 
b990: 74 68 65 20 78 4f 70 65 6e 20 63 61 6c 6c 2e 0a  the xOpen call..
b9a0: 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f  **.** [[sqlite3_
b9b0: 76 66 73 2e 78 41 63 63 65 73 73 5d 5d 0a 2a 2a  vfs.xAccess]].**
b9c0: 20 5e 54 68 65 20 66 6c 61 67 73 20 61 72 67 75   ^The flags argu
b9d0: 6d 65 6e 74 20 74 6f 20 78 41 63 63 65 73 73 28  ment to xAccess(
b9e0: 29 20 6d 61 79 20 62 65 20 5b 53 51 4c 49 54 45  ) may be [SQLITE
b9f0: 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 5d 0a  _ACCESS_EXISTS].
ba00: 2a 2a 20 74 6f 20 74 65 73 74 20 66 6f 72 20 74  ** to test for t
ba10: 68 65 20 65 78 69 73 74 65 6e 63 65 20 6f 66 20  he existence of 
ba20: 61 20 66 69 6c 65 2c 20 6f 72 20 5b 53 51 4c 49  a file, or [SQLI
ba30: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52  TE_ACCESS_READWR
ba40: 49 54 45 5d 20 74 6f 0a 2a 2a 20 74 65 73 74 20  ITE] to.** test 
ba50: 77 68 65 74 68 65 72 20 61 20 66 69 6c 65 20 69  whether a file i
ba60: 73 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77  s readable and w
ba70: 72 69 74 61 62 6c 65 2c 20 6f 72 20 5b 53 51 4c  ritable, or [SQL
ba80: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 5d  ITE_ACCESS_READ]
ba90: 0a 2a 2a 20 74 6f 20 74 65 73 74 20 77 68 65 74  .** to test whet
baa0: 68 65 72 20 61 20 66 69 6c 65 20 69 73 20 61 74  her a file is at
bab0: 20 6c 65 61 73 74 20 72 65 61 64 61 62 6c 65 2e   least readable.
bac0: 20 20 20 54 68 65 20 66 69 6c 65 20 63 61 6e 20     The file can 
bad0: 62 65 20 61 0a 2a 2a 20 64 69 72 65 63 74 6f 72  be a.** director
bae0: 79 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65  y..**.** ^SQLite
baf0: 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 61 6c 6c   will always all
bb00: 6f 63 61 74 65 20 61 74 20 6c 65 61 73 74 20 6d  ocate at least m
bb10: 78 50 61 74 68 6e 61 6d 65 2b 31 20 62 79 74 65  xPathname+1 byte
bb20: 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20 6f 75 74  s for the.** out
bb30: 70 75 74 20 62 75 66 66 65 72 20 78 46 75 6c 6c  put buffer xFull
bb40: 50 61 74 68 6e 61 6d 65 2e 20 20 54 68 65 20 65  Pathname.  The e
bb50: 78 61 63 74 20 73 69 7a 65 20 6f 66 20 74 68 65  xact size of the
bb60: 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a   output buffer.*
bb70: 2a 20 69 73 20 61 6c 73 6f 20 70 61 73 73 65 64  * is also passed
bb80: 20 61 73 20 61 20 70 61 72 61 6d 65 74 65 72 20   as a parameter 
bb90: 74 6f 20 62 6f 74 68 20 20 6d 65 74 68 6f 64 73  to both  methods
bba0: 2e 20 49 66 20 74 68 65 20 6f 75 74 70 75 74 20  . If the output 
bbb0: 62 75 66 66 65 72 0a 2a 2a 20 69 73 20 6e 6f 74  buffer.** is not
bbc0: 20 6c 61 72 67 65 20 65 6e 6f 75 67 68 2c 20 5b   large enough, [
bbd0: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d  SQLITE_CANTOPEN]
bbe0: 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72   should be retur
bbf0: 6e 65 64 2e 20 53 69 6e 63 65 20 74 68 69 73 20  ned. Since this 
bc00: 69 73 0a 2a 2a 20 68 61 6e 64 6c 65 64 20 61 73  is.** handled as
bc10: 20 61 20 66 61 74 61 6c 20 65 72 72 6f 72 20 62   a fatal error b
bc20: 79 20 53 51 4c 69 74 65 2c 20 76 66 73 20 69 6d  y SQLite, vfs im
bc30: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68  plementations sh
bc40: 6f 75 6c 64 20 65 6e 64 65 61 76 6f 72 0a 2a 2a  ould endeavor.**
bc50: 20 74 6f 20 70 72 65 76 65 6e 74 20 74 68 69 73   to prevent this
bc60: 20 62 79 20 73 65 74 74 69 6e 67 20 6d 78 50 61   by setting mxPa
bc70: 74 68 6e 61 6d 65 20 74 6f 20 61 20 73 75 66 66  thname to a suff
bc80: 69 63 69 65 6e 74 6c 79 20 6c 61 72 67 65 20 76  iciently large v
bc90: 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  alue..**.** The 
bca0: 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 2c 20 78  xRandomness(), x
bcb0: 53 6c 65 65 70 28 29 2c 20 78 43 75 72 72 65 6e  Sleep(), xCurren
bcc0: 74 54 69 6d 65 28 29 2c 20 61 6e 64 20 78 43 75  tTime(), and xCu
bcd0: 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29  rrentTimeInt64()
bce0: 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61  .** interfaces a
bcf0: 72 65 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20  re not strictly 
bd00: 61 20 70 61 72 74 20 6f 66 20 74 68 65 20 66 69  a part of the fi
bd10: 6c 65 73 79 73 74 65 6d 2c 20 62 75 74 20 74 68  lesystem, but th
bd20: 65 79 20 61 72 65 0a 2a 2a 20 69 6e 63 6c 75 64  ey are.** includ
bd30: 65 64 20 69 6e 20 74 68 65 20 56 46 53 20 73 74  ed in the VFS st
bd40: 72 75 63 74 75 72 65 20 66 6f 72 20 63 6f 6d 70  ructure for comp
bd50: 6c 65 74 65 6e 65 73 73 2e 0a 2a 2a 20 54 68 65  leteness..** The
bd60: 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 20 66   xRandomness() f
bd70: 75 6e 63 74 69 6f 6e 20 61 74 74 65 6d 70 74 73  unction attempts
bd80: 20 74 6f 20 72 65 74 75 72 6e 20 6e 42 79 74 65   to return nByte
bd90: 73 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 67 6f  s bytes.** of go
bda0: 6f 64 2d 71 75 61 6c 69 74 79 20 72 61 6e 64 6f  od-quality rando
bdb0: 6d 6e 65 73 73 20 69 6e 74 6f 20 7a 4f 75 74 2e  mness into zOut.
bdc0: 20 20 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c    The return val
bdd0: 75 65 20 69 73 0a 2a 2a 20 74 68 65 20 61 63 74  ue is.** the act
bde0: 75 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  ual number of by
bdf0: 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73  tes of randomnes
be00: 73 20 6f 62 74 61 69 6e 65 64 2e 0a 2a 2a 20 54  s obtained..** T
be10: 68 65 20 78 53 6c 65 65 70 28 29 20 6d 65 74 68  he xSleep() meth
be20: 6f 64 20 63 61 75 73 65 73 20 74 68 65 20 63 61  od causes the ca
be30: 6c 6c 69 6e 67 20 74 68 72 65 61 64 20 74 6f 20  lling thread to 
be40: 73 6c 65 65 70 20 66 6f 72 20 61 74 0a 2a 2a 20  sleep for at.** 
be50: 6c 65 61 73 74 20 74 68 65 20 6e 75 6d 62 65 72  least the number
be60: 20 6f 66 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73   of microseconds
be70: 20 67 69 76 65 6e 2e 20 20 5e 54 68 65 20 78 43   given.  ^The xC
be80: 75 72 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a 20  urrentTime().** 
be90: 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61  method returns a
bea0: 20 4a 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d 62   Julian Day Numb
beb0: 65 72 20 66 6f 72 20 74 68 65 20 63 75 72 72 65  er for the curre
bec0: 6e 74 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65  nt date and time
bed0: 20 61 73 0a 2a 2a 20 61 20 66 6c 6f 61 74 69 6e   as.** a floatin
bee0: 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 2e 0a 2a  g point value..*
bef0: 2a 20 5e 54 68 65 20 78 43 75 72 72 65 6e 74 54  * ^The xCurrentT
bf00: 69 6d 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f  imeInt64() metho
bf10: 64 20 72 65 74 75 72 6e 73 2c 20 61 73 20 61 6e  d returns, as an
bf20: 20 69 6e 74 65 67 65 72 2c 20 74 68 65 20 4a 75   integer, the Ju
bf30: 6c 69 61 6e 0a 2a 2a 20 44 61 79 20 4e 75 6d 62  lian.** Day Numb
bf40: 65 72 20 6d 75 6c 74 69 70 6c 69 65 64 20 62 79  er multiplied by
bf50: 20 38 36 34 30 30 30 30 30 20 28 74 68 65 20 6e   86400000 (the n
bf60: 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65  umber of millise
bf70: 63 6f 6e 64 73 20 69 6e 20 0a 2a 2a 20 61 20 32  conds in .** a 2
bf80: 34 2d 68 6f 75 72 20 64 61 79 29 2e 20 20 0a 2a  4-hour day).  .*
bf90: 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75  * ^SQLite will u
bfa0: 73 65 20 74 68 65 20 78 43 75 72 72 65 6e 74 54  se the xCurrentT
bfb0: 69 6d 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f  imeInt64() metho
bfc0: 64 20 74 6f 20 67 65 74 20 74 68 65 20 63 75 72  d to get the cur
bfd0: 72 65 6e 74 0a 2a 2a 20 64 61 74 65 20 61 6e 64  rent.** date and
bfe0: 20 74 69 6d 65 20 69 66 20 74 68 61 74 20 6d 65   time if that me
bff0: 74 68 6f 64 20 69 73 20 61 76 61 69 6c 61 62 6c  thod is availabl
c000: 65 20 28 69 66 20 69 56 65 72 73 69 6f 6e 20 69  e (if iVersion i
c010: 73 20 32 20 6f 72 20 0a 2a 2a 20 67 72 65 61 74  s 2 or .** great
c020: 65 72 20 61 6e 64 20 74 68 65 20 66 75 6e 63 74  er and the funct
c030: 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e  ion pointer is n
c040: 6f 74 20 4e 55 4c 4c 29 20 61 6e 64 20 77 69 6c  ot NULL) and wil
c050: 6c 20 66 61 6c 6c 20 62 61 63 6b 0a 2a 2a 20 74  l fall back.** t
c060: 6f 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29  o xCurrentTime()
c070: 20 69 66 20 78 43 75 72 72 65 6e 74 54 69 6d 65   if xCurrentTime
c080: 49 6e 74 36 34 28 29 20 69 73 20 75 6e 61 76 61  Int64() is unava
c090: 69 6c 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ilable..**.** ^T
c0a0: 68 65 20 78 53 65 74 53 79 73 74 65 6d 43 61 6c  he xSetSystemCal
c0b0: 6c 28 29 2c 20 78 47 65 74 53 79 73 74 65 6d 43  l(), xGetSystemC
c0c0: 61 6c 6c 28 29 2c 20 61 6e 64 20 78 4e 65 73 74  all(), and xNest
c0d0: 53 79 73 74 65 6d 43 61 6c 6c 28 29 20 69 6e 74  SystemCall() int
c0e0: 65 72 66 61 63 65 73 0a 2a 2a 20 61 72 65 20 6e  erfaces.** are n
c0f0: 6f 74 20 75 73 65 64 20 62 79 20 74 68 65 20 53  ot used by the S
c100: 51 4c 69 74 65 20 63 6f 72 65 2e 20 20 54 68 65  QLite core.  The
c110: 73 65 20 6f 70 74 69 6f 6e 61 6c 20 69 6e 74 65  se optional inte
c120: 72 66 61 63 65 73 20 61 72 65 20 70 72 6f 76 69  rfaces are provi
c130: 64 65 64 0a 2a 2a 20 62 79 20 73 6f 6d 65 20 56  ded.** by some V
c140: 46 53 65 73 20 74 6f 20 66 61 63 69 6c 69 74 61  FSes to facilita
c150: 74 65 20 74 65 73 74 69 6e 67 20 6f 66 20 74 68  te testing of th
c160: 65 20 56 46 53 20 63 6f 64 65 2e 20 42 79 20 6f  e VFS code. By o
c170: 76 65 72 72 69 64 69 6e 67 20 0a 2a 2a 20 73 79  verriding .** sy
c180: 73 74 65 6d 20 63 61 6c 6c 73 20 77 69 74 68 20  stem calls with 
c190: 66 75 6e 63 74 69 6f 6e 73 20 75 6e 64 65 72 20  functions under 
c1a0: 69 74 73 20 63 6f 6e 74 72 6f 6c 2c 20 61 20 74  its control, a t
c1b0: 65 73 74 20 70 72 6f 67 72 61 6d 20 63 61 6e 0a  est program can.
c1c0: 2a 2a 20 73 69 6d 75 6c 61 74 65 20 66 61 75 6c  ** simulate faul
c1d0: 74 73 20 61 6e 64 20 65 72 72 6f 72 20 63 6f 6e  ts and error con
c1e0: 64 69 74 69 6f 6e 73 20 74 68 61 74 20 77 6f 75  ditions that wou
c1f0: 6c 64 20 6f 74 68 65 72 77 69 73 65 20 62 65 20  ld otherwise be 
c200: 64 69 66 66 69 63 75 6c 74 0a 2a 2a 20 6f 72 20  difficult.** or 
c210: 69 6d 70 6f 73 73 69 62 6c 65 20 74 6f 20 69 6e  impossible to in
c220: 64 75 63 65 2e 20 20 54 68 65 20 73 65 74 20 6f  duce.  The set o
c230: 66 20 73 79 73 74 65 6d 20 63 61 6c 6c 73 20 74  f system calls t
c240: 68 61 74 20 63 61 6e 20 62 65 20 6f 76 65 72 72  hat can be overr
c250: 69 64 64 65 6e 0a 2a 2a 20 76 61 72 69 65 73 20  idden.** varies 
c260: 66 72 6f 6d 20 6f 6e 65 20 56 46 53 20 74 6f 20  from one VFS to 
c270: 61 6e 6f 74 68 65 72 2c 20 61 6e 64 20 66 72 6f  another, and fro
c280: 6d 20 6f 6e 65 20 76 65 72 73 69 6f 6e 20 6f 66  m one version of
c290: 20 74 68 65 20 73 61 6d 65 20 56 46 53 20 74 6f   the same VFS to
c2a0: 20 74 68 65 0a 2a 2a 20 6e 65 78 74 2e 20 20 41   the.** next.  A
c2b0: 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74  pplications that
c2c0: 20 75 73 65 20 74 68 65 73 65 20 69 6e 74 65 72   use these inter
c2d0: 66 61 63 65 73 20 6d 75 73 74 20 62 65 20 70 72  faces must be pr
c2e0: 65 70 61 72 65 64 20 66 6f 72 20 61 6e 79 0a 2a  epared for any.*
c2f0: 2a 20 6f 72 20 61 6c 6c 20 6f 66 20 74 68 65 73  * or all of thes
c300: 65 20 69 6e 74 65 72 66 61 63 65 73 20 74 6f 20  e interfaces to 
c310: 62 65 20 4e 55 4c 4c 20 6f 72 20 66 6f 72 20 74  be NULL or for t
c320: 68 65 69 72 20 62 65 68 61 76 69 6f 72 20 74 6f  heir behavior to
c330: 20 63 68 61 6e 67 65 0a 2a 2a 20 66 72 6f 6d 20   change.** from 
c340: 6f 6e 65 20 72 65 6c 65 61 73 65 20 74 6f 20 74  one release to t
c350: 68 65 20 6e 65 78 74 2e 20 20 41 70 70 6c 69 63  he next.  Applic
c360: 61 74 69 6f 6e 73 20 6d 75 73 74 20 6e 6f 74 20  ations must not 
c370: 61 74 74 65 6d 70 74 20 74 6f 20 61 63 63 65 73  attempt to acces
c380: 73 0a 2a 2a 20 61 6e 79 20 6f 66 20 74 68 65 73  s.** any of thes
c390: 65 20 6d 65 74 68 6f 64 73 20 69 66 20 74 68 65  e methods if the
c3a0: 20 69 56 65 72 73 69 6f 6e 20 6f 66 20 74 68 65   iVersion of the
c3b0: 20 56 46 53 20 69 73 20 6c 65 73 73 20 74 68 61   VFS is less tha
c3c0: 6e 20 33 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  n 3..*/.typedef 
c3d0: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76  struct sqlite3_v
c3e0: 66 73 20 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a  fs sqlite3_vfs;.
c3f0: 74 79 70 65 64 65 66 20 76 6f 69 64 20 28 2a 73  typedef void (*s
c400: 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70  qlite3_syscall_p
c410: 74 72 29 28 76 6f 69 64 29 3b 0a 73 74 72 75 63  tr)(void);.struc
c420: 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20 7b 0a  t sqlite3_vfs {.
c430: 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 20    int iVersion; 
c440: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 74             /* St
c450: 72 75 63 74 75 72 65 20 76 65 72 73 69 6f 6e 20  ructure version 
c460: 6e 75 6d 62 65 72 20 28 63 75 72 72 65 6e 74 6c  number (currentl
c470: 79 20 33 29 20 2a 2f 0a 20 20 69 6e 74 20 73 7a  y 3) */.  int sz
c480: 4f 73 46 69 6c 65 3b 20 20 20 20 20 20 20 20 20  OsFile;         
c490: 20 20 20 2f 2a 20 53 69 7a 65 20 6f 66 20 73 75     /* Size of su
c4a0: 62 63 6c 61 73 73 65 64 20 73 71 6c 69 74 65 33  bclassed sqlite3
c4b0: 5f 66 69 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6d  _file */.  int m
c4c0: 78 50 61 74 68 6e 61 6d 65 3b 20 20 20 20 20 20  xPathname;      
c4d0: 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 66      /* Maximum f
c4e0: 69 6c 65 20 70 61 74 68 6e 61 6d 65 20 6c 65 6e  ile pathname len
c4f0: 67 74 68 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  gth */.  sqlite3
c500: 5f 76 66 73 20 2a 70 4e 65 78 74 3b 20 20 20 20  _vfs *pNext;    
c510: 20 20 2f 2a 20 4e 65 78 74 20 72 65 67 69 73 74    /* Next regist
c520: 65 72 65 64 20 56 46 53 20 2a 2f 0a 20 20 63 6f  ered VFS */.  co
c530: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 3b  nst char *zName;
c540: 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f         /* Name o
c550: 66 20 74 68 69 73 20 76 69 72 74 75 61 6c 20 66  f this virtual f
c560: 69 6c 65 20 73 79 73 74 65 6d 20 2a 2f 0a 20 20  ile system */.  
c570: 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20  void *pAppData; 
c580: 20 20 20 20 20 20 20 20 20 2f 2a 20 50 6f 69 6e           /* Poin
c590: 74 65 72 20 74 6f 20 61 70 70 6c 69 63 61 74 69  ter to applicati
c5a0: 6f 6e 2d 73 70 65 63 69 66 69 63 20 64 61 74 61  on-specific data
c5b0: 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65   */.  int (*xOpe
c5c0: 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  n)(sqlite3_vfs*,
c5d0: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
c5e0: 6d 65 2c 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  me, sqlite3_file
c5f0: 2a 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20  *,.             
c600: 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74    int flags, int
c610: 20 2a 70 4f 75 74 46 6c 61 67 73 29 3b 0a 20 20   *pOutFlags);.  
c620: 69 6e 74 20 28 2a 78 44 65 6c 65 74 65 29 28 73  int (*xDelete)(s
c630: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
c640: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
c650: 69 6e 74 20 73 79 6e 63 44 69 72 29 3b 0a 20 20  int syncDir);.  
c660: 69 6e 74 20 28 2a 78 41 63 63 65 73 73 29 28 73  int (*xAccess)(s
c670: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
c680: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
c690: 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a  int flags, int *
c6a0: 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20  pResOut);.  int 
c6b0: 28 2a 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 29  (*xFullPathname)
c6c0: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
c6d0: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
c6e0: 2c 20 69 6e 74 20 6e 4f 75 74 2c 20 63 68 61 72  , int nOut, char
c6f0: 20 2a 7a 4f 75 74 29 3b 0a 20 20 76 6f 69 64 20   *zOut);.  void 
c700: 2a 28 2a 78 44 6c 4f 70 65 6e 29 28 73 71 6c 69  *(*xDlOpen)(sqli
c710: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
c720: 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 29  char *zFilename)
c730: 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 45 72  ;.  void (*xDlEr
c740: 72 6f 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ror)(sqlite3_vfs
c750: 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68  *, int nByte, ch
c760: 61 72 20 2a 7a 45 72 72 4d 73 67 29 3b 0a 20 20  ar *zErrMsg);.  
c770: 76 6f 69 64 20 28 2a 28 2a 78 44 6c 53 79 6d 29  void (*(*xDlSym)
c780: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 76 6f  (sqlite3_vfs*,vo
c790: 69 64 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  id*, const char 
c7a0: 2a 7a 53 79 6d 62 6f 6c 29 29 28 76 6f 69 64 29  *zSymbol))(void)
c7b0: 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 43 6c  ;.  void (*xDlCl
c7c0: 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ose)(sqlite3_vfs
c7d0: 2a 2c 20 76 6f 69 64 2a 29 3b 0a 20 20 69 6e 74  *, void*);.  int
c7e0: 20 28 2a 78 52 61 6e 64 6f 6d 6e 65 73 73 29 28   (*xRandomness)(
c7f0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e  sqlite3_vfs*, in
c800: 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a  t nByte, char *z
c810: 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53  Out);.  int (*xS
c820: 6c 65 65 70 29 28 73 71 6c 69 74 65 33 5f 76 66  leep)(sqlite3_vf
c830: 73 2a 2c 20 69 6e 74 20 6d 69 63 72 6f 73 65 63  s*, int microsec
c840: 6f 6e 64 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78  onds);.  int (*x
c850: 43 75 72 72 65 6e 74 54 69 6d 65 29 28 73 71 6c  CurrentTime)(sql
c860: 69 74 65 33 5f 76 66 73 2a 2c 20 64 6f 75 62 6c  ite3_vfs*, doubl
c870: 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 47 65  e*);.  int (*xGe
c880: 74 4c 61 73 74 45 72 72 6f 72 29 28 73 71 6c 69  tLastError)(sqli
c890: 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 2c 20 63  te3_vfs*, int, c
c8a0: 68 61 72 20 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a  har *);.  /*.  *
c8b0: 2a 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62  * The methods ab
c8c0: 6f 76 65 20 61 72 65 20 69 6e 20 76 65 72 73 69  ove are in versi
c8d0: 6f 6e 20 31 20 6f 66 20 74 68 65 20 73 71 6c 69  on 1 of the sqli
c8e0: 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 0a 20 20  te_vfs object.  
c8f0: 2a 2a 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20  ** definition.  
c900: 54 68 6f 73 65 20 74 68 61 74 20 66 6f 6c 6c 6f  Those that follo
c910: 77 20 61 72 65 20 61 64 64 65 64 20 69 6e 20 76  w are added in v
c920: 65 72 73 69 6f 6e 20 32 20 6f 72 20 6c 61 74 65  ersion 2 or late
c930: 72 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  r.  */.  int (*x
c940: 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34  CurrentTimeInt64
c950: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
c960: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2a 29 3b  sqlite3_int64*);
c970: 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d  .  /*.  ** The m
c980: 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65  ethods above are
c990: 20 69 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 61   in versions 1 a
c9a0: 6e 64 20 32 20 6f 66 20 74 68 65 20 73 71 6c 69  nd 2 of the sqli
c9b0: 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20  te_vfs object.. 
c9c0: 20 2a 2a 20 54 68 6f 73 65 20 62 65 6c 6f 77 20   ** Those below 
c9d0: 61 72 65 20 66 6f 72 20 76 65 72 73 69 6f 6e 20  are for version 
c9e0: 33 20 61 6e 64 20 67 72 65 61 74 65 72 2e 0a 20  3 and greater.. 
c9f0: 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 65 74   */.  int (*xSet
ca00: 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69  SystemCall)(sqli
ca10: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
ca20: 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c  char *zName, sql
ca30: 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72  ite3_syscall_ptr
ca40: 29 3b 0a 20 20 73 71 6c 69 74 65 33 5f 73 79 73  );.  sqlite3_sys
ca50: 63 61 6c 6c 5f 70 74 72 20 28 2a 78 47 65 74 53  call_ptr (*xGetS
ca60: 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74  ystemCall)(sqlit
ca70: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
ca80: 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 63  har *zName);.  c
ca90: 6f 6e 73 74 20 63 68 61 72 20 2a 28 2a 78 4e 65  onst char *(*xNe
caa0: 78 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71  xtSystemCall)(sq
cab0: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
cac0: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a  t char *zName);.
cad0: 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65    /*.  ** The me
cae0: 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20  thods above are 
caf0: 69 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 74 68  in versions 1 th
cb00: 72 6f 75 67 68 20 33 20 6f 66 20 74 68 65 20 73  rough 3 of the s
cb10: 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74  qlite_vfs object
cb20: 2e 0a 20 20 2a 2a 20 4e 65 77 20 66 69 65 6c 64  ..  ** New field
cb30: 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65  s may be appende
cb40: 64 20 69 6e 20 66 69 67 75 72 65 20 76 65 72 73  d in figure vers
cb50: 69 6f 6e 73 2e 20 20 54 68 65 20 69 56 65 72 73  ions.  The iVers
cb60: 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75 65 20 77  ion.  ** value w
cb70: 69 6c 6c 20 69 6e 63 72 65 6d 65 6e 74 20 77 68  ill increment wh
cb80: 65 6e 65 76 65 72 20 74 68 69 73 20 68 61 70 70  enever this happ
cb90: 65 6e 73 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f  ens. .  */.};../
cba0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
cbb0: 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78 41 63  lags for the xAc
cbc0: 63 65 73 73 20 56 46 53 20 6d 65 74 68 6f 64 0a  cess VFS method.
cbd0: 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65  **.** These inte
cbe0: 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 63 61  ger constants ca
cbf0: 6e 20 62 65 20 75 73 65 64 20 61 73 20 74 68 65  n be used as the
cc00: 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
cc10: 20 74 6f 0a 2a 2a 20 74 68 65 20 78 41 63 63 65   to.** the xAcce
cc20: 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20  ss method of an 
cc30: 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
cc40: 6a 65 63 74 2e 20 20 54 68 65 79 20 64 65 74 65  ject.  They dete
cc50: 72 6d 69 6e 65 0a 2a 2a 20 77 68 61 74 20 6b 69  rmine.** what ki
cc60: 6e 64 20 6f 66 20 70 65 72 6d 69 73 73 69 6f 6e  nd of permission
cc70: 73 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65  s the xAccess me
cc80: 74 68 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e 67 20  thod is looking 
cc90: 66 6f 72 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c  for..** With SQL
cca0: 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54  ITE_ACCESS_EXIST
ccb0: 53 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d  S, the xAccess m
ccc0: 65 74 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79 20  ethod.** simply 
ccd0: 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 74  checks whether t
cce0: 68 65 20 66 69 6c 65 20 65 78 69 73 74 73 2e 0a  he file exists..
ccf0: 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41  ** With SQLITE_A
cd00: 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 2c  CCESS_READWRITE,
cd10: 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74   the xAccess met
cd20: 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68  hod.** checks wh
cd30: 65 74 68 65 72 20 74 68 65 20 6e 61 6d 65 64 20  ether the named 
cd40: 64 69 72 65 63 74 6f 72 79 20 69 73 20 62 6f 74  directory is bot
cd50: 68 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77  h readable and w
cd60: 72 69 74 61 62 6c 65 0a 2a 2a 20 28 69 6e 20 6f  ritable.** (in o
cd70: 74 68 65 72 20 77 6f 72 64 73 2c 20 69 66 20 66  ther words, if f
cd80: 69 6c 65 73 20 63 61 6e 20 62 65 20 61 64 64 65  iles can be adde
cd90: 64 2c 20 72 65 6d 6f 76 65 64 2c 20 61 6e 64 20  d, removed, and 
cda0: 72 65 6e 61 6d 65 64 20 77 69 74 68 69 6e 0a 2a  renamed within.*
cdb0: 2a 20 74 68 65 20 64 69 72 65 63 74 6f 72 79 29  * the directory)
cdc0: 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f  ..** The SQLITE_
cdd0: 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45  ACCESS_READWRITE
cde0: 20 63 6f 6e 73 74 61 6e 74 20 69 73 20 63 75 72   constant is cur
cdf0: 72 65 6e 74 6c 79 20 75 73 65 64 20 6f 6e 6c 79  rently used only
ce00: 20 62 79 20 74 68 65 0a 2a 2a 20 5b 74 65 6d 70   by the.** [temp
ce10: 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79  _store_directory
ce20: 20 70 72 61 67 6d 61 5d 2c 20 74 68 6f 75 67 68   pragma], though
ce30: 20 74 68 69 73 20 63 6f 75 6c 64 20 63 68 61 6e   this could chan
ce40: 67 65 20 69 6e 20 61 20 66 75 74 75 72 65 0a 2a  ge in a future.*
ce50: 2a 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c  * release of SQL
ce60: 69 74 65 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c  ite..** With SQL
ce70: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 2c  ITE_ACCESS_READ,
ce80: 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74   the xAccess met
ce90: 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68  hod.** checks wh
cea0: 65 74 68 65 72 20 74 68 65 20 66 69 6c 65 20 69  ether the file i
ceb0: 73 20 72 65 61 64 61 62 6c 65 2e 20 20 54 68 65  s readable.  The
cec0: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52   SQLITE_ACCESS_R
ced0: 45 41 44 20 63 6f 6e 73 74 61 6e 74 20 69 73 0a  EAD constant is.
cee0: 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 75 6e 75  ** currently unu
cef0: 73 65 64 2c 20 74 68 6f 75 67 68 20 69 74 20 6d  sed, though it m
cf00: 69 67 68 74 20 62 65 20 75 73 65 64 20 69 6e 20  ight be used in 
cf10: 61 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  a future release
cf20: 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 0a 2a   of.** SQLite..*
cf30: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
cf40: 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 20 20  _ACCESS_EXISTS  
cf50: 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    0.#define SQLI
cf60: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52  TE_ACCESS_READWR
cf70: 49 54 45 20 31 20 20 20 2f 2a 20 55 73 65 64 20  ITE 1   /* Used 
cf80: 62 79 20 50 52 41 47 4d 41 20 74 65 6d 70 5f 73  by PRAGMA temp_s
cf90: 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 2a  tore_directory *
cfa0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
cfb0: 5f 41 43 43 45 53 53 5f 52 45 41 44 20 20 20 20  _ACCESS_READ    
cfc0: 20 20 32 20 20 20 2f 2a 20 55 6e 75 73 65 64 20    2   /* Unused 
cfd0: 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
cfe0: 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68  EF: Flags for th
cff0: 65 20 78 53 68 6d 4c 6f 63 6b 20 56 46 53 20 6d  e xShmLock VFS m
d000: 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ethod.**.** Thes
d010: 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61  e integer consta
d020: 6e 74 73 20 64 65 66 69 6e 65 20 74 68 65 20 76  nts define the v
d030: 61 72 69 6f 75 73 20 6c 6f 63 6b 69 6e 67 20 6f  arious locking o
d040: 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 6c 6c  perations.** all
d050: 6f 77 65 64 20 62 79 20 74 68 65 20 78 53 68 6d  owed by the xShm
d060: 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 66 20 5b  Lock method of [
d070: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
d080: 64 73 5d 2e 20 20 54 68 65 0a 2a 2a 20 66 6f 6c  ds].  The.** fol
d090: 6c 6f 77 69 6e 67 20 61 72 65 20 74 68 65 20 6f  lowing are the o
d0a0: 6e 6c 79 20 6c 65 67 61 6c 20 63 6f 6d 62 69 6e  nly legal combin
d0b0: 61 74 69 6f 6e 73 20 6f 66 20 66 6c 61 67 73 20  ations of flags 
d0c0: 74 6f 20 74 68 65 0a 2a 2a 20 78 53 68 6d 4c 6f  to the.** xShmLo
d0d0: 63 6b 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a  ck method:.**.**
d0e0: 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53   <ul>.** <li>  S
d0f0: 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c  QLITE_SHM_LOCK |
d100: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52   SQLITE_SHM_SHAR
d110: 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49  ED.** <li>  SQLI
d120: 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51  TE_SHM_LOCK | SQ
d130: 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49  LITE_SHM_EXCLUSI
d140: 56 45 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49  VE.** <li>  SQLI
d150: 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20  TE_SHM_UNLOCK | 
d160: 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45  SQLITE_SHM_SHARE
d170: 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54  D.** <li>  SQLIT
d180: 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53  E_SHM_UNLOCK | S
d190: 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53  QLITE_SHM_EXCLUS
d1a0: 49 56 45 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a  IVE.** </ul>.**.
d1b0: 2a 2a 20 57 68 65 6e 20 75 6e 6c 6f 63 6b 69 6e  ** When unlockin
d1c0: 67 2c 20 74 68 65 20 73 61 6d 65 20 53 48 41 52  g, the same SHAR
d1d0: 45 44 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20  ED or EXCLUSIVE 
d1e0: 66 6c 61 67 20 6d 75 73 74 20 62 65 20 73 75 70  flag must be sup
d1f0: 70 6c 69 65 64 20 61 73 0a 2a 2a 20 77 61 73 20  plied as.** was 
d200: 67 69 76 65 6e 20 6e 6f 20 74 68 65 20 63 6f 72  given no the cor
d210: 72 65 73 70 6f 6e 64 69 6e 67 20 6c 6f 63 6b 2e  responding lock.
d220: 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68    .**.** The xSh
d230: 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 63 61 6e  mLock method can
d240: 20 74 72 61 6e 73 69 74 69 6f 6e 20 62 65 74 77   transition betw
d250: 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64  een unlocked and
d260: 20 53 48 41 52 45 44 20 6f 72 0a 2a 2a 20 62 65   SHARED or.** be
d270: 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61  tween unlocked a
d280: 6e 64 20 45 58 43 4c 55 53 49 56 45 2e 20 20 49  nd EXCLUSIVE.  I
d290: 74 20 63 61 6e 6e 6f 74 20 74 72 61 6e 73 69 74  t cannot transit
d2a0: 69 6f 6e 20 62 65 74 77 65 65 6e 20 53 48 41 52  ion between SHAR
d2b0: 45 44 0a 2a 2a 20 61 6e 64 20 45 58 43 4c 55 53  ED.** and EXCLUS
d2c0: 49 56 45 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  IVE..*/.#define 
d2d0: 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43  SQLITE_SHM_UNLOC
d2e0: 4b 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e  K       1.#defin
d2f0: 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43  e SQLITE_SHM_LOC
d300: 4b 20 20 20 20 20 20 20 20 20 32 0a 23 64 65 66  K         2.#def
d310: 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53  ine SQLITE_SHM_S
d320: 48 41 52 45 44 20 20 20 20 20 20 20 34 0a 23 64  HARED       4.#d
d330: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d  efine SQLITE_SHM
d340: 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20 38 0a  _EXCLUSIVE    8.
d350: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
d360: 20 4d 61 78 69 6d 75 6d 20 78 53 68 6d 4c 6f 63   Maximum xShmLoc
d370: 6b 20 69 6e 64 65 78 0a 2a 2a 0a 2a 2a 20 54 68  k index.**.** Th
d380: 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f  e xShmLock metho
d390: 64 20 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f  d on [sqlite3_io
d3a0: 5f 6d 65 74 68 6f 64 73 5d 20 6d 61 79 20 75 73  _methods] may us
d3b0: 65 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77  e values.** betw
d3c0: 65 65 6e 20 30 20 61 6e 64 20 74 68 69 73 20 75  een 0 and this u
d3d0: 70 70 65 72 20 62 6f 75 6e 64 20 61 73 20 69 74  pper bound as it
d3e0: 73 20 22 6f 66 66 73 65 74 22 20 61 72 67 75 6d  s "offset" argum
d3f0: 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69  ent..** The SQLi
d400: 74 65 20 63 6f 72 65 20 77 69 6c 6c 20 6e 65 76  te core will nev
d410: 65 72 20 61 74 74 65 6d 70 74 20 74 6f 20 61 63  er attempt to ac
d420: 71 75 69 72 65 20 6f 72 20 72 65 6c 65 61 73 65  quire or release
d430: 20 61 0a 2a 2a 20 6c 6f 63 6b 20 6f 75 74 73 69   a.** lock outsi
d440: 64 65 20 6f 66 20 74 68 69 73 20 72 61 6e 67 65  de of this range
d450: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
d460: 54 45 5f 53 48 4d 5f 4e 4c 4f 43 4b 20 20 20 20  TE_SHM_NLOCK    
d470: 20 20 20 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41      8.../*.** CA
d480: 50 49 33 52 45 46 3a 20 49 6e 69 74 69 61 6c 69  PI3REF: Initiali
d490: 7a 65 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69  ze The SQLite Li
d4a0: 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  brary.**.** ^The
d4b0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
d4c0: 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69 6e  ize() routine in
d4d0: 69 74 69 61 6c 69 7a 65 73 20 74 68 65 0a 2a 2a  itializes the.**
d4e0: 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e   SQLite library.
d4f0: 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73    ^The sqlite3_s
d500: 68 75 74 64 6f 77 6e 28 29 20 72 6f 75 74 69 6e  hutdown() routin
d510: 65 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61 74 65 73  e.** deallocates
d520: 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20 74   any resources t
d530: 68 61 74 20 77 65 72 65 20 61 6c 6c 6f 63 61 74  hat were allocat
d540: 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e  ed by sqlite3_in
d550: 69 74 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a 20 54  itialize()..** T
d560: 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
d570: 65 20 64 65 73 69 67 6e 65 64 20 74 6f 20 61 69  e designed to ai
d580: 64 20 69 6e 20 70 72 6f 63 65 73 73 20 69 6e 69  d in process ini
d590: 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 0a  tialization and.
d5a0: 2a 2a 20 73 68 75 74 64 6f 77 6e 20 6f 6e 20 65  ** shutdown on e
d5b0: 6d 62 65 64 64 65 64 20 73 79 73 74 65 6d 73 2e  mbedded systems.
d5c0: 20 20 57 6f 72 6b 73 74 61 74 69 6f 6e 20 61 70    Workstation ap
d5d0: 70 6c 69 63 61 74 69 6f 6e 73 20 75 73 69 6e 67  plications using
d5e0: 0a 2a 2a 20 53 51 4c 69 74 65 20 6e 6f 72 6d 61  .** SQLite norma
d5f0: 6c 6c 79 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20  lly do not need 
d600: 74 6f 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72  to invoke either
d610: 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
d620: 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c  es..**.** A call
d630: 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74   to sqlite3_init
d640: 69 61 6c 69 7a 65 28 29 20 69 73 20 61 6e 20 22  ialize() is an "
d650: 65 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20  effective" call 
d660: 69 66 20 69 74 20 69 73 0a 2a 2a 20 74 68 65 20  if it is.** the 
d670: 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74  first time sqlit
d680: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
d690: 69 73 20 69 6e 76 6f 6b 65 64 20 64 75 72 69 6e  is invoked durin
d6a0: 67 20 74 68 65 20 6c 69 66 65 74 69 6d 65 20 6f  g the lifetime o
d6b0: 66 0a 2a 2a 20 74 68 65 20 70 72 6f 63 65 73 73  f.** the process
d6c0: 2c 20 6f 72 20 69 66 20 69 74 20 69 73 20 74 68  , or if it is th
d6d0: 65 20 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c  e first time sql
d6e0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
d6f0: 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20  ) is invoked.** 
d700: 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 61 6c 6c  following a call
d710: 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74   to sqlite3_shut
d720: 64 6f 77 6e 28 29 2e 20 20 5e 28 4f 6e 6c 79 20  down().  ^(Only 
d730: 61 6e 20 65 66 66 65 63 74 69 76 65 20 63 61 6c  an effective cal
d740: 6c 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f  l.** of sqlite3_
d750: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 6f 65  initialize() doe
d760: 73 20 61 6e 79 20 69 6e 69 74 69 61 6c 69 7a 61  s any initializa
d770: 74 69 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68 65 72  tion.  All other
d780: 20 63 61 6c 6c 73 0a 2a 2a 20 61 72 65 20 68 61   calls.** are ha
d790: 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e  rmless no-ops.)^
d7a0: 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f  .**.** A call to
d7b0: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
d7c0: 6e 28 29 20 69 73 20 61 6e 20 22 65 66 66 65 63  n() is an "effec
d7d0: 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74  tive" call if it
d7e0: 20 69 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a   is the first.**
d7f0: 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
d800: 5f 73 68 75 74 64 6f 77 6e 28 29 20 73 69 6e 63  _shutdown() sinc
d810: 65 20 74 68 65 20 6c 61 73 74 20 73 71 6c 69 74  e the last sqlit
d820: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e  e3_initialize().
d830: 20 20 5e 28 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 65    ^(Only.** an e
d840: 66 66 65 63 74 69 76 65 20 63 61 6c 6c 20 74 6f  ffective call to
d850: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
d860: 6e 28 29 20 64 6f 65 73 20 61 6e 79 20 64 65 69  n() does any dei
d870: 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a  nitialization..*
d880: 2a 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 69  * All other vali
d890: 64 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  d calls to sqlit
d8a0: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 61 72  e3_shutdown() ar
d8b0: 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70  e harmless no-op
d8c0: 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  s.)^.**.** The s
d8d0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
d8e0: 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  e() interface is
d8f0: 20 74 68 72 65 61 64 73 61 66 65 2c 20 62 75 74   threadsafe, but
d900: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
d910: 6e 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 2e 20 20  n().** is not.  
d920: 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74  The sqlite3_shut
d930: 64 6f 77 6e 28 29 20 69 6e 74 65 72 66 61 63 65  down() interface
d940: 20 6d 75 73 74 20 6f 6e 6c 79 20 62 65 20 63 61   must only be ca
d950: 6c 6c 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 73  lled from a.** s
d960: 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20 41  ingle thread.  A
d970: 6c 6c 20 6f 70 65 6e 20 5b 64 61 74 61 62 61 73  ll open [databas
d980: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 6d  e connections] m
d990: 75 73 74 20 62 65 20 63 6c 6f 73 65 64 20 61 6e  ust be closed an
d9a0: 64 20 61 6c 6c 0a 2a 2a 20 6f 74 68 65 72 20 53  d all.** other S
d9b0: 51 4c 69 74 65 20 72 65 73 6f 75 72 63 65 73 20  QLite resources 
d9c0: 6d 75 73 74 20 62 65 20 64 65 61 6c 6c 6f 63 61  must be dealloca
d9d0: 74 65 64 20 70 72 69 6f 72 20 74 6f 20 69 6e 76  ted prior to inv
d9e0: 6f 6b 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33  oking.** sqlite3
d9f0: 5f 73 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2a 0a  _shutdown()..**.
da00: 2a 2a 20 41 6d 6f 6e 67 20 6f 74 68 65 72 20 74  ** Among other t
da10: 68 69 6e 67 73 2c 20 5e 73 71 6c 69 74 65 33 5f  hings, ^sqlite3_
da20: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 77 69 6c  initialize() wil
da30: 6c 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69  l invoke.** sqli
da40: 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20  te3_os_init().  
da50: 53 69 6d 69 6c 61 72 6c 79 2c 20 5e 73 71 6c 69  Similarly, ^sqli
da60: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a  te3_shutdown().*
da70: 2a 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 73 71  * will invoke sq
da80: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a  lite3_os_end()..
da90: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
daa0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
dab0: 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
dac0: 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73  [SQLITE_OK] on s
dad0: 75 63 63 65 73 73 2e 0a 2a 2a 20 5e 49 66 20 66  uccess..** ^If f
dae0: 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2c 20  or some reason, 
daf0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
db00: 7a 65 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74  ze() is unable t
db10: 6f 20 69 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a 20  o initialize.** 
db20: 74 68 65 20 6c 69 62 72 61 72 79 20 28 70 65 72  the library (per
db30: 68 61 70 73 20 69 74 20 69 73 20 75 6e 61 62 6c  haps it is unabl
db40: 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61 20  e to allocate a 
db50: 6e 65 65 64 65 64 20 72 65 73 6f 75 72 63 65 20  needed resource 
db60: 73 75 63 68 0a 2a 2a 20 61 73 20 61 20 6d 75 74  such.** as a mut
db70: 65 78 29 20 69 74 20 72 65 74 75 72 6e 73 20 61  ex) it returns a
db80: 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f  n [error code] o
db90: 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
dba0: 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  E_OK]..**.** ^Th
dbb0: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
dbc0: 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69  lize() routine i
dbd0: 73 20 63 61 6c 6c 65 64 20 69 6e 74 65 72 6e 61  s called interna
dbe0: 6c 6c 79 20 62 79 20 6d 61 6e 79 20 6f 74 68 65  lly by many othe
dbf0: 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65  r.** SQLite inte
dc00: 72 66 61 63 65 73 20 73 6f 20 74 68 61 74 20 61  rfaces so that a
dc10: 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73  n application us
dc20: 75 61 6c 6c 79 20 64 6f 65 73 20 6e 6f 74 20 6e  ually does not n
dc30: 65 65 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65  eed to.** invoke
dc40: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
dc50: 69 7a 65 28 29 20 64 69 72 65 63 74 6c 79 2e 20  ize() directly. 
dc60: 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 5b 73   For example, [s
dc70: 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a  qlite3_open()].*
dc80: 2a 20 63 61 6c 6c 73 20 73 71 6c 69 74 65 33 5f  * calls sqlite3_
dc90: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 73 6f 20  initialize() so 
dca0: 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61  the SQLite libra
dcb0: 72 79 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d  ry will be autom
dcc0: 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74  atically.** init
dcd0: 69 61 6c 69 7a 65 64 20 77 68 65 6e 20 5b 73 71  ialized when [sq
dce0: 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 69 73  lite3_open()] is
dcf0: 20 63 61 6c 6c 65 64 20 69 66 20 69 74 20 68 61   called if it ha
dd00: 73 20 6e 6f 74 20 62 65 20 69 6e 69 74 69 61 6c  s not be initial
dd10: 69 7a 65 64 0a 2a 2a 20 61 6c 72 65 61 64 79 2e  ized.** already.
dd20: 20 20 5e 48 6f 77 65 76 65 72 2c 20 69 66 20 53    ^However, if S
dd30: 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
dd40: 64 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49  d with the [SQLI
dd50: 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54  TE_OMIT_AUTOINIT
dd60: 5d 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  ].** compile-tim
dd70: 65 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 74  e option, then t
dd80: 68 65 20 61 75 74 6f 6d 61 74 69 63 20 63 61 6c  he automatic cal
dd90: 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e  ls to sqlite3_in
dda0: 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 61 72  itialize().** ar
ddb0: 65 20 6f 6d 69 74 74 65 64 20 61 6e 64 20 74 68  e omitted and th
ddc0: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  e application mu
ddd0: 73 74 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f  st call sqlite3_
dde0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72  initialize() dir
ddf0: 65 63 74 6c 79 0a 2a 2a 20 70 72 69 6f 72 20 74  ectly.** prior t
de00: 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65  o using any othe
de10: 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  r SQLite interfa
de20: 63 65 2e 20 20 46 6f 72 20 6d 61 78 69 6d 75 6d  ce.  For maximum
de30: 20 70 6f 72 74 61 62 69 6c 69 74 79 2c 0a 2a 2a   portability,.**
de40: 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64   it is recommend
de50: 65 64 20 74 68 61 74 20 61 70 70 6c 69 63 61 74  ed that applicat
de60: 69 6f 6e 73 20 61 6c 77 61 79 73 20 69 6e 76 6f  ions always invo
de70: 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  ke sqlite3_initi
de80: 61 6c 69 7a 65 28 29 0a 2a 2a 20 64 69 72 65 63  alize().** direc
de90: 74 6c 79 20 70 72 69 6f 72 20 74 6f 20 75 73 69  tly prior to usi
dea0: 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c  ng any other SQL
deb0: 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20  ite interface.  
dec0: 46 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 0a  Future releases.
ded0: 2a 2a 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79  ** of SQLite may
dee0: 20 72 65 71 75 69 72 65 20 74 68 69 73 2e 20 20   require this.  
def0: 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  In other words, 
df00: 74 68 65 20 62 65 68 61 76 69 6f 72 20 65 78 68  the behavior exh
df10: 69 62 69 74 65 64 0a 2a 2a 20 77 68 65 6e 20 53  ibited.** when S
df20: 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
df30: 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 4f  d with [SQLITE_O
df40: 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 20 6d 69  MIT_AUTOINIT] mi
df50: 67 68 74 20 62 65 63 6f 6d 65 20 74 68 65 0a 2a  ght become the.*
df60: 2a 20 64 65 66 61 75 6c 74 20 62 65 68 61 76 69  * default behavi
df70: 6f 72 20 69 6e 20 73 6f 6d 65 20 66 75 74 75 72  or in some futur
df80: 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c  e release of SQL
df90: 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ite..**.** The s
dfa0: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
dfb0: 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6f 70   routine does op
dfc0: 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73  erating-system s
dfd0: 70 65 63 69 66 69 63 0a 2a 2a 20 69 6e 69 74 69  pecific.** initi
dfe0: 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 74 68 65  alization of the
dff0: 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e   SQLite library.
e000: 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73    The sqlite3_os
e010: 5f 65 6e 64 28 29 0a 2a 2a 20 72 6f 75 74 69 6e  _end().** routin
e020: 65 20 75 6e 64 6f 65 73 20 74 68 65 20 65 66 66  e undoes the eff
e030: 65 63 74 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f  ect of sqlite3_o
e040: 73 5f 69 6e 69 74 28 29 2e 20 20 54 79 70 69 63  s_init().  Typic
e050: 61 6c 20 74 61 73 6b 73 0a 2a 2a 20 70 65 72 66  al tasks.** perf
e060: 6f 72 6d 65 64 20 62 79 20 74 68 65 73 65 20 72  ormed by these r
e070: 6f 75 74 69 6e 65 73 20 69 6e 63 6c 75 64 65 20  outines include 
e080: 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72 20 64 65  allocation or de
e090: 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66  allocation.** of
e0a0: 20 73 74 61 74 69 63 20 72 65 73 6f 75 72 63 65   static resource
e0b0: 73 2c 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f  s, initializatio
e0c0: 6e 20 6f 66 20 67 6c 6f 62 61 6c 20 76 61 72 69  n of global vari
e0d0: 61 62 6c 65 73 2c 0a 2a 2a 20 73 65 74 74 69 6e  ables,.** settin
e0e0: 67 20 75 70 20 61 20 64 65 66 61 75 6c 74 20 5b  g up a default [
e0f0: 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6d 6f 64  sqlite3_vfs] mod
e100: 75 6c 65 2c 20 6f 72 20 73 65 74 74 69 6e 67 20  ule, or setting 
e110: 75 70 0a 2a 2a 20 61 20 64 65 66 61 75 6c 74 20  up.** a default 
e120: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 73  configuration us
e130: 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  ing [sqlite3_con
e140: 66 69 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68  fig()]..**.** Th
e150: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68  e application sh
e160: 6f 75 6c 64 20 6e 65 76 65 72 20 69 6e 76 6f 6b  ould never invok
e170: 65 20 65 69 74 68 65 72 20 73 71 6c 69 74 65 33  e either sqlite3
e180: 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f 72  _os_init().** or
e190: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
e1a0: 29 20 64 69 72 65 63 74 6c 79 2e 20 20 54 68 65  ) directly.  The
e1b0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f   application sho
e1c0: 75 6c 64 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a  uld only invoke.
e1d0: 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  ** sqlite3_initi
e1e0: 61 6c 69 7a 65 28 29 20 61 6e 64 20 73 71 6c 69  alize() and sqli
e1f0: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20  te3_shutdown(). 
e200: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f   The sqlite3_os_
e210: 69 6e 69 74 28 29 0a 2a 2a 20 69 6e 74 65 72 66  init().** interf
e220: 61 63 65 20 69 73 20 63 61 6c 6c 65 64 20 61 75  ace is called au
e230: 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73  tomatically by s
e240: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
e250: 65 28 29 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74  e() and.** sqlit
e260: 65 33 5f 6f 73 5f 65 6e 64 28 29 20 69 73 20 63  e3_os_end() is c
e270: 61 6c 6c 65 64 20 62 79 20 73 71 6c 69 74 65 33  alled by sqlite3
e280: 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 41 70  _shutdown().  Ap
e290: 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20 69 6d 70  propriate.** imp
e2a0: 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72  lementations for
e2b0: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
e2c0: 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f  () and sqlite3_o
e2d0: 73 5f 65 6e 64 28 29 0a 2a 2a 20 61 72 65 20 62  s_end().** are b
e2e0: 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65  uilt into SQLite
e2f0: 20 77 68 65 6e 20 69 74 20 69 73 20 63 6f 6d 70   when it is comp
e300: 69 6c 65 64 20 66 6f 72 20 55 6e 69 78 2c 20 57  iled for Unix, W
e310: 69 6e 64 6f 77 73 2c 20 6f 72 20 4f 53 2f 32 2e  indows, or OS/2.
e320: 0a 2a 2a 20 57 68 65 6e 20 5b 63 75 73 74 6f 6d  .** When [custom
e330: 20 62 75 69 6c 64 73 20 7c 20 62 75 69 6c 74 20   builds | built 
e340: 66 6f 72 20 6f 74 68 65 72 20 70 6c 61 74 66 6f  for other platfo
e350: 72 6d 73 5d 0a 2a 2a 20 28 75 73 69 6e 67 20 74  rms].** (using t
e360: 68 65 20 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f 54  he [SQLITE_OS_OT
e370: 48 45 52 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d 74  HER=1] compile-t
e380: 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20 74  ime.** option) t
e390: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
e3a0: 75 73 74 20 73 75 70 70 6c 79 20 61 20 73 75 69  ust supply a sui
e3b0: 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61  table implementa
e3c0: 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c 69  tion for.** sqli
e3d0: 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e  te3_os_init() an
e3e0: 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  d sqlite3_os_end
e3f0: 28 29 2e 20 20 41 6e 20 61 70 70 6c 69 63 61 74  ().  An applicat
e400: 69 6f 6e 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20  ion-supplied.** 
e410: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
e420: 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  f sqlite3_os_ini
e430: 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f  t() or sqlite3_o
e440: 73 5f 65 6e 64 28 29 0a 2a 2a 20 6d 75 73 74 20  s_end().** must 
e450: 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f  return [SQLITE_O
e460: 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 61 6e  K] on success an
e470: 64 20 73 6f 6d 65 20 6f 74 68 65 72 20 5b 65 72  d some other [er
e480: 72 6f 72 20 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a  ror code] upon.*
e490: 2a 20 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a 69 6e  * failure..*/.in
e4a0: 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  t sqlite3_initia
e4b0: 6c 69 7a 65 28 76 6f 69 64 29 3b 0a 69 6e 74 20  lize(void);.int 
e4c0: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
e4d0: 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69  (void);.int sqli
e4e0: 74 65 33 5f 6f 73 5f 69 6e 69 74 28 76 6f 69 64  te3_os_init(void
e4f0: 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f  );.int sqlite3_o
e500: 73 5f 65 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f 2a  s_end(void);../*
e510: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
e520: 6e 66 69 67 75 72 69 6e 67 20 54 68 65 20 53 51  nfiguring The SQ
e530: 4c 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a  Lite Library.**.
e540: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63  ** The sqlite3_c
e550: 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63  onfig() interfac
e560: 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b  e is used to mak
e570: 65 20 67 6c 6f 62 61 6c 20 63 6f 6e 66 69 67 75  e global configu
e580: 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65  ration.** change
e590: 73 20 74 6f 20 53 51 4c 69 74 65 20 69 6e 20 6f  s to SQLite in o
e5a0: 72 64 65 72 20 74 6f 20 74 75 6e 65 20 53 51 4c  rder to tune SQL
e5b0: 69 74 65 20 74 6f 20 74 68 65 20 73 70 65 63 69  ite to the speci
e5c0: 66 69 63 20 6e 65 65 64 73 20 6f 66 0a 2a 2a 20  fic needs of.** 
e5d0: 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e  the application.
e5e0: 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 63 6f    The default co
e5f0: 6e 66 69 67 75 72 61 74 69 6f 6e 20 69 73 20 72  nfiguration is r
e600: 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6d  ecommended for m
e610: 6f 73 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69  ost.** applicati
e620: 6f 6e 73 20 61 6e 64 20 73 6f 20 74 68 69 73 20  ons and so this 
e630: 72 6f 75 74 69 6e 65 20 69 73 20 75 73 75 61 6c  routine is usual
e640: 6c 79 20 6e 6f 74 20 6e 65 63 65 73 73 61 72 79  ly not necessary
e650: 2e 20 20 49 74 20 69 73 0a 2a 2a 20 70 72 6f 76  .  It is.** prov
e660: 69 64 65 64 20 74 6f 20 73 75 70 70 6f 72 74 20  ided to support 
e670: 72 61 72 65 20 61 70 70 6c 69 63 61 74 69 6f 6e  rare application
e680: 73 20 77 69 74 68 20 75 6e 75 73 75 61 6c 20 6e  s with unusual n
e690: 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  eeds..**.** The 
e6a0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
e6b0: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f   interface is no
e6c0: 74 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 54  t threadsafe.  T
e6d0: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a  he application.*
e6e0: 2a 20 6d 75 73 74 20 69 6e 73 75 72 65 20 74 68  * must insure th
e6f0: 61 74 20 6e 6f 20 6f 74 68 65 72 20 53 51 4c 69  at no other SQLi
e700: 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  te interfaces ar
e710: 65 20 69 6e 76 6f 6b 65 64 20 62 79 20 6f 74 68  e invoked by oth
e720: 65 72 0a 2a 2a 20 74 68 72 65 61 64 73 20 77 68  er.** threads wh
e730: 69 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ile sqlite3_conf
e740: 69 67 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e  ig() is running.
e750: 20 20 46 75 72 74 68 65 72 6d 6f 72 65 2c 20 73    Furthermore, s
e760: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 0a  qlite3_config().
e770: 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 69  ** may only be i
e780: 6e 76 6f 6b 65 64 20 70 72 69 6f 72 20 74 6f 20  nvoked prior to 
e790: 6c 69 62 72 61 72 79 20 69 6e 69 74 69 61 6c 69  library initiali
e7a0: 7a 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20  zation using.** 
e7b0: 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c  [sqlite3_initial
e7c0: 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20  ize()] or after 
e7d0: 73 68 75 74 64 6f 77 6e 20 62 79 20 5b 73 71 6c  shutdown by [sql
e7e0: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d  ite3_shutdown()]
e7f0: 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33  ..** ^If sqlite3
e800: 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 63 61 6c  _config() is cal
e810: 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74  led after [sqlit
e820: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d  e3_initialize()]
e830: 20 61 6e 64 20 62 65 66 6f 72 65 0a 2a 2a 20 5b   and before.** [
e840: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
e850: 28 29 5d 20 74 68 65 6e 20 69 74 20 77 69 6c 6c  ()] then it will
e860: 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4d   return SQLITE_M
e870: 49 53 55 53 45 2e 0a 2a 2a 20 4e 6f 74 65 2c 20  ISUSE..** Note, 
e880: 68 6f 77 65 76 65 72 2c 20 74 68 61 74 20 5e 73  however, that ^s
e890: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
e8a0: 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 73  can be called as
e8b0: 20 70 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a 20   part of the.** 
e8c0: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
e8d0: 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  f an application
e8e0: 2d 64 65 66 69 6e 65 64 20 5b 73 71 6c 69 74 65  -defined [sqlite
e8f0: 33 5f 6f 73 5f 69 6e 69 74 28 29 5d 2e 0a 2a 2a  3_os_init()]..**
e900: 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72  .** The first ar
e910: 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
e920: 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 61 6e  3_config() is an
e930: 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 63 6f 6e   integer.** [con
e940: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
e950: 6e 5d 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e  n] that determin
e960: 65 73 0a 2a 2a 20 77 68 61 74 20 70 72 6f 70 65  es.** what prope
e970: 72 74 79 20 6f 66 20 53 51 4c 69 74 65 20 69 73  rty of SQLite is
e980: 20 74 6f 20 62 65 20 63 6f 6e 66 69 67 75 72 65   to be configure
e990: 64 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20 61  d.  Subsequent a
e9a0: 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 76 61 72 79  rguments.** vary
e9b0: 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68   depending on th
e9c0: 65 20 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  e [configuration
e9d0: 20 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74   option].** in t
e9e0: 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
e9f0: 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 61  t..**.** ^When a
ea00: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
ea10: 70 74 69 6f 6e 20 69 73 20 73 65 74 2c 20 73 71  ption is set, sq
ea20: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 72  lite3_config() r
ea30: 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
ea40: 4b 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6f  K]..** ^If the o
ea50: 70 74 69 6f 6e 20 69 73 20 75 6e 6b 6e 6f 77 6e  ption is unknown
ea60: 20 6f 72 20 53 51 4c 69 74 65 20 69 73 20 75 6e   or SQLite is un
ea70: 61 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20  able to set the 
ea80: 6f 70 74 69 6f 6e 0a 2a 2a 20 74 68 65 6e 20 74  option.** then t
ea90: 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75  his routine retu
eaa0: 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 5b  rns a non-zero [
eab0: 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2f 0a  error code]..*/.
eac0: 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  int sqlite3_conf
ead0: 69 67 28 69 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f  ig(int, ...);../
eae0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
eaf0: 6f 6e 66 69 67 75 72 65 20 64 61 74 61 62 61 73  onfigure databas
eb00: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a  e connections.**
eb10: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
eb20: 64 62 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65  db_config() inte
eb30: 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f  rface is used to
eb40: 20 6d 61 6b 65 20 63 6f 6e 66 69 67 75 72 61 74   make configurat
eb50: 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74  ion.** changes t
eb60: 6f 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f  o a [database co
eb70: 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20  nnection].  The 
eb80: 69 6e 74 65 72 66 61 63 65 20 69 73 20 73 69 6d  interface is sim
eb90: 69 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  ilar to.** [sqli
eba0: 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 65 78  te3_config()] ex
ebb0: 63 65 70 74 20 74 68 61 74 20 74 68 65 20 63 68  cept that the ch
ebc0: 61 6e 67 65 73 20 61 70 70 6c 79 20 74 6f 20 61  anges apply to a
ebd0: 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64 61 74 61   single.** [data
ebe0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
ebf0: 20 28 73 70 65 63 69 66 69 65 64 20 69 6e 20 74   (specified in t
ec00: 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
ec10: 74 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65  t)..**.** The se
ec20: 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
ec30: 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66   sqlite3_db_conf
ec40: 69 67 28 44 2c 56 2c 2e 2e 2e 29 20 20 69 73 20  ig(D,V,...)  is 
ec50: 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44  the.** [SQLITE_D
ec60: 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
ec70: 45 20 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  E | configuratio
ec80: 6e 20 76 65 72 62 5d 20 2d 20 61 6e 20 69 6e 74  n verb] - an int
ec90: 65 67 65 72 20 63 6f 64 65 20 0a 2a 2a 20 74 68  eger code .** th
eca0: 61 74 20 69 6e 64 69 63 61 74 65 73 20 77 68 61  at indicates wha
ecb0: 74 20 61 73 70 65 63 74 20 6f 66 20 74 68 65 20  t aspect of the 
ecc0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
ecd0: 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20 63  tion] is being c
ece0: 6f 6e 66 69 67 75 72 65 64 2e 0a 2a 2a 20 53 75  onfigured..** Su
ecf0: 62 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e  bsequent argumen
ed00: 74 73 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e  ts vary dependin
ed10: 67 20 6f 6e 20 74 68 65 20 63 6f 6e 66 69 67 75  g on the configu
ed20: 72 61 74 69 6f 6e 20 76 65 72 62 2e 0a 2a 2a 0a  ration verb..**.
ed30: 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c  ** ^Calls to sql
ed40: 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
ed50: 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f   return SQLITE_O
ed60: 4b 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66  K if and only if
ed70: 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 69 73 20  .** the call is 
ed80: 63 6f 6e 73 69 64 65 72 65 64 20 73 75 63 63 65  considered succe
ed90: 73 73 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ssful..*/.int sq
eda0: 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
edb0: 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 70  sqlite3*, int op
edc0: 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  , ...);../*.** C
edd0: 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20  API3REF: Memory 
ede0: 41 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f 75 74 69  Allocation Routi
edf0: 6e 65 73 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73  nes.**.** An ins
ee00: 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62  tance of this ob
ee10: 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65  ject defines the
ee20: 20 69 6e 74 65 72 66 61 63 65 20 62 65 74 77 65   interface betwe
ee30: 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64  en SQLite.** and
ee40: 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72   low-level memor
ee50: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75  y allocation rou
ee60: 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  tines..**.** Thi
ee70: 73 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64  s object is used
ee80: 20 69 6e 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61   in only one pla
ee90: 63 65 20 69 6e 20 74 68 65 20 53 51 4c 69 74 65  ce in the SQLite
eea0: 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 41   interface..** A
eeb0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
eec0: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20  nstance of this 
eed0: 6f 62 6a 65 63 74 20 69 73 20 74 68 65 20 61 72  object is the ar
eee0: 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71  gument to.** [sq
eef0: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
ef00: 77 68 65 6e 20 74 68 65 20 63 6f 6e 66 69 67 75  when the configu
ef10: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73  ration option is
ef20: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  .** [SQLITE_CONF
ef30: 49 47 5f 4d 41 4c 4c 4f 43 5d 20 6f 72 20 5b 53  IG_MALLOC] or [S
ef40: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
ef50: 4d 41 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a 20 42 79  MALLOC].  .** By
ef60: 20 63 72 65 61 74 69 6e 67 20 61 6e 20 69 6e 73   creating an ins
ef70: 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62  tance of this ob
ef80: 6a 65 63 74 0a 2a 2a 20 61 6e 64 20 70 61 73 73  ject.** and pass
ef90: 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74  ing it to [sqlit
efa0: 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49  e3_config]([SQLI
efb0: 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
efc0: 5d 29 0a 2a 2a 20 64 75 72 69 6e 67 20 63 6f 6e  ]).** during con
efd0: 66 69 67 75 72 61 74 69 6f 6e 2c 20 61 6e 20 61  figuration, an a
efe0: 70 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 73  pplication can s
eff0: 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e  pecify an altern
f000: 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20  ative.** memory 
f010: 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79  allocation subsy
f020: 73 74 65 6d 20 66 6f 72 20 53 51 4c 69 74 65 20  stem for SQLite 
f030: 74 6f 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f  to use for all o
f040: 66 20 69 74 73 0a 2a 2a 20 64 79 6e 61 6d 69 63  f its.** dynamic
f050: 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 2e 0a 2a   memory needs..*
f060: 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 53  *.** Note that S
f070: 51 4c 69 74 65 20 63 6f 6d 65 73 20 77 69 74 68  QLite comes with
f080: 20 73 65 76 65 72 61 6c 20 5b 62 75 69 6c 74 2d   several [built-
f090: 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  in memory alloca
f0a0: 74 6f 72 73 5d 0a 2a 2a 20 74 68 61 74 20 61 72  tors].** that ar
f0b0: 65 20 70 65 72 66 65 63 74 6c 79 20 61 64 65 71  e perfectly adeq
f0c0: 75 61 74 65 20 66 6f 72 20 74 68 65 20 6f 76 65  uate for the ove
f0d0: 72 77 68 65 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69  rwhelming majori
f0e0: 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f  ty of applicatio
f0f0: 6e 73 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 74  ns.** and that t
f100: 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 6f 6e  his object is on
f110: 6c 79 20 75 73 65 66 75 6c 20 74 6f 20 61 20 74  ly useful to a t
f120: 69 6e 79 20 6d 69 6e 6f 72 69 74 79 20 6f 66 20  iny minority of 
f130: 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20  applications.** 
f140: 77 69 74 68 20 73 70 65 63 69 61 6c 69 7a 65 64  with specialized
f150: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
f160: 6f 6e 20 72 65 71 75 69 72 65 6d 65 6e 74 73 2e  on requirements.
f170: 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73    This object is
f180: 0a 2a 2a 20 61 6c 73 6f 20 75 73 65 64 20 64 75  .** also used du
f190: 72 69 6e 67 20 74 65 73 74 69 6e 67 20 6f 66 20  ring testing of 
f1a0: 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20  SQLite in order 
f1b0: 74 6f 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c  to specify an al
f1c0: 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d  ternative.** mem
f1d0: 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68  ory allocator th
f1e0: 61 74 20 73 69 6d 75 6c 61 74 65 73 20 6d 65 6d  at simulates mem
f1f0: 6f 72 79 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72  ory out-of-memor
f200: 79 20 63 6f 6e 64 69 74 69 6f 6e 73 20 69 6e 0a  y conditions in.
f210: 2a 2a 20 6f 72 64 65 72 20 74 6f 20 76 65 72 69  ** order to veri
f220: 66 79 20 74 68 61 74 20 53 51 4c 69 74 65 20 72  fy that SQLite r
f230: 65 63 6f 76 65 72 73 20 67 72 61 63 65 66 75 6c  ecovers graceful
f240: 6c 79 20 66 72 6f 6d 20 73 75 63 68 0a 2a 2a 20  ly from such.** 
f250: 63 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a  conditions..**.*
f260: 2a 20 54 68 65 20 78 4d 61 6c 6c 6f 63 2c 20 78  * The xMalloc, x
f270: 52 65 61 6c 6c 6f 63 2c 20 61 6e 64 20 78 46 72  Realloc, and xFr
f280: 65 65 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20  ee methods must 
f290: 77 6f 72 6b 20 6c 69 6b 65 20 74 68 65 0a 2a 2a  work like the.**
f2a0: 20 6d 61 6c 6c 6f 63 28 29 2c 20 72 65 61 6c 6c   malloc(), reall
f2b0: 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20  oc() and free() 
f2c0: 66 75 6e 63 74 69 6f 6e 73 20 66 72 6f 6d 20 74  functions from t
f2d0: 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69  he standard C li
f2e0: 62 72 61 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74  brary..** ^SQLit
f2f0: 65 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61  e guarantees tha
f300: 74 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  t the second arg
f310: 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 78 52 65 61  ument to.** xRea
f320: 6c 6c 6f 63 20 69 73 20 61 6c 77 61 79 73 20 61  lloc is always a
f330: 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
f340: 62 79 20 61 20 70 72 69 6f 72 20 63 61 6c 6c 20  by a prior call 
f350: 74 6f 20 78 52 6f 75 6e 64 75 70 2e 0a 2a 2a 0a  to xRoundup..**.
f360: 2a 2a 20 78 53 69 7a 65 20 73 68 6f 75 6c 64 20  ** xSize should 
f370: 72 65 74 75 72 6e 20 74 68 65 20 61 6c 6c 6f 63  return the alloc
f380: 61 74 65 64 20 73 69 7a 65 20 6f 66 20 61 20 6d  ated size of a m
f390: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
f3a0: 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 6f  .** previously o
f3b0: 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 78 4d 61  btained from xMa
f3c0: 6c 6c 6f 63 20 6f 72 20 78 52 65 61 6c 6c 6f 63  lloc or xRealloc
f3d0: 2e 20 20 54 68 65 20 61 6c 6c 6f 63 61 74 65 64  .  The allocated
f3e0: 20 73 69 7a 65 0a 2a 2a 20 69 73 20 61 6c 77 61   size.** is alwa
f3f0: 79 73 20 61 74 20 6c 65 61 73 74 20 61 73 20 62  ys at least as b
f400: 69 67 20 61 73 20 74 68 65 20 72 65 71 75 65 73  ig as the reques
f410: 74 65 64 20 73 69 7a 65 20 62 75 74 20 6d 61 79  ted size but may
f420: 20 62 65 20 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a   be larger..**.*
f430: 2a 20 54 68 65 20 78 52 6f 75 6e 64 75 70 20 6d  * The xRoundup m
f440: 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 77 68  ethod returns wh
f450: 61 74 20 77 6f 75 6c 64 20 62 65 20 74 68 65 20  at would be the 
f460: 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f  allocated size o
f470: 66 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79 20 61 6c  f.** a memory al
f480: 6c 6f 63 61 74 69 6f 6e 20 67 69 76 65 6e 20 61  location given a
f490: 20 70 61 72 74 69 63 75 6c 61 72 20 72 65 71 75   particular requ
f4a0: 65 73 74 65 64 20 73 69 7a 65 2e 20 20 4d 6f 73  ested size.  Mos
f4b0: 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f  t memory.** allo
f4c0: 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20  cators round up 
f4d0: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
f4e0: 6e 73 20 61 74 20 6c 65 61 73 74 20 74 6f 20 74  ns at least to t
f4f0: 68 65 20 6e 65 78 74 20 6d 75 6c 74 69 70 6c 65  he next multiple
f500: 0a 2a 2a 20 6f 66 20 38 2e 20 20 53 6f 6d 65 20  .** of 8.  Some 
f510: 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64  allocators round
f520: 20 75 70 20 74 6f 20 61 20 6c 61 72 67 65 72 20   up to a larger 
f530: 6d 75 6c 74 69 70 6c 65 20 6f 72 20 74 6f 20 61  multiple or to a
f540: 20 70 6f 77 65 72 20 6f 66 20 32 2e 0a 2a 2a 20   power of 2..** 
f550: 45 76 65 72 79 20 6d 65 6d 6f 72 79 20 61 6c 6c  Every memory all
f560: 6f 63 61 74 69 6f 6e 20 72 65 71 75 65 73 74 20  ocation request 
f570: 63 6f 6d 69 6e 67 20 69 6e 20 74 68 72 6f 75 67  coming in throug
f580: 68 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  h [sqlite3_mallo
f590: 63 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69  c()].** or [sqli
f5a0: 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 66  te3_realloc()] f
f5b0: 69 72 73 74 20 63 61 6c 6c 73 20 78 52 6f 75 6e  irst calls xRoun
f5c0: 64 75 70 2e 20 20 49 66 20 78 52 6f 75 6e 64 75  dup.  If xRoundu
f5d0: 70 20 72 65 74 75 72 6e 73 20 30 2c 20 0a 2a 2a  p returns 0, .**
f5e0: 20 74 68 61 74 20 63 61 75 73 65 73 20 74 68 65   that causes the
f5f0: 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6d   corresponding m
f600: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
f610: 20 74 6f 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20   to fail..**.** 
f620: 54 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64  The xInit method
f630: 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65   initializes the
f640: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
f650: 72 2e 20 20 28 46 6f 72 20 65 78 61 6d 70 6c 65  r.  (For example
f660: 2c 0a 2a 2a 20 69 74 20 6d 69 67 68 74 20 61 6c  ,.** it might al
f670: 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 71 75 69  locate any requi
f680: 72 65 20 6d 75 74 65 78 65 73 20 6f 72 20 69 6e  re mutexes or in
f690: 69 74 69 61 6c 69 7a 65 20 69 6e 74 65 72 6e 61  itialize interna
f6a0: 6c 20 64 61 74 61 0a 2a 2a 20 73 74 72 75 63 74  l data.** struct
f6b0: 75 72 65 73 2e 20 20 54 68 65 20 78 53 68 75 74  ures.  The xShut
f6c0: 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 69  down method is i
f6d0: 6e 76 6f 6b 65 64 20 28 69 6e 64 69 72 65 63 74  nvoked (indirect
f6e0: 6c 79 29 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74  ly) by.** [sqlit
f6f0: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 61  e3_shutdown()] a
f700: 6e 64 20 73 68 6f 75 6c 64 20 64 65 61 6c 6c 6f  nd should deallo
f710: 63 61 74 65 20 61 6e 79 20 72 65 73 6f 75 72 63  cate any resourc
f720: 65 73 20 61 63 71 75 69 72 65 64 0a 2a 2a 20 62  es acquired.** b
f730: 79 20 78 49 6e 69 74 2e 20 20 54 68 65 20 70 41  y xInit.  The pA
f740: 70 70 44 61 74 61 20 70 6f 69 6e 74 65 72 20 69  ppData pointer i
f750: 73 20 75 73 65 64 20 61 73 20 74 68 65 20 6f 6e  s used as the on
f760: 6c 79 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  ly parameter to.
f770: 2a 2a 20 78 49 6e 69 74 20 61 6e 64 20 78 53 68  ** xInit and xSh
f780: 75 74 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51  utdown..**.** SQ
f790: 4c 69 74 65 20 68 6f 6c 64 73 20 74 68 65 20 5b  Lite holds the [
f7a0: 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41  SQLITE_MUTEX_STA
f7b0: 54 49 43 5f 4d 41 53 54 45 52 5d 20 6d 75 74 65  TIC_MASTER] mute
f7c0: 78 20 77 68 65 6e 20 69 74 20 69 6e 76 6f 6b 65  x when it invoke
f7d0: 73 0a 2a 2a 20 74 68 65 20 78 49 6e 69 74 20 6d  s.** the xInit m
f7e0: 65 74 68 6f 64 2c 20 73 6f 20 74 68 65 20 78 49  ethod, so the xI
f7f0: 6e 69 74 20 6d 65 74 68 6f 64 20 6e 65 65 64 20  nit method need 
f800: 6e 6f 74 20 62 65 20 74 68 72 65 61 64 73 61 66  not be threadsaf
f810: 65 2e 20 20 54 68 65 0a 2a 2a 20 78 53 68 75 74  e.  The.** xShut
f820: 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 6f  down method is o
f830: 6e 6c 79 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20  nly called from 
f840: 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77  [sqlite3_shutdow
f850: 6e 28 29 5d 20 73 6f 20 69 74 20 64 6f 65 73 0a  n()] so it does.
f860: 2a 2a 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62  ** not need to b
f870: 65 20 74 68 72 65 61 64 73 61 66 65 20 65 69 74  e threadsafe eit
f880: 68 65 72 2e 20 20 46 6f 72 20 61 6c 6c 20 6f 74  her.  For all ot
f890: 68 65 72 20 6d 65 74 68 6f 64 73 2c 20 53 51 4c  her methods, SQL
f8a0: 69 74 65 0a 2a 2a 20 68 6f 6c 64 73 20 74 68 65  ite.** holds the
f8b0: 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53   [SQLITE_MUTEX_S
f8c0: 54 41 54 49 43 5f 4d 45 4d 5d 20 6d 75 74 65 78  TATIC_MEM] mutex
f8d0: 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 0a   as long as the.
f8e0: 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ** [SQLITE_CONFI
f8f0: 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20 63 6f 6e  G_MEMSTATUS] con
f900: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
f910: 6e 20 69 73 20 74 75 72 6e 65 64 20 6f 6e 20 28  n is turned on (
f920: 77 68 69 63 68 0a 2a 2a 20 69 74 20 69 73 20 62  which.** it is b
f930: 79 20 64 65 66 61 75 6c 74 29 20 61 6e 64 20 73  y default) and s
f940: 6f 20 74 68 65 20 6d 65 74 68 6f 64 73 20 61 72  o the methods ar
f950: 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  e automatically 
f960: 73 65 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a 20 48  serialized..** H
f970: 6f 77 65 76 65 72 2c 20 69 66 20 5b 53 51 4c 49  owever, if [SQLI
f980: 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41  TE_CONFIG_MEMSTA
f990: 54 55 53 5d 20 69 73 20 64 69 73 61 62 6c 65 64  TUS] is disabled
f9a0: 2c 20 74 68 65 6e 20 74 68 65 20 6f 74 68 65 72  , then the other
f9b0: 0a 2a 2a 20 6d 65 74 68 6f 64 73 20 6d 75 73 74  .** methods must
f9c0: 20 62 65 20 74 68 72 65 61 64 73 61 66 65 20 6f   be threadsafe o
f9d0: 72 20 65 6c 73 65 20 6d 61 6b 65 20 74 68 65 69  r else make thei
f9e0: 72 20 6f 77 6e 20 61 72 72 61 6e 67 65 6d 65 6e  r own arrangemen
f9f0: 74 73 20 66 6f 72 0a 2a 2a 20 73 65 72 69 61 6c  ts for.** serial
fa00: 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53  ization..**.** S
fa10: 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72  QLite will never
fa20: 20 69 6e 76 6f 6b 65 20 78 49 6e 69 74 28 29 20   invoke xInit() 
fa30: 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 20 77  more than once w
fa40: 69 74 68 6f 75 74 20 61 6e 20 69 6e 74 65 72 76  ithout an interv
fa50: 65 6e 69 6e 67 0a 2a 2a 20 63 61 6c 6c 20 74 6f  ening.** call to
fa60: 20 78 53 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2f   xShutdown()..*/
fa70: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
fa80: 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
fa90: 6f 64 73 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  ods sqlite3_mem_
faa0: 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20  methods;.struct 
fab0: 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
fac0: 6f 64 73 20 7b 0a 20 20 76 6f 69 64 20 2a 28 2a  ods {.  void *(*
fad0: 78 4d 61 6c 6c 6f 63 29 28 69 6e 74 29 3b 20 20  xMalloc)(int);  
fae0: 20 20 20 20 20 20 20 2f 2a 20 4d 65 6d 6f 72 79         /* Memory
faf0: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 75 6e 63   allocation func
fb00: 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 28  tion */.  void (
fb10: 2a 78 46 72 65 65 29 28 76 6f 69 64 2a 29 3b 20  *xFree)(void*); 
fb20: 20 20 20 20 20 20 20 20 20 2f 2a 20 46 72 65 65           /* Free
fb30: 20 61 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74   a prior allocat
fb40: 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 28  ion */.  void *(
fb50: 2a 78 52 65 61 6c 6c 6f 63 29 28 76 6f 69 64 2a  *xRealloc)(void*
fb60: 2c 69 6e 74 29 3b 20 20 2f 2a 20 52 65 73 69 7a  ,int);  /* Resiz
fb70: 65 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  e an allocation 
fb80: 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 69 7a 65  */.  int (*xSize
fb90: 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20  )(void*);       
fba0: 20 20 20 20 2f 2a 20 52 65 74 75 72 6e 20 74 68      /* Return th
fbb0: 65 20 73 69 7a 65 20 6f 66 20 61 6e 20 61 6c 6c  e size of an all
fbc0: 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74  ocation */.  int
fbd0: 20 28 2a 78 52 6f 75 6e 64 75 70 29 28 69 6e 74   (*xRoundup)(int
fbe0: 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52  );          /* R
fbf0: 6f 75 6e 64 20 75 70 20 72 65 71 75 65 73 74 20  ound up request 
fc00: 73 69 7a 65 20 74 6f 20 61 6c 6c 6f 63 61 74 69  size to allocati
fc10: 6f 6e 20 73 69 7a 65 20 2a 2f 0a 20 20 69 6e 74  on size */.  int
fc20: 20 28 2a 78 49 6e 69 74 29 28 76 6f 69 64 2a 29   (*xInit)(void*)
fc30: 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 49  ;           /* I
fc40: 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65  nitialize the me
fc50: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a  mory allocator *
fc60: 2f 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 75 74  /.  void (*xShut
fc70: 64 6f 77 6e 29 28 76 6f 69 64 2a 29 3b 20 20 20  down)(void*);   
fc80: 20 20 20 2f 2a 20 44 65 69 6e 69 74 69 61 6c 69     /* Deinitiali
fc90: 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c  ze the memory al
fca0: 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69  locator */.  voi
fcb0: 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20  d *pAppData;    
fcc0: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41              /* A
fcd0: 72 67 75 6d 65 6e 74 20 74 6f 20 78 49 6e 69 74  rgument to xInit
fce0: 28 29 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e  () and xShutdown
fcf0: 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20  () */.};../*.** 
fd00: 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67  CAPI3REF: Config
fd10: 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a  uration Options.
fd20: 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f  ** KEYWORDS: {co
fd30: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
fd40: 6f 6e 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  on}.**.** These 
fd50: 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68  constants are th
fd60: 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65  e available inte
fd70: 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ger configuratio
fd80: 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a  n options that.*
fd90: 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65 64 20  * can be passed 
fda0: 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67  as the first arg
fdb0: 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71  ument to the [sq
fdc0: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
fdd0: 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a  interface..**.**
fde0: 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69   New configurati
fdf0: 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62  on options may b
fe00: 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72  e added in futur
fe10: 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51  e releases of SQ
fe20: 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e  Lite..** Existin
fe30: 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  g configuration 
fe40: 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65  options might be
fe50: 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20   discontinued.  
fe60: 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20  Applications.** 
fe70: 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65  should check the
fe80: 20 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f   return code fro
fe90: 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  m [sqlite3_confi
fea0: 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72  g()] to make sur
feb0: 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61  e that.** the ca
fec0: 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 54 68 65 20  ll worked.  The 
fed0: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
fee0: 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c  )] interface wil
fef0: 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f  l return a.** no
ff00: 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f  n-zero [error co
ff10: 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74  de] if a discont
ff20: 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f  inued or unsuppo
ff30: 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69  rted configurati
ff40: 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20  on option.** is 
ff50: 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c  invoked..**.** <
ff60: 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  dl>.** [[SQLITE_
ff70: 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52  CONFIG_SINGLETHR
ff80: 45 41 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  EAD]] <dt>SQLITE
ff90: 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48  _CONFIG_SINGLETH
ffa0: 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  READ</dt>.** <dd
ffb0: 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72  >There are no ar
ffc0: 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20  guments to this 
ffd0: 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f  option.  ^This o
ffe0: 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a  ption sets the.*
fff0: 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  * [threading mod
10000 65 5d 20 74 6f 20 53 69 6e 67 6c 65 2d 74 68 72  e] to Single-thr
10010 65 61 64 2e 20 20 49 6e 20 6f 74 68 65 72 20 77  ead.  In other w
10020 6f 72 64 73 2c 20 69 74 20 64 69 73 61 62 6c 65  ords, it disable
10030 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 69 6e  s.** all mutexin
10040 67 20 61 6e 64 20 70 75 74 73 20 53 51 4c 69 74  g and puts SQLit
10050 65 20 69 6e 74 6f 20 61 20 6d 6f 64 65 20 77 68  e into a mode wh
10060 65 72 65 20 69 74 20 63 61 6e 20 6f 6e 6c 79 20  ere it can only 
10070 62 65 20 75 73 65 64 0a 2a 2a 20 62 79 20 61 20  be used.** by a 
10080 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20  single thread.  
10090 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63   ^If SQLite is c
100a0 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
100b0 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
100c0 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f  ADSAFE | SQLITE_
100d0 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f  THREADSAFE=0] co
100e0 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
100f0 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20  n then.** it is 
10100 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20  not possible to 
10110 63 68 61 6e 67 65 20 74 68 65 20 5b 74 68 72 65  change the [thre
10120 61 64 69 6e 67 20 6d 6f 64 65 5d 20 66 72 6f 6d  ading mode] from
10130 20 69 74 73 20 64 65 66 61 75 6c 74 0a 2a 2a 20   its default.** 
10140 76 61 6c 75 65 20 6f 66 20 53 69 6e 67 6c 65 2d  value of Single-
10150 74 68 72 65 61 64 20 61 6e 64 20 73 6f 20 5b 73  thread and so [s
10160 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
10170 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 0a 2a 2a   will return .**
10180 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
10190 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74  if called with t
101a0 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
101b0 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 0a 2a 2a  _SINGLETHREAD.**
101c0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
101d0 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ption.</dd>.**.*
101e0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
101f0 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 5d 20  G_MULTITHREAD]] 
10200 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
10210 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 3c 2f 64  G_MULTITHREAD</d
10220 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20  t>.** <dd>There 
10230 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73  are no arguments
10240 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e   to this option.
10250 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73    ^This option s
10260 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65  ets the.** [thre
10270 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 4d  ading mode] to M
10280 75 6c 74 69 2d 74 68 72 65 61 64 2e 20 20 49 6e  ulti-thread.  In
10290 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69 74   other words, it
102a0 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 6d 75 74   disables.** mut
102b0 65 78 69 6e 67 20 6f 6e 20 5b 64 61 74 61 62 61  exing on [databa
102c0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61  se connection] a
102d0 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  nd [prepared sta
102e0 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e  tement] objects.
102f0 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
10300 69 6f 6e 20 69 73 20 72 65 73 70 6f 6e 73 69 62  ion is responsib
10310 6c 65 20 66 6f 72 20 73 65 72 69 61 6c 69 7a 69  le for serializi
10320 6e 67 20 61 63 63 65 73 73 20 74 6f 0a 2a 2a 20  ng access to.** 
10330 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
10340 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70  tions] and [prep
10350 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d  ared statements]
10360 2e 20 20 42 75 74 20 6f 74 68 65 72 20 6d 75 74  .  But other mut
10370 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62  exes.** are enab
10380 6c 65 64 20 73 6f 20 74 68 61 74 20 53 51 4c 69  led so that SQLi
10390 74 65 20 77 69 6c 6c 20 62 65 20 73 61 66 65 20  te will be safe 
103a0 74 6f 20 75 73 65 20 69 6e 20 61 20 6d 75 6c 74  to use in a mult
103b0 69 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 65 6e  i-threaded.** en
103c0 76 69 72 6f 6e 6d 65 6e 74 20 61 73 20 6c 6f 6e  vironment as lon
103d0 67 20 61 73 20 6e 6f 20 74 77 6f 20 74 68 72 65  g as no two thre
103e0 61 64 73 20 61 74 74 65 6d 70 74 20 74 6f 20 75  ads attempt to u
103f0 73 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 5b  se the same.** [
10400 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
10410 69 6f 6e 5d 20 61 74 20 74 68 65 20 73 61 6d 65  ion] at the same
10420 20 74 69 6d 65 2e 20 20 5e 49 66 20 53 51 4c 69   time.  ^If SQLi
10430 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
10440 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49  ith.** the [SQLI
10450 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20  TE_THREADSAFE | 
10460 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
10470 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  E=0] compile-tim
10480 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a  e option then.**
10490 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69   it is not possi
104a0 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 4d  ble to set the M
104b0 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72  ulti-thread [thr
104c0 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64  eading mode] and
104d0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
104e0 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75  fig()] will retu
104f0 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  rn [SQLITE_ERROR
10500 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68  ] if called with
10510 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43   the.** SQLITE_C
10520 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41  ONFIG_MULTITHREA
10530 44 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  D configuration 
10540 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a  option.</dd>.**.
10550 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
10560 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 5d 5d 20  IG_SERIALIZED]] 
10570 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
10580 47 5f 53 45 52 49 41 4c 49 5a 45 44 3c 2f 64 74  G_SERIALIZED</dt
10590 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61  >.** <dd>There a
105a0 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20  re no arguments 
105b0 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20  to this option. 
105c0 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65   ^This option se
105d0 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61  ts the.** [threa
105e0 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 65  ding mode] to Se
105f0 72 69 61 6c 69 7a 65 64 2e 20 49 6e 20 6f 74 68  rialized. In oth
10600 65 72 20 77 6f 72 64 73 2c 20 74 68 69 73 20 6f  er words, this o
10610 70 74 69 6f 6e 20 65 6e 61 62 6c 65 73 0a 2a 2a  ption enables.**
10620 20 61 6c 6c 20 6d 75 74 65 78 65 73 20 69 6e 63   all mutexes inc
10630 6c 75 64 69 6e 67 20 74 68 65 20 72 65 63 75 72  luding the recur
10640 73 69 76 65 0a 2a 2a 20 6d 75 74 65 78 65 73 20  sive.** mutexes 
10650 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  on [database con
10660 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72  nection] and [pr
10670 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
10680 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 49 6e  ] objects..** In
10690 20 74 68 69 73 20 6d 6f 64 65 20 28 77 68 69 63   this mode (whic
106a0 68 20 69 73 20 74 68 65 20 64 65 66 61 75 6c 74  h is the default
106b0 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20   when SQLite is 
106c0 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
106d0 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
106e0 41 46 45 3d 31 5d 29 20 74 68 65 20 53 51 4c 69  AFE=1]) the SQLi
106f0 74 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20  te library will 
10700 69 74 73 65 6c 66 20 73 65 72 69 61 6c 69 7a 65  itself serialize
10710 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 5b 64   access.** to [d
10720 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
10730 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72  ons] and [prepar
10740 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 73  ed statements] s
10750 6f 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 61 70  o that the.** ap
10760 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 66 72 65  plication is fre
10770 65 20 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d  e to use the sam
10780 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
10790 65 63 74 69 6f 6e 5d 20 6f 72 20 74 68 65 0a 2a  ection] or the.*
107a0 2a 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64  * same [prepared
107b0 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 64   statement] in d
107c0 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 73  ifferent threads
107d0 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d   at the same tim
107e0 65 2e 0a 2a 2a 20 5e 49 66 20 53 51 4c 69 74 65  e..** ^If SQLite
107f0 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
10800 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  h.** the [SQLITE
10810 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51  _THREADSAFE | SQ
10820 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
10830 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  0] compile-time 
10840 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69  option then.** i
10850 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c  t is not possibl
10860 65 20 74 6f 20 73 65 74 20 74 68 65 20 53 65 72  e to set the Ser
10870 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69  ialized [threadi
10880 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20  ng mode] and.** 
10890 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
108a0 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b  )] will return [
108b0 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66  SQLITE_ERROR] if
108c0 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65   called with the
108d0 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  .** SQLITE_CONFI
108e0 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 63 6f 6e  G_SERIALIZED con
108f0 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
10900 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  n.</dd>.**.** [[
10910 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41  SQLITE_CONFIG_MA
10920 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  LLOC]] <dt>SQLIT
10930 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c  E_CONFIG_MALLOC<
10940 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54  /dt>.** <dd> ^(T
10950 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
10960 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
10970 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f  nt which is a po
10980 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69  inter to an.** i
10990 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b  nstance of the [
109a0 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
109b0 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20  ods] structure. 
109c0 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70   The argument sp
109d0 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72  ecifies.** alter
109e0 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c  native low-level
109f0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
10a00 6f 6e 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62  on routines to b
10a10 65 20 75 73 65 64 20 69 6e 20 70 6c 61 63 65 20  e used in place 
10a20 6f 66 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79  of.** the memory
10a30 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74   allocation rout
10a40 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20  ines built into 
10a50 53 51 4c 69 74 65 2e 29 5e 20 5e 53 51 4c 69 74  SQLite.)^ ^SQLit
10a60 65 20 6d 61 6b 65 73 0a 2a 2a 20 69 74 73 20 6f  e makes.** its o
10a70 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20  wn private copy 
10a80 6f 66 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f  of the content o
10a90 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
10aa0 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75  em_methods] stru
10ab0 63 74 75 72 65 0a 2a 2a 20 62 65 66 6f 72 65 20  cture.** before 
10ac0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  the [sqlite3_con
10ad0 66 69 67 28 29 5d 20 63 61 6c 6c 20 72 65 74 75  fig()] call retu
10ae0 72 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  rns.</dd>.**.** 
10af0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
10b00 47 45 54 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e  GETMALLOC]] <dt>
10b10 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
10b20 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20  TMALLOC</dt>.** 
10b30 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69  <dd> ^(This opti
10b40 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
10b50 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
10b60 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
10b70 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20   an.** instance 
10b80 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
10b90 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72  mem_methods] str
10ba0 75 63 74 75 72 65 2e 20 20 54 68 65 20 5b 73 71  ucture.  The [sq
10bb0 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
10bc0 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20  s].** structure 
10bd0 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74  is filled with t
10be0 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66  he currently def
10bf0 69 6e 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ined memory allo
10c00 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e  cation routines.
10c10 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f  )^.** This optio
10c20 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  n can be used to
10c30 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65   overload the de
10c40 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c  fault memory all
10c50 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69  ocation.** routi
10c60 6e 65 73 20 77 69 74 68 20 61 20 77 72 61 70 70  nes with a wrapp
10c70 65 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74 69  er that simulati
10c80 6f 6e 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ons memory alloc
10c90 61 74 69 6f 6e 20 66 61 69 6c 75 72 65 20 6f 72  ation failure or
10ca0 0a 2a 2a 20 74 72 61 63 6b 73 20 6d 65 6d 6f 72  .** tracks memor
10cb0 79 20 75 73 61 67 65 2c 20 66 6f 72 20 65 78 61  y usage, for exa
10cc0 6d 70 6c 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  mple. </dd>.**.*
10cd0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
10ce0 47 5f 4d 45 4d 53 54 41 54 55 53 5d 5d 20 3c 64  G_MEMSTATUS]] <d
10cf0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
10d00 4d 45 4d 53 54 41 54 55 53 3c 2f 64 74 3e 0a 2a  MEMSTATUS</dt>.*
10d10 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74  * <dd> ^This opt
10d20 69 6f 6e 20 74 61 6b 65 73 20 73 69 6e 67 6c 65  ion takes single
10d30 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 70   argument of typ
10d40 65 20 69 6e 74 2c 20 69 6e 74 65 72 70 72 65 74  e int, interpret
10d50 65 64 20 61 73 20 61 20 0a 2a 2a 20 62 6f 6f 6c  ed as a .** bool
10d60 65 61 6e 2c 20 77 68 69 63 68 20 65 6e 61 62 6c  ean, which enabl
10d70 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74  es or disables t
10d80 68 65 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66  he collection of
10d90 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
10da0 6f 6e 20 0a 2a 2a 20 73 74 61 74 69 73 74 69 63  on .** statistic
10db0 73 2e 20 5e 28 57 68 65 6e 20 6d 65 6d 6f 72 79  s. ^(When memory
10dc0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74   allocation stat
10dd0 69 73 74 69 63 73 20 61 72 65 20 64 69 73 61 62  istics are disab
10de0 6c 65 64 2c 20 74 68 65 20 0a 2a 2a 20 66 6f 6c  led, the .** fol
10df0 6c 6f 77 69 6e 67 20 53 51 4c 69 74 65 20 69 6e  lowing SQLite in
10e00 74 65 72 66 61 63 65 73 20 62 65 63 6f 6d 65 20  terfaces become 
10e10 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e 61 6c 3a  non-operational:
10e20 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20  .**   <ul>.**   
10e30 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65  <li> [sqlite3_me
10e40 6d 6f 72 79 5f 75 73 65 64 28 29 5d 0a 2a 2a 20  mory_used()].** 
10e50 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f    <li> [sqlite3_
10e60 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
10e70 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73  ()].**   <li> [s
10e80 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70  qlite3_soft_heap
10e90 5f 6c 69 6d 69 74 36 34 28 29 5d 0a 2a 2a 20 20  _limit64()].**  
10ea0 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73   <li> [sqlite3_s
10eb0 74 61 74 75 73 28 29 5d 0a 2a 2a 20 20 20 3c 2f  tatus()].**   </
10ec0 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72 79  ul>)^.** ^Memory
10ed0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74   allocation stat
10ee0 69 73 74 69 63 73 20 61 72 65 20 65 6e 61 62 6c  istics are enabl
10ef0 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 75 6e  ed by default un
10f00 6c 65 73 73 20 53 51 4c 69 74 65 20 69 73 0a 2a  less SQLite is.*
10f10 2a 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  * compiled with 
10f20 5b 53 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f  [SQLITE_DEFAULT_
10f30 4d 45 4d 53 54 41 54 55 53 5d 3d 30 20 69 6e 20  MEMSTATUS]=0 in 
10f40 77 68 69 63 68 20 63 61 73 65 20 6d 65 6d 6f 72  which case memor
10f50 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  y.** allocation 
10f60 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20 64  statistics are d
10f70 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75  isabled by defau
10f80 6c 74 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a  lt..** </dd>.**.
10f90 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
10fa0 49 47 5f 53 43 52 41 54 43 48 5d 5d 20 3c 64 74  IG_SCRATCH]] <dt
10fb0 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  >SQLITE_CONFIG_S
10fc0 43 52 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20 3c  CRATCH</dt>.** <
10fd0 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  dd> ^This option
10fe0 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61   specifies a sta
10ff0 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65  tic memory buffe
11000 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 61  r that SQLite ca
11010 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20 73 63 72  n use for.** scr
11020 61 74 63 68 20 6d 65 6d 6f 72 79 2e 20 20 54 68  atch memory.  Th
11030 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72  ere are three ar
11040 67 75 6d 65 6e 74 73 3a 20 20 41 20 70 6f 69 6e  guments:  A poin
11050 74 65 72 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a  ter an 8-byte.**
11060 20 61 6c 69 67 6e 65 64 20 6d 65 6d 6f 72 79 20   aligned memory 
11070 62 75 66 66 65 72 20 66 72 6f 6d 20 77 68 69 63  buffer from whic
11080 68 20 74 68 65 20 73 63 72 61 74 63 68 20 61 6c  h the scratch al
11090 6c 6f 63 61 74 69 6f 6e 73 20 77 69 6c 6c 20 62  locations will b
110a0 65 0a 2a 2a 20 64 72 61 77 6e 2c 20 74 68 65 20  e.** drawn, the 
110b0 73 69 7a 65 20 6f 66 20 65 61 63 68 20 73 63 72  size of each scr
110c0 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  atch allocation 
110d0 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74 68 65  (sz),.** and the
110e0 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
110f0 6f 66 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63  of scratch alloc
11100 61 74 69 6f 6e 73 20 28 4e 29 2e 20 20 54 68 65  ations (N).  The
11110 20 73 7a 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20   sz.** argument 
11120 6d 75 73 74 20 62 65 20 61 20 6d 75 6c 74 69 70  must be a multip
11130 6c 65 20 6f 66 20 31 36 2e 0a 2a 2a 20 54 68 65  le of 16..** The
11140 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
11150 6d 75 73 74 20 62 65 20 61 20 70 6f 69 6e 74 65  must be a pointe
11160 72 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 61  r to an 8-byte a
11170 6c 69 67 6e 65 64 20 62 75 66 66 65 72 0a 2a 2a  ligned buffer.**
11180 20 6f 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a   of at least sz*
11190 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72  N bytes of memor
111a0 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69  y..** ^SQLite wi
111b0 6c 6c 20 75 73 65 20 6e 6f 20 6d 6f 72 65 20 74  ll use no more t
111c0 68 61 6e 20 74 77 6f 20 73 63 72 61 74 63 68 20  han two scratch 
111d0 62 75 66 66 65 72 73 20 70 65 72 20 74 68 72 65  buffers per thre
111e0 61 64 2e 20 20 53 6f 0a 2a 2a 20 4e 20 73 68 6f  ad.  So.** N sho
111f0 75 6c 64 20 62 65 20 73 65 74 20 74 6f 20 74 77  uld be set to tw
11200 69 63 65 20 74 68 65 20 65 78 70 65 63 74 65 64  ice the expected
11210 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
11220 6f 66 20 74 68 72 65 61 64 73 2e 0a 2a 2a 20 5e  of threads..** ^
11230 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65  SQLite will neve
11240 72 20 72 65 71 75 69 72 65 20 61 20 73 63 72 61  r require a scra
11250 74 63 68 20 62 75 66 66 65 72 20 74 68 61 74 20  tch buffer that 
11260 69 73 20 6d 6f 72 65 20 74 68 61 6e 20 36 0a 2a  is more than 6.*
11270 2a 20 74 69 6d 65 73 20 74 68 65 20 64 61 74 61  * times the data
11280 62 61 73 65 20 70 61 67 65 20 73 69 7a 65 2e 20  base page size. 
11290 5e 49 66 20 53 51 4c 69 74 65 20 6e 65 65 64 73  ^If SQLite needs
112a0 20 6e 65 65 64 73 20 61 64 64 69 74 69 6f 6e 61   needs additiona
112b0 6c 0a 2a 2a 20 73 63 72 61 74 63 68 20 6d 65 6d  l.** scratch mem
112c0 6f 72 79 20 62 65 79 6f 6e 64 20 77 68 61 74 20  ory beyond what 
112d0 69 73 20 70 72 6f 76 69 64 65 64 20 62 79 20 74  is provided by t
112e0 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  his configuratio
112f0 6e 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 0a  n option, then .
11300 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ** [sqlite3_mall
11310 6f 63 28 29 5d 20 77 69 6c 6c 20 62 65 20 75 73  oc()] will be us
11320 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65  ed to obtain the
11330 20 6d 65 6d 6f 72 79 20 6e 65 65 64 65 64 2e 3c   memory needed.<
11340 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
11350 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43  ITE_CONFIG_PAGEC
11360 41 43 48 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  ACHE]] <dt>SQLIT
11370 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43  E_CONFIG_PAGECAC
11380 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  HE</dt>.** <dd> 
11390 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65  ^This option spe
113a0 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20  cifies a static 
113b0 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68  memory buffer th
113c0 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73  at SQLite can us
113d0 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 64 61 74  e for.** the dat
113e0 61 62 61 73 65 20 70 61 67 65 20 63 61 63 68 65  abase page cache
113f0 20 77 69 74 68 20 74 68 65 20 64 65 66 61 75 6c   with the defaul
11400 74 20 70 61 67 65 20 63 61 63 68 65 20 69 6d 70  t page cache imp
11410 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 0a 2a  lementation.  .*
11420 2a 20 54 68 69 73 20 63 6f 6e 66 69 67 75 72 61  * This configura
11430 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 6f 74 20  tion should not 
11440 62 65 20 75 73 65 64 20 69 66 20 61 6e 20 61 70  be used if an ap
11450 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
11460 20 70 61 67 65 0a 2a 2a 20 63 61 63 68 65 20 69   page.** cache i
11470 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73  mplementation is
11480 20 6c 6f 61 64 65 64 20 75 73 69 6e 67 20 74 68   loaded using th
11490 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
114a0 50 43 41 43 48 45 32 20 6f 70 74 69 6f 6e 2e 0a  PCACHE2 option..
114b0 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74 68 72  ** There are thr
114c0 65 65 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  ee arguments to 
114d0 74 68 69 73 20 6f 70 74 69 6f 6e 3a 20 41 20 70  this option: A p
114e0 6f 69 6e 74 65 72 20 74 6f 20 38 2d 62 79 74 65  ointer to 8-byte
114f0 20 61 6c 69 67 6e 65 64 0a 2a 2a 20 6d 65 6d 6f   aligned.** memo
11500 72 79 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20  ry, the size of 
11510 65 61 63 68 20 70 61 67 65 20 62 75 66 66 65 72  each page buffer
11520 20 28 73 7a 29 2c 20 61 6e 64 20 74 68 65 20 6e   (sz), and the n
11530 75 6d 62 65 72 20 6f 66 20 70 61 67 65 73 20 28  umber of pages (
11540 4e 29 2e 0a 2a 2a 20 54 68 65 20 73 7a 20 61 72  N)..** The sz ar
11550 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65  gument should be
11560 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
11570 20 6c 61 72 67 65 73 74 20 64 61 74 61 62 61 73   largest databas
11580 65 20 70 61 67 65 0a 2a 2a 20 28 61 20 70 6f 77  e page.** (a pow
11590 65 72 20 6f 66 20 74 77 6f 20 62 65 74 77 65 65  er of two betwee
115a0 6e 20 35 31 32 20 61 6e 64 20 33 32 37 36 38 29  n 512 and 32768)
115b0 20 70 6c 75 73 20 61 20 6c 69 74 74 6c 65 20 65   plus a little e
115c0 78 74 72 61 20 66 6f 72 20 65 61 63 68 0a 2a 2a  xtra for each.**
115d0 20 70 61 67 65 20 68 65 61 64 65 72 2e 20 20 5e   page header.  ^
115e0 54 68 65 20 70 61 67 65 20 68 65 61 64 65 72 20  The page header 
115f0 73 69 7a 65 20 69 73 20 32 30 20 74 6f 20 34 30  size is 20 to 40
11600 20 62 79 74 65 73 20 64 65 70 65 6e 64 69 6e 67   bytes depending
11610 20 6f 6e 0a 2a 2a 20 74 68 65 20 68 6f 73 74 20   on.** the host 
11620 61 72 63 68 69 74 65 63 74 75 72 65 2e 20 20 5e  architecture.  ^
11630 49 74 20 69 73 20 68 61 72 6d 6c 65 73 73 2c 20  It is harmless, 
11640 61 70 61 72 74 20 66 72 6f 6d 20 74 68 65 20 77  apart from the w
11650 61 73 74 65 64 20 6d 65 6d 6f 72 79 2c 0a 2a 2a  asted memory,.**
11660 20 74 6f 20 6d 61 6b 65 20 73 7a 20 61 20 6c 69   to make sz a li
11670 74 74 6c 65 20 74 6f 6f 20 6c 61 72 67 65 2e 20  ttle too large. 
11680 20 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 61 72   The first.** ar
11690 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 70 6f  gument should po
116a0 69 6e 74 20 74 6f 20 61 6e 20 61 6c 6c 6f 63 61  int to an alloca
116b0 74 69 6f 6e 20 6f 66 20 61 74 20 6c 65 61 73 74  tion of at least
116c0 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d   sz*N bytes of m
116d0 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74  emory..** ^SQLit
116e0 65 20 77 69 6c 6c 20 75 73 65 20 74 68 65 20 6d  e will use the m
116f0 65 6d 6f 72 79 20 70 72 6f 76 69 64 65 64 20 62  emory provided b
11700 79 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  y the first argu
11710 6d 65 6e 74 20 74 6f 20 73 61 74 69 73 66 79 20  ment to satisfy 
11720 69 74 73 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6e 65  its.** memory ne
11730 65 64 73 20 66 6f 72 20 74 68 65 20 66 69 72 73  eds for the firs
11740 74 20 4e 20 70 61 67 65 73 20 74 68 61 74 20 69  t N pages that i
11750 74 20 61 64 64 73 20 74 6f 20 63 61 63 68 65 2e  t adds to cache.
11760 20 20 5e 49 66 20 61 64 64 69 74 69 6f 6e 61 6c    ^If additional
11770 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 65 20 6d  .** page cache m
11780 65 6d 6f 72 79 20 69 73 20 6e 65 65 64 65 64 20  emory is needed 
11790 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70  beyond what is p
117a0 72 6f 76 69 64 65 64 20 62 79 20 74 68 69 73 20  rovided by this 
117b0 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 0a 2a 2a 20  option, then.** 
117c0 53 51 4c 69 74 65 20 67 6f 65 73 20 74 6f 20 5b  SQLite goes to [
117d0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
117e0 5d 20 66 6f 72 20 74 68 65 20 61 64 64 69 74 69  ] for the additi
117f0 6f 6e 61 6c 20 73 74 6f 72 61 67 65 20 73 70 61  onal storage spa
11800 63 65 2e 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74  ce..** The point
11810 65 72 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  er in the first 
11820 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 0a 2a 2a  argument must.**
11830 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61   be aligned to a
11840 6e 20 38 2d 62 79 74 65 20 62 6f 75 6e 64 61 72  n 8-byte boundar
11850 79 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20  y or subsequent 
11860 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69  behavior of SQLi
11870 74 65 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 75 6e  te.** will be un
11880 64 65 66 69 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a  defined.</dd>.**
11890 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
118a0 46 49 47 5f 48 45 41 50 5d 5d 20 3c 64 74 3e 53  FIG_HEAP]] <dt>S
118b0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41  QLITE_CONFIG_HEA
118c0 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  P</dt>.** <dd> ^
118d0 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63  This option spec
118e0 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d  ifies a static m
118f0 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68 61  emory buffer tha
11900 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73  t SQLite will us
11910 65 0a 2a 2a 20 66 6f 72 20 61 6c 6c 20 6f 66 20  e.** for all of 
11920 69 74 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f  its dynamic memo
11930 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65  ry allocation ne
11940 65 64 73 20 62 65 79 6f 6e 64 20 74 68 6f 73 65  eds beyond those
11950 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 66 6f 72   provided.** for
11960 20 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46   by [SQLITE_CONF
11970 49 47 5f 53 43 52 41 54 43 48 5d 20 61 6e 64 20  IG_SCRATCH] and 
11980 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  [SQLITE_CONFIG_P
11990 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 54 68  AGECACHE]..** Th
119a0 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72  ere are three ar
119b0 67 75 6d 65 6e 74 73 3a 20 41 6e 20 38 2d 62 79  guments: An 8-by
119c0 74 65 20 61 6c 69 67 6e 65 64 20 70 6f 69 6e 74  te aligned point
119d0 65 72 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79  er to the memory
119e0 2c 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20  ,.** the number 
119f0 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  of bytes in the 
11a00 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 2c 20 61  memory buffer, a
11a10 6e 64 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61  nd the minimum a
11a20 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 2e 0a  llocation size..
11a30 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 72 73 74  ** ^If the first
11a40 20 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65   pointer (the me
11a50 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 69 73  mory pointer) is
11a60 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 53 51 4c 69   NULL, then SQLi
11a70 74 65 20 72 65 76 65 72 74 73 0a 2a 2a 20 74 6f  te reverts.** to
11a80 20 75 73 69 6e 67 20 69 74 73 20 64 65 66 61 75   using its defau
11a90 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  lt memory alloca
11aa0 74 6f 72 20 28 74 68 65 20 73 79 73 74 65 6d 20  tor (the system 
11ab0 6d 61 6c 6c 6f 63 28 29 20 69 6d 70 6c 65 6d 65  malloc() impleme
11ac0 6e 74 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64  ntation),.** und
11ad0 6f 69 6e 67 20 61 6e 79 20 70 72 69 6f 72 20 69  oing any prior i
11ae0 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 53 51  nvocation of [SQ
11af0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c  LITE_CONFIG_MALL
11b00 4f 43 5d 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a  OC].  ^If the.**
11b10 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 20   memory pointer 
11b20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20  is not NULL and 
11b30 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 45  either [SQLITE_E
11b40 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 33 5d 20 6f  NABLE_MEMSYS3] o
11b50 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41  r.** [SQLITE_ENA
11b60 42 4c 45 5f 4d 45 4d 53 59 53 35 5d 20 61 72 65  BLE_MEMSYS5] are
11b70 20 64 65 66 69 6e 65 64 2c 20 74 68 65 6e 20 74   defined, then t
11b80 68 65 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6d  he alternative m
11b90 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74  emory.** allocat
11ba0 6f 72 20 69 73 20 65 6e 67 61 67 65 64 20 74 6f  or is engaged to
11bb0 20 68 61 6e 64 6c 65 20 61 6c 6c 20 6f 66 20 53   handle all of S
11bc0 51 4c 69 74 65 73 20 6d 65 6d 6f 72 79 20 61 6c  QLites memory al
11bd0 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 0a  location needs..
11be0 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 6f 69  ** The first poi
11bf0 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79  nter (the memory
11c00 20 70 6f 69 6e 74 65 72 29 20 6d 75 73 74 20 62   pointer) must b
11c10 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20  e aligned to an 
11c20 38 2d 62 79 74 65 0a 2a 2a 20 62 6f 75 6e 64 61  8-byte.** bounda
11c30 72 79 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74  ry or subsequent
11c40 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c   behavior of SQL
11c50 69 74 65 20 77 69 6c 6c 20 62 65 20 75 6e 64 65  ite will be unde
11c60 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 6d 69  fined..** The mi
11c70 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e  nimum allocation
11c80 20 73 69 7a 65 20 69 73 20 63 61 70 70 65 64 20   size is capped 
11c90 61 74 20 32 2a 2a 31 32 2e 20 52 65 61 73 6f 6e  at 2**12. Reason
11ca0 61 62 6c 65 20 76 61 6c 75 65 73 0a 2a 2a 20 66  able values.** f
11cb0 6f 72 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61  or the minimum a
11cc0 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 61  llocation size a
11cd0 72 65 20 32 2a 2a 35 20 74 68 72 6f 75 67 68 20  re 2**5 through 
11ce0 32 2a 2a 38 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  2**8.</dd>.**.**
11cf0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
11d00 5f 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c  _MUTEX]] <dt>SQL
11d10 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
11d20 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28  </dt>.** <dd> ^(
11d30 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
11d40 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
11d50 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70  ent which is a p
11d60 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20  ointer to an.** 
11d70 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
11d80 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d  [sqlite3_mutex_m
11d90 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72  ethods] structur
11da0 65 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74  e.  The argument
11db0 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c   specifies.** al
11dc0 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65  ternative low-le
11dd0 76 65 6c 20 6d 75 74 65 78 20 72 6f 75 74 69 6e  vel mutex routin
11de0 65 73 20 74 6f 20 62 65 20 75 73 65 64 20 69 6e  es to be used in
11df0 20 70 6c 61 63 65 0a 2a 2a 20 74 68 65 20 6d 75   place.** the mu
11e00 74 65 78 20 72 6f 75 74 69 6e 65 73 20 62 75 69  tex routines bui
11e10 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29  lt into SQLite.)
11e20 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73  ^  ^SQLite makes
11e30 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a   a copy of the.*
11e40 2a 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65  * content of the
11e50 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
11e60 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75  methods] structu
11e70 72 65 20 62 65 66 6f 72 65 20 74 68 65 20 63 61  re before the ca
11e80 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ll to.** [sqlite
11e90 33 5f 63 6f 6e 66 69 67 28 29 5d 20 72 65 74 75  3_config()] retu
11ea0 72 6e 73 2e 20 5e 49 66 20 53 51 4c 69 74 65 20  rns. ^If SQLite 
11eb0 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
11ec0 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  .** the [SQLITE_
11ed0 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c  THREADSAFE | SQL
11ee0 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30  ITE_THREADSAFE=0
11ef0 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
11f00 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68  ption then.** th
11f10 65 20 65 6e 74 69 72 65 20 6d 75 74 65 78 69 6e  e entire mutexin
11f20 67 20 73 75 62 73 79 73 74 65 6d 20 69 73 20 6f  g subsystem is o
11f30 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20  mitted from the 
11f40 62 75 69 6c 64 20 61 6e 64 20 68 65 6e 63 65 20  build and hence 
11f50 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c  calls to.** [sql
11f60 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77  ite3_config()] w
11f70 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43  ith the SQLITE_C
11f80 4f 4e 46 49 47 5f 4d 55 54 45 58 20 63 6f 6e 66  ONFIG_MUTEX conf
11f90 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
11fa0 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20   will.** return 
11fb0 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c  [SQLITE_ERROR].<
11fc0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
11fd0 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55  ITE_CONFIG_GETMU
11fe0 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  TEX]] <dt>SQLITE
11ff0 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58  _CONFIG_GETMUTEX
12000 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28  </dt>.** <dd> ^(
12010 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
12020 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
12030 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70  ent which is a p
12040 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20  ointer to an.** 
12050 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
12060 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d  [sqlite3_mutex_m
12070 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72  ethods] structur
12080 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69  e.  The.** [sqli
12090 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64  te3_mutex_method
120a0 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20  s].** structure 
120b0 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74  is filled with t
120c0 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66  he currently def
120d0 69 6e 65 64 20 6d 75 74 65 78 20 72 6f 75 74 69  ined mutex routi
120e0 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f  nes.)^.** This o
120f0 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65  ption can be use
12100 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68  d to overload th
12110 65 20 64 65 66 61 75 6c 74 20 6d 75 74 65 78 20  e default mutex 
12120 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f  allocation.** ro
12130 75 74 69 6e 65 73 20 77 69 74 68 20 61 20 77 72  utines with a wr
12140 61 70 70 65 72 20 75 73 65 64 20 74 6f 20 74 72  apper used to tr
12150 61 63 6b 20 6d 75 74 65 78 20 75 73 61 67 65 20  ack mutex usage 
12160 66 6f 72 20 70 65 72 66 6f 72 6d 61 6e 63 65 0a  for performance.
12170 2a 2a 20 70 72 6f 66 69 6c 69 6e 67 20 6f 72 20  ** profiling or 
12180 74 65 73 74 69 6e 67 2c 20 66 6f 72 20 65 78 61  testing, for exa
12190 6d 70 6c 65 2e 20 20 20 5e 49 66 20 53 51 4c 69  mple.   ^If SQLi
121a0 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
121b0 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49  ith.** the [SQLI
121c0 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20  TE_THREADSAFE | 
121d0 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
121e0 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  E=0] compile-tim
121f0 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a  e option then.**
12200 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65   the entire mute
12210 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69  xing subsystem i
12220 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74  s omitted from t
12230 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e  he build and hen
12240 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b  ce calls to.** [
12250 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
12260 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54  ] with the SQLIT
12270 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45  E_CONFIG_GETMUTE
12280 58 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  X configuration 
12290 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72  option will.** r
122a0 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52  eturn [SQLITE_ER
122b0 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ROR].</dd>.**.**
122c0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
122d0 5f 4c 4f 4f 4b 41 53 49 44 45 5d 5d 20 3c 64 74  _LOOKASIDE]] <dt
122e0 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c  >SQLITE_CONFIG_L
122f0 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a  OOKASIDE</dt>.**
12300 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74   <dd> ^(This opt
12310 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72  ion takes two ar
12320 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74  guments that det
12330 65 72 6d 69 6e 65 20 74 68 65 20 64 65 66 61 75  ermine the defau
12340 6c 74 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c  lt.** memory all
12350 6f 63 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 20  ocation for the 
12360 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79  lookaside memory
12370 20 61 6c 6c 6f 63 61 74 6f 72 20 6f 6e 20 65 61   allocator on ea
12380 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  ch.** [database 
12390 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68  connection].  Th
123a0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
123b0 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20   is the.** size 
123c0 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64  of each lookasid
123d0 65 20 62 75 66 66 65 72 20 73 6c 6f 74 20 61 6e  e buffer slot an
123e0 64 20 74 68 65 20 73 65 63 6f 6e 64 20 69 73 20  d the second is 
123f0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a  the number of.**
12400 20 73 6c 6f 74 73 20 61 6c 6c 6f 63 61 74 65 64   slots allocated
12410 20 74 6f 20 65 61 63 68 20 64 61 74 61 62 61 73   to each databas
12420 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 29 5e 20  e connection.)^ 
12430 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 73   ^(This option s
12440 65 74 73 20 74 68 65 0a 2a 2a 20 3c 69 3e 64 65  ets the.** <i>de
12450 66 61 75 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 73  fault</i> lookas
12460 69 64 65 20 73 69 7a 65 2e 20 54 68 65 20 5b 53  ide size. The [S
12470 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c  QLITE_DBCONFIG_L
12480 4f 4f 4b 41 53 49 44 45 5d 0a 2a 2a 20 76 65 72  OOKASIDE].** ver
12490 62 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62  b to [sqlite3_db
124a0 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6e 20 62  _config()] can b
124b0 65 20 75 73 65 64 20 74 6f 20 63 68 61 6e 67 65  e used to change
124c0 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a   the lookaside.*
124d0 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  * configuration 
124e0 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 63 6f  on individual co
124f0 6e 6e 65 63 74 69 6f 6e 73 2e 29 5e 20 3c 2f 64  nnections.)^ </d
12500 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
12510 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32  E_CONFIG_PCACHE2
12520 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
12530 4e 46 49 47 5f 50 43 41 43 48 45 32 3c 2f 64 74  NFIG_PCACHE2</dt
12540 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73  >.** <dd> ^(This
12550 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
12560 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
12570 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74  which is a point
12580 65 72 20 74 6f 0a 2a 2a 20 61 6e 20 5b 73 71 6c  er to.** an [sql
12590 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68  ite3_pcache_meth
125a0 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20 54  ods2] object.  T
125b0 68 69 73 20 6f 62 6a 65 63 74 20 73 70 65 63 69  his object speci
125c0 66 69 65 73 20 74 68 65 20 69 6e 74 65 72 66 61  fies the interfa
125d0 63 65 0a 2a 2a 20 74 6f 20 61 20 63 75 73 74 6f  ce.** to a custo
125e0 6d 20 70 61 67 65 20 63 61 63 68 65 20 69 6d 70  m page cache imp
125f0 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 29 5e 20 20  lementation.)^  
12600 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20  ^SQLite makes a 
12610 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f  copy of the.** o
12620 62 6a 65 63 74 20 61 6e 64 20 75 73 65 73 20 69  bject and uses i
12630 74 20 66 6f 72 20 70 61 67 65 20 63 61 63 68 65  t for page cache
12640 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
12650 6f 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ons.</dd>.**.** 
12660 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
12670 47 45 54 50 43 41 43 48 45 32 5d 5d 20 3c 64 74  GETPCACHE2]] <dt
12680 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  >SQLITE_CONFIG_G
12690 45 54 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a 2a  ETPCACHE2</dt>.*
126a0 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70  * <dd> ^(This op
126b0 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
126c0 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69  gle argument whi
126d0 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  ch is a pointer 
126e0 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65  to an.** [sqlite
126f0 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73  3_pcache_methods
12700 32 5d 20 6f 62 6a 65 63 74 2e 20 20 53 51 4c 69  2] object.  SQLi
12710 74 65 20 63 6f 70 69 65 73 20 6f 66 20 74 68 65  te copies of the
12720 20 63 75 72 72 65 6e 74 0a 2a 2a 20 70 61 67 65   current.** page
12730 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74   cache implement
12740 61 74 69 6f 6e 20 69 6e 74 6f 20 74 68 61 74 20  ation into that 
12750 6f 62 6a 65 63 74 2e 29 5e 20 3c 2f 64 64 3e 0a  object.)^ </dd>.
12760 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
12770 4f 4e 46 49 47 5f 4c 4f 47 5d 5d 20 3c 64 74 3e  ONFIG_LOG]] <dt>
12780 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
12790 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  G</dt>.** <dd> ^
127a0 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
127b0 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 74 61 6b  G_LOG option tak
127c0 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73  es two arguments
127d0 3a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  : a pointer to a
127e0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 69 74  .** function wit
127f0 68 20 61 20 63 61 6c 6c 20 73 69 67 6e 61 74 75  h a call signatu
12800 72 65 20 6f 66 20 76 6f 69 64 28 2a 29 28 76 6f  re of void(*)(vo
12810 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68  id*,int,const ch
12820 61 72 2a 29 2c 20 0a 2a 2a 20 61 6e 64 20 61 20  ar*), .** and a 
12830 70 6f 69 6e 74 65 72 20 74 6f 20 76 6f 69 64 2e  pointer to void.
12840 20 5e 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f   ^If the functio
12850 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74  n pointer is not
12860 20 4e 55 4c 4c 2c 20 69 74 20 69 73 0a 2a 2a 20   NULL, it is.** 
12870 69 6e 76 6f 6b 65 64 20 62 79 20 5b 73 71 6c 69  invoked by [sqli
12880 74 65 33 5f 6c 6f 67 28 29 5d 20 74 6f 20 70 72  te3_log()] to pr
12890 6f 63 65 73 73 20 65 61 63 68 20 6c 6f 67 67 69  ocess each loggi
128a0 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74  ng event.  ^If t
128b0 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70  he.** function p
128c0 6f 69 6e 74 65 72 20 69 73 20 4e 55 4c 4c 2c 20  ointer is NULL, 
128d0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67  the [sqlite3_log
128e0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 62 65  ()] interface be
128f0 63 6f 6d 65 73 20 61 20 6e 6f 2d 6f 70 2e 0a 2a  comes a no-op..*
12900 2a 20 5e 54 68 65 20 76 6f 69 64 20 70 6f 69 6e  * ^The void poin
12910 74 65 72 20 74 68 61 74 20 69 73 20 74 68 65 20  ter that is the 
12920 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
12930 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  to SQLITE_CONFIG
12940 5f 4c 4f 47 20 69 73 0a 2a 2a 20 70 61 73 73 65  _LOG is.** passe
12950 64 20 74 68 72 6f 75 67 68 20 61 73 20 74 68 65  d through as the
12960 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
12970 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74   to the applicat
12980 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67  ion-defined logg
12990 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77  er.** function w
129a0 68 65 6e 65 76 65 72 20 74 68 61 74 20 66 75 6e  henever that fun
129b0 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64  ction is invoked
129c0 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70  .  ^The second p
129d0 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74  arameter to.** t
129e0 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69  he logger functi
129f0 6f 6e 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20  on is a copy of 
12a00 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
12a10 74 65 72 20 74 6f 20 74 68 65 20 63 6f 72 72 65  ter to the corre
12a20 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 5b 73 71 6c  sponding.** [sql
12a30 69 74 65 33 5f 6c 6f 67 28 29 5d 20 63 61 6c 6c  ite3_log()] call
12a40 20 61 6e 64 20 69 73 20 69 6e 74 65 6e 64 65 64   and is intended
12a50 20 74 6f 20 62 65 20 61 20 5b 72 65 73 75 6c 74   to be a [result
12a60 20 63 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20   code] or an.** 
12a70 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  [extended result
12a80 20 63 6f 64 65 5d 2e 20 20 5e 54 68 65 20 74 68   code].  ^The th
12a90 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 70 61  ird parameter pa
12aa0 73 73 65 64 20 74 6f 20 74 68 65 20 6c 6f 67 67  ssed to the logg
12ab0 65 72 20 69 73 0a 2a 2a 20 6c 6f 67 20 6d 65 73  er is.** log mes
12ac0 73 61 67 65 20 61 66 74 65 72 20 66 6f 72 6d 61  sage after forma
12ad0 74 74 69 6e 67 20 76 69 61 20 5b 73 71 6c 69 74  tting via [sqlit
12ae0 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 2e 0a  e3_snprintf()]..
12af0 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 6c 6f  ** The SQLite lo
12b00 67 67 69 6e 67 20 69 6e 74 65 72 66 61 63 65 20  gging interface 
12b10 69 73 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74  is not reentrant
12b20 3b 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e  ; the logger fun
12b30 63 74 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69 65  ction.** supplie
12b40 64 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61  d by the applica
12b50 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 69 6e  tion must not in
12b60 76 6f 6b 65 20 61 6e 79 20 53 51 4c 69 74 65 20  voke any SQLite 
12b70 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 49 6e  interface..** In
12b80 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65   a multi-threade
12b90 64 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20 74  d application, t
12ba0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
12bb0 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a  efined logger.**
12bc0 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 62   function must b
12bd0 65 20 74 68 72 65 61 64 73 61 66 65 2e 20 3c 2f  e threadsafe. </
12be0 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
12bf0 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 5d 20  TE_CONFIG_URI]] 
12c00 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
12c10 47 5f 55 52 49 0a 2a 2a 20 3c 64 64 3e 20 54 68  G_URI.** <dd> Th
12c20 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
12c30 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
12c40 74 20 6f 66 20 74 79 70 65 20 69 6e 74 2e 20 49  t of type int. I
12c50 66 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e  f non-zero, then
12c60 0a 2a 2a 20 55 52 49 20 68 61 6e 64 6c 69 6e 67  .** URI handling
12c70 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 65 6e 61   is globally ena
12c80 62 6c 65 64 2e 20 49 66 20 74 68 65 20 70 61 72  bled. If the par
12c90 61 6d 65 74 65 72 20 69 73 20 7a 65 72 6f 2c 20  ameter is zero, 
12ca0 74 68 65 6e 20 55 52 49 20 68 61 6e 64 6c 69 6e  then URI handlin
12cb0 67 0a 2a 2a 20 69 73 20 67 6c 6f 62 61 6c 6c 79  g.** is globally
12cc0 20 64 69 73 61 62 6c 65 64 2e 20 49 66 20 55 52   disabled. If UR
12cd0 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c  I handling is gl
12ce0 6f 62 61 6c 6c 79 20 65 6e 61 62 6c 65 64 2c 20  obally enabled, 
12cf0 61 6c 6c 20 66 69 6c 65 6e 61 6d 65 73 0a 2a 2a  all filenames.**
12d00 20 70 61 73 73 65 64 20 74 6f 20 5b 73 71 6c 69   passed to [sqli
12d10 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71  te3_open()], [sq
12d20 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
12d30 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  , [sqlite3_open1
12d40 36 28 29 5d 20 6f 72 0a 2a 2a 20 73 70 65 63 69  6()] or.** speci
12d50 66 69 65 64 20 61 73 20 70 61 72 74 20 6f 66 20  fied as part of 
12d60 5b 41 54 54 41 43 48 5d 20 63 6f 6d 6d 61 6e 64  [ATTACH] command
12d70 73 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65  s are interprete
12d80 64 20 61 73 20 55 52 49 73 2c 20 72 65 67 61 72  d as URIs, regar
12d90 64 6c 65 73 73 0a 2a 2a 20 6f 66 20 77 68 65 74  dless.** of whet
12da0 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 5b  her or not the [
12db0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d  SQLITE_OPEN_URI]
12dc0 20 66 6c 61 67 20 69 73 20 73 65 74 20 77 68 65   flag is set whe
12dd0 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  n the database.*
12de0 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  * connection is 
12df0 6f 70 65 6e 65 64 2e 20 49 66 20 69 74 20 69 73  opened. If it is
12e00 20 67 6c 6f 62 61 6c 6c 79 20 64 69 73 61 62 6c   globally disabl
12e10 65 64 2c 20 66 69 6c 65 6e 61 6d 65 73 20 61 72  ed, filenames ar
12e20 65 0a 2a 2a 20 6f 6e 6c 79 20 69 6e 74 65 72 70  e.** only interp
12e30 72 65 74 65 64 20 61 73 20 55 52 49 73 20 69 66  reted as URIs if
12e40 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e   the SQLITE_OPEN
12e50 5f 55 52 49 20 66 6c 61 67 20 69 73 20 73 65 74  _URI flag is set
12e60 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20 64 61 74   when the.** dat
12e70 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
12e80 20 69 73 20 6f 70 65 6e 65 64 2e 20 42 79 20 64   is opened. By d
12e90 65 66 61 75 6c 74 2c 20 55 52 49 20 68 61 6e 64  efault, URI hand
12ea0 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79  ling is globally
12eb0 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e 20 54 68  .** disabled. Th
12ec0 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20  e default value 
12ed0 6d 61 79 20 62 65 20 63 68 61 6e 67 65 64 20 62  may be changed b
12ee0 79 20 63 6f 6d 70 69 6c 69 6e 67 20 77 69 74 68  y compiling with
12ef0 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
12f00 55 53 45 5f 55 52 49 5d 20 73 79 6d 62 6f 6c 20  USE_URI] symbol 
12f10 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b  defined..**.** [
12f20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  [SQLITE_CONFIG_P
12f30 43 41 43 48 45 5d 5d 20 5b 5b 53 51 4c 49 54 45  CACHE]] [[SQLITE
12f40 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48  _CONFIG_GETPCACH
12f50 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  E]].** <dt>SQLIT
12f60 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 20  E_CONFIG_PCACHE 
12f70 61 6e 64 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  and SQLITE_CONFI
12f80 47 5f 47 45 54 50 43 41 43 48 45 0a 2a 2a 20 3c  G_GETPCACHE.** <
12f90 64 64 3e 20 54 68 65 73 65 20 6f 70 74 69 6f 6e  dd> These option
12fa0 73 20 61 72 65 20 6f 62 73 6f 6c 65 74 65 20 61  s are obsolete a
12fb0 6e 64 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65  nd should not be
12fc0 20 75 73 65 64 20 62 79 20 6e 65 77 20 63 6f 64   used by new cod
12fd0 65 2e 0a 2a 2a 20 54 68 65 79 20 61 72 65 20 72  e..** They are r
12fe0 65 74 61 69 6e 65 64 20 66 6f 72 20 62 61 63 6b  etained for back
12ff0 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c  wards compatibil
13000 69 74 79 20 62 75 74 20 61 72 65 20 6e 6f 77 20  ity but are now 
13010 6e 6f 2d 6f 70 73 2e 0a 2a 2a 20 3c 2f 64 6c 3e  no-ops..** </dl>
13020 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
13030 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
13040 54 48 52 45 41 44 20 20 31 20 20 2f 2a 20 6e 69  THREAD  1  /* ni
13050 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  l */.#define SQL
13060 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49  ITE_CONFIG_MULTI
13070 54 48 52 45 41 44 20 20 20 32 20 20 2f 2a 20 6e  THREAD   2  /* n
13080 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  il */.#define SQ
13090 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49  LITE_CONFIG_SERI
130a0 41 4c 49 5a 45 44 20 20 20 20 33 20 20 2f 2a 20  ALIZED    3  /* 
130b0 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nil */.#define S
130c0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c  QLITE_CONFIG_MAL
130d0 4c 4f 43 20 20 20 20 20 20 20 20 34 20 20 2f 2a  LOC        4  /*
130e0 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74   sqlite3_mem_met
130f0 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  hods* */.#define
13100 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47   SQLITE_CONFIG_G
13110 45 54 4d 41 4c 4c 4f 43 20 20 20 20 20 35 20 20  ETMALLOC     5  
13120 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  /* sqlite3_mem_m
13130 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69  ethods* */.#defi
13140 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
13150 5f 53 43 52 41 54 43 48 20 20 20 20 20 20 20 36  _SCRATCH       6
13160 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20    /* void*, int 
13170 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65  sz, int N */.#de
13180 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
13190 49 47 5f 50 41 47 45 43 41 43 48 45 20 20 20 20  IG_PAGECACHE    
131a0 20 37 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e   7  /* void*, in
131b0 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23  t sz, int N */.#
131c0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
131d0 4e 46 49 47 5f 48 45 41 50 20 20 20 20 20 20 20  NFIG_HEAP       
131e0 20 20 20 38 20 20 2f 2a 20 76 6f 69 64 2a 2c 20     8  /* void*, 
131f0 69 6e 74 20 6e 42 79 74 65 2c 20 69 6e 74 20 6d  int nByte, int m
13200 69 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  in */.#define SQ
13210 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53  LITE_CONFIG_MEMS
13220 54 41 54 55 53 20 20 20 20 20 39 20 20 2f 2a 20  TATUS     9  /* 
13230 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 23 64 65 66 69  boolean */.#defi
13240 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
13250 5f 4d 55 54 45 58 20 20 20 20 20 20 20 20 31 30  _MUTEX        10
13260 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74    /* sqlite3_mut
13270 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23  ex_methods* */.#
13280 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
13290 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20 20 20  NFIG_GETMUTEX   
132a0 20 20 31 31 20 20 2f 2a 20 73 71 6c 69 74 65 33    11  /* sqlite3
132b0 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20  _mutex_methods* 
132c0 2a 2f 0a 2f 2a 20 70 72 65 76 69 6f 75 73 6c 79  */./* previously
132d0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43   SQLITE_CONFIG_C
132e0 48 55 4e 4b 41 4c 4c 4f 43 20 31 32 20 77 68 69  HUNKALLOC 12 whi
132f0 63 68 20 69 73 20 6e 6f 77 20 75 6e 75 73 65 64  ch is now unused
13300 2e 20 2a 2f 20 0a 23 64 65 66 69 6e 65 20 53 51  . */ .#define SQ
13310 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  LITE_CONFIG_LOOK
13320 41 53 49 44 45 20 20 20 20 31 33 20 20 2f 2a 20  ASIDE    13  /* 
13330 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69  int int */.#defi
13340 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
13350 5f 50 43 41 43 48 45 20 20 20 20 20 20 20 31 34  _PCACHE       14
13360 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64    /* no-op */.#d
13370 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
13380 46 49 47 5f 47 45 54 50 43 41 43 48 45 20 20 20  FIG_GETPCACHE   
13390 20 31 35 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f   15  /* no-op */
133a0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
133b0 43 4f 4e 46 49 47 5f 4c 4f 47 20 20 20 20 20 20  CONFIG_LOG      
133c0 20 20 20 20 31 36 20 20 2f 2a 20 78 46 75 6e 63      16  /* xFunc
133d0 2c 20 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69  , void* */.#defi
133e0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
133f0 5f 55 52 49 20 20 20 20 20 20 20 20 20 20 31 37  _URI          17
13400 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66    /* int */.#def
13410 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
13420 47 5f 50 43 41 43 48 45 32 20 20 20 20 20 20 31  G_PCACHE2      1
13430 38 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63  8  /* sqlite3_pc
13440 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a  ache_methods2* *
13450 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
13460 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48  _CONFIG_GETPCACH
13470 45 32 20 20 20 31 39 20 20 2f 2a 20 73 71 6c 69  E2   19  /* sqli
13480 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f  te3_pcache_metho
13490 64 73 32 2a 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  ds2* */../*.** C
134a0 41 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73  API3REF: Databas
134b0 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 43 6f 6e  e Connection Con
134c0 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f  figuration Optio
134d0 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63  ns.**.** These c
134e0 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68 65  onstants are the
134f0 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67   available integ
13500 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  er configuration
13510 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a   options that.**
13520 20 63 61 6e 20 62 65 20 70 61 73 73 65 64 20 61   can be passed a
13530 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  s the second arg
13540 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71  ument to the [sq
13550 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
13560 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  )] interface..**
13570 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75 72  .** New configur
13580 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61  ation options ma
13590 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75  y be added in fu
135a0 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66  ture releases of
135b0 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73   SQLite..** Exis
135c0 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69  ting configurati
135d0 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74  on options might
135e0 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65 64   be discontinued
135f0 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a  .  Applications.
13600 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b 20  ** should check 
13610 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20  the return code 
13620 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 64 62  from [sqlite3_db
13630 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61  _config()] to ma
13640 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20  ke sure that.** 
13650 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e  the call worked.
13660 20 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f    ^The [sqlite3_
13670 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74  db_config()] int
13680 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74 75  erface will retu
13690 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f  rn a.** non-zero
136a0 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66   [error code] if
136b0 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 20   a discontinued 
136c0 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20 63  or unsupported c
136d0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
136e0 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65  ion.** is invoke
136f0 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a  d..**.** <dl>.**
13700 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f   <dt>SQLITE_DBCO
13710 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f  NFIG_LOOKASIDE</
13720 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69  dt>.** <dd> ^Thi
13730 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74  s option takes t
13740 68 72 65 65 20 61 64 64 69 74 69 6f 6e 61 6c 20  hree additional 
13750 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64  arguments that d
13760 65 74 65 72 6d 69 6e 65 20 74 68 65 20 0a 2a 2a  etermine the .**
13770 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f   [lookaside memo
13780 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 20 63 6f  ry allocator] co
13790 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f 72 20  nfiguration for 
137a0 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
137b0 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 5e 54  nnection]..** ^T
137c0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
137d0 74 20 28 74 68 65 20 74 68 69 72 64 20 70 61 72  t (the third par
137e0 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74  ameter to [sqlit
137f0 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20  e3_db_config()] 
13800 69 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  is a.** pointer 
13810 74 6f 20 61 20 6d 65 6d 6f 72 79 20 62 75 66 66  to a memory buff
13820 65 72 20 74 6f 20 75 73 65 20 66 6f 72 20 6c 6f  er to use for lo
13830 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 2e 0a  okaside memory..
13840 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72  ** ^The first ar
13850 67 75 6d 65 6e 74 20 61 66 74 65 72 20 74 68 65  gument after the
13860 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47   SQLITE_DBCONFIG
13870 5f 4c 4f 4f 4b 41 53 49 44 45 20 76 65 72 62 0a  _LOOKASIDE verb.
13880 2a 2a 20 6d 61 79 20 62 65 20 4e 55 4c 4c 20 69  ** may be NULL i
13890 6e 20 77 68 69 63 68 20 63 61 73 65 20 53 51 4c  n which case SQL
138a0 69 74 65 20 77 69 6c 6c 20 61 6c 6c 6f 63 61 74  ite will allocat
138b0 65 20 74 68 65 0a 2a 2a 20 6c 6f 6f 6b 61 73 69  e the.** lookasi
138c0 64 65 20 62 75 66 66 65 72 20 69 74 73 65 6c 66  de buffer itself
138d0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
138e0 6d 61 6c 6c 6f 63 28 29 5d 2e 20 5e 54 68 65 20  malloc()]. ^The 
138f0 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
13900 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f  is the.** size o
13910 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65  f each lookaside
13920 20 62 75 66 66 65 72 20 73 6c 6f 74 2e 20 20 5e   buffer slot.  ^
13930 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  The third argume
13940 6e 74 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72  nt is the number
13950 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 2e 20 20 54   of.** slots.  T
13960 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62  he size of the b
13970 75 66 66 65 72 20 69 6e 20 74 68 65 20 66 69 72  uffer in the fir
13980 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74  st argument must
13990 20 62 65 20 67 72 65 61 74 65 72 20 74 68 61 6e   be greater than
139a0 0a 2a 2a 20 6f 72 20 65 71 75 61 6c 20 74 6f 20  .** or equal to 
139b0 74 68 65 20 70 72 6f 64 75 63 74 20 6f 66 20 74  the product of t
139c0 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68  he second and th
139d0 69 72 64 20 61 72 67 75 6d 65 6e 74 73 2e 20 20  ird arguments.  
139e0 54 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 6d 75  The buffer.** mu
139f0 73 74 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f  st be aligned to
13a00 20 61 6e 20 38 2d 62 79 74 65 20 62 6f 75 6e 64   an 8-byte bound
13a10 61 72 79 2e 20 20 5e 49 66 20 74 68 65 20 73 65  ary.  ^If the se
13a20 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
13a30 0a 2a 2a 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  .** SQLITE_DBCON
13a40 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 69 73  FIG_LOOKASIDE is
13a50 20 6e 6f 74 20 61 20 6d 75 6c 74 69 70 6c 65 20   not a multiple 
13a60 6f 66 20 38 2c 20 69 74 20 69 73 20 69 6e 74 65  of 8, it is inte
13a70 72 6e 61 6c 6c 79 0a 2a 2a 20 72 6f 75 6e 64 65  rnally.** rounde
13a80 64 20 64 6f 77 6e 20 74 6f 20 74 68 65 20 6e 65  d down to the ne
13a90 78 74 20 73 6d 61 6c 6c 65 72 20 6d 75 6c 74 69  xt smaller multi
13aa0 70 6c 65 20 6f 66 20 38 2e 20 20 5e 28 54 68 65  ple of 8.  ^(The
13ab0 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72   lookaside memor
13ac0 79 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69  y.** configurati
13ad0 6f 6e 20 66 6f 72 20 61 20 64 61 74 61 62 61 73  on for a databas
13ae0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 61 6e  e connection can
13af0 20 6f 6e 6c 79 20 62 65 20 63 68 61 6e 67 65 64   only be changed
13b00 20 77 68 65 6e 20 74 68 61 74 0a 2a 2a 20 63 6f   when that.** co
13b10 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6e 6f 74 20  nnection is not 
13b20 63 75 72 72 65 6e 74 6c 79 20 75 73 69 6e 67 20  currently using 
13b30 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79  lookaside memory
13b40 2c 20 6f 72 20 69 6e 20 6f 74 68 65 72 20 77 6f  , or in other wo
13b50 72 64 73 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20  rds.** when the 
13b60 22 63 75 72 72 65 6e 74 20 76 61 6c 75 65 22 20  "current value" 
13b70 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b  returned by.** [
13b80 73 71 6c 69 74 65 33 5f 64 62 5f 73 74 61 74 75  sqlite3_db_statu
13b90 73 5d 28 44 2c 5b 53 51 4c 49 54 45 5f 43 4f 4e  s](D,[SQLITE_CON
13ba0 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 2c 2e  FIG_LOOKASIDE],.
13bb0 2e 2e 29 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a 20  ..) is zero..** 
13bc0 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 63  Any attempt to c
13bd0 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73  hange the lookas
13be0 69 64 65 20 6d 65 6d 6f 72 79 20 63 6f 6e 66 69  ide memory confi
13bf0 67 75 72 61 74 69 6f 6e 20 77 68 65 6e 20 6c 6f  guration when lo
13c00 6f 6b 61 73 69 64 65 0a 2a 2a 20 6d 65 6d 6f 72  okaside.** memor
13c10 79 20 69 73 20 69 6e 20 75 73 65 20 6c 65 61 76  y is in use leav
13c20 65 73 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61  es the configura
13c30 74 69 6f 6e 20 75 6e 63 68 61 6e 67 65 64 20 61  tion unchanged a
13c40 6e 64 20 72 65 74 75 72 6e 73 20 0a 2a 2a 20 5b  nd returns .** [
13c50 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 29 5e 3c  SQLITE_BUSY].)^<
13c60 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
13c70 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45  QLITE_DBCONFIG_E
13c80 4e 41 42 4c 45 5f 46 4b 45 59 3c 2f 64 74 3e 0a  NABLE_FKEY</dt>.
13c90 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70  ** <dd> ^This op
13ca0 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20  tion is used to 
13cb0 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c  enable or disabl
13cc0 65 20 74 68 65 20 65 6e 66 6f 72 63 65 6d 65 6e  e the enforcemen
13cd0 74 20 6f 66 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e  t of.** [foreign
13ce0 20 6b 65 79 20 63 6f 6e 73 74 72 61 69 6e 74 73   key constraints
13cf0 5d 2e 20 20 54 68 65 72 65 20 73 68 6f 75 6c 64  ].  There should
13d00 20 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e   be two addition
13d10 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a  al arguments..**
13d20 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
13d30 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ent is an intege
13d40 72 20 77 68 69 63 68 20 69 73 20 30 20 74 6f 20  r which is 0 to 
13d50 64 69 73 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72  disable FK enfor
13d60 63 65 6d 65 6e 74 2c 0a 2a 2a 20 70 6f 73 69 74  cement,.** posit
13d70 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 46 4b  ive to enable FK
13d80 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 72 20   enforcement or 
13d90 6e 65 67 61 74 69 76 65 20 74 6f 20 6c 65 61 76  negative to leav
13da0 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74  e FK enforcement
13db0 0a 2a 2a 20 75 6e 63 68 61 6e 67 65 64 2e 20 20  .** unchanged.  
13dc0 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
13dd0 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65  eter is a pointe
13de0 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20  r to an integer 
13df0 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73  into which.** is
13e00 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20   written 0 or 1 
13e10 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65 74  to indicate whet
13e20 68 65 72 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65  her FK enforceme
13e30 6e 74 20 69 73 20 6f 66 66 20 6f 72 20 6f 6e 0a  nt is off or on.
13e40 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69  ** following thi
13e50 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 63  s call.  The sec
13e60 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d 61  ond parameter ma
13e70 79 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  y be a NULL poin
13e80 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68  ter, in.** which
13e90 20 63 61 73 65 20 74 68 65 20 46 4b 20 65 6e 66   case the FK enf
13ea0 6f 72 63 65 6d 65 6e 74 20 73 65 74 74 69 6e 67  orcement setting
13eb0 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 64   is not reported
13ec0 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a   back. </dd>.**.
13ed0 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42  ** <dt>SQLITE_DB
13ee0 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52  CONFIG_ENABLE_TR
13ef0 49 47 47 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  IGGER</dt>.** <d
13f00 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  d> ^This option 
13f10 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c  is used to enabl
13f20 65 20 6f 72 20 64 69 73 61 62 6c 65 20 5b 43 52  e or disable [CR
13f30 45 41 54 45 20 54 52 49 47 47 45 52 20 7c 20 74  EATE TRIGGER | t
13f40 72 69 67 67 65 72 73 5d 2e 0a 2a 2a 20 54 68 65  riggers]..** The
13f50 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f  re should be two
13f60 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75   additional argu
13f70 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69  ments..** The fi
13f80 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20  rst argument is 
13f90 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68  an integer which
13fa0 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65   is 0 to disable
13fb0 20 74 72 69 67 67 65 72 73 2c 0a 2a 2a 20 70 6f   triggers,.** po
13fc0 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65  sitive to enable
13fd0 20 74 72 69 67 67 65 72 73 20 6f 72 20 6e 65 67   triggers or neg
13fe0 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20 74  ative to leave t
13ff0 68 65 20 73 65 74 74 69 6e 67 20 75 6e 63 68 61  he setting uncha
14000 6e 67 65 64 2e 0a 2a 2a 20 54 68 65 20 73 65 63  nged..** The sec
14010 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
14020 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
14030 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68   integer into wh
14040 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65  ich.** is writte
14050 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69  n 0 or 1 to indi
14060 63 61 74 65 20 77 68 65 74 68 65 72 20 74 72 69  cate whether tri
14070 67 67 65 72 73 20 61 72 65 20 64 69 73 61 62 6c  ggers are disabl
14080 65 64 20 6f 72 20 65 6e 61 62 6c 65 64 0a 2a 2a  ed or enabled.**
14090 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20   following this 
140a0 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e  call.  The secon
140b0 64 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20  d parameter may 
140c0 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  be a NULL pointe
140d0 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63  r, in.** which c
140e0 61 73 65 20 74 68 65 20 74 72 69 67 67 65 72 20  ase the trigger 
140f0 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72  setting is not r
14100 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f  eported back. </
14110 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a  dd>.**.** </dl>.
14120 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
14130 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  E_DBCONFIG_LOOKA
14140 53 49 44 45 20 20 20 20 20 20 20 31 30 30 31 20  SIDE       1001 
14150 20 2f 2a 20 76 6f 69 64 2a 20 69 6e 74 20 69 6e   /* void* int in
14160 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  t */.#define SQL
14170 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41  ITE_DBCONFIG_ENA
14180 42 4c 45 5f 46 4b 45 59 20 20 20 20 20 31 30 30  BLE_FKEY     100
14190 32 20 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a  2  /* int int* *
141a0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
141b0 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45  _DBCONFIG_ENABLE
141c0 5f 54 52 49 47 47 45 52 20 20 31 30 30 33 20 20  _TRIGGER  1003  
141d0 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 0a  /* int int* */..
141e0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
141f0 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62   Enable Or Disab
14200 6c 65 20 45 78 74 65 6e 64 65 64 20 52 65 73 75  le Extended Resu
14210 6c 74 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 5e  lt Codes.**.** ^
14220 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65  The sqlite3_exte
14230 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65  nded_result_code
14240 73 28 29 20 72 6f 75 74 69 6e 65 20 65 6e 61 62  s() routine enab
14250 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20  les or disables 
14260 74 68 65 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64  the.** [extended
14270 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 66   result codes] f
14280 65 61 74 75 72 65 20 6f 66 20 53 51 4c 69 74 65  eature of SQLite
14290 2e 20 5e 54 68 65 20 65 78 74 65 6e 64 65 64 20  . ^The extended 
142a0 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 64 65 73 20  result.** codes 
142b0 61 72 65 20 64 69 73 61 62 6c 65 64 20 62 79 20  are disabled by 
142c0 64 65 66 61 75 6c 74 20 66 6f 72 20 68 69 73 74  default for hist
142d0 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74 69 62 69  orical compatibi
142e0 6c 69 74 79 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  lity..*/.int sql
142f0 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65  ite3_extended_re
14300 73 75 6c 74 5f 63 6f 64 65 73 28 73 71 6c 69 74  sult_codes(sqlit
14310 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b  e3*, int onoff);
14320 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
14330 3a 20 4c 61 73 74 20 49 6e 73 65 72 74 20 52 6f  : Last Insert Ro
14340 77 69 64 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20  wid.**.** ^Each 
14350 65 6e 74 72 79 20 69 6e 20 61 6e 20 53 51 4c 69  entry in an SQLi
14360 74 65 20 74 61 62 6c 65 20 68 61 73 20 61 20 75  te table has a u
14370 6e 69 71 75 65 20 36 34 2d 62 69 74 20 73 69 67  nique 64-bit sig
14380 6e 65 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6b  ned.** integer k
14390 65 79 20 63 61 6c 6c 65 64 20 74 68 65 20 5b 52  ey called the [R
143a0 4f 57 49 44 20 7c 20 22 72 6f 77 69 64 22 5d 2e  OWID | "rowid"].
143b0 20 5e 54 68 65 20 72 6f 77 69 64 20 69 73 20 61   ^The rowid is a
143c0 6c 77 61 79 73 20 61 76 61 69 6c 61 62 6c 65 0a  lways available.
143d0 2a 2a 20 61 73 20 61 6e 20 75 6e 64 65 63 6c 61  ** as an undecla
143e0 72 65 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64  red column named
143f0 20 52 4f 57 49 44 2c 20 4f 49 44 2c 20 6f 72 20   ROWID, OID, or 
14400 5f 52 4f 57 49 44 5f 20 61 73 20 6c 6f 6e 67 20  _ROWID_ as long 
14410 61 73 20 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65  as those.** name
14420 73 20 61 72 65 20 6e 6f 74 20 61 6c 73 6f 20 75  s are not also u
14430 73 65 64 20 62 79 20 65 78 70 6c 69 63 69 74 6c  sed by explicitl
14440 79 20 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d  y declared colum
14450 6e 73 2e 20 5e 49 66 0a 2a 2a 20 74 68 65 20 74  ns. ^If.** the t
14460 61 62 6c 65 20 68 61 73 20 61 20 63 6f 6c 75 6d  able has a colum
14470 6e 20 6f 66 20 74 79 70 65 20 5b 49 4e 54 45 47  n of type [INTEG
14480 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59 5d 20  ER PRIMARY KEY] 
14490 74 68 65 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e  then that column
144a0 0a 2a 2a 20 69 73 20 61 6e 6f 74 68 65 72 20 61  .** is another a
144b0 6c 69 61 73 20 66 6f 72 20 74 68 65 20 72 6f 77  lias for the row
144c0 69 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  id..**.** ^This 
144d0 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
144e0 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74  the [rowid] of t
144f0 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 0a 2a  he most recent.*
14500 2a 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e  * successful [IN
14510 53 45 52 54 5d 20 69 6e 74 6f 20 74 68 65 20 64  SERT] into the d
14520 61 74 61 62 61 73 65 20 66 72 6f 6d 20 74 68 65  atabase from the
14530 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
14540 63 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65  ction].** in the
14550 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e   first argument.
14560 20 20 5e 41 73 20 6f 66 20 53 51 4c 69 74 65 20    ^As of SQLite 
14570 76 65 72 73 69 6f 6e 20 33 2e 37 2e 37 2c 20 74  version 3.7.7, t
14580 68 69 73 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20  his routines.** 
14590 72 65 63 6f 72 64 73 20 74 68 65 20 6c 61 73 74  records the last
145a0 20 69 6e 73 65 72 74 20 72 6f 77 69 64 20 6f 66   insert rowid of
145b0 20 62 6f 74 68 20 6f 72 64 69 6e 61 72 79 20 74   both ordinary t
145c0 61 62 6c 65 73 20 61 6e 64 20 5b 76 69 72 74 75  ables and [virtu
145d0 61 6c 20 74 61 62 6c 65 73 5d 2e 0a 2a 2a 20 5e  al tables]..** ^
145e0 49 66 20 6e 6f 20 73 75 63 63 65 73 73 66 75 6c  If no successful
145f0 20 5b 49 4e 53 45 52 54 5d 73 0a 2a 2a 20 68 61   [INSERT]s.** ha
14600 76 65 20 65 76 65 72 20 6f 63 63 75 72 72 65 64  ve ever occurred
14610 20 6f 6e 20 74 68 61 74 20 64 61 74 61 62 61 73   on that databas
14620 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 7a 65  e connection, ze
14630 72 6f 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  ro is returned..
14640 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 6e 20 5b 49  **.** ^(If an [I
14650 4e 53 45 52 54 5d 20 6f 63 63 75 72 73 20 77 69  NSERT] occurs wi
14660 74 68 69 6e 20 61 20 74 72 69 67 67 65 72 20 6f  thin a trigger o
14670 72 20 77 69 74 68 69 6e 20 61 20 5b 76 69 72 74  r within a [virt
14680 75 61 6c 20 74 61 62 6c 65 5d 0a 2a 2a 20 6d 65  ual table].** me
14690 74 68 6f 64 2c 20 74 68 65 6e 20 74 68 69 73 20  thod, then this 
146a0 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20 72 65 74  routine will ret
146b0 75 72 6e 20 74 68 65 20 5b 72 6f 77 69 64 5d 20  urn the [rowid] 
146c0 6f 66 20 74 68 65 20 69 6e 73 65 72 74 65 64 0a  of the inserted.
146d0 2a 2a 20 72 6f 77 20 61 73 20 6c 6f 6e 67 20 61  ** row as long a
146e0 73 20 74 68 65 20 74 72 69 67 67 65 72 20 6f 72  s the trigger or
146f0 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d   virtual table m
14700 65 74 68 6f 64 20 69 73 20 72 75 6e 6e 69 6e 67  ethod is running
14710 2e 0a 2a 2a 20 42 75 74 20 6f 6e 63 65 20 74 68  ..** But once th
14720 65 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 72  e trigger or vir
14730 74 75 61 6c 20 74 61 62 6c 65 20 6d 65 74 68 6f  tual table metho
14740 64 20 65 6e 64 73 2c 20 74 68 65 20 76 61 6c 75  d ends, the valu
14750 65 20 72 65 74 75 72 6e 65 64 20 0a 2a 2a 20 62  e returned .** b
14760 79 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72  y this routine r
14770 65 76 65 72 74 73 20 74 6f 20 77 68 61 74 20 69  everts to what i
14780 74 20 77 61 73 20 62 65 66 6f 72 65 20 74 68 65  t was before the
14790 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 72 74   trigger or virt
147a0 75 61 6c 0a 2a 2a 20 74 61 62 6c 65 20 6d 65 74  ual.** table met
147b0 68 6f 64 20 62 65 67 61 6e 2e 29 5e 0a 2a 2a 0a  hod began.)^.**.
147c0 2a 2a 20 5e 41 6e 20 5b 49 4e 53 45 52 54 5d 20  ** ^An [INSERT] 
147d0 74 68 61 74 20 66 61 69 6c 73 20 64 75 65 20 74  that fails due t
147e0 6f 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76  o a constraint v
147f0 69 6f 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20  iolation is not 
14800 61 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 20  a.** successful 
14810 5b 49 4e 53 45 52 54 5d 20 61 6e 64 20 64 6f 65  [INSERT] and doe
14820 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65  s not change the
14830 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
14840 62 79 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69  by this.** routi
14850 6e 65 2e 20 20 5e 54 68 75 73 20 49 4e 53 45 52  ne.  ^Thus INSER
14860 54 20 4f 52 20 46 41 49 4c 2c 20 49 4e 53 45 52  T OR FAIL, INSER
14870 54 20 4f 52 20 49 47 4e 4f 52 45 2c 20 49 4e 53  T OR IGNORE, INS
14880 45 52 54 20 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c  ERT OR ROLLBACK,
14890 0a 2a 2a 20 61 6e 64 20 49 4e 53 45 52 54 20 4f  .** and INSERT O
148a0 52 20 41 42 4f 52 54 20 6d 61 6b 65 20 6e 6f 20  R ABORT make no 
148b0 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20 72  changes to the r
148c0 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74  eturn value of t
148d0 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 77  his.** routine w
148e0 68 65 6e 20 74 68 65 69 72 20 69 6e 73 65 72 74  hen their insert
148f0 69 6f 6e 20 66 61 69 6c 73 2e 20 20 5e 28 57 68  ion fails.  ^(Wh
14900 65 6e 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50  en INSERT OR REP
14910 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65  LACE.** encounte
14920 72 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20  rs a constraint 
14930 76 69 6f 6c 61 74 69 6f 6e 2c 20 69 74 20 64 6f  violation, it do
14940 65 73 20 6e 6f 74 20 66 61 69 6c 2e 20 20 54 68  es not fail.  Th
14950 65 0a 2a 2a 20 49 4e 53 45 52 54 20 63 6f 6e 74  e.** INSERT cont
14960 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74  inues to complet
14970 69 6f 6e 20 61 66 74 65 72 20 64 65 6c 65 74 69  ion after deleti
14980 6e 67 20 72 6f 77 73 20 74 68 61 74 20 63 61 75  ng rows that cau
14990 73 65 64 0a 2a 2a 20 74 68 65 20 63 6f 6e 73 74  sed.** the const
149a0 72 61 69 6e 74 20 70 72 6f 62 6c 65 6d 20 73 6f  raint problem so
149b0 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41   INSERT OR REPLA
149c0 43 45 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 63  CE will always c
149d0 68 61 6e 67 65 0a 2a 2a 20 74 68 65 20 72 65 74  hange.** the ret
149e0 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69  urn value of thi
149f0 73 20 69 6e 74 65 72 66 61 63 65 2e 29 5e 0a 2a  s interface.)^.*
14a00 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20 70 75  *.** ^For the pu
14a10 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20 72  rposes of this r
14a20 6f 75 74 69 6e 65 2c 20 61 6e 20 5b 49 4e 53 45  outine, an [INSE
14a30 52 54 5d 20 69 73 20 63 6f 6e 73 69 64 65 72 65  RT] is considere
14a40 64 20 74 6f 0a 2a 2a 20 62 65 20 73 75 63 63 65  d to.** be succe
14a50 73 73 66 75 6c 20 65 76 65 6e 20 69 66 20 69 74  ssful even if it
14a60 20 69 73 20 73 75 62 73 65 71 75 65 6e 74 6c 79   is subsequently
14a70 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a   rolled back..**
14a80 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f  .** This functio
14a90 6e 20 69 73 20 61 63 63 65 73 73 69 62 6c 65 20  n is accessible 
14aa0 74 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  to SQL statement
14ab0 73 20 76 69 61 20 74 68 65 0a 2a 2a 20 5b 6c 61  s via the.** [la
14ac0 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
14ad0 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e  ) SQL function].
14ae0 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61  .**.** If a sepa
14af0 72 61 74 65 20 74 68 72 65 61 64 20 70 65 72 66  rate thread perf
14b00 6f 72 6d 73 20 61 20 6e 65 77 20 5b 49 4e 53 45  orms a new [INSE
14b10 52 54 5d 20 6f 6e 20 74 68 65 20 73 61 6d 65 0a  RT] on the same.
14b20 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ** database conn
14b30 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 65  ection while the
14b40 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69   [sqlite3_last_i
14b50 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 0a 2a  nsert_rowid()].*
14b60 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75  * function is ru
14b70 6e 6e 69 6e 67 20 61 6e 64 20 74 68 75 73 20 63  nning and thus c
14b80 68 61 6e 67 65 73 20 74 68 65 20 6c 61 73 74 20  hanges the last 
14b90 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2c 0a  insert [rowid],.
14ba0 2a 2a 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75  ** then the valu
14bb0 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73  e returned by [s
14bc0 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65  qlite3_last_inse
14bd0 72 74 5f 72 6f 77 69 64 28 29 5d 20 69 73 0a 2a  rt_rowid()] is.*
14be0 2a 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20  * unpredictable 
14bf0 61 6e 64 20 6d 69 67 68 74 20 6e 6f 74 20 65 71  and might not eq
14c00 75 61 6c 20 65 69 74 68 65 72 20 74 68 65 20 6f  ual either the o
14c10 6c 64 20 6f 72 20 74 68 65 20 6e 65 77 0a 2a 2a  ld or the new.**
14c20 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f   last insert [ro
14c30 77 69 64 5d 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33  wid]..*/.sqlite3
14c40 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6c  _int64 sqlite3_l
14c50 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
14c60 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
14c70 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 75  ** CAPI3REF: Cou
14c80 6e 74 20 54 68 65 20 4e 75 6d 62 65 72 20 4f 66  nt The Number Of
14c90 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a   Rows Modified.*
14ca0 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74  *.** ^This funct
14cb0 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20  ion returns the 
14cc0 6e 75 6d 62 65 72 20 6f 66 20 64 61 74 61 62 61  number of databa
14cd0 73 65 20 72 6f 77 73 20 74 68 61 74 20 77 65 72  se rows that wer
14ce0 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20 6f 72 20  e changed.** or 
14cf0 69 6e 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65  inserted or dele
14d00 74 65 64 20 62 79 20 74 68 65 20 6d 6f 73 74 20  ted by the most 
14d10 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74  recently complet
14d20 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ed SQL statement
14d30 0a 2a 2a 20 6f 6e 20 74 68 65 20 5b 64 61 74 61  .** on the [data
14d40 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
14d50 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68   specified by th
14d60 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
14d70 72 2e 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 63 68 61  r..** ^(Only cha
14d80 6e 67 65 73 20 74 68 61 74 20 61 72 65 20 64 69  nges that are di
14d90 72 65 63 74 6c 79 20 73 70 65 63 69 66 69 65 64  rectly specified
14da0 20 62 79 20 74 68 65 20 5b 49 4e 53 45 52 54 5d   by the [INSERT]
14db0 2c 20 5b 55 50 44 41 54 45 5d 2c 0a 2a 2a 20 6f  , [UPDATE],.** o
14dc0 72 20 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 65  r [DELETE] state
14dd0 6d 65 6e 74 20 61 72 65 20 63 6f 75 6e 74 65 64  ment are counted
14de0 2e 20 20 41 75 78 69 6c 69 61 72 79 20 63 68 61  .  Auxiliary cha
14df0 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 0a 2a  nges caused by.*
14e00 2a 20 74 72 69 67 67 65 72 73 20 6f 72 20 5b 66  * triggers or [f
14e10 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f  oreign key actio
14e20 6e 73 5d 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e  ns] are not coun
14e30 74 65 64 2e 29 5e 20 55 73 65 20 74 68 65 0a 2a  ted.)^ Use the.*
14e40 2a 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c  * [sqlite3_total
14e50 5f 63 68 61 6e 67 65 73 28 29 5d 20 66 75 6e 63  _changes()] func
14e60 74 69 6f 6e 20 74 6f 20 66 69 6e 64 20 74 68 65  tion to find the
14e70 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66   total number of
14e80 20 63 68 61 6e 67 65 73 0a 2a 2a 20 69 6e 63 6c   changes.** incl
14e90 75 64 69 6e 67 20 63 68 61 6e 67 65 73 20 63 61  uding changes ca
14ea0 75 73 65 64 20 62 79 20 74 72 69 67 67 65 72 73  used by triggers
14eb0 20 61 6e 64 20 66 6f 72 65 69 67 6e 20 6b 65 79   and foreign key
14ec0 20 61 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20   actions..**.** 
14ed0 5e 43 68 61 6e 67 65 73 20 74 6f 20 61 20 76 69  ^Changes to a vi
14ee0 65 77 20 74 68 61 74 20 61 72 65 20 73 69 6d 75  ew that are simu
14ef0 6c 61 74 65 64 20 62 79 20 61 6e 20 5b 49 4e 53  lated by an [INS
14f00 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 72 5d  TEAD OF trigger]
14f10 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e  .** are not coun
14f20 74 65 64 2e 20 20 4f 6e 6c 79 20 72 65 61 6c 20  ted.  Only real 
14f30 74 61 62 6c 65 20 63 68 61 6e 67 65 73 20 61 72  table changes ar
14f40 65 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a  e counted..**.**
14f50 20 5e 28 41 20 22 72 6f 77 20 63 68 61 6e 67 65   ^(A "row change
14f60 22 20 69 73 20 61 20 63 68 61 6e 67 65 20 74 6f  " is a change to
14f70 20 61 20 73 69 6e 67 6c 65 20 72 6f 77 20 6f 66   a single row of
14f80 20 61 20 73 69 6e 67 6c 65 20 74 61 62 6c 65 0a   a single table.
14f90 2a 2a 20 63 61 75 73 65 64 20 62 79 20 61 6e 20  ** caused by an 
14fa0 49 4e 53 45 52 54 2c 20 44 45 4c 45 54 45 2c 20  INSERT, DELETE, 
14fb0 6f 72 20 55 50 44 41 54 45 20 73 74 61 74 65 6d  or UPDATE statem
14fc0 65 6e 74 2e 20 20 52 6f 77 73 20 74 68 61 74 0a  ent.  Rows that.
14fd0 2a 2a 20 61 72 65 20 63 68 61 6e 67 65 64 20 61  ** are changed a
14fe0 73 20 73 69 64 65 20 65 66 66 65 63 74 73 20 6f  s side effects o
14ff0 66 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73  f [REPLACE] cons
15000 74 72 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f  traint resolutio
15010 6e 2c 0a 2a 2a 20 72 6f 6c 6c 62 61 63 6b 2c 20  n,.** rollback, 
15020 41 42 4f 52 54 20 70 72 6f 63 65 73 73 69 6e 67  ABORT processing
15030 2c 20 5b 44 52 4f 50 20 54 41 42 4c 45 5d 2c 20  , [DROP TABLE], 
15040 6f 72 20 62 79 20 61 6e 79 20 6f 74 68 65 72 0a  or by any other.
15050 2a 2a 20 6d 65 63 68 61 6e 69 73 6d 73 20 64 6f  ** mechanisms do
15060 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 64 69   not count as di
15070 72 65 63 74 20 72 6f 77 20 63 68 61 6e 67 65 73  rect row changes
15080 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 22 74 72 69  .)^.**.** A "tri
15090 67 67 65 72 20 63 6f 6e 74 65 78 74 22 20 69 73  gger context" is
150a0 20 61 20 73 63 6f 70 65 20 6f 66 20 65 78 65 63   a scope of exec
150b0 75 74 69 6f 6e 20 74 68 61 74 20 62 65 67 69 6e  ution that begin
150c0 73 20 61 6e 64 0a 2a 2a 20 65 6e 64 73 20 77 69  s and.** ends wi
150d0 74 68 20 74 68 65 20 73 63 72 69 70 74 20 6f 66  th the script of
150e0 20 61 20 5b 43 52 45 41 54 45 20 54 52 49 47 47   a [CREATE TRIGG
150f0 45 52 20 7c 20 74 72 69 67 67 65 72 5d 2e 20 0a  ER | trigger]. .
15100 2a 2a 20 4d 6f 73 74 20 53 51 4c 20 73 74 61 74  ** Most SQL stat
15110 65 6d 65 6e 74 73 20 61 72 65 0a 2a 2a 20 65 76  ements are.** ev
15120 61 6c 75 61 74 65 64 20 6f 75 74 73 69 64 65 20  aluated outside 
15130 6f 66 20 61 6e 79 20 74 72 69 67 67 65 72 2e 20  of any trigger. 
15140 20 54 68 69 73 20 69 73 20 74 68 65 20 22 74 6f   This is the "to
15150 70 20 6c 65 76 65 6c 22 0a 2a 2a 20 74 72 69 67  p level".** trig
15160 67 65 72 20 63 6f 6e 74 65 78 74 2e 20 20 49 66  ger context.  If
15170 20 61 20 74 72 69 67 67 65 72 20 66 69 72 65 73   a trigger fires
15180 20 66 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65   from the top le
15190 76 65 6c 2c 20 61 0a 2a 2a 20 6e 65 77 20 74 72  vel, a.** new tr
151a0 69 67 67 65 72 20 63 6f 6e 74 65 78 74 20 69 73  igger context is
151b0 20 65 6e 74 65 72 65 64 20 66 6f 72 20 74 68 65   entered for the
151c0 20 64 75 72 61 74 69 6f 6e 20 6f 66 20 74 68 61   duration of tha
151d0 74 20 6f 6e 65 0a 2a 2a 20 74 72 69 67 67 65 72  t one.** trigger
151e0 2e 20 20 53 75 62 74 72 69 67 67 65 72 73 20 63  .  Subtriggers c
151f0 72 65 61 74 65 20 73 75 62 63 6f 6e 74 65 78 74  reate subcontext
15200 73 20 66 6f 72 20 74 68 65 69 72 20 64 75 72 61  s for their dura
15210 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c  tion..**.** ^Cal
15220 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 78  ling [sqlite3_ex
15230 65 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  ec()] or [sqlite
15240 33 5f 73 74 65 70 28 29 5d 20 72 65 63 75 72 73  3_step()] recurs
15250 69 76 65 6c 79 20 64 6f 65 73 0a 2a 2a 20 6e 6f  ively does.** no
15260 74 20 63 72 65 61 74 65 20 61 20 6e 65 77 20 74  t create a new t
15270 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a  rigger context..
15280 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63  **.** ^This func
15290 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65  tion returns the
152a0 20 6e 75 6d 62 65 72 20 6f 66 20 64 69 72 65 63   number of direc
152b0 74 20 72 6f 77 20 63 68 61 6e 67 65 73 20 69 6e  t row changes in
152c0 20 74 68 65 0a 2a 2a 20 6d 6f 73 74 20 72 65 63   the.** most rec
152d0 65 6e 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41  ent INSERT, UPDA
152e0 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 20 73 74  TE, or DELETE st
152f0 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74  atement within t
15300 68 65 20 73 61 6d 65 0a 2a 2a 20 74 72 69 67 67  he same.** trigg
15310 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a  er context..**.*
15320 2a 20 5e 54 68 75 73 2c 20 77 68 65 6e 20 63 61  * ^Thus, when ca
15330 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 74 6f  lled from the to
15340 70 20 6c 65 76 65 6c 2c 20 74 68 69 73 20 66 75  p level, this fu
15350 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74  nction returns t
15360 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
15370 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 6d  changes in the m
15380 6f 73 74 20 72 65 63 65 6e 74 20 49 4e 53 45 52  ost recent INSER
15390 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45  T, UPDATE, or DE
153a0 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 61 6c 73  LETE.** that als
153b0 6f 20 6f 63 63 75 72 72 65 64 20 61 74 20 74 68  o occurred at th
153c0 65 20 74 6f 70 20 6c 65 76 65 6c 2e 20 20 5e 28  e top level.  ^(
153d0 57 69 74 68 69 6e 20 74 68 65 20 62 6f 64 79 20  Within the body 
153e0 6f 66 20 61 20 74 72 69 67 67 65 72 2c 0a 2a 2a  of a trigger,.**
153f0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61   the sqlite3_cha
15400 6e 67 65 73 28 29 20 69 6e 74 65 72 66 61 63 65  nges() interface
15410 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 74   can be called t
15420 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65  o find the numbe
15430 72 20 6f 66 0a 2a 2a 20 63 68 61 6e 67 65 73 20  r of.** changes 
15440 69 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  in the most rece
15450 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 49  ntly completed I
15460 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f  NSERT, UPDATE, o
15470 72 20 44 45 4c 45 54 45 0a 2a 2a 20 73 74 61 74  r DELETE.** stat
15480 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65  ement within the
15490 20 62 6f 64 79 20 6f 66 20 74 68 65 20 73 61 6d   body of the sam
154a0 65 20 74 72 69 67 67 65 72 2e 0a 2a 2a 20 48 6f  e trigger..** Ho
154b0 77 65 76 65 72 2c 20 74 68 65 20 6e 75 6d 62 65  wever, the numbe
154c0 72 20 72 65 74 75 72 6e 65 64 20 64 6f 65 73 20  r returned does 
154d0 6e 6f 74 20 69 6e 63 6c 75 64 65 20 63 68 61 6e  not include chan
154e0 67 65 73 0a 2a 2a 20 63 61 75 73 65 64 20 62 79  ges.** caused by
154f0 20 73 75 62 74 72 69 67 67 65 72 73 20 73 69 6e   subtriggers sin
15500 63 65 20 74 68 6f 73 65 20 68 61 76 65 20 74 68  ce those have th
15510 65 69 72 20 6f 77 6e 20 63 6f 6e 74 65 78 74 2e  eir own context.
15520 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  )^.**.** See als
15530 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74  o the [sqlite3_t
15540 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20  otal_changes()] 
15550 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a  interface, the.*
15560 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73  * [count_changes
15570 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68   pragma], and th
15580 65 20 5b 63 68 61 6e 67 65 73 28 29 20 53 51 4c  e [changes() SQL
15590 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a   function]..**.*
155a0 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20  * If a separate 
155b0 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61  thread makes cha
155c0 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65  nges on the same
155d0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
155e0 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73  tion.** while [s
155f0 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29  qlite3_changes()
15600 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65  ] is running the
15610 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  n the value retu
15620 72 6e 65 64 0a 2a 2a 20 69 73 20 75 6e 70 72 65  rned.** is unpre
15630 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74  dictable and not
15640 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a   meaningful..*/.
15650 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 68 61 6e  int sqlite3_chan
15660 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  ges(sqlite3*);..
15670 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
15680 54 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20  Total Number Of 
15690 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a  Rows Modified.**
156a0 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69  .** ^This functi
156b0 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  on returns the n
156c0 75 6d 62 65 72 20 6f 66 20 72 6f 77 20 63 68 61  umber of row cha
156d0 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 20 5b  nges caused by [
156e0 49 4e 53 45 52 54 5d 2c 0a 2a 2a 20 5b 55 50 44  INSERT],.** [UPD
156f0 41 54 45 5d 20 6f 72 20 5b 44 45 4c 45 54 45 5d  ATE] or [DELETE]
15700 20 73 74 61 74 65 6d 65 6e 74 73 20 73 69 6e 63   statements sinc
15710 65 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  e the [database 
15720 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 61 73 20  connection] was 
15730 6f 70 65 6e 65 64 2e 0a 2a 2a 20 5e 28 54 68 65  opened..** ^(The
15740 20 63 6f 75 6e 74 20 72 65 74 75 72 6e 65 64 20   count returned 
15750 62 79 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c  by sqlite3_total
15760 5f 63 68 61 6e 67 65 73 28 29 20 69 6e 63 6c 75  _changes() inclu
15770 64 65 73 20 61 6c 6c 20 63 68 61 6e 67 65 73 0a  des all changes.
15780 2a 2a 20 66 72 6f 6d 20 61 6c 6c 20 5b 43 52 45  ** from all [CRE
15790 41 54 45 20 54 52 49 47 47 45 52 20 7c 20 74 72  ATE TRIGGER | tr
157a0 69 67 67 65 72 5d 20 63 6f 6e 74 65 78 74 73 20  igger] contexts 
157b0 61 6e 64 20 63 68 61 6e 67 65 73 20 6d 61 64 65  and changes made
157c0 20 62 79 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20   by.** [foreign 
157d0 6b 65 79 20 61 63 74 69 6f 6e 73 5d 2e 20 48 6f  key actions]. Ho
157e0 77 65 76 65 72 2c 0a 2a 2a 20 74 68 65 20 63 6f  wever,.** the co
157f0 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63  unt does not inc
15800 6c 75 64 65 20 63 68 61 6e 67 65 73 20 75 73 65  lude changes use
15810 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 5b  d to implement [
15820 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61  REPLACE] constra
15830 69 6e 74 73 2c 0a 2a 2a 20 64 6f 20 72 6f 6c 6c  ints,.** do roll
15840 62 61 63 6b 73 20 6f 72 20 41 42 4f 52 54 20 70  backs or ABORT p
15850 72 6f 63 65 73 73 69 6e 67 2c 20 6f 72 20 5b 44  rocessing, or [D
15860 52 4f 50 20 54 41 42 4c 45 5d 20 70 72 6f 63 65  ROP TABLE] proce
15870 73 73 69 6e 67 2e 20 20 54 68 65 0a 2a 2a 20 63  ssing.  The.** c
15880 6f 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e  ount does not in
15890 63 6c 75 64 65 20 72 6f 77 73 20 6f 66 20 76 69  clude rows of vi
158a0 65 77 73 20 74 68 61 74 20 66 69 72 65 20 61 6e  ews that fire an
158b0 20 5b 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69   [INSTEAD OF tri
158c0 67 67 65 72 5d 2c 0a 2a 2a 20 74 68 6f 75 67 68  gger],.** though
158d0 20 69 66 20 74 68 65 20 49 4e 53 54 45 41 44 20   if the INSTEAD 
158e0 4f 46 20 74 72 69 67 67 65 72 20 6d 61 6b 65 73  OF trigger makes
158f0 20 63 68 61 6e 67 65 73 20 6f 66 20 69 74 73 20   changes of its 
15900 6f 77 6e 2c 20 74 68 6f 73 65 20 63 68 61 6e 67  own, those chang
15910 65 73 20 0a 2a 2a 20 61 72 65 20 63 6f 75 6e 74  es .** are count
15920 65 64 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 73 71  ed.)^.** ^The sq
15930 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e  lite3_total_chan
15940 67 65 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 63  ges() function c
15950 6f 75 6e 74 73 20 74 68 65 20 63 68 61 6e 67 65  ounts the change
15960 73 20 61 73 20 73 6f 6f 6e 20 61 73 0a 2a 2a 20  s as soon as.** 
15970 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74 68  the statement th
15980 61 74 20 6d 61 6b 65 73 20 74 68 65 6d 20 69 73  at makes them is
15990 20 63 6f 6d 70 6c 65 74 65 64 20 28 77 68 65 6e   completed (when
159a0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68   the statement h
159b0 61 6e 64 6c 65 0a 2a 2a 20 69 73 20 70 61 73 73  andle.** is pass
159c0 65 64 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72  ed to [sqlite3_r
159d0 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69  eset()] or [sqli
159e0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 29  te3_finalize()])
159f0 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
15a00 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 68   the [sqlite3_ch
15a10 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61  anges()] interfa
15a20 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e  ce, the.** [coun
15a30 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61  t_changes pragma
15a40 5d 2c 20 61 6e 64 20 74 68 65 20 5b 74 6f 74 61  ], and the [tota
15a50 6c 5f 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20  l_changes() SQL 
15a60 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a  function]..**.**
15a70 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74   If a separate t
15a80 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e  hread makes chan
15a90 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20  ges on the same 
15aa0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
15ab0 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71  ion.** while [sq
15ac0 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e  lite3_total_chan
15ad0 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e  ges()] is runnin
15ae0 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65  g then the value
15af0 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 73 20  .** returned is 
15b00 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e  unpredictable an
15b10 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c  d not meaningful
15b20 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
15b30 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 73  _total_changes(s
15b40 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
15b50 20 43 41 50 49 33 52 45 46 3a 20 49 6e 74 65 72   CAPI3REF: Inter
15b60 72 75 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e  rupt A Long-Runn
15b70 69 6e 67 20 51 75 65 72 79 0a 2a 2a 0a 2a 2a 20  ing Query.**.** 
15b80 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 63  ^This function c
15b90 61 75 73 65 73 20 61 6e 79 20 70 65 6e 64 69 6e  auses any pendin
15ba0 67 20 64 61 74 61 62 61 73 65 20 6f 70 65 72 61  g database opera
15bb0 74 69 6f 6e 20 74 6f 20 61 62 6f 72 74 20 61 6e  tion to abort an
15bc0 64 0a 2a 2a 20 72 65 74 75 72 6e 20 61 74 20 69  d.** return at i
15bd0 74 73 20 65 61 72 6c 69 65 73 74 20 6f 70 70 6f  ts earliest oppo
15be0 72 74 75 6e 69 74 79 2e 20 54 68 69 73 20 72 6f  rtunity. This ro
15bf0 75 74 69 6e 65 20 69 73 20 74 79 70 69 63 61 6c  utine is typical
15c00 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 69 6e 20  ly.** called in 
15c10 72 65 73 70 6f 6e 73 65 20 74 6f 20 61 20 75 73  response to a us
15c20 65 72 20 61 63 74 69 6f 6e 20 73 75 63 68 20 61  er action such a
15c30 73 20 70 72 65 73 73 69 6e 67 20 22 43 61 6e 63  s pressing "Canc
15c40 65 6c 22 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d 43  el".** or Ctrl-C
15c50 20 77 68 65 72 65 20 74 68 65 20 75 73 65 72 20   where the user 
15c60 77 61 6e 74 73 20 61 20 6c 6f 6e 67 20 71 75 65  wants a long que
15c70 72 79 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20  ry operation to 
15c80 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69 61 74  halt.** immediat
15c90 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69  ely..**.** ^It i
15ca0 73 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74  s safe to call t
15cb0 68 69 73 20 72 6f 75 74 69 6e 65 20 66 72 6f 6d  his routine from
15cc0 20 61 20 74 68 72 65 61 64 20 64 69 66 66 65 72   a thread differ
15cd0 65 6e 74 20 66 72 6f 6d 20 74 68 65 0a 2a 2a 20  ent from the.** 
15ce0 74 68 72 65 61 64 20 74 68 61 74 20 69 73 20 63  thread that is c
15cf0 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67  urrently running
15d00 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6f 70   the database op
15d10 65 72 61 74 69 6f 6e 2e 20 20 42 75 74 20 69 74  eration.  But it
15d20 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 61 66 65 20  .** is not safe 
15d30 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75  to call this rou
15d40 74 69 6e 65 20 77 69 74 68 20 61 20 5b 64 61 74  tine with a [dat
15d50 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
15d60 5d 20 74 68 61 74 0a 2a 2a 20 69 73 20 63 6c 6f  ] that.** is clo
15d70 73 65 64 20 6f 72 20 6d 69 67 68 74 20 63 6c 6f  sed or might clo
15d80 73 65 20 62 65 66 6f 72 65 20 73 71 6c 69 74 65  se before sqlite
15d90 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 72 65  3_interrupt() re
15da0 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  turns..**.** ^If
15db0 20 61 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f   an SQL operatio
15dc0 6e 20 69 73 20 76 65 72 79 20 6e 65 61 72 6c 79  n is very nearly
15dd0 20 66 69 6e 69 73 68 65 64 20 61 74 20 74 68 65   finished at the
15de0 20 74 69 6d 65 20 77 68 65 6e 0a 2a 2a 20 73 71   time when.** sq
15df0 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
15e00 29 20 69 73 20 63 61 6c 6c 65 64 2c 20 74 68 65  ) is called, the
15e10 6e 20 69 74 20 6d 69 67 68 74 20 6e 6f 74 20 68  n it might not h
15e20 61 76 65 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69  ave an opportuni
15e30 74 79 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 74 65  ty.** to be inte
15e40 72 72 75 70 74 65 64 20 61 6e 64 20 6d 69 67 68  rrupted and migh
15e50 74 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 63 6f  t continue to co
15e60 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  mpletion..**.** 
15e70 5e 41 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f  ^An SQL operatio
15e80 6e 20 74 68 61 74 20 69 73 20 69 6e 74 65 72 72  n that is interr
15e90 75 70 74 65 64 20 77 69 6c 6c 20 72 65 74 75 72  upted will retur
15ea0 6e 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52  n [SQLITE_INTERR
15eb0 55 50 54 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  UPT]..** ^If the
15ec0 20 69 6e 74 65 72 72 75 70 74 65 64 20 53 51 4c   interrupted SQL
15ed0 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 61 6e   operation is an
15ee0 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c   INSERT, UPDATE,
15ef0 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68   or DELETE.** th
15f00 61 74 20 69 73 20 69 6e 73 69 64 65 20 61 6e 20  at is inside an 
15f10 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63  explicit transac
15f20 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 65  tion, then the e
15f30 6e 74 69 72 65 20 74 72 61 6e 73 61 63 74 69 6f  ntire transactio
15f40 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 72 6f 6c  n.** will be rol
15f50 6c 65 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 74  led back automat
15f60 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ically..**.** ^T
15f70 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  he sqlite3_inter
15f80 72 75 70 74 28 44 29 20 63 61 6c 6c 20 69 73 20  rupt(D) call is 
15f90 69 6e 20 65 66 66 65 63 74 20 75 6e 74 69 6c 20  in effect until 
15fa0 61 6c 6c 20 63 75 72 72 65 6e 74 6c 79 20 72 75  all currently ru
15fb0 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61  nning.** SQL sta
15fc0 74 65 6d 65 6e 74 73 20 6f 6e 20 5b 64 61 74 61  tements on [data
15fd0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
15fe0 20 44 20 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 41   D complete.  ^A
15ff0 6e 79 20 6e 65 77 20 53 51 4c 20 73 74 61 74 65  ny new SQL state
16000 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72  ments.** that ar
16010 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20  e started after 
16020 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  the sqlite3_inte
16030 72 72 75 70 74 28 29 20 63 61 6c 6c 20 61 6e 64  rrupt() call and
16040 20 62 65 66 6f 72 65 20 74 68 65 20 0a 2a 2a 20   before the .** 
16050 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e  running statemen
16060 74 73 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20  ts reaches zero 
16070 61 72 65 20 69 6e 74 65 72 72 75 70 74 65 64 20  are interrupted 
16080 61 73 20 69 66 20 74 68 65 79 20 68 61 64 20 62  as if they had b
16090 65 65 6e 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 70  een.** running p
160a0 72 69 6f 72 20 74 6f 20 74 68 65 20 73 71 6c 69  rior to the sqli
160b0 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20  te3_interrupt() 
160c0 63 61 6c 6c 2e 20 20 5e 4e 65 77 20 53 51 4c 20  call.  ^New SQL 
160d0 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68  statements.** th
160e0 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61  at are started a
160f0 66 74 65 72 20 74 68 65 20 72 75 6e 6e 69 6e 67  fter the running
16100 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 75 6e 74   statement count
16110 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72   reaches zero ar
16120 65 0a 2a 2a 20 6e 6f 74 20 65 66 66 65 63 74 65  e.** not effecte
16130 64 20 62 79 20 74 68 65 20 73 71 6c 69 74 65 33  d by the sqlite3
16140 5f 69 6e 74 65 72 72 75 70 74 28 29 2e 0a 2a 2a  _interrupt()..**
16150 20 5e 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69   ^A call to sqli
16160 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 44 29  te3_interrupt(D)
16170 20 74 68 61 74 20 6f 63 63 75 72 73 20 77 68 65   that occurs whe
16180 6e 20 74 68 65 72 65 20 61 72 65 20 6e 6f 20 72  n there are no r
16190 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74  unning.** SQL st
161a0 61 74 65 6d 65 6e 74 73 20 69 73 20 61 20 6e 6f  atements is a no
161b0 2d 6f 70 20 61 6e 64 20 68 61 73 20 6e 6f 20 65  -op and has no e
161c0 66 66 65 63 74 20 6f 6e 20 53 51 4c 20 73 74 61  ffect on SQL sta
161d0 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20  tements.** that 
161e0 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65  are started afte
161f0 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  r the sqlite3_in
16200 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20 72  terrupt() call r
16210 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 66  eturns..**.** If
16220 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
16230 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 20  nnection closes 
16240 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 69  while [sqlite3_i
16250 6e 74 65 72 72 75 70 74 28 29 5d 0a 2a 2a 20 69  nterrupt()].** i
16260 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 62  s running then b
16270 61 64 20 74 68 69 6e 67 73 20 77 69 6c 6c 20 6c  ad things will l
16280 69 6b 65 6c 79 20 68 61 70 70 65 6e 2e 0a 2a 2f  ikely happen..*/
16290 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 69 6e  .void sqlite3_in
162a0 74 65 72 72 75 70 74 28 73 71 6c 69 74 65 33 2a  terrupt(sqlite3*
162b0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
162c0 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66  EF: Determine If
162d0 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e   An SQL Statemen
162e0 74 20 49 73 20 43 6f 6d 70 6c 65 74 65 0a 2a 2a  t Is Complete.**
162f0 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
16300 65 73 20 61 72 65 20 75 73 65 66 75 6c 20 64 75  es are useful du
16310 72 69 6e 67 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e  ring command-lin
16320 65 20 69 6e 70 75 74 20 74 6f 20 64 65 74 65 72  e input to deter
16330 6d 69 6e 65 20 69 66 20 74 68 65 0a 2a 2a 20 63  mine if the.** c
16340 75 72 72 65 6e 74 6c 79 20 65 6e 74 65 72 65 64  urrently entered
16350 20 74 65 78 74 20 73 65 65 6d 73 20 74 6f 20 66   text seems to f
16360 6f 72 6d 20 61 20 63 6f 6d 70 6c 65 74 65 20 53  orm a complete S
16370 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 6f 72 0a  QL statement or.
16380 2a 2a 20 69 66 20 61 64 64 69 74 69 6f 6e 61 6c  ** if additional
16390 20 69 6e 70 75 74 20 69 73 20 6e 65 65 64 65 64   input is needed
163a0 20 62 65 66 6f 72 65 20 73 65 6e 64 69 6e 67 20   before sending 
163b0 74 68 65 20 74 65 78 74 20 69 6e 74 6f 0a 2a 2a  the text into.**
163c0 20 53 51 4c 69 74 65 20 66 6f 72 20 70 61 72 73   SQLite for pars
163d0 69 6e 67 2e 20 20 5e 54 68 65 73 65 20 72 6f 75  ing.  ^These rou
163e0 74 69 6e 65 73 20 72 65 74 75 72 6e 20 31 20 69  tines return 1 i
163f0 66 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69  f the input stri
16400 6e 67 0a 2a 2a 20 61 70 70 65 61 72 73 20 74 6f  ng.** appears to
16410 20 62 65 20 61 20 63 6f 6d 70 6c 65 74 65 20 53   be a complete S
16420 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e  QL statement.  ^
16430 41 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6a  A statement is j
16440 75 64 67 65 64 20 74 6f 20 62 65 0a 2a 2a 20 63  udged to be.** c
16450 6f 6d 70 6c 65 74 65 20 69 66 20 69 74 20 65 6e  omplete if it en
16460 64 73 20 77 69 74 68 20 61 20 73 65 6d 69 63 6f  ds with a semico
16470 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64 20 69 73  lon token and is
16480 20 6e 6f 74 20 61 20 70 72 65 66 69 78 20 6f 66   not a prefix of
16490 20 61 0a 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d 65   a.** well-forme
164a0 64 20 43 52 45 41 54 45 20 54 52 49 47 47 45 52  d CREATE TRIGGER
164b0 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 53 65   statement.  ^Se
164c0 6d 69 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72  micolons that ar
164d0 65 20 65 6d 62 65 64 64 65 64 20 77 69 74 68 69  e embedded withi
164e0 6e 0a 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74 65  n.** string lite
164f0 72 61 6c 73 20 6f 72 20 71 75 6f 74 65 64 20 69  rals or quoted i
16500 64 65 6e 74 69 66 69 65 72 20 6e 61 6d 65 73 20  dentifier names 
16510 6f 72 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20  or comments are 
16520 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65  not.** independe
16530 6e 74 20 74 6f 6b 65 6e 73 20 28 74 68 65 79 20  nt tokens (they 
16540 61 72 65 20 70 61 72 74 20 6f 66 20 74 68 65 20  are part of the 
16550 74 6f 6b 65 6e 20 69 6e 20 77 68 69 63 68 20 74  token in which t
16560 68 65 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64  hey are.** embed
16570 64 65 64 29 20 61 6e 64 20 74 68 75 73 20 64 6f  ded) and thus do
16580 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 61 20   not count as a 
16590 73 74 61 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e  statement termin
165a0 61 74 6f 72 2e 20 20 5e 57 68 69 74 65 73 70 61  ator.  ^Whitespa
165b0 63 65 0a 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65 6e  ce.** and commen
165c0 74 73 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 74  ts that follow t
165d0 68 65 20 66 69 6e 61 6c 20 73 65 6d 69 63 6f 6c  he final semicol
165e0 6f 6e 20 61 72 65 20 69 67 6e 6f 72 65 64 2e 0a  on are ignored..
165f0 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75  **.** ^These rou
16600 74 69 6e 65 73 20 72 65 74 75 72 6e 20 30 20 69  tines return 0 i
16610 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  f the statement 
16620 69 73 20 69 6e 63 6f 6d 70 6c 65 74 65 2e 20 20  is incomplete.  
16630 5e 49 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20  ^If a.** memory 
16640 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73  allocation fails
16650 2c 20 74 68 65 6e 20 53 51 4c 49 54 45 5f 4e 4f  , then SQLITE_NO
16660 4d 45 4d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  MEM is returned.
16670 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
16680 75 74 69 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61  utines do not pa
16690 72 73 65 20 74 68 65 20 53 51 4c 20 73 74 61 74  rse the SQL stat
166a0 65 6d 65 6e 74 73 20 74 68 75 73 0a 2a 2a 20 77  ements thus.** w
166b0 69 6c 6c 20 6e 6f 74 20 64 65 74 65 63 74 20 73  ill not detect s
166c0 79 6e 74 61 63 74 69 63 61 6c 6c 79 20 69 6e 63  yntactically inc
166d0 6f 72 72 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a  orrect SQL..**.*
166e0 2a 20 5e 28 49 66 20 53 51 4c 69 74 65 20 68 61  * ^(If SQLite ha
166f0 73 20 6e 6f 74 20 62 65 65 6e 20 69 6e 69 74 69  s not been initi
16700 61 6c 69 7a 65 64 20 75 73 69 6e 67 20 5b 73 71  alized using [sq
16710 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
16720 28 29 5d 20 70 72 69 6f 72 20 0a 2a 2a 20 74 6f  ()] prior .** to
16730 20 69 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65   invoking sqlite
16740 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 74  3_complete16() t
16750 68 65 6e 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  hen sqlite3_init
16760 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f  ialize() is invo
16770 6b 65 64 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63  ked.** automatic
16780 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f  ally by sqlite3_
16790 63 6f 6d 70 6c 65 74 65 31 36 28 29 2e 20 20 49  complete16().  I
167a0 66 20 74 68 61 74 20 69 6e 69 74 69 61 6c 69 7a  f that initializ
167b0 61 74 69 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a 20  ation fails,.** 
167c0 74 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20  then the return 
167d0 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74  value from sqlit
167e0 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20  e3_complete16() 
167f0 77 69 6c 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72 6f  will be non-zero
16800 0a 2a 2a 20 72 65 67 61 72 64 6c 65 73 73 20 6f  .** regardless o
16810 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  f whether or not
16820 20 74 68 65 20 69 6e 70 75 74 20 53 51 4c 20 69   the input SQL i
16830 73 20 63 6f 6d 70 6c 65 74 65 2e 29 5e 0a 2a 2a  s complete.)^.**
16840 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f  .** The input to
16850 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65   [sqlite3_comple
16860 74 65 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20  te()] must be a 
16870 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a  zero-terminated.
16880 2a 2a 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2e  ** UTF-8 string.
16890 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74  .**.** The input
168a0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d   to [sqlite3_com
168b0 70 6c 65 74 65 31 36 28 29 5d 20 6d 75 73 74 20  plete16()] must 
168c0 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  be a zero-termin
168d0 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73  ated.** UTF-16 s
168e0 74 72 69 6e 67 20 69 6e 20 6e 61 74 69 76 65 20  tring in native 
168f0 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a 69  byte order..*/.i
16900 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  nt sqlite3_compl
16910 65 74 65 28 63 6f 6e 73 74 20 63 68 61 72 20 2a  ete(const char *
16920 73 71 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  sql);.int sqlite
16930 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 63 6f 6e  3_complete16(con
16940 73 74 20 76 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a  st void *sql);..
16950 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
16960 52 65 67 69 73 74 65 72 20 41 20 43 61 6c 6c 62  Register A Callb
16970 61 63 6b 20 54 6f 20 48 61 6e 64 6c 65 20 53 51  ack To Handle SQ
16980 4c 49 54 45 5f 42 55 53 59 20 45 72 72 6f 72 73  LITE_BUSY Errors
16990 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75  .**.** ^This rou
169a0 74 69 6e 65 20 73 65 74 73 20 61 20 63 61 6c 6c  tine sets a call
169b0 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 74 68  back function th
169c0 61 74 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f  at might be invo
169d0 6b 65 64 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20  ked whenever.** 
169e0 61 6e 20 61 74 74 65 6d 70 74 20 69 73 20 6d 61  an attempt is ma
169f0 64 65 20 74 6f 20 6f 70 65 6e 20 61 20 64 61 74  de to open a dat
16a00 61 62 61 73 65 20 74 61 62 6c 65 20 74 68 61 74  abase table that
16a10 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 0a   another thread.
16a20 2a 2a 20 6f 72 20 70 72 6f 63 65 73 73 20 68 61  ** or process ha
16a30 73 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20  s locked..**.** 
16a40 5e 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c  ^If the busy cal
16a50 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74  lback is NULL, t
16a60 68 65 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  hen [SQLITE_BUSY
16a70 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45  ] or [SQLITE_IOE
16a80 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 69  RR_BLOCKED].** i
16a90 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64  s returned immed
16aa0 69 61 74 65 6c 79 20 75 70 6f 6e 20 65 6e 63 6f  iately upon enco
16ab0 75 6e 74 65 72 69 6e 67 20 74 68 65 20 6c 6f 63  untering the loc
16ac0 6b 2e 20 20 5e 49 66 20 74 68 65 20 62 75 73 79  k.  ^If the busy
16ad0 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20   callback.** is 
16ae0 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74  not NULL, then t
16af0 68 65 20 63 61 6c 6c 62 61 63 6b 20 6d 69 67 68  he callback migh
16b00 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74  t be invoked wit
16b10 68 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e  h two arguments.
16b20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
16b30 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
16b40 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69  e busy handler i
16b50 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
16b60 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72 20 77 68  void* pointer wh
16b70 69 63 68 0a 2a 2a 20 69 73 20 74 68 65 20 74 68  ich.** is the th
16b80 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ird argument to 
16b90 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e  sqlite3_busy_han
16ba0 64 6c 65 72 28 29 2e 20 20 5e 54 68 65 20 73 65  dler().  ^The se
16bb0 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
16bc0 0a 2a 2a 20 74 68 65 20 62 75 73 79 20 68 61 6e  .** the busy han
16bd0 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  dler callback is
16be0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 74   the number of t
16bf0 69 6d 65 73 20 74 68 61 74 20 74 68 65 20 62 75  imes that the bu
16c00 73 79 20 68 61 6e 64 6c 65 72 20 68 61 73 0a 2a  sy handler has.*
16c10 2a 20 62 65 65 6e 20 69 6e 76 6f 6b 65 64 20 66  * been invoked f
16c20 6f 72 20 74 68 69 73 20 6c 6f 63 6b 69 6e 67 20  or this locking 
16c30 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a  event.  ^If the.
16c40 2a 2a 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b  ** busy callback
16c50 20 72 65 74 75 72 6e 73 20 30 2c 20 74 68 65 6e   returns 0, then
16c60 20 6e 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61   no additional a
16c70 74 74 65 6d 70 74 73 20 61 72 65 20 6d 61 64 65  ttempts are made
16c80 20 74 6f 0a 2a 2a 20 61 63 63 65 73 73 20 74 68   to.** access th
16c90 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 5b  e database and [
16ca0 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20  SQLITE_BUSY] or 
16cb0 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c  [SQLITE_IOERR_BL
16cc0 4f 43 4b 45 44 5d 20 69 73 20 72 65 74 75 72 6e  OCKED] is return
16cd0 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 63  ed..** ^If the c
16ce0 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
16cf0 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 61  non-zero, then a
16d00 6e 6f 74 68 65 72 20 61 74 74 65 6d 70 74 0a 2a  nother attempt.*
16d10 2a 20 69 73 20 6d 61 64 65 20 74 6f 20 6f 70 65  * is made to ope
16d20 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  n the database f
16d30 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 74  or reading and t
16d40 68 65 20 63 79 63 6c 65 20 72 65 70 65 61 74 73  he cycle repeats
16d50 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65 73  ..**.** The pres
16d60 65 6e 63 65 20 6f 66 20 61 20 62 75 73 79 20 68  ence of a busy h
16d70 61 6e 64 6c 65 72 20 64 6f 65 73 20 6e 6f 74 20  andler does not 
16d80 67 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 69  guarantee that i
16d90 74 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65  t will be invoke
16da0 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65 72 65 20  d.** when there 
16db0 69 73 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74 69  is lock contenti
16dc0 6f 6e 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 64  on. ^If SQLite d
16dd0 65 74 65 72 6d 69 6e 65 73 20 74 68 61 74 20 69  etermines that i
16de0 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79  nvoking the busy
16df0 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 63 6f 75 6c  .** handler coul
16e00 64 20 72 65 73 75 6c 74 20 69 6e 20 61 20 64 65  d result in a de
16e10 61 64 6c 6f 63 6b 2c 20 69 74 20 77 69 6c 6c 20  adlock, it will 
16e20 67 6f 20 61 68 65 61 64 20 61 6e 64 20 72 65 74  go ahead and ret
16e30 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  urn [SQLITE_BUSY
16e40 5d 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ].** or [SQLITE_
16e50 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69  IOERR_BLOCKED] i
16e60 6e 73 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69  nstead of invoki
16e70 6e 67 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ng the busy hand
16e80 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65 72  ler..** Consider
16e90 20 61 20 73 63 65 6e 61 72 69 6f 20 77 68 65 72   a scenario wher
16ea0 65 20 6f 6e 65 20 70 72 6f 63 65 73 73 20 69 73  e one process is
16eb0 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 61 64 20   holding a read 
16ec0 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a 20 69 74 20  lock that.** it 
16ed0 69 73 20 74 72 79 69 6e 67 20 74 6f 20 70 72 6f  is trying to pro
16ee0 6d 6f 74 65 20 74 6f 20 61 20 72 65 73 65 72 76  mote to a reserv
16ef0 65 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61  ed lock and.** a
16f00 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20   second process 
16f10 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 73  is holding a res
16f20 65 72 76 65 64 20 6c 6f 63 6b 20 74 68 61 74 20  erved lock that 
16f30 69 74 20 69 73 20 74 72 79 69 6e 67 0a 2a 2a 20  it is trying.** 
16f40 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 6e  to promote to an
16f50 20 65 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b 2e   exclusive lock.
16f60 20 20 54 68 65 20 66 69 72 73 74 20 70 72 6f 63    The first proc
16f70 65 73 73 20 63 61 6e 6e 6f 74 20 70 72 6f 63 65  ess cannot proce
16f80 65 64 0a 2a 2a 20 62 65 63 61 75 73 65 20 69 74  ed.** because it
16f90 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74   is blocked by t
16fa0 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68  he second and th
16fb0 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73  e second process
16fc0 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65   cannot.** proce
16fd0 65 64 20 62 65 63 61 75 73 65 20 69 74 20 69 73  ed because it is
16fe0 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20   blocked by the 
16ff0 66 69 72 73 74 2e 20 20 49 66 20 62 6f 74 68 20  first.  If both 
17000 70 72 6f 63 65 73 73 65 73 0a 2a 2a 20 69 6e 76  processes.** inv
17010 6f 6b 65 20 74 68 65 20 62 75 73 79 20 68 61 6e  oke the busy han
17020 64 6c 65 72 73 2c 20 6e 65 69 74 68 65 72 20 77  dlers, neither w
17030 69 6c 6c 20 6d 61 6b 65 20 61 6e 79 20 70 72 6f  ill make any pro
17040 67 72 65 73 73 2e 20 20 54 68 65 72 65 66 6f 72  gress.  Therefor
17050 65 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 72 65 74  e,.** SQLite ret
17060 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55 53  urns [SQLITE_BUS
17070 59 5d 20 66 6f 72 20 74 68 65 20 66 69 72 73 74  Y] for the first
17080 20 70 72 6f 63 65 73 73 2c 20 68 6f 70 69 6e 67   process, hoping
17090 20 74 68 61 74 20 74 68 69 73 0a 2a 2a 20 77 69   that this.** wi
170a0 6c 6c 20 69 6e 64 75 63 65 20 74 68 65 20 66 69  ll induce the fi
170b0 72 73 74 20 70 72 6f 63 65 73 73 20 74 6f 20 72  rst process to r
170c0 65 6c 65 61 73 65 20 69 74 73 20 72 65 61 64 20  elease its read 
170d0 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a  lock and allow.*
170e0 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f  * the second pro
170f0 63 65 73 73 20 74 6f 20 70 72 6f 63 65 65 64 2e  cess to proceed.
17100 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61  .**.** ^The defa
17110 75 6c 74 20 62 75 73 79 20 63 61 6c 6c 62 61 63  ult busy callbac
17120 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  k is NULL..**.**
17130 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 42 55   ^The [SQLITE_BU
17140 53 59 5d 20 65 72 72 6f 72 20 69 73 20 63 6f 6e  SY] error is con
17150 76 65 72 74 65 64 20 74 6f 20 5b 53 51 4c 49 54  verted to [SQLIT
17160 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d  E_IOERR_BLOCKED]
17170 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74 65 20  .** when SQLite 
17180 69 73 20 69 6e 20 74 68 65 20 6d 69 64 64 6c 65  is in the middle
17190 20 6f 66 20 61 20 6c 61 72 67 65 20 74 72 61 6e   of a large tran
171a0 73 61 63 74 69 6f 6e 20 77 68 65 72 65 20 61 6c  saction where al
171b0 6c 20 74 68 65 0a 2a 2a 20 63 68 61 6e 67 65 73  l the.** changes
171c0 20 77 69 6c 6c 20 6e 6f 74 20 66 69 74 20 69 6e   will not fit in
171d0 74 6f 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79  to the in-memory
171e0 20 63 61 63 68 65 2e 20 20 53 51 4c 69 74 65 20   cache.  SQLite 
171f0 77 69 6c 6c 0a 2a 2a 20 61 6c 72 65 61 64 79 20  will.** already 
17200 68 6f 6c 64 20 61 20 52 45 53 45 52 56 45 44 20  hold a RESERVED 
17210 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 64 61 74 61  lock on the data
17220 62 61 73 65 20 66 69 6c 65 2c 20 62 75 74 20 69  base file, but i
17230 74 20 6e 65 65 64 73 0a 2a 2a 20 74 6f 20 70 72  t needs.** to pr
17240 6f 6d 6f 74 65 20 74 68 69 73 20 6c 6f 63 6b 20  omote this lock 
17250 74 6f 20 45 58 43 4c 55 53 49 56 45 20 73 6f 20  to EXCLUSIVE so 
17260 74 68 61 74 20 69 74 20 63 61 6e 20 73 70 69 6c  that it can spil
17270 6c 20 63 61 63 68 65 0a 2a 2a 20 70 61 67 65 73  l cache.** pages
17280 20 69 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61   into the databa
17290 73 65 20 66 69 6c 65 20 77 69 74 68 6f 75 74 20  se file without 
172a0 68 61 72 6d 20 74 6f 20 63 6f 6e 63 75 72 72 65  harm to concurre
172b0 6e 74 0a 2a 2a 20 72 65 61 64 65 72 73 2e 20 20  nt.** readers.  
172c0 5e 49 66 20 69 74 20 69 73 20 75 6e 61 62 6c 65  ^If it is unable
172d0 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68 65 20   to promote the 
172e0 6c 6f 63 6b 2c 20 74 68 65 6e 20 74 68 65 20 69  lock, then the i
172f0 6e 2d 6d 65 6d 6f 72 79 0a 2a 2a 20 63 61 63 68  n-memory.** cach
17300 65 20 77 69 6c 6c 20 62 65 20 6c 65 66 74 20 69  e will be left i
17310 6e 20 61 6e 20 69 6e 63 6f 6e 73 69 73 74 65 6e  n an inconsisten
17320 74 20 73 74 61 74 65 20 61 6e 64 20 73 6f 20 74  t state and so t
17330 68 65 20 65 72 72 6f 72 0a 2a 2a 20 63 6f 64 65  he error.** code
17340 20 69 73 20 70 72 6f 6d 6f 74 65 64 20 66 72 6f   is promoted fro
17350 6d 20 74 68 65 20 72 65 6c 61 74 69 76 65 6c 79  m the relatively
17360 20 62 65 6e 69 67 6e 20 5b 53 51 4c 49 54 45 5f   benign [SQLITE_
17370 42 55 53 59 5d 20 74 6f 0a 2a 2a 20 74 68 65 20  BUSY] to.** the 
17380 6d 6f 72 65 20 73 65 76 65 72 65 20 5b 53 51 4c  more severe [SQL
17390 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45  ITE_IOERR_BLOCKE
173a0 44 5d 2e 20 20 5e 54 68 69 73 20 65 72 72 6f 72  D].  ^This error
173b0 20 63 6f 64 65 20 70 72 6f 6d 6f 74 69 6f 6e 0a   code promotion.
173c0 2a 2a 20 66 6f 72 63 65 73 20 61 6e 20 61 75 74  ** forces an aut
173d0 6f 6d 61 74 69 63 20 72 6f 6c 6c 62 61 63 6b 20  omatic rollback 
173e0 6f 66 20 74 68 65 20 63 68 61 6e 67 65 73 2e 20  of the changes. 
173f0 20 53 65 65 20 74 68 65 0a 2a 2a 20 3c 61 20 68   See the.** <a h
17400 72 65 66 3d 22 2f 63 76 73 74 72 61 63 2f 77 69  ref="/cvstrac/wi
17410 6b 69 3f 70 3d 43 6f 72 72 75 70 74 69 6f 6e 46  ki?p=CorruptionF
17420 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72 72 6f  ollowingBusyErro
17430 72 22 3e 0a 2a 2a 20 43 6f 72 72 75 70 74 69 6f  r">.** Corruptio
17440 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72  nFollowingBusyEr
17450 72 6f 72 3c 2f 61 3e 20 77 69 6b 69 20 70 61 67  ror</a> wiki pag
17460 65 20 66 6f 72 20 61 20 64 69 73 63 75 73 73 69  e for a discussi
17470 6f 6e 20 6f 66 20 77 68 79 0a 2a 2a 20 74 68 69  on of why.** thi
17480 73 20 69 73 20 69 6d 70 6f 72 74 61 6e 74 2e 0a  s is important..
17490 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61  **.** ^(There ca
174a0 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67  n only be a sing
174b0 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  le busy handler 
174c0 64 65 66 69 6e 65 64 20 66 6f 72 20 65 61 63 68  defined for each
174d0 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
174e0 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 53 65 74 74  nnection].  Sett
174f0 69 6e 67 20 61 20 6e 65 77 20 62 75 73 79 20 68  ing a new busy h
17500 61 6e 64 6c 65 72 20 63 6c 65 61 72 73 20 61 6e  andler clears an
17510 79 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20  y.** previously 
17520 73 65 74 20 68 61 6e 64 6c 65 72 2e 29 5e 20 20  set handler.)^  
17530 5e 4e 6f 74 65 20 74 68 61 74 20 63 61 6c 6c 69  ^Note that calli
17540 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79  ng [sqlite3_busy
17550 5f 74 69 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20 77  _timeout()].** w
17560 69 6c 6c 20 61 6c 73 6f 20 73 65 74 20 6f 72 20  ill also set or 
17570 63 6c 65 61 72 20 74 68 65 20 62 75 73 79 20 68  clear the busy h
17580 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  andler..**.** Th
17590 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20  e busy callback 
175a0 73 68 6f 75 6c 64 20 6e 6f 74 20 74 61 6b 65 20  should not take 
175b0 61 6e 79 20 61 63 74 69 6f 6e 73 20 77 68 69 63  any actions whic
175c0 68 20 6d 6f 64 69 66 79 20 74 68 65 0a 2a 2a 20  h modify the.** 
175d0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
175e0 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64  ion that invoked
175f0 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
17600 72 2e 20 20 41 6e 79 20 73 75 63 68 20 61 63 74  r.  Any such act
17610 69 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c 74 20 69  ions.** result i
17620 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61  n undefined beha
17630 76 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20 41 20 62  vior..** .** A b
17640 75 73 79 20 68 61 6e 64 6c 65 72 20 6d 75 73 74  usy handler must
17650 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20 64   not close the d
17660 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
17670 6f 6e 0a 2a 2a 20 6f 72 20 5b 70 72 65 70 61 72  on.** or [prepar
17680 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68  ed statement] th
17690 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62  at invoked the b
176a0 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a  usy handler..*/.
176b0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79  int sqlite3_busy
176c0 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33  _handler(sqlite3
176d0 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c  *, int(*)(void*,
176e0 69 6e 74 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f  int), void*);../
176f0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
17700 65 74 20 41 20 42 75 73 79 20 54 69 6d 65 6f 75  et A Busy Timeou
17710 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f  t.**.** ^This ro
17720 75 74 69 6e 65 20 73 65 74 73 20 61 20 5b 73 71  utine sets a [sq
17730 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c  lite3_busy_handl
17740 65 72 20 7c 20 62 75 73 79 20 68 61 6e 64 6c 65  er | busy handle
17750 72 5d 20 74 68 61 74 20 73 6c 65 65 70 73 0a 2a  r] that sleeps.*
17760 2a 20 66 6f 72 20 61 20 73 70 65 63 69 66 69 65  * for a specifie
17770 64 20 61 6d 6f 75 6e 74 20 6f 66 20 74 69 6d 65  d amount of time
17780 20 77 68 65 6e 20 61 20 74 61 62 6c 65 20 69 73   when a table is
17790 20 6c 6f 63 6b 65 64 2e 20 20 5e 54 68 65 20 68   locked.  ^The h
177a0 61 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20 73  andler.** will s
177b0 6c 65 65 70 20 6d 75 6c 74 69 70 6c 65 20 74 69  leep multiple ti
177c0 6d 65 73 20 75 6e 74 69 6c 20 61 74 20 6c 65 61  mes until at lea
177d0 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63  st "ms" millisec
177e0 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67  onds of sleeping
177f0 0a 2a 2a 20 68 61 76 65 20 61 63 63 75 6d 75 6c  .** have accumul
17800 61 74 65 64 2e 20 20 5e 41 66 74 65 72 20 61 74  ated.  ^After at
17810 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c   least "ms" mill
17820 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65  iseconds of slee
17830 70 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 68 61 6e  ping,.** the han
17840 64 6c 65 72 20 72 65 74 75 72 6e 73 20 30 20 77  dler returns 0 w
17850 68 69 63 68 20 63 61 75 73 65 73 20 5b 73 71 6c  hich causes [sql
17860 69 74 65 33 5f 73 74 65 70 28 29 5d 20 74 6f 20  ite3_step()] to 
17870 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54  return.** [SQLIT
17880 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49  E_BUSY] or [SQLI
17890 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44  TE_IOERR_BLOCKED
178a0 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e  ]..**.** ^Callin
178b0 67 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  g this routine w
178c0 69 74 68 20 61 6e 20 61 72 67 75 6d 65 6e 74 20  ith an argument 
178d0 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75  less than or equ
178e0 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75  al to zero.** tu
178f0 72 6e 73 20 6f 66 66 20 61 6c 6c 20 62 75 73 79  rns off all busy
17900 20 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a   handlers..**.**
17910 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c   ^(There can onl
17920 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75  y be a single bu
17930 73 79 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61  sy handler for a
17940 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b   particular.** [
17950 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
17960 69 6f 6e 5d 20 61 6e 79 20 61 6e 79 20 67 69 76  ion] any any giv
17970 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49 66 20 61  en moment.  If a
17980 6e 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e 64  nother busy hand
17990 6c 65 72 0a 2a 2a 20 77 61 73 20 64 65 66 69 6e  ler.** was defin
179a0 65 64 20 20 28 75 73 69 6e 67 20 5b 73 71 6c 69  ed  (using [sqli
179b0 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72  te3_busy_handler
179c0 28 29 5d 29 20 70 72 69 6f 72 20 74 6f 20 63 61  ()]) prior to ca
179d0 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69 73 20 72 6f  lling.** this ro
179e0 75 74 69 6e 65 2c 20 74 68 61 74 20 6f 74 68 65  utine, that othe
179f0 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69  r busy handler i
17a00 73 20 63 6c 65 61 72 65 64 2e 29 5e 0a 2a 2f 0a  s cleared.)^.*/.
17a10 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79  int sqlite3_busy
17a20 5f 74 69 6d 65 6f 75 74 28 73 71 6c 69 74 65 33  _timeout(sqlite3
17a30 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a  *, int ms);../*.
17a40 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e  ** CAPI3REF: Con
17a50 76 65 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e 65  venience Routine
17a60 73 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75  s For Running Qu
17a70 65 72 69 65 73 0a 2a 2a 0a 2a 2a 20 54 68 69 73  eries.**.** This
17a80 20 69 73 20 61 20 6c 65 67 61 63 79 20 69 6e 74   is a legacy int
17a90 65 72 66 61 63 65 20 74 68 61 74 20 69 73 20 70  erface that is p
17aa0 72 65 73 65 72 76 65 64 20 66 6f 72 20 62 61 63  reserved for bac
17ab0 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69  kwards compatibi
17ac0 6c 69 74 79 2e 0a 2a 2a 20 55 73 65 20 6f 66 20  lity..** Use of 
17ad0 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 69  this interface i
17ae0 73 20 6e 6f 74 20 72 65 63 6f 6d 6d 65 6e 64 65  s not recommende
17af0 64 2e 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69 74  d..**.** Definit
17b00 69 6f 6e 3a 20 41 20 3c 62 3e 72 65 73 75 6c 74  ion: A <b>result
17b10 20 74 61 62 6c 65 3c 2f 62 3e 20 69 73 20 6d 65   table</b> is me
17b20 6d 6f 72 79 20 64 61 74 61 20 73 74 72 75 63 74  mory data struct
17b30 75 72 65 20 63 72 65 61 74 65 64 20 62 79 20 74  ure created by t
17b40 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67  he.** [sqlite3_g
17b50 65 74 5f 74 61 62 6c 65 28 29 5d 20 69 6e 74 65  et_table()] inte
17b60 72 66 61 63 65 2e 20 20 41 20 72 65 73 75 6c 74  rface.  A result
17b70 20 74 61 62 6c 65 20 72 65 63 6f 72 64 73 20 74   table records t
17b80 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 71  he.** complete q
17b90 75 65 72 79 20 72 65 73 75 6c 74 73 20 66 72 6f  uery results fro
17ba0 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 71 75  m one or more qu
17bb0 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  eries..**.** The
17bc0 20 74 61 62 6c 65 20 63 6f 6e 63 65 70 74 75 61   table conceptua
17bd0 6c 6c 79 20 68 61 73 20 61 20 6e 75 6d 62 65 72  lly has a number
17be0 20 6f 66 20 72 6f 77 73 20 61 6e 64 20 63 6f 6c   of rows and col
17bf0 75 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a 20 74 68  umns.  But.** th
17c00 65 73 65 20 6e 75 6d 62 65 72 73 20 61 72 65 20  ese numbers are 
17c10 6e 6f 74 20 70 61 72 74 20 6f 66 20 74 68 65 20  not part of the 
17c20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 74 73  result table its
17c30 65 6c 66 2e 20 20 54 68 65 73 65 0a 2a 2a 20 6e  elf.  These.** n
17c40 75 6d 62 65 72 73 20 61 72 65 20 6f 62 74 61 69  umbers are obtai
17c50 6e 65 64 20 73 65 70 61 72 61 74 65 6c 79 2e 20  ned separately. 
17c60 20 4c 65 74 20 4e 20 62 65 20 74 68 65 20 6e 75   Let N be the nu
17c70 6d 62 65 72 20 6f 66 20 72 6f 77 73 0a 2a 2a 20  mber of rows.** 
17c80 61 6e 64 20 4d 20 62 65 20 74 68 65 20 6e 75 6d  and M be the num
17c90 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e 0a  ber of columns..
17ca0 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74  **.** A result t
17cb0 61 62 6c 65 20 69 73 20 61 6e 20 61 72 72 61 79  able is an array
17cc0 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20   of pointers to 
17cd0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
17ce0 55 54 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a 2a  UTF-8 strings..*
17cf0 2a 20 54 68 65 72 65 20 61 72 65 20 28 4e 2b 31  * There are (N+1
17d00 29 2a 4d 20 65 6c 65 6d 65 6e 74 73 20 69 6e 20  )*M elements in 
17d10 74 68 65 20 61 72 72 61 79 2e 20 20 54 68 65 20  the array.  The 
17d20 66 69 72 73 74 20 4d 20 70 6f 69 6e 74 65 72 73  first M pointers
17d30 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65 72   point.** to zer
17d40 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72  o-terminated str
17d50 69 6e 67 73 20 74 68 61 74 20 20 63 6f 6e 74 61  ings that  conta
17d60 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20  in the names of 
17d70 74 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20  the columns..** 
17d80 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 65 6e  The remaining en
17d90 74 72 69 65 73 20 61 6c 6c 20 70 6f 69 6e 74 20  tries all point 
17da0 74 6f 20 71 75 65 72 79 20 72 65 73 75 6c 74 73  to query results
17db0 2e 20 20 4e 55 4c 4c 20 76 61 6c 75 65 73 20 72  .  NULL values r
17dc0 65 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c 4c  esult.** in NULL
17dd0 20 70 6f 69 6e 74 65 72 73 2e 20 20 41 6c 6c 20   pointers.  All 
17de0 6f 74 68 65 72 20 76 61 6c 75 65 73 20 61 72 65  other values are
17df0 20 69 6e 20 74 68 65 69 72 20 55 54 46 2d 38 20   in their UTF-8 
17e00 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a  zero-terminated.
17e10 2a 2a 20 73 74 72 69 6e 67 20 72 65 70 72 65 73  ** string repres
17e20 65 6e 74 61 74 69 6f 6e 20 61 73 20 72 65 74 75  entation as retu
17e30 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  rned by [sqlite3
17e40 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e  _column_text()].
17e50 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20  .**.** A result 
17e60 74 61 62 6c 65 20 6d 69 67 68 74 20 63 6f 6e 73  table might cons
17e70 69 73 74 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f  ist of one or mo
17e80 72 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  re memory alloca
17e90 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69 73 20  tions..** It is 
17ea0 6e 6f 74 20 73 61 66 65 20 74 6f 20 70 61 73 73  not safe to pass
17eb0 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   a result table 
17ec0 64 69 72 65 63 74 6c 79 20 74 6f 20 5b 73 71 6c  directly to [sql
17ed0 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a  ite3_free()]..**
17ee0 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   A result table 
17ef0 73 68 6f 75 6c 64 20 62 65 20 64 65 61 6c 6c 6f  should be deallo
17f00 63 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  cated using [sql
17f10 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28  ite3_free_table(
17f20 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 73 20 61  )]..**.** ^(As a
17f30 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 74 68 65  n example of the
17f40 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 66 6f   result table fo
17f50 72 6d 61 74 2c 20 73 75 70 70 6f 73 65 20 61 20  rmat, suppose a 
17f60 71 75 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a 20  query result.** 
17f70 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a  is as follows:.*
17f80 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
17f90 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20  ><pre>.**       
17fa0 20 4e 61 6d 65 20 20 20 20 20 20 20 20 7c 20 41   Name        | A
17fb0 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 2d 2d 2d  ge.**        ---
17fc0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
17fd0 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 20 41  ----.**        A
17fe0 6c 69 63 65 20 20 20 20 20 20 20 7c 20 34 33 0a  lice       | 43.
17ff0 2a 2a 20 20 20 20 20 20 20 20 42 6f 62 20 20 20  **        Bob   
18000 20 20 20 20 20 20 7c 20 32 38 0a 2a 2a 20 20 20        | 28.**   
18010 20 20 20 20 20 43 69 6e 64 79 20 20 20 20 20 20       Cindy      
18020 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c   | 21.** </pre><
18030 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
18040 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74 77 6f  ** There are two
18050 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20 61   column (M==2) a
18060 6e 64 20 74 68 72 65 65 20 72 6f 77 73 20 28 4e  nd three rows (N
18070 3d 3d 33 29 2e 20 20 54 68 75 73 20 74 68 65 0a  ==3).  Thus the.
18080 2a 2a 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20  ** result table 
18090 68 61 73 20 38 20 65 6e 74 72 69 65 73 2e 20 20  has 8 entries.  
180a0 53 75 70 70 6f 73 65 20 74 68 65 20 72 65 73 75  Suppose the resu
180b0 6c 74 20 74 61 62 6c 65 20 69 73 20 73 74 6f 72  lt table is stor
180c0 65 64 0a 2a 2a 20 69 6e 20 61 6e 20 61 72 72 61  ed.** in an arra
180d0 79 20 6e 61 6d 65 73 20 61 7a 52 65 73 75 6c 74  y names azResult
180e0 2e 20 20 54 68 65 6e 20 61 7a 52 65 73 75 6c 74  .  Then azResult
180f0 20 68 6f 6c 64 73 20 74 68 69 73 20 63 6f 6e 74   holds this cont
18100 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ent:.**.** <bloc
18110 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
18120 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
18130 23 39 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 22 3b  #91;0] = "Name";
18140 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
18150 75 6c 74 26 23 39 31 3b 31 5d 20 3d 20 22 41 67  ult&#91;1] = "Ag
18160 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  e";.**        az
18170 52 65 73 75 6c 74 26 23 39 31 3b 32 5d 20 3d 20  Result&#91;2] = 
18180 22 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 20 20  "Alice";.**     
18190 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
181a0 33 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20 20  3] = "43";.**   
181b0 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
181c0 31 3b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a  1;4] = "Bob";.**
181d0 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
181e0 26 23 39 31 3b 35 5d 20 3d 20 22 32 38 22 3b 0a  &#91;5] = "28";.
181f0 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
18200 6c 74 26 23 39 31 3b 36 5d 20 3d 20 22 43 69 6e  lt&#91;6] = "Cin
18210 64 79 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  dy";.**        a
18220 7a 52 65 73 75 6c 74 26 23 39 31 3b 37 5d 20 3d  zResult&#91;7] =
18230 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e   "21";.** </pre>
18240 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a  </blockquote>)^.
18250 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
18260 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 66  e3_get_table() f
18270 75 6e 63 74 69 6f 6e 20 65 76 61 6c 75 61 74 65  unction evaluate
18280 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a  s one or more.**
18290 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72   semicolon-separ
182a0 61 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65  ated SQL stateme
182b0 6e 74 73 20 69 6e 20 74 68 65 20 7a 65 72 6f 2d  nts in the zero-
182c0 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38  terminated UTF-8
182d0 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 66 20 69 74  .** string of it
182e0 73 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  s 2nd parameter 
182f0 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 72 65  and returns a re
18300 73 75 6c 74 20 74 61 62 6c 65 20 74 6f 20 74 68  sult table to th
18310 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 67 69 76  e.** pointer giv
18320 65 6e 20 69 6e 20 69 74 73 20 33 72 64 20 70 61  en in its 3rd pa
18330 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41  rameter..**.** A
18340 66 74 65 72 20 74 68 65 20 61 70 70 6c 69 63 61  fter the applica
18350 74 69 6f 6e 20 68 61 73 20 66 69 6e 69 73 68 65  tion has finishe
18360 64 20 77 69 74 68 20 74 68 65 20 72 65 73 75 6c  d with the resul
18370 74 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 67  t from sqlite3_g
18380 65 74 5f 74 61 62 6c 65 28 29 2c 0a 2a 2a 20 69  et_table(),.** i
18390 74 20 6d 75 73 74 20 70 61 73 73 20 74 68 65 20  t must pass the 
183a0 72 65 73 75 6c 74 20 74 61 62 6c 65 20 70 6f 69  result table poi
183b0 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  nter to sqlite3_
183c0 66 72 65 65 5f 74 61 62 6c 65 28 29 20 69 6e 20  free_table() in 
183d0 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 72 65 6c 65  order to.** rele
183e0 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 74  ase the memory t
183f0 68 61 74 20 77 61 73 20 6d 61 6c 6c 6f 63 65 64  hat was malloced
18400 2e 20 20 42 65 63 61 75 73 65 20 6f 66 20 74 68  .  Because of th
18410 65 20 77 61 79 20 74 68 65 0a 2a 2a 20 5b 73 71  e way the.** [sq
18420 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
18430 68 61 70 70 65 6e 73 20 77 69 74 68 69 6e 20 73  happens within s
18440 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
18450 28 29 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 0a  (), the calling.
18460 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74  ** function must
18470 20 6e 6f 74 20 74 72 79 20 74 6f 20 63 61 6c 6c   not try to call
18480 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
18490 5d 20 64 69 72 65 63 74 6c 79 2e 20 20 4f 6e 6c  ] directly.  Onl
184a0 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72  y.** [sqlite3_fr
184b0 65 65 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 61  ee_table()] is a
184c0 62 6c 65 20 74 6f 20 72 65 6c 65 61 73 65 20 74  ble to release t
184d0 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 70 65 72  he memory proper
184e0 6c 79 20 61 6e 64 20 73 61 66 65 6c 79 2e 0a 2a  ly and safely..*
184f0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
18500 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 69 6e 74  _get_table() int
18510 65 72 66 61 63 65 20 69 73 20 69 6d 70 6c 65 6d  erface is implem
18520 65 6e 74 65 64 20 61 73 20 61 20 77 72 61 70 70  ented as a wrapp
18530 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71  er around.** [sq
18540 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2e 20 20  lite3_exec()].  
18550 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  The sqlite3_get_
18560 74 61 62 6c 65 28 29 20 72 6f 75 74 69 6e 65 20  table() routine 
18570 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 61 63  does not have ac
18580 63 65 73 73 0a 2a 2a 20 74 6f 20 61 6e 79 20 69  cess.** to any i
18590 6e 74 65 72 6e 61 6c 20 64 61 74 61 20 73 74 72  nternal data str
185a0 75 63 74 75 72 65 73 20 6f 66 20 53 51 4c 69 74  uctures of SQLit
185b0 65 2e 20 20 49 74 20 75 73 65 73 20 6f 6e 6c 79  e.  It uses only
185c0 20 74 68 65 20 70 75 62 6c 69 63 0a 2a 2a 20 69   the public.** i
185d0 6e 74 65 72 66 61 63 65 20 64 65 66 69 6e 65 64  nterface defined
185e0 20 68 65 72 65 2e 20 20 41 73 20 61 20 63 6f 6e   here.  As a con
185f0 73 65 71 75 65 6e 63 65 2c 20 65 72 72 6f 72 73  sequence, errors
18600 20 74 68 61 74 20 6f 63 63 75 72 20 69 6e 20 74   that occur in t
18610 68 65 0a 2a 2a 20 77 72 61 70 70 65 72 20 6c 61  he.** wrapper la
18620 79 65 72 20 6f 75 74 73 69 64 65 20 6f 66 20 74  yer outside of t
18630 68 65 20 69 6e 74 65 72 6e 61 6c 20 5b 73 71 6c  he internal [sql
18640 69 74 65 33 5f 65 78 65 63 28 29 5d 20 63 61 6c  ite3_exec()] cal
18650 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 66  l are not.** ref
18660 6c 65 63 74 65 64 20 69 6e 20 73 75 62 73 65 71  lected in subseq
18670 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73  uent calls to [s
18680 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29  qlite3_errcode()
18690 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
186a0 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2f 0a 69  _errmsg()]..*/.i
186b0 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  nt sqlite3_get_t
186c0 61 62 6c 65 28 0a 20 20 73 71 6c 69 74 65 33 20  able(.  sqlite3 
186d0 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 2f 2a  *db,          /*
186e0 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73   An open databas
186f0 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
18700 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 2f 2a 20  r *zSql,     /* 
18710 53 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75 61  SQL to be evalua
18720 74 65 64 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a  ted */.  char **
18730 2a 70 61 7a 52 65 73 75 6c 74 2c 20 20 20 20 2f  *pazResult,    /
18740 2a 20 52 65 73 75 6c 74 73 20 6f 66 20 74 68 65  * Results of the
18750 20 71 75 65 72 79 20 2a 2f 0a 20 20 69 6e 74 20   query */.  int 
18760 2a 70 6e 52 6f 77 2c 20 20 20 20 20 20 20 20 20  *pnRow,         
18770 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72    /* Number of r
18780 65 73 75 6c 74 20 72 6f 77 73 20 77 72 69 74 74  esult rows writt
18790 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 69 6e 74  en here */.  int
187a0 20 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20 20 20 20   *pnColumn,     
187b0 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20     /* Number of 
187c0 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 77  result columns w
187d0 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20  ritten here */. 
187e0 20 63 68 61 72 20 2a 2a 70 7a 45 72 72 6d 73 67   char **pzErrmsg
187f0 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20         /* Error 
18800 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65 72 65  msg written here
18810 20 2a 2f 0a 29 3b 0a 76 6f 69 64 20 73 71 6c 69   */.);.void sqli
18820 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 63  te3_free_table(c
18830 68 61 72 20 2a 2a 72 65 73 75 6c 74 29 3b 0a 0a  har **result);..
18840 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
18850 46 6f 72 6d 61 74 74 65 64 20 53 74 72 69 6e 67  Formatted String
18860 20 50 72 69 6e 74 69 6e 67 20 46 75 6e 63 74 69   Printing Functi
18870 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ons.**.** These 
18880 72 6f 75 74 69 6e 65 73 20 61 72 65 20 77 6f 72  routines are wor
18890 6b 2d 61 6c 69 6b 65 73 20 6f 66 20 74 68 65 20  k-alikes of the 
188a0 22 70 72 69 6e 74 66 28 29 22 20 66 61 6d 69 6c  "printf()" famil
188b0 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a  y of functions.*
188c0 2a 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64  * from the stand
188d0 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a  ard C library..*
188e0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
188f0 33 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e 64 20  3_mprintf() and 
18900 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66  sqlite3_vmprintf
18910 28 29 20 72 6f 75 74 69 6e 65 73 20 77 72 69 74  () routines writ
18920 65 20 74 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c  e their.** resul
18930 74 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f  ts into memory o
18940 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
18950 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e  lite3_malloc()].
18960 0a 2a 2a 20 54 68 65 20 73 74 72 69 6e 67 73 20  .** The strings 
18970 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 73  returned by thes
18980 65 20 74 77 6f 20 72 6f 75 74 69 6e 65 73 20 73  e two routines s
18990 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65  hould be.** rele
189a0 61 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  ased by [sqlite3
189b0 5f 66 72 65 65 28 29 5d 2e 20 20 5e 42 6f 74 68  _free()].  ^Both
189c0 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
189d0 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74   a.** NULL point
189e0 65 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d  er if [sqlite3_m
189f0 61 6c 6c 6f 63 28 29 5d 20 69 73 20 75 6e 61 62  alloc()] is unab
18a00 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65  le to allocate e
18a10 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20  nough.** memory 
18a20 74 6f 20 68 6f 6c 64 20 74 68 65 20 72 65 73 75  to hold the resu
18a30 6c 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a  lting string..**
18a40 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65  .** ^(The sqlite
18a50 33 5f 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75  3_snprintf() rou
18a60 74 69 6e 65 20 69 73 20 73 69 6d 69 6c 61 72 20  tine is similar 
18a70 74 6f 20 22 73 6e 70 72 69 6e 74 66 28 29 22 20  to "snprintf()" 
18a80 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61 6e  from.** the stan
18a90 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 20  dard C library. 
18aa0 20 54 68 65 20 72 65 73 75 6c 74 20 69 73 20 77   The result is w
18ab0 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 0a  ritten into the.
18ac0 2a 2a 20 62 75 66 66 65 72 20 73 75 70 70 6c 69  ** buffer suppli
18ad0 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  ed as the second
18ae0 20 70 61 72 61 6d 65 74 65 72 20 77 68 6f 73 65   parameter whose
18af0 20 73 69 7a 65 20 69 73 20 67 69 76 65 6e 20 62   size is given b
18b00 79 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 70  y.** the first p
18b10 61 72 61 6d 65 74 65 72 2e 20 4e 6f 74 65 20 74  arameter. Note t
18b20 68 61 74 20 74 68 65 20 6f 72 64 65 72 20 6f 66  hat the order of
18b30 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 77   the.** first tw
18b40 6f 20 70 61 72 61 6d 65 74 65 72 73 20 69 73 20  o parameters is 
18b50 72 65 76 65 72 73 65 64 20 66 72 6f 6d 20 73 6e  reversed from sn
18b60 70 72 69 6e 74 66 28 29 2e 29 5e 20 20 54 68 69  printf().)^  Thi
18b70 73 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74 6f  s is an.** histo
18b80 72 69 63 61 6c 20 61 63 63 69 64 65 6e 74 20 74  rical accident t
18b90 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 20 66 69  hat cannot be fi
18ba0 78 65 64 20 77 69 74 68 6f 75 74 20 62 72 65 61  xed without brea
18bb0 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72 64  king.** backward
18bc0 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e  s compatibility.
18bd0 20 20 5e 28 4e 6f 74 65 20 61 6c 73 6f 20 74 68    ^(Note also th
18be0 61 74 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  at sqlite3_snpri
18bf0 6e 74 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73  ntf().** returns
18c00 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74   a pointer to it
18c10 73 20 62 75 66 66 65 72 20 69 6e 73 74 65 61 64  s buffer instead
18c20 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   of the number o
18c30 66 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20  f.** characters 
18c40 61 63 74 75 61 6c 6c 79 20 77 72 69 74 74 65 6e  actually written
18c50 20 69 6e 74 6f 20 74 68 65 20 62 75 66 66 65 72   into the buffer
18c60 2e 29 5e 20 20 57 65 20 61 64 6d 69 74 20 74 68  .)^  We admit th
18c70 61 74 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72  at.** the number
18c80 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 20 77   of characters w
18c90 72 69 74 74 65 6e 20 77 6f 75 6c 64 20 62 65 20  ritten would be 
18ca0 61 20 6d 6f 72 65 20 75 73 65 66 75 6c 20 72 65  a more useful re
18cb0 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62 75  turn.** value bu
18cc0 74 20 77 65 20 63 61 6e 6e 6f 74 20 63 68 61 6e  t we cannot chan
18cd0 67 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74  ge the implement
18ce0 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33  ation of sqlite3
18cf0 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 6e  _snprintf().** n
18d00 6f 77 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b  ow without break
18d10 69 6e 67 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  ing compatibilit
18d20 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 6c 6f 6e  y..**.** ^As lon
18d30 67 20 61 73 20 74 68 65 20 62 75 66 66 65 72 20  g as the buffer 
18d40 73 69 7a 65 20 69 73 20 67 72 65 61 74 65 72 20  size is greater 
18d50 74 68 61 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 74  than zero, sqlit
18d60 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a  e3_snprintf().**
18d70 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74   guarantees that
18d80 20 74 68 65 20 62 75 66 66 65 72 20 69 73 20 61   the buffer is a
18d90 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69  lways zero-termi
18da0 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 66 69 72  nated.  ^The fir
18db0 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  st.** parameter 
18dc0 22 6e 22 20 69 73 20 74 68 65 20 74 6f 74 61 6c  "n" is the total
18dd0 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66   size of the buf
18de0 66 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67 20 73  fer, including s
18df0 70 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20  pace for.** the 
18e00 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e  zero terminator.
18e10 20 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73 74    So the longest
18e20 20 73 74 72 69 6e 67 20 74 68 61 74 20 63 61 6e   string that can
18e30 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a   be completely.*
18e40 2a 20 77 72 69 74 74 65 6e 20 77 69 6c 6c 20 62  * written will b
18e50 65 20 6e 2d 31 20 63 68 61 72 61 63 74 65 72 73  e n-1 characters
18e60 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
18e70 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 29  ite3_vsnprintf()
18e80 20 72 6f 75 74 69 6e 65 20 69 73 20 61 20 76 61   routine is a va
18e90 72 61 72 67 73 20 76 65 72 73 69 6f 6e 20 6f 66  rargs version of
18ea0 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74   sqlite3_snprint
18eb0 66 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  f()..**.** These
18ec0 20 72 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69 6d   routines all im
18ed0 70 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64 64  plement some add
18ee0 69 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74 69  itional formatti
18ef0 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74 68  ng.** options th
18f00 61 74 20 61 72 65 20 75 73 65 66 75 6c 20 66 6f  at are useful fo
18f10 72 20 63 6f 6e 73 74 72 75 63 74 69 6e 67 20 53  r constructing S
18f20 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a  QL statements..*
18f30 2a 20 41 6c 6c 20 6f 66 20 74 68 65 20 75 73 75  * All of the usu
18f40 61 6c 20 70 72 69 6e 74 66 28 29 20 66 6f 72 6d  al printf() form
18f50 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 61  atting options a
18f60 70 70 6c 79 2e 20 20 49 6e 20 61 64 64 69 74 69  pply.  In additi
18f70 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73 20  on, there.** is 
18f80 61 72 65 20 22 25 71 22 2c 20 22 25 51 22 2c 20  are "%q", "%Q", 
18f90 61 6e 64 20 22 25 7a 22 20 6f 70 74 69 6f 6e 73  and "%z" options
18fa0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 71  ..**.** ^(The %q
18fb0 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69   option works li
18fc0 6b 65 20 25 73 20 69 6e 20 74 68 61 74 20 69 74  ke %s in that it
18fd0 20 73 75 62 73 74 69 74 75 74 65 73 20 61 20 6e   substitutes a n
18fe0 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ul-terminated.**
18ff0 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 74 68 65   string from the
19000 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 2e 20   argument list. 
19010 20 42 75 74 20 25 71 20 61 6c 73 6f 20 64 6f 75   But %q also dou
19020 62 6c 65 73 20 65 76 65 72 79 20 27 5c 27 27 20  bles every '\'' 
19030 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 25 71  character..** %q
19040 20 69 73 20 64 65 73 69 67 6e 65 64 20 66 6f 72   is designed for
19050 20 75 73 65 20 69 6e 73 69 64 65 20 61 20 73 74   use inside a st
19060 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 29 5e 20  ring literal.)^ 
19070 20 42 79 20 64 6f 75 62 6c 69 6e 67 20 65 61 63   By doubling eac
19080 68 20 27 5c 27 27 0a 2a 2a 20 63 68 61 72 61 63  h '\''.** charac
19090 74 65 72 20 69 74 20 65 73 63 61 70 65 73 20 74  ter it escapes t
190a0 68 61 74 20 63 68 61 72 61 63 74 65 72 20 61 6e  hat character an
190b0 64 20 61 6c 6c 6f 77 73 20 69 74 20 74 6f 20 62  d allows it to b
190c0 65 20 69 6e 73 65 72 74 65 64 20 69 6e 74 6f 0a  e inserted into.
190d0 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 2e 0a 2a  ** the string..*
190e0 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65  *.** For example
190f0 2c 20 61 73 73 75 6d 65 20 74 68 65 20 73 74 72  , assume the str
19100 69 6e 67 20 76 61 72 69 61 62 6c 65 20 7a 54 65  ing variable zTe
19110 78 74 20 63 6f 6e 74 61 69 6e 73 20 74 65 78 74  xt contains text
19120 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a   as follows:.**.
19130 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
19140 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a  pre>.**  char *z
19150 54 65 78 74 20 3d 20 22 49 74 27 73 20 61 20 68  Text = "It's a h
19160 61 70 70 79 20 64 61 79 21 22 3b 0a 2a 2a 20 3c  appy day!";.** <
19170 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
19180 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e  e>.**.** One can
19190 20 75 73 65 20 74 68 69 73 20 74 65 78 74 20 69   use this text i
191a0 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  n an SQL stateme
191b0 6e 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a  nt as follows:.*
191c0 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
191d0 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20  ><pre>.**  char 
191e0 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f  *zSQL = sqlite3_
191f0 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20  mprintf("INSERT 
19200 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45  INTO table VALUE
19210 53 28 27 25 71 27 29 22 2c 20 7a 54 65 78 74 29  S('%q')", zText)
19220 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78  ;.**  sqlite3_ex
19230 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20  ec(db, zSQL, 0, 
19240 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74  0, 0);.**  sqlit
19250 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a  e3_free(zSQL);.*
19260 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
19270 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61  uote>.**.** Beca
19280 75 73 65 20 74 68 65 20 25 71 20 66 6f 72 6d 61  use the %q forma
19290 74 20 73 74 72 69 6e 67 20 69 73 20 75 73 65 64  t string is used
192a0 2c 20 74 68 65 20 27 5c 27 27 20 63 68 61 72 61  , the '\'' chara
192b0 63 74 65 72 20 69 6e 20 7a 54 65 78 74 0a 2a 2a  cter in zText.**
192c0 20 69 73 20 65 73 63 61 70 65 64 20 61 6e 64 20   is escaped and 
192d0 74 68 65 20 53 51 4c 20 67 65 6e 65 72 61 74 65  the SQL generate
192e0 64 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a  d is as follows:
192f0 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
19300 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53  te><pre>.**  INS
19310 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20  ERT INTO table1 
19320 56 41 4c 55 45 53 28 27 49 74 27 27 73 20 61 20  VALUES('It''s a 
19330 68 61 70 70 79 20 64 61 79 21 27 29 0a 2a 2a 20  happy day!').** 
19340 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
19350 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69  te>.**.** This i
19360 73 20 63 6f 72 72 65 63 74 2e 20 20 48 61 64 20  s correct.  Had 
19370 77 65 20 75 73 65 64 20 25 73 20 69 6e 73 74 65  we used %s inste
19380 61 64 20 6f 66 20 25 71 2c 20 74 68 65 20 67 65  ad of %q, the ge
19390 6e 65 72 61 74 65 64 20 53 51 4c 0a 2a 2a 20 77  nerated SQL.** w
193a0 6f 75 6c 64 20 68 61 76 65 20 6c 6f 6f 6b 65 64  ould have looked
193b0 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a   like this:.**.*
193c0 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
193d0 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49  re>.**  INSERT I
193e0 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45  NTO table1 VALUE
193f0 53 28 27 49 74 27 73 20 61 20 68 61 70 70 79 20  S('It's a happy 
19400 64 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65  day!');.** </pre
19410 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
19420 2a 0a 2a 2a 20 54 68 69 73 20 73 65 63 6f 6e 64  *.** This second
19430 20 65 78 61 6d 70 6c 65 20 69 73 20 61 6e 20 53   example is an S
19440 51 4c 20 73 79 6e 74 61 78 20 65 72 72 6f 72 2e  QL syntax error.
19450 20 20 41 73 20 61 20 67 65 6e 65 72 61 6c 20 72    As a general r
19460 75 6c 65 20 79 6f 75 20 73 68 6f 75 6c 64 0a 2a  ule you should.*
19470 2a 20 61 6c 77 61 79 73 20 75 73 65 20 25 71 20  * always use %q 
19480 69 6e 73 74 65 61 64 20 6f 66 20 25 73 20 77 68  instead of %s wh
19490 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 74 65 78  en inserting tex
194a0 74 20 69 6e 74 6f 20 61 20 73 74 72 69 6e 67 20  t into a string 
194b0 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 5e  literal..**.** ^
194c0 28 54 68 65 20 25 51 20 6f 70 74 69 6f 6e 20 77  (The %Q option w
194d0 6f 72 6b 73 20 6c 69 6b 65 20 25 71 20 65 78 63  orks like %q exc
194e0 65 70 74 20 69 74 20 61 6c 73 6f 20 61 64 64 73  ept it also adds
194f0 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 20 61   single quotes a
19500 72 6f 75 6e 64 0a 2a 2a 20 74 68 65 20 6f 75 74  round.** the out
19510 73 69 64 65 20 6f 66 20 74 68 65 20 74 6f 74 61  side of the tota
19520 6c 20 73 74 72 69 6e 67 2e 20 20 41 64 64 69 74  l string.  Addit
19530 69 6f 6e 61 6c 6c 79 2c 20 69 66 20 74 68 65 20  ionally, if the 
19540 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65  parameter in the
19550 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6c 69 73  .** argument lis
19560 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  t is a NULL poin
19570 74 65 72 2c 20 25 51 20 73 75 62 73 74 69 74 75  ter, %Q substitu
19580 74 65 73 20 74 68 65 20 74 65 78 74 20 22 4e 55  tes the text "NU
19590 4c 4c 22 20 28 77 69 74 68 6f 75 74 0a 2a 2a 20  LL" (without.** 
195a0 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 29 2e 29  single quotes).)
195b0 5e 20 20 53 6f 2c 20 66 6f 72 20 65 78 61 6d 70  ^  So, for examp
195c0 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c 64 20 73 61  le, one could sa
195d0 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  y:.**.** <blockq
195e0 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63  uote><pre>.**  c
195f0 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69  har *zSQL = sqli
19600 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53  te3_mprintf("INS
19610 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56  ERT INTO table V
19620 41 4c 55 45 53 28 25 51 29 22 2c 20 7a 54 65 78  ALUES(%Q)", zTex
19630 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f  t);.**  sqlite3_
19640 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30  exec(db, zSQL, 0
19650 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c  , 0, 0);.**  sql
19660 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b  ite3_free(zSQL);
19670 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
19680 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68  kquote>.**.** Th
19690 65 20 63 6f 64 65 20 61 62 6f 76 65 20 77 69 6c  e code above wil
196a0 6c 20 72 65 6e 64 65 72 20 61 20 63 6f 72 72 65  l render a corre
196b0 63 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ct SQL statement
196c0 20 69 6e 20 74 68 65 20 7a 53 51 4c 0a 2a 2a 20   in the zSQL.** 
196d0 76 61 72 69 61 62 6c 65 20 65 76 65 6e 20 69 66  variable even if
196e0 20 74 68 65 20 7a 54 65 78 74 20 76 61 72 69 61   the zText varia
196f0 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  ble is a NULL po
19700 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  inter..**.** ^(T
19710 68 65 20 22 25 7a 22 20 66 6f 72 6d 61 74 74 69  he "%z" formatti
19720 6e 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20  ng option works 
19730 6c 69 6b 65 20 22 25 73 22 20 62 75 74 20 77 69  like "%s" but wi
19740 74 68 20 74 68 65 0a 2a 2a 20 61 64 64 69 74 69  th the.** additi
19750 6f 6e 20 74 68 61 74 20 61 66 74 65 72 20 74 68  on that after th
19760 65 20 73 74 72 69 6e 67 20 68 61 73 20 62 65 65  e string has bee
19770 6e 20 72 65 61 64 20 61 6e 64 20 63 6f 70 69 65  n read and copie
19780 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 72 65  d into.** the re
19790 73 75 6c 74 2c 20 5b 73 71 6c 69 74 65 33 5f 66  sult, [sqlite3_f
197a0 72 65 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64  ree()] is called
197b0 20 6f 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74   on the input st
197c0 72 69 6e 67 2e 29 5e 0a 2a 2f 0a 63 68 61 72 20  ring.)^.*/.char 
197d0 2a 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66  *sqlite3_mprintf
197e0 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 2e 2e 2e  (const char*,...
197f0 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33  );.char *sqlite3
19800 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20  _vmprintf(const 
19810 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b  char*, va_list);
19820 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73  .char *sqlite3_s
19830 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72  nprintf(int,char
19840 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 2e  *,const char*, .
19850 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74  ..);.char *sqlit
19860 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 69 6e 74  e3_vsnprintf(int
19870 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61  ,char*,const cha
19880 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 0a 2f  r*, va_list);../
19890 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
198a0 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e  emory Allocation
198b0 20 53 75 62 73 79 73 74 65 6d 0a 2a 2a 0a 2a 2a   Subsystem.**.**
198c0 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   The SQLite core
198d0 20 75 73 65 73 20 74 68 65 73 65 20 74 68 72 65   uses these thre
198e0 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 20 61  e routines for a
198f0 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e 0a 2a 2a  ll of its own.**
19900 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72 79   internal memory
19910 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64   allocation need
19920 73 2e 20 22 43 6f 72 65 22 20 69 6e 20 74 68 65  s. "Core" in the
19930 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e   previous senten
19940 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 69  ce.** does not i
19950 6e 63 6c 75 64 65 20 6f 70 65 72 61 74 69 6e 67  nclude operating
19960 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66 69 63  -system specific
19970 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
19980 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 57 69 6e  ion.  The.** Win
19990 64 6f 77 73 20 56 46 53 20 75 73 65 73 20 6e 61  dows VFS uses na
199a0 74 69 76 65 20 6d 61 6c 6c 6f 63 28 29 20 61 6e  tive malloc() an
199b0 64 20 66 72 65 65 28 29 20 66 6f 72 20 73 6f 6d  d free() for som
199c0 65 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a  e operations..**
199d0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
199e0 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e  _malloc() routin
199f0 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  e returns a poin
19a00 74 65 72 20 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a  ter to a block.*
19a10 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61 74 20 6c  * of memory at l
19a20 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20  east N bytes in 
19a30 6c 65 6e 67 74 68 2c 20 77 68 65 72 65 20 4e 20  length, where N 
19a40 69 73 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  is the parameter
19a50 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33  ..** ^If sqlite3
19a60 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 75 6e 61  _malloc() is una
19a70 62 6c 65 20 74 6f 20 6f 62 74 61 69 6e 20 73 75  ble to obtain su
19a80 66 66 69 63 69 65 6e 74 20 66 72 65 65 0a 2a 2a  fficient free.**
19a90 20 6d 65 6d 6f 72 79 2c 20 69 74 20 72 65 74 75   memory, it retu
19aa0 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  rns a NULL point
19ab0 65 72 2e 20 20 5e 49 66 20 74 68 65 20 70 61 72  er.  ^If the par
19ac0 61 6d 65 74 65 72 20 4e 20 74 6f 0a 2a 2a 20 73  ameter N to.** s
19ad0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
19ae0 69 73 20 7a 65 72 6f 20 6f 72 20 6e 65 67 61 74  is zero or negat
19af0 69 76 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ive then sqlite3
19b00 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e  _malloc() return
19b10 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  s.** a NULL poin
19b20 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c  ter..**.** ^Call
19b30 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 65 65  ing sqlite3_free
19b40 28 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65  () with a pointe
19b50 72 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74  r previously ret
19b60 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69  urned.** by sqli
19b70 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20  te3_malloc() or 
19b80 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
19b90 29 20 72 65 6c 65 61 73 65 73 20 74 68 61 74 20  ) releases that 
19ba0 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 68 61  memory so.** tha
19bb0 74 20 69 74 20 6d 69 67 68 74 20 62 65 20 72 65  t it might be re
19bc0 75 73 65 64 2e 20 20 5e 54 68 65 20 73 71 6c 69  used.  ^The sqli
19bd0 74 65 33 5f 66 72 65 65 28 29 20 72 6f 75 74 69  te3_free() routi
19be0 6e 65 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70  ne is.** a no-op
19bf0 20 69 66 20 69 73 20 63 61 6c 6c 65 64 20 77 69   if is called wi
19c00 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  th a NULL pointe
19c10 72 2e 20 20 50 61 73 73 69 6e 67 20 61 20 4e 55  r.  Passing a NU
19c20 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f  LL pointer.** to
19c30 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20   sqlite3_free() 
19c40 69 73 20 68 61 72 6d 6c 65 73 73 2e 20 20 41 66  is harmless.  Af
19c50 74 65 72 20 62 65 69 6e 67 20 66 72 65 65 64 2c  ter being freed,
19c60 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c   memory.** shoul
19c70 64 20 6e 65 69 74 68 65 72 20 62 65 20 72 65 61  d neither be rea
19c80 64 20 6e 6f 72 20 77 72 69 74 74 65 6e 2e 20 20  d nor written.  
19c90 45 76 65 6e 20 72 65 61 64 69 6e 67 20 70 72 65  Even reading pre
19ca0 76 69 6f 75 73 6c 79 20 66 72 65 65 64 0a 2a 2a  viously freed.**
19cb0 20 6d 65 6d 6f 72 79 20 6d 69 67 68 74 20 72 65   memory might re
19cc0 73 75 6c 74 20 69 6e 20 61 20 73 65 67 6d 65 6e  sult in a segmen
19cd0 74 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72 20  tation fault or 
19ce0 6f 74 68 65 72 20 73 65 76 65 72 65 20 65 72 72  other severe err
19cf0 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f  or..** Memory co
19d00 72 72 75 70 74 69 6f 6e 2c 20 61 20 73 65 67 6d  rruption, a segm
19d10 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 2c 20  entation fault, 
19d20 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72 65 20  or other severe 
19d30 65 72 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 20 72  error.** might r
19d40 65 73 75 6c 74 20 69 66 20 73 71 6c 69 74 65 33  esult if sqlite3
19d50 5f 66 72 65 65 28 29 20 69 73 20 63 61 6c 6c 65  _free() is calle
19d60 64 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c  d with a non-NUL
19d70 4c 20 70 6f 69 6e 74 65 72 20 74 68 61 74 0a 2a  L pointer that.*
19d80 2a 20 77 61 73 20 6e 6f 74 20 6f 62 74 61 69 6e  * was not obtain
19d90 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ed from sqlite3_
19da0 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69  malloc() or sqli
19db0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a  te3_realloc()..*
19dc0 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74  *.** ^(The sqlit
19dd0 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69 6e 74  e3_realloc() int
19de0 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20  erface attempts 
19df0 74 6f 20 72 65 73 69 7a 65 20 61 0a 2a 2a 20 70  to resize a.** p
19e00 72 69 6f 72 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  rior memory allo
19e10 63 61 74 69 6f 6e 20 74 6f 20 62 65 20 61 74 20  cation to be at 
19e20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 2c 20 77  least N bytes, w
19e30 68 65 72 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a  here N is the.**
19e40 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
19e50 72 2e 20 20 54 68 65 20 6d 65 6d 6f 72 79 20 61  r.  The memory a
19e60 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65 20  llocation to be 
19e70 72 65 73 69 7a 65 64 20 69 73 20 74 68 65 20 66  resized is the f
19e80 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65  irst.** paramete
19e90 72 2e 29 5e 20 5e 20 49 66 20 74 68 65 20 66 69  r.)^ ^ If the fi
19ea0 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rst parameter to
19eb0 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
19ec0 28 29 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20  ().** is a NULL 
19ed0 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 69 74 73  pointer then its
19ee0 20 62 65 68 61 76 69 6f 72 20 69 73 20 69 64 65   behavior is ide
19ef0 6e 74 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69 6e  ntical to callin
19f00 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c  g.** sqlite3_mal
19f10 6c 6f 63 28 4e 29 20 77 68 65 72 65 20 4e 20 69  loc(N) where N i
19f20 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  s the second par
19f30 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
19f40 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20  3_realloc()..** 
19f50 5e 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20 70  ^If the second p
19f60 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
19f70 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69 73  te3_realloc() is
19f80 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67 61   zero or.** nega
19f90 74 69 76 65 20 74 68 65 6e 20 74 68 65 20 62 65  tive then the be
19fa0 68 61 76 69 6f 72 20 69 73 20 65 78 61 63 74 6c  havior is exactl
19fb0 79 20 74 68 65 20 73 61 6d 65 20 61 73 20 63 61  y the same as ca
19fc0 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33  lling.** sqlite3
19fd0 5f 66 72 65 65 28 50 29 20 77 68 65 72 65 20 50  _free(P) where P
19fe0 20 69 73 20 74 68 65 20 66 69 72 73 74 20 70 61   is the first pa
19ff0 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
1a000 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a  e3_realloc()..**
1a010 20 5e 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   ^sqlite3_reallo
1a020 63 28 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f  c() returns a po
1a030 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72  inter to a memor
1a040 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  y allocation.** 
1a050 6f 66 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79  of at least N by
1a060 74 65 73 20 69 6e 20 73 69 7a 65 20 6f 72 20 4e  tes in size or N
1a070 55 4c 4c 20 69 66 20 73 75 66 66 69 63 69 65 6e  ULL if sufficien
1a080 74 20 6d 65 6d 6f 72 79 20 69 73 20 75 6e 61 76  t memory is unav
1a090 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20  ailable..** ^If 
1a0a0 4d 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66  M is the size of
1a0b0 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63   the prior alloc
1a0c0 61 74 69 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e 28  ation, then min(
1a0d0 4e 2c 4d 29 20 62 79 74 65 73 0a 2a 2a 20 6f 66  N,M) bytes.** of
1a0e0 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63   the prior alloc
1a0f0 61 74 69 6f 6e 20 61 72 65 20 63 6f 70 69 65 64  ation are copied
1a100 20 69 6e 74 6f 20 74 68 65 20 62 65 67 69 6e 6e   into the beginn
1a110 69 6e 67 20 6f 66 20 62 75 66 66 65 72 20 72 65  ing of buffer re
1a120 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c  turned.** by sql
1a130 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 61  ite3_realloc() a
1a140 6e 64 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c  nd the prior all
1a150 6f 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65 64  ocation is freed
1a160 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33  ..** ^If sqlite3
1a170 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 74 75 72  _realloc() retur
1a180 6e 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68  ns NULL, then th
1a190 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69  e prior allocati
1a1a0 6f 6e 0a 2a 2a 20 69 73 20 6e 6f 74 20 66 72 65  on.** is not fre
1a1b0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d  ed..**.** ^The m
1a1c0 65 6d 6f 72 79 20 72 65 74 75 72 6e 65 64 20 62  emory returned b
1a1d0 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  y sqlite3_malloc
1a1e0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72  () and sqlite3_r
1a1f0 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61  ealloc().** is a
1a200 6c 77 61 79 73 20 61 6c 69 67 6e 65 64 20 74 6f  lways aligned to
1a210 20 61 74 20 6c 65 61 73 74 20 61 6e 20 38 20 62   at least an 8 b
1a220 79 74 65 20 62 6f 75 6e 64 61 72 79 2c 20 6f 72  yte boundary, or
1a230 20 74 6f 20 61 0a 2a 2a 20 34 20 62 79 74 65 20   to a.** 4 byte 
1a240 62 6f 75 6e 64 61 72 79 20 69 66 20 74 68 65 20  boundary if the 
1a250 5b 53 51 4c 49 54 45 5f 34 5f 42 59 54 45 5f 41  [SQLITE_4_BYTE_A
1a260 4c 49 47 4e 45 44 5f 4d 41 4c 4c 4f 43 5d 20 63  LIGNED_MALLOC] c
1a270 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f  ompile-time.** o
1a280 70 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a  ption is used..*
1a290 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69 74 65 20 76  *.** In SQLite v
1a2a0 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20 61 6e 64  ersion 3.5.0 and
1a2b0 20 33 2e 35 2e 31 2c 20 69 74 20 77 61 73 20 70   3.5.1, it was p
1a2c0 6f 73 73 69 62 6c 65 20 74 6f 20 64 65 66 69 6e  ossible to defin
1a2d0 65 0a 2a 2a 20 74 68 65 20 53 51 4c 49 54 45 5f  e.** the SQLITE_
1a2e0 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f  OMIT_MEMORY_ALLO
1a2f0 43 41 54 49 4f 4e 20 77 68 69 63 68 20 77 6f 75  CATION which wou
1a300 6c 64 20 63 61 75 73 65 20 74 68 65 20 62 75 69  ld cause the bui
1a310 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65  lt-in.** impleme
1a320 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 73 65  ntation of these
1a330 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20   routines to be 
1a340 6f 6d 69 74 74 65 64 2e 20 20 54 68 61 74 20 63  omitted.  That c
1a350 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20  apability.** is 
1a360 6e 6f 20 6c 6f 6e 67 65 72 20 70 72 6f 76 69 64  no longer provid
1a370 65 64 2e 20 20 4f 6e 6c 79 20 62 75 69 6c 74 2d  ed.  Only built-
1a380 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  in memory alloca
1a390 74 6f 72 73 20 63 61 6e 20 62 65 20 75 73 65 64  tors can be used
1a3a0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 57 69 6e 64  ..**.** The Wind
1a3b0 6f 77 73 20 4f 53 20 69 6e 74 65 72 66 61 63 65  ows OS interface
1a3c0 20 6c 61 79 65 72 20 63 61 6c 6c 73 0a 2a 2a 20   layer calls.** 
1a3d0 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f  the system mallo
1a3e0 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 64  c() and free() d
1a3f0 69 72 65 63 74 6c 79 20 77 68 65 6e 20 63 6f 6e  irectly when con
1a400 76 65 72 74 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e  verting.** filen
1a410 61 6d 65 73 20 62 65 74 77 65 65 6e 20 74 68 65  ames between the
1a420 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20   UTF-8 encoding 
1a430 75 73 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a  used by SQLite.*
1a440 2a 20 61 6e 64 20 77 68 61 74 65 76 65 72 20 66  * and whatever f
1a450 69 6c 65 6e 61 6d 65 20 65 6e 63 6f 64 69 6e 67  ilename encoding
1a460 20 69 73 20 75 73 65 64 20 62 79 20 74 68 65 20   is used by the 
1a470 70 61 72 74 69 63 75 6c 61 72 20 57 69 6e 64 6f  particular Windo
1a480 77 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61 74 69  ws.** installati
1a490 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f  on.  Memory allo
1a4a0 63 61 74 69 6f 6e 20 65 72 72 6f 72 73 20 61 72  cation errors ar
1a4b0 65 20 64 65 74 65 63 74 65 64 2c 20 62 75 74 0a  e detected, but.
1a4c0 2a 2a 20 74 68 65 79 20 61 72 65 20 72 65 70 6f  ** they are repo
1a4d0 72 74 65 64 20 62 61 63 6b 20 61 73 20 5b 53 51  rted back as [SQ
1a4e0 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f  LITE_CANTOPEN] o
1a4f0 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45  r.** [SQLITE_IOE
1a500 52 52 5d 20 72 61 74 68 65 72 20 74 68 61 6e 20  RR] rather than 
1a510 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a  [SQLITE_NOMEM]..
1a520 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65  **.** The pointe
1a530 72 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 5b  r arguments to [
1a540 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20  sqlite3_free()] 
1a550 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61  and [sqlite3_rea
1a560 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6d 75 73 74 20  lloc()].** must 
1a570 62 65 20 65 69 74 68 65 72 20 4e 55 4c 4c 20 6f  be either NULL o
1a580 72 20 65 6c 73 65 20 70 6f 69 6e 74 65 72 73 20  r else pointers 
1a590 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 20  obtained from a 
1a5a0 70 72 69 6f 72 0a 2a 2a 20 69 6e 76 6f 63 61 74  prior.** invocat
1a5b0 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  ion of [sqlite3_
1a5c0 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71  malloc()] or [sq
1a5d0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
1a5e0 20 74 68 61 74 20 68 61 76 65 0a 2a 2a 20 6e 6f   that have.** no
1a5f0 74 20 79 65 74 20 62 65 65 6e 20 72 65 6c 65 61  t yet been relea
1a600 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61  sed..**.** The a
1a610 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
1a620 6e 6f 74 20 72 65 61 64 20 6f 72 20 77 72 69 74  not read or writ
1a630 65 20 61 6e 79 20 70 61 72 74 20 6f 66 0a 2a 2a  e any part of.**
1a640 20 61 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f   a block of memo
1a650 72 79 20 61 66 74 65 72 20 69 74 20 68 61 73 20  ry after it has 
1a660 62 65 65 6e 20 72 65 6c 65 61 73 65 64 20 75 73  been released us
1a670 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
1a680 66 72 65 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69  free()] or [sqli
1a690 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e 0a  te3_realloc()]..
1a6a0 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  */.void *sqlite3
1a6b0 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76 6f  _malloc(int);.vo
1a6c0 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c  id *sqlite3_real
1a6d0 6c 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74 29 3b  loc(void*, int);
1a6e0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72  .void sqlite3_fr
1a6f0 65 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a  ee(void*);../*.*
1a700 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f  * CAPI3REF: Memo
1a710 72 79 20 41 6c 6c 6f 63 61 74 6f 72 20 53 74 61  ry Allocator Sta
1a720 74 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 53 51  tistics.**.** SQ
1a730 4c 69 74 65 20 70 72 6f 76 69 64 65 73 20 74 68  Lite provides th
1a740 65 73 65 20 74 77 6f 20 69 6e 74 65 72 66 61 63  ese two interfac
1a750 65 73 20 66 6f 72 20 72 65 70 6f 72 74 69 6e 67  es for reporting
1a760 20 6f 6e 20 74 68 65 20 73 74 61 74 75 73 0a 2a   on the status.*
1a770 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  * of the [sqlite
1a780 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71  3_malloc()], [sq
1a790 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2c 20 61  lite3_free()], a
1a7a0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  nd [sqlite3_real
1a7b0 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e  loc()].** routin
1a7c0 65 73 2c 20 77 68 69 63 68 20 66 6f 72 6d 20 74  es, which form t
1a7d0 68 65 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f  he built-in memo
1a7e0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75  ry allocation su
1a7f0 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 5e  bsystem..**.** ^
1a800 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  The [sqlite3_mem
1a810 6f 72 79 5f 75 73 65 64 28 29 5d 20 72 6f 75 74  ory_used()] rout
1a820 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ine returns the 
1a830 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 0a  number of bytes.
1a840 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 63 75 72  ** of memory cur
1a850 72 65 6e 74 6c 79 20 6f 75 74 73 74 61 6e 64 69  rently outstandi
1a860 6e 67 20 28 6d 61 6c 6c 6f 63 65 64 20 62 75 74  ng (malloced but
1a870 20 6e 6f 74 20 66 72 65 65 64 29 2e 0a 2a 2a 20   not freed)..** 
1a880 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65  ^The [sqlite3_me
1a890 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29  mory_highwater()
1a8a0 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ] routine return
1a8b0 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a  s the maximum.**
1a8c0 20 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74   value of [sqlit
1a8d0 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29  e3_memory_used()
1a8e0 5d 20 73 69 6e 63 65 20 74 68 65 20 68 69 67 68  ] since the high
1a8f0 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 77  -water mark.** w
1a900 61 73 20 6c 61 73 74 20 72 65 73 65 74 2e 20 20  as last reset.  
1a910 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65 74 75  ^The values retu
1a920 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  rned by [sqlite3
1a930 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20  _memory_used()] 
1a940 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
1a950 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
1a960 28 29 5d 20 69 6e 63 6c 75 64 65 20 61 6e 79 20  ()] include any 
1a970 6f 76 65 72 68 65 61 64 0a 2a 2a 20 61 64 64 65  overhead.** adde
1a980 64 20 62 79 20 53 51 4c 69 74 65 20 69 6e 20 69  d by SQLite in i
1a990 74 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ts implementatio
1a9a0 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61  n of [sqlite3_ma
1a9b0 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 62 75 74 20  lloc()],.** but 
1a9c0 6e 6f 74 20 6f 76 65 72 68 65 61 64 20 61 64 64  not overhead add
1a9d0 65 64 20 62 79 20 74 68 65 20 61 6e 79 20 75 6e  ed by the any un
1a9e0 64 65 72 6c 79 69 6e 67 20 73 79 73 74 65 6d 20  derlying system 
1a9f0 6c 69 62 72 61 72 79 0a 2a 2a 20 72 6f 75 74 69  library.** routi
1aa00 6e 65 73 20 74 68 61 74 20 5b 73 71 6c 69 74 65  nes that [sqlite
1aa10 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61 79 20  3_malloc()] may 
1aa20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  call..**.** ^The
1aa30 20 6d 65 6d 6f 72 79 20 68 69 67 68 2d 77 61 74   memory high-wat
1aa40 65 72 20 6d 61 72 6b 20 69 73 20 72 65 73 65 74  er mark is reset
1aa50 20 74 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20   to the current 
1aa60 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 5b 73 71 6c  value of.** [sql
1aa70 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64  ite3_memory_used
1aa80 28 29 5d 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20  ()] if and only 
1aa90 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  if the parameter
1aaa0 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
1aab0 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
1aac0 28 29 5d 20 69 73 20 74 72 75 65 2e 20 20 5e 54  ()] is true.  ^T
1aad0 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
1aae0 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33  d.** by [sqlite3
1aaf0 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
1ab00 72 28 31 29 5d 20 69 73 20 74 68 65 20 68 69 67  r(1)] is the hig
1ab10 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20  h-water mark.** 
1ab20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 72 65 73  prior to the res
1ab30 65 74 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69  et..*/.sqlite3_i
1ab40 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d  nt64 sqlite3_mem
1ab50 6f 72 79 5f 75 73 65 64 28 76 6f 69 64 29 3b 0a  ory_used(void);.
1ab60 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71  sqlite3_int64 sq
1ab70 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67  lite3_memory_hig
1ab80 68 77 61 74 65 72 28 69 6e 74 20 72 65 73 65 74  hwater(int reset
1ab90 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Flag);../*.** CA
1aba0 50 49 33 52 45 46 3a 20 50 73 65 75 64 6f 2d 52  PI3REF: Pseudo-R
1abb0 61 6e 64 6f 6d 20 4e 75 6d 62 65 72 20 47 65 6e  andom Number Gen
1abc0 65 72 61 74 6f 72 0a 2a 2a 0a 2a 2a 20 53 51 4c  erator.**.** SQL
1abd0 69 74 65 20 63 6f 6e 74 61 69 6e 73 20 61 20 68  ite contains a h
1abe0 69 67 68 2d 71 75 61 6c 69 74 79 20 70 73 65 75  igh-quality pseu
1abf0 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62 65 72  do-random number
1ac00 20 67 65 6e 65 72 61 74 6f 72 20 28 50 52 4e 47   generator (PRNG
1ac10 29 20 75 73 65 64 20 74 6f 0a 2a 2a 20 73 65 6c  ) used to.** sel
1ac20 65 63 74 20 72 61 6e 64 6f 6d 20 5b 52 4f 57 49  ect random [ROWI
1ac30 44 20 7c 20 52 4f 57 49 44 73 5d 20 77 68 65 6e  D | ROWIDs] when
1ac40 20 69 6e 73 65 72 74 69 6e 67 20 6e 65 77 20 72   inserting new r
1ac50 65 63 6f 72 64 73 20 69 6e 74 6f 20 61 20 74 61  ecords into a ta
1ac60 62 6c 65 20 74 68 61 74 0a 2a 2a 20 61 6c 72 65  ble that.** alre
1ac70 61 64 79 20 75 73 65 73 20 74 68 65 20 6c 61 72  ady uses the lar
1ac80 67 65 73 74 20 70 6f 73 73 69 62 6c 65 20 5b 52  gest possible [R
1ac90 4f 57 49 44 5d 2e 20 20 54 68 65 20 50 52 4e 47  OWID].  The PRNG
1aca0 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20 66 6f   is also used fo
1acb0 72 0a 2a 2a 20 74 68 65 20 62 75 69 6c 64 2d 69  r.** the build-i
1acc0 6e 20 72 61 6e 64 6f 6d 28 29 20 61 6e 64 20 72  n random() and r
1acd0 61 6e 64 6f 6d 62 6c 6f 62 28 29 20 53 51 4c 20  andomblob() SQL 
1ace0 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 68 69 73  functions.  This
1acf0 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77   interface allow
1ad00 73 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e  s.** application
1ad10 73 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20  s to access the 
1ad20 73 61 6d 65 20 50 52 4e 47 20 66 6f 72 20 6f 74  same PRNG for ot
1ad30 68 65 72 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2a  her purposes..**
1ad40 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 74  .** ^A call to t
1ad50 68 69 73 20 72 6f 75 74 69 6e 65 20 73 74 6f 72  his routine stor
1ad60 65 73 20 4e 20 62 79 74 65 73 20 6f 66 20 72 61  es N bytes of ra
1ad70 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 62 75  ndomness into bu
1ad80 66 66 65 72 20 50 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ffer P..**.** ^T
1ad90 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 74 68  he first time th
1ada0 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 69 6e  is routine is in
1adb0 76 6f 6b 65 64 20 28 65 69 74 68 65 72 20 69 6e  voked (either in
1adc0 74 65 72 6e 61 6c 6c 79 20 6f 72 20 62 79 0a 2a  ternally or by.*
1add0 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * the applicatio
1ade0 6e 29 20 74 68 65 20 50 52 4e 47 20 69 73 20 73  n) the PRNG is s
1adf0 65 65 64 65 64 20 75 73 69 6e 67 20 72 61 6e 64  eeded using rand
1ae00 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 0a  omness obtained.
1ae10 2a 2a 20 66 72 6f 6d 20 74 68 65 20 78 52 61 6e  ** from the xRan
1ae20 64 6f 6d 6e 65 73 73 20 6d 65 74 68 6f 64 20 6f  domness method o
1ae30 66 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73  f the default [s
1ae40 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
1ae50 63 74 2e 0a 2a 2a 20 5e 4f 6e 20 61 6c 6c 20 73  ct..** ^On all s
1ae60 75 62 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61  ubsequent invoca
1ae70 74 69 6f 6e 73 2c 20 74 68 65 20 70 73 65 75 64  tions, the pseud
1ae80 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69 73 20  o-randomness is 
1ae90 67 65 6e 65 72 61 74 65 64 0a 2a 2a 20 69 6e 74  generated.** int
1aea0 65 72 6e 61 6c 6c 79 20 61 6e 64 20 77 69 74 68  ernally and with
1aeb0 6f 75 74 20 72 65 63 6f 75 72 73 65 20 74 6f 20  out recourse to 
1aec0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  the [sqlite3_vfs
1aed0 5d 20 78 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a  ] xRandomness.**
1aee0 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 76 6f 69 64   method..*/.void
1aef0 20 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 6e   sqlite3_randomn
1af00 65 73 73 28 69 6e 74 20 4e 2c 20 76 6f 69 64 20  ess(int N, void 
1af10 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  *P);../*.** CAPI
1af20 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69  3REF: Compile-Ti
1af30 6d 65 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e  me Authorization
1af40 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a   Callbacks.**.**
1af50 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72   ^This routine r
1af60 65 67 69 73 74 65 72 73 20 61 6e 20 61 75 74 68  egisters an auth
1af70 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
1af80 77 69 74 68 20 61 20 70 61 72 74 69 63 75 6c 61  with a particula
1af90 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  r.** [database c
1afa0 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73 75 70 70  onnection], supp
1afb0 6c 69 65 64 20 69 6e 20 74 68 65 20 66 69 72 73  lied in the firs
1afc0 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e  t argument..** ^
1afd0 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  The authorizer c
1afe0 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
1aff0 65 64 20 61 73 20 53 51 4c 20 73 74 61 74 65 6d  ed as SQL statem
1b000 65 6e 74 73 20 61 72 65 20 62 65 69 6e 67 20 63  ents are being c
1b010 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73  ompiled.** by [s
1b020 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
1b030 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74  ] or its variant
1b040 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  s [sqlite3_prepa
1b050 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71  re_v2()],.** [sq
1b060 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
1b070 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
1b080 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e  prepare16_v2()].
1b090 20 20 5e 41 74 20 76 61 72 69 6f 75 73 0a 2a 2a    ^At various.**
1b0a0 20 70 6f 69 6e 74 73 20 64 75 72 69 6e 67 20 74   points during t
1b0b0 68 65 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 70  he compilation p
1b0c0 72 6f 63 65 73 73 2c 20 61 73 20 6c 6f 67 69 63  rocess, as logic
1b0d0 20 69 73 20 62 65 69 6e 67 20 63 72 65 61 74 65   is being create
1b0e0 64 0a 2a 2a 20 74 6f 20 70 65 72 66 6f 72 6d 20  d.** to perform 
1b0f0 76 61 72 69 6f 75 73 20 61 63 74 69 6f 6e 73 2c  various actions,
1b100 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
1b110 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
1b120 6b 65 64 20 74 6f 0a 2a 2a 20 73 65 65 20 69 66  ked to.** see if
1b130 20 74 68 6f 73 65 20 61 63 74 69 6f 6e 73 20 61   those actions a
1b140 72 65 20 61 6c 6c 6f 77 65 64 2e 20 20 5e 54 68  re allowed.  ^Th
1b150 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
1b160 6c 62 61 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20  lback should.** 
1b170 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f  return [SQLITE_O
1b180 4b 5d 20 74 6f 20 61 6c 6c 6f 77 20 74 68 65 20  K] to allow the 
1b190 61 63 74 69 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f  action, [SQLITE_
1b1a0 49 47 4e 4f 52 45 5d 20 74 6f 20 64 69 73 61 6c  IGNORE] to disal
1b1b0 6c 6f 77 20 74 68 65 0a 2a 2a 20 73 70 65 63 69  low the.** speci
1b1c0 66 69 63 20 61 63 74 69 6f 6e 20 62 75 74 20 61  fic action but a
1b1d0 6c 6c 6f 77 20 74 68 65 20 53 51 4c 20 73 74 61  llow the SQL sta
1b1e0 74 65 6d 65 6e 74 20 74 6f 20 63 6f 6e 74 69 6e  tement to contin
1b1f0 75 65 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70  ue to be.** comp
1b200 69 6c 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45  iled, or [SQLITE
1b210 5f 44 45 4e 59 5d 20 74 6f 20 63 61 75 73 65 20  _DENY] to cause 
1b220 74 68 65 20 65 6e 74 69 72 65 20 53 51 4c 20 73  the entire SQL s
1b230 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 0a 2a  tatement to be.*
1b240 2a 20 72 65 6a 65 63 74 65 64 20 77 69 74 68 20  * rejected with 
1b250 61 6e 20 65 72 72 6f 72 2e 20 20 5e 49 66 20 74  an error.  ^If t
1b260 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
1b270 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a  llback returns.*
1b280 2a 20 61 6e 79 20 76 61 6c 75 65 20 6f 74 68 65  * any value othe
1b290 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 49  r than [SQLITE_I
1b2a0 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f  GNORE], [SQLITE_
1b2b0 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  OK], or [SQLITE_
1b2c0 44 45 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20 74 68  DENY].** then th
1b2d0 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  e [sqlite3_prepa
1b2e0 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69  re_v2()] or equi
1b2f0 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74  valent call that
1b300 20 74 72 69 67 67 65 72 65 64 0a 2a 2a 20 74 68   triggered.** th
1b310 65 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c  e authorizer wil
1b320 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65  l fail with an e
1b330 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a  rror message..**
1b340 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 63 61 6c  .** When the cal
1b350 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53  lback returns [S
1b360 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 61 74 20  QLITE_OK], that 
1b370 6d 65 61 6e 73 20 74 68 65 20 6f 70 65 72 61 74  means the operat
1b380 69 6f 6e 0a 2a 2a 20 72 65 71 75 65 73 74 65 64  ion.** requested
1b390 20 69 73 20 6f 6b 2e 20 20 5e 57 68 65 6e 20 74   is ok.  ^When t
1b3a0 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  he callback retu
1b3b0 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59  rns [SQLITE_DENY
1b3c0 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ], the.** [sqlit
1b3d0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
1b3e0 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63   or equivalent c
1b3f0 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72  all that trigger
1b400 65 64 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72  ed the.** author
1b410 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77  izer will fail w
1b420 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73  ith an error mes
1b430 73 61 67 65 20 65 78 70 6c 61 69 6e 69 6e 67 20  sage explaining 
1b440 74 68 61 74 0a 2a 2a 20 61 63 63 65 73 73 20 69  that.** access i
1b450 73 20 64 65 6e 69 65 64 2e 20 0a 2a 2a 0a 2a 2a  s denied. .**.**
1b460 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 72 61   ^The first para
1b470 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74  meter to the aut
1b480 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1b490 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68   is a copy of th
1b4a0 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d  e third.** param
1b4b0 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69  eter to the sqli
1b4c0 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
1b4d0 65 72 28 29 20 69 6e 74 65 72 66 61 63 65 2e 20  er() interface. 
1b4e0 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61  ^The second para
1b4f0 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20  meter.** to the 
1b500 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69  callback is an i
1b510 6e 74 65 67 65 72 20 5b 53 51 4c 49 54 45 5f 43  nteger [SQLITE_C
1b520 4f 50 59 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64  OPY | action cod
1b530 65 5d 20 74 68 61 74 20 73 70 65 63 69 66 69 65  e] that specifie
1b540 73 0a 2a 2a 20 74 68 65 20 70 61 72 74 69 63 75  s.** the particu
1b550 6c 61 72 20 61 63 74 69 6f 6e 20 74 6f 20 62 65  lar action to be
1b560 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 5e 54 68   authorized. ^Th
1b570 65 20 74 68 69 72 64 20 74 68 72 6f 75 67 68 20  e third through 
1b580 73 69 78 74 68 20 70 61 72 61 6d 65 74 65 72 73  sixth parameters
1b590 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  .** to the callb
1b5a0 61 63 6b 20 61 72 65 20 7a 65 72 6f 2d 74 65 72  ack are zero-ter
1b5b0 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20  minated strings 
1b5c0 74 68 61 74 20 63 6f 6e 74 61 69 6e 20 61 64 64  that contain add
1b5d0 69 74 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74 61 69  itional.** detai
1b5e0 6c 73 20 61 62 6f 75 74 20 74 68 65 20 61 63 74  ls about the act
1b5f0 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72  ion to be author
1b600 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ized..**.** ^If 
1b610 74 68 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20  the action code 
1b620 69 73 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d  is [SQLITE_READ]
1b630 0a 2a 2a 20 61 6e 64 20 74 68 65 20 63 61 6c 6c  .** and the call
1b640 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51  back returns [SQ
1b650 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65  LITE_IGNORE] the
1b660 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  n the.** [prepar
1b670 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 73 74  ed statement] st
1b680 61 74 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73 74  atement is const
1b690 72 75 63 74 65 64 20 74 6f 20 73 75 62 73 74 69  ructed to substi
1b6a0 74 75 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76  tute.** a NULL v
1b6b0 61 6c 75 65 20 69 6e 20 70 6c 61 63 65 20 6f 66  alue in place of
1b6c0 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d   the table colum
1b6d0 6e 20 74 68 61 74 20 77 6f 75 6c 64 20 68 61 76  n that would hav
1b6e0 65 0a 2a 2a 20 62 65 65 6e 20 72 65 61 64 20 69  e.** been read i
1b6f0 66 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 68 61  f [SQLITE_OK] ha
1b700 64 20 62 65 65 6e 20 72 65 74 75 72 6e 65 64 2e  d been returned.
1b710 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 47    The [SQLITE_IG
1b720 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74 75 72 6e 20  NORE].** return 
1b730 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 64  can be used to d
1b740 65 6e 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64  eny an untrusted
1b750 20 75 73 65 72 20 61 63 63 65 73 73 20 74 6f 20   user access to 
1b760 69 6e 64 69 76 69 64 75 61 6c 0a 2a 2a 20 63 6f  individual.** co
1b770 6c 75 6d 6e 73 20 6f 66 20 61 20 74 61 62 6c 65  lumns of a table
1b780 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74  ..** ^If the act
1b790 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c  ion code is [SQL
1b7a0 49 54 45 5f 44 45 4c 45 54 45 5d 20 61 6e 64 20  ITE_DELETE] and 
1b7b0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  the callback ret
1b7c0 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  urns.** [SQLITE_
1b7d0 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65  IGNORE] then the
1b7e0 20 5b 44 45 4c 45 54 45 5d 20 6f 70 65 72 61 74   [DELETE] operat
1b7f0 69 6f 6e 20 70 72 6f 63 65 65 64 73 20 62 75 74  ion proceeds but
1b800 20 74 68 65 0a 2a 2a 20 5b 74 72 75 6e 63 61 74   the.** [truncat
1b810 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 20  e optimization] 
1b820 69 73 20 64 69 73 61 62 6c 65 64 20 61 6e 64 20  is disabled and 
1b830 61 6c 6c 20 72 6f 77 73 20 61 72 65 20 64 65 6c  all rows are del
1b840 65 74 65 64 20 69 6e 64 69 76 69 64 75 61 6c 6c  eted individuall
1b850 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68  y..**.** An auth
1b860 6f 72 69 7a 65 72 20 69 73 20 75 73 65 64 20 77  orizer is used w
1b870 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  hen [sqlite3_pre
1b880 70 61 72 65 20 7c 20 70 72 65 70 61 72 69 6e 67  pare | preparing
1b890 5d 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65  ].** SQL stateme
1b8a0 6e 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72  nts from an untr
1b8b0 75 73 74 65 64 20 73 6f 75 72 63 65 2c 20 74 6f  usted source, to
1b8c0 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65   ensure that the
1b8d0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a   SQL statements.
1b8e0 2a 2a 20 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f  ** do not try to
1b8f0 20 61 63 63 65 73 73 20 64 61 74 61 20 74 68 65   access data the
1b900 79 20 61 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65  y are not allowe
1b910 64 20 74 6f 20 73 65 65 2c 20 6f 72 20 74 68 61  d to see, or tha
1b920 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a  t they do not.**
1b930 20 74 72 79 20 74 6f 20 65 78 65 63 75 74 65 20   try to execute 
1b940 6d 61 6c 69 63 69 6f 75 73 20 73 74 61 74 65 6d  malicious statem
1b950 65 6e 74 73 20 74 68 61 74 20 64 61 6d 61 67 65  ents that damage
1b960 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 20 20   the database.  
1b970 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20  For.** example, 
1b980 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  an application m
1b990 61 79 20 61 6c 6c 6f 77 20 61 20 75 73 65 72 20  ay allow a user 
1b9a0 74 6f 20 65 6e 74 65 72 20 61 72 62 69 74 72 61  to enter arbitra
1b9b0 72 79 0a 2a 2a 20 53 51 4c 20 71 75 65 72 69 65  ry.** SQL querie
1b9c0 73 20 66 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e  s for evaluation
1b9d0 20 62 79 20 61 20 64 61 74 61 62 61 73 65 2e 20   by a database. 
1b9e0 20 42 75 74 20 74 68 65 20 61 70 70 6c 69 63 61   But the applica
1b9f0 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74  tion does.** not
1ba00 20 77 61 6e 74 20 74 68 65 20 75 73 65 72 20 74   want the user t
1ba10 6f 20 62 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b  o be able to mak
1ba20 65 20 61 72 62 69 74 72 61 72 79 20 63 68 61 6e  e arbitrary chan
1ba30 67 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61  ges to the.** da
1ba40 74 61 62 61 73 65 2e 20 20 41 6e 20 61 75 74 68  tabase.  An auth
1ba50 6f 72 69 7a 65 72 20 63 6f 75 6c 64 20 74 68 65  orizer could the
1ba60 6e 20 62 65 20 70 75 74 20 69 6e 20 70 6c 61 63  n be put in plac
1ba70 65 20 77 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75  e while the.** u
1ba80 73 65 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 20  ser-entered SQL 
1ba90 69 73 20 62 65 69 6e 67 20 5b 73 71 6c 69 74 65  is being [sqlite
1baa0 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70  3_prepare | prep
1bab0 61 72 65 64 5d 20 74 68 61 74 0a 2a 2a 20 64 69  ared] that.** di
1bac0 73 61 6c 6c 6f 77 73 20 65 76 65 72 79 74 68 69  sallows everythi
1bad0 6e 67 20 65 78 63 65 70 74 20 5b 53 45 4c 45 43  ng except [SELEC
1bae0 54 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a  T] statements..*
1baf0 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e  *.** Application
1bb00 73 20 74 68 61 74 20 6e 65 65 64 20 74 6f 20 70  s that need to p
1bb10 72 6f 63 65 73 73 20 53 51 4c 20 66 72 6f 6d 20  rocess SQL from 
1bb20 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63 65  untrusted source
1bb30 73 0a 2a 2a 20 6d 69 67 68 74 20 61 6c 73 6f 20  s.** might also 
1bb40 63 6f 6e 73 69 64 65 72 20 6c 6f 77 65 72 69 6e  consider lowerin
1bb50 67 20 72 65 73 6f 75 72 63 65 20 6c 69 6d 69 74  g resource limit
1bb60 73 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  s using [sqlite3
1bb70 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 64  _limit()].** and
1bb80 20 6c 69 6d 69 74 69 6e 67 20 64 61 74 61 62 61   limiting databa
1bb90 73 65 20 73 69 7a 65 20 75 73 69 6e 67 20 74 68  se size using th
1bba0 65 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e  e [max_page_coun
1bbb0 74 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 69  t] [PRAGMA].** i
1bbc0 6e 20 61 64 64 69 74 69 6f 6e 20 74 6f 20 75 73  n addition to us
1bbd0 69 6e 67 20 61 6e 20 61 75 74 68 6f 72 69 7a 65  ing an authorize
1bbe0 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79 20  r..**.** ^(Only 
1bbf0 61 20 73 69 6e 67 6c 65 20 61 75 74 68 6f 72 69  a single authori
1bc00 7a 65 72 20 63 61 6e 20 62 65 20 69 6e 20 70 6c  zer can be in pl
1bc10 61 63 65 20 6f 6e 20 61 20 64 61 74 61 62 61 73  ace on a databas
1bc20 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e connection.** 
1bc30 61 74 20 61 20 74 69 6d 65 2e 20 20 45 61 63 68  at a time.  Each
1bc40 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
1bc50 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20  _set_authorizer 
1bc60 6f 76 65 72 72 69 64 65 73 20 74 68 65 0a 2a 2a  overrides the.**
1bc70 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e 29   previous call.)
1bc80 5e 20 20 5e 44 69 73 61 62 6c 65 20 74 68 65 20  ^  ^Disable the 
1bc90 61 75 74 68 6f 72 69 7a 65 72 20 62 79 20 69 6e  authorizer by in
1bca0 73 74 61 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c 20  stalling a NULL 
1bcb0 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65  callback..** The
1bcc0 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 64   authorizer is d
1bcd0 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75  isabled by defau
1bce0 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75  lt..**.** The au
1bcf0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1bd00 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e  k must not do an
1bd10 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c  ything that will
1bd20 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64   modify.** the d
1bd30 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1bd40 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20  on that invoked 
1bd50 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
1bd60 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65  allback..** Note
1bd70 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70   that [sqlite3_p
1bd80 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64  repare_v2()] and
1bd90 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
1bda0 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68  ] both modify th
1bdb0 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  eir.** database 
1bdc0 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20  connections for 
1bdd0 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22  the meaning of "
1bde0 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20  modify" in this 
1bdf0 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a  paragraph..**.**
1be00 20 5e 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f   ^When [sqlite3_
1be10 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 69 73  prepare_v2()] is
1be20 20 75 73 65 64 20 74 6f 20 70 72 65 70 61 72 65   used to prepare
1be30 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 20 74 68   a statement, th
1be40 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 6d  e.** statement m
1be50 69 67 68 74 20 62 65 20 72 65 2d 70 72 65 70 61  ight be re-prepa
1be60 72 65 64 20 64 75 72 69 6e 67 20 5b 73 71 6c 69  red during [sqli
1be70 74 65 33 5f 73 74 65 70 28 29 5d 20 64 75 65 20  te3_step()] due 
1be80 74 6f 20 61 20 0a 2a 2a 20 73 63 68 65 6d 61 20  to a .** schema 
1be90 63 68 61 6e 67 65 2e 20 20 48 65 6e 63 65 2c 20  change.  Hence, 
1bea0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
1beb0 73 68 6f 75 6c 64 20 65 6e 73 75 72 65 20 74 68  should ensure th
1bec0 61 74 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 63  at the.** correc
1bed0 74 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  t authorizer cal
1bee0 6c 62 61 63 6b 20 72 65 6d 61 69 6e 73 20 69 6e  lback remains in
1bef0 20 70 6c 61 63 65 20 64 75 72 69 6e 67 20 74 68   place during th
1bf00 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  e [sqlite3_step(
1bf10 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20  )]..**.** ^Note 
1bf20 74 68 61 74 20 74 68 65 20 61 75 74 68 6f 72 69  that the authori
1bf30 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
1bf40 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72  invoked only dur
1bf50 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
1bf60 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74  prepare()] or it
1bf70 73 20 76 61 72 69 61 6e 74 73 2e 20 20 41 75 74  s variants.  Aut
1bf80 68 6f 72 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f  horization is no
1bf90 74 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 64  t.** performed d
1bfa0 75 72 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20  uring statement 
1bfb0 65 76 61 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73  evaluation in [s
1bfc0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20  qlite3_step()], 
1bfd0 75 6e 6c 65 73 73 0a 2a 2a 20 61 73 20 73 74 61  unless.** as sta
1bfe0 74 65 64 20 69 6e 20 74 68 65 20 70 72 65 76 69  ted in the previ
1bff0 6f 75 73 20 70 61 72 61 67 72 61 70 68 2c 20 73  ous paragraph, s
1c000 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e  qlite3_step() in
1c010 76 6f 6b 65 73 0a 2a 2a 20 73 71 6c 69 74 65 33  vokes.** sqlite3
1c020 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20 74 6f  _prepare_v2() to
1c030 20 72 65 70 72 65 70 61 72 65 20 61 20 73 74 61   reprepare a sta
1c040 74 65 6d 65 6e 74 20 61 66 74 65 72 20 61 20 73  tement after a s
1c050 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 0a 2a 2f  chema change..*/
1c060 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 65 74  .int sqlite3_set
1c070 5f 61 75 74 68 6f 72 69 7a 65 72 28 0a 20 20 73  _authorizer(.  s
1c080 71 6c 69 74 65 33 2a 2c 0a 20 20 69 6e 74 20 28  qlite3*,.  int (
1c090 2a 78 41 75 74 68 29 28 76 6f 69 64 2a 2c 69 6e  *xAuth)(void*,in
1c0a0 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f  t,const char*,co
1c0b0 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20  nst char*,const 
1c0c0 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72  char*,const char
1c0d0 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70 55 73 65  *),.  void *pUse
1c0e0 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  rData.);../*.** 
1c0f0 43 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72  CAPI3REF: Author
1c100 69 7a 65 72 20 52 65 74 75 72 6e 20 43 6f 64 65  izer Return Code
1c110 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c  s.**.** The [sql
1c120 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
1c130 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72  zer | authorizer
1c140 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
1c150 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72 65 74 75  on] must.** retu
1c160 72 6e 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54  rn either [SQLIT
1c170 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66 20  E_OK] or one of 
1c180 74 68 65 73 65 20 74 77 6f 20 63 6f 6e 73 74 61  these two consta
1c190 6e 74 73 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20  nts in order.** 
1c1a0 74 6f 20 73 69 67 6e 61 6c 20 53 51 4c 69 74 65  to signal SQLite
1c1b0 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
1c1c0 74 68 65 20 61 63 74 69 6f 6e 20 69 73 20 70 65  the action is pe
1c1d0 72 6d 69 74 74 65 64 2e 20 20 53 65 65 20 74 68  rmitted.  See th
1c1e0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65  e.** [sqlite3_se
1c1f0 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61  t_authorizer | a
1c200 75 74 68 6f 72 69 7a 65 72 20 64 6f 63 75 6d 65  uthorizer docume
1c210 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 61 64 64  ntation] for add
1c220 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72  itional.** infor
1c230 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 4e 6f  mation..**.** No
1c240 74 65 20 74 68 61 74 20 53 51 4c 49 54 45 5f 49  te that SQLITE_I
1c250 47 4e 4f 52 45 20 69 73 20 61 6c 73 6f 20 75 73  GNORE is also us
1c260 65 64 20 61 73 20 61 20 5b 53 51 4c 49 54 45 5f  ed as a [SQLITE_
1c270 52 4f 4c 4c 42 41 43 4b 20 7c 20 72 65 74 75 72  ROLLBACK | retur
1c280 6e 20 63 6f 64 65 5d 0a 2a 2a 20 66 72 6f 6d 20  n code].** from 
1c290 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 74 61  the [sqlite3_vta
1c2a0 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28 29 5d  b_on_conflict()]
1c2b0 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 23   interface..*/.#
1c2c0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45  define SQLITE_DE
1c2d0 4e 59 20 20 20 31 20 20 20 2f 2a 20 41 62 6f 72  NY   1   /* Abor
1c2e0 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  t the SQL statem
1c2f0 65 6e 74 20 77 69 74 68 20 61 6e 20 65 72 72 6f  ent with an erro
1c300 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  r */.#define SQL
1c310 49 54 45 5f 49 47 4e 4f 52 45 20 32 20 20 20 2f  ITE_IGNORE 2   /
1c320 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77 20 61 63  * Don't allow ac
1c330 63 65 73 73 2c 20 62 75 74 20 64 6f 6e 27 74 20  cess, but don't 
1c340 67 65 6e 65 72 61 74 65 20 61 6e 20 65 72 72 6f  generate an erro
1c350 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  r */../*.** CAPI
1c360 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72  3REF: Authorizer
1c370 20 41 63 74 69 6f 6e 20 43 6f 64 65 73 0a 2a 2a   Action Codes.**
1c380 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33  .** The [sqlite3
1c390 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28  _set_authorizer(
1c3a0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 67  )] interface reg
1c3b0 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63  isters a callbac
1c3c0 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68  k function.** th
1c3d0 61 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f  at is invoked to
1c3e0 20 61 75 74 68 6f 72 69 7a 65 20 63 65 72 74 61   authorize certa
1c3f0 69 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  in SQL statement
1c400 20 61 63 74 69 6f 6e 73 2e 20 20 54 68 65 0a 2a   actions.  The.*
1c410 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  * second paramet
1c420 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  er to the callba
1c430 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  ck is an integer
1c440 20 63 6f 64 65 20 74 68 61 74 20 73 70 65 63 69   code that speci
1c450 66 69 65 73 0a 2a 2a 20 77 68 61 74 20 61 63 74  fies.** what act
1c460 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 61 75 74  ion is being aut
1c470 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 73 65 20  horized.  These 
1c480 61 72 65 20 74 68 65 20 69 6e 74 65 67 65 72 20  are the integer 
1c490 61 63 74 69 6f 6e 20 63 6f 64 65 73 20 74 68 61  action codes tha
1c4a0 74 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69  t.** the authori
1c4b0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 61 79  zer callback may
1c4c0 20 62 65 20 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a   be passed..**.*
1c4d0 2a 20 54 68 65 73 65 20 61 63 74 69 6f 6e 20 63  * These action c
1c4e0 6f 64 65 20 76 61 6c 75 65 73 20 73 69 67 6e 69  ode values signi
1c4f0 66 79 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20  fy what kind of 
1c500 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 74 6f 20  operation is to 
1c510 62 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 64  be.** authorized
1c520 2e 20 20 54 68 65 20 33 72 64 20 61 6e 64 20 34  .  The 3rd and 4
1c530 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f  th parameters to
1c540 20 74 68 65 20 61 75 74 68 6f 72 69 7a 61 74 69   the authorizati
1c550 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66  on.** callback f
1c560 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20  unction will be 
1c570 70 61 72 61 6d 65 74 65 72 73 20 6f 72 20 4e 55  parameters or NU
1c580 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20  LL depending on 
1c590 77 68 69 63 68 20 6f 66 20 74 68 65 73 65 0a 2a  which of these.*
1c5a0 2a 20 63 6f 64 65 73 20 69 73 20 75 73 65 64 20  * codes is used 
1c5b0 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  as the second pa
1c5c0 72 61 6d 65 74 65 72 2e 20 20 5e 28 54 68 65 20  rameter.  ^(The 
1c5d0 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  5th parameter to
1c5e0 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a   the.** authoriz
1c5f0 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74  er callback is t
1c600 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64  he name of the d
1c610 61 74 61 62 61 73 65 20 28 22 6d 61 69 6e 22 2c  atabase ("main",
1c620 20 22 74 65 6d 70 22 2c 0a 2a 2a 20 65 74 63 2e   "temp",.** etc.
1c630 29 20 69 66 20 61 70 70 6c 69 63 61 62 6c 65 2e  ) if applicable.
1c640 29 5e 20 20 5e 54 68 65 20 36 74 68 20 70 61 72  )^  ^The 6th par
1c650 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75  ameter to the au
1c660 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1c670 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65  k.** is the name
1c680 20 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f   of the inner-mo
1c690 73 74 20 74 72 69 67 67 65 72 20 6f 72 20 76 69  st trigger or vi
1c6a0 65 77 20 74 68 61 74 20 69 73 20 72 65 73 70 6f  ew that is respo
1c6b0 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 74 68  nsible for.** th
1c6c0 65 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74  e access attempt
1c6d0 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 69 73   or NULL if this
1c6e0 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20   access attempt 
1c6f0 69 73 20 64 69 72 65 63 74 6c 79 20 66 72 6f 6d  is directly from
1c700 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51  .** top-level SQ
1c710 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a  L code..*/./****
1c720 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1c730 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1c740 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a  ******* 3rd ****
1c750 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a  ******** 4th ***
1c760 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e  ********/.#defin
1c770 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
1c780 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 31  INDEX          1
1c790 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65     /* Index Name
1c7a0 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65        Table Name
1c7b0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1c7c0 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
1c7d0 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 32 20  ABLE          2 
1c7e0 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
1c7f0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
1c800 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1c810 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45  SQLITE_CREATE_TE
1c820 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 33 20 20  MP_INDEX     3  
1c830 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20   /* Index Name  
1c840 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
1c850 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1c860 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d  QLITE_CREATE_TEM
1c870 50 5f 54 41 42 4c 45 20 20 20 20 20 34 20 20 20  P_TABLE     4   
1c880 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
1c890 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1c8a0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1c8b0 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50  LITE_CREATE_TEMP
1c8c0 5f 54 52 49 47 47 45 52 20 20 20 35 20 20 20 2f  _TRIGGER   5   /
1c8d0 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20  * Trigger Name  
1c8e0 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
1c8f0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1c900 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f  ITE_CREATE_TEMP_
1c910 56 49 45 57 20 20 20 20 20 20 36 20 20 20 2f 2a  VIEW      6   /*
1c920 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20   View Name      
1c930 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1c940 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1c950 54 45 5f 43 52 45 41 54 45 5f 54 52 49 47 47 45  TE_CREATE_TRIGGE
1c960 52 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20  R        7   /* 
1c970 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20  Trigger Name    
1c980 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1c990 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1c9a0 45 5f 43 52 45 41 54 45 5f 56 49 45 57 20 20 20  E_CREATE_VIEW   
1c9b0 20 20 20 20 20 20 20 20 38 20 20 20 2f 2a 20 56          8   /* V
1c9c0 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e  iew Name       N
1c9d0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1c9e0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1c9f0 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20  _DELETE         
1ca00 20 20 20 20 20 20 20 39 20 20 20 2f 2a 20 54 61         9   /* Ta
1ca10 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
1ca20 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
1ca30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1ca40 44 52 4f 50 5f 49 4e 44 45 58 20 20 20 20 20 20  DROP_INDEX      
1ca50 20 20 20 20 20 31 30 20 20 20 2f 2a 20 49 6e 64       10   /* Ind
1ca60 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62  ex Name      Tab
1ca70 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
1ca80 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1ca90 52 4f 50 5f 54 41 42 4c 45 20 20 20 20 20 20 20  ROP_TABLE       
1caa0 20 20 20 20 31 31 20 20 20 2f 2a 20 54 61 62 6c      11   /* Tabl
1cab0 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
1cac0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1cad0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
1cae0 4f 50 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20  OP_TEMP_INDEX   
1caf0 20 20 20 31 32 20 20 20 2f 2a 20 49 6e 64 65 78     12   /* Index
1cb00 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65   Name      Table
1cb10 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
1cb20 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
1cb30 50 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20  P_TEMP_TABLE    
1cb40 20 20 31 33 20 20 20 2f 2a 20 54 61 62 6c 65 20    13   /* Table 
1cb50 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
1cb60 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
1cb70 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
1cb80 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20  _TEMP_TRIGGER   
1cb90 20 31 34 20 20 20 2f 2a 20 54 72 69 67 67 65 72   14   /* Trigger
1cba0 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e   Name    Table N
1cbb0 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
1cbc0 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
1cbd0 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20 20  TEMP_VIEW       
1cbe0 31 35 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d  15   /* View Nam
1cbf0 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  e       NULL    
1cc00 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
1cc10 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
1cc20 52 49 47 47 45 52 20 20 20 20 20 20 20 20 20 31  RIGGER         1
1cc30 36 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e  6   /* Trigger N
1cc40 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  ame    Table Nam
1cc50 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
1cc60 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 49  e SQLITE_DROP_VI
1cc70 45 57 20 20 20 20 20 20 20 20 20 20 20 20 31 37  EW            17
1cc80 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20     /* View Name 
1cc90 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1cca0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1ccb0 20 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 20 20   SQLITE_INSERT  
1ccc0 20 20 20 20 20 20 20 20 20 20 20 20 20 31 38 20               18 
1ccd0 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
1cce0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
1ccf0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1cd00 53 51 4c 49 54 45 5f 50 52 41 47 4d 41 20 20 20  SQLITE_PRAGMA   
1cd10 20 20 20 20 20 20 20 20 20 20 20 20 31 39 20 20              19  
1cd20 20 2f 2a 20 50 72 61 67 6d 61 20 4e 61 6d 65 20   /* Pragma Name 
1cd30 20 20 20 20 31 73 74 20 61 72 67 20 6f 72 20 4e      1st arg or N
1cd40 55 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ULL */.#define S
1cd50 51 4c 49 54 45 5f 52 45 41 44 20 20 20 20 20 20  QLITE_READ      
1cd60 20 20 20 20 20 20 20 20 20 20 20 32 30 20 20 20             20   
1cd70 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
1cd80 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20     Column Name  
1cd90 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1cda0 4c 49 54 45 5f 53 45 4c 45 43 54 20 20 20 20 20  LITE_SELECT     
1cdb0 20 20 20 20 20 20 20 20 20 20 32 31 20 20 20 2f            21   /
1cdc0 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20  * NULL          
1cdd0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1cde0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1cdf0 49 54 45 5f 54 52 41 4e 53 41 43 54 49 4f 4e 20  ITE_TRANSACTION 
1ce00 20 20 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a           22   /*
1ce10 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20   Operation      
1ce20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1ce30 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1ce40 54 45 5f 55 50 44 41 54 45 20 20 20 20 20 20 20  TE_UPDATE       
1ce50 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20          23   /* 
1ce60 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1ce70 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20  Column Name     
1ce80 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1ce90 45 5f 41 54 54 41 43 48 20 20 20 20 20 20 20 20  E_ATTACH        
1cea0 20 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20 46         24   /* F
1ceb0 69 6c 65 6e 61 6d 65 20 20 20 20 20 20 20 20 4e  ilename        N
1cec0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1ced0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1cee0 5f 44 45 54 41 43 48 20 20 20 20 20 20 20 20 20  _DETACH         
1cef0 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20 44 61        25   /* Da
1cf00 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20 4e 55  tabase Name   NU
1cf10 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
1cf20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1cf30 41 4c 54 45 52 5f 54 41 42 4c 45 20 20 20 20 20  ALTER_TABLE     
1cf40 20 20 20 20 20 32 36 20 20 20 2f 2a 20 44 61 74       26   /* Dat
1cf50 61 62 61 73 65 20 4e 61 6d 65 20 20 20 54 61 62  abase Name   Tab
1cf60 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
1cf70 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
1cf80 45 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20  EINDEX          
1cf90 20 20 20 20 32 37 20 20 20 2f 2a 20 49 6e 64 65      27   /* Inde
1cfa0 78 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  x Name      NULL
1cfb0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1cfc0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e  define SQLITE_AN
1cfd0 41 4c 59 5a 45 20 20 20 20 20 20 20 20 20 20 20  ALYZE           
1cfe0 20 20 20 32 38 20 20 20 2f 2a 20 54 61 62 6c 65     28   /* Table
1cff0 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
1d000 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
1d010 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
1d020 41 54 45 5f 56 54 41 42 4c 45 20 20 20 20 20 20  ATE_VTABLE      
1d030 20 20 32 39 20 20 20 2f 2a 20 54 61 62 6c 65 20    29   /* Table 
1d040 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65  Name      Module
1d050 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65   Name     */.#de
1d060 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
1d070 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 20 20  _VTABLE         
1d080 20 33 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   30   /* Table N
1d090 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20  ame      Module 
1d0a0 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66  Name     */.#def
1d0b0 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4e 43 54  ine SQLITE_FUNCT
1d0c0 49 4f 4e 20 20 20 20 20 20 20 20 20 20 20 20 20  ION             
1d0d0 33 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20  31   /* NULL    
1d0e0 20 20 20 20 20 20 20 20 46 75 6e 63 74 69 6f 6e          Function
1d0f0 20 4e 61 6d 65 20 20 20 2a 2f 0a 23 64 65 66 69   Name   */.#defi
1d100 6e 65 20 53 51 4c 49 54 45 5f 53 41 56 45 50 4f  ne SQLITE_SAVEPO
1d110 49 4e 54 20 20 20 20 20 20 20 20 20 20 20 20 33  INT            3
1d120 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e  2   /* Operation
1d130 20 20 20 20 20 20 20 53 61 76 65 70 6f 69 6e 74         Savepoint
1d140 20 4e 61 6d 65 20 20 2a 2f 0a 23 64 65 66 69 6e   Name  */.#defin
1d150 65 20 53 51 4c 49 54 45 5f 43 4f 50 59 20 20 20  e SQLITE_COPY   
1d160 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
1d170 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20     /* No longer 
1d180 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  used */../*.** C
1d190 41 50 49 33 52 45 46 3a 20 54 72 61 63 69 6e 67  API3REF: Tracing
1d1a0 20 41 6e 64 20 50 72 6f 66 69 6c 69 6e 67 20 46   And Profiling F
1d1b0 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54  unctions.**.** T
1d1c0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65  hese routines re
1d1d0 67 69 73 74 65 72 20 63 61 6c 6c 62 61 63 6b 20  gister callback 
1d1e0 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 63  functions that c
1d1f0 61 6e 20 62 65 20 75 73 65 64 20 66 6f 72 0a 2a  an be used for.*
1d200 2a 20 74 72 61 63 69 6e 67 20 61 6e 64 20 70 72  * tracing and pr
1d210 6f 66 69 6c 69 6e 67 20 74 68 65 20 65 78 65 63  ofiling the exec
1d220 75 74 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61  ution of SQL sta
1d230 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e  tements..**.** ^
1d240 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  The callback fun
1d250 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64  ction registered
1d260 20 62 79 20 73 71 6c 69 74 65 33 5f 74 72 61 63   by sqlite3_trac
1d270 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 61  e() is invoked a
1d280 74 0a 2a 2a 20 76 61 72 69 6f 75 73 20 74 69 6d  t.** various tim
1d290 65 73 20 77 68 65 6e 20 61 6e 20 53 51 4c 20 73  es when an SQL s
1d2a0 74 61 74 65 6d 65 6e 74 20 69 73 20 62 65 69 6e  tatement is bein
1d2b0 67 20 72 75 6e 20 62 79 20 5b 73 71 6c 69 74 65  g run by [sqlite
1d2c0 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 5e 54  3_step()]..** ^T
1d2d0 68 65 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65  he sqlite3_trace
1d2e0 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  () callback is i
1d2f0 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 20 55 54  nvoked with a UT
1d300 46 2d 38 20 72 65 6e 64 65 72 69 6e 67 20 6f 66  F-8 rendering of
1d310 20 74 68 65 0a 2a 2a 20 53 51 4c 20 73 74 61 74   the.** SQL stat
1d320 65 6d 65 6e 74 20 74 65 78 74 20 61 73 20 74 68  ement text as th
1d330 65 20 73 74 61 74 65 6d 65 6e 74 20 66 69 72 73  e statement firs
1d340 74 20 62 65 67 69 6e 73 20 65 78 65 63 75 74 69  t begins executi
1d350 6e 67 2e 0a 2a 2a 20 5e 28 41 64 64 69 74 69 6f  ng..** ^(Additio
1d360 6e 61 6c 20 73 71 6c 69 74 65 33 5f 74 72 61 63  nal sqlite3_trac
1d370 65 28 29 20 63 61 6c 6c 62 61 63 6b 73 20 6d 69  e() callbacks mi
1d380 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 61 73 20  ght occur.** as 
1d390 65 61 63 68 20 74 72 69 67 67 65 72 65 64 20 73  each triggered s
1d3a0 75 62 70 72 6f 67 72 61 6d 20 69 73 20 65 6e 74  ubprogram is ent
1d3b0 65 72 65 64 2e 20 20 54 68 65 20 63 61 6c 6c 62  ered.  The callb
1d3c0 61 63 6b 73 20 66 6f 72 20 74 72 69 67 67 65 72  acks for trigger
1d3d0 73 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 61 20 55  s.** contain a U
1d3e0 54 46 2d 38 20 53 51 4c 20 63 6f 6d 6d 65 6e 74  TF-8 SQL comment
1d3f0 20 74 68 61 74 20 69 64 65 6e 74 69 66 69 65 73   that identifies
1d400 20 74 68 65 20 74 72 69 67 67 65 72 2e 29 5e 0a   the trigger.)^.
1d410 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62  **.** ^The callb
1d420 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67  ack function reg
1d430 69 73 74 65 72 65 64 20 62 79 20 73 71 6c 69 74  istered by sqlit
1d440 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 69 73 20  e3_profile() is 
1d450 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73 20 65 61  invoked.** as ea
1d460 63 68 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ch SQL statement
1d470 20 66 69 6e 69 73 68 65 73 2e 20 20 5e 54 68 65   finishes.  ^The
1d480 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63   profile callbac
1d490 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74 68  k contains.** th
1d4a0 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65  e original state
1d4b0 6d 65 6e 74 20 74 65 78 74 20 61 6e 64 20 61 6e  ment text and an
1d4c0 20 65 73 74 69 6d 61 74 65 20 6f 66 20 77 61 6c   estimate of wal
1d4d0 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a 20  l-clock time.** 
1d4e0 6f 66 20 68 6f 77 20 6c 6f 6e 67 20 74 68 61 74  of how long that
1d4f0 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b 20   statement took 
1d500 74 6f 20 72 75 6e 2e 20 20 5e 54 68 65 20 70 72  to run.  ^The pr
1d510 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 0a 2a  ofile callback.*
1d520 2a 20 74 69 6d 65 20 69 73 20 69 6e 20 75 6e 69  * time is in uni
1d530 74 73 20 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e 64  ts of nanosecond
1d540 73 2c 20 68 6f 77 65 76 65 72 20 74 68 65 20 63  s, however the c
1d550 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74  urrent implement
1d560 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6f 6e 6c 79  ation.** is only
1d570 20 63 61 70 61 62 6c 65 20 6f 66 20 6d 69 6c 6c   capable of mill
1d580 69 73 65 63 6f 6e 64 20 72 65 73 6f 6c 75 74 69  isecond resoluti
1d590 6f 6e 20 73 6f 20 74 68 65 20 73 69 78 20 6c 65  on so the six le
1d5a0 61 73 74 20 73 69 67 6e 69 66 69 63 61 6e 74 0a  ast significant.
1d5b0 2a 2a 20 64 69 67 69 74 73 20 69 6e 20 74 68 65  ** digits in the
1d5c0 20 74 69 6d 65 20 61 72 65 20 6d 65 61 6e 69 6e   time are meanin
1d5d0 67 6c 65 73 73 2e 20 20 46 75 74 75 72 65 20 76  gless.  Future v
1d5e0 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
1d5f0 65 0a 2a 2a 20 6d 69 67 68 74 20 70 72 6f 76 69  e.** might provi
1d600 64 65 20 67 72 65 61 74 65 72 20 72 65 73 6f 6c  de greater resol
1d610 75 74 69 6f 6e 20 6f 6e 20 74 68 65 20 70 72 6f  ution on the pro
1d620 66 69 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20  filer callback. 
1d630 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   The.** sqlite3_
1d640 70 72 6f 66 69 6c 65 28 29 20 66 75 6e 63 74 69  profile() functi
1d650 6f 6e 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64  on is considered
1d660 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e   experimental an
1d670 64 20 69 73 0a 2a 2a 20 73 75 62 6a 65 63 74 20  d is.** subject 
1d680 74 6f 20 63 68 61 6e 67 65 20 69 6e 20 66 75 74  to change in fut
1d690 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ure versions of 
1d6a0 53 51 4c 69 74 65 2e 0a 2a 2f 0a 76 6f 69 64 20  SQLite..*/.void 
1d6b0 2a 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 73  *sqlite3_trace(s
1d6c0 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a 78  qlite3*, void(*x
1d6d0 54 72 61 63 65 29 28 76 6f 69 64 2a 2c 63 6f 6e  Trace)(void*,con
1d6e0 73 74 20 63 68 61 72 2a 29 2c 20 76 6f 69 64 2a  st char*), void*
1d6f0 29 3b 0a 53 51 4c 49 54 45 5f 45 58 50 45 52 49  );.SQLITE_EXPERI
1d700 4d 45 4e 54 41 4c 20 76 6f 69 64 20 2a 73 71 6c  MENTAL void *sql
1d710 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 73 71 6c  ite3_profile(sql
1d720 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a  ite3*,.   void(*
1d730 78 50 72 6f 66 69 6c 65 29 28 76 6f 69 64 2a 2c  xProfile)(void*,
1d740 63 6f 6e 73 74 20 63 68 61 72 2a 2c 73 71 6c 69  const char*,sqli
1d750 74 65 33 5f 75 69 6e 74 36 34 29 2c 20 76 6f 69  te3_uint64), voi
1d760 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d*);../*.** CAPI
1d770 33 52 45 46 3a 20 51 75 65 72 79 20 50 72 6f 67  3REF: Query Prog
1d780 72 65 73 73 20 43 61 6c 6c 62 61 63 6b 73 0a 2a  ress Callbacks.*
1d790 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
1d7a0 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c  3_progress_handl
1d7b0 65 72 28 44 2c 4e 2c 58 2c 50 29 20 69 6e 74 65  er(D,N,X,P) inte
1d7c0 72 66 61 63 65 20 63 61 75 73 65 73 20 74 68 65  rface causes the
1d7d0 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e   callback.** fun
1d7e0 63 74 69 6f 6e 20 58 20 74 6f 20 62 65 20 69 6e  ction X to be in
1d7f0 76 6f 6b 65 64 20 70 65 72 69 6f 64 69 63 61 6c  voked periodical
1d800 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67 20 72  ly during long r
1d810 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f 0a  unning calls to.
1d820 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  ** [sqlite3_exec
1d830 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74  ()], [sqlite3_st
1d840 65 70 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  ep()] and [sqlit
1d850 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20  e3_get_table()] 
1d860 66 6f 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  for.** database 
1d870 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 20 41  connection D.  A
1d880 6e 20 65 78 61 6d 70 6c 65 20 75 73 65 20 66 6f  n example use fo
1d890 72 20 74 68 69 73 0a 2a 2a 20 69 6e 74 65 72 66  r this.** interf
1d8a0 61 63 65 20 69 73 20 74 6f 20 6b 65 65 70 20 61  ace is to keep a
1d8b0 20 47 55 49 20 75 70 64 61 74 65 64 20 64 75 72   GUI updated dur
1d8c0 69 6e 67 20 61 20 6c 61 72 67 65 20 71 75 65 72  ing a large quer
1d8d0 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 61  y..**.** ^The pa
1d8e0 72 61 6d 65 74 65 72 20 50 20 69 73 20 70 61 73  rameter P is pas
1d8f0 73 65 64 20 74 68 72 6f 75 67 68 20 61 73 20 74  sed through as t
1d900 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65  he only paramete
1d910 72 20 74 6f 20 74 68 65 20 0a 2a 2a 20 63 61 6c  r to the .** cal
1d920 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 58  lback function X
1d930 2e 20 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65  .  ^The paramete
1d940 72 20 4e 20 69 73 20 74 68 65 20 6e 75 6d 62 65  r N is the numbe
1d950 72 20 6f 66 20 0a 2a 2a 20 5b 76 69 72 74 75 61  r of .** [virtua
1d960 6c 20 6d 61 63 68 69 6e 65 20 69 6e 73 74 72 75  l machine instru
1d970 63 74 69 6f 6e 73 5d 20 74 68 61 74 20 61 72 65  ctions] that are
1d980 20 65 76 61 6c 75 61 74 65 64 20 62 65 74 77 65   evaluated betwe
1d990 65 6e 20 73 75 63 63 65 73 73 69 76 65 0a 2a 2a  en successive.**
1d9a0 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20   invocations of 
1d9b0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 58 2e 0a  the callback X..
1d9c0 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 61 20 73 69  **.** ^Only a si
1d9d0 6e 67 6c 65 20 70 72 6f 67 72 65 73 73 20 68 61  ngle progress ha
1d9e0 6e 64 6c 65 72 20 6d 61 79 20 62 65 20 64 65 66  ndler may be def
1d9f0 69 6e 65 64 20 61 74 20 6f 6e 65 20 74 69 6d 65  ined at one time
1da00 20 70 65 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73   per.** [databas
1da10 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 3b 20 73  e connection]; s
1da20 65 74 74 69 6e 67 20 61 20 6e 65 77 20 70 72 6f  etting a new pro
1da30 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61  gress handler ca
1da40 6e 63 65 6c 73 20 74 68 65 0a 2a 2a 20 6f 6c 64  ncels the.** old
1da50 20 6f 6e 65 2e 20 20 5e 53 65 74 74 69 6e 67 20   one.  ^Setting 
1da60 70 61 72 61 6d 65 74 65 72 20 58 20 74 6f 20 4e  parameter X to N
1da70 55 4c 4c 20 64 69 73 61 62 6c 65 73 20 74 68 65  ULL disables the
1da80 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65   progress handle
1da90 72 2e 0a 2a 2a 20 5e 54 68 65 20 70 72 6f 67 72  r..** ^The progr
1daa0 65 73 73 20 68 61 6e 64 6c 65 72 20 69 73 20 61  ess handler is a
1dab0 6c 73 6f 20 64 69 73 61 62 6c 65 64 20 62 79 20  lso disabled by 
1dac0 73 65 74 74 69 6e 67 20 4e 20 74 6f 20 61 20 76  setting N to a v
1dad0 61 6c 75 65 20 6c 65 73 73 0a 2a 2a 20 74 68 61  alue less.** tha
1dae0 6e 20 31 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  n 1..**.** ^If t
1daf0 68 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c  he progress call
1db00 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e  back returns non
1db10 2d 7a 65 72 6f 2c 20 74 68 65 20 6f 70 65 72 61  -zero, the opera
1db20 74 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74 65 72  tion is.** inter
1db30 72 75 70 74 65 64 2e 20 20 54 68 69 73 20 66 65  rupted.  This fe
1db40 61 74 75 72 65 20 63 61 6e 20 62 65 20 75 73 65  ature can be use
1db50 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61  d to implement a
1db60 0a 2a 2a 20 22 43 61 6e 63 65 6c 22 20 62 75 74  .** "Cancel" but
1db70 74 6f 6e 20 6f 6e 20 61 20 47 55 49 20 70 72 6f  ton on a GUI pro
1db80 67 72 65 73 73 20 64 69 61 6c 6f 67 20 62 6f 78  gress dialog box
1db90 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 6f 67  ..**.** The prog
1dba0 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61 6c  ress handler cal
1dbb0 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64  lback must not d
1dbc0 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20  o anything that 
1dbd0 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74  will modify.** t
1dbe0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
1dbf0 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f  ection that invo
1dc00 6b 65 64 20 74 68 65 20 70 72 6f 67 72 65 73 73  ked the progress
1dc10 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 4e 6f 74   handler..** Not
1dc20 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f  e that [sqlite3_
1dc30 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e  prepare_v2()] an
1dc40 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  d [sqlite3_step(
1dc50 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74  )] both modify t
1dc60 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65  heir.** database
1dc70 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72   connections for
1dc80 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20   the meaning of 
1dc90 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73  "modify" in this
1dca0 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a   paragraph..**.*
1dcb0 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 70  /.void sqlite3_p
1dcc0 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28  rogress_handler(
1dcd0 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 2c 20 69  sqlite3*, int, i
1dce0 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f  nt(*)(void*), vo
1dcf0 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  id*);../*.** CAP
1dd00 49 33 52 45 46 3a 20 4f 70 65 6e 69 6e 67 20 41  I3REF: Opening A
1dd10 20 4e 65 77 20 44 61 74 61 62 61 73 65 20 43 6f   New Database Co
1dd20 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e  nnection.**.** ^
1dd30 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f  These routines o
1dd40 70 65 6e 20 61 6e 20 53 51 4c 69 74 65 20 64 61  pen an SQLite da
1dd50 74 61 62 61 73 65 20 66 69 6c 65 20 61 73 20 73  tabase file as s
1dd60 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20  pecified by the 
1dd70 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 61 72 67  .** filename arg
1dd80 75 6d 65 6e 74 2e 20 5e 54 68 65 20 66 69 6c 65  ument. ^The file
1dd90 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 69 73  name argument is
1dda0 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
1ddb0 55 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c  UTF-8 for.** sql
1ddc0 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20  ite3_open() and 
1ddd0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
1dde0 29 20 61 6e 64 20 61 73 20 55 54 46 2d 31 36 20  ) and as UTF-16 
1ddf0 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79  in the native by
1de00 74 65 0a 2a 2a 20 6f 72 64 65 72 20 66 6f 72 20  te.** order for 
1de10 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
1de20 2e 20 5e 28 41 20 5b 64 61 74 61 62 61 73 65 20  . ^(A [database 
1de30 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64  connection] hand
1de40 6c 65 20 69 73 20 75 73 75 61 6c 6c 79 0a 2a 2a  le is usually.**
1de50 20 72 65 74 75 72 6e 65 64 20 69 6e 20 2a 70 70   returned in *pp
1de60 44 62 2c 20 65 76 65 6e 20 69 66 20 61 6e 20 65  Db, even if an e
1de70 72 72 6f 72 20 6f 63 63 75 72 73 2e 20 20 54 68  rror occurs.  Th
1de80 65 20 6f 6e 6c 79 20 65 78 63 65 70 74 69 6f 6e  e only exception
1de90 20 69 73 20 74 68 61 74 0a 2a 2a 20 69 66 20 53   is that.** if S
1dea0 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20  QLite is unable 
1deb0 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f  to allocate memo
1dec0 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 5b  ry to hold the [
1ded0 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2c  sqlite3] object,
1dee0 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77 69 6c 6c 20  .** a NULL will 
1def0 62 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20  be written into 
1df00 2a 70 70 44 62 20 69 6e 73 74 65 61 64 20 6f 66  *ppDb instead of
1df10 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
1df20 65 20 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f  e [sqlite3].** o
1df30 62 6a 65 63 74 2e 29 5e 20 5e 28 49 66 20 74 68  bject.)^ ^(If th
1df40 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
1df50 65 6e 65 64 20 28 61 6e 64 2f 6f 72 20 63 72 65  ened (and/or cre
1df60 61 74 65 64 29 20 73 75 63 63 65 73 73 66 75 6c  ated) successful
1df70 6c 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c  ly, then.** [SQL
1df80 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72  ITE_OK] is retur
1df90 6e 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20  ned.  Otherwise 
1dfa0 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  an [error code] 
1dfb0 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 5e  is returned.)^ ^
1dfc0 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  The.** [sqlite3_
1dfd0 65 72 72 6d 73 67 28 29 5d 20 6f 72 20 5b 73 71  errmsg()] or [sq
1dfe0 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29  lite3_errmsg16()
1dff0 5d 20 72 6f 75 74 69 6e 65 73 20 63 61 6e 20 62  ] routines can b
1e000 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e  e used to obtain
1e010 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69 73 68 20 6c  .** an English l
1e020 61 6e 67 75 61 67 65 20 64 65 73 63 72 69 70 74  anguage descript
1e030 69 6f 6e 20 6f 66 20 74 68 65 20 65 72 72 6f 72  ion of the error
1e040 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69   following a fai
1e050 6c 75 72 65 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f  lure of any.** o
1e060 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 6f 70  f the sqlite3_op
1e070 65 6e 28 29 20 72 6f 75 74 69 6e 65 73 2e 0a 2a  en() routines..*
1e080 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c  *.** ^The defaul
1e090 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20 74  t encoding for t
1e0a0 68 65 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c  he database will
1e0b0 20 62 65 20 55 54 46 2d 38 20 69 66 0a 2a 2a 20   be UTF-8 if.** 
1e0c0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f  sqlite3_open() o
1e0d0 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
1e0e0 32 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 6e  2() is called an
1e0f0 64 0a 2a 2a 20 55 54 46 2d 31 36 20 69 6e 20 74  d.** UTF-16 in t
1e100 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  he native byte o
1e110 72 64 65 72 20 69 66 20 73 71 6c 69 74 65 33 5f  rder if sqlite3_
1e120 6f 70 65 6e 31 36 28 29 20 69 73 20 75 73 65 64  open16() is used
1e130 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68 65 72 20  ..**.** Whether 
1e140 6f 72 20 6e 6f 74 20 61 6e 20 65 72 72 6f 72 20  or not an error 
1e150 6f 63 63 75 72 73 20 77 68 65 6e 20 69 74 20 69  occurs when it i
1e160 73 20 6f 70 65 6e 65 64 2c 20 72 65 73 6f 75 72  s opened, resour
1e170 63 65 73 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65  ces.** associate
1e180 64 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61  d with the [data
1e190 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
1e1a0 20 68 61 6e 64 6c 65 20 73 68 6f 75 6c 64 20 62   handle should b
1e1b0 65 20 72 65 6c 65 61 73 65 64 20 62 79 0a 2a 2a  e released by.**
1e1c0 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b   passing it to [
1e1d0 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d  sqlite3_close()]
1e1e0 20 77 68 65 6e 20 69 74 20 69 73 20 6e 6f 20 6c   when it is no l
1e1f0 6f 6e 67 65 72 20 72 65 71 75 69 72 65 64 2e 0a  onger required..
1e200 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
1e210 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 6e 74 65  3_open_v2() inte
1e220 72 66 61 63 65 20 77 6f 72 6b 73 20 6c 69 6b 65  rface works like
1e230 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 0a   sqlite3_open().
1e240 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 69  ** except that i
1e250 74 20 61 63 63 65 70 74 73 20 74 77 6f 20 61 64  t accepts two ad
1e260 64 69 74 69 6f 6e 61 6c 20 70 61 72 61 6d 65 74  ditional paramet
1e270 65 72 73 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  ers for addition
1e280 61 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76  al control.** ov
1e290 65 72 20 74 68 65 20 6e 65 77 20 64 61 74 61 62  er the new datab
1e2a0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20  ase connection. 
1e2b0 20 5e 28 54 68 65 20 66 6c 61 67 73 20 70 61 72   ^(The flags par
1e2c0 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 73 71 6c  ameter to.** sql
1e2d0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 63  ite3_open_v2() c
1e2e0 61 6e 20 74 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a  an take one of.*
1e2f0 2a 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  * the following 
1e300 74 68 72 65 65 20 76 61 6c 75 65 73 2c 20 6f 70  three values, op
1e310 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65  tionally combine
1e320 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b  d with the .** [
1e330 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55  SQLITE_OPEN_NOMU
1e340 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50  TEX], [SQLITE_OP
1e350 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 2c 20 5b  EN_FULLMUTEX], [
1e360 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52  SQLITE_OPEN_SHAR
1e370 45 44 43 41 43 48 45 5d 2c 0a 2a 2a 20 5b 53 51  EDCACHE],.** [SQ
1e380 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54  LITE_OPEN_PRIVAT
1e390 45 43 41 43 48 45 5d 2c 20 61 6e 64 2f 6f 72 20  ECACHE], and/or 
1e3a0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49  [SQLITE_OPEN_URI
1e3b0 5d 20 66 6c 61 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a  ] flags:)^.**.**
1e3c0 20 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 5b   <dl>.** ^(<dt>[
1e3d0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
1e3e0 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ONLY]</dt>.** <d
1e3f0 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69  d>The database i
1e400 73 20 6f 70 65 6e 65 64 20 69 6e 20 72 65 61 64  s opened in read
1e410 2d 6f 6e 6c 79 20 6d 6f 64 65 2e 20 20 49 66 20  -only mode.  If 
1e420 74 68 65 20 64 61 74 61 62 61 73 65 20 64 6f 65  the database doe
1e430 73 20 6e 6f 74 0a 2a 2a 20 61 6c 72 65 61 64 79  s not.** already
1e440 20 65 78 69 73 74 2c 20 61 6e 20 65 72 72 6f 72   exist, an error
1e450 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64   is returned.</d
1e460 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74  d>)^.**.** ^(<dt
1e470 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45  >[SQLITE_OPEN_RE
1e480 41 44 57 52 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a  ADWRITE]</dt>.**
1e490 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73   <dd>The databas
1e4a0 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20  e is opened for 
1e4b0 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74  reading and writ
1e4c0 69 6e 67 20 69 66 20 70 6f 73 73 69 62 6c 65 2c  ing if possible,
1e4d0 20 6f 72 20 72 65 61 64 69 6e 67 0a 2a 2a 20 6f   or reading.** o
1e4e0 6e 6c 79 20 69 66 20 74 68 65 20 66 69 6c 65 20  nly if the file 
1e4f0 69 73 20 77 72 69 74 65 20 70 72 6f 74 65 63 74  is write protect
1e500 65 64 20 62 79 20 74 68 65 20 6f 70 65 72 61 74  ed by the operat
1e510 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 49 6e 20  ing system.  In 
1e520 65 69 74 68 65 72 0a 2a 2a 20 63 61 73 65 20 74  either.** case t
1e530 68 65 20 64 61 74 61 62 61 73 65 20 6d 75 73 74  he database must
1e540 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20   already exist, 
1e550 6f 74 68 65 72 77 69 73 65 20 61 6e 20 65 72 72  otherwise an err
1e560 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c  or is returned.<
1e570 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c  /dd>)^.**.** ^(<
1e580 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  dt>[SQLITE_OPEN_
1e590 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51  READWRITE] | [SQ
1e5a0 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
1e5b0 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  ]</dt>.** <dd>Th
1e5c0 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
1e5d0 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67  ened for reading
1e5e0 20 61 6e 64 20 77 72 69 74 69 6e 67 2c 20 61 6e   and writing, an
1e5f0 64 20 69 73 20 63 72 65 61 74 65 64 20 69 66 0a  d is created if.
1e600 2a 2a 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 61  ** it does not a
1e610 6c 72 65 61 64 79 20 65 78 69 73 74 2e 20 54 68  lready exist. Th
1e620 69 73 20 69 73 20 74 68 65 20 62 65 68 61 76 69  is is the behavi
1e630 6f 72 20 74 68 61 74 20 69 73 20 61 6c 77 61 79  or that is alway
1e640 73 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 73 71  s used for.** sq
1e650 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64  lite3_open() and
1e660 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28   sqlite3_open16(
1e670 29 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64  ).</dd>)^.** </d
1e680 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  l>.**.** If the 
1e690 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  3rd parameter to
1e6a0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
1e6b0 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66  () is not one of
1e6c0 20 74 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74   the.** combinat
1e6d0 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76 65  ions shown above
1e6e0 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62   optionally comb
1e6f0 69 6e 65 64 20 77 69 74 68 20 6f 74 68 65 72 0a  ined with other.
1e700 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ** [SQLITE_OPEN_
1e710 52 45 41 44 4f 4e 4c 59 20 7c 20 53 51 4c 49 54  READONLY | SQLIT
1e720 45 5f 4f 50 45 4e 5f 2a 20 62 69 74 73 5d 0a 2a  E_OPEN_* bits].*
1e730 2a 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  * then the behav
1e740 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ior is undefined
1e750 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
1e760 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d  [SQLITE_OPEN_NOM
1e770 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65  UTEX] flag is se
1e780 74 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61  t, then the data
1e790 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
1e7a0 2a 2a 20 6f 70 65 6e 73 20 69 6e 20 74 68 65 20  ** opens in the 
1e7b0 6d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68  multi-thread [th
1e7c0 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 73  reading mode] as
1e7d0 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 73 69 6e   long as the sin
1e7e0 67 6c 65 2d 74 68 72 65 61 64 0a 2a 2a 20 6d 6f  gle-thread.** mo
1e7f0 64 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20  de has not been 
1e800 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74  set at compile-t
1e810 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d  ime or start-tim
1e820 65 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b  e.  ^If the.** [
1e830 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c  SQLITE_OPEN_FULL
1e840 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73  MUTEX] flag is s
1e850 65 74 20 74 68 65 6e 20 74 68 65 20 64 61 74 61  et then the data
1e860 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
1e870 6f 70 65 6e 73 0a 2a 2a 20 69 6e 20 74 68 65 20  opens.** in the 
1e880 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65  serialized [thre
1e890 61 64 69 6e 67 20 6d 6f 64 65 5d 20 75 6e 6c 65  ading mode] unle
1e8a0 73 73 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64  ss single-thread
1e8b0 20 77 61 73 0a 2a 2a 20 70 72 65 76 69 6f 75 73   was.** previous
1e8c0 6c 79 20 73 65 6c 65 63 74 65 64 20 61 74 20 63  ly selected at c
1e8d0 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73  ompile-time or s
1e8e0 74 61 72 74 2d 74 69 6d 65 2e 0a 2a 2a 20 5e 54  tart-time..** ^T
1e8f0 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
1e900 53 48 41 52 45 44 43 41 43 48 45 5d 20 66 6c 61  SHAREDCACHE] fla
1e910 67 20 63 61 75 73 65 73 20 74 68 65 20 64 61 74  g causes the dat
1e920 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1e930 20 74 6f 20 62 65 0a 2a 2a 20 65 6c 69 67 69 62   to be.** eligib
1e940 6c 65 20 74 6f 20 75 73 65 20 5b 73 68 61 72 65  le to use [share
1e950 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 2c 20 72  d cache mode], r
1e960 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65  egardless of whe
1e970 74 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72  ther or not shar
1e980 65 64 0a 2a 2a 20 63 61 63 68 65 20 69 73 20 65  ed.** cache is e
1e990 6e 61 62 6c 65 64 20 75 73 69 6e 67 20 5b 73 71  nabled using [sq
1e9a0 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61  lite3_enable_sha
1e9b0 72 65 64 5f 63 61 63 68 65 28 29 5d 2e 20 20 5e  red_cache()].  ^
1e9c0 54 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  The.** [SQLITE_O
1e9d0 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45  PEN_PRIVATECACHE
1e9e0 5d 20 66 6c 61 67 20 63 61 75 73 65 73 20 74 68  ] flag causes th
1e9f0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
1ea00 63 74 69 6f 6e 20 74 6f 20 6e 6f 74 0a 2a 2a 20  ction to not.** 
1ea10 70 61 72 74 69 63 69 70 61 74 65 20 69 6e 20 5b  participate in [
1ea20 73 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64  shared cache mod
1ea30 65 5d 20 65 76 65 6e 20 69 66 20 69 74 20 69 73  e] even if it is
1ea40 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20   enabled..**.** 
1ea50 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61  ^The fourth para
1ea60 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
1ea70 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 74 68  _open_v2() is th
1ea80 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a  e name of the.**
1ea90 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f   [sqlite3_vfs] o
1eaa0 62 6a 65 63 74 20 74 68 61 74 20 64 65 66 69 6e  bject that defin
1eab0 65 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67  es the operating
1eac0 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61 63   system interfac
1ead0 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 65  e that.** the ne
1eae0 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  w database conne
1eaf0 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65  ction should use
1eb00 2e 20 20 5e 49 66 20 74 68 65 20 66 6f 75 72 74  .  ^If the fourt
1eb10 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a  h parameter is.*
1eb20 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  * a NULL pointer
1eb30 20 74 68 65 6e 20 74 68 65 20 64 65 66 61 75 6c   then the defaul
1eb40 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  t [sqlite3_vfs] 
1eb50 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e 0a  object is used..
1eb60 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69  **.** ^If the fi
1eb70 6c 65 6e 61 6d 65 20 69 73 20 22 3a 6d 65 6d 6f  lename is ":memo
1eb80 72 79 3a 22 2c 20 74 68 65 6e 20 61 20 70 72 69  ry:", then a pri
1eb90 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 20  vate, temporary 
1eba0 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61  in-memory databa
1ebb0 73 65 0a 2a 2a 20 69 73 20 63 72 65 61 74 65 64  se.** is created
1ebc0 20 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63 74   for the connect
1ebd0 69 6f 6e 2e 20 20 5e 54 68 69 73 20 69 6e 2d 6d  ion.  ^This in-m
1ebe0 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 20 77  emory database w
1ebf0 69 6c 6c 20 76 61 6e 69 73 68 20 77 68 65 6e 0a  ill vanish when.
1ec00 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ** the database 
1ec10 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c  connection is cl
1ec20 6f 73 65 64 2e 20 20 46 75 74 75 72 65 20 76 65  osed.  Future ve
1ec30 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
1ec40 20 6d 69 67 68 74 0a 2a 2a 20 6d 61 6b 65 20 75   might.** make u
1ec50 73 65 20 6f 66 20 61 64 64 69 74 69 6f 6e 61 6c  se of additional
1ec60 20 73 70 65 63 69 61 6c 20 66 69 6c 65 6e 61 6d   special filenam
1ec70 65 73 20 74 68 61 74 20 62 65 67 69 6e 20 77 69  es that begin wi
1ec80 74 68 20 74 68 65 20 22 3a 22 20 63 68 61 72 61  th the ":" chara
1ec90 63 74 65 72 2e 0a 2a 2a 20 49 74 20 69 73 20 72  cter..** It is r
1eca0 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20  ecommended that 
1ecb0 77 68 65 6e 20 61 20 64 61 74 61 62 61 73 65 20  when a database 
1ecc0 66 69 6c 65 6e 61 6d 65 20 61 63 74 75 61 6c 6c  filename actuall
1ecd0 79 20 64 6f 65 73 20 62 65 67 69 6e 20 77 69 74  y does begin wit
1ece0 68 0a 2a 2a 20 61 20 22 3a 22 20 63 68 61 72 61  h.** a ":" chara
1ecf0 63 74 65 72 20 79 6f 75 20 73 68 6f 75 6c 64 20  cter you should 
1ed00 70 72 65 66 69 78 20 74 68 65 20 66 69 6c 65 6e  prefix the filen
1ed10 61 6d 65 20 77 69 74 68 20 61 20 70 61 74 68 6e  ame with a pathn
1ed20 61 6d 65 20 73 75 63 68 20 61 73 0a 2a 2a 20 22  ame such as.** "
1ed30 2e 2f 22 20 74 6f 20 61 76 6f 69 64 20 61 6d 62  ./" to avoid amb
1ed40 69 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49  iguity..**.** ^I
1ed50 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69  f the filename i
1ed60 73 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e  s an empty strin
1ed70 67 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61 74  g, then a privat
1ed80 65 2c 20 74 65 6d 70 6f 72 61 72 79 0a 2a 2a 20  e, temporary.** 
1ed90 6f 6e 2d 64 69 73 6b 20 64 61 74 61 62 61 73 65  on-disk database
1eda0 20 77 69 6c 6c 20 62 65 20 63 72 65 61 74 65 64   will be created
1edb0 2e 20 20 5e 54 68 69 73 20 70 72 69 76 61 74 65  .  ^This private
1edc0 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62   database will b
1edd0 65 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c  e.** automatical
1ede0 6c 79 20 64 65 6c 65 74 65 64 20 61 73 20 73 6f  ly deleted as so
1edf0 6f 6e 20 61 73 20 74 68 65 20 64 61 74 61 62 61  on as the databa
1ee00 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
1ee10 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b   closed..**.** [
1ee20 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 69  [URI filenames i
1ee30 6e 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  n sqlite3_open()
1ee40 5d 5d 20 3c 68 33 3e 55 52 49 20 46 69 6c 65 6e  ]] <h3>URI Filen
1ee50 61 6d 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20  ames</h3>.**.** 
1ee60 5e 49 66 20 5b 55 52 49 20 66 69 6c 65 6e 61 6d  ^If [URI filenam
1ee70 65 5d 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f  e] interpretatio
1ee80 6e 20 69 73 20 65 6e 61 62 6c 65 64 2c 20 61 6e  n is enabled, an
1ee90 64 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61  d the filename a
1eea0 72 67 75 6d 65 6e 74 0a 2a 2a 20 62 65 67 69 6e  rgument.** begin
1eeb0 73 20 77 69 74 68 20 22 66 69 6c 65 3a 22 2c 20  s with "file:", 
1eec0 74 68 65 6e 20 74 68 65 20 66 69 6c 65 6e 61 6d  then the filenam
1eed0 65 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64  e is interpreted
1eee0 20 61 73 20 61 20 55 52 49 2e 20 5e 55 52 49 0a   as a URI. ^URI.
1eef0 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65  ** filename inte
1ef00 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20 65 6e  rpretation is en
1ef10 61 62 6c 65 64 20 69 66 20 74 68 65 20 5b 53 51  abled if the [SQ
1ef20 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66  LITE_OPEN_URI] f
1ef30 6c 61 67 20 69 73 0a 2a 2a 20 73 65 74 20 69 6e  lag is.** set in
1ef40 20 74 68 65 20 66 6f 75 72 74 68 20 61 72 67 75   the fourth argu
1ef50 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
1ef60 6f 70 65 6e 5f 76 32 28 29 2c 20 6f 72 20 69 66  open_v2(), or if
1ef70 20 69 74 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20   it has.** been 
1ef80 65 6e 61 62 6c 65 64 20 67 6c 6f 62 61 6c 6c 79  enabled globally
1ef90 20 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49   using the [SQLI
1efa0 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 20 6f  TE_CONFIG_URI] o
1efb0 70 74 69 6f 6e 20 77 69 74 68 20 74 68 65 0a 2a  ption with the.*
1efc0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
1efd0 67 28 29 5d 20 6d 65 74 68 6f 64 20 6f 72 20 62  g()] method or b
1efe0 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 55 53  y the [SQLITE_US
1eff0 45 5f 55 52 49 5d 20 63 6f 6d 70 69 6c 65 2d 74  E_URI] compile-t
1f000 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 41  ime option..** A
1f010 73 20 6f 66 20 53 51 4c 69 74 65 20 76 65 72 73  s of SQLite vers
1f020 69 6f 6e 20 33 2e 37 2e 37 2c 20 55 52 49 20 66  ion 3.7.7, URI f
1f030 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 65  ilename interpre
1f040 74 61 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64  tation is turned
1f050 20 6f 66 66 0a 2a 2a 20 62 79 20 64 65 66 61 75   off.** by defau
1f060 6c 74 2c 20 62 75 74 20 66 75 74 75 72 65 20 72  lt, but future r
1f070 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74  eleases of SQLit
1f080 65 20 6d 69 67 68 74 20 65 6e 61 62 6c 65 20 55  e might enable U
1f090 52 49 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 69  RI filename.** i
1f0a0 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 62 79  nterpretation by
1f0b0 20 64 65 66 61 75 6c 74 2e 20 20 53 65 65 20 22   default.  See "
1f0c0 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 5d 22  [URI filenames]"
1f0d0 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a   for additional.
1f0e0 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  ** information..
1f0f0 2a 2a 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61  **.** URI filena
1f100 6d 65 73 20 61 72 65 20 70 61 72 73 65 64 20 61  mes are parsed a
1f110 63 63 6f 72 64 69 6e 67 20 74 6f 20 52 46 43 20  ccording to RFC 
1f120 33 39 38 36 2e 20 5e 49 66 20 74 68 65 20 55 52  3986. ^If the UR
1f130 49 20 63 6f 6e 74 61 69 6e 73 20 61 6e 0a 2a 2a  I contains an.**
1f140 20 61 75 74 68 6f 72 69 74 79 2c 20 74 68 65 6e   authority, then
1f150 20 69 74 20 6d 75 73 74 20 62 65 20 65 69 74 68   it must be eith
1f160 65 72 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69  er an empty stri
1f170 6e 67 20 6f 72 20 74 68 65 20 73 74 72 69 6e 67  ng or the string
1f180 20 0a 2a 2a 20 22 6c 6f 63 61 6c 68 6f 73 74 22   .** "localhost"
1f190 2e 20 5e 49 66 20 74 68 65 20 61 75 74 68 6f 72  . ^If the author
1f1a0 69 74 79 20 69 73 20 6e 6f 74 20 61 6e 20 65 6d  ity is not an em
1f1b0 70 74 79 20 73 74 72 69 6e 67 20 6f 72 20 22 6c  pty string or "l
1f1c0 6f 63 61 6c 68 6f 73 74 22 2c 20 61 6e 20 0a 2a  ocalhost", an .*
1f1d0 2a 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72  * error is retur
1f1e0 6e 65 64 20 74 6f 20 74 68 65 20 63 61 6c 6c 65  ned to the calle
1f1f0 72 2e 20 5e 54 68 65 20 66 72 61 67 6d 65 6e 74  r. ^The fragment
1f200 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20   component of a 
1f210 55 52 49 2c 20 69 66 20 0a 2a 2a 20 70 72 65 73  URI, if .** pres
1f220 65 6e 74 2c 20 69 73 20 69 67 6e 6f 72 65 64 2e  ent, is ignored.
1f230 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75  .**.** ^SQLite u
1f240 73 65 73 20 74 68 65 20 70 61 74 68 20 63 6f 6d  ses the path com
1f250 70 6f 6e 65 6e 74 20 6f 66 20 74 68 65 20 55 52  ponent of the UR
1f260 49 20 61 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  I as the name of
1f270 20 74 68 65 20 64 69 73 6b 20 66 69 6c 65 0a 2a   the disk file.*
1f280 2a 20 77 68 69 63 68 20 63 6f 6e 74 61 69 6e 73  * which contains
1f290 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 20 5e   the database. ^
1f2a0 49 66 20 74 68 65 20 70 61 74 68 20 62 65 67 69  If the path begi
1f2b0 6e 73 20 77 69 74 68 20 61 20 27 2f 27 20 63 68  ns with a '/' ch
1f2c0 61 72 61 63 74 65 72 2c 20 0a 2a 2a 20 74 68 65  aracter, .** the
1f2d0 6e 20 69 74 20 69 73 20 69 6e 74 65 72 70 72 65  n it is interpre
1f2e0 74 65 64 20 61 73 20 61 6e 20 61 62 73 6f 6c 75  ted as an absolu
1f2f0 74 65 20 70 61 74 68 2e 20 5e 49 66 20 74 68 65  te path. ^If the
1f300 20 70 61 74 68 20 64 6f 65 73 20 6e 6f 74 20 62   path does not b
1f310 65 67 69 6e 20 0a 2a 2a 20 77 69 74 68 20 61 20  egin .** with a 
1f320 27 2f 27 20 28 6d 65 61 6e 69 6e 67 20 74 68 61  '/' (meaning tha
1f330 74 20 74 68 65 20 61 75 74 68 6f 72 69 74 79 20  t the authority 
1f340 73 65 63 74 69 6f 6e 20 69 73 20 6f 6d 69 74 74  section is omitt
1f350 65 64 20 66 72 6f 6d 20 74 68 65 20 55 52 49 29  ed from the URI)
1f360 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 70 61 74  .** then the pat
1f370 68 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64  h is interpreted
1f380 20 61 73 20 61 20 72 65 6c 61 74 69 76 65 20 70   as a relative p
1f390 61 74 68 2e 20 0a 2a 2a 20 5e 4f 6e 20 77 69 6e  ath. .** ^On win
1f3a0 64 6f 77 73 2c 20 74 68 65 20 66 69 72 73 74 20  dows, the first 
1f3b0 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 6e 20  component of an 
1f3c0 61 62 73 6f 6c 75 74 65 20 70 61 74 68 20 0a 2a  absolute path .*
1f3d0 2a 20 69 73 20 61 20 64 72 69 76 65 20 73 70 65  * is a drive spe
1f3e0 63 69 66 69 63 61 74 69 6f 6e 20 28 65 2e 67 2e  cification (e.g.
1f3f0 20 22 43 3a 22 29 2e 0a 2a 2a 0a 2a 2a 20 5b 5b   "C:")..**.** [[
1f400 63 6f 72 65 20 55 52 49 20 71 75 65 72 79 20 70  core URI query p
1f410 61 72 61 6d 65 74 65 72 73 5d 5d 0a 2a 2a 20 54  arameters]].** T
1f420 68 65 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65  he query compone
1f430 6e 74 20 6f 66 20 61 20 55 52 49 20 6d 61 79 20  nt of a URI may 
1f440 63 6f 6e 74 61 69 6e 20 70 61 72 61 6d 65 74 65  contain paramete
1f450 72 73 20 74 68 61 74 20 61 72 65 20 69 6e 74 65  rs that are inte
1f460 72 70 72 65 74 65 64 0a 2a 2a 20 65 69 74 68 65  rpreted.** eithe
1f470 72 20 62 79 20 53 51 4c 69 74 65 20 69 74 73 65  r by SQLite itse
1f480 6c 66 2c 20 6f 72 20 62 79 20 61 20 5b 56 46 53  lf, or by a [VFS
1f490 20 7c 20 63 75 73 74 6f 6d 20 56 46 53 20 69 6d   | custom VFS im
1f4a0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 5d 2e 0a 2a  plementation]..*
1f4b0 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 70 72  * SQLite interpr
1f4c0 65 74 73 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e  ets the followin
1f4d0 67 20 74 68 72 65 65 20 71 75 65 72 79 20 70 61  g three query pa
1f4e0 72 61 6d 65 74 65 72 73 3a 0a 2a 2a 0a 2a 2a 20  rameters:.**.** 
1f4f0 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c  <ul>.**   <li> <
1f500 62 3e 76 66 73 3c 2f 62 3e 3a 20 5e 54 68 65 20  b>vfs</b>: ^The 
1f510 22 76 66 73 22 20 70 61 72 61 6d 65 74 65 72 20  "vfs" parameter 
1f520 6d 61 79 20 62 65 20 75 73 65 64 20 74 6f 20 73  may be used to s
1f530 70 65 63 69 66 79 20 74 68 65 20 6e 61 6d 65 20  pecify the name 
1f540 6f 66 0a 2a 2a 20 20 20 20 20 61 20 56 46 53 20  of.**     a VFS 
1f550 6f 62 6a 65 63 74 20 74 68 61 74 20 70 72 6f 76  object that prov
1f560 69 64 65 73 20 74 68 65 20 6f 70 65 72 61 74 69  ides the operati
1f570 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66  ng system interf
1f580 61 63 65 20 74 68 61 74 20 73 68 6f 75 6c 64 0a  ace that should.
1f590 2a 2a 20 20 20 20 20 62 65 20 75 73 65 64 20 74  **     be used t
1f5a0 6f 20 61 63 63 65 73 73 20 74 68 65 20 64 61 74  o access the dat
1f5b0 61 62 61 73 65 20 66 69 6c 65 20 6f 6e 20 64 69  abase file on di
1f5c0 73 6b 2e 20 5e 49 66 20 74 68 69 73 20 6f 70 74  sk. ^If this opt
1f5d0 69 6f 6e 20 69 73 20 73 65 74 20 74 6f 0a 2a 2a  ion is set to.**
1f5e0 20 20 20 20 20 61 6e 20 65 6d 70 74 79 20 73 74       an empty st
1f5f0 72 69 6e 67 20 74 68 65 20 64 65 66 61 75 6c 74  ring the default
1f600 20 56 46 53 20 6f 62 6a 65 63 74 20 69 73 20 75   VFS object is u
1f610 73 65 64 2e 20 5e 53 70 65 63 69 66 79 69 6e 67  sed. ^Specifying
1f620 20 61 6e 20 75 6e 6b 6e 6f 77 6e 0a 2a 2a 20 20   an unknown.**  
1f630 20 20 20 56 46 53 20 69 73 20 61 6e 20 65 72 72     VFS is an err
1f640 6f 72 2e 20 5e 49 66 20 73 71 6c 69 74 65 33 5f  or. ^If sqlite3_
1f650 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 75 73 65  open_v2() is use
1f660 64 20 61 6e 64 20 74 68 65 20 76 66 73 20 6f 70  d and the vfs op
1f670 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20 70  tion is.**     p
1f680 72 65 73 65 6e 74 2c 20 74 68 65 6e 20 74 68 65  resent, then the
1f690 20 56 46 53 20 73 70 65 63 69 66 69 65 64 20 62   VFS specified b
1f6a0 79 20 74 68 65 20 6f 70 74 69 6f 6e 20 74 61 6b  y the option tak
1f6b0 65 73 20 70 72 65 63 65 64 65 6e 63 65 20 6f 76  es precedence ov
1f6c0 65 72 0a 2a 2a 20 20 20 20 20 74 68 65 20 76 61  er.**     the va
1f6d0 6c 75 65 20 70 61 73 73 65 64 20 61 73 20 74 68  lue passed as th
1f6e0 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
1f6f0 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70  er to sqlite3_op
1f700 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20  en_v2()..**.**  
1f710 20 3c 6c 69 3e 20 3c 62 3e 6d 6f 64 65 3c 2f 62   <li> <b>mode</b
1f720 3e 3a 20 5e 28 54 68 65 20 6d 6f 64 65 20 70 61  >: ^(The mode pa
1f730 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 73  rameter may be s
1f740 65 74 20 74 6f 20 65 69 74 68 65 72 20 22 72 6f  et to either "ro
1f750 22 2c 20 22 72 77 22 2c 0a 2a 2a 20 20 20 20 20  ", "rw",.**     
1f760 22 72 77 63 22 2c 20 6f 72 20 22 6d 65 6d 6f 72  "rwc", or "memor
1f770 79 22 2e 20 41 74 74 65 6d 70 74 69 6e 67 20 74  y". Attempting t
1f780 6f 20 73 65 74 20 69 74 20 74 6f 20 61 6e 79 20  o set it to any 
1f790 6f 74 68 65 72 20 76 61 6c 75 65 20 69 73 0a 2a  other value is.*
1f7a0 2a 20 20 20 20 20 61 6e 20 65 72 72 6f 72 29 5e  *     an error)^
1f7b0 2e 20 0a 2a 2a 20 20 20 20 20 5e 49 66 20 22 72  . .**     ^If "r
1f7c0 6f 22 20 69 73 20 73 70 65 63 69 66 69 65 64 2c  o" is specified,
1f7d0 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   then the databa
1f7e0 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72  se is opened for
1f7f0 20 72 65 61 64 2d 6f 6e 6c 79 20 0a 2a 2a 20 20   read-only .**  
1f800 20 20 20 61 63 63 65 73 73 2c 20 6a 75 73 74 20     access, just 
1f810 61 73 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54  as if the [SQLIT
1f820 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d  E_OPEN_READONLY]
1f830 20 66 6c 61 67 20 68 61 64 20 62 65 65 6e 20 73   flag had been s
1f840 65 74 20 69 6e 20 74 68 65 20 0a 2a 2a 20 20 20  et in the .**   
1f850 20 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74    third argument
1f860 20 74 6f 20 73 71 6c 69 74 65 33 5f 70 72 65 70   to sqlite3_prep
1f870 61 72 65 5f 76 32 28 29 2e 20 5e 49 66 20 74 68  are_v2(). ^If th
1f880 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 69 73  e mode option is
1f890 20 73 65 74 20 74 6f 20 0a 2a 2a 20 20 20 20 20   set to .**     
1f8a0 22 72 77 22 2c 20 74 68 65 6e 20 74 68 65 20 64  "rw", then the d
1f8b0 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65  atabase is opene
1f8c0 64 20 66 6f 72 20 72 65 61 64 2d 77 72 69 74 65  d for read-write
1f8d0 20 28 62 75 74 20 6e 6f 74 20 63 72 65 61 74 65   (but not create
1f8e0 29 20 0a 2a 2a 20 20 20 20 20 61 63 63 65 73 73  ) .**     access
1f8f0 2c 20 61 73 20 69 66 20 53 51 4c 49 54 45 5f 4f  , as if SQLITE_O
1f900 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 28 62  PEN_READWRITE (b
1f910 75 74 20 6e 6f 74 20 53 51 4c 49 54 45 5f 4f 50  ut not SQLITE_OP
1f920 45 4e 5f 43 52 45 41 54 45 29 20 68 61 64 20 0a  EN_CREATE) had .
1f930 2a 2a 20 20 20 20 20 62 65 65 6e 20 73 65 74 2e  **     been set.
1f940 20 5e 56 61 6c 75 65 20 22 72 77 63 22 20 69 73   ^Value "rwc" is
1f950 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73   equivalent to s
1f960 65 74 74 69 6e 67 20 62 6f 74 68 20 0a 2a 2a 20  etting both .** 
1f970 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f      SQLITE_OPEN_
1f980 52 45 41 44 57 52 49 54 45 20 61 6e 64 20 53 51  READWRITE and SQ
1f990 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
1f9a0 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f 64 65 20  .  ^If the mode 
1f9b0 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20  option is.**    
1f9c0 20 73 65 74 20 74 6f 20 22 6d 65 6d 6f 72 79 22   set to "memory"
1f9d0 20 74 68 65 6e 20 61 20 70 75 72 65 20 5b 69 6e   then a pure [in
1f9e0 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65  -memory database
1f9f0 5d 20 74 68 61 74 20 6e 65 76 65 72 20 72 65 61  ] that never rea
1fa00 64 73 0a 2a 2a 20 20 20 20 20 6f 72 20 77 72 69  ds.**     or wri
1fa10 74 65 73 20 66 72 6f 6d 20 64 69 73 6b 20 69 73  tes from disk is
1fa20 20 75 73 65 64 2e 20 5e 49 74 20 69 73 20 61 6e   used. ^It is an
1fa30 20 65 72 72 6f 72 20 74 6f 20 73 70 65 63 69 66   error to specif
1fa40 79 20 61 20 76 61 6c 75 65 20 66 6f 72 0a 2a 2a  y a value for.**
1fa50 20 20 20 20 20 74 68 65 20 6d 6f 64 65 20 70 61       the mode pa
1fa60 72 61 6d 65 74 65 72 20 74 68 61 74 20 69 73 20  rameter that is 
1fa70 6c 65 73 73 20 72 65 73 74 72 69 63 74 69 76 65  less restrictive
1fa80 20 74 68 61 6e 20 74 68 61 74 20 73 70 65 63 69   than that speci
1fa90 66 69 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 74  fied by.**     t
1faa0 68 65 20 66 6c 61 67 73 20 70 61 73 73 65 64 20  he flags passed 
1fab0 69 6e 20 74 68 65 20 74 68 69 72 64 20 70 61 72  in the third par
1fac0 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
1fad0 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a  3_open_v2()..**.
1fae0 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 63 61 63  **   <li> <b>cac
1faf0 68 65 3c 2f 62 3e 3a 20 5e 54 68 65 20 63 61 63  he</b>: ^The cac
1fb00 68 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79  he parameter may
1fb10 20 62 65 20 73 65 74 20 74 6f 20 65 69 74 68 65   be set to eithe
1fb20 72 20 22 73 68 61 72 65 64 22 20 6f 72 0a 2a 2a  r "shared" or.**
1fb30 20 20 20 20 20 22 70 72 69 76 61 74 65 22 2e 20       "private". 
1fb40 5e 53 65 74 74 69 6e 67 20 69 74 20 74 6f 20 22  ^Setting it to "
1fb50 73 68 61 72 65 64 22 20 69 73 20 65 71 75 69 76  shared" is equiv
1fb60 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67  alent to setting
1fb70 20 74 68 65 0a 2a 2a 20 20 20 20 20 53 51 4c 49   the.**     SQLI
1fb80 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41  TE_OPEN_SHAREDCA
1fb90 43 48 45 20 62 69 74 20 69 6e 20 74 68 65 20 66  CHE bit in the f
1fba0 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 70 61  lags argument pa
1fbb0 73 73 65 64 20 74 6f 0a 2a 2a 20 20 20 20 20 73  ssed to.**     s
1fbc0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
1fbd0 2e 20 5e 53 65 74 74 69 6e 67 20 74 68 65 20 63  . ^Setting the c
1fbe0 61 63 68 65 20 70 61 72 61 6d 65 74 65 72 20 74  ache parameter t
1fbf0 6f 20 22 70 72 69 76 61 74 65 22 20 69 73 20 0a  o "private" is .
1fc00 2a 2a 20 20 20 20 20 65 71 75 69 76 61 6c 65 6e  **     equivalen
1fc10 74 20 74 6f 20 73 65 74 74 69 6e 67 20 74 68 65  t to setting the
1fc20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49   SQLITE_OPEN_PRI
1fc30 56 41 54 45 43 41 43 48 45 20 62 69 74 2e 0a 2a  VATECACHE bit..*
1fc40 2a 20 20 20 20 20 5e 49 66 20 73 71 6c 69 74 65  *     ^If sqlite
1fc50 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 75  3_open_v2() is u
1fc60 73 65 64 20 61 6e 64 20 74 68 65 20 22 63 61 63  sed and the "cac
1fc70 68 65 22 20 70 61 72 61 6d 65 74 65 72 20 69 73  he" parameter is
1fc80 20 70 72 65 73 65 6e 74 20 69 6e 0a 2a 2a 20 20   present in.**  
1fc90 20 20 20 61 20 55 52 49 20 66 69 6c 65 6e 61 6d     a URI filenam
1fca0 65 2c 20 69 74 73 20 76 61 6c 75 65 20 6f 76 65  e, its value ove
1fcb0 72 72 69 64 65 73 20 61 6e 79 20 62 65 68 61 76  rrides any behav
1fcc0 69 6f 75 72 20 72 65 71 75 65 73 74 65 64 20 62  iour requested b
1fcd0 79 20 73 65 74 74 69 6e 67 0a 2a 2a 20 20 20 20  y setting.**    
1fce0 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49   SQLITE_OPEN_PRI
1fcf0 56 41 54 45 43 41 43 48 45 20 6f 72 20 53 51 4c  VATECACHE or SQL
1fd00 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43  ITE_OPEN_SHAREDC
1fd10 41 43 48 45 20 66 6c 61 67 2e 0a 2a 2a 20 3c 2f  ACHE flag..** </
1fd20 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 53 70 65 63 69  ul>.**.** ^Speci
1fd30 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e  fying an unknown
1fd40 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68   parameter in th
1fd50 65 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e  e query componen
1fd60 74 20 6f 66 20 61 20 55 52 49 20 69 73 20 6e 6f  t of a URI is no
1fd70 74 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 2e 20 20  t an.** error.  
1fd80 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20  Future versions 
1fd90 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20  of SQLite might 
1fda0 75 6e 64 65 72 73 74 61 6e 64 20 61 64 64 69 74  understand addit
1fdb0 69 6f 6e 61 6c 20 71 75 65 72 79 0a 2a 2a 20 70  ional query.** p
1fdc0 61 72 61 6d 65 74 65 72 73 2e 20 20 53 65 65 20  arameters.  See 
1fdd0 22 5b 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  "[query paramete
1fde0 72 73 20 77 69 74 68 20 73 70 65 63 69 61 6c 20  rs with special 
1fdf0 6d 65 61 6e 69 6e 67 20 74 6f 20 53 51 4c 69 74  meaning to SQLit
1fe00 65 5d 22 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74  e]" for.** addit
1fe10 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f  ional informatio
1fe20 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66  n..**.** [[URI f
1fe30 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73  ilename examples
1fe40 5d 5d 20 3c 68 33 3e 55 52 49 20 66 69 6c 65 6e  ]] <h3>URI filen
1fe50 61 6d 65 20 65 78 61 6d 70 6c 65 73 3c 2f 68 33  ame examples</h3
1fe60 3e 0a 2a 2a 0a 2a 2a 20 3c 74 61 62 6c 65 20 62  >.**.** <table b
1fe70 6f 72 64 65 72 3d 22 31 22 20 61 6c 69 67 6e 3d  order="1" align=
1fe80 63 65 6e 74 65 72 20 63 65 6c 6c 70 61 64 64 69  center cellpaddi
1fe90 6e 67 3d 35 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68  ng=5>.** <tr><th
1fea0 3e 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20  > URI filenames 
1feb0 3c 74 68 3e 20 52 65 73 75 6c 74 73 0a 2a 2a 20  <th> Results.** 
1fec0 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61  <tr><td> file:da
1fed0 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20  ta.db <td> .**  
1fee0 20 20 20 20 20 20 20 20 4f 70 65 6e 20 74 68 65          Open the
1fef0 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20   file "data.db" 
1ff00 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 64  in the current d
1ff10 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 20 3c 74 72  irectory..** <tr
1ff20 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65  ><td> file:/home
1ff30 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 3c 62 72  /fred/data.db<br
1ff40 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69  >.**          fi
1ff50 6c 65 3a 2f 2f 2f 68 6f 6d 65 2f 66 72 65 64 2f  le:///home/fred/
1ff60 64 61 74 61 2e 64 62 20 3c 62 72 3e 20 0a 2a 2a  data.db <br> .**
1ff70 20 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f            file:/
1ff80 2f 6c 6f 63 61 6c 68 6f 73 74 2f 68 6f 6d 65 2f  /localhost/home/
1ff90 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 62 72  fred/data.db <br
1ffa0 3e 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20  > <td> .**      
1ffb0 20 20 20 20 4f 70 65 6e 20 74 68 65 20 64 61 74      Open the dat
1ffc0 61 62 61 73 65 20 66 69 6c 65 20 22 2f 68 6f 6d  abase file "/hom
1ffd0 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 22 2e  e/fred/data.db".
1ffe0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c  .** <tr><td> fil
1fff0 65 3a 2f 2f 64 61 72 6b 73 74 61 72 2f 68 6f 6d  e://darkstar/hom
20000 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c  e/fred/data.db <
20010 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  td> .**         
20020 20 41 6e 20 65 72 72 6f 72 2e 20 22 64 61 72 6b   An error. "dark
20030 73 74 61 72 22 20 69 73 20 6e 6f 74 20 61 20 72  star" is not a r
20040 65 63 6f 67 6e 69 7a 65 64 20 61 75 74 68 6f 72  ecognized author
20050 69 74 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 20  ity..** <tr><td 
20060 73 74 79 6c 65 3d 22 77 68 69 74 65 2d 73 70 61  style="white-spa
20070 63 65 3a 6e 6f 77 72 61 70 22 3e 20 0a 2a 2a 20  ce:nowrap"> .** 
20080 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f           file://
20090 2f 43 3a 2f 44 6f 63 75 6d 65 6e 74 73 25 32 30  /C:/Documents%20
200a0 61 6e 64 25 32 30 53 65 74 74 69 6e 67 73 2f 66  and%20Settings/f
200b0 72 65 64 2f 44 65 73 6b 74 6f 70 2f 64 61 74 61  red/Desktop/data
200c0 2e 64 62 0a 2a 2a 20 20 20 20 20 3c 74 64 3e 20  .db.**     <td> 
200d0 57 69 6e 64 6f 77 73 20 6f 6e 6c 79 3a 20 4f 70  Windows only: Op
200e0 65 6e 20 74 68 65 20 66 69 6c 65 20 22 64 61 74  en the file "dat
200f0 61 2e 64 62 22 20 6f 6e 20 66 72 65 64 27 73 20  a.db" on fred's 
20100 64 65 73 6b 74 6f 70 20 6f 6e 20 64 72 69 76 65  desktop on drive
20110 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 43 3a 2e  .**          C:.
20120 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 25   Note that the %
20130 32 30 20 65 73 63 61 70 69 6e 67 20 69 6e 20 74  20 escaping in t
20140 68 69 73 20 65 78 61 6d 70 6c 65 20 69 73 20 6e  his example is n
20150 6f 74 20 73 74 72 69 63 74 6c 79 20 0a 2a 2a 20  ot strictly .** 
20160 20 20 20 20 20 20 20 20 20 6e 65 63 65 73 73 61           necessa
20170 72 79 20 2d 20 73 70 61 63 65 20 63 68 61 72 61  ry - space chara
20180 63 74 65 72 73 20 63 61 6e 20 62 65 20 75 73 65  cters can be use
20190 64 20 6c 69 74 65 72 61 6c 6c 79 0a 2a 2a 20 20  d literally.**  
201a0 20 20 20 20 20 20 20 20 69 6e 20 55 52 49 20 66          in URI f
201b0 69 6c 65 6e 61 6d 65 73 2e 0a 2a 2a 20 3c 74 72  ilenames..** <tr
201c0 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e  ><td> file:data.
201d0 64 62 3f 6d 6f 64 65 3d 72 6f 26 63 61 63 68 65  db?mode=ro&cache
201e0 3d 70 72 69 76 61 74 65 20 3c 74 64 3e 20 0a 2a  =private <td> .*
201f0 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20  *          Open 
20200 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20 69  file "data.db" i
20210 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 69  n the current di
20220 72 65 63 74 6f 72 79 20 66 6f 72 20 72 65 61 64  rectory for read
20230 2d 6f 6e 6c 79 20 61 63 63 65 73 73 2e 0a 2a 2a  -only access..**
20240 20 20 20 20 20 20 20 20 20 20 52 65 67 61 72 64            Regard
20250 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20  less of whether 
20260 6f 72 20 6e 6f 74 20 73 68 61 72 65 64 2d 63 61  or not shared-ca
20270 63 68 65 20 6d 6f 64 65 20 69 73 20 65 6e 61 62  che mode is enab
20280 6c 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 20  led by.**       
20290 20 20 20 64 65 66 61 75 6c 74 2c 20 75 73 65 20     default, use 
202a0 61 20 70 72 69 76 61 74 65 20 63 61 63 68 65 2e  a private cache.
202b0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c  .** <tr><td> fil
202c0 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74  e:/home/fred/dat
202d0 61 2e 64 62 3f 76 66 73 3d 75 6e 69 78 2d 6e 6f  a.db?vfs=unix-no
202e0 6c 6f 63 6b 20 3c 74 64 3e 0a 2a 2a 20 20 20 20  lock <td>.**    
202f0 20 20 20 20 20 20 4f 70 65 6e 20 66 69 6c 65 20        Open file 
20300 22 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61  "/home/fred/data
20310 2e 64 62 22 2e 20 55 73 65 20 74 68 65 20 73 70  .db". Use the sp
20320 65 63 69 61 6c 20 56 46 53 20 22 75 6e 69 78 2d  ecial VFS "unix-
20330 6e 6f 6c 6f 63 6b 22 2e 0a 2a 2a 20 3c 74 72 3e  nolock"..** <tr>
20340 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64  <td> file:data.d
20350 62 3f 6d 6f 64 65 3d 72 65 61 64 6f 6e 6c 79 20  b?mode=readonly 
20360 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20  <td> .**        
20370 20 20 41 6e 20 65 72 72 6f 72 2e 20 22 72 65 61    An error. "rea
20380 64 6f 6e 6c 79 22 20 69 73 20 6e 6f 74 20 61 20  donly" is not a 
20390 76 61 6c 69 64 20 6f 70 74 69 6f 6e 20 66 6f 72  valid option for
203a0 20 74 68 65 20 22 6d 6f 64 65 22 20 70 61 72 61   the "mode" para
203b0 6d 65 74 65 72 2e 0a 2a 2a 20 3c 2f 74 61 62 6c  meter..** </tabl
203c0 65 3e 0a 2a 2a 0a 2a 2a 20 5e 55 52 49 20 68 65  e>.**.** ^URI he
203d0 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65  xadecimal escape
203e0 20 73 65 71 75 65 6e 63 65 73 20 28 25 48 48 29   sequences (%HH)
203f0 20 61 72 65 20 73 75 70 70 6f 72 74 65 64 20 77   are supported w
20400 69 74 68 69 6e 20 74 68 65 20 70 61 74 68 20 61  ithin the path a
20410 6e 64 0a 2a 2a 20 71 75 65 72 79 20 63 6f 6d 70  nd.** query comp
20420 6f 6e 65 6e 74 73 20 6f 66 20 61 20 55 52 49 2e  onents of a URI.
20430 20 41 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65   A hexadecimal e
20440 73 63 61 70 65 20 73 65 71 75 65 6e 63 65 20 63  scape sequence c
20450 6f 6e 73 69 73 74 73 20 6f 66 20 61 0a 2a 2a 20  onsists of a.** 
20460 70 65 72 63 65 6e 74 20 73 69 67 6e 20 2d 20 22  percent sign - "
20470 25 22 20 2d 20 66 6f 6c 6c 6f 77 65 64 20 62 79  %" - followed by
20480 20 65 78 61 63 74 6c 79 20 74 77 6f 20 68 65 78   exactly two hex
20490 61 64 65 63 69 6d 61 6c 20 64 69 67 69 74 73 20  adecimal digits 
204a0 0a 2a 2a 20 73 70 65 63 69 66 79 69 6e 67 20 61  .** specifying a
204b0 6e 20 6f 63 74 65 74 20 76 61 6c 75 65 2e 20 5e  n octet value. ^
204c0 42 65 66 6f 72 65 20 74 68 65 20 70 61 74 68 20  Before the path 
204d0 6f 72 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65  or query compone
204e0 6e 74 73 20 6f 66 20 61 0a 2a 2a 20 55 52 49 20  nts of a.** URI 
204f0 66 69 6c 65 6e 61 6d 65 20 61 72 65 20 69 6e 74  filename are int
20500 65 72 70 72 65 74 65 64 2c 20 74 68 65 79 20 61  erpreted, they a
20510 72 65 20 65 6e 63 6f 64 65 64 20 75 73 69 6e 67  re encoded using
20520 20 55 54 46 2d 38 20 61 6e 64 20 61 6c 6c 20 0a   UTF-8 and all .
20530 2a 2a 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65  ** hexadecimal e
20540 73 63 61 70 65 20 73 65 71 75 65 6e 63 65 73 20  scape sequences 
20550 72 65 70 6c 61 63 65 64 20 62 79 20 61 20 73 69  replaced by a si
20560 6e 67 6c 65 20 62 79 74 65 20 63 6f 6e 74 61 69  ngle byte contai
20570 6e 69 6e 67 20 74 68 65 0a 2a 2a 20 63 6f 72 72  ning the.** corr
20580 65 73 70 6f 6e 64 69 6e 67 20 6f 63 74 65 74 2e  esponding octet.
20590 20 49 66 20 74 68 69 73 20 70 72 6f 63 65 73 73   If this process
205a0 20 67 65 6e 65 72 61 74 65 73 20 61 6e 20 69 6e   generates an in
205b0 76 61 6c 69 64 20 55 54 46 2d 38 20 65 6e 63 6f  valid UTF-8 enco
205c0 64 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 72 65 73  ding,.** the res
205d0 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e  ults are undefin
205e0 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74  ed..**.** <b>Not
205f0 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 75 73 65  e to Windows use
20600 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 65 6e 63  rs:</b>  The enc
20610 6f 64 69 6e 67 20 75 73 65 64 20 66 6f 72 20 74  oding used for t
20620 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75  he filename argu
20630 6d 65 6e 74 0a 2a 2a 20 6f 66 20 73 71 6c 69 74  ment.** of sqlit
20640 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71  e3_open() and sq
20650 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
20660 6d 75 73 74 20 62 65 20 55 54 46 2d 38 2c 20 6e  must be UTF-8, n
20670 6f 74 20 77 68 61 74 65 76 65 72 0a 2a 2a 20 63  ot whatever.** c
20680 6f 64 65 70 61 67 65 20 69 73 20 63 75 72 72 65  odepage is curre
20690 6e 74 6c 79 20 64 65 66 69 6e 65 64 2e 20 20 46  ntly defined.  F
206a0 69 6c 65 6e 61 6d 65 73 20 63 6f 6e 74 61 69 6e  ilenames contain
206b0 69 6e 67 20 69 6e 74 65 72 6e 61 74 69 6f 6e 61  ing internationa
206c0 6c 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20  l.** characters 
206d0 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65  must be converte
206e0 64 20 74 6f 20 55 54 46 2d 38 20 70 72 69 6f 72  d to UTF-8 prior
206f0 20 74 6f 20 70 61 73 73 69 6e 67 20 74 68 65 6d   to passing them
20700 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33   into.** sqlite3
20710 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74  _open() or sqlit
20720 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2f  e3_open_v2()..*/
20730 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65  .int sqlite3_ope
20740 6e 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  n(.  const char 
20750 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20  *filename,   /* 
20760 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d  Database filenam
20770 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73  e (UTF-8) */.  s
20780 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20  qlite3 **ppDb   
20790 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53         /* OUT: S
207a0 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20  QLite db handle 
207b0 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  */.);.int sqlite
207c0 33 5f 6f 70 65 6e 31 36 28 0a 20 20 63 6f 6e 73  3_open16(.  cons
207d0 74 20 76 6f 69 64 20 2a 66 69 6c 65 6e 61 6d 65  t void *filename
207e0 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  ,   /* Database 
207f0 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 31 36  filename (UTF-16
20800 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a  ) */.  sqlite3 *
20810 2a 70 70 44 62 20 20 20 20 20 20 20 20 20 20 2f  *ppDb          /
20820 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62  * OUT: SQLite db
20830 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e   handle */.);.in
20840 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  t sqlite3_open_v
20850 32 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  2(.  const char 
20860 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20  *filename,   /* 
20870 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d  Database filenam
20880 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73  e (UTF-8) */.  s
20890 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 2c 20 20  qlite3 **ppDb,  
208a0 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53         /* OUT: S
208b0 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20  QLite db handle 
208c0 2a 2f 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c 20  */.  int flags, 
208d0 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
208e0 46 6c 61 67 73 20 2a 2f 0a 20 20 63 6f 6e 73 74  Flags */.  const
208f0 20 63 68 61 72 20 2a 7a 56 66 73 20 20 20 20 20   char *zVfs     
20900 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 56 46     /* Name of VF
20910 53 20 6d 6f 64 75 6c 65 20 74 6f 20 75 73 65 20  S module to use 
20920 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.);../*.** CAP
20930 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 56 61  I3REF: Obtain Va
20940 6c 75 65 73 20 46 6f 72 20 55 52 49 20 50 61 72  lues For URI Par
20950 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 54 68  ameters.**.** Th
20960 65 73 65 20 61 72 65 20 75 74 69 6c 69 74 79 20  ese are utility 
20970 72 6f 75 74 69 6e 65 73 2c 20 75 73 65 66 75 6c  routines, useful
20980 20 74 6f 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e   to VFS implemen
20990 74 61 74 69 6f 6e 73 2c 20 74 68 61 74 20 63 68  tations, that ch
209a0 65 63 6b 0a 2a 2a 20 74 6f 20 73 65 65 20 69 66  eck.** to see if
209b0 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65   a database file
209c0 20 77 61 73 20 61 20 55 52 49 20 74 68 61 74 20   was a URI that 
209d0 63 6f 6e 74 61 69 6e 65 64 20 61 20 73 70 65 63  contained a spec
209e0 69 66 69 63 20 71 75 65 72 79 20 0a 2a 2a 20 70  ific query .** p
209f0 61 72 61 6d 65 74 65 72 2c 20 61 6e 64 20 69 66  arameter, and if
20a00 20 73 6f 20 6f 62 74 61 69 6e 73 20 74 68 65 20   so obtains the 
20a10 76 61 6c 75 65 20 6f 66 20 74 68 61 74 20 71 75  value of that qu
20a20 65 72 79 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  ery parameter..*
20a30 2a 0a 2a 2a 20 49 66 20 46 20 69 73 20 74 68 65  *.** If F is the
20a40 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61   database filena
20a50 6d 65 20 70 6f 69 6e 74 65 72 20 70 61 73 73 65  me pointer passe
20a60 64 20 69 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e  d into the xOpen
20a70 28 29 20 6d 65 74 68 6f 64 20 6f 66 20 0a 2a 2a  () method of .**
20a80 20 61 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74   a VFS implement
20a90 61 74 69 6f 6e 20 77 68 65 6e 20 74 68 65 20 66  ation when the f
20aa0 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 74  lags parameter t
20ab0 6f 20 78 4f 70 65 6e 28 29 20 68 61 73 20 6f 6e  o xOpen() has on
20ac0 65 20 6f 72 20 0a 2a 2a 20 6d 6f 72 65 20 6f 66  e or .** more of
20ad0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   the [SQLITE_OPE
20ae0 4e 5f 55 52 49 5d 20 6f 72 20 5b 53 51 4c 49 54  N_URI] or [SQLIT
20af0 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 20  E_OPEN_MAIN_DB] 
20b00 62 69 74 73 20 73 65 74 20 61 6e 64 0a 2a 2a 20  bits set and.** 
20b10 50 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  P is the name of
20b20 20 74 68 65 20 71 75 65 72 79 20 70 61 72 61 6d   the query param
20b30 65 74 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 73 71  eter, then.** sq
20b40 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65  lite3_uri_parame
20b50 74 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73  ter(F,P) returns
20b60 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68   the value of th
20b70 65 20 50 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  e P.** parameter
20b80 20 69 66 20 69 74 20 65 78 69 73 74 73 20 6f 72   if it exists or
20b90 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
20ba0 69 66 20 50 20 64 6f 65 73 20 6e 6f 74 20 61 70  if P does not ap
20bb0 70 65 61 72 20 61 73 20 61 20 0a 2a 2a 20 71 75  pear as a .** qu
20bc0 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 6f 6e  ery parameter on
20bd0 20 46 2e 20 20 49 66 20 50 20 69 73 20 61 20 71   F.  If P is a q
20be0 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 6f  uery parameter o
20bf0 66 20 46 0a 2a 2a 20 68 61 73 20 6e 6f 20 65 78  f F.** has no ex
20c00 70 6c 69 63 69 74 20 76 61 6c 75 65 2c 20 74 68  plicit value, th
20c10 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70  en sqlite3_uri_p
20c20 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65  arameter(F,P) re
20c30 74 75 72 6e 73 0a 2a 2a 20 61 20 70 6f 69 6e 74  turns.** a point
20c40 65 72 20 74 6f 20 61 6e 20 65 6d 70 74 79 20 73  er to an empty s
20c50 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  tring..**.** The
20c60 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f   sqlite3_uri_boo
20c70 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74  lean(F,P,B) rout
20c80 69 6e 65 20 61 73 73 75 6d 65 73 20 74 68 61 74  ine assumes that
20c90 20 50 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e 0a   P is a boolean.
20ca0 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64  ** parameter and
20cb0 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 31   returns true (1
20cc0 29 20 6f 72 20 66 61 6c 73 65 20 28 30 29 20 61  ) or false (0) a
20cd0 63 63 6f 72 64 69 6e 67 20 74 6f 20 74 68 65 20  ccording to the 
20ce0 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 50 2e 20 20  value.** of P.  
20cf0 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  The sqlite3_uri_
20d00 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72  boolean(F,P,B) r
20d10 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
20d20 72 75 65 20 28 31 29 20 69 66 20 74 68 65 0a 2a  rue (1) if the.*
20d30 2a 20 76 61 6c 75 65 20 6f 66 20 71 75 65 72 79  * value of query
20d40 20 70 61 72 61 6d 65 74 65 72 20 50 20 69 73 20   parameter P is 
20d50 6f 6e 65 20 6f 66 20 22 79 65 73 22 2c 20 22 74  one of "yes", "t
20d60 72 75 65 22 2c 20 6f 72 20 22 6f 6e 22 20 69 6e  rue", or "on" in
20d70 20 61 6e 79 0a 2a 2a 20 63 61 73 65 20 6f 72 20   any.** case or 
20d80 69 66 20 74 68 65 20 76 61 6c 75 65 20 62 65 67  if the value beg
20d90 69 6e 73 20 77 69 74 68 20 61 20 6e 6f 6e 2d 7a  ins with a non-z
20da0 65 72 6f 20 6e 75 6d 62 65 72 2e 20 20 54 68 65  ero number.  The
20db0 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69   .** sqlite3_uri
20dc0 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20  _boolean(F,P,B) 
20dd0 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 73  routines returns
20de0 20 66 61 6c 73 65 20 28 30 29 20 69 66 20 74 68   false (0) if th
20df0 65 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 71 75  e value of.** qu
20e00 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 50 20  ery parameter P 
20e10 69 73 20 6f 6e 65 20 6f 66 20 22 6e 6f 22 2c 20  is one of "no", 
20e20 22 66 61 6c 73 65 22 2c 20 6f 72 20 22 6f 66 66  "false", or "off
20e30 22 20 69 6e 20 61 6e 79 20 63 61 73 65 20 6f 72  " in any case or
20e40 0a 2a 2a 20 69 66 20 74 68 65 20 76 61 6c 75 65  .** if the value
20e50 20 62 65 67 69 6e 73 20 77 69 74 68 20 61 20 6e   begins with a n
20e60 75 6d 65 72 69 63 20 7a 65 72 6f 2e 20 20 49 66  umeric zero.  If
20e70 20 50 20 69 73 20 6e 6f 74 20 61 20 71 75 65 72   P is not a quer
20e80 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 6f  y.** parameter o
20e90 6e 20 46 20 6f 72 20 69 66 20 74 68 65 20 76 61  n F or if the va
20ea0 6c 75 65 20 6f 66 20 50 20 69 73 20 64 6f 65 73  lue of P is does
20eb0 20 6e 6f 74 20 6d 61 74 63 68 20 61 6e 79 20 6f   not match any o
20ec0 66 20 74 68 65 0a 2a 2a 20 61 62 6f 76 65 2c 20  f the.** above, 
20ed0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69  then sqlite3_uri
20ee0 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20  _boolean(F,P,B) 
20ef0 72 65 74 75 72 6e 73 20 28 42 21 3d 30 29 2e 0a  returns (B!=0)..
20f00 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
20f10 33 5f 75 72 69 5f 69 6e 74 36 34 28 46 2c 50 2c  3_uri_int64(F,P,
20f20 44 29 20 72 6f 75 74 69 6e 65 20 63 6f 6e 76 65  D) routine conve
20f30 72 74 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66  rts the value of
20f40 20 50 20 69 6e 74 6f 20 61 0a 2a 2a 20 36 34 2d   P into a.** 64-
20f50 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67  bit signed integ
20f60 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20 74  er and returns t
20f70 68 61 74 20 69 6e 74 65 67 65 72 2c 20 6f 72 20  hat integer, or 
20f80 44 20 69 66 20 50 20 64 6f 65 73 20 6e 6f 74 0a  D if P does not.
20f90 2a 2a 20 65 78 69 73 74 2e 20 20 49 66 20 74 68  ** exist.  If th
20fa0 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69 73 20  e value of P is 
20fb0 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20  something other 
20fc0 74 68 61 6e 20 61 6e 20 69 6e 74 65 67 65 72 2c  than an integer,
20fd0 20 74 68 65 6e 0a 2a 2a 20 7a 65 72 6f 20 69 73   then.** zero is
20fe0 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 0a 2a   returned..** .*
20ff0 2a 20 49 66 20 46 20 69 73 20 61 20 4e 55 4c 4c  * If F is a NULL
21000 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 73   pointer, then s
21010 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d  qlite3_uri_param
21020 65 74 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e  eter(F,P) return
21030 73 20 4e 55 4c 4c 20 61 6e 64 0a 2a 2a 20 73 71  s NULL and.** sq
21040 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61  lite3_uri_boolea
21050 6e 28 46 2c 50 2c 42 29 20 72 65 74 75 72 6e 73  n(F,P,B) returns
21060 20 42 2e 20 20 49 66 20 46 20 69 73 20 6e 6f 74   B.  If F is not
21070 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
21080 61 6e 64 0a 2a 2a 20 69 73 20 6e 6f 74 20 61 20  and.** is not a 
21090 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 70 61  database file pa
210a0 74 68 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20 74  thname pointer t
210b0 68 61 74 20 53 51 4c 69 74 65 20 70 61 73 73 65  hat SQLite passe
210c0 64 20 69 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e  d into the xOpen
210d0 0a 2a 2a 20 56 46 53 20 6d 65 74 68 6f 64 2c 20  .** VFS method, 
210e0 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
210f0 72 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e  r of this routin
21100 65 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61  e is undefined a
21110 6e 64 20 70 72 6f 62 61 62 6c 79 0a 2a 2a 20 75  nd probably.** u
21120 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2f 0a 63  ndesirable..*/.c
21130 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
21140 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72  e3_uri_parameter
21150 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69  (const char *zFi
21160 6c 65 6e 61 6d 65 2c 20 63 6f 6e 73 74 20 63 68  lename, const ch
21170 61 72 20 2a 7a 50 61 72 61 6d 29 3b 0a 69 6e 74  ar *zParam);.int
21180 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f   sqlite3_uri_boo
21190 6c 65 61 6e 28 63 6f 6e 73 74 20 63 68 61 72 20  lean(const char 
211a0 2a 7a 46 69 6c 65 2c 20 63 6f 6e 73 74 20 63 68  *zFile, const ch
211b0 61 72 20 2a 7a 50 61 72 61 6d 2c 20 69 6e 74 20  ar *zParam, int 
211c0 62 44 65 66 61 75 6c 74 29 3b 0a 73 71 6c 69 74  bDefault);.sqlit
211d0 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
211e0 5f 75 72 69 5f 69 6e 74 36 34 28 63 6f 6e 73 74  _uri_int64(const
211f0 20 63 68 61 72 2a 2c 20 63 6f 6e 73 74 20 63 68   char*, const ch
21200 61 72 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  ar*, sqlite3_int
21210 36 34 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  64);.../*.** CAP
21220 49 33 52 45 46 3a 20 45 72 72 6f 72 20 43 6f 64  I3REF: Error Cod
21230 65 73 20 41 6e 64 20 4d 65 73 73 61 67 65 73 0a  es And Messages.
21240 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
21250 65 33 5f 65 72 72 63 6f 64 65 28 29 20 69 6e 74  e3_errcode() int
21260 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
21270 68 65 20 6e 75 6d 65 72 69 63 20 5b 72 65 73 75  he numeric [resu
21280 6c 74 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b  lt code] or.** [
21290 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
212a0 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 6d 6f  code] for the mo
212b0 73 74 20 72 65 63 65 6e 74 20 66 61 69 6c 65 64  st recent failed
212c0 20 73 71 6c 69 74 65 33 5f 2a 20 41 50 49 20 63   sqlite3_* API c
212d0 61 6c 6c 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65  all.** associate
212e0 64 20 77 69 74 68 20 61 20 5b 64 61 74 61 62 61  d with a [databa
212f0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20  se connection]. 
21300 49 66 20 61 20 70 72 69 6f 72 20 41 50 49 20 63  If a prior API c
21310 61 6c 6c 20 66 61 69 6c 65 64 0a 2a 2a 20 62 75  all failed.** bu
21320 74 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  t the most recen
21330 74 20 41 50 49 20 63 61 6c 6c 20 73 75 63 63 65  t API call succe
21340 65 64 65 64 2c 20 74 68 65 20 72 65 74 75 72 6e  eded, the return
21350 20 76 61 6c 75 65 20 66 72 6f 6d 0a 2a 2a 20 73   value from.** s
21360 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29  qlite3_errcode()
21370 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20   is undefined.  
21380 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74  ^The sqlite3_ext
21390 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29 0a  ended_errcode().
213a0 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  ** interface is 
213b0 74 68 65 20 73 61 6d 65 20 65 78 63 65 70 74 20  the same except 
213c0 74 68 61 74 20 69 74 20 61 6c 77 61 79 73 20 72  that it always r
213d0 65 74 75 72 6e 73 20 74 68 65 20 0a 2a 2a 20 5b  eturns the .** [
213e0 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
213f0 63 6f 64 65 5d 20 65 76 65 6e 20 77 68 65 6e 20  code] even when 
21400 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
21410 63 6f 64 65 73 20 61 72 65 0a 2a 2a 20 64 69 73  codes are.** dis
21420 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  abled..**.** ^Th
21430 65 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67  e sqlite3_errmsg
21440 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 65  () and sqlite3_e
21450 72 72 6d 73 67 31 36 28 29 20 72 65 74 75 72 6e  rrmsg16() return
21460 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67   English-languag
21470 65 0a 2a 2a 20 74 65 78 74 20 74 68 61 74 20 64  e.** text that d
21480 65 73 63 72 69 62 65 73 20 74 68 65 20 65 72 72  escribes the err
21490 6f 72 2c 20 61 73 20 65 69 74 68 65 72 20 55 54  or, as either UT
214a0 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 72 65  F-8 or UTF-16 re
214b0 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e  spectively..** ^
214c0 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20  (Memory to hold 
214d0 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  the error messag
214e0 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61  e string is mana
214f0 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a  ged internally..
21500 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
21510 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64  on does not need
21520 20 74 6f 20 77 6f 72 72 79 20 61 62 6f 75 74 20   to worry about 
21530 66 72 65 65 69 6e 67 20 74 68 65 20 72 65 73 75  freeing the resu
21540 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20  lt..** However, 
21550 74 68 65 20 65 72 72 6f 72 20 73 74 72 69 6e 67  the error string
21560 20 6d 69 67 68 74 20 62 65 20 6f 76 65 72 77 72   might be overwr
21570 69 74 74 65 6e 20 6f 72 20 64 65 61 6c 6c 6f 63  itten or dealloc
21580 61 74 65 64 20 62 79 0a 2a 2a 20 73 75 62 73 65  ated by.** subse
21590 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 6f  quent calls to o
215a0 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65  ther SQLite inte
215b0 72 66 61 63 65 20 66 75 6e 63 74 69 6f 6e 73 2e  rface functions.
215c0 29 5e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68  )^.**.** When th
215d0 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68  e serialized [th
215e0 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 69 73  reading mode] is
215f0 20 69 6e 20 75 73 65 2c 20 69 74 20 6d 69 67 68   in use, it migh
21600 74 20 62 65 20 74 68 65 0a 2a 2a 20 63 61 73 65  t be the.** case
21610 20 74 68 61 74 20 61 20 73 65 63 6f 6e 64 20 65   that a second e
21620 72 72 6f 72 20 6f 63 63 75 72 73 20 6f 6e 20 61  rror occurs on a
21630 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64   separate thread
21640 20 69 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74   in between.** t
21650 68 65 20 74 69 6d 65 20 6f 66 20 74 68 65 20 66  he time of the f
21660 69 72 73 74 20 65 72 72 6f 72 20 61 6e 64 20 74  irst error and t
21670 68 65 20 63 61 6c 6c 20 74 6f 20 74 68 65 73 65  he call to these
21680 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20   interfaces..** 
21690 57 68 65 6e 20 74 68 61 74 20 68 61 70 70 65 6e  When that happen
216a0 73 2c 20 74 68 65 20 73 65 63 6f 6e 64 20 65 72  s, the second er
216b0 72 6f 72 20 77 69 6c 6c 20 62 65 20 72 65 70 6f  ror will be repo
216c0 72 74 65 64 20 73 69 6e 63 65 20 74 68 65 73 65  rted since these
216d0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61  .** interfaces a
216e0 6c 77 61 79 73 20 72 65 70 6f 72 74 20 74 68 65  lways report the
216f0 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 72 65 73   most recent res
21700 75 6c 74 2e 20 20 54 6f 20 61 76 6f 69 64 0a 2a  ult.  To avoid.*
21710 2a 20 74 68 69 73 2c 20 65 61 63 68 20 74 68 72  * this, each thr
21720 65 61 64 20 63 61 6e 20 6f 62 74 61 69 6e 20 65  ead can obtain e
21730 78 63 6c 75 73 69 76 65 20 75 73 65 20 6f 66 20  xclusive use of 
21740 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
21750 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20 62  nnection] D.** b
21760 79 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69  y invoking [sqli
21770 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 5d  te3_mutex_enter]
21780 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74  ([sqlite3_db_mut
21790 65 78 5d 28 44 29 29 20 62 65 66 6f 72 65 20 62  ex](D)) before b
217a0 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20 74 6f 20 75  eginning.** to u
217b0 73 65 20 44 20 61 6e 64 20 69 6e 76 6f 6b 69 6e  se D and invokin
217c0 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  g [sqlite3_mutex
217d0 5f 6c 65 61 76 65 5d 28 5b 73 71 6c 69 74 65 33  _leave]([sqlite3
217e0 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 61  _db_mutex](D)) a
217f0 66 74 65 72 0a 2a 2a 20 61 6c 6c 20 63 61 6c 6c  fter.** all call
21800 73 20 74 6f 20 74 68 65 20 69 6e 74 65 72 66 61  s to the interfa
21810 63 65 73 20 6c 69 73 74 65 64 20 68 65 72 65 20  ces listed here 
21820 61 72 65 20 63 6f 6d 70 6c 65 74 65 64 2e 0a 2a  are completed..*
21830 2a 0a 2a 2a 20 49 66 20 61 6e 20 69 6e 74 65 72  *.** If an inter
21840 66 61 63 65 20 66 61 69 6c 73 20 77 69 74 68 20  face fails with 
21850 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2c 20 74  SQLITE_MISUSE, t
21860 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 69 6e  hat means the in
21870 74 65 72 66 61 63 65 0a 2a 2a 20 77 61 73 20 69  terface.** was i
21880 6e 76 6f 6b 65 64 20 69 6e 63 6f 72 72 65 63 74  nvoked incorrect
21890 6c 79 20 62 79 20 74 68 65 20 61 70 70 6c 69 63  ly by the applic
218a0 61 74 69 6f 6e 2e 20 20 49 6e 20 74 68 61 74 20  ation.  In that 
218b0 63 61 73 65 2c 20 74 68 65 0a 2a 2a 20 65 72 72  case, the.** err
218c0 6f 72 20 63 6f 64 65 20 61 6e 64 20 6d 65 73 73  or code and mess
218d0 61 67 65 20 6d 61 79 20 6f 72 20 6d 61 79 20 6e  age may or may n
218e0 6f 74 20 62 65 20 73 65 74 2e 0a 2a 2f 0a 69 6e  ot be set..*/.in
218f0 74 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64  t sqlite3_errcod
21900 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a  e(sqlite3 *db);.
21910 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65  int sqlite3_exte
21920 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 73 71 6c  nded_errcode(sql
21930 69 74 65 33 20 2a 64 62 29 3b 0a 63 6f 6e 73 74  ite3 *db);.const
21940 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65   char *sqlite3_e
21950 72 72 6d 73 67 28 73 71 6c 69 74 65 33 2a 29 3b  rrmsg(sqlite3*);
21960 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
21970 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 73 71  ite3_errmsg16(sq
21980 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  lite3*);../*.** 
21990 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20 53 74  CAPI3REF: SQL St
219a0 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a  atement Object.*
219b0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 65  * KEYWORDS: {pre
219c0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 7d  pared statement}
219d0 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   {prepared state
219e0 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20  ments}.**.** An 
219f0 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
21a00 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e   object represen
21a10 74 73 20 61 20 73 69 6e 67 6c 65 20 53 51 4c 20  ts a single SQL 
21a20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 54 68  statement..** Th
21a30 69 73 20 6f 62 6a 65 63 74 20 69 73 20 76 61 72  is object is var
21a40 69 6f 75 73 6c 79 20 6b 6e 6f 77 6e 20 61 73 20  iously known as 
21a50 61 20 22 70 72 65 70 61 72 65 64 20 73 74 61 74  a "prepared stat
21a60 65 6d 65 6e 74 22 20 6f 72 20 61 0a 2a 2a 20 22  ement" or a.** "
21a70 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20 73 74 61  compiled SQL sta
21a80 74 65 6d 65 6e 74 22 20 6f 72 20 73 69 6d 70 6c  tement" or simpl
21a90 79 20 61 73 20 61 20 22 73 74 61 74 65 6d 65 6e  y as a "statemen
21aa0 74 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69  t"..**.** The li
21ab0 66 65 20 6f 66 20 61 20 73 74 61 74 65 6d 65 6e  fe of a statemen
21ac0 74 20 6f 62 6a 65 63 74 20 67 6f 65 73 20 73 6f  t object goes so
21ad0 6d 65 74 68 69 6e 67 20 6c 69 6b 65 20 74 68 69  mething like thi
21ae0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a  s:.**.** <ol>.**
21af0 20 3c 6c 69 3e 20 43 72 65 61 74 65 20 74 68 65   <li> Create the
21b00 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73   object using [s
21b10 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
21b20 32 28 29 5d 20 6f 72 20 61 20 72 65 6c 61 74 65  2()] or a relate
21b30 64 0a 2a 2a 20 20 20 20 20 20 66 75 6e 63 74 69  d.**      functi
21b40 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e 64  on..** <li> Bind
21b50 20 76 61 6c 75 65 73 20 74 6f 20 5b 68 6f 73 74   values to [host
21b60 20 70 61 72 61 6d 65 74 65 72 73 5d 20 75 73 69   parameters] usi
21b70 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62  ng the sqlite3_b
21b80 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20 20 20 20  ind_*().**      
21b90 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 3c  interfaces..** <
21ba0 6c 69 3e 20 52 75 6e 20 74 68 65 20 53 51 4c 20  li> Run the SQL 
21bb0 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  by calling [sqli
21bc0 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 6e 65 20  te3_step()] one 
21bd0 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a  or more times..*
21be0 2a 20 3c 6c 69 3e 20 52 65 73 65 74 20 74 68 65  * <li> Reset the
21bf0 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67   statement using
21c00 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
21c10 29 5d 20 74 68 65 6e 20 67 6f 20 62 61 63 6b 0a  )] then go back.
21c20 2a 2a 20 20 20 20 20 20 74 6f 20 73 74 65 70 20  **      to step 
21c30 32 2e 20 20 44 6f 20 74 68 69 73 20 7a 65 72 6f  2.  Do this zero
21c40 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a   or more times..
21c50 2a 2a 20 3c 6c 69 3e 20 44 65 73 74 72 6f 79 20  ** <li> Destroy 
21c60 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67  the object using
21c70 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
21c80 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a  ze()]..** </ol>.
21c90 2a 2a 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20 64  **.** Refer to d
21ca0 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 6f 6e 20  ocumentation on 
21cb0 69 6e 64 69 76 69 64 75 61 6c 20 6d 65 74 68 6f  individual metho
21cc0 64 73 20 61 62 6f 76 65 20 66 6f 72 20 61 64 64  ds above for add
21cd0 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72  itional.** infor
21ce0 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64  mation..*/.typed
21cf0 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
21d00 33 5f 73 74 6d 74 20 73 71 6c 69 74 65 33 5f 73  3_stmt sqlite3_s
21d10 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  tmt;../*.** CAPI
21d20 33 52 45 46 3a 20 52 75 6e 2d 74 69 6d 65 20 4c  3REF: Run-time L
21d30 69 6d 69 74 73 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  imits.**.** ^(Th
21d40 69 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c  is interface all
21d50 6f 77 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20  ows the size of 
21d60 76 61 72 69 6f 75 73 20 63 6f 6e 73 74 72 75 63  various construc
21d70 74 73 20 74 6f 20 62 65 20 6c 69 6d 69 74 65 64  ts to be limited
21d80 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e 6e 65 63 74  .** on a connect
21d90 69 6f 6e 20 62 79 20 63 6f 6e 6e 65 63 74 69 6f  ion by connectio
21da0 6e 20 62 61 73 69 73 2e 20 20 54 68 65 20 66 69  n basis.  The fi
21db0 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73  rst parameter is
21dc0 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73   the.** [databas
21dd0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 68  e connection] wh
21de0 6f 73 65 20 6c 69 6d 69 74 20 69 73 20 74 6f 20  ose limit is to 
21df0 62 65 20 73 65 74 20 6f 72 20 71 75 65 72 69 65  be set or querie
21e00 64 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e  d.  The.** secon
21e10 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6f  d parameter is o
21e20 6e 65 20 6f 66 20 74 68 65 20 5b 6c 69 6d 69 74  ne of the [limit
21e30 20 63 61 74 65 67 6f 72 69 65 73 5d 20 74 68 61   categories] tha
21e40 74 20 64 65 66 69 6e 65 20 61 0a 2a 2a 20 63 6c  t define a.** cl
21e50 61 73 73 20 6f 66 20 63 6f 6e 73 74 72 75 63 74  ass of construct
21e60 73 20 74 6f 20 62 65 20 73 69 7a 65 20 6c 69 6d  s to be size lim
21e70 69 74 65 64 2e 20 20 54 68 65 20 74 68 69 72 64  ited.  The third
21e80 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
21e90 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d 69 74 20 66  e.** new limit f
21ea0 6f 72 20 74 68 61 74 20 63 6f 6e 73 74 72 75 63  or that construc
21eb0 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  t.)^.**.** ^If t
21ec0 68 65 20 6e 65 77 20 6c 69 6d 69 74 20 69 73 20  he new limit is 
21ed0 61 20 6e 65 67 61 74 69 76 65 20 6e 75 6d 62 65  a negative numbe
21ee0 72 2c 20 74 68 65 20 6c 69 6d 69 74 20 69 73 20  r, the limit is 
21ef0 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 5e 28  unchanged..** ^(
21f00 46 6f 72 20 65 61 63 68 20 6c 69 6d 69 74 20 63  For each limit c
21f10 61 74 65 67 6f 72 79 20 53 51 4c 49 54 45 5f 4c  ategory SQLITE_L
21f20 49 4d 49 54 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e  IMIT_<i>NAME</i>
21f30 20 74 68 65 72 65 20 69 73 20 61 20 0a 2a 2a 20   there is a .** 
21f40 5b 6c 69 6d 69 74 73 20 7c 20 68 61 72 64 20 75  [limits | hard u
21f50 70 70 65 72 20 62 6f 75 6e 64 5d 0a 2a 2a 20 73  pper bound].** s
21f60 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69  et at compile-ti
21f70 6d 65 20 62 79 20 61 20 43 20 70 72 65 70 72 6f  me by a C prepro
21f80 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 63 61 6c  cessor macro cal
21f90 6c 65 64 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c  led.** [limits |
21fa0 20 53 51 4c 49 54 45 5f 4d 41 58 5f 3c 69 3e 4e   SQLITE_MAX_<i>N
21fb0 41 4d 45 3c 2f 69 3e 5d 2e 0a 2a 2a 20 28 54 68  AME</i>]..** (Th
21fc0 65 20 22 5f 4c 49 4d 49 54 5f 22 20 69 6e 20 74  e "_LIMIT_" in t
21fd0 68 65 20 6e 61 6d 65 20 69 73 20 63 68 61 6e 67  he name is chang
21fe0 65 64 20 74 6f 20 22 5f 4d 41 58 5f 22 2e 29 29  ed to "_MAX_".))
21ff0 5e 0a 2a 2a 20 5e 41 74 74 65 6d 70 74 73 20 74  ^.** ^Attempts t
22000 6f 20 69 6e 63 72 65 61 73 65 20 61 20 6c 69 6d  o increase a lim
22010 69 74 20 61 62 6f 76 65 20 69 74 73 20 68 61 72  it above its har
22020 64 20 75 70 70 65 72 20 62 6f 75 6e 64 20 61 72  d upper bound ar
22030 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c 79 20 74 72  e.** silently tr
22040 75 6e 63 61 74 65 64 20 74 6f 20 74 68 65 20 68  uncated to the h
22050 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 2e  ard upper bound.
22060 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 61 72 64 6c 65  .**.** ^Regardle
22070 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72  ss of whether or
22080 20 6e 6f 74 20 74 68 65 20 6c 69 6d 69 74 20 77   not the limit w
22090 61 73 20 63 68 61 6e 67 65 64 2c 20 74 68 65 20  as changed, the 
220a0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d  .** [sqlite3_lim
220b0 69 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  it()] interface 
220c0 72 65 74 75 72 6e 73 20 74 68 65 20 70 72 69 6f  returns the prio
220d0 72 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 6c  r value of the l
220e0 69 6d 69 74 2e 0a 2a 2a 20 5e 48 65 6e 63 65 2c  imit..** ^Hence,
220f0 20 74 6f 20 66 69 6e 64 20 74 68 65 20 63 75 72   to find the cur
22100 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 20 61 20  rent value of a 
22110 6c 69 6d 69 74 20 77 69 74 68 6f 75 74 20 63 68  limit without ch
22120 61 6e 67 69 6e 67 20 69 74 2c 0a 2a 2a 20 73 69  anging it,.** si
22130 6d 70 6c 79 20 69 6e 76 6f 6b 65 20 74 68 69 73  mply invoke this
22140 20 69 6e 74 65 72 66 61 63 65 20 77 69 74 68 20   interface with 
22150 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
22160 74 65 72 20 73 65 74 20 74 6f 20 2d 31 2e 0a 2a  ter set to -1..*
22170 2a 0a 2a 2a 20 52 75 6e 2d 74 69 6d 65 20 6c 69  *.** Run-time li
22180 6d 69 74 73 20 61 72 65 20 69 6e 74 65 6e 64 65  mits are intende
22190 64 20 66 6f 72 20 75 73 65 20 69 6e 20 61 70 70  d for use in app
221a0 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6d  lications that m
221b0 61 6e 61 67 65 0a 2a 2a 20 62 6f 74 68 20 74 68  anage.** both th
221c0 65 69 72 20 6f 77 6e 20 69 6e 74 65 72 6e 61 6c  eir own internal
221d0 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 61 6c   database and al
221e0 73 6f 20 64 61 74 61 62 61 73 65 73 20 74 68 61  so databases tha
221f0 74 20 61 72 65 20 63 6f 6e 74 72 6f 6c 6c 65 64  t are controlled
22200 0a 2a 2a 20 62 79 20 75 6e 74 72 75 73 74 65 64  .** by untrusted
22210 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65   external source
22220 73 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 61  s.  An example a
22230 70 70 6c 69 63 61 74 69 6f 6e 20 6d 69 67 68 74  pplication might
22240 20 62 65 20 61 0a 2a 2a 20 77 65 62 20 62 72 6f   be a.** web bro
22250 77 73 65 72 20 74 68 61 74 20 68 61 73 20 69 74  wser that has it
22260 73 20 6f 77 6e 20 64 61 74 61 62 61 73 65 73 20  s own databases 
22270 66 6f 72 20 73 74 6f 72 69 6e 67 20 68 69 73 74  for storing hist
22280 6f 72 79 20 61 6e 64 0a 2a 2a 20 73 65 70 61 72  ory and.** separ
22290 61 74 65 20 64 61 74 61 62 61 73 65 73 20 63 6f  ate databases co
222a0 6e 74 72 6f 6c 6c 65 64 20 62 79 20 4a 61 76 61  ntrolled by Java
222b0 53 63 72 69 70 74 20 61 70 70 6c 69 63 61 74 69  Script applicati
222c0 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64 65 64 0a 2a  ons downloaded.*
222d0 2a 20 6f 66 66 20 74 68 65 20 49 6e 74 65 72 6e  * off the Intern
222e0 65 74 2e 20 20 54 68 65 20 69 6e 74 65 72 6e 61  et.  The interna
222f0 6c 20 64 61 74 61 62 61 73 65 73 20 63 61 6e 20  l databases can 
22300 62 65 20 67 69 76 65 6e 20 74 68 65 0a 2a 2a 20  be given the.** 
22310 6c 61 72 67 65 2c 20 64 65 66 61 75 6c 74 20 6c  large, default l
22320 69 6d 69 74 73 2e 20 20 44 61 74 61 62 61 73 65  imits.  Database
22330 73 20 6d 61 6e 61 67 65 64 20 62 79 20 65 78 74  s managed by ext
22340 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 20 63 61  ernal sources ca
22350 6e 0a 2a 2a 20 62 65 20 67 69 76 65 6e 20 6d 75  n.** be given mu
22360 63 68 20 73 6d 61 6c 6c 65 72 20 6c 69 6d 69 74  ch smaller limit
22370 73 20 64 65 73 69 67 6e 65 64 20 74 6f 20 70 72  s designed to pr
22380 65 76 65 6e 74 20 61 20 64 65 6e 69 61 6c 20 6f  event a denial o
22390 66 20 73 65 72 76 69 63 65 0a 2a 2a 20 61 74 74  f service.** att
223a0 61 63 6b 2e 20 20 44 65 76 65 6c 6f 70 65 72 73  ack.  Developers
223b0 20 6d 69 67 68 74 20 61 6c 73 6f 20 77 61 6e 74   might also want
223c0 20 74 6f 20 75 73 65 20 74 68 65 20 5b 73 71 6c   to use the [sql
223d0 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
223e0 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66  zer()].** interf
223f0 61 63 65 20 74 6f 20 66 75 72 74 68 65 72 20 63  ace to further c
22400 6f 6e 74 72 6f 6c 20 75 6e 74 72 75 73 74 65 64  ontrol untrusted
22410 20 53 51 4c 2e 20 20 54 68 65 20 73 69 7a 65 20   SQL.  The size 
22420 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 0a  of the database.
22430 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20 61 6e  ** created by an
22440 20 75 6e 74 72 75 73 74 65 64 20 73 63 72 69 70   untrusted scrip
22450 74 20 63 61 6e 20 62 65 20 63 6f 6e 74 61 69 6e  t can be contain
22460 65 64 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  ed using the.** 
22470 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d  [max_page_count]
22480 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a   [PRAGMA]..**.**
22490 20 4e 65 77 20 72 75 6e 2d 74 69 6d 65 20 6c 69   New run-time li
224a0 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 20 6d  mit categories m
224b0 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66  ay be added in f
224c0 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e 0a  uture releases..
224d0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c  */.int sqlite3_l
224e0 69 6d 69 74 28 73 71 6c 69 74 65 33 2a 2c 20 69  imit(sqlite3*, i
224f0 6e 74 20 69 64 2c 20 69 6e 74 20 6e 65 77 56 61  nt id, int newVa
22500 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  l);../*.** CAPI3
22510 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69  REF: Run-Time Li
22520 6d 69 74 20 43 61 74 65 67 6f 72 69 65 73 0a 2a  mit Categories.*
22530 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 6c 69 6d  * KEYWORDS: {lim
22540 69 74 20 63 61 74 65 67 6f 72 79 7d 20 7b 2a 6c  it category} {*l
22550 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 7d  imit categories}
22560 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e  .**.** These con
22570 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20 76 61  stants define va
22580 72 69 6f 75 73 20 70 65 72 66 6f 72 6d 61 6e 63  rious performanc
22590 65 20 6c 69 6d 69 74 73 0a 2a 2a 20 74 68 61 74  e limits.** that
225a0 20 63 61 6e 20 62 65 20 6c 6f 77 65 72 65 64 20   can be lowered 
225b0 61 74 20 72 75 6e 2d 74 69 6d 65 20 75 73 69 6e  at run-time usin
225c0 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  g [sqlite3_limit
225d0 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 79 6e 6f  ()]..** The syno
225e0 70 73 69 73 20 6f 66 20 74 68 65 20 6d 65 61 6e  psis of the mean
225f0 69 6e 67 73 20 6f 66 20 74 68 65 20 76 61 72 69  ings of the vari
22600 6f 75 73 20 6c 69 6d 69 74 73 20 69 73 20 73 68  ous limits is sh
22610 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a 20 41 64  own below..** Ad
22620 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61  ditional informa
22630 74 69 6f 6e 20 69 73 20 61 76 61 69 6c 61 62 6c  tion is availabl
22640 65 20 61 74 20 5b 6c 69 6d 69 74 73 20 7c 20 4c  e at [limits | L
22650 69 6d 69 74 73 20 69 6e 20 53 51 4c 69 74 65 5d  imits in SQLite]
22660 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20  ..**.** <dl>.** 
22670 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  [[SQLITE_LIMIT_L
22680 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51  ENGTH]] ^(<dt>SQ
22690 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54  LITE_LIMIT_LENGT
226a0 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  H</dt>.** <dd>Th
226b0 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f  e maximum size o
226c0 66 20 61 6e 79 20 73 74 72 69 6e 67 20 6f 72 20  f any string or 
226d0 42 4c 4f 42 20 6f 72 20 74 61 62 6c 65 20 72 6f  BLOB or table ro
226e0 77 2c 20 69 6e 20 62 79 74 65 73 2e 3c 64 64 3e  w, in bytes.<dd>
226f0 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
22700 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47  E_LIMIT_SQL_LENG
22710 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  TH]] ^(<dt>SQLIT
22720 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47  E_LIMIT_SQL_LENG
22730 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  TH</dt>.** <dd>T
22740 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  he maximum lengt
22750 68 20 6f 66 20 61 6e 20 53 51 4c 20 73 74 61 74  h of an SQL stat
22760 65 6d 65 6e 74 2c 20 69 6e 20 62 79 74 65 73 2e  ement, in bytes.
22770 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  </dd>)^.**.** [[
22780 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c  SQLITE_LIMIT_COL
22790 55 4d 4e 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  UMN]] ^(<dt>SQLI
227a0 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c  TE_LIMIT_COLUMN<
227b0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
227c0 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
227d0 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 74  f columns in a t
227e0 61 62 6c 65 20 64 65 66 69 6e 69 74 69 6f 6e 20  able definition 
227f0 6f 72 20 69 6e 20 74 68 65 0a 2a 2a 20 72 65 73  or in the.** res
22800 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45  ult set of a [SE
22810 4c 45 43 54 5d 20 6f 72 20 74 68 65 20 6d 61 78  LECT] or the max
22820 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63  imum number of c
22830 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e 20 69 6e 64  olumns in an ind
22840 65 78 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e 20 4f  ex.** or in an O
22850 52 44 45 52 20 42 59 20 6f 72 20 47 52 4f 55 50  RDER BY or GROUP
22860 20 42 59 20 63 6c 61 75 73 65 2e 3c 2f 64 64 3e   BY clause.</dd>
22870 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
22880 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50  E_LIMIT_EXPR_DEP
22890 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  TH]] ^(<dt>SQLIT
228a0 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50  E_LIMIT_EXPR_DEP
228b0 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  TH</dt>.** <dd>T
228c0 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68  he maximum depth
228d0 20 6f 66 20 74 68 65 20 70 61 72 73 65 20 74 72   of the parse tr
228e0 65 65 20 6f 6e 20 61 6e 79 20 65 78 70 72 65 73  ee on any expres
228f0 73 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  sion.</dd>)^.**.
22900 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
22910 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43  T_COMPOUND_SELEC
22920 54 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  T]] ^(<dt>SQLITE
22930 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f  _LIMIT_COMPOUND_
22940 53 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c  SELECT</dt>.** <
22950 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
22960 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20 69  umber of terms i
22970 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20 53 45 4c  n a compound SEL
22980 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f  ECT statement.</
22990 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
229a0 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f  LITE_LIMIT_VDBE_
229b0 4f 50 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  OP]] ^(<dt>SQLIT
229c0 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 3c  E_LIMIT_VDBE_OP<
229d0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
229e0 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
229f0 66 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 20 69  f instructions i
22a00 6e 20 61 20 76 69 72 74 75 61 6c 20 6d 61 63 68  n a virtual mach
22a10 69 6e 65 20 70 72 6f 67 72 61 6d 0a 2a 2a 20 75  ine program.** u
22a20 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74  sed to implement
22a30 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   an SQL statemen
22a40 74 2e 20 20 54 68 69 73 20 6c 69 6d 69 74 20 69  t.  This limit i
22a50 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 0a  s not currently.
22a60 2a 2a 20 65 6e 66 6f 72 63 65 64 2c 20 74 68 6f  ** enforced, tho
22a70 75 67 68 20 74 68 61 74 20 6d 69 67 68 74 20 62  ugh that might b
22a80 65 20 61 64 64 65 64 20 69 6e 20 73 6f 6d 65 20  e added in some 
22a90 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f  future release o
22aa0 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 3c 2f 64 64  f.** SQLite.</dd
22ab0 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
22ac0 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f  TE_LIMIT_FUNCTIO
22ad0 4e 5f 41 52 47 5d 5d 20 5e 28 3c 64 74 3e 53 51  N_ARG]] ^(<dt>SQ
22ae0 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54  LITE_LIMIT_FUNCT
22af0 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20  ION_ARG</dt>.** 
22b00 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
22b10 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65  number of argume
22b20 6e 74 73 20 6f 6e 20 61 20 66 75 6e 63 74 69 6f  nts on a functio
22b30 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  n.</dd>)^.**.** 
22b40 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41  [[SQLITE_LIMIT_A
22b50 54 54 41 43 48 45 44 5d 5d 20 5e 28 3c 64 74 3e  TTACHED]] ^(<dt>
22b60 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54  SQLITE_LIMIT_ATT
22b70 41 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ACHED</dt>.** <d
22b80 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d>The maximum nu
22b90 6d 62 65 72 20 6f 66 20 5b 41 54 54 41 43 48 20  mber of [ATTACH 
22ba0 7c 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62  | attached datab
22bb0 61 73 65 73 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a  ases].)^</dd>.**
22bc0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
22bd0 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f  IT_LIKE_PATTERN_
22be0 4c 45 4e 47 54 48 5d 5d 0a 2a 2a 20 5e 28 3c 64  LENGTH]].** ^(<d
22bf0 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  t>SQLITE_LIMIT_L
22c00 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47  IKE_PATTERN_LENG
22c10 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  TH</dt>.** <dd>T
22c20 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  he maximum lengt
22c30 68 20 6f 66 20 74 68 65 20 70 61 74 74 65 72 6e  h of the pattern
22c40 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
22c50 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a 2a 20 5b 47   [LIKE] or.** [G
22c60 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 73 2e 3c  LOB] operators.<
22c70 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  /dd>)^.**.** [[S
22c80 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49  QLITE_LIMIT_VARI
22c90 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 5d 0a 2a 2a  ABLE_NUMBER]].**
22ca0 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
22cb0 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d  MIT_VARIABLE_NUM
22cc0 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  BER</dt>.** <dd>
22cd0 54 68 65 20 6d 61 78 69 6d 75 6d 20 69 6e 64 65  The maximum inde
22ce0 78 20 6e 75 6d 62 65 72 20 6f 66 20 61 6e 79 20  x number of any 
22cf0 5b 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 61  [parameter] in a
22d00 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e  n SQL statement.
22d10 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
22d20 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f  E_LIMIT_TRIGGER_
22d30 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51  DEPTH]] ^(<dt>SQ
22d40 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47  LITE_LIMIT_TRIGG
22d50 45 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a  ER_DEPTH</dt>.**
22d60 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
22d70 20 64 65 70 74 68 20 6f 66 20 72 65 63 75 72 73   depth of recurs
22d80 69 6f 6e 20 66 6f 72 20 74 72 69 67 67 65 72 73  ion for triggers
22d90 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c  .</dd>)^.** </dl
22da0 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  >.*/.#define SQL
22db0 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48  ITE_LIMIT_LENGTH
22dc0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
22dd0 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51      0.#define SQ
22de0 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c  LITE_LIMIT_SQL_L
22df0 45 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 20  ENGTH           
22e00 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53       1.#define S
22e10 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55  QLITE_LIMIT_COLU
22e20 4d 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 20  MN              
22e30 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20        2.#define 
22e40 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50  SQLITE_LIMIT_EXP
22e50 52 5f 44 45 50 54 48 20 20 20 20 20 20 20 20 20  R_DEPTH         
22e60 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65         3.#define
22e70 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f   SQLITE_LIMIT_CO
22e80 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 20 20 20  MPOUND_SELECT   
22e90 20 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e          4.#defin
22ea0 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56  e SQLITE_LIMIT_V
22eb0 44 42 45 5f 4f 50 20 20 20 20 20 20 20 20 20 20  DBE_OP          
22ec0 20 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 69           5.#defi
22ed0 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
22ee0 46 55 4e 43 54 49 4f 4e 5f 41 52 47 20 20 20 20  FUNCTION_ARG    
22ef0 20 20 20 20 20 20 20 20 20 20 36 0a 23 64 65 66            6.#def
22f00 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
22f10 5f 41 54 54 41 43 48 45 44 20 20 20 20 20 20 20  _ATTACHED       
22f20 20 20 20 20 20 20 20 20 20 20 20 37 0a 23 64 65             7.#de
22f30 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
22f40 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c  T_LIKE_PATTERN_L
22f50 45 4e 47 54 48 20 20 20 20 20 20 20 38 0a 23 64  ENGTH       8.#d
22f60 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
22f70 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42  IT_VARIABLE_NUMB
22f80 45 52 20 20 20 20 20 20 20 20 20 20 20 39 0a 23  ER           9.#
22f90 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
22fa0 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54  MIT_TRIGGER_DEPT
22fb0 48 20 20 20 20 20 20 20 20 20 20 20 20 31 30 0a  H            10.
22fc0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
22fd0 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53 51   Compiling An SQ
22fe0 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4b  L Statement.** K
22ff0 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 73 74  EYWORDS: {SQL st
23000 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72  atement compiler
23010 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 75  }.**.** To execu
23020 74 65 20 61 6e 20 53 51 4c 20 71 75 65 72 79 2c  te an SQL query,
23030 20 69 74 20 6d 75 73 74 20 66 69 72 73 74 20 62   it must first b
23040 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20  e compiled into 
23050 61 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70  a byte-code.** p
23060 72 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65  rogram using one
23070 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
23080 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  es..**.** The fi
23090 72 73 74 20 61 72 67 75 6d 65 6e 74 2c 20 22 64  rst argument, "d
230a0 62 22 2c 20 69 73 20 61 20 5b 64 61 74 61 62 61  b", is a [databa
230b0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f  se connection] o
230c0 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 0a 2a  btained from a.*
230d0 2a 20 70 72 69 6f 72 20 73 75 63 63 65 73 73 66  * prior successf
230e0 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  ul call to [sqli
230f0 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71  te3_open()], [sq
23100 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
23110 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
23120 6f 70 65 6e 31 36 28 29 5d 2e 20 20 54 68 65 20  open16()].  The 
23130 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
23140 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 68 61 76  ion must not hav
23150 65 20 62 65 65 6e 20 63 6c 6f 73 65 64 2e 0a 2a  e been closed..*
23160 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  *.** The second 
23170 61 72 67 75 6d 65 6e 74 2c 20 22 7a 53 71 6c 22  argument, "zSql"
23180 2c 20 69 73 20 74 68 65 20 73 74 61 74 65 6d 65  , is the stateme
23190 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65  nt to be compile
231a0 64 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 73  d, encoded.** as
231b0 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72   either UTF-8 or
231c0 20 55 54 46 2d 31 36 2e 20 20 54 68 65 20 73 71   UTF-16.  The sq
231d0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 20  lite3_prepare() 
231e0 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70  and sqlite3_prep
231f0 61 72 65 5f 76 32 28 29 0a 2a 2a 20 69 6e 74 65  are_v2().** inte
23200 72 66 61 63 65 73 20 75 73 65 20 55 54 46 2d 38  rfaces use UTF-8
23210 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72  , and sqlite3_pr
23220 65 70 61 72 65 31 36 28 29 20 61 6e 64 20 73 71  epare16() and sq
23230 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
23240 76 32 28 29 0a 2a 2a 20 75 73 65 20 55 54 46 2d  v2().** use UTF-
23250 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  16..**.** ^If th
23260 65 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e 74  e nByte argument
23270 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 7a 65   is less than ze
23280 72 6f 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69 73  ro, then zSql is
23290 20 72 65 61 64 20 75 70 20 74 6f 20 74 68 65 0a   read up to the.
232a0 2a 2a 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65  ** first zero te
232b0 72 6d 69 6e 61 74 6f 72 2e 20 5e 49 66 20 6e 42  rminator. ^If nB
232c0 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74  yte is non-negat
232d0 69 76 65 2c 20 74 68 65 6e 20 69 74 20 69 73 20  ive, then it is 
232e0 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 6e  the maximum.** n
232f0 75 6d 62 65 72 20 6f 66 20 20 62 79 74 65 73 20  umber of  bytes 
23300 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 20  read from zSql. 
23310 20 5e 57 68 65 6e 20 6e 42 79 74 65 20 69 73 20   ^When nByte is 
23320 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68  non-negative, th
23330 65 0a 2a 2a 20 7a 53 71 6c 20 73 74 72 69 6e 67  e.** zSql string
23340 20 65 6e 64 73 20 61 74 20 65 69 74 68 65 72 20   ends at either 
23350 74 68 65 20 66 69 72 73 74 20 27 5c 30 30 30 27  the first '\000'
23360 20 6f 72 20 27 5c 75 30 30 30 30 27 20 63 68 61   or '\u0000' cha
23370 72 61 63 74 65 72 20 6f 72 0a 2a 2a 20 74 68 65  racter or.** the
23380 20 6e 42 79 74 65 2d 74 68 20 62 79 74 65 2c 20   nByte-th byte, 
23390 77 68 69 63 68 65 76 65 72 20 63 6f 6d 65 73 20  whichever comes 
233a0 66 69 72 73 74 2e 20 49 66 20 74 68 65 20 63 61  first. If the ca
233b0 6c 6c 65 72 20 6b 6e 6f 77 73 0a 2a 2a 20 74 68  ller knows.** th
233c0 61 74 20 74 68 65 20 73 75 70 70 6c 69 65 64 20  at the supplied 
233d0 73 74 72 69 6e 67 20 69 73 20 6e 75 6c 2d 74 65  string is nul-te
233e0 72 6d 69 6e 61 74 65 64 2c 20 74 68 65 6e 20 74  rminated, then t
233f0 68 65 72 65 20 69 73 20 61 20 73 6d 61 6c 6c 0a  here is a small.
23400 2a 2a 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 61  ** performance a
23410 64 76 61 6e 74 61 67 65 20 74 6f 20 62 65 20 67  dvantage to be g
23420 61 69 6e 65 64 20 62 79 20 70 61 73 73 69 6e 67  ained by passing
23430 20 61 6e 20 6e 42 79 74 65 20 70 61 72 61 6d 65   an nByte parame
23440 74 65 72 20 74 68 61 74 0a 2a 2a 20 69 73 20 65  ter that.** is e
23450 71 75 61 6c 20 74 6f 20 74 68 65 20 6e 75 6d 62  qual to the numb
23460 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
23470 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 20  he input string 
23480 3c 69 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e  <i>including</i>
23490 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d 74 65 72 6d  .** the nul-term
234a0 69 6e 61 74 6f 72 20 62 79 74 65 73 20 61 73 20  inator bytes as 
234b0 74 68 69 73 20 73 61 76 65 73 20 53 51 4c 69 74  this saves SQLit
234c0 65 20 66 72 6f 6d 20 68 61 76 69 6e 67 20 74 6f  e from having to
234d0 0a 2a 2a 20 6d 61 6b 65 20 61 20 63 6f 70 79 20  .** make a copy 
234e0 6f 66 20 74 68 65 20 69 6e 70 75 74 20 73 74 72  of the input str
234f0 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 70  ing..**.** ^If p
23500 7a 54 61 69 6c 20 69 73 20 6e 6f 74 20 4e 55 4c  zTail is not NUL
23510 4c 20 74 68 65 6e 20 2a 70 7a 54 61 69 6c 20 69  L then *pzTail i
23520 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20  s made to point 
23530 74 6f 20 74 68 65 20 66 69 72 73 74 20 62 79 74  to the first byt
23540 65 0a 2a 2a 20 70 61 73 74 20 74 68 65 20 65 6e  e.** past the en
23550 64 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 53  d of the first S
23560 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20  QL statement in 
23570 7a 53 71 6c 2e 20 20 54 68 65 73 65 20 72 6f 75  zSql.  These rou
23580 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a 2a 20 63 6f  tines only.** co
23590 6d 70 69 6c 65 20 74 68 65 20 66 69 72 73 74 20  mpile the first 
235a0 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71  statement in zSq
235b0 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c 20 69 73  l, so *pzTail is
235c0 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74   left pointing t
235d0 6f 0a 2a 2a 20 77 68 61 74 20 72 65 6d 61 69 6e  o.** what remain
235e0 73 20 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a  s uncompiled..**
235f0 0a 2a 2a 20 5e 2a 70 70 53 74 6d 74 20 69 73 20  .** ^*ppStmt is 
23600 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f  left pointing to
23610 20 61 20 63 6f 6d 70 69 6c 65 64 20 5b 70 72 65   a compiled [pre
23620 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
23630 20 74 68 61 74 20 63 61 6e 20 62 65 0a 2a 2a 20   that can be.** 
23640 65 78 65 63 75 74 65 64 20 75 73 69 6e 67 20 5b  executed using [
23650 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e  sqlite3_step()].
23660 20 20 5e 49 66 20 74 68 65 72 65 20 69 73 20 61    ^If there is a
23670 6e 20 65 72 72 6f 72 2c 20 2a 70 70 53 74 6d 74  n error, *ppStmt
23680 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f 20 4e 55   is set.** to NU
23690 4c 4c 2e 20 20 5e 49 66 20 74 68 65 20 69 6e 70  LL.  ^If the inp
236a0 75 74 20 74 65 78 74 20 63 6f 6e 74 61 69 6e 73  ut text contains
236b0 20 6e 6f 20 53 51 4c 20 28 69 66 20 74 68 65 20   no SQL (if the 
236c0 69 6e 70 75 74 20 69 73 20 61 6e 20 65 6d 70 74  input is an empt
236d0 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 72 20 61  y.** string or a
236e0 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65 6e 20 2a   comment) then *
236f0 70 70 53 74 6d 74 20 69 73 20 73 65 74 20 74 6f  ppStmt is set to
23700 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65 20 63 61   NULL..** The ca
23710 6c 6c 69 6e 67 20 70 72 6f 63 65 64 75 72 65 20  lling procedure 
23720 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66  is responsible f
23730 6f 72 20 64 65 6c 65 74 69 6e 67 20 74 68 65 20  or deleting the 
23740 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53 51 4c 20  compiled.** SQL 
23750 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20  statement using 
23760 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
23770 65 28 29 5d 20 61 66 74 65 72 20 69 74 20 68 61  e()] after it ha
23780 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20  s finished with 
23790 69 74 2e 0a 2a 2a 20 70 70 53 74 6d 74 20 6d 61  it..** ppStmt ma
237a0 79 20 6e 6f 74 20 62 65 20 4e 55 4c 4c 2e 0a 2a  y not be NULL..*
237b0 2a 0a 2a 2a 20 5e 4f 6e 20 73 75 63 63 65 73 73  *.** ^On success
237c0 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 70 72  , the sqlite3_pr
237d0 65 70 61 72 65 28 29 20 66 61 6d 69 6c 79 20 6f  epare() family o
237e0 66 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  f routines retur
237f0 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 3b 0a 2a  n [SQLITE_OK];.*
23800 2a 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20 5b  * otherwise an [
23810 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72  error code] is r
23820 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  eturned..**.** T
23830 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  he sqlite3_prepa
23840 72 65 5f 76 32 28 29 20 61 6e 64 20 73 71 6c 69  re_v2() and sqli
23850 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
23860 28 29 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  () interfaces ar
23870 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e 64 65 64  e.** recommended
23880 20 66 6f 72 20 61 6c 6c 20 6e 65 77 20 70 72 6f   for all new pro
23890 67 72 61 6d 73 2e 20 54 68 65 20 74 77 6f 20 6f  grams. The two o
238a0 6c 64 65 72 20 69 6e 74 65 72 66 61 63 65 73 20  lder interfaces 
238b0 61 72 65 20 72 65 74 61 69 6e 65 64 0a 2a 2a 20  are retained.** 
238c0 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f  for backwards co
238d0 6d 70 61 74 69 62 69 6c 69 74 79 2c 20 62 75 74  mpatibility, but
238e0 20 74 68 65 69 72 20 75 73 65 20 69 73 20 64 69   their use is di
238f0 73 63 6f 75 72 61 67 65 64 2e 0a 2a 2a 20 5e 49  scouraged..** ^I
23900 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72  n the "v2" inter
23910 66 61 63 65 73 2c 20 74 68 65 20 70 72 65 70 61  faces, the prepa
23920 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a  red statement.**
23930 20 74 68 61 74 20 69 73 20 72 65 74 75 72 6e 65   that is returne
23940 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  d (the [sqlite3_
23950 73 74 6d 74 5d 20 6f 62 6a 65 63 74 29 20 63 6f  stmt] object) co
23960 6e 74 61 69 6e 73 20 61 20 63 6f 70 79 20 6f 66  ntains a copy of
23970 20 74 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c   the.** original
23980 20 53 51 4c 20 74 65 78 74 2e 20 54 68 69 73 20   SQL text. This 
23990 63 61 75 73 65 73 20 74 68 65 20 5b 73 71 6c 69  causes the [sqli
239a0 74 65 33 5f 73 74 65 70 28 29 5d 20 69 6e 74 65  te3_step()] inte
239b0 72 66 61 63 65 20 74 6f 0a 2a 2a 20 62 65 68 61  rface to.** beha
239c0 76 65 20 64 69 66 66 65 72 65 6e 74 6c 79 20 69  ve differently i
239d0 6e 20 74 68 72 65 65 20 77 61 79 73 3a 0a 2a 2a  n three ways:.**
239e0 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ol>.** <li>
239f0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64 61 74 61  .** ^If the data
23a00 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e  base schema chan
23a10 67 65 73 2c 20 69 6e 73 74 65 61 64 20 6f 66 20  ges, instead of 
23a20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54  returning [SQLIT
23a30 45 5f 53 43 48 45 4d 41 5d 20 61 73 20 69 74 0a  E_SCHEMA] as it.
23a40 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 64 20 74  ** always used t
23a50 6f 20 64 6f 2c 20 5b 73 71 6c 69 74 65 33 5f 73  o do, [sqlite3_s
23a60 74 65 70 28 29 5d 20 77 69 6c 6c 20 61 75 74 6f  tep()] will auto
23a70 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70  matically recomp
23a80 69 6c 65 20 74 68 65 20 53 51 4c 0a 2a 2a 20 73  ile the SQL.** s
23a90 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 72 79  tatement and try
23aa0 20 74 6f 20 72 75 6e 20 69 74 20 61 67 61 69 6e   to run it again
23ab0 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a  ..** </li>.**.**
23ac0 20 3c 6c 69 3e 0a 2a 2a 20 5e 57 68 65 6e 20 61   <li>.** ^When a
23ad0 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2c 20  n error occurs, 
23ae0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
23af0 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6f 6e 65   will return one
23b00 20 6f 66 20 74 68 65 20 64 65 74 61 69 6c 65 64   of the detailed
23b10 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 73  .** [error codes
23b20 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 65  ] or [extended e
23b30 72 72 6f 72 20 63 6f 64 65 73 5d 2e 20 20 5e 54  rror codes].  ^T
23b40 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 69  he legacy behavi
23b50 6f 72 20 77 61 73 20 74 68 61 74 0a 2a 2a 20 5b  or was that.** [
23b60 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
23b70 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65 74 75 72  would only retur
23b80 6e 20 61 20 67 65 6e 65 72 69 63 20 5b 53 51 4c  n a generic [SQL
23b90 49 54 45 5f 45 52 52 4f 52 5d 20 72 65 73 75 6c  ITE_ERROR] resul
23ba0 74 20 63 6f 64 65 0a 2a 2a 20 61 6e 64 20 74 68  t code.** and th
23bb0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 77 6f  e application wo
23bc0 75 6c 64 20 68 61 76 65 20 74 6f 20 6d 61 6b 65  uld have to make
23bd0 20 61 20 73 65 63 6f 6e 64 20 63 61 6c 6c 20 74   a second call t
23be0 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  o [sqlite3_reset
23bf0 28 29 5d 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20  ()].** in order 
23c00 74 6f 20 66 69 6e 64 20 74 68 65 20 75 6e 64 65  to find the unde
23c10 72 6c 79 69 6e 67 20 63 61 75 73 65 20 6f 66 20  rlying cause of 
23c20 74 68 65 20 70 72 6f 62 6c 65 6d 2e 20 57 69 74  the problem. Wit
23c30 68 20 74 68 65 20 22 76 32 22 20 70 72 65 70 61  h the "v2" prepa
23c40 72 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  re.** interfaces
23c50 2c 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67  , the underlying
23c60 20 72 65 61 73 6f 6e 20 66 6f 72 20 74 68 65 20   reason for the 
23c70 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65  error is returne
23c80 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a  d immediately..*
23c90 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c  * </li>.**.** <l
23ca0 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73 70  i>.** ^If the sp
23cb0 65 63 69 66 69 63 20 76 61 6c 75 65 20 62 6f 75  ecific value bou
23cc0 6e 64 20 74 6f 20 5b 70 61 72 61 6d 65 74 65 72  nd to [parameter
23cd0 20 7c 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65   | host paramete
23ce0 72 5d 20 69 6e 20 74 68 65 20 0a 2a 2a 20 57 48  r] in the .** WH
23cf0 45 52 45 20 63 6c 61 75 73 65 20 6d 69 67 68 74  ERE clause might
23d00 20 69 6e 66 6c 75 65 6e 63 65 20 74 68 65 20 63   influence the c
23d10 68 6f 69 63 65 20 6f 66 20 71 75 65 72 79 20 70  hoice of query p
23d20 6c 61 6e 20 66 6f 72 20 61 20 73 74 61 74 65 6d  lan for a statem
23d30 65 6e 74 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ent,.** then the
23d40 20 73 74 61 74 65 6d 65 6e 74 20 77 69 6c 6c 20   statement will 
23d50 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  be automatically
23d60 20 72 65 63 6f 6d 70 69 6c 65 64 2c 20 61 73 20   recompiled, as 
23d70 69 66 20 74 68 65 72 65 20 68 61 64 20 62 65 65  if there had bee
23d80 6e 20 0a 2a 2a 20 61 20 73 63 68 65 6d 61 20 63  n .** a schema c
23d90 68 61 6e 67 65 2c 20 6f 6e 20 74 68 65 20 66 69  hange, on the fi
23da0 72 73 74 20 20 5b 73 71 6c 69 74 65 33 5f 73 74  rst  [sqlite3_st
23db0 65 70 28 29 5d 20 63 61 6c 6c 20 66 6f 6c 6c 6f  ep()] call follo
23dc0 77 69 6e 67 20 61 6e 79 20 63 68 61 6e 67 65 0a  wing any change.
23dd0 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  ** to the [sqlit
23de0 65 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20 62  e3_bind_text | b
23df0 69 6e 64 69 6e 67 73 5d 20 6f 66 20 74 68 61 74  indings] of that
23e00 20 5b 70 61 72 61 6d 65 74 65 72 5d 2e 20 0a 2a   [parameter]. .*
23e10 2a 20 5e 54 68 65 20 73 70 65 63 69 66 69 63 20  * ^The specific 
23e20 76 61 6c 75 65 20 6f 66 20 57 48 45 52 45 2d 63  value of WHERE-c
23e30 6c 61 75 73 65 20 5b 70 61 72 61 6d 65 74 65 72  lause [parameter
23e40 5d 20 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e 63  ] might influenc
23e50 65 20 74 68 65 20 0a 2a 2a 20 63 68 6f 69 63 65  e the .** choice
23e60 20 6f 66 20 71 75 65 72 79 20 70 6c 61 6e 20 69   of query plan i
23e70 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
23e80 69 73 20 74 68 65 20 6c 65 66 74 2d 68 61 6e 64  is the left-hand
23e90 20 73 69 64 65 20 6f 66 20 61 20 5b 4c 49 4b 45   side of a [LIKE
23ea0 5d 0a 2a 2a 20 6f 72 20 5b 47 4c 4f 42 5d 20 6f  ].** or [GLOB] o
23eb0 70 65 72 61 74 6f 72 20 6f 72 20 69 66 20 74 68  perator or if th
23ec0 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 63  e parameter is c
23ed0 6f 6d 70 61 72 65 64 20 74 6f 20 61 6e 20 69 6e  ompared to an in
23ee0 64 65 78 65 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  dexed column.** 
23ef0 61 6e 64 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  and the [SQLITE_
23f00 45 4e 41 42 4c 45 5f 53 54 41 54 33 5d 20 63 6f  ENABLE_STAT3] co
23f10 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
23f20 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a  n is enabled..**
23f30 20 74 68 65 20 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a   the .** </li>.*
23f40 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 69 6e 74 20 73  * </ol>.*/.int s
23f50 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 0a  qlite3_prepare(.
23f60 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
23f70 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
23f80 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a  abase handle */.
23f90 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53    const char *zS
23fa0 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c  ql,       /* SQL
23fb0 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d   statement, UTF-
23fc0 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69  8 encoded */.  i
23fd0 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20  nt nByte,       
23fe0 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75         /* Maximu
23ff0 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c  m length of zSql
24000 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20   in bytes. */.  
24010 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70  sqlite3_stmt **p
24020 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20  pStmt,  /* OUT: 
24030 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65  Statement handle
24040 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
24050 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a   **pzTail     /*
24060 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f   OUT: Pointer to
24070 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20   unused portion 
24080 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e  of zSql */.);.in
24090 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  t sqlite3_prepar
240a0 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20  e_v2(.  sqlite3 
240b0 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
240c0 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64  /* Database hand
240d0 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  le */.  const ch
240e0 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20  ar *zSql,       
240f0 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  /* SQL statement
24100 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20  , UTF-8 encoded 
24110 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20  */.  int nByte, 
24120 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
24130 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  Maximum length o
24140 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e  f zSql in bytes.
24150 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74   */.  sqlite3_st
24160 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a  mt **ppStmt,  /*
24170 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20   OUT: Statement 
24180 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
24190 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20  t char **pzTail 
241a0 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e      /* OUT: Poin
241b0 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f  ter to unused po
241c0 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f  rtion of zSql */
241d0 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
241e0 70 72 65 70 61 72 65 31 36 28 0a 20 20 73 71 6c  prepare16(.  sql
241f0 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
24200 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
24210 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
24220 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20  st void *zSql,  
24230 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74       /* SQL stat
24240 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e  ement, UTF-16 en
24250 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e  coded */.  int n
24260 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20  Byte,           
24270 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65     /* Maximum le
24280 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20  ngth of zSql in 
24290 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69  bytes. */.  sqli
242a0 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d  te3_stmt **ppStm
242b0 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74  t,  /* OUT: Stat
242c0 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a  ement handle */.
242d0 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70    const void **p
242e0 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54  zTail     /* OUT
242f0 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75  : Pointer to unu
24300 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a  sed portion of z
24310 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71  Sql */.);.int sq
24320 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
24330 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  v2(.  sqlite3 *d
24340 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  b,            /*
24350 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65   Database handle
24360 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64   */.  const void
24370 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a   *zSql,       /*
24380 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20   SQL statement, 
24390 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a  UTF-16 encoded *
243a0 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20  /.  int nByte,  
243b0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d              /* M
243c0 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
243d0 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20   zSql in bytes. 
243e0 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d  */.  sqlite3_stm
243f0 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20  t **ppStmt,  /* 
24400 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68  OUT: Statement h
24410 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
24420 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20   void **pzTail  
24430 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74     /* OUT: Point
24440 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72  er to unused por
24450 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a  tion of zSql */.
24460 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
24470 45 46 3a 20 52 65 74 72 69 65 76 69 6e 67 20 53  EF: Retrieving S
24480 74 61 74 65 6d 65 6e 74 20 53 51 4c 0a 2a 2a 0a  tatement SQL.**.
24490 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65 72 66 61  ** ^This interfa
244a0 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  ce can be used t
244b0 6f 20 72 65 74 72 69 65 76 65 20 61 20 73 61 76  o retrieve a sav
244c0 65 64 20 63 6f 70 79 20 6f 66 20 74 68 65 20 6f  ed copy of the o
244d0 72 69 67 69 6e 61 6c 0a 2a 2a 20 53 51 4c 20 74  riginal.** SQL t
244e0 65 78 74 20 75 73 65 64 20 74 6f 20 63 72 65 61  ext used to crea
244f0 74 65 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  te a [prepared s
24500 74 61 74 65 6d 65 6e 74 5d 20 69 66 20 74 68 61  tatement] if tha
24510 74 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 0a  t statement was.
24520 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 75 73 69 6e  ** compiled usin
24530 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65  g either [sqlite
24540 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
24550 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  or [sqlite3_prep
24560 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2f 0a  are16_v2()]..*/.
24570 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
24580 74 65 33 5f 73 71 6c 28 73 71 6c 69 74 65 33 5f  te3_sql(sqlite3_
24590 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
245a0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
245b0 65 74 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 53  etermine If An S
245c0 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 57 72 69  QL Statement Wri
245d0 74 65 73 20 54 68 65 20 44 61 74 61 62 61 73 65  tes The Database
245e0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
245f0 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c  te3_stmt_readonl
24600 79 28 58 29 20 69 6e 74 65 72 66 61 63 65 20 72  y(X) interface r
24610 65 74 75 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e  eturns true (non
24620 2d 7a 65 72 6f 29 20 69 66 0a 2a 2a 20 61 6e 64  -zero) if.** and
24630 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 5b 70 72   only if the [pr
24640 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
24650 5d 20 58 20 6d 61 6b 65 73 20 6e 6f 20 64 69 72  ] X makes no dir
24660 65 63 74 20 63 68 61 6e 67 65 73 20 74 6f 0a 2a  ect changes to.*
24670 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66  * the content of
24680 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
24690 6c 65 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74  le..**.** Note t
246a0 68 61 74 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e  hat [application
246b0 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
246c0 63 74 69 6f 6e 73 5d 20 6f 72 0a 2a 2a 20 5b 76  ctions] or.** [v
246d0 69 72 74 75 61 6c 20 74 61 62 6c 65 73 5d 20 6d  irtual tables] m
246e0 69 67 68 74 20 63 68 61 6e 67 65 20 74 68 65 20  ight change the 
246f0 64 61 74 61 62 61 73 65 20 69 6e 64 69 72 65 63  database indirec
24700 74 6c 79 20 61 73 20 61 20 73 69 64 65 20 65 66  tly as a side ef
24710 66 65 63 74 2e 20 20 0a 2a 2a 20 5e 28 46 6f 72  fect.  .** ^(For
24720 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 61 6e 20   example, if an 
24730 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69  application defi
24740 6e 65 73 20 61 20 66 75 6e 63 74 69 6f 6e 20 22  nes a function "
24750 65 76 61 6c 28 29 22 20 74 68 61 74 20 0a 2a 2a  eval()" that .**
24760 20 63 61 6c 6c 73 20 5b 73 71 6c 69 74 65 33 5f   calls [sqlite3_
24770 65 78 65 63 28 29 5d 2c 20 74 68 65 6e 20 74 68  exec()], then th
24780 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 20  e following SQL 
24790 73 74 61 74 65 6d 65 6e 74 20 77 6f 75 6c 64 0a  statement would.
247a0 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 64 61  ** change the da
247b0 74 61 62 61 73 65 20 66 69 6c 65 20 74 68 72 6f  tabase file thro
247c0 75 67 68 20 73 69 64 65 2d 65 66 66 65 63 74 73  ugh side-effects
247d0 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
247e0 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20  ote><pre>.**    
247f0 53 45 4c 45 43 54 20 65 76 61 6c 28 27 44 45 4c  SELECT eval('DEL
24800 45 54 45 20 46 52 4f 4d 20 74 31 27 29 20 46 52  ETE FROM t1') FR
24810 4f 4d 20 74 32 3b 0a 2a 2a 20 3c 2f 70 72 65 3e  OM t2;.** </pre>
24820 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
24830 0a 2a 2a 20 42 75 74 20 62 65 63 61 75 73 65 20  .** But because 
24840 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61  the [SELECT] sta
24850 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20  tement does not 
24860 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62  change the datab
24870 61 73 65 20 66 69 6c 65 0a 2a 2a 20 64 69 72 65  ase file.** dire
24880 63 74 6c 79 2c 20 73 71 6c 69 74 65 33 5f 73 74  ctly, sqlite3_st
24890 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 77 6f  mt_readonly() wo
248a0 75 6c 64 20 73 74 69 6c 6c 20 72 65 74 75 72 6e  uld still return
248b0 20 74 72 75 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e   true.)^.**.** ^
248c0 54 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74  Transaction cont
248d0 72 6f 6c 20 73 74 61 74 65 6d 65 6e 74 73 20 73  rol statements s
248e0 75 63 68 20 61 73 20 5b 42 45 47 49 4e 5d 2c 20  uch as [BEGIN], 
248f0 5b 43 4f 4d 4d 49 54 5d 2c 20 5b 52 4f 4c 4c 42  [COMMIT], [ROLLB
24900 41 43 4b 5d 2c 0a 2a 2a 20 5b 53 41 56 45 50 4f  ACK],.** [SAVEPO
24910 49 4e 54 5d 2c 20 61 6e 64 20 5b 52 45 4c 45 41  INT], and [RELEA
24920 53 45 5d 20 63 61 75 73 65 20 73 71 6c 69 74 65  SE] cause sqlite
24930 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28  3_stmt_readonly(
24940 29 20 74 6f 20 72 65 74 75 72 6e 20 74 72 75 65  ) to return true
24950 2c 0a 2a 2a 20 73 69 6e 63 65 20 74 68 65 20 73  ,.** since the s
24960 74 61 74 65 6d 65 6e 74 73 20 74 68 65 6d 73 65  tatements themse
24970 6c 76 65 73 20 64 6f 20 6e 6f 74 20 61 63 74 75  lves do not actu
24980 61 6c 6c 79 20 6d 6f 64 69 66 79 20 74 68 65 20  ally modify the 
24990 64 61 74 61 62 61 73 65 20 62 75 74 0a 2a 2a 20  database but.** 
249a0 72 61 74 68 65 72 20 74 68 65 79 20 63 6f 6e 74  rather they cont
249b0 72 6f 6c 20 74 68 65 20 74 69 6d 69 6e 67 20 6f  rol the timing o
249c0 66 20 77 68 65 6e 20 6f 74 68 65 72 20 73 74 61  f when other sta
249d0 74 65 6d 65 6e 74 73 20 6d 6f 64 69 66 79 20 74  tements modify t
249e0 68 65 20 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e  he .** database.
249f0 20 20 5e 54 68 65 20 5b 41 54 54 41 43 48 5d 20    ^The [ATTACH] 
24a00 61 6e 64 20 5b 44 45 54 41 43 48 5d 20 73 74 61  and [DETACH] sta
24a10 74 65 6d 65 6e 74 73 20 61 6c 73 6f 20 63 61 75  tements also cau
24a20 73 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74  se.** sqlite3_st
24a30 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f  mt_readonly() to
24a40 20 72 65 74 75 72 6e 20 74 72 75 65 20 73 69 6e   return true sin
24a50 63 65 2c 20 77 68 69 6c 65 20 74 68 6f 73 65 20  ce, while those 
24a60 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 63 68  statements.** ch
24a70 61 6e 67 65 20 74 68 65 20 63 6f 6e 66 69 67 75  ange the configu
24a80 72 61 74 69 6f 6e 20 6f 66 20 61 20 64 61 74 61  ration of a data
24a90 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c  base connection,
24aa0 20 74 68 65 79 20 64 6f 20 6e 6f 74 20 6d 61 6b   they do not mak
24ab0 65 20 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f  e .** changes to
24ac0 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20   the content of 
24ad0 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
24ae0 65 73 20 6f 6e 20 64 69 73 6b 2e 0a 2a 2f 0a 69  es on disk..*/.i
24af0 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  nt sqlite3_stmt_
24b00 72 65 61 64 6f 6e 6c 79 28 73 71 6c 69 74 65 33  readonly(sqlite3
24b10 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a  _stmt *pStmt);..
24b20 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
24b30 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 20 50  Determine If A P
24b40 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
24b50 74 20 48 61 73 20 42 65 65 6e 20 52 65 73 65 74  t Has Been Reset
24b60 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
24b70 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 53 29  te3_stmt_busy(S)
24b80 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
24b90 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72  ns true (non-zer
24ba0 6f 29 20 69 66 20 74 68 65 0a 2a 2a 20 5b 70 72  o) if the.** [pr
24bb0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
24bc0 5d 20 53 20 68 61 73 20 62 65 65 6e 20 73 74 65  ] S has been ste
24bd0 70 70 65 64 20 61 74 20 6c 65 61 73 74 20 6f 6e  pped at least on
24be0 63 65 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71  ce using .** [sq
24bf0 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 62  lite3_step(S)] b
24c00 75 74 20 68 61 73 20 6e 6f 74 20 72 75 6e 20 74  ut has not run t
24c10 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 6e 64  o completion and
24c20 2f 6f 72 20 68 61 73 20 6e 6f 74 20 0a 2a 2a 20  /or has not .** 
24c30 62 65 65 6e 20 72 65 73 65 74 20 75 73 69 6e 67  been reset using
24c40 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
24c50 53 29 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 74  S)].  ^The sqlit
24c60 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 53 29 0a  e3_stmt_busy(S).
24c70 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  ** interface ret
24c80 75 72 6e 73 20 66 61 6c 73 65 20 69 66 20 53 20  urns false if S 
24c90 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
24ca0 72 2e 20 20 49 66 20 53 20 69 73 20 6e 6f 74 20  r.  If S is not 
24cb0 61 20 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74  a .** NULL point
24cc0 65 72 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20  er and is not a 
24cd0 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 76 61 6c  pointer to a val
24ce0 69 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  id [prepared sta
24cf0 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63  tement].** objec
24d00 74 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  t, then the beha
24d10 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65  vior is undefine
24d20 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 75  d and probably u
24d30 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2a 0a 2a  ndesirable..**.*
24d40 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65  * This interface
24d50 20 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e 20   can be used in 
24d60 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 5b 73 71 6c  combination [sql
24d70 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 29  ite3_next_stmt()
24d80 5d 0a 2a 2a 20 74 6f 20 6c 6f 63 61 74 65 20 61  ].** to locate a
24d90 6c 6c 20 70 72 65 70 61 72 65 64 20 73 74 61 74  ll prepared stat
24da0 65 6d 65 6e 74 73 20 61 73 73 6f 63 69 61 74 65  ements associate
24db0 64 20 77 69 74 68 20 61 20 64 61 74 61 62 61 73  d with a databas
24dc0 65 20 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  e .** connection
24dd0 20 74 68 61 74 20 61 72 65 20 69 6e 20 6e 65 65   that are in nee
24de0 64 20 6f 66 20 62 65 69 6e 67 20 72 65 73 65 74  d of being reset
24df0 2e 20 20 54 68 69 73 20 63 61 6e 20 62 65 20 75  .  This can be u
24e00 73 65 64 2c 0a 2a 2a 20 66 6f 72 20 65 78 61 6d  sed,.** for exam
24e10 70 6c 65 2c 20 69 6e 20 64 69 61 67 6e 6f 73 74  ple, in diagnost
24e20 69 63 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 73  ic routines to s
24e30 65 61 72 63 68 20 66 6f 72 20 70 72 65 70 61 72  earch for prepar
24e40 65 64 20 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  ed .** statement
24e50 73 20 74 68 61 74 20 61 72 65 20 68 6f 6c 64 69  s that are holdi
24e60 6e 67 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e  ng a transaction
24e70 20 6f 70 65 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71   open..*/.int sq
24e80 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28  lite3_stmt_busy(
24e90 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a  sqlite3_stmt*);.
24ea0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
24eb0 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54 79 70   Dynamically Typ
24ec0 65 64 20 56 61 6c 75 65 20 4f 62 6a 65 63 74 0a  ed Value Object.
24ed0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72  ** KEYWORDS: {pr
24ee0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
24ef0 76 61 6c 75 65 7d 20 7b 75 6e 70 72 6f 74 65 63  value} {unprotec
24f00 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
24f10 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  e}.**.** SQLite 
24f20 75 73 65 73 20 74 68 65 20 73 71 6c 69 74 65 33  uses the sqlite3
24f30 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 74 6f  _value object to
24f40 20 72 65 70 72 65 73 65 6e 74 20 61 6c 6c 20 76   represent all v
24f50 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 63 61  alues.** that ca
24f60 6e 20 62 65 20 73 74 6f 72 65 64 20 69 6e 20 61  n be stored in a
24f70 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 2e   database table.
24f80 20 53 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e   SQLite uses dyn
24f90 61 6d 69 63 20 74 79 70 69 6e 67 0a 2a 2a 20 66  amic typing.** f
24fa0 6f 72 20 74 68 65 20 76 61 6c 75 65 73 20 69 74  or the values it
24fb0 20 73 74 6f 72 65 73 2e 20 20 5e 56 61 6c 75 65   stores.  ^Value
24fc0 73 20 73 74 6f 72 65 64 20 69 6e 20 73 71 6c 69  s stored in sqli
24fd0 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
24fe0 73 0a 2a 2a 20 63 61 6e 20 62 65 20 69 6e 74 65  s.** can be inte
24ff0 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67 20 70  gers, floating p
25000 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20 73 74 72  oint values, str
25010 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f 72 20  ings, BLOBs, or 
25020 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73  NULL..**.** An s
25030 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
25040 65 63 74 20 6d 61 79 20 62 65 20 65 69 74 68 65  ect may be eithe
25050 72 20 22 70 72 6f 74 65 63 74 65 64 22 20 6f 72  r "protected" or
25060 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 2e 0a   "unprotected"..
25070 2a 2a 20 53 6f 6d 65 20 69 6e 74 65 72 66 61 63  ** Some interfac
25080 65 73 20 72 65 71 75 69 72 65 20 61 20 70 72 6f  es require a pro
25090 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
250a0 61 6c 75 65 2e 20 20 4f 74 68 65 72 20 69 6e 74  alue.  Other int
250b0 65 72 66 61 63 65 73 0a 2a 2a 20 77 69 6c 6c 20  erfaces.** will 
250c0 61 63 63 65 70 74 20 65 69 74 68 65 72 20 61 20  accept either a 
250d0 70 72 6f 74 65 63 74 65 64 20 6f 72 20 61 6e 20  protected or an 
250e0 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
250f0 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45 76  te3_value..** Ev
25100 65 72 79 20 69 6e 74 65 72 66 61 63 65 20 74 68  ery interface th
25110 61 74 20 61 63 63 65 70 74 73 20 73 71 6c 69 74  at accepts sqlit
25120 65 33 5f 76 61 6c 75 65 20 61 72 67 75 6d 65 6e  e3_value argumen
25130 74 73 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20  ts specifies.** 
25140 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 69  whether or not i
25150 74 20 72 65 71 75 69 72 65 73 20 61 20 70 72 6f  t requires a pro
25160 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
25170 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  alue..**.** The 
25180 74 65 72 6d 73 20 22 70 72 6f 74 65 63 74 65 64  terms "protected
25190 22 20 61 6e 64 20 22 75 6e 70 72 6f 74 65 63 74  " and "unprotect
251a0 65 64 22 20 72 65 66 65 72 20 74 6f 20 77 68 65  ed" refer to whe
251b0 74 68 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61  ther or not.** a
251c0 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 2e 20   mutex is held. 
251d0 20 41 6e 20 69 6e 74 65 72 6e 61 6c 20 6d 75 74   An internal mut
251e0 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61  ex is held for a
251f0 20 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71   protected.** sq
25200 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
25210 63 74 20 62 75 74 20 6e 6f 20 6d 75 74 65 78 20  ct but no mutex 
25220 69 73 20 68 65 6c 64 20 66 6f 72 20 61 6e 20 75  is held for an u
25230 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71  nprotected.** sq
25240 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
25250 63 74 2e 20 20 49 66 20 53 51 4c 69 74 65 20 69  ct.  If SQLite i
25260 73 20 63 6f 6d 70 69 6c 65 64 20 74 6f 20 62 65  s compiled to be
25270 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 65 64   single-threaded
25280 0a 2a 2a 20 28 77 69 74 68 20 5b 53 51 4c 49 54  .** (with [SQLIT
25290 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20  E_THREADSAFE=0] 
252a0 61 6e 64 20 77 69 74 68 20 5b 73 71 6c 69 74 65  and with [sqlite
252b0 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 5d 20  3_threadsafe()] 
252c0 72 65 74 75 72 6e 69 6e 67 20 30 29 0a 2a 2a 20  returning 0).** 
252d0 6f 72 20 69 66 20 53 51 4c 69 74 65 20 69 73 20  or if SQLite is 
252e0 72 75 6e 20 69 6e 20 6f 6e 65 20 6f 66 20 72 65  run in one of re
252f0 64 75 63 65 64 20 6d 75 74 65 78 20 6d 6f 64 65  duced mutex mode
25300 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f  s .** [SQLITE_CO
25310 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
25320 44 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f  D] or [SQLITE_CO
25330 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44  NFIG_MULTITHREAD
25340 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 72 65 20  ].** then there 
25350 69 73 20 6e 6f 20 64 69 73 74 69 6e 63 74 69 6f  is no distinctio
25360 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63  n between protec
25370 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63  ted and unprotec
25380 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76  ted.** sqlite3_v
25390 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 61 6e 64  alue objects and
253a0 20 74 68 65 79 20 63 61 6e 20 62 65 20 75 73 65   they can be use
253b0 64 20 69 6e 74 65 72 63 68 61 6e 67 65 61 62 6c  d interchangeabl
253c0 79 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20  y.  However,.** 
253d0 66 6f 72 20 6d 61 78 69 6d 75 6d 20 63 6f 64 65  for maximum code
253e0 20 70 6f 72 74 61 62 69 6c 69 74 79 20 69 74 20   portability it 
253f0 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74  is recommended t
25400 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  hat applications
25410 0a 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b 65 20 74  .** still make t
25420 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62  he distinction b
25430 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64  etween protected
25440 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64   and unprotected
25450 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  .** sqlite3_valu
25460 65 20 6f 62 6a 65 63 74 73 20 65 76 65 6e 20 77  e objects even w
25470 68 65 6e 20 6e 6f 74 20 73 74 72 69 63 74 6c 79  hen not strictly
25480 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a   required..**.**
25490 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61   ^The sqlite3_va
254a0 6c 75 65 20 6f 62 6a 65 63 74 73 20 74 68 61 74  lue objects that
254b0 20 61 72 65 20 70 61 73 73 65 64 20 61 73 20 70   are passed as p
254c0 61 72 61 6d 65 74 65 72 73 20 69 6e 74 6f 20 74  arameters into t
254d0 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  he.** implementa
254e0 74 69 6f 6e 20 6f 66 20 5b 61 70 70 6c 69 63 61  tion of [applica
254f0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
25500 20 66 75 6e 63 74 69 6f 6e 73 5d 20 61 72 65 20   functions] are 
25510 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 5e 54  protected..** ^T
25520 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  he sqlite3_value
25530 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64   object returned
25540 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   by.** [sqlite3_
25550 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20  column_value()] 
25560 69 73 20 75 6e 70 72 6f 74 65 63 74 65 64 2e 0a  is unprotected..
25570 2a 2a 20 55 6e 70 72 6f 74 65 63 74 65 64 20 73  ** Unprotected s
25580 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
25590 65 63 74 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65  ects may only be
255a0 20 75 73 65 64 20 77 69 74 68 0a 2a 2a 20 5b 73   used with.** [s
255b0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61  qlite3_result_va
255c0 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  lue()] and [sqli
255d0 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29  te3_bind_value()
255e0 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74  ]..** The [sqlit
255f0 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 20 7c 20  e3_value_blob | 
25600 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79  sqlite3_value_ty
25610 70 65 28 29 5d 20 66 61 6d 69 6c 79 20 6f 66 0a  pe()] family of.
25620 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 72 65  ** interfaces re
25630 71 75 69 72 65 20 70 72 6f 74 65 63 74 65 64 20  quire protected 
25640 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
25650 6a 65 63 74 73 2e 0a 2a 2f 0a 74 79 70 65 64 65  jects..*/.typede
25660 66 20 73 74 72 75 63 74 20 4d 65 6d 20 73 71 6c  f struct Mem sql
25670 69 74 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a  ite3_value;../*.
25680 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c  ** CAPI3REF: SQL
25690 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78   Function Contex
256a0 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54  t Object.**.** T
256b0 68 65 20 63 6f 6e 74 65 78 74 20 69 6e 20 77 68  he context in wh
256c0 69 63 68 20 61 6e 20 53 51 4c 20 66 75 6e 63 74  ich an SQL funct
256d0 69 6f 6e 20 65 78 65 63 75 74 65 73 20 69 73 20  ion executes is 
256e0 73 74 6f 72 65 64 20 69 6e 20 61 6e 0a 2a 2a 20  stored in an.** 
256f0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20  sqlite3_context 
25700 6f 62 6a 65 63 74 2e 20 20 5e 41 20 70 6f 69 6e  object.  ^A poin
25710 74 65 72 20 74 6f 20 61 6e 20 73 71 6c 69 74 65  ter to an sqlite
25720 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74  3_context object
25730 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 66 69  .** is always fi
25740 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rst parameter to
25750 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   [application-de
25760 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
25770 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 70 70  ons]..** The app
25780 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
25790 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d   SQL function im
257a0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c  plementation wil
257b0 6c 20 70 61 73 73 20 74 68 69 73 0a 2a 2a 20 70  l pass this.** p
257c0 6f 69 6e 74 65 72 20 74 68 72 6f 75 67 68 20 69  ointer through i
257d0 6e 74 6f 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71  nto calls to [sq
257e0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74  lite3_result_int
257f0 20 7c 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c   | sqlite3_resul
25800 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  t()],.** [sqlite
25810 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
25820 65 78 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  ext()], [sqlite3
25830 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2c 0a 2a  _user_data()],.*
25840 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  * [sqlite3_conte
25850 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 5d 2c  xt_db_handle()],
25860 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75   [sqlite3_get_au
25870 78 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e 64  xdata()],.** and
25880 2f 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  /or [sqlite3_set
25890 5f 61 75 78 64 61 74 61 28 29 5d 2e 0a 2a 2f 0a  _auxdata()]..*/.
258a0 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
258b0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 73  qlite3_context s
258c0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 3b 0a  qlite3_context;.
258d0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
258e0 20 42 69 6e 64 69 6e 67 20 56 61 6c 75 65 73 20   Binding Values 
258f0 54 6f 20 50 72 65 70 61 72 65 64 20 53 74 61 74  To Prepared Stat
25900 65 6d 65 6e 74 73 0a 2a 2a 20 4b 45 59 57 4f 52  ements.** KEYWOR
25910 44 53 3a 20 7b 68 6f 73 74 20 70 61 72 61 6d 65  DS: {host parame
25920 74 65 72 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d  ter} {host param
25930 65 74 65 72 73 7d 20 7b 68 6f 73 74 20 70 61 72  eters} {host par
25940 61 6d 65 74 65 72 20 6e 61 6d 65 7d 0a 2a 2a 20  ameter name}.** 
25950 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 70  KEYWORDS: {SQL p
25960 61 72 61 6d 65 74 65 72 7d 20 7b 53 51 4c 20 70  arameter} {SQL p
25970 61 72 61 6d 65 74 65 72 73 7d 20 7b 70 61 72 61  arameters} {para
25980 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 7d 0a 2a  meter binding}.*
25990 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 65 20 53 51  *.** ^(In the SQ
259a0 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74  L statement text
259b0 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74   input to [sqlit
259c0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
259d0 20 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74   and its variant
259e0 73 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c 73 20 6d  s,.** literals m
259f0 61 79 20 62 65 20 72 65 70 6c 61 63 65 64 20 62  ay be replaced b
25a00 79 20 61 20 5b 70 61 72 61 6d 65 74 65 72 5d 20  y a [parameter] 
25a10 74 68 61 74 20 6d 61 74 63 68 65 73 20 6f 6e 65  that matches one
25a20 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a   of following.**
25a30 20 74 65 6d 70 6c 61 74 65 73 3a 0a 2a 2a 0a 2a   templates:.**.*
25a40 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20  * <ul>.** <li>  
25a50 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a  ?.** <li>  ?NNN.
25a60 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a  ** <li>  :VVV.**
25a70 20 3c 6c 69 3e 20 20 40 56 56 56 0a 2a 2a 20 3c   <li>  @VVV.** <
25a80 6c 69 3e 20 20 24 56 56 56 0a 2a 2a 20 3c 2f 75  li>  $VVV.** </u
25a90 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20  l>.**.** In the 
25aa0 74 65 6d 70 6c 61 74 65 73 20 61 62 6f 76 65 2c  templates above,
25ab0 20 4e 4e 4e 20 72 65 70 72 65 73 65 6e 74 73 20   NNN represents 
25ac0 61 6e 20 69 6e 74 65 67 65 72 20 6c 69 74 65 72  an integer liter
25ad0 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56 56 20 72  al,.** and VVV r
25ae0 65 70 72 65 73 65 6e 74 73 20 61 6e 20 61 6c 70  epresents an alp
25af0 68 61 6e 75 6d 65 72 69 63 20 69 64 65 6e 74 69  hanumeric identi
25b00 66 69 65 72 2e 29 5e 20 20 5e 54 68 65 20 76 61  fier.)^  ^The va
25b10 6c 75 65 73 20 6f 66 20 74 68 65 73 65 0a 2a 2a  lues of these.**
25b20 20 70 61 72 61 6d 65 74 65 72 73 20 28 61 6c 73   parameters (als
25b30 6f 20 63 61 6c 6c 65 64 20 22 68 6f 73 74 20 70  o called "host p
25b40 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 73 22 20  arameter names" 
25b50 6f 72 20 22 53 51 4c 20 70 61 72 61 6d 65 74 65  or "SQL paramete
25b60 72 73 22 29 0a 2a 2a 20 63 61 6e 20 62 65 20 73  rs").** can be s
25b70 65 74 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c  et using the sql
25b80 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f  ite3_bind_*() ro
25b90 75 74 69 6e 65 73 20 64 65 66 69 6e 65 64 20 68  utines defined h
25ba0 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ere..**.** ^The 
25bb0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
25bc0 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69  o the sqlite3_bi
25bd0 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20  nd_*() routines 
25be0 69 73 20 61 6c 77 61 79 73 0a 2a 2a 20 61 20 70  is always.** a p
25bf0 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73  ointer to the [s
25c00 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a  qlite3_stmt] obj
25c10 65 63 74 20 72 65 74 75 72 6e 65 64 20 66 72 6f  ect returned fro
25c20 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  m.** [sqlite3_pr
25c30 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 69  epare_v2()] or i
25c40 74 73 20 76 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a  ts variants..**.
25c50 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61  ** ^The second a
25c60 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69  rgument is the i
25c70 6e 64 65 78 20 6f 66 20 74 68 65 20 53 51 4c 20  ndex of the SQL 
25c80 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62 65 20  parameter to be 
25c90 73 65 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66  set..** ^The lef
25ca0 74 6d 6f 73 74 20 53 51 4c 20 70 61 72 61 6d 65  tmost SQL parame
25cb0 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78  ter has an index
25cc0 20 6f 66 20 31 2e 20 20 5e 57 68 65 6e 20 74 68   of 1.  ^When th
25cd0 65 20 73 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20  e same named.** 
25ce0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73  SQL parameter is
25cf0 20 75 73 65 64 20 6d 6f 72 65 20 74 68 61 6e 20   used more than 
25d00 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 20 61 6e 64  once, second and
25d10 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 6f   subsequent.** o
25d20 63 63 75 72 72 65 6e 63 65 73 20 68 61 76 65 20  ccurrences have 
25d30 74 68 65 20 73 61 6d 65 20 69 6e 64 65 78 20 61  the same index a
25d40 73 20 74 68 65 20 66 69 72 73 74 20 6f 63 63 75  s the first occu
25d50 72 72 65 6e 63 65 2e 0a 2a 2a 20 5e 54 68 65 20  rrence..** ^The 
25d60 69 6e 64 65 78 20 66 6f 72 20 6e 61 6d 65 64 20  index for named 
25d70 70 61 72 61 6d 65 74 65 72 73 20 63 61 6e 20 62  parameters can b
25d80 65 20 6c 6f 6f 6b 65 64 20 75 70 20 75 73 69 6e  e looked up usin
25d90 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  g the.** [sqlite
25da0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
25db0 5f 69 6e 64 65 78 28 29 5d 20 41 50 49 20 69 66  _index()] API if
25dc0 20 64 65 73 69 72 65 64 2e 20 20 5e 54 68 65 20   desired.  ^The 
25dd0 69 6e 64 65 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e  index.** for "?N
25de0 4e 4e 22 20 70 61 72 61 6d 65 74 65 72 73 20 69  NN" parameters i
25df0 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 4e  s the value of N
25e00 4e 4e 2e 0a 2a 2a 20 5e 54 68 65 20 4e 4e 4e 20  NN..** ^The NNN 
25e10 76 61 6c 75 65 20 6d 75 73 74 20 62 65 20 62 65  value must be be
25e20 74 77 65 65 6e 20 31 20 61 6e 64 20 74 68 65 20  tween 1 and the 
25e30 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29  [sqlite3_limit()
25e40 5d 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 5b  ].** parameter [
25e50 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52  SQLITE_LIMIT_VAR
25e60 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 20 28 64  IABLE_NUMBER] (d
25e70 65 66 61 75 6c 74 20 76 61 6c 75 65 3a 20 39 39  efault value: 99
25e80 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74  9)..**.** ^The t
25e90 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73  hird argument is
25ea0 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 62 69   the value to bi
25eb0 6e 64 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65  nd to the parame
25ec0 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20  ter..**.** ^(In 
25ed0 74 68 6f 73 65 20 72 6f 75 74 69 6e 65 73 20 74  those routines t
25ee0 68 61 74 20 68 61 76 65 20 61 20 66 6f 75 72 74  hat have a fourt
25ef0 68 20 61 72 67 75 6d 65 6e 74 2c 20 69 74 73 20  h argument, its 
25f00 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20  value is the.** 
25f10 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
25f20 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  in the parameter
25f30 2e 20 20 54 6f 20 62 65 20 63 6c 65 61 72 3a 20  .  To be clear: 
25f40 74 68 65 20 76 61 6c 75 65 20 69 73 20 74 68 65  the value is the
25f50 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 3c 75  .** number of <u
25f60 3e 62 79 74 65 73 3c 2f 75 3e 20 69 6e 20 74 68  >bytes</u> in th
25f70 65 20 76 61 6c 75 65 2c 20 6e 6f 74 20 74 68 65  e value, not the
25f80 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61   number of chara
25f90 63 74 65 72 73 2e 29 5e 0a 2a 2a 20 5e 49 66 20  cters.)^.** ^If 
25fa0 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
25fb0 65 74 65 72 20 69 73 20 6e 65 67 61 74 69 76 65  eter is negative
25fc0 2c 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20  , the length of 
25fd0 74 68 65 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a  the string is.**
25fe0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
25ff0 79 74 65 73 20 75 70 20 74 6f 20 74 68 65 20 66  ytes up to the f
26000 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e  irst zero termin
26010 61 74 6f 72 2e 0a 2a 2a 20 49 66 20 61 20 6e 6f  ator..** If a no
26020 6e 2d 6e 65 67 61 74 69 76 65 20 66 6f 75 72 74  n-negative fourt
26030 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 70  h parameter is p
26040 72 6f 76 69 64 65 64 20 74 6f 20 73 71 6c 69 74  rovided to sqlit
26050 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 0a 2a  e3_bind_text().*
26060 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e  * or sqlite3_bin
26070 64 5f 74 65 78 74 31 36 28 29 20 74 68 65 6e 20  d_text16() then 
26080 74 68 61 74 20 70 61 72 61 6d 65 74 65 72 20 6d  that parameter m
26090 75 73 74 20 62 65 20 74 68 65 20 62 79 74 65 20  ust be the byte 
260a0 6f 66 66 73 65 74 0a 2a 2a 20 77 68 65 72 65 20  offset.** where 
260b0 74 68 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74  the NUL terminat
260c0 6f 72 20 77 6f 75 6c 64 20 6f 63 63 75 72 20 61  or would occur a
260d0 73 73 75 6d 69 6e 67 20 74 68 65 20 73 74 72 69  ssuming the stri
260e0 6e 67 20 77 65 72 65 20 4e 55 4c 0a 2a 2a 20 74  ng were NUL.** t
260f0 65 72 6d 69 6e 61 74 65 64 2e 20 20 49 66 20 61  erminated.  If a
26100 6e 79 20 4e 55 4c 20 63 68 61 72 61 63 74 65 72  ny NUL character
26110 73 20 6f 63 63 75 72 20 61 74 20 62 79 74 65 20  s occur at byte 
26120 6f 66 66 73 65 74 73 20 6c 65 73 73 20 74 68 61  offsets less tha
26130 6e 20 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20  n .** the value 
26140 6f 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  of the fourth pa
26150 72 61 6d 65 74 65 72 20 74 68 65 6e 20 74 68 65  rameter then the
26160 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e   resulting strin
26170 67 20 76 61 6c 75 65 20 77 69 6c 6c 0a 2a 2a 20  g value will.** 
26180 63 6f 6e 74 61 69 6e 20 65 6d 62 65 64 64 65 64  contain embedded
26190 20 4e 55 4c 73 2e 20 20 54 68 65 20 72 65 73 75   NULs.  The resu
261a0 6c 74 20 6f 66 20 65 78 70 72 65 73 73 69 6f 6e  lt of expression
261b0 73 20 69 6e 76 6f 6c 76 69 6e 67 20 73 74 72 69  s involving stri
261c0 6e 67 73 0a 2a 2a 20 77 69 74 68 20 65 6d 62 65  ngs.** with embe
261d0 64 64 65 64 20 4e 55 4c 73 20 69 73 20 75 6e 64  dded NULs is und
261e0 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  efined..**.** ^T
261f0 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e  he fifth argumen
26200 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e  t to sqlite3_bin
26210 64 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65  d_blob(), sqlite
26220 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 2c 20 61  3_bind_text(), a
26230 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62 69  nd.** sqlite3_bi
26240 6e 64 5f 74 65 78 74 31 36 28 29 20 69 73 20 61  nd_text16() is a
26250 20 64 65 73 74 72 75 63 74 6f 72 20 75 73 65 64   destructor used
26260 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74   to dispose of t
26270 68 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74  he BLOB or.** st
26280 72 69 6e 67 20 61 66 74 65 72 20 53 51 4c 69 74  ring after SQLit
26290 65 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77  e has finished w
262a0 69 74 68 20 69 74 2e 20 20 5e 54 68 65 20 64 65  ith it.  ^The de
262b0 73 74 72 75 63 74 6f 72 20 69 73 20 63 61 6c 6c  structor is call
262c0 65 64 0a 2a 2a 20 74 6f 20 64 69 73 70 6f 73 65  ed.** to dispose
262d0 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 20   of the BLOB or 
262e0 73 74 72 69 6e 67 20 65 76 65 6e 20 69 66 20 74  string even if t
262f0 68 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74  he call to sqlit
26300 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 2c 0a  e3_bind_blob(),.
26310 2a 2a 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  ** sqlite3_bind_
26320 74 65 78 74 28 29 2c 20 6f 72 20 73 71 6c 69 74  text(), or sqlit
26330 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29  e3_bind_text16()
26340 20 66 61 69 6c 73 2e 20 20 0a 2a 2a 20 5e 49 66   fails.  .** ^If
26350 20 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d   the fifth argum
26360 65 6e 74 20 69 73 0a 2a 2a 20 74 68 65 20 73 70  ent is.** the sp
26370 65 63 69 61 6c 20 76 61 6c 75 65 20 5b 53 51 4c  ecial value [SQL
26380 49 54 45 5f 53 54 41 54 49 43 5d 2c 20 74 68 65  ITE_STATIC], the
26390 6e 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73  n SQLite assumes
263a0 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 69 6e 66   that the.** inf
263b0 6f 72 6d 61 74 69 6f 6e 20 69 73 20 69 6e 20 73  ormation is in s
263c0 74 61 74 69 63 2c 20 75 6e 6d 61 6e 61 67 65 64  tatic, unmanaged
263d0 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20   space and does 
263e0 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 66  not need to be f
263f0 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  reed..** ^If the
26400 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20   fifth argument 
26410 68 61 73 20 74 68 65 20 76 61 6c 75 65 20 5b 53  has the value [S
26420 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d  QLITE_TRANSIENT]
26430 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65  , then.** SQLite
26440 20 6d 61 6b 65 73 20 69 74 73 20 6f 77 6e 20 70   makes its own p
26450 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74  rivate copy of t
26460 68 65 20 64 61 74 61 20 69 6d 6d 65 64 69 61 74  he data immediat
26470 65 6c 79 2c 20 62 65 66 6f 72 65 0a 2a 2a 20 74  ely, before.** t
26480 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
26490 2a 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  *() routine retu
264a0 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  rns..**.** ^The 
264b0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72  sqlite3_bind_zer
264c0 6f 62 6c 6f 62 28 29 20 72 6f 75 74 69 6e 65 20  oblob() routine 
264d0 62 69 6e 64 73 20 61 20 42 4c 4f 42 20 6f 66 20  binds a BLOB of 
264e0 6c 65 6e 67 74 68 20 4e 20 74 68 61 74 0a 2a 2a  length N that.**
264f0 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20   is filled with 
26500 7a 65 72 6f 65 73 2e 20 20 5e 41 20 7a 65 72 6f  zeroes.  ^A zero
26510 62 6c 6f 62 20 75 73 65 73 20 61 20 66 69 78 65  blob uses a fixe
26520 64 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f  d amount of memo
26530 72 79 0a 2a 2a 20 28 6a 75 73 74 20 61 6e 20 69  ry.** (just an i
26540 6e 74 65 67 65 72 20 74 6f 20 68 6f 6c 64 20 69  nteger to hold i
26550 74 73 20 73 69 7a 65 29 20 77 68 69 6c 65 20 69  ts size) while i
26560 74 20 69 73 20 62 65 69 6e 67 20 70 72 6f 63 65  t is being proce
26570 73 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f  ssed..** Zeroblo
26580 62 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20  bs are intended 
26590 74 6f 20 73 65 72 76 65 20 61 73 20 70 6c 61 63  to serve as plac
265a0 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 42 4c 4f  eholders for BLO
265b0 42 73 20 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74  Bs whose.** cont
265c0 65 6e 74 20 69 73 20 6c 61 74 65 72 20 77 72 69  ent is later wri
265d0 74 74 65 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73  tten using.** [s
265e0 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e  qlite3_blob_open
265f0 20 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42   | incremental B
26600 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75 74 69 6e 65  LOB I/O] routine
26610 73 2e 0a 2a 2a 20 5e 41 20 6e 65 67 61 74 69 76  s..** ^A negativ
26620 65 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20  e value for the 
26630 7a 65 72 6f 62 6c 6f 62 20 72 65 73 75 6c 74 73  zeroblob results
26640 20 69 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74   in a zero-lengt
26650 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e 49  h BLOB..**.** ^I
26660 66 20 61 6e 79 20 6f 66 20 74 68 65 20 73 71 6c  f any of the sql
26670 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f  ite3_bind_*() ro
26680 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65  utines are calle
26690 64 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f  d with a NULL po
266a0 69 6e 74 65 72 0a 2a 2a 20 66 6f 72 20 74 68 65  inter.** for the
266b0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
266c0 6d 65 6e 74 5d 20 6f 72 20 77 69 74 68 20 61 20  ment] or with a 
266d0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
266e0 6e 74 20 66 6f 72 20 77 68 69 63 68 0a 2a 2a 20  nt for which.** 
266f0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
26700 20 68 61 73 20 62 65 65 6e 20 63 61 6c 6c 65 64   has been called
26710 20 6d 6f 72 65 20 72 65 63 65 6e 74 6c 79 20 74   more recently t
26720 68 61 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  han [sqlite3_res
26730 65 74 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74  et()],.** then t
26740 68 65 20 63 61 6c 6c 20 77 69 6c 6c 20 72 65 74  he call will ret
26750 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55  urn [SQLITE_MISU
26760 53 45 5d 2e 20 20 49 66 20 61 6e 79 20 73 71 6c  SE].  If any sql
26770 69 74 65 33 5f 62 69 6e 64 5f 28 29 0a 2a 2a 20  ite3_bind_().** 
26780 72 6f 75 74 69 6e 65 20 69 73 20 70 61 73 73 65  routine is passe
26790 64 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  d a [prepared st
267a0 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61  atement] that ha
267b0 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64  s been finalized
267c0 2c 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20  , the.** result 
267d0 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64  is undefined and
267e0 20 70 72 6f 62 61 62 6c 79 20 68 61 72 6d 66 75   probably harmfu
267f0 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 42 69 6e 64 69 6e  l..**.** ^Bindin
26800 67 73 20 61 72 65 20 6e 6f 74 20 63 6c 65 61 72  gs are not clear
26810 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74  ed by the [sqlit
26820 65 33 5f 72 65 73 65 74 28 29 5d 20 72 6f 75 74  e3_reset()] rout
26830 69 6e 65 2e 0a 2a 2a 20 5e 55 6e 62 6f 75 6e 64  ine..** ^Unbound
26840 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20   parameters are 
26850 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 4e  interpreted as N
26860 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ULL..**.** ^The 
26870 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 20 72  sqlite3_bind_* r
26880 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b  outines return [
26890 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75  SQLITE_OK] on su
268a0 63 63 65 73 73 20 6f 72 20 61 6e 0a 2a 2a 20 5b  ccess or an.** [
268b0 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61  error code] if a
268c0 6e 79 74 68 69 6e 67 20 67 6f 65 73 20 77 72 6f  nything goes wro
268d0 6e 67 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f  ng..** ^[SQLITE_
268e0 52 41 4e 47 45 5d 20 69 73 20 72 65 74 75 72 6e  RANGE] is return
268f0 65 64 20 69 66 20 74 68 65 20 70 61 72 61 6d 65  ed if the parame
26900 74 65 72 0a 2a 2a 20 69 6e 64 65 78 20 69 73 20  ter.** index is 
26910 6f 75 74 20 6f 66 20 72 61 6e 67 65 2e 20 20 5e  out of range.  ^
26920 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69  [SQLITE_NOMEM] i
26930 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 6d 61  s returned if ma
26940 6c 6c 6f 63 28 29 20 66 61 69 6c 73 2e 0a 2a 2a  lloc() fails..**
26950 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
26960 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
26970 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a  meter_count()],.
26980 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
26990 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28  _parameter_name(
269a0 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  )], and [sqlite3
269b0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
269c0 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74  index()]..*/.int
269d0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c   sqlite3_bind_bl
269e0 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ob(sqlite3_stmt*
269f0 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69  , int, const voi
26a00 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28  d*, int n, void(
26a10 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20  *)(void*));.int 
26a20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f 75  sqlite3_bind_dou
26a30 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ble(sqlite3_stmt
26a40 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29 3b  *, int, double);
26a50 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
26a60 64 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74  d_int(sqlite3_st
26a70 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b 0a  mt*, int, int);.
26a80 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
26a90 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73  _int64(sqlite3_s
26aa0 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74  tmt*, int, sqlit
26ab0 65 33 5f 69 6e 74 36 34 29 3b 0a 69 6e 74 20 73  e3_int64);.int s
26ac0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c  qlite3_bind_null
26ad0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
26ae0 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  int);.int sqlite
26af0 33 5f 62 69 6e 64 5f 74 65 78 74 28 73 71 6c 69  3_bind_text(sqli
26b00 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
26b10 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74  const char*, int
26b20 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64   n, void(*)(void
26b30 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  *));.int sqlite3
26b40 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 73 71 6c  _bind_text16(sql
26b50 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
26b60 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
26b70 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  t, void(*)(void*
26b80 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  ));.int sqlite3_
26b90 62 69 6e 64 5f 76 61 6c 75 65 28 73 71 6c 69 74  bind_value(sqlit
26ba0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63  e3_stmt*, int, c
26bb0 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 76 61 6c  onst sqlite3_val
26bc0 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  ue*);.int sqlite
26bd0 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28  3_bind_zeroblob(
26be0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
26bf0 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a  nt, int n);../*.
26c00 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d  ** CAPI3REF: Num
26c10 62 65 72 20 4f 66 20 53 51 4c 20 50 61 72 61 6d  ber Of SQL Param
26c20 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  eters.**.** ^Thi
26c30 73 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65  s routine can be
26c40 20 75 73 65 64 20 74 6f 20 66 69 6e 64 20 74 68   used to find th
26c50 65 20 6e 75 6d 62 65 72 20 6f 66 20 5b 53 51 4c  e number of [SQL
26c60 20 70 61 72 61 6d 65 74 65 72 73 5d 0a 2a 2a 20   parameters].** 
26c70 69 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  in a [prepared s
26c80 74 61 74 65 6d 65 6e 74 5d 2e 20 20 53 51 4c 20  tatement].  SQL 
26c90 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 74  parameters are t
26ca0 6f 6b 65 6e 73 20 6f 66 20 74 68 65 0a 2a 2a 20  okens of the.** 
26cb0 66 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22  form "?", "?NNN"
26cc0 2c 20 22 3a 41 41 41 22 2c 20 22 24 41 41 41 22  , ":AAA", "$AAA"
26cd0 2c 20 6f 72 20 22 40 41 41 41 22 20 74 68 61 74  , or "@AAA" that
26ce0 20 73 65 72 76 65 20 61 73 0a 2a 2a 20 70 6c 61   serve as.** pla
26cf0 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 76 61  ceholders for va
26d00 6c 75 65 73 20 74 68 61 74 20 61 72 65 20 5b 73  lues that are [s
26d10 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
26d20 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20   | bound].** to 
26d30 74 68 65 20 70 61 72 61 6d 65 74 65 72 73 20 61  the parameters a
26d40 74 20 61 20 6c 61 74 65 72 20 74 69 6d 65 2e 0a  t a later time..
26d50 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f 75  **.** ^(This rou
26d60 74 69 6e 65 20 61 63 74 75 61 6c 6c 79 20 72 65  tine actually re
26d70 74 75 72 6e 73 20 74 68 65 20 69 6e 64 65 78 20  turns the index 
26d80 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 28  of the largest (
26d90 72 69 67 68 74 6d 6f 73 74 29 0a 2a 2a 20 70 61  rightmost).** pa
26da0 72 61 6d 65 74 65 72 2e 20 46 6f 72 20 61 6c 6c  rameter. For all
26db0 20 66 6f 72 6d 73 20 65 78 63 65 70 74 20 3f 4e   forms except ?N
26dc0 4e 4e 2c 20 74 68 69 73 20 77 69 6c 6c 20 63 6f  NN, this will co
26dd0 72 72 65 73 70 6f 6e 64 20 74 6f 20 74 68 65 0a  rrespond to the.
26de0 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 75 6e 69  ** number of uni
26df0 71 75 65 20 70 61 72 61 6d 65 74 65 72 73 2e 20  que parameters. 
26e00 20 49 66 20 70 61 72 61 6d 65 74 65 72 73 20 6f   If parameters o
26e10 66 20 74 68 65 20 3f 4e 4e 4e 20 66 6f 72 6d 20  f the ?NNN form 
26e20 61 72 65 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65  are used,.** the
26e30 72 65 20 6d 61 79 20 62 65 20 67 61 70 73 20 69  re may be gaps i
26e40 6e 20 74 68 65 20 6c 69 73 74 2e 29 5e 0a 2a 2a  n the list.)^.**
26e50 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
26e60 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
26e70 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d  |sqlite3_bind()]
26e80 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  ,.** [sqlite3_bi
26e90 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d  nd_parameter_nam
26ea0 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71  e()], and.** [sq
26eb0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
26ec0 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a  eter_index()]..*
26ed0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  /.int sqlite3_bi
26ee0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75  nd_parameter_cou
26ef0 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  nt(sqlite3_stmt*
26f00 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
26f10 45 46 3a 20 4e 61 6d 65 20 4f 66 20 41 20 48 6f  EF: Name Of A Ho
26f20 73 74 20 50 61 72 61 6d 65 74 65 72 0a 2a 2a 0a  st Parameter.**.
26f30 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
26f40 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e  bind_parameter_n
26f50 61 6d 65 28 50 2c 4e 29 20 69 6e 74 65 72 66 61  ame(P,N) interfa
26f60 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68  ce returns.** th
26f70 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 4e 2d  e name of the N-
26f80 74 68 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65  th [SQL paramete
26f90 72 5d 20 69 6e 20 74 68 65 20 5b 70 72 65 70 61  r] in the [prepa
26fa0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50  red statement] P
26fb0 2e 0a 2a 2a 20 5e 28 53 51 4c 20 70 61 72 61 6d  ..** ^(SQL param
26fc0 65 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72  eters of the for
26fd0 6d 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41  m "?NNN" or ":AA
26fe0 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20  A" or "@AAA" or 
26ff0 22 24 41 41 41 22 0a 2a 2a 20 68 61 76 65 20 61  "$AAA".** have a
27000 20 6e 61 6d 65 20 77 68 69 63 68 20 69 73 20 74   name which is t
27010 68 65 20 73 74 72 69 6e 67 20 22 3f 4e 4e 4e 22  he string "?NNN"
27020 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40   or ":AAA" or "@
27030 41 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a  AAA" or "$AAA".*
27040 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a  * respectively..
27050 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  ** In other word
27060 73 2c 20 74 68 65 20 69 6e 69 74 69 61 6c 20 22  s, the initial "
27070 3a 22 20 6f 72 20 22 24 22 20 6f 72 20 22 40 22  :" or "$" or "@"
27080 20 6f 72 20 22 3f 22 0a 2a 2a 20 69 73 20 69 6e   or "?".** is in
27090 63 6c 75 64 65 64 20 61 73 20 70 61 72 74 20 6f  cluded as part o
270a0 66 20 74 68 65 20 6e 61 6d 65 2e 29 5e 0a 2a 2a  f the name.)^.**
270b0 20 5e 50 61 72 61 6d 65 74 65 72 73 20 6f 66 20   ^Parameters of 
270c0 74 68 65 20 66 6f 72 6d 20 22 3f 22 20 77 69 74  the form "?" wit
270d0 68 6f 75 74 20 61 20 66 6f 6c 6c 6f 77 69 6e 67  hout a following
270e0 20 69 6e 74 65 67 65 72 20 68 61 76 65 20 6e 6f   integer have no
270f0 20 6e 61 6d 65 0a 2a 2a 20 61 6e 64 20 61 72 65   name.** and are
27100 20 72 65 66 65 72 72 65 64 20 74 6f 20 61 73 20   referred to as 
27110 22 6e 61 6d 65 6c 65 73 73 22 20 6f 72 20 22 61  "nameless" or "a
27120 6e 6f 6e 79 6d 6f 75 73 20 70 61 72 61 6d 65 74  nonymous paramet
27130 65 72 73 22 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ers"..**.** ^The
27140 20 66 69 72 73 74 20 68 6f 73 74 20 70 61 72 61   first host para
27150 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64  meter has an ind
27160 65 78 20 6f 66 20 31 2c 20 6e 6f 74 20 30 2e 0a  ex of 1, not 0..
27170 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 76 61  **.** ^If the va
27180 6c 75 65 20 4e 20 69 73 20 6f 75 74 20 6f 66 20  lue N is out of 
27190 72 61 6e 67 65 20 6f 72 20 69 66 20 74 68 65 20  range or if the 
271a0 4e 2d 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  N-th parameter i
271b0 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c 20 74  s.** nameless, t
271c0 68 65 6e 20 4e 55 4c 4c 20 69 73 20 72 65 74 75  hen NULL is retu
271d0 72 6e 65 64 2e 20 20 5e 54 68 65 20 72 65 74 75  rned.  ^The retu
271e0 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 0a 2a  rned string is.*
271f0 2a 20 61 6c 77 61 79 73 20 69 6e 20 55 54 46 2d  * always in UTF-
27200 38 20 65 6e 63 6f 64 69 6e 67 20 65 76 65 6e 20  8 encoding even 
27210 69 66 20 74 68 65 20 6e 61 6d 65 64 20 70 61 72  if the named par
27220 61 6d 65 74 65 72 20 77 61 73 0a 2a 2a 20 6f 72  ameter was.** or
27230 69 67 69 6e 61 6c 6c 79 20 73 70 65 63 69 66 69  iginally specifi
27240 65 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20  ed as UTF-16 in 
27250 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
27260 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c  16()] or.** [sql
27270 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
27280 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  2()]..**.** See 
27290 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62  also: [sqlite3_b
272a0 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33  ind_blob|sqlite3
272b0 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71  _bind()],.** [sq
272c0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
272d0 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61  eter_count()], a
272e0 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  nd.** [sqlite3_b
272f0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
27300 64 65 78 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74  dex()]..*/.const
27310 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 62   char *sqlite3_b
27320 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61  ind_parameter_na
27330 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  me(sqlite3_stmt*
27340 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  , int);../*.** C
27350 41 50 49 33 52 45 46 3a 20 49 6e 64 65 78 20 4f  API3REF: Index O
27360 66 20 41 20 50 61 72 61 6d 65 74 65 72 20 57 69  f A Parameter Wi
27370 74 68 20 41 20 47 69 76 65 6e 20 4e 61 6d 65 0a  th A Given Name.
27380 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68  **.** ^Return th
27390 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 53 51  e index of an SQ
273a0 4c 20 70 61 72 61 6d 65 74 65 72 20 67 69 76 65  L parameter give
273b0 6e 20 69 74 73 20 6e 61 6d 65 2e 20 20 5e 54 68  n its name.  ^Th
273c0 65 0a 2a 2a 20 69 6e 64 65 78 20 76 61 6c 75 65  e.** index value
273d0 20 72 65 74 75 72 6e 65 64 20 69 73 20 73 75 69   returned is sui
273e0 74 61 62 6c 65 20 66 6f 72 20 75 73 65 20 61 73  table for use as
273f0 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 70   the second.** p
27400 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c  arameter to [sql
27410 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73  ite3_bind_blob|s
27420 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2e 20  qlite3_bind()]. 
27430 20 5e 41 20 7a 65 72 6f 0a 2a 2a 20 69 73 20 72   ^A zero.** is r
27440 65 74 75 72 6e 65 64 20 69 66 20 6e 6f 20 6d 61  eturned if no ma
27450 74 63 68 69 6e 67 20 70 61 72 61 6d 65 74 65 72  tching parameter
27460 20 69 73 20 66 6f 75 6e 64 2e 20 20 5e 54 68 65   is found.  ^The
27470 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6e 61   parameter.** na
27480 6d 65 20 6d 75 73 74 20 62 65 20 67 69 76 65 6e  me must be given
27490 20 69 6e 20 55 54 46 2d 38 20 65 76 65 6e 20 69   in UTF-8 even i
274a0 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73  f the original s
274b0 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 73 20  tatement.** was 
274c0 70 72 65 70 61 72 65 64 20 66 72 6f 6d 20 55 54  prepared from UT
274d0 46 2d 31 36 20 74 65 78 74 20 75 73 69 6e 67 20  F-16 text using 
274e0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
274f0 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  16_v2()]..**.** 
27500 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
27510 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c  e3_bind_blob|sql
27520 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a  ite3_bind()],.**
27530 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
27540 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29  arameter_count()
27550 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  ], and.** [sqlit
27560 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
27570 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69  r_index()]..*/.i
27580 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
27590 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28  parameter_index(
275a0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 63  sqlite3_stmt*, c
275b0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
275c0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
275d0 45 46 3a 20 52 65 73 65 74 20 41 6c 6c 20 42 69  EF: Reset All Bi
275e0 6e 64 69 6e 67 73 20 4f 6e 20 41 20 50 72 65 70  ndings On A Prep
275f0 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 0a 2a  ared Statement.*
27600 2a 0a 2a 2a 20 5e 43 6f 6e 74 72 61 72 79 20 74  *.** ^Contrary t
27610 6f 20 74 68 65 20 69 6e 74 75 69 74 69 6f 6e 20  o the intuition 
27620 6f 66 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74 65  of many, [sqlite
27630 33 5f 72 65 73 65 74 28 29 5d 20 64 6f 65 73 20  3_reset()] does 
27640 6e 6f 74 20 72 65 73 65 74 0a 2a 2a 20 74 68 65  not reset.** the
27650 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
27660 6c 6f 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20  lob | bindings] 
27670 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  on a [prepared s
27680 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 55  tatement]..** ^U
27690 73 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  se this routine 
276a0 74 6f 20 72 65 73 65 74 20 61 6c 6c 20 68 6f 73  to reset all hos
276b0 74 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20  t parameters to 
276c0 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  NULL..*/.int sql
276d0 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69  ite3_clear_bindi
276e0 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ngs(sqlite3_stmt
276f0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
27700 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 43  REF: Number Of C
27710 6f 6c 75 6d 6e 73 20 49 6e 20 41 20 52 65 73 75  olumns In A Resu
27720 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e 52 65  lt Set.**.** ^Re
27730 74 75 72 6e 20 74 68 65 20 6e 75 6d 62 65 72 20  turn the number 
27740 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68  of columns in th
27750 65 20 72 65 73 75 6c 74 20 73 65 74 20 72 65 74  e result set ret
27760 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20  urned by the.** 
27770 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
27780 65 6e 74 5d 2e 20 5e 54 68 69 73 20 72 6f 75 74  ent]. ^This rout
27790 69 6e 65 20 72 65 74 75 72 6e 73 20 30 20 69 66  ine returns 0 if
277a0 20 70 53 74 6d 74 20 69 73 20 61 6e 20 53 51 4c   pStmt is an SQL
277b0 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 74 68  .** statement th
277c0 61 74 20 64 6f 65 73 20 6e 6f 74 20 72 65 74 75  at does not retu
277d0 72 6e 20 64 61 74 61 20 28 66 6f 72 20 65 78 61  rn data (for exa
277e0 6d 70 6c 65 20 61 6e 20 5b 55 50 44 41 54 45 5d  mple an [UPDATE]
277f0 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  )..**.** See als
27800 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 64 61 74 61  o: [sqlite3_data
27810 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69 6e 74  _count()].*/.int
27820 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
27830 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74  count(sqlite3_st
27840 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
27850 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c  ** CAPI3REF: Col
27860 75 6d 6e 20 4e 61 6d 65 73 20 49 6e 20 41 20 52  umn Names In A R
27870 65 73 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20  esult Set.**.** 
27880 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
27890 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20  return the name 
278a0 61 73 73 69 67 6e 65 64 20 74 6f 20 61 20 70 61  assigned to a pa
278b0 72 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a  rticular column.
278c0 2a 2a 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74  ** in the result
278d0 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43   set of a [SELEC
278e0 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e  T] statement.  ^
278f0 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  The sqlite3_colu
27900 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e 74  mn_name().** int
27910 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
27920 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65   pointer to a ze
27930 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54  ro-terminated UT
27940 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 61 6e  F-8 string.** an
27950 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  d sqlite3_column
27960 5f 6e 61 6d 65 31 36 28 29 20 72 65 74 75 72 6e  _name16() return
27970 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
27980 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
27990 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69 6e  .** UTF-16 strin
279a0 67 2e 20 20 5e 54 68 65 20 66 69 72 73 74 20 70  g.  ^The first p
279b0 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20  arameter is the 
279c0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
279d0 65 6e 74 5d 0a 2a 2a 20 74 68 61 74 20 69 6d 70  ent].** that imp
279e0 6c 65 6d 65 6e 74 73 20 74 68 65 20 5b 53 45 4c  lements the [SEL
279f0 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20  ECT] statement. 
27a00 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61  ^The second para
27a10 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20  meter is the.** 
27a20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 20 20  column number.  
27a30 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f  ^The leftmost co
27a40 6c 75 6d 6e 20 69 73 20 6e 75 6d 62 65 72 20 30  lumn is number 0
27a50 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72 65 74  ..**.** ^The ret
27a60 75 72 6e 65 64 20 73 74 72 69 6e 67 20 70 6f 69  urned string poi
27a70 6e 74 65 72 20 69 73 20 76 61 6c 69 64 20 75 6e  nter is valid un
27a80 74 69 6c 20 65 69 74 68 65 72 20 74 68 65 20 5b  til either the [
27a90 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
27aa0 6e 74 5d 0a 2a 2a 20 69 73 20 64 65 73 74 72 6f  nt].** is destro
27ab0 79 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  yed by [sqlite3_
27ac0 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75  finalize()] or u
27ad0 6e 74 69 6c 20 74 68 65 20 73 74 61 74 65 6d 65  ntil the stateme
27ae0 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61  nt is automatica
27af0 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61 72 65  lly.** reprepare
27b00 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20 63  d by the first c
27b10 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
27b20 73 74 65 70 28 29 5d 20 66 6f 72 20 61 20 70 61  step()] for a pa
27b30 72 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20  rticular run.** 
27b40 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78  or until the nex
27b50 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c  t call to.** sql
27b60 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
27b70 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f  () or sqlite3_co
27b80 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 6f 6e  lumn_name16() on
27b90 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 75 6d 6e   the same column
27ba0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 73 71 6c 69  ..**.** ^If sqli
27bb0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 61 69  te3_malloc() fai
27bc0 6c 73 20 64 75 72 69 6e 67 20 74 68 65 20 70 72  ls during the pr
27bd0 6f 63 65 73 73 69 6e 67 20 6f 66 20 65 69 74 68  ocessing of eith
27be0 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 28 66  er routine.** (f
27bf0 6f 72 20 65 78 61 6d 70 6c 65 20 64 75 72 69 6e  or example durin
27c00 67 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66  g a conversion f
27c10 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55 54 46  rom UTF-8 to UTF
27c20 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a 2a 20 4e  -16) then a.** N
27c30 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72  ULL pointer is r
27c40 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  eturned..**.** ^
27c50 54 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 72 65  The name of a re
27c60 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74  sult column is t
27c70 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  he value of the 
27c80 22 41 53 22 20 63 6c 61 75 73 65 20 66 6f 72 0a  "AS" clause for.
27c90 2a 2a 20 74 68 61 74 20 63 6f 6c 75 6d 6e 2c 20  ** that column, 
27ca0 69 66 20 74 68 65 72 65 20 69 73 20 61 6e 20 41  if there is an A
27cb0 53 20 63 6c 61 75 73 65 2e 20 20 49 66 20 74 68  S clause.  If th
27cc0 65 72 65 20 69 73 20 6e 6f 20 41 53 20 63 6c 61  ere is no AS cla
27cd0 75 73 65 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  use.** then the 
27ce0 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c 75  name of the colu
27cf0 6d 6e 20 69 73 20 75 6e 73 70 65 63 69 66 69 65  mn is unspecifie
27d00 64 20 61 6e 64 20 6d 61 79 20 63 68 61 6e 67 65  d and may change
27d10 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c   from.** one rel
27d20 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 20 74  ease of SQLite t
27d30 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a 63  o the next..*/.c
27d40 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
27d50 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73  e3_column_name(s
27d60 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
27d70 74 20 4e 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  t N);.const void
27d80 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
27d90 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f  _name16(sqlite3_
27da0 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a  stmt*, int N);..
27db0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
27dc0 53 6f 75 72 63 65 20 4f 66 20 44 61 74 61 20 49  Source Of Data I
27dd0 6e 20 41 20 51 75 65 72 79 20 52 65 73 75 6c 74  n A Query Result
27de0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
27df0 75 74 69 6e 65 73 20 70 72 6f 76 69 64 65 20 61  utines provide a
27e00 20 6d 65 61 6e 73 20 74 6f 20 64 65 74 65 72 6d   means to determ
27e10 69 6e 65 20 74 68 65 20 64 61 74 61 62 61 73 65  ine the database
27e20 2c 20 74 61 62 6c 65 2c 20 61 6e 64 0a 2a 2a 20  , table, and.** 
27e30 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61  table column tha
27e40 74 20 69 73 20 74 68 65 20 6f 72 69 67 69 6e 20  t is the origin 
27e50 6f 66 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  of a particular 
27e60 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 6e  result column in
27e70 0a 2a 2a 20 5b 53 45 4c 45 43 54 5d 20 73 74 61  .** [SELECT] sta
27e80 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20  tement..** ^The 
27e90 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61  name of the data
27ea0 62 61 73 65 20 6f 72 20 74 61 62 6c 65 20 6f 72  base or table or
27eb0 20 63 6f 6c 75 6d 6e 20 63 61 6e 20 62 65 20 72   column can be r
27ec0 65 74 75 72 6e 65 64 20 61 73 0a 2a 2a 20 65 69  eturned as.** ei
27ed0 74 68 65 72 20 61 20 55 54 46 2d 38 20 6f 72 20  ther a UTF-8 or 
27ee0 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20  UTF-16 string.  
27ef0 5e 54 68 65 20 5f 64 61 74 61 62 61 73 65 5f 20  ^The _database_ 
27f00 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 0a  routines return.
27f10 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ** the database 
27f20 6e 61 6d 65 2c 20 74 68 65 20 5f 74 61 62 6c 65  name, the _table
27f30 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  _ routines retur
27f40 6e 20 74 68 65 20 74 61 62 6c 65 20 6e 61 6d 65  n the table name
27f50 2c 20 61 6e 64 0a 2a 2a 20 74 68 65 20 6f 72 69  , and.** the ori
27f60 67 69 6e 5f 20 72 6f 75 74 69 6e 65 73 20 72 65  gin_ routines re
27f70 74 75 72 6e 20 74 68 65 20 63 6f 6c 75 6d 6e 20  turn the column 
27f80 6e 61 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 72 65  name..** ^The re
27f90 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73  turned string is
27fa0 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 74 68 65   valid until the
27fb0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
27fc0 6d 65 6e 74 5d 20 69 73 20 64 65 73 74 72 6f 79  ment] is destroy
27fd0 65 64 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c  ed.** using [sql
27fe0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
27ff0 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 74   or until the st
28000 61 74 65 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d  atement is autom
28010 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72  atically.** repr
28020 65 70 61 72 65 64 20 62 79 20 74 68 65 20 66 69  epared by the fi
28030 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  rst call to [sql
28040 69 74 65 33 5f 73 74 65 70 28 29 5d 20 66 6f 72  ite3_step()] for
28050 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 75   a particular ru
28060 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68  n.** or until th
28070 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69  e same informati
28080 6f 6e 20 69 73 20 72 65 71 75 65 73 74 65 64 0a  on is requested.
28090 2a 2a 20 61 67 61 69 6e 20 69 6e 20 61 20 64 69  ** again in a di
280a0 66 66 65 72 65 6e 74 20 65 6e 63 6f 64 69 6e 67  fferent encoding
280b0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d  ..**.** ^The nam
280c0 65 73 20 72 65 74 75 72 6e 65 64 20 61 72 65 20  es returned are 
280d0 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 75 6e 2d  the original un-
280e0 61 6c 69 61 73 65 64 20 6e 61 6d 65 73 20 6f 66  aliased names of
280f0 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
28100 2c 20 74 61 62 6c 65 2c 20 61 6e 64 20 63 6f 6c  , table, and col
28110 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  umn..**.** ^The 
28120 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
28130 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63  o these interfac
28140 65 73 20 69 73 20 61 20 5b 70 72 65 70 61 72 65  es is a [prepare
28150 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a  d statement]..**
28160 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e   ^These function
28170 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61  s return informa
28180 74 69 6f 6e 20 61 62 6f 75 74 20 74 68 65 20 4e  tion about the N
28190 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  th result column
281a0 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20   returned by.** 
281b0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2c 20 77  the statement, w
281c0 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 73 65  here N is the se
281d0 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61 72  cond function ar
281e0 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20  gument..** ^The 
281f0 6c 65 66 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e  left-most column
28200 20 69 73 20 63 6f 6c 75 6d 6e 20 30 20 66 6f 72   is column 0 for
28210 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e   these routines.
28220 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 4e  .**.** ^If the N
28230 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e  th column return
28240 65 64 20 62 79 20 74 68 65 20 73 74 61 74 65 6d  ed by the statem
28250 65 6e 74 20 69 73 20 61 6e 20 65 78 70 72 65 73  ent is an expres
28260 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62 71 75  sion or.** subqu
28270 65 72 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 61  ery and is not a
28280 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 74   column value, t
28290 68 65 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73 65  hen all of these
282a0 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72   functions retur
282b0 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 5e 54 68 65  n.** NULL.  ^The
282c0 73 65 20 72 6f 75 74 69 6e 65 20 6d 69 67 68 74  se routine might
282d0 20 61 6c 73 6f 20 72 65 74 75 72 6e 20 4e 55 4c   also return NUL
282e0 4c 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c  L if a memory al
282f0 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 0a 2a  location error.*
28300 2a 20 6f 63 63 75 72 73 2e 20 20 5e 4f 74 68 65  * occurs.  ^Othe
28310 72 77 69 73 65 2c 20 74 68 65 79 20 72 65 74 75  rwise, they retu
28320 72 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  rn the name of t
28330 68 65 20 61 74 74 61 63 68 65 64 20 64 61 74 61  he attached data
28340 62 61 73 65 2c 20 74 61 62 6c 65 2c 0a 2a 2a 20  base, table,.** 
28350 6f 72 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 71  or column that q
28360 75 65 72 79 20 72 65 73 75 6c 74 20 63 6f 6c 75  uery result colu
28370 6d 6e 20 77 61 73 20 65 78 74 72 61 63 74 65 64  mn was extracted
28380 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73   from..**.** ^As
28390 20 77 69 74 68 20 61 6c 6c 20 6f 74 68 65 72 20   with all other 
283a0 53 51 4c 69 74 65 20 41 50 49 73 2c 20 74 68 6f  SQLite APIs, tho
283b0 73 65 20 77 68 6f 73 65 20 6e 61 6d 65 73 20 65  se whose names e
283c0 6e 64 20 77 69 74 68 20 22 31 36 22 20 72 65 74  nd with "16" ret
283d0 75 72 6e 0a 2a 2a 20 55 54 46 2d 31 36 20 65 6e  urn.** UTF-16 en
283e0 63 6f 64 65 64 20 73 74 72 69 6e 67 73 20 61 6e  coded strings an
283f0 64 20 74 68 65 20 6f 74 68 65 72 20 66 75 6e 63  d the other func
28400 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 55 54 46  tions return UTF
28410 2d 38 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  -8..**.** ^These
28420 20 41 50 49 73 20 61 72 65 20 6f 6e 6c 79 20 61   APIs are only a
28430 76 61 69 6c 61 62 6c 65 20 69 66 20 74 68 65 20  vailable if the 
28440 6c 69 62 72 61 72 79 20 77 61 73 20 63 6f 6d 70  library was comp
28450 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a  iled with the.**
28460 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f   [SQLITE_ENABLE_
28470 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41 5d  COLUMN_METADATA]
28480 20 43 2d 70 72 65 70 72 6f 63 65 73 73 6f 72 20   C-preprocessor 
28490 73 79 6d 62 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49 66  symbol..**.** If
284a0 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72   two or more thr
284b0 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72  eads call one or
284c0 20 6d 6f 72 65 20 6f 66 20 74 68 65 73 65 20 72   more of these r
284d0 6f 75 74 69 6e 65 73 20 61 67 61 69 6e 73 74 20  outines against 
284e0 74 68 65 20 73 61 6d 65 0a 2a 2a 20 70 72 65 70  the same.** prep
284f0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61  ared statement a
28500 6e 64 20 63 6f 6c 75 6d 6e 20 61 74 20 74 68 65  nd column at the
28510 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20   same time then 
28520 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 0a  the results are.
28530 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  ** undefined..**
28540 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f  .** If two or mo
28550 72 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20  re threads call 
28560 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 5b  one or more.** [
28570 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
28580 61 74 61 62 61 73 65 5f 6e 61 6d 65 20 7c 20 63  atabase_name | c
28590 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 74 61 20 69  olumn metadata i
285a0 6e 74 65 72 66 61 63 65 73 5d 0a 2a 2a 20 66 6f  nterfaces].** fo
285b0 72 20 74 68 65 20 73 61 6d 65 20 5b 70 72 65 70  r the same [prep
285c0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
285d0 61 6e 64 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  and result colum
285e0 6e 0a 2a 2a 20 61 74 20 74 68 65 20 73 61 6d 65  n.** at the same
285f0 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72   time then the r
28600 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66  esults are undef
28610 69 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63  ined..*/.const c
28620 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
28630 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d  umn_database_nam
28640 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
28650 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  int);.const void
28660 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
28670 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 31 36  _database_name16
28680 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
28690 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20  nt);.const char 
286a0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
286b0 74 61 62 6c 65 5f 6e 61 6d 65 28 73 71 6c 69 74  table_name(sqlit
286c0 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63  e3_stmt*,int);.c
286d0 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
286e0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f  e3_column_table_
286f0 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73  name16(sqlite3_s
28700 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74  tmt*,int);.const
28710 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
28720 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d  olumn_origin_nam
28730 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
28740 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  int);.const void
28750 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
28760 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28 73  _origin_name16(s
28770 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
28780 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
28790 45 46 3a 20 44 65 63 6c 61 72 65 64 20 44 61 74  EF: Declared Dat
287a0 61 74 79 70 65 20 4f 66 20 41 20 51 75 65 72 79  atype Of A Query
287b0 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e 28   Result.**.** ^(
287c0 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
287d0 74 65 72 20 69 73 20 61 20 5b 70 72 65 70 61 72  ter is a [prepar
287e0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a  ed statement]..*
287f0 2a 20 49 66 20 74 68 69 73 20 73 74 61 74 65 6d  * If this statem
28800 65 6e 74 20 69 73 20 61 20 5b 53 45 4c 45 43 54  ent is a [SELECT
28810 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20  ] statement and 
28820 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f  the Nth column o
28830 66 20 74 68 65 0a 2a 2a 20 72 65 74 75 72 6e 65  f the.** returne
28840 64 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20  d result set of 
28850 74 68 61 74 20 5b 53 45 4c 45 43 54 5d 20 69 73  that [SELECT] is
28860 20 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20   a table column 
28870 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72 65  (not an.** expre
28880 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72  ssion or subquer
28890 79 29 20 74 68 65 6e 20 74 68 65 20 64 65 63 6c  y) then the decl
288a0 61 72 65 64 20 74 79 70 65 20 6f 66 20 74 68 65  ared type of the
288b0 20 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e   table.** column
288c0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20   is returned.)^ 
288d0 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c   ^If the Nth col
288e0 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c  umn of the resul
288f0 74 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20 65  t set is an.** e
28900 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62  xpression or sub
28910 71 75 65 72 79 2c 20 74 68 65 6e 20 61 20 4e 55  query, then a NU
28920 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65  LL pointer is re
28930 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65 20  turned..** ^The 
28940 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20  returned string 
28950 69 73 20 61 6c 77 61 79 73 20 55 54 46 2d 38 20  is always UTF-8 
28960 65 6e 63 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  encoded..**.** ^
28970 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 67 69  (For example, gi
28980 76 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  ven the database
28990 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43   schema:.**.** C
289a0 52 45 41 54 45 20 54 41 42 4c 45 20 74 31 28 63  REATE TABLE t1(c
289b0 31 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a  1 VARIANT);.**.*
289c0 2a 20 61 6e 64 20 74 68 65 20 66 6f 6c 6c 6f 77  * and the follow
289d0 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 74 6f  ing statement to
289e0 20 62 65 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a   be compiled:.**
289f0 0a 2a 2a 20 53 45 4c 45 43 54 20 63 31 20 2b 20  .** SELECT c1 + 
28a00 31 2c 20 63 31 20 46 52 4f 4d 20 74 31 3b 0a 2a  1, c1 FROM t1;.*
28a10 2a 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e  *.** this routin
28a20 65 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 20 74  e would return t
28a30 68 65 20 73 74 72 69 6e 67 20 22 56 41 52 49 41  he string "VARIA
28a40 4e 54 22 20 66 6f 72 20 74 68 65 20 73 65 63 6f  NT" for the seco
28a50 6e 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c  nd result.** col
28a60 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e 64 20  umn (i==1), and 
28a70 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66  a NULL pointer f
28a80 6f 72 20 74 68 65 20 66 69 72 73 74 20 72 65 73  or the first res
28a90 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 30  ult column (i==0
28aa0 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69  ).)^.**.** ^SQLi
28ab0 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20  te uses dynamic 
28ac0 72 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67 2e  run-time typing.
28ad0 20 20 5e 53 6f 20 6a 75 73 74 20 62 65 63 61 75    ^So just becau
28ae0 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69  se a column.** i
28af0 73 20 64 65 63 6c 61 72 65 64 20 74 6f 20 63 6f  s declared to co
28b00 6e 74 61 69 6e 20 61 20 70 61 72 74 69 63 75 6c  ntain a particul
28b10 61 72 20 74 79 70 65 20 64 6f 65 73 20 6e 6f 74  ar type does not
28b20 20 6d 65 61 6e 20 74 68 61 74 20 74 68 65 0a 2a   mean that the.*
28b30 2a 20 64 61 74 61 20 73 74 6f 72 65 64 20 69 6e  * data stored in
28b40 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20   that column is 
28b50 6f 66 20 74 68 65 20 64 65 63 6c 61 72 65 64 20  of the declared 
28b60 74 79 70 65 2e 20 20 53 51 4c 69 74 65 20 69 73  type.  SQLite is
28b70 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79 70  .** strongly typ
28b80 65 64 2c 20 62 75 74 20 74 68 65 20 74 79 70 69  ed, but the typi
28b90 6e 67 20 69 73 20 64 79 6e 61 6d 69 63 20 6e 6f  ng is dynamic no
28ba0 74 20 73 74 61 74 69 63 2e 20 20 5e 54 79 70 65  t static.  ^Type
28bb0 0a 2a 2a 20 69 73 20 61 73 73 6f 63 69 61 74 65  .** is associate
28bc0 64 20 77 69 74 68 20 69 6e 64 69 76 69 64 75 61  d with individua
28bd0 6c 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77 69  l values, not wi
28be0 74 68 20 74 68 65 20 63 6f 6e 74 61 69 6e 65 72  th the container
28bf0 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f 6c  s.** used to hol
28c00 64 20 74 68 6f 73 65 20 76 61 6c 75 65 73 2e 0a  d those values..
28c10 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  */.const char *s
28c20 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65  qlite3_column_de
28c30 63 6c 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73  cltype(sqlite3_s
28c40 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74  tmt*,int);.const
28c50 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
28c60 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36  olumn_decltype16
28c70 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
28c80 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
28c90 33 52 45 46 3a 20 45 76 61 6c 75 61 74 65 20 41  3REF: Evaluate A
28ca0 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a  n SQL Statement.
28cb0 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61 20 5b 70  **.** After a [p
28cc0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
28cd0 74 5d 20 68 61 73 20 62 65 65 6e 20 70 72 65 70  t] has been prep
28ce0 61 72 65 64 20 75 73 69 6e 67 20 65 69 74 68 65  ared using eithe
28cf0 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  r.** [sqlite3_pr
28d00 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b  epare_v2()] or [
28d10 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
28d20 36 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f  6_v2()] or one o
28d30 66 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20  f the legacy.** 
28d40 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69  interfaces [sqli
28d50 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f  te3_prepare()] o
28d60 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
28d70 72 65 31 36 28 29 5d 2c 20 74 68 69 73 20 66 75  re16()], this fu
28d80 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62  nction.** must b
28d90 65 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20  e called one or 
28da0 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 65 76  more times to ev
28db0 61 6c 75 61 74 65 20 74 68 65 20 73 74 61 74 65  aluate the state
28dc0 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ment..**.** The 
28dd0 64 65 74 61 69 6c 73 20 6f 66 20 74 68 65 20 62  details of the b
28de0 65 68 61 76 69 6f 72 20 6f 66 20 74 68 65 20 73  ehavior of the s
28df0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e  qlite3_step() in
28e00 74 65 72 66 61 63 65 20 64 65 70 65 6e 64 0a 2a  terface depend.*
28e10 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 74 68 65  * on whether the
28e20 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 20 70   statement was p
28e30 72 65 70 61 72 65 64 20 75 73 69 6e 67 20 74 68  repared using th
28e40 65 20 6e 65 77 65 72 20 22 76 32 22 20 69 6e 74  e newer "v2" int
28e50 65 72 66 61 63 65 0a 2a 2a 20 5b 73 71 6c 69 74  erface.** [sqlit
28e60 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
28e70 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72   and [sqlite3_pr
28e80 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72  epare16_v2()] or
28e90 20 74 68 65 20 6f 6c 64 65 72 20 6c 65 67 61 63   the older legac
28ea0 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 5b  y.** interface [
28eb0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
28ec0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
28ed0 70 72 65 70 61 72 65 31 36 28 29 5d 2e 20 20 54  prepare16()].  T
28ee0 68 65 20 75 73 65 20 6f 66 20 74 68 65 0a 2a 2a  he use of the.**
28ef0 20 6e 65 77 20 22 76 32 22 20 69 6e 74 65 72 66   new "v2" interf
28f00 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64  ace is recommend
28f10 65 64 20 66 6f 72 20 6e 65 77 20 61 70 70 6c 69  ed for new appli
28f20 63 61 74 69 6f 6e 73 20 62 75 74 20 74 68 65 20  cations but the 
28f30 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66  legacy.** interf
28f40 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74 69 6e 75  ace will continu
28f50 65 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65  e to be supporte
28f60 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65  d..**.** ^In the
28f70 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63   legacy interfac
28f80 65 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  e, the return va
28f90 6c 75 65 20 77 69 6c 6c 20 62 65 20 65 69 74 68  lue will be eith
28fa0 65 72 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  er [SQLITE_BUSY]
28fb0 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e  ,.** [SQLITE_DON
28fc0 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  E], [SQLITE_ROW]
28fd0 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  , [SQLITE_ERROR]
28fe0 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53  , or [SQLITE_MIS
28ff0 55 53 45 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74  USE]..** ^With t
29000 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  he "v2" interfac
29010 65 2c 20 61 6e 79 20 6f 66 20 74 68 65 20 6f 74  e, any of the ot
29020 68 65 72 20 5b 72 65 73 75 6c 74 20 63 6f 64 65  her [result code
29030 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64  s] or.** [extend
29040 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d  ed result codes]
29050 20 6d 69 67 68 74 20 62 65 20 72 65 74 75 72 6e   might be return
29060 65 64 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a  ed as well..**.*
29070 2a 20 5e 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  * ^[SQLITE_BUSY]
29080 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20   means that the 
29090 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65 20  database engine 
290a0 77 61 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 63  was unable to ac
290b0 71 75 69 72 65 20 74 68 65 0a 2a 2a 20 64 61 74  quire the.** dat
290c0 61 62 61 73 65 20 6c 6f 63 6b 73 20 69 74 20 6e  abase locks it n
290d0 65 65 64 73 20 74 6f 20 64 6f 20 69 74 73 20 6a  eeds to do its j
290e0 6f 62 2e 20 20 5e 49 66 20 74 68 65 20 73 74 61  ob.  ^If the sta
290f0 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 43 4f 4d  tement is a [COM
29100 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75 72  MIT].** or occur
29110 73 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e 20  s outside of an 
29120 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63  explicit transac
29130 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 20 63  tion, then you c
29140 61 6e 20 72 65 74 72 79 20 74 68 65 0a 2a 2a 20  an retry the.** 
29150 73 74 61 74 65 6d 65 6e 74 2e 20 20 49 66 20 74  statement.  If t
29160 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
29170 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 61  not a [COMMIT] a
29180 6e 64 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e  nd occurs within
29190 20 61 6e 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20   an.** explicit 
291a0 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 68 65 6e  transaction then
291b0 20 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c 6c   you should roll
291c0 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63  back the transac
291d0 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 63  tion before.** c
291e0 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a  ontinuing..**.**
291f0 20 5e 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20   ^[SQLITE_DONE] 
29200 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 73  means that the s
29210 74 61 74 65 6d 65 6e 74 20 68 61 73 20 66 69 6e  tatement has fin
29220 69 73 68 65 64 20 65 78 65 63 75 74 69 6e 67 0a  ished executing.
29230 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e  ** successfully.
29240 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29    sqlite3_step()
29250 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63   should not be c
29260 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20 74  alled again on t
29270 68 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d  his virtual.** m
29280 61 63 68 69 6e 65 20 77 69 74 68 6f 75 74 20 66  achine without f
29290 69 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71  irst calling [sq
292a0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74  lite3_reset()] t
292b0 6f 20 72 65 73 65 74 20 74 68 65 20 76 69 72 74  o reset the virt
292c0 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 62  ual.** machine b
292d0 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69  ack to its initi
292e0 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20  al state..**.** 
292f0 5e 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 74  ^If the SQL stat
29300 65 6d 65 6e 74 20 62 65 69 6e 67 20 65 78 65 63  ement being exec
29310 75 74 65 64 20 72 65 74 75 72 6e 73 20 61 6e 79  uted returns any
29320 20 64 61 74 61 2c 20 74 68 65 6e 20 5b 53 51 4c   data, then [SQL
29330 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20 72  ITE_ROW].** is r
29340 65 74 75 72 6e 65 64 20 65 61 63 68 20 74 69 6d  eturned each tim
29350 65 20 61 20 6e 65 77 20 72 6f 77 20 6f 66 20 64  e a new row of d
29360 61 74 61 20 69 73 20 72 65 61 64 79 20 66 6f 72  ata is ready for
29370 20 70 72 6f 63 65 73 73 69 6e 67 20 62 79 20 74   processing by t
29380 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20 54 68  he.** caller. Th
29390 65 20 76 61 6c 75 65 73 20 6d 61 79 20 62 65 20  e values may be 
293a0 61 63 63 65 73 73 65 64 20 75 73 69 6e 67 20 74  accessed using t
293b0 68 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73  he [column acces
293c0 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a  s functions]..**
293d0 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
293e0 69 73 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20  is called again 
293f0 74 6f 20 72 65 74 72 69 65 76 65 20 74 68 65 20  to retrieve the 
29400 6e 65 78 74 20 72 6f 77 20 6f 66 20 64 61 74 61  next row of data
29410 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45  ..**.** ^[SQLITE
29420 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74 68  _ERROR] means th
29430 61 74 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 72  at a run-time er
29440 72 6f 72 20 28 73 75 63 68 20 61 73 20 61 20 63  ror (such as a c
29450 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69 6f  onstraint.** vio
29460 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f 63 63 75  lation) has occu
29470 72 72 65 64 2e 20 20 73 71 6c 69 74 65 33 5f 73  rred.  sqlite3_s
29480 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74  tep() should not
29490 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e   be called again
294a0 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20 4d   on.** the VM. M
294b0 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  ore information 
294c0 6d 61 79 20 62 65 20 66 6f 75 6e 64 20 62 79 20  may be found by 
294d0 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
294e0 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 5e  _errmsg()]..** ^
294f0 57 69 74 68 20 74 68 65 20 6c 65 67 61 63 79 20  With the legacy 
29500 69 6e 74 65 72 66 61 63 65 2c 20 61 20 6d 6f 72  interface, a mor
29510 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72  e specific error
29520 20 63 6f 64 65 20 28 66 6f 72 20 65 78 61 6d 70   code (for examp
29530 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49  le,.** [SQLITE_I
29540 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c 49  NTERRUPT], [SQLI
29550 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51 4c  TE_SCHEMA], [SQL
29560 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61 6e  ITE_CORRUPT], an
29570 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20 63  d so forth).** c
29580 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20 62  an be obtained b
29590 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  y calling [sqlit
295a0 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20 74  e3_reset()] on t
295b0 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  he.** [prepared 
295c0 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 5e 49 6e  statement].  ^In
295d0 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66   the "v2" interf
295e0 61 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 65  ace,.** the more
295f0 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20   specific error 
29600 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65 64  code is returned
29610 20 64 69 72 65 63 74 6c 79 20 62 79 20 73 71 6c   directly by sql
29620 69 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a  ite3_step()..**.
29630 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  ** [SQLITE_MISUS
29640 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  E] means that th
29650 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  e this routine w
29660 61 73 20 63 61 6c 6c 65 64 20 69 6e 61 70 70 72  as called inappr
29670 6f 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 65  opriately..** Pe
29680 72 68 61 70 73 20 69 74 20 77 61 73 20 63 61 6c  rhaps it was cal
29690 6c 65 64 20 6f 6e 20 61 20 5b 70 72 65 70 61 72  led on a [prepar
296a0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68  ed statement] th
296b0 61 74 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61 64  at has.** alread
296c0 79 20 62 65 65 6e 20 5b 73 71 6c 69 74 65 33 5f  y been [sqlite3_
296d0 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c  finalize | final
296e0 69 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20  ized] or on one 
296f0 74 68 61 74 20 68 61 64 0a 2a 2a 20 70 72 65 76  that had.** prev
29700 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 20  iously returned 
29710 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6f  [SQLITE_ERROR] o
29720 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e  r [SQLITE_DONE].
29730 20 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a 2a    Or it could.**
29740 20 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61   be the case tha
29750 74 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62  t the same datab
29760 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
29770 73 20 62 65 69 6e 67 20 75 73 65 64 20 62 79 20  s being used by 
29780 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74  two or.** more t
29790 68 72 65 61 64 73 20 61 74 20 74 68 65 20 73 61  hreads at the sa
297a0 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 6d  me moment in tim
297b0 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 61 6c 6c  e..**.** For all
297c0 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
297d0 69 74 65 20 75 70 20 74 6f 20 61 6e 64 20 69 6e  ite up to and in
297e0 63 6c 75 64 69 6e 67 20 33 2e 36 2e 32 33 2e 31  cluding 3.6.23.1
297f0 2c 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b  , a call to.** [
29800 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
29810 20 77 61 73 20 72 65 71 75 69 72 65 64 20 61 66   was required af
29820 74 65 72 20 73 71 6c 69 74 65 33 5f 73 74 65 70  ter sqlite3_step
29830 28 29 20 72 65 74 75 72 6e 65 64 20 61 6e 79 74  () returned anyt
29840 68 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 74 68  hing.** other th
29850 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20  an [SQLITE_ROW] 
29860 62 65 66 6f 72 65 20 61 6e 79 20 73 75 62 73 65  before any subse
29870 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e  quent invocation
29880 20 6f 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73   of.** sqlite3_s
29890 74 65 70 28 29 2e 20 20 46 61 69 6c 75 72 65 20  tep().  Failure 
298a0 74 6f 20 72 65 73 65 74 20 74 68 65 20 70 72 65  to reset the pre
298b0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
298c0 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74  using .** [sqlit
298d0 65 33 5f 72 65 73 65 74 28 29 5d 20 77 6f 75 6c  e3_reset()] woul
298e0 64 20 72 65 73 75 6c 74 20 69 6e 20 61 6e 20 5b  d result in an [
298f0 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 72  SQLITE_MISUSE] r
29900 65 74 75 72 6e 20 66 72 6f 6d 0a 2a 2a 20 73 71  eturn from.** sq
29910 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 42  lite3_step().  B
29920 75 74 20 61 66 74 65 72 20 76 65 72 73 69 6f 6e  ut after version
29930 20 33 2e 36 2e 32 33 2e 31 2c 20 73 71 6c 69 74   3.6.23.1, sqlit
29940 65 33 5f 73 74 65 70 28 29 20 62 65 67 61 6e 0a  e3_step() began.
29950 2a 2a 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  ** calling [sqli
29960 74 65 33 5f 72 65 73 65 74 28 29 5d 20 61 75 74  te3_reset()] aut
29970 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e 20 74 68  omatically in th
29980 69 73 20 63 69 72 63 75 6d 73 74 61 6e 63 65 20  is circumstance 
29990 72 61 74 68 65 72 0a 2a 2a 20 74 68 61 6e 20 72  rather.** than r
299a0 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45  eturning [SQLITE
299b0 5f 4d 49 53 55 53 45 5d 2e 20 20 54 68 69 73 20  _MISUSE].  This 
299c0 69 73 20 6e 6f 74 20 63 6f 6e 73 69 64 65 72 65  is not considere
299d0 64 20 61 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  d a compatibilit
299e0 79 0a 2a 2a 20 62 72 65 61 6b 20 62 65 63 61 75  y.** break becau
299f0 73 65 20 61 6e 79 20 61 70 70 6c 69 63 61 74 69  se any applicati
29a00 6f 6e 20 74 68 61 74 20 65 76 65 72 20 72 65 63  on that ever rec
29a10 65 69 76 65 73 20 61 6e 20 53 51 4c 49 54 45 5f  eives an SQLITE_
29a20 4d 49 53 55 53 45 20 65 72 72 6f 72 0a 2a 2a 20  MISUSE error.** 
29a30 69 73 20 62 72 6f 6b 65 6e 20 62 79 20 64 65 66  is broken by def
29a40 69 6e 69 74 69 6f 6e 2e 20 20 54 68 65 20 5b 53  inition.  The [S
29a50 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 52  QLITE_OMIT_AUTOR
29a60 45 53 45 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  ESET] compile-ti
29a70 6d 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 63 61 6e  me option.** can
29a80 20 62 65 20 75 73 65 64 20 74 6f 20 72 65 73 74   be used to rest
29a90 6f 72 65 20 74 68 65 20 6c 65 67 61 63 79 20 62  ore the legacy b
29aa0 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c  ehavior..**.** <
29ab0 62 3e 47 6f 6f 66 79 20 49 6e 74 65 72 66 61 63  b>Goofy Interfac
29ac0 65 20 41 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e 20  e Alert:</b> In 
29ad0 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72  the legacy inter
29ae0 66 61 63 65 2c 20 74 68 65 20 73 71 6c 69 74 65  face, the sqlite
29af0 33 5f 73 74 65 70 28 29 0a 2a 2a 20 41 50 49 20  3_step().** API 
29b00 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 61  always returns a
29b10 20 67 65 6e 65 72 69 63 20 65 72 72 6f 72 20 63   generic error c
29b20 6f 64 65 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52  ode, [SQLITE_ERR
29b30 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  OR], following a
29b40 6e 79 0a 2a 2a 20 65 72 72 6f 72 20 6f 74 68 65  ny.** error othe
29b50 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 42  r than [SQLITE_B
29b60 55 53 59 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45  USY] and [SQLITE
29b70 5f 4d 49 53 55 53 45 5d 2e 20 20 59 6f 75 20 6d  _MISUSE].  You m
29b80 75 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c  ust call.** [sql
29b90 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72  ite3_reset()] or
29ba0 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
29bb0 7a 65 28 29 5d 20 69 6e 20 6f 72 64 65 72 20 74  ze()] in order t
29bc0 6f 20 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74 68  o find one of th
29bd0 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 5b 65  e.** specific [e
29be0 72 72 6f 72 20 63 6f 64 65 73 5d 20 74 68 61 74  rror codes] that
29bf0 20 62 65 74 74 65 72 20 64 65 73 63 72 69 62 65   better describe
29c00 73 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 20  s the error..** 
29c10 57 65 20 61 64 6d 69 74 20 74 68 61 74 20 74 68  We admit that th
29c20 69 73 20 69 73 20 61 20 67 6f 6f 66 79 20 64 65  is is a goofy de
29c30 73 69 67 6e 2e 20 20 54 68 65 20 70 72 6f 62 6c  sign.  The probl
29c40 65 6d 20 68 61 73 20 62 65 65 6e 20 66 69 78 65  em has been fixe
29c50 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 22 76  d.** with the "v
29c60 32 22 20 69 6e 74 65 72 66 61 63 65 2e 20 20 49  2" interface.  I
29c70 66 20 79 6f 75 20 70 72 65 70 61 72 65 20 61 6c  f you prepare al
29c80 6c 20 6f 66 20 79 6f 75 72 20 53 51 4c 20 73 74  l of your SQL st
29c90 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69 6e  atements.** usin
29ca0 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65  g either [sqlite
29cb0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
29cc0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  or [sqlite3_prep
29cd0 61 72 65 31 36 5f 76 32 28 29 5d 20 69 6e 73 74  are16_v2()] inst
29ce0 65 61 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c 65  ead.** of the le
29cf0 67 61 63 79 20 5b 73 71 6c 69 74 65 33 5f 70 72  gacy [sqlite3_pr
29d00 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71  epare()] and [sq
29d10 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
29d20 29 5d 20 69 6e 74 65 72 66 61 63 65 73 2c 0a 2a  )] interfaces,.*
29d30 2a 20 74 68 65 6e 20 74 68 65 20 6d 6f 72 65 20  * then the more 
29d40 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20  specific [error 
29d50 63 6f 64 65 73 5d 20 61 72 65 20 72 65 74 75 72  codes] are retur
29d60 6e 65 64 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20  ned directly.** 
29d70 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  by sqlite3_step(
29d80 29 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20 74  ).  The use of t
29d90 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  he "v2" interfac
29da0 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  e is recommended
29db0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
29dc0 5f 73 74 65 70 28 73 71 6c 69 74 65 33 5f 73 74  _step(sqlite3_st
29dd0 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  mt*);../*.** CAP
29de0 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 6f 66  I3REF: Number of
29df0 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 72 65   columns in a re
29e00 73 75 6c 74 20 73 65 74 0a 2a 2a 0a 2a 2a 20 5e  sult set.**.** ^
29e10 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61  The sqlite3_data
29e20 5f 63 6f 75 6e 74 28 50 29 20 69 6e 74 65 72 66  _count(P) interf
29e30 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ace returns the 
29e40 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
29e50 73 20 69 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72  s in the.** curr
29e60 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72  ent row of the r
29e70 65 73 75 6c 74 20 73 65 74 20 6f 66 20 5b 70 72  esult set of [pr
29e80 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
29e90 5d 20 50 2e 0a 2a 2a 20 5e 49 66 20 70 72 65 70  ] P..** ^If prep
29ea0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 50  ared statement P
29eb0 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 72   does not have r
29ec0 65 73 75 6c 74 73 20 72 65 61 64 79 20 74 6f 20  esults ready to 
29ed0 72 65 74 75 72 6e 0a 2a 2a 20 28 76 69 61 20 63  return.** (via c
29ee0 61 6c 6c 73 20 74 6f 20 74 68 65 20 5b 73 71 6c  alls to the [sql
29ef0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 20  ite3_column_int 
29f00 7c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  | sqlite3_column
29f10 5f 2a 28 29 5d 20 6f 66 0a 2a 2a 20 69 6e 74 65  _*()] of.** inte
29f20 72 66 61 63 65 73 29 20 74 68 65 6e 20 73 71 6c  rfaces) then sql
29f30 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
29f40 50 29 20 72 65 74 75 72 6e 73 20 30 2e 0a 2a 2a  P) returns 0..**
29f50 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61   ^The sqlite3_da
29f60 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75 74  ta_count(P) rout
29f70 69 6e 65 20 61 6c 73 6f 20 72 65 74 75 72 6e 73  ine also returns
29f80 20 30 20 69 66 20 50 20 69 73 20 61 20 4e 55 4c   0 if P is a NUL
29f90 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20 5e 54  L pointer..** ^T
29fa0 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f  he sqlite3_data_
29fb0 63 6f 75 6e 74 28 50 29 20 72 6f 75 74 69 6e 65  count(P) routine
29fc0 20 72 65 74 75 72 6e 73 20 30 20 69 66 20 74 68   returns 0 if th
29fd0 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20  e previous call 
29fe0 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  to.** [sqlite3_s
29ff0 74 65 70 5d 28 50 29 20 72 65 74 75 72 6e 65 64  tep](P) returned
2a000 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20   [SQLITE_DONE]. 
2a010 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61   ^The sqlite3_da
2a020 74 61 5f 63 6f 75 6e 74 28 50 29 0a 2a 2a 20 77  ta_count(P).** w
2a030 69 6c 6c 20 72 65 74 75 72 6e 20 6e 6f 6e 2d 7a  ill return non-z
2a040 65 72 6f 20 69 66 20 70 72 65 76 69 6f 75 73 20  ero if previous 
2a050 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
2a060 5f 73 74 65 70 5d 28 50 29 20 72 65 74 75 72 6e  _step](P) return
2a070 65 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 52 4f  ed.** [SQLITE_RO
2a080 57 5d 2c 20 65 78 63 65 70 74 20 69 6e 20 74 68  W], except in th
2a090 65 20 63 61 73 65 20 6f 66 20 74 68 65 20 5b 50  e case of the [P
2a0a0 52 41 47 4d 41 20 69 6e 63 72 65 6d 65 6e 74 61  RAGMA incrementa
2a0b0 6c 5f 76 61 63 75 75 6d 5d 0a 2a 2a 20 77 68 65  l_vacuum].** whe
2a0c0 72 65 20 69 74 20 61 6c 77 61 79 73 20 72 65 74  re it always ret
2a0d0 75 72 6e 73 20 7a 65 72 6f 20 73 69 6e 63 65 20  urns zero since 
2a0e0 65 61 63 68 20 73 74 65 70 20 6f 66 20 74 68 61  each step of tha
2a0f0 74 20 6d 75 6c 74 69 2d 73 74 65 70 0a 2a 2a 20  t multi-step.** 
2a100 70 72 61 67 6d 61 20 72 65 74 75 72 6e 73 20 30  pragma returns 0
2a110 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 64 61 74 61   columns of data
2a120 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
2a130 3a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  : [sqlite3_colum
2a140 6e 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69 6e  n_count()].*/.in
2a150 74 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63  t sqlite3_data_c
2a160 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  ount(sqlite3_stm
2a170 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a  t *pStmt);../*.*
2a180 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e 64  * CAPI3REF: Fund
2a190 61 6d 65 6e 74 61 6c 20 44 61 74 61 74 79 70 65  amental Datatype
2a1a0 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53  s.** KEYWORDS: S
2a1b0 51 4c 49 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a 2a  QLITE_TEXT.**.**
2a1c0 20 5e 28 45 76 65 72 79 20 76 61 6c 75 65 20 69   ^(Every value i
2a1d0 6e 20 53 51 4c 69 74 65 20 68 61 73 20 6f 6e 65  n SQLite has one
2a1e0 20 6f 66 20 66 69 76 65 20 66 75 6e 64 61 6d 65   of five fundame
2a1f0 6e 74 61 6c 20 64 61 74 61 74 79 70 65 73 3a 0a  ntal datatypes:.
2a200 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
2a210 69 3e 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64  i> 64-bit signed
2a220 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e   integer.** <li>
2a230 20 36 34 2d 62 69 74 20 49 45 45 45 20 66 6c 6f   64-bit IEEE flo
2a240 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62  ating point numb
2a250 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72 69 6e  er.** <li> strin
2a260 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a  g.** <li> BLOB.*
2a270 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c  * <li> NULL.** <
2a280 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65  /ul>)^.**.** The
2a290 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65  se constants are
2a2a0 20 63 6f 64 65 73 20 66 6f 72 20 65 61 63 68 20   codes for each 
2a2b0 6f 66 20 74 68 6f 73 65 20 74 79 70 65 73 2e 0a  of those types..
2a2c0 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  **.** Note that 
2a2d0 74 68 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20  the SQLITE_TEXT 
2a2e0 63 6f 6e 73 74 61 6e 74 20 77 61 73 20 61 6c 73  constant was als
2a2f0 6f 20 75 73 65 64 20 69 6e 20 53 51 4c 69 74 65  o used in SQLite
2a300 20 76 65 72 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f   version 2.** fo
2a310 72 20 61 20 63 6f 6d 70 6c 65 74 65 6c 79 20 64  r a completely d
2a320 69 66 66 65 72 65 6e 74 20 6d 65 61 6e 69 6e 67  ifferent meaning
2a330 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68 61 74  .  Software that
2a340 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74 20 62   links against b
2a350 6f 74 68 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65  oth.** SQLite ve
2a360 72 73 69 6f 6e 20 32 20 61 6e 64 20 53 51 4c 69  rsion 2 and SQLi
2a370 74 65 20 76 65 72 73 69 6f 6e 20 33 20 73 68 6f  te version 3 sho
2a380 75 6c 64 20 75 73 65 20 53 51 4c 49 54 45 33 5f  uld use SQLITE3_
2a390 54 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51 4c  TEXT, not.** SQL
2a3a0 49 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64 65  ITE_TEXT..*/.#de
2a3b0 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45  fine SQLITE_INTE
2a3c0 47 45 52 20 20 31 0a 23 64 65 66 69 6e 65 20 53  GER  1.#define S
2a3d0 51 4c 49 54 45 5f 46 4c 4f 41 54 20 20 20 20 32  QLITE_FLOAT    2
2a3e0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2a3f0 42 4c 4f 42 20 20 20 20 20 34 0a 23 64 65 66 69  BLOB     4.#defi
2a400 6e 65 20 53 51 4c 49 54 45 5f 4e 55 4c 4c 20 20  ne SQLITE_NULL  
2a410 20 20 20 35 0a 23 69 66 64 65 66 20 53 51 4c 49     5.#ifdef SQLI
2a420 54 45 5f 54 45 58 54 0a 23 20 75 6e 64 65 66 20  TE_TEXT.# undef 
2a430 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 65 6c 73  SQLITE_TEXT.#els
2a440 65 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54  e.# define SQLIT
2a450 45 5f 54 45 58 54 20 20 20 20 20 33 0a 23 65 6e  E_TEXT     3.#en
2a460 64 69 66 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  dif.#define SQLI
2a470 54 45 33 5f 54 45 58 54 20 20 20 20 20 33 0a 0a  TE3_TEXT     3..
2a480 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2a490 52 65 73 75 6c 74 20 56 61 6c 75 65 73 20 46 72  Result Values Fr
2a4a0 6f 6d 20 41 20 51 75 65 72 79 0a 2a 2a 20 4b 45  om A Query.** KE
2a4b0 59 57 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d 6e 20  YWORDS: {column 
2a4c0 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73  access functions
2a4d0 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  }.**.** These ro
2a4e0 75 74 69 6e 65 73 20 66 6f 72 6d 20 74 68 65 20  utines form the 
2a4f0 22 72 65 73 75 6c 74 20 73 65 74 22 20 69 6e 74  "result set" int
2a500 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54  erface..**.** ^T
2a510 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65  hese routines re
2a520 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  turn information
2a530 20 61 62 6f 75 74 20 61 20 73 69 6e 67 6c 65 20   about a single 
2a540 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 63 75  column of the cu
2a550 72 72 65 6e 74 0a 2a 2a 20 72 65 73 75 6c 74 20  rrent.** result 
2a560 72 6f 77 20 6f 66 20 61 20 71 75 65 72 79 2e 20  row of a query. 
2a570 20 5e 49 6e 20 65 76 65 72 79 20 63 61 73 65 20   ^In every case 
2a580 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
2a590 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 0a  nt is a pointer.
2a5a0 2a 2a 20 74 6f 20 74 68 65 20 5b 70 72 65 70 61  ** to the [prepa
2a5b0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74  red statement] t
2a5c0 68 61 74 20 69 73 20 62 65 69 6e 67 20 65 76 61  hat is being eva
2a5d0 6c 75 61 74 65 64 20 28 74 68 65 20 5b 73 71 6c  luated (the [sql
2a5e0 69 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a 2a 20 74  ite3_stmt*].** t
2a5f0 68 61 74 20 77 61 73 20 72 65 74 75 72 6e 65 64  hat was returned
2a600 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 70   from [sqlite3_p
2a610 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
2a620 6f 6e 65 20 6f 66 20 69 74 73 20 76 61 72 69 61  one of its varia
2a630 6e 74 73 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20  nts).** and the 
2a640 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
2a650 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20  is the index of 
2a660 74 68 65 20 63 6f 6c 75 6d 6e 20 66 6f 72 20 77  the column for w
2a670 68 69 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  hich information
2a680 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 65  .** should be re
2a690 74 75 72 6e 65 64 2e 20 5e 54 68 65 20 6c 65 66  turned. ^The lef
2a6a0 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f 66 20  tmost column of 
2a6b0 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 68  the result set h
2a6c0 61 73 20 74 68 65 20 69 6e 64 65 78 20 30 2e 0a  as the index 0..
2a6d0 2a 2a 20 5e 54 68 65 20 6e 75 6d 62 65 72 20 6f  ** ^The number o
2a6e0 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65  f columns in the
2a6f0 20 72 65 73 75 6c 74 20 63 61 6e 20 62 65 20 64   result can be d
2a700 65 74 65 72 6d 69 6e 65 64 20 75 73 69 6e 67 0a  etermined using.
2a710 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
2a720 6d 6e 5f 63 6f 75 6e 74 28 29 5d 2e 0a 2a 2a 0a  mn_count()]..**.
2a730 2a 2a 20 49 66 20 74 68 65 20 53 51 4c 20 73 74  ** If the SQL st
2a740 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74  atement does not
2a750 20 63 75 72 72 65 6e 74 6c 79 20 70 6f 69 6e 74   currently point
2a760 20 74 6f 20 61 20 76 61 6c 69 64 20 72 6f 77 2c   to a valid row,
2a770 20 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20 63 6f   or if the.** co
2a780 6c 75 6d 6e 20 69 6e 64 65 78 20 69 73 20 6f 75  lumn index is ou
2a790 74 20 6f 66 20 72 61 6e 67 65 2c 20 74 68 65 20  t of range, the 
2a7a0 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69  result is undefi
2a7b0 6e 65 64 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ned..** These ro
2a7c0 75 74 69 6e 65 73 20 6d 61 79 20 6f 6e 6c 79 20  utines may only 
2a7d0 62 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 74  be called when t
2a7e0 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63  he most recent c
2a7f0 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  all to.** [sqlit
2a800 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72  e3_step()] has r
2a810 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f  eturned [SQLITE_
2a820 52 4f 57 5d 20 61 6e 64 20 6e 65 69 74 68 65 72  ROW] and neither
2a830 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  .** [sqlite3_res
2a840 65 74 28 29 5d 20 6e 6f 72 20 5b 73 71 6c 69 74  et()] nor [sqlit
2a850 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 68  e3_finalize()] h
2a860 61 76 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20  ave been called 
2a870 73 75 62 73 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a  subsequently..**
2a880 20 49 66 20 61 6e 79 20 6f 66 20 74 68 65 73 65   If any of these
2a890 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61   routines are ca
2a8a0 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69  lled after [sqli
2a8b0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a  te3_reset()] or.
2a8c0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ** [sqlite3_fina
2a8d0 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72  lize()] or after
2a8e0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
2a8f0 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64 0a 2a  ] has returned.*
2a900 2a 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65  * something othe
2a910 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52  r than [SQLITE_R
2a920 4f 57 5d 2c 20 74 68 65 20 72 65 73 75 6c 74 73  OW], the results
2a930 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a   are undefined..
2a940 2a 2a 20 49 66 20 5b 73 71 6c 69 74 65 33 5f 73  ** If [sqlite3_s
2a950 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  tep()] or [sqlit
2a960 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b  e3_reset()] or [
2a970 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2a980 28 29 5d 0a 2a 2a 20 61 72 65 20 63 61 6c 6c 65  ()].** are calle
2a990 64 20 66 72 6f 6d 20 61 20 64 69 66 66 65 72 65  d from a differe
2a9a0 6e 74 20 74 68 72 65 61 64 20 77 68 69 6c 65 20  nt thread while 
2a9b0 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75  any of these rou
2a9c0 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20 70 65 6e  tines.** are pen
2a9d0 64 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72  ding, then the r
2a9e0 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66  esults are undef
2a9f0 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ined..**.** ^The
2aa00 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2aa10 74 79 70 65 28 29 20 72 6f 75 74 69 6e 65 20 72  type() routine r
2aa20 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 5b 53  eturns the.** [S
2aa30 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20  QLITE_INTEGER | 
2aa40 64 61 74 61 74 79 70 65 20 63 6f 64 65 5d 20 66  datatype code] f
2aa50 6f 72 20 74 68 65 20 69 6e 69 74 69 61 6c 20 64  or the initial d
2aa60 61 74 61 20 74 79 70 65 0a 2a 2a 20 6f 66 20 74  ata type.** of t
2aa70 68 65 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  he result column
2aa80 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64  .  ^The returned
2aa90 20 76 61 6c 75 65 20 69 73 20 6f 6e 65 20 6f 66   value is one of
2aaa0 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52   [SQLITE_INTEGER
2aab0 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 4c  ],.** [SQLITE_FL
2aac0 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 45  OAT], [SQLITE_TE
2aad0 58 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 4c 4f  XT], [SQLITE_BLO
2aae0 42 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e  B], or [SQLITE_N
2aaf0 55 4c 4c 5d 2e 20 20 54 68 65 20 76 61 6c 75 65  ULL].  The value
2ab00 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20  .** returned by 
2ab10 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2ab20 79 70 65 28 29 20 69 73 20 6f 6e 6c 79 20 6d 65  ype() is only me
2ab30 61 6e 69 6e 67 66 75 6c 20 69 66 20 6e 6f 20 74  aningful if no t
2ab40 79 70 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f  ype.** conversio
2ab50 6e 73 20 68 61 76 65 20 6f 63 63 75 72 72 65 64  ns have occurred
2ab60 20 61 73 20 64 65 73 63 72 69 62 65 64 20 62 65   as described be
2ab70 6c 6f 77 2e 20 20 41 66 74 65 72 20 61 20 74 79  low.  After a ty
2ab80 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a 2a  pe conversion,.*
2ab90 2a 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  * the value retu
2aba0 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
2abb0 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73  column_type() is
2abc0 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 46 75 74   undefined.  Fut
2abd0 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20  ure.** versions 
2abe0 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20 63 68  of SQLite may ch
2abf0 61 6e 67 65 20 74 68 65 20 62 65 68 61 76 69 6f  ange the behavio
2ac00 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c  r of sqlite3_col
2ac10 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 66 6f  umn_type().** fo
2ac20 6c 6c 6f 77 69 6e 67 20 61 20 74 79 70 65 20 63  llowing a type c
2ac30 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  onversion..**.**
2ac40 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20   ^If the result 
2ac50 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46  is a BLOB or UTF
2ac60 2d 38 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74  -8 string then t
2ac70 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  he sqlite3_colum
2ac80 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20 72 6f 75  n_bytes().** rou
2ac90 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65  tine returns the
2aca0 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
2acb0 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72   in that BLOB or
2acc0 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20   string..** ^If 
2acd0 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20  the result is a 
2ace0 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2c 20 74  UTF-16 string, t
2acf0 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  hen sqlite3_colu
2ad00 6d 6e 5f 62 79 74 65 73 28 29 20 63 6f 6e 76 65  mn_bytes() conve
2ad10 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e  rts.** the strin
2ad20 67 20 74 6f 20 55 54 46 2d 38 20 61 6e 64 20 74  g to UTF-8 and t
2ad30 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20  hen returns the 
2ad40 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e  number of bytes.
2ad50 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
2ad60 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20  lt is a numeric 
2ad70 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74  value then sqlit
2ad80 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
2ad90 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74  ) uses.** [sqlit
2ada0 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74  e3_snprintf()] t
2adb0 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76  o convert that v
2adc0 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 38 20  alue to a UTF-8 
2add0 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72  string and retur
2ade0 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72  ns.** the number
2adf0 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61   of bytes in tha
2ae00 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66  t string..** ^If
2ae10 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 4e   the result is N
2ae20 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  ULL, then sqlite
2ae30 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
2ae40 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a   returns zero..*
2ae50 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73  *.** ^If the res
2ae60 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72  ult is a BLOB or
2ae70 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 74   UTF-16 string t
2ae80 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f  hen the sqlite3_
2ae90 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
2aea0 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75  .** routine retu
2aeb0 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
2aec0 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20  f bytes in that 
2aed0 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a  BLOB or string..
2aee0 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
2aef0 74 20 69 73 20 61 20 55 54 46 2d 38 20 73 74 72  t is a UTF-8 str
2af00 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  ing, then sqlite
2af10 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
2af20 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74  () converts.** t
2af30 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46  he string to UTF
2af40 2d 31 36 20 61 6e 64 20 74 68 65 6e 20 72 65 74  -16 and then ret
2af50 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
2af60 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66  of bytes..** ^If
2af70 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61   the result is a
2af80 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74   numeric value t
2af90 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  hen sqlite3_colu
2afa0 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 75 73 65  mn_bytes16() use
2afb0 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e  s.** [sqlite3_sn
2afc0 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e  printf()] to con
2afd0 76 65 72 74 20 74 68 61 74 20 76 61 6c 75 65 20  vert that value 
2afe0 74 6f 20 61 20 55 54 46 2d 31 36 20 73 74 72 69  to a UTF-16 stri
2aff0 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a  ng and returns.*
2b000 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  * the number of 
2b010 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 73 74  bytes in that st
2b020 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ring..** ^If the
2b030 20 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c   result is NULL,
2b040 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f   then sqlite3_co
2b050 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 72  lumn_bytes16() r
2b060 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a  eturns zero..**.
2b070 2a 2a 20 5e 54 68 65 20 76 61 6c 75 65 73 20 72  ** ^The values r
2b080 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69  eturned by [sqli
2b090 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2b0a0 28 29 5d 20 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c  ()] and .** [sql
2b0b0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2b0c0 73 31 36 28 29 5d 20 64 6f 20 6e 6f 74 20 69 6e  s16()] do not in
2b0d0 63 6c 75 64 65 20 74 68 65 20 7a 65 72 6f 20 74  clude the zero t
2b0e0 65 72 6d 69 6e 61 74 6f 72 73 20 61 74 20 74 68  erminators at th
2b0f0 65 20 65 6e 64 0a 2a 2a 20 6f 66 20 74 68 65 20  e end.** of the 
2b100 73 74 72 69 6e 67 2e 20 20 5e 46 6f 72 20 63 6c  string.  ^For cl
2b110 61 72 69 74 79 3a 20 74 68 65 20 76 61 6c 75 65  arity: the value
2b120 73 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a  s returned by.**
2b130 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
2b140 5f 62 79 74 65 73 28 29 5d 20 61 6e 64 20 5b 73  _bytes()] and [s
2b150 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2b160 74 65 73 31 36 28 29 5d 20 61 72 65 20 74 68 65  tes16()] are the
2b170 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 79   number of.** by
2b180 74 65 73 20 69 6e 20 74 68 65 20 73 74 72 69 6e  tes in the strin
2b190 67 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65  g, not the numbe
2b1a0 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e  r of characters.
2b1b0 0a 2a 2a 0a 2a 2a 20 5e 53 74 72 69 6e 67 73 20  .**.** ^Strings 
2b1c0 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
2b1d0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
2b1e0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f  ) and sqlite3_co
2b1f0 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 2c 0a 2a  lumn_text16(),.*
2b200 2a 20 65 76 65 6e 20 65 6d 70 74 79 20 73 74 72  * even empty str
2b210 69 6e 67 73 2c 20 61 72 65 20 61 6c 77 61 79 73  ings, are always
2b220 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
2b230 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 0a 2a  .  ^The return.*
2b240 2a 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c  * value from sql
2b250 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
2b260 28 29 20 66 6f 72 20 61 20 7a 65 72 6f 2d 6c 65  () for a zero-le
2b270 6e 67 74 68 20 42 4c 4f 42 20 69 73 20 61 20 4e  ngth BLOB is a N
2b280 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ULL pointer..**.
2b290 2a 2a 20 5e 54 68 65 20 6f 62 6a 65 63 74 20 72  ** ^The object r
2b2a0 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69  eturned by [sqli
2b2b0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65  te3_column_value
2b2c0 28 29 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e  ()] is an.** [un
2b2d0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
2b2e0 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e  3_value] object.
2b2f0 20 20 41 6e 20 75 6e 70 72 6f 74 65 63 74 65 64    An unprotected
2b300 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
2b310 62 6a 65 63 74 0a 2a 2a 20 6d 61 79 20 6f 6e 6c  bject.** may onl
2b320 79 20 62 65 20 75 73 65 64 20 77 69 74 68 20 5b  y be used with [
2b330 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c  sqlite3_bind_val
2b340 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  ue()] and [sqlit
2b350 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28  e3_result_value(
2b360 29 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b 75  )]..** If the [u
2b370 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
2b380 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
2b390 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20   returned by.** 
2b3a0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
2b3b0 76 61 6c 75 65 28 29 5d 20 69 73 20 75 73 65 64  value()] is used
2b3c0 20 69 6e 20 61 6e 79 20 6f 74 68 65 72 20 77 61   in any other wa
2b3d0 79 2c 20 69 6e 63 6c 75 64 69 6e 67 20 63 61 6c  y, including cal
2b3e0 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75 74 69 6e 65  ls.** to routine
2b3f0 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f  s like [sqlite3_
2b400 76 61 6c 75 65 5f 69 6e 74 28 29 5d 2c 20 5b 73  value_int()], [s
2b410 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
2b420 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c  t()],.** or [sql
2b430 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73  ite3_value_bytes
2b440 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 62 65  ()], then the be
2b450 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69  havior is undefi
2b460 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ned..**.** These
2b470 20 72 6f 75 74 69 6e 65 73 20 61 74 74 65 6d 70   routines attemp
2b480 74 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65  t to convert the
2b490 20 76 61 6c 75 65 20 77 68 65 72 65 20 61 70 70   value where app
2b4a0 72 6f 70 72 69 61 74 65 2e 20 20 5e 46 6f 72 0a  ropriate.  ^For.
2b4b0 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 74  ** example, if t
2b4c0 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72  he internal repr
2b4d0 65 73 65 6e 74 61 74 69 6f 6e 20 69 73 20 46 4c  esentation is FL
2b4e0 4f 41 54 20 61 6e 64 20 61 20 74 65 78 74 20 72  OAT and a text r
2b4f0 65 73 75 6c 74 0a 2a 2a 20 69 73 20 72 65 71 75  esult.** is requ
2b500 65 73 74 65 64 2c 20 5b 73 71 6c 69 74 65 33 5f  ested, [sqlite3_
2b510 73 6e 70 72 69 6e 74 66 28 29 5d 20 69 73 20 75  snprintf()] is u
2b520 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74  sed internally t
2b530 6f 20 70 65 72 66 6f 72 6d 20 74 68 65 0a 2a 2a  o perform the.**
2b540 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 75 74 6f   conversion auto
2b550 6d 61 74 69 63 61 6c 6c 79 2e 20 20 5e 28 54 68  matically.  ^(Th
2b560 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 61 62 6c  e following tabl
2b570 65 20 64 65 74 61 69 6c 73 20 74 68 65 20 63 6f  e details the co
2b580 6e 76 65 72 73 69 6f 6e 73 0a 2a 2a 20 74 68 61  nversions.** tha
2b590 74 20 61 72 65 20 61 70 70 6c 69 65 64 3a 0a 2a  t are applied:.*
2b5a0 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
2b5b0 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64  >.** <table bord
2b5c0 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c  er="1">.** <tr><
2b5d0 74 68 3e 20 49 6e 74 65 72 6e 61 6c 3c 62 72 3e  th> Internal<br>
2b5e0 54 79 70 65 20 3c 74 68 3e 20 52 65 71 75 65 73  Type <th> Reques
2b5f0 74 65 64 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e  ted<br>Type <th>
2b600 20 20 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a    Conversion.**.
2b610 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c  ** <tr><td>  NUL
2b620 4c 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45  L    <td> INTEGE
2b630 52 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20  R   <td> Result 
2b640 69 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  is 0.** <tr><td>
2b650 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20    NULL    <td>  
2b660 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 52 65  FLOAT    <td> Re
2b670 73 75 6c 74 20 69 73 20 30 2e 30 0a 2a 2a 20 3c  sult is 0.0.** <
2b680 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20  tr><td>  NULL   
2b690 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20   <td>   TEXT    
2b6a0 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 4e  <td> Result is N
2b6b0 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c  ULL pointer.** <
2b6c0 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20  tr><td>  NULL   
2b6d0 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20   <td>   BLOB    
2b6e0 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 4e  <td> Result is N
2b6f0 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c  ULL pointer.** <
2b700 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20  tr><td> INTEGER 
2b710 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20   <td>  FLOAT    
2b720 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f  <td> Convert fro
2b730 6d 20 69 6e 74 65 67 65 72 20 74 6f 20 66 6c 6f  m integer to flo
2b740 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49  at.** <tr><td> I
2b750 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20 54  NTEGER  <td>   T
2b760 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49  EXT    <td> ASCI
2b770 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74  I rendering of t
2b780 68 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74  he integer.** <t
2b790 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20  r><td> INTEGER  
2b7a0 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c  <td>   BLOB    <
2b7b0 74 64 3e 20 53 61 6d 65 20 61 73 20 49 4e 54 45  td> Same as INTE
2b7c0 47 45 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72  GER->TEXT.** <tr
2b7d0 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c  ><td>  FLOAT   <
2b7e0 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74  td> INTEGER   <t
2b7f0 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20  d> Convert from 
2b800 66 6c 6f 61 74 20 74 6f 20 69 6e 74 65 67 65 72  float to integer
2b810 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c  .** <tr><td>  FL
2b820 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 54 45 58  OAT   <td>   TEX
2b830 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20  T    <td> ASCII 
2b840 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65  rendering of the
2b850 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74   float.** <tr><t
2b860 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e  d>  FLOAT   <td>
2b870 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20     BLOB    <td> 
2b880 53 61 6d 65 20 61 73 20 46 4c 4f 41 54 2d 3e 54  Same as FLOAT->T
2b890 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  EXT.** <tr><td> 
2b8a0 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 49 4e   TEXT    <td> IN
2b8b0 54 45 47 45 52 20 20 20 3c 74 64 3e 20 55 73 65  TEGER   <td> Use
2b8c0 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c   atoi().** <tr><
2b8d0 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64  td>  TEXT    <td
2b8e0 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e  >  FLOAT    <td>
2b8f0 20 55 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c   Use atof().** <
2b900 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20  tr><td>  TEXT   
2b910 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20   <td>   BLOB    
2b920 3c 74 64 3e 20 4e 6f 20 63 68 61 6e 67 65 0a 2a  <td> No change.*
2b930 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42  * <tr><td>  BLOB
2b940 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52      <td> INTEGER
2b950 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20     <td> Convert 
2b960 74 6f 20 54 45 58 54 20 74 68 65 6e 20 75 73 65  to TEXT then use
2b970 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c   atoi().** <tr><
2b980 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  td>  BLOB    <td
2b990 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e  >  FLOAT    <td>
2b9a0 20 43 6f 6e 76 65 72 74 20 74 6f 20 54 45 58 54   Convert to TEXT
2b9b0 20 74 68 65 6e 20 75 73 65 20 61 74 6f 66 28 29   then use atof()
2b9c0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c  .** <tr><td>  BL
2b9d0 4f 42 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58  OB    <td>   TEX
2b9e0 54 20 20 20 20 3c 74 64 3e 20 41 64 64 20 61 20  T    <td> Add a 
2b9f0 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20  zero terminator 
2ba00 69 66 20 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f 74  if needed.** </t
2ba10 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b  able>.** </block
2ba20 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54  quote>)^.**.** T
2ba30 68 65 20 74 61 62 6c 65 20 61 62 6f 76 65 20 6d  he table above m
2ba40 61 6b 65 73 20 72 65 66 65 72 65 6e 63 65 20 74  akes reference t
2ba50 6f 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62  o standard C lib
2ba60 72 61 72 79 20 66 75 6e 63 74 69 6f 6e 73 20 61  rary functions a
2ba70 74 6f 69 28 29 0a 2a 2a 20 61 6e 64 20 61 74 6f  toi().** and ato
2ba80 66 28 29 2e 20 20 53 51 4c 69 74 65 20 64 6f 65  f().  SQLite doe
2ba90 73 20 6e 6f 74 20 72 65 61 6c 6c 79 20 75 73 65  s not really use
2baa0 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   these functions
2bab0 2e 20 20 49 74 20 68 61 73 20 69 74 73 0a 2a 2a  .  It has its.**
2bac0 20 6f 77 6e 20 65 71 75 69 76 61 6c 65 6e 74 20   own equivalent 
2bad0 69 6e 74 65 72 6e 61 6c 20 72 6f 75 74 69 6e 65  internal routine
2bae0 73 2e 20 20 54 68 65 20 61 74 6f 69 28 29 20 61  s.  The atoi() a
2baf0 6e 64 20 61 74 6f 66 28 29 20 6e 61 6d 65 73 20  nd atof() names 
2bb00 61 72 65 0a 2a 2a 20 75 73 65 64 20 69 6e 20 74  are.** used in t
2bb10 68 65 20 74 61 62 6c 65 20 66 6f 72 20 62 72 65  he table for bre
2bb20 76 69 74 79 20 61 6e 64 20 62 65 63 61 75 73 65  vity and because
2bb30 20 74 68 65 79 20 61 72 65 20 66 61 6d 69 6c 69   they are famili
2bb40 61 72 20 74 6f 20 6d 6f 73 74 0a 2a 2a 20 43 20  ar to most.** C 
2bb50 70 72 6f 67 72 61 6d 6d 65 72 73 2e 0a 2a 2a 0a  programmers..**.
2bb60 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 77 68 65  ** Note that whe
2bb70 6e 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f  n type conversio
2bb80 6e 73 20 6f 63 63 75 72 2c 20 70 6f 69 6e 74 65  ns occur, pointe
2bb90 72 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 70  rs returned by p
2bba0 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f  rior.** calls to
2bbb0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2bbc0 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f  blob(), sqlite3_
2bbd0 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20 61  column_text(), a
2bbe0 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  nd/or.** sqlite3
2bbf0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
2bc00 20 6d 61 79 20 62 65 20 69 6e 76 61 6c 69 64 61   may be invalida
2bc10 74 65 64 2e 0a 2a 2a 20 54 79 70 65 20 63 6f 6e  ted..** Type con
2bc20 76 65 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f 69  versions and poi
2bc30 6e 74 65 72 20 69 6e 76 61 6c 69 64 61 74 69 6f  nter invalidatio
2bc40 6e 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a  ns might occur.*
2bc50 2a 20 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69  * in the followi
2bc60 6e 67 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20  ng cases:.**.** 
2bc70 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  <ul>.** <li> The
2bc80 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74   initial content
2bc90 20 69 73 20 61 20 42 4c 4f 42 20 61 6e 64 20 73   is a BLOB and s
2bca0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2bcb0 78 74 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20  xt() or.**      
2bcc0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2bcd0 65 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65  ext16() is calle
2bce0 64 2e 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d 69  d.  A zero-termi
2bcf0 6e 61 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20 20  nator might.**  
2bd00 20 20 20 20 6e 65 65 64 20 74 6f 20 62 65 20 61      need to be a
2bd10 64 64 65 64 20 74 6f 20 74 68 65 20 73 74 72 69  dded to the stri
2bd20 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e  ng.</li>.** <li>
2bd30 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e   The initial con
2bd40 74 65 6e 74 20 69 73 20 55 54 46 2d 38 20 74 65  tent is UTF-8 te
2bd50 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  xt and sqlite3_c
2bd60 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20  olumn_bytes16() 
2bd70 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74  or.**      sqlit
2bd80 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
2bd90 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54  () is called.  T
2bda0 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20  he content must 
2bdb0 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20  be converted.** 
2bdc0 20 20 20 20 20 74 6f 20 55 54 46 2d 31 36 2e 3c       to UTF-16.<
2bdd0 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  /li>.** <li> The
2bde0 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74   initial content
2bdf0 20 69 73 20 55 54 46 2d 31 36 20 74 65 78 74 20   is UTF-16 text 
2be00 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  and sqlite3_colu
2be10 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a  mn_bytes() or.**
2be20 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f        sqlite3_co
2be30 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69 73 20 63  lumn_text() is c
2be40 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74  alled.  The cont
2be50 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76  ent must be conv
2be60 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f  erted.**      to
2be70 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20   UTF-8.</li>.** 
2be80 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e  </ul>.**.** ^Con
2be90 76 65 72 73 69 6f 6e 73 20 62 65 74 77 65 65 6e  versions between
2bea0 20 55 54 46 2d 31 36 62 65 20 61 6e 64 20 55 54   UTF-16be and UT
2beb0 46 2d 31 36 6c 65 20 61 72 65 20 61 6c 77 61 79  F-16le are alway
2bec0 73 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20  s done in place 
2bed0 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e  and do.** not in
2bee0 76 61 6c 69 64 61 74 65 20 61 20 70 72 69 6f 72  validate a prior
2bef0 20 70 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67 68   pointer, though
2bf00 20 6f 66 20 63 6f 75 72 73 65 20 74 68 65 20 63   of course the c
2bf10 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 62 75  ontent of the bu
2bf20 66 66 65 72 0a 2a 2a 20 74 68 61 74 20 74 68 65  ffer.** that the
2bf30 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 20 72   prior pointer r
2bf40 65 66 65 72 65 6e 63 65 73 20 77 69 6c 6c 20 68  eferences will h
2bf50 61 76 65 20 62 65 65 6e 20 6d 6f 64 69 66 69 65  ave been modifie
2bf60 64 2e 20 20 4f 74 68 65 72 20 6b 69 6e 64 73 0a  d.  Other kinds.
2bf70 2a 2a 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e  ** of conversion
2bf80 20 61 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c 61   are done in pla
2bf90 63 65 20 77 68 65 6e 20 69 74 20 69 73 20 70 6f  ce when it is po
2bfa0 73 73 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d 65  ssible, but some
2bfb0 74 69 6d 65 73 20 74 68 65 79 0a 2a 2a 20 61 72  times they.** ar
2bfc0 65 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 61  e not possible a
2bfd0 6e 64 20 69 6e 20 74 68 6f 73 65 20 63 61 73 65  nd in those case
2bfe0 73 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 73  s prior pointers
2bff0 20 61 72 65 20 69 6e 76 61 6c 69 64 61 74 65 64   are invalidated
2c000 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 61 66 65  ..**.** The safe
2c010 73 74 20 61 6e 64 20 65 61 73 69 65 73 74 20 74  st and easiest t
2c020 6f 20 72 65 6d 65 6d 62 65 72 20 70 6f 6c 69 63  o remember polic
2c030 79 20 69 73 20 74 6f 20 69 6e 76 6f 6b 65 20 74  y is to invoke t
2c040 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a  hese routines.**
2c050 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 66   in one of the f
2c060 6f 6c 6c 6f 77 69 6e 67 20 77 61 79 73 3a 0a 2a  ollowing ways:.*
2c070 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c  *.** <ul>.**  <l
2c080 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  i>sqlite3_column
2c090 5f 74 65 78 74 28 29 20 66 6f 6c 6c 6f 77 65 64  _text() followed
2c0a0 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
2c0b0 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a  mn_bytes()</li>.
2c0c0 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f  **  <li>sqlite3_
2c0d0 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f  column_blob() fo
2c0e0 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65  llowed by sqlite
2c0f0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
2c100 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71  </li>.**  <li>sq
2c110 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
2c120 74 31 36 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62  t16() followed b
2c130 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
2c140 5f 62 79 74 65 73 31 36 28 29 3c 2f 6c 69 3e 0a  _bytes16()</li>.
2c150 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49  ** </ul>.**.** I
2c160 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 79  n other words, y
2c170 6f 75 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20 73  ou should call s
2c180 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2c190 78 74 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33  xt(),.** sqlite3
2c1a0 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20  _column_blob(), 
2c1b0 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  or sqlite3_colum
2c1c0 6e 5f 74 65 78 74 31 36 28 29 20 66 69 72 73 74  n_text16() first
2c1d0 20 74 6f 20 66 6f 72 63 65 20 74 68 65 20 72 65   to force the re
2c1e0 73 75 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74 68 65  sult.** into the
2c1f0 20 64 65 73 69 72 65 64 20 66 6f 72 6d 61 74 2c   desired format,
2c200 20 74 68 65 6e 20 69 6e 76 6f 6b 65 20 73 71 6c   then invoke sql
2c210 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2c220 73 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  s() or.** sqlite
2c230 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
2c240 28 29 20 74 6f 20 66 69 6e 64 20 74 68 65 20 73  () to find the s
2c250 69 7a 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c  ize of the resul
2c260 74 2e 20 20 44 6f 20 6e 6f 74 20 6d 69 78 20 63  t.  Do not mix c
2c270 61 6c 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c 69 74  alls.** to sqlit
2c280 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
2c290 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   or sqlite3_colu
2c2a0 6d 6e 5f 62 6c 6f 62 28 29 20 77 69 74 68 20 63  mn_blob() with c
2c2b0 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  alls to.** sqlit
2c2c0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
2c2d0 36 28 29 2c 20 61 6e 64 20 64 6f 20 6e 6f 74 20  6(), and do not 
2c2e0 6d 69 78 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  mix calls to sql
2c2f0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2c300 31 36 28 29 0a 2a 2a 20 77 69 74 68 20 63 61 6c  16().** with cal
2c310 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ls to sqlite3_co
2c320 6c 75 6d 6e 5f 62 79 74 65 73 28 29 2e 0a 2a 2a  lumn_bytes()..**
2c330 0a 2a 2a 20 5e 54 68 65 20 70 6f 69 6e 74 65 72  .** ^The pointer
2c340 73 20 72 65 74 75 72 6e 65 64 20 61 72 65 20 76  s returned are v
2c350 61 6c 69 64 20 75 6e 74 69 6c 20 61 20 74 79 70  alid until a typ
2c360 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63  e conversion occ
2c370 75 72 73 20 61 73 0a 2a 2a 20 64 65 73 63 72 69  urs as.** descri
2c380 62 65 64 20 61 62 6f 76 65 2c 20 6f 72 20 75 6e  bed above, or un
2c390 74 69 6c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  til [sqlite3_ste
2c3a0 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  p()] or [sqlite3
2c3b0 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20  _reset()] or.** 
2c3c0 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
2c3d0 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e 20  e()] is called. 
2c3e0 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 73 70 61   ^The memory spa
2c3f0 63 65 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20  ce used to hold 
2c400 73 74 72 69 6e 67 73 0a 2a 2a 20 61 6e 64 20 42  strings.** and B
2c410 4c 4f 42 73 20 69 73 20 66 72 65 65 64 20 61 75  LOBs is freed au
2c420 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 44 6f  tomatically.  Do
2c430 20 3c 62 3e 6e 6f 74 3c 2f 62 3e 20 70 61 73 73   <b>not</b> pass
2c440 20 74 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65   the pointers re
2c450 74 75 72 6e 65 64 0a 2a 2a 20 5b 73 71 6c 69 74  turned.** [sqlit
2c460 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
2c470 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ], [sqlite3_colu
2c480 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 65 74 63 2e  mn_text()], etc.
2c490 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65   into.** [sqlite
2c4a0 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a  3_free()]..**.**
2c4b0 20 5e 28 49 66 20 61 20 6d 65 6d 6f 72 79 20 61   ^(If a memory a
2c4c0 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 20  llocation error 
2c4d0 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20 74 68  occurs during th
2c4e0 65 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20  e evaluation of 
2c4f0 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20  any.** of these 
2c500 72 6f 75 74 69 6e 65 73 2c 20 61 20 64 65 66 61  routines, a defa
2c510 75 6c 74 20 76 61 6c 75 65 20 69 73 20 72 65 74  ult value is ret
2c520 75 72 6e 65 64 2e 20 20 54 68 65 20 64 65 66 61  urned.  The defa
2c530 75 6c 74 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20  ult value.** is 
2c540 65 69 74 68 65 72 20 74 68 65 20 69 6e 74 65 67  either the integ
2c550 65 72 20 30 2c 20 74 68 65 20 66 6c 6f 61 74 69  er 0, the floati
2c560 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 20  ng point number 
2c570 30 2e 30 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a  0.0, or a NULL.*
2c580 2a 20 70 6f 69 6e 74 65 72 2e 20 20 53 75 62 73  * pointer.  Subs
2c590 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20  equent calls to 
2c5a0 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65  [sqlite3_errcode
2c5b0 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a  ()] will return.
2c5c0 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  ** [SQLITE_NOMEM
2c5d0 5d 2e 29 5e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f  ].)^.*/.const vo
2c5e0 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
2c5f0 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f  mn_blob(sqlite3_
2c600 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
2c610 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  ;.int sqlite3_co
2c620 6c 75 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69 74  lumn_bytes(sqlit
2c630 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
2c640 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ol);.int sqlite3
2c650 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
2c660 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2c670 6e 74 20 69 43 6f 6c 29 3b 0a 64 6f 75 62 6c 65  nt iCol);.double
2c680 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2c690 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73  double(sqlite3_s
2c6a0 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
2c6b0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c  .int sqlite3_col
2c6c0 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f  umn_int(sqlite3_
2c6d0 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
2c6e0 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  ;.sqlite3_int64 
2c6f0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69  sqlite3_column_i
2c700 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d  nt64(sqlite3_stm
2c710 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63  t*, int iCol);.c
2c720 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68  onst unsigned ch
2c730 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ar *sqlite3_colu
2c740 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f  mn_text(sqlite3_
2c750 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
2c760 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
2c770 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
2c780 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  t16(sqlite3_stmt
2c790 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e  *, int iCol);.in
2c7a0 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  t sqlite3_column
2c7b0 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74  _type(sqlite3_st
2c7c0 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
2c7d0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 73  sqlite3_value *s
2c7e0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61  qlite3_column_va
2c7f0 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  lue(sqlite3_stmt
2c800 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f  *, int iCol);../
2c810 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
2c820 65 73 74 72 6f 79 20 41 20 50 72 65 70 61 72 65  estroy A Prepare
2c830 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65  d Statement Obje
2c840 63 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ct.**.** ^The sq
2c850 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
2c860 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c   function is cal
2c870 6c 65 64 20 74 6f 20 64 65 6c 65 74 65 20 61 20  led to delete a 
2c880 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2c890 65 6e 74 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ent]..** ^If the
2c8a0 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 76 61   most recent eva
2c8b0 6c 75 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73  luation of the s
2c8c0 74 61 74 65 6d 65 6e 74 20 65 6e 63 6f 75 6e 74  tatement encount
2c8d0 65 72 65 64 20 6e 6f 20 65 72 72 6f 72 73 0a 2a  ered no errors.*
2c8e0 2a 20 6f 72 20 69 66 20 74 68 65 20 73 74 61 74  * or if the stat
2c8f0 65 6d 65 6e 74 20 69 73 20 6e 65 76 65 72 20 62  ement is never b
2c900 65 65 6e 20 65 76 61 6c 75 61 74 65 64 2c 20 74  een evaluated, t
2c910 68 65 6e 20 73 71 6c 69 74 65 33 5f 66 69 6e 61  hen sqlite3_fina
2c920 6c 69 7a 65 28 29 20 72 65 74 75 72 6e 73 0a 2a  lize() returns.*
2c930 2a 20 53 51 4c 49 54 45 5f 4f 4b 2e 20 20 5e 49  * SQLITE_OK.  ^I
2c940 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  f the most recen
2c950 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20  t evaluation of 
2c960 73 74 61 74 65 6d 65 6e 74 20 53 20 66 61 69 6c  statement S fail
2c970 65 64 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69  ed, then.** sqli
2c980 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20  te3_finalize(S) 
2c990 72 65 74 75 72 6e 73 20 74 68 65 20 61 70 70 72  returns the appr
2c9a0 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63  opriate [error c
2c9b0 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65  ode] or.** [exte
2c9c0 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d  nded error code]
2c9d0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
2c9e0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29  ite3_finalize(S)
2c9f0 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20   routine can be 
2ca00 63 61 6c 6c 65 64 20 61 74 20 61 6e 79 20 70 6f  called at any po
2ca10 69 6e 74 20 64 75 72 69 6e 67 0a 2a 2a 20 74 68  int during.** th
2ca20 65 20 6c 69 66 65 20 63 79 63 6c 65 20 6f 66 20  e life cycle of 
2ca30 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2ca40 65 6e 74 5d 20 53 3a 0a 2a 2a 20 62 65 66 6f 72  ent] S:.** befor
2ca50 65 20 73 74 61 74 65 6d 65 6e 74 20 53 20 69 73  e statement S is
2ca60 20 65 76 65 72 20 65 76 61 6c 75 61 74 65 64 2c   ever evaluated,
2ca70 20 61 66 74 65 72 0a 2a 2a 20 6f 6e 65 20 6f 72   after.** one or
2ca80 20 6d 6f 72 65 20 63 61 6c 6c 73 20 74 6f 20 5b   more calls to [
2ca90 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
2caa0 2c 20 6f 72 20 61 66 74 65 72 20 61 6e 79 20 63  , or after any c
2cab0 61 6c 6c 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74  all.** to [sqlit
2cac0 65 33 5f 73 74 65 70 28 29 5d 20 72 65 67 61 72  e3_step()] regar
2cad0 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72  dless of whether
2cae0 20 6f 72 20 6e 6f 74 20 74 68 65 20 73 74 61 74   or not the stat
2caf0 65 6d 65 6e 74 20 68 61 73 0a 2a 2a 20 63 6f 6d  ement has.** com
2cb00 70 6c 65 74 65 64 20 65 78 65 63 75 74 69 6f 6e  pleted execution
2cb10 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 76 6f 6b 69 6e  ..**.** ^Invokin
2cb20 67 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69  g sqlite3_finali
2cb30 7a 65 28 29 20 6f 6e 20 61 20 4e 55 4c 4c 20 70  ze() on a NULL p
2cb40 6f 69 6e 74 65 72 20 69 73 20 61 20 68 61 72 6d  ointer is a harm
2cb50 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a  less no-op..**.*
2cb60 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
2cb70 6e 20 6d 75 73 74 20 66 69 6e 61 6c 69 7a 65 20  n must finalize 
2cb80 65 76 65 72 79 20 5b 70 72 65 70 61 72 65 64 20  every [prepared 
2cb90 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 6f 72  statement] in or
2cba0 64 65 72 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20  der to avoid.** 
2cbb0 72 65 73 6f 75 72 63 65 20 6c 65 61 6b 73 2e 20  resource leaks. 
2cbc0 20 49 74 20 69 73 20 61 20 67 72 69 65 76 6f 75   It is a grievou
2cbd0 73 20 65 72 72 6f 72 20 66 6f 72 20 74 68 65 20  s error for the 
2cbe0 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 74  application to t
2cbf0 72 79 20 74 6f 20 75 73 65 0a 2a 2a 20 61 20 70  ry to use.** a p
2cc00 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2cc10 74 20 61 66 74 65 72 20 69 74 20 68 61 73 20 62  t after it has b
2cc20 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2e 20 20  een finalized.  
2cc30 41 6e 79 20 75 73 65 20 6f 66 20 61 20 70 72 65  Any use of a pre
2cc40 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65  pared.** stateme
2cc50 6e 74 20 61 66 74 65 72 20 69 74 20 68 61 73 20  nt after it has 
2cc60 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 20 63  been finalized c
2cc70 61 6e 20 72 65 73 75 6c 74 20 69 6e 20 75 6e 64  an result in und
2cc80 65 66 69 6e 65 64 20 61 6e 64 0a 2a 2a 20 75 6e  efined and.** un
2cc90 64 65 73 69 72 61 62 6c 65 20 62 65 68 61 76 69  desirable behavi
2cca0 6f 72 20 73 75 63 68 20 61 73 20 73 65 67 66 61  or such as segfa
2ccb0 75 6c 74 73 20 61 6e 64 20 68 65 61 70 20 63 6f  ults and heap co
2ccc0 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 69 6e 74  rruption..*/.int
2ccd0 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a   sqlite3_finaliz
2cce0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  e(sqlite3_stmt *
2ccf0 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
2cd00 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 41  API3REF: Reset A
2cd10 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d   Prepared Statem
2cd20 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a  ent Object.**.**
2cd30 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   The sqlite3_res
2cd40 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73  et() function is
2cd50 20 63 61 6c 6c 65 64 20 74 6f 20 72 65 73 65 74   called to reset
2cd60 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
2cd70 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63  tement].** objec
2cd80 74 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e  t back to its in
2cd90 69 74 69 61 6c 20 73 74 61 74 65 2c 20 72 65 61  itial state, rea
2cda0 64 79 20 74 6f 20 62 65 20 72 65 2d 65 78 65 63  dy to be re-exec
2cdb0 75 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20 53 51  uted..** ^Any SQ
2cdc0 4c 20 73 74 61 74 65 6d 65 6e 74 20 76 61 72 69  L statement vari
2cdd0 61 62 6c 65 73 20 74 68 61 74 20 68 61 64 20 76  ables that had v
2cde0 61 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f 20 74  alues bound to t
2cdf0 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65  hem using.** the
2ce00 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
2ce10 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 69  lob | sqlite3_bi
2ce20 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72 65 74 61  nd_*() API] reta
2ce30 69 6e 20 74 68 65 69 72 20 76 61 6c 75 65 73 2e  in their values.
2ce40 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69 74 65 33  .** Use [sqlite3
2ce50 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28  _clear_bindings(
2ce60 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65 20  )] to reset the 
2ce70 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20  bindings..**.** 
2ce80 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65  ^The [sqlite3_re
2ce90 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63  set(S)] interfac
2cea0 65 20 72 65 73 65 74 73 20 74 68 65 20 5b 70 72  e resets the [pr
2ceb0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2cec0 5d 20 53 0a 2a 2a 20 62 61 63 6b 20 74 6f 20 74  ] S.** back to t
2ced0 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20  he beginning of 
2cee0 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a  its program..**.
2cef0 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20  ** ^If the most 
2cf00 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b  recent call to [
2cf10 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d  sqlite3_step(S)]
2cf20 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65   for the.** [pre
2cf30 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2cf40 20 53 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c   S returned [SQL
2cf50 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b 53 51 4c  ITE_ROW] or [SQL
2cf60 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f 72  ITE_DONE],.** or
2cf70 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   if [sqlite3_ste
2cf80 70 28 53 29 5d 20 68 61 73 20 6e 65 76 65 72 20  p(S)] has never 
2cf90 62 65 66 6f 72 65 20 62 65 65 6e 20 63 61 6c 6c  before been call
2cfa0 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20 74 68 65 6e  ed on S,.** then
2cfb0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2cfc0 53 29 5d 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  S)] returns [SQL
2cfd0 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  ITE_OK]..**.** ^
2cfe0 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  If the most rece
2cff0 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  nt call to [sqli
2d000 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72  te3_step(S)] for
2d010 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
2d020 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69  d statement] S i
2d030 6e 64 69 63 61 74 65 64 20 61 6e 20 65 72 72 6f  ndicated an erro
2d040 72 2c 20 74 68 65 6e 0a 2a 2a 20 5b 73 71 6c 69  r, then.** [sqli
2d050 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65  te3_reset(S)] re
2d060 74 75 72 6e 73 20 61 6e 20 61 70 70 72 6f 70 72  turns an appropr
2d070 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65  iate [error code
2d080 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73  ]..**.** ^The [s
2d090 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d  qlite3_reset(S)]
2d0a0 20 69 6e 74 65 72 66 61 63 65 20 64 6f 65 73 20   interface does 
2d0b0 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 76  not change the v
2d0c0 61 6c 75 65 73 0a 2a 2a 20 6f 66 20 61 6e 79 20  alues.** of any 
2d0d0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
2d0e0 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20  ob|bindings] on 
2d0f0 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
2d100 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 69  atement] S..*/.i
2d110 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74  nt sqlite3_reset
2d120 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
2d130 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
2d140 50 49 33 52 45 46 3a 20 43 72 65 61 74 65 20 4f  PI3REF: Create O
2d150 72 20 52 65 64 65 66 69 6e 65 20 53 51 4c 20 46  r Redefine SQL F
2d160 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57  unctions.** KEYW
2d170 4f 52 44 53 3a 20 7b 66 75 6e 63 74 69 6f 6e 20  ORDS: {function 
2d180 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  creation routine
2d190 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  s}.** KEYWORDS: 
2d1a0 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66  {application-def
2d1b0 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
2d1c0 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  n}.** KEYWORDS: 
2d1d0 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66  {application-def
2d1e0 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
2d1f0 6e 73 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  ns}.**.** ^These
2d200 20 66 75 6e 63 74 69 6f 6e 73 20 28 63 6f 6c 6c   functions (coll
2d210 65 63 74 69 76 65 6c 79 20 6b 6e 6f 77 6e 20 61  ectively known a
2d220 73 20 22 66 75 6e 63 74 69 6f 6e 20 63 72 65 61  s "function crea
2d230 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 22 29 0a  tion routines").
2d240 2a 2a 20 61 72 65 20 75 73 65 64 20 74 6f 20 61  ** are used to a
2d250 64 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  dd SQL functions
2d260 20 6f 72 20 61 67 67 72 65 67 61 74 65 73 20 6f   or aggregates o
2d270 72 20 74 6f 20 72 65 64 65 66 69 6e 65 20 74 68  r to redefine th
2d280 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66  e behavior.** of
2d290 20 65 78 69 73 74 69 6e 67 20 53 51 4c 20 66 75   existing SQL fu
2d2a0 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65  nctions or aggre
2d2b0 67 61 74 65 73 2e 20 20 54 68 65 20 6f 6e 6c 79  gates.  The only
2d2c0 20 64 69 66 66 65 72 65 6e 63 65 73 20 62 65 74   differences bet
2d2d0 77 65 65 6e 0a 2a 2a 20 74 68 65 73 65 20 72 6f  ween.** these ro
2d2e0 75 74 69 6e 65 73 20 61 72 65 20 74 68 65 20 74  utines are the t
2d2f0 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 65 78 70  ext encoding exp
2d300 65 63 74 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65  ected for.** the
2d310 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
2d320 72 20 28 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  r (the name of t
2d330 68 65 20 66 75 6e 63 74 69 6f 6e 20 62 65 69 6e  he function bein
2d340 67 20 63 72 65 61 74 65 64 29 0a 2a 2a 20 61 6e  g created).** an
2d350 64 20 74 68 65 20 70 72 65 73 65 6e 63 65 20 6f  d the presence o
2d360 72 20 61 62 73 65 6e 63 65 20 6f 66 20 61 20 64  r absence of a d
2d370 65 73 74 72 75 63 74 6f 72 20 63 61 6c 6c 62 61  estructor callba
2d380 63 6b 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61 70  ck for.** the ap
2d390 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70  plication data p
2d3a0 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ointer..**.** ^T
2d3b0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
2d3c0 65 72 20 69 73 20 74 68 65 20 5b 64 61 74 61 62  er is the [datab
2d3d0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
2d3e0 74 6f 20 77 68 69 63 68 20 74 68 65 20 53 51 4c  to which the SQL
2d3f0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  .** function is 
2d400 74 6f 20 62 65 20 61 64 64 65 64 2e 20 20 5e 49  to be added.  ^I
2d410 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  f an application
2d420 20 75 73 65 73 20 6d 6f 72 65 20 74 68 61 6e 20   uses more than 
2d430 6f 6e 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  one database.** 
2d440 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 65 6e 20  connection then 
2d450 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
2d460 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
2d470 73 20 6d 75 73 74 20 62 65 20 61 64 64 65 64 0a  s must be added.
2d480 2a 2a 20 74 6f 20 65 61 63 68 20 64 61 74 61 62  ** to each datab
2d490 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73  ase connection s
2d4a0 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a  eparately..**.**
2d4b0 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72   ^The second par
2d4c0 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e 61  ameter is the na
2d4d0 6d 65 20 6f 66 20 74 68 65 20 53 51 4c 20 66 75  me of the SQL fu
2d4e0 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 63 72 65  nction to be cre
2d4f0 61 74 65 64 20 6f 72 0a 2a 2a 20 72 65 64 65 66  ated or.** redef
2d500 69 6e 65 64 2e 20 20 5e 54 68 65 20 6c 65 6e 67  ined.  ^The leng
2d510 74 68 20 6f 66 20 74 68 65 20 6e 61 6d 65 20 69  th of the name i
2d520 73 20 6c 69 6d 69 74 65 64 20 74 6f 20 32 35 35  s limited to 255
2d530 20 62 79 74 65 73 20 69 6e 20 61 20 55 54 46 2d   bytes in a UTF-
2d540 38 0a 2a 2a 20 72 65 70 72 65 73 65 6e 74 61 74  8.** representat
2d550 69 6f 6e 2c 20 65 78 63 6c 75 73 69 76 65 20 6f  ion, exclusive o
2d560 66 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69  f the zero-termi
2d570 6e 61 74 6f 72 2e 20 20 5e 4e 6f 74 65 20 74 68  nator.  ^Note th
2d580 61 74 20 74 68 65 20 6e 61 6d 65 0a 2a 2a 20 6c  at the name.** l
2d590 65 6e 67 74 68 20 6c 69 6d 69 74 20 69 73 20 69  ength limit is i
2d5a0 6e 20 55 54 46 2d 38 20 62 79 74 65 73 2c 20 6e  n UTF-8 bytes, n
2d5b0 6f 74 20 63 68 61 72 61 63 74 65 72 73 20 6e 6f  ot characters no
2d5c0 72 20 55 54 46 2d 31 36 20 62 79 74 65 73 2e 20  r UTF-16 bytes. 
2d5d0 20 0a 2a 2a 20 5e 41 6e 79 20 61 74 74 65 6d 70   .** ^Any attemp
2d5e0 74 20 74 6f 20 63 72 65 61 74 65 20 61 20 66 75  t to create a fu
2d5f0 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 6c 6f  nction with a lo
2d600 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c  nger name.** wil
2d610 6c 20 72 65 73 75 6c 74 20 69 6e 20 5b 53 51 4c  l result in [SQL
2d620 49 54 45 5f 4d 49 53 55 53 45 5d 20 62 65 69 6e  ITE_MISUSE] bein
2d630 67 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  g returned..**.*
2d640 2a 20 5e 54 68 65 20 74 68 69 72 64 20 70 61 72  * ^The third par
2d650 61 6d 65 74 65 72 20 28 6e 41 72 67 29 0a 2a 2a  ameter (nArg).**
2d660 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   is the number o
2d670 66 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74  f arguments that
2d680 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
2d690 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74  n or.** aggregat
2d6a0 65 20 74 61 6b 65 73 2e 20 5e 49 66 20 74 68 69  e takes. ^If thi
2d6b0 73 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 2d  s parameter is -
2d6c0 31 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c 20  1, then the SQL 
2d6d0 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61  function or.** a
2d6e0 67 67 72 65 67 61 74 65 20 6d 61 79 20 74 61 6b  ggregate may tak
2d6f0 65 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66 20  e any number of 
2d700 61 72 67 75 6d 65 6e 74 73 20 62 65 74 77 65 65  arguments betwee
2d710 6e 20 30 20 61 6e 64 20 74 68 65 20 6c 69 6d 69  n 0 and the limi
2d720 74 0a 2a 2a 20 73 65 74 20 62 79 20 5b 73 71 6c  t.** set by [sql
2d730 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c  ite3_limit]([SQL
2d740 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49  ITE_LIMIT_FUNCTI
2d750 4f 4e 5f 41 52 47 5d 29 2e 20 20 49 66 20 74 68  ON_ARG]).  If th
2d760 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d  e third.** param
2d770 65 74 65 72 20 69 73 20 6c 65 73 73 20 74 68 61  eter is less tha
2d780 6e 20 2d 31 20 6f 72 20 67 72 65 61 74 65 72 20  n -1 or greater 
2d790 74 68 61 6e 20 31 32 37 20 74 68 65 6e 20 74 68  than 127 then th
2d7a0 65 20 62 65 68 61 76 69 6f 72 20 69 73 0a 2a 2a  e behavior is.**
2d7b0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
2d7c0 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61  * ^The fourth pa
2d7d0 72 61 6d 65 74 65 72 2c 20 65 54 65 78 74 52 65  rameter, eTextRe
2d7e0 70 2c 20 73 70 65 63 69 66 69 65 73 20 77 68 61  p, specifies wha
2d7f0 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46  t.** [SQLITE_UTF
2d800 38 20 7c 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  8 | text encodin
2d810 67 5d 20 74 68 69 73 20 53 51 4c 20 66 75 6e 63  g] this SQL func
2d820 74 69 6f 6e 20 70 72 65 66 65 72 73 20 66 6f 72  tion prefers for
2d830 0a 2a 2a 20 69 74 73 20 70 61 72 61 6d 65 74 65  .** its paramete
2d840 72 73 2e 20 20 45 76 65 72 79 20 53 51 4c 20 66  rs.  Every SQL f
2d850 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e  unction implemen
2d860 74 61 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 61  tation must be a
2d870 62 6c 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77  ble to work.** w
2d880 69 74 68 20 55 54 46 2d 38 2c 20 55 54 46 2d 31  ith UTF-8, UTF-1
2d890 36 6c 65 2c 20 6f 72 20 55 54 46 2d 31 36 62 65  6le, or UTF-16be
2d8a0 2e 20 20 42 75 74 20 73 6f 6d 65 20 69 6d 70 6c  .  But some impl
2d8b0 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 61 79 20  ementations may 
2d8c0 62 65 0a 2a 2a 20 6d 6f 72 65 20 65 66 66 69 63  be.** more effic
2d8d0 69 65 6e 74 20 77 69 74 68 20 6f 6e 65 20 65 6e  ient with one en
2d8e0 63 6f 64 69 6e 67 20 74 68 61 6e 20 61 6e 6f 74  coding than anot
2d8f0 68 65 72 2e 20 20 5e 41 6e 20 61 70 70 6c 69 63  her.  ^An applic
2d900 61 74 69 6f 6e 20 6d 61 79 0a 2a 2a 20 69 6e 76  ation may.** inv
2d910 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61  oke sqlite3_crea
2d920 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 20 6f 72  te_function() or
2d930 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
2d940 66 75 6e 63 74 69 6f 6e 31 36 28 29 20 6d 75 6c  function16() mul
2d950 74 69 70 6c 65 0a 2a 2a 20 74 69 6d 65 73 20 77  tiple.** times w
2d960 69 74 68 20 74 68 65 20 73 61 6d 65 20 66 75 6e  ith the same fun
2d970 63 74 69 6f 6e 20 62 75 74 20 77 69 74 68 20 64  ction but with d
2d980 69 66 66 65 72 65 6e 74 20 76 61 6c 75 65 73 20  ifferent values 
2d990 6f 66 20 65 54 65 78 74 52 65 70 2e 0a 2a 2a 20  of eTextRep..** 
2d9a0 5e 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20 69  ^When multiple i
2d9b0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f  mplementations o
2d9c0 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74  f the same funct
2d9d0 69 6f 6e 20 61 72 65 20 61 76 61 69 6c 61 62 6c  ion are availabl
2d9e0 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c  e, SQLite.** wil
2d9f0 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e 65 20 74  l pick the one t
2da00 68 61 74 20 69 6e 76 6f 6c 76 65 73 20 74 68 65  hat involves the
2da10 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66   least amount of
2da20 20 64 61 74 61 20 63 6f 6e 76 65 72 73 69 6f 6e   data conversion
2da30 2e 0a 2a 2a 20 49 66 20 74 68 65 72 65 20 69 73  ..** If there is
2da40 20 6f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 69   only a single i
2da50 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68  mplementation wh
2da60 69 63 68 20 64 6f 65 73 20 6e 6f 74 20 63 61 72  ich does not car
2da70 65 20 77 68 61 74 20 74 65 78 74 0a 2a 2a 20 65  e what text.** e
2da80 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64 2c  ncoding is used,
2da90 20 74 68 65 6e 20 74 68 65 20 66 6f 75 72 74 68   then the fourth
2daa0 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64   argument should
2dab0 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 4e 59 5d   be [SQLITE_ANY]
2dac0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69  ..**.** ^(The fi
2dad0 66 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  fth parameter is
2dae0 20 61 6e 20 61 72 62 69 74 72 61 72 79 20 70 6f   an arbitrary po
2daf0 69 6e 74 65 72 2e 20 20 54 68 65 20 69 6d 70 6c  inter.  The impl
2db00 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68  ementation of th
2db10 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 63 61  e.** function ca
2db20 6e 20 67 61 69 6e 20 61 63 63 65 73 73 20 74 6f  n gain access to
2db30 20 74 68 69 73 20 70 6f 69 6e 74 65 72 20 75 73   this pointer us
2db40 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 75 73 65  ing [sqlite3_use
2db50 72 5f 64 61 74 61 28 29 5d 2e 29 5e 0a 2a 2a 0a  r_data()].)^.**.
2db60 2a 2a 20 5e 54 68 65 20 73 69 78 74 68 2c 20 73  ** ^The sixth, s
2db70 65 76 65 6e 74 68 20 61 6e 64 20 65 69 67 68 74  eventh and eight
2db80 68 20 70 61 72 61 6d 65 74 65 72 73 2c 20 78 46  h parameters, xF
2db90 75 6e 63 2c 20 78 53 74 65 70 20 61 6e 64 20 78  unc, xStep and x
2dba0 46 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f  Final, are.** po
2dbb0 69 6e 74 65 72 73 20 74 6f 20 43 2d 6c 61 6e 67  inters to C-lang
2dbc0 75 61 67 65 20 66 75 6e 63 74 69 6f 6e 73 20 74  uage functions t
2dbd0 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68  hat implement th
2dbe0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f  e SQL function o
2dbf0 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 2e 20  r.** aggregate. 
2dc00 5e 41 20 73 63 61 6c 61 72 20 53 51 4c 20 66 75  ^A scalar SQL fu
2dc10 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20  nction requires 
2dc20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  an implementatio
2dc30 6e 20 6f 66 20 74 68 65 20 78 46 75 6e 63 0a 2a  n of the xFunc.*
2dc40 2a 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c 79 3b  * callback only;
2dc50 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 6d   NULL pointers m
2dc60 75 73 74 20 62 65 20 70 61 73 73 65 64 20 61 73  ust be passed as
2dc70 20 74 68 65 20 78 53 74 65 70 20 61 6e 64 20 78   the xStep and x
2dc80 46 69 6e 61 6c 0a 2a 2a 20 70 61 72 61 6d 65 74  Final.** paramet
2dc90 65 72 73 2e 20 5e 41 6e 20 61 67 67 72 65 67 61  ers. ^An aggrega
2dca0 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  te SQL function 
2dcb0 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c  requires an impl
2dcc0 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 78 53  ementation of xS
2dcd0 74 65 70 0a 2a 2a 20 61 6e 64 20 78 46 69 6e 61  tep.** and xFina
2dce0 6c 20 61 6e 64 20 4e 55 4c 4c 20 70 6f 69 6e 74  l and NULL point
2dcf0 65 72 20 6d 75 73 74 20 62 65 20 70 61 73 73 65  er must be passe
2dd00 64 20 66 6f 72 20 78 46 75 6e 63 2e 20 5e 54 6f  d for xFunc. ^To
2dd10 20 64 65 6c 65 74 65 20 61 6e 20 65 78 69 73 74   delete an exist
2dd20 69 6e 67 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74  ing.** SQL funct
2dd30 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65  ion or aggregate
2dd40 2c 20 70 61 73 73 20 4e 55 4c 4c 20 70 6f 69 6e  , pass NULL poin
2dd50 74 65 72 73 20 66 6f 72 20 61 6c 6c 20 74 68 72  ters for all thr
2dd60 65 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 63  ee function.** c
2dd70 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20  allbacks..**.** 
2dd80 5e 28 49 66 20 74 68 65 20 6e 69 6e 74 68 20 70  ^(If the ninth p
2dd90 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
2dda0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2ddb0 69 6f 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74 20  ion_v2() is not 
2ddc0 4e 55 4c 4c 2c 0a 2a 2a 20 74 68 65 6e 20 69 74  NULL,.** then it
2ddd0 20 69 73 20 64 65 73 74 72 75 63 74 6f 72 20 66   is destructor f
2dde0 6f 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  or the applicati
2ddf0 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 2e  on data pointer.
2de00 20 0a 2a 2a 20 54 68 65 20 64 65 73 74 72 75 63   .** The destruc
2de10 74 6f 72 20 69 73 20 69 6e 76 6f 6b 65 64 20 77  tor is invoked w
2de20 68 65 6e 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  hen the function
2de30 20 69 73 20 64 65 6c 65 74 65 64 2c 20 65 69 74   is deleted, eit
2de40 68 65 72 20 62 79 20 62 65 69 6e 67 0a 2a 2a 20  her by being.** 
2de50 6f 76 65 72 6c 6f 61 64 65 64 20 6f 72 20 77 68  overloaded or wh
2de60 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
2de70 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65  connection close
2de80 73 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 64 65 73  s.)^.** ^The des
2de90 74 72 75 63 74 6f 72 20 69 73 20 61 6c 73 6f 20  tructor is also 
2dea0 69 6e 76 6f 6b 65 64 20 69 66 20 74 68 65 20 63  invoked if the c
2deb0 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  all to.** sqlite
2dec0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
2ded0 6e 5f 76 32 28 29 20 66 61 69 6c 73 2e 0a 2a 2a  n_v2() fails..**
2dee0 20 5e 57 68 65 6e 20 74 68 65 20 64 65 73 74 72   ^When the destr
2def0 75 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20 6f  uctor callback o
2df00 66 20 74 68 65 20 74 65 6e 74 68 20 70 61 72 61  f the tenth para
2df10 6d 65 74 65 72 20 69 73 20 69 6e 76 6f 6b 65 64  meter is invoked
2df20 2c 20 69 74 0a 2a 2a 20 69 73 20 70 61 73 73 65  , it.** is passe
2df30 64 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  d a single argum
2df40 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 63  ent which is a c
2df50 6f 70 79 20 6f 66 20 74 68 65 20 61 70 70 6c 69  opy of the appli
2df60 63 61 74 69 6f 6e 20 64 61 74 61 20 0a 2a 2a 20  cation data .** 
2df70 70 6f 69 6e 74 65 72 20 77 68 69 63 68 20 77 61  pointer which wa
2df80 73 20 74 68 65 20 66 69 66 74 68 20 70 61 72 61  s the fifth para
2df90 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
2dfa0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
2dfb0 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74  _v2()..**.** ^It
2dfc0 20 69 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f   is permitted to
2dfd0 20 72 65 67 69 73 74 65 72 20 6d 75 6c 74 69 70   register multip
2dfe0 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
2dff0 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 0a 2a  ns of the same.*
2e000 2a 20 66 75 6e 63 74 69 6f 6e 73 20 77 69 74 68  * functions with
2e010 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 62   the same name b
2e020 75 74 20 77 69 74 68 20 65 69 74 68 65 72 20 64  ut with either d
2e030 69 66 66 65 72 69 6e 67 20 6e 75 6d 62 65 72 73  iffering numbers
2e040 20 6f 66 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 73   of.** arguments
2e050 20 6f 72 20 64 69 66 66 65 72 69 6e 67 20 70 72   or differing pr
2e060 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63  eferred text enc
2e070 6f 64 69 6e 67 73 2e 20 20 5e 53 51 4c 69 74 65  odings.  ^SQLite
2e080 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 74 68 65   will use.** the
2e090 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
2e0a0 74 68 61 74 20 6d 6f 73 74 20 63 6c 6f 73 65 6c  that most closel
2e0b0 79 20 6d 61 74 63 68 65 73 20 74 68 65 20 77 61  y matches the wa
2e0c0 79 20 69 6e 20 77 68 69 63 68 20 74 68 65 0a 2a  y in which the.*
2e0d0 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69  * SQL function i
2e0e0 73 20 75 73 65 64 2e 20 20 5e 41 20 66 75 6e 63  s used.  ^A func
2e0f0 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  tion implementat
2e100 69 6f 6e 20 77 69 74 68 20 61 20 6e 6f 6e 2d 6e  ion with a non-n
2e110 65 67 61 74 69 76 65 0a 2a 2a 20 6e 41 72 67 20  egative.** nArg 
2e120 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 62  parameter is a b
2e130 65 74 74 65 72 20 6d 61 74 63 68 20 74 68 61 6e  etter match than
2e140 20 61 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c   a function impl
2e150 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 0a  ementation with.
2e160 2a 2a 20 61 20 6e 65 67 61 74 69 76 65 20 6e 41  ** a negative nA
2e170 72 67 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e  rg.  ^A function
2e180 20 77 68 65 72 65 20 74 68 65 20 70 72 65 66 65   where the prefe
2e190 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69  rred text encodi
2e1a0 6e 67 0a 2a 2a 20 6d 61 74 63 68 65 73 20 74 68  ng.** matches th
2e1b0 65 20 64 61 74 61 62 61 73 65 20 65 6e 63 6f 64  e database encod
2e1c0 69 6e 67 20 69 73 20 61 20 62 65 74 74 65 72 0a  ing is a better.
2e1d0 2a 2a 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20  ** match than a 
2e1e0 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74  function where t
2e1f0 68 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 64  he encoding is d
2e200 69 66 66 65 72 65 6e 74 2e 20 20 0a 2a 2a 20 5e  ifferent.  .** ^
2e210 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65  A function where
2e220 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69   the encoding di
2e230 66 66 65 72 65 6e 63 65 20 69 73 20 62 65 74 77  fference is betw
2e240 65 65 6e 20 55 54 46 31 36 6c 65 20 61 6e 64 20  een UTF16le and 
2e250 55 54 46 31 36 62 65 0a 2a 2a 20 69 73 20 61 20  UTF16be.** is a 
2e260 63 6c 6f 73 65 72 20 6d 61 74 63 68 20 74 68 61  closer match tha
2e270 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65  n a function whe
2e280 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20  re the encoding 
2e290 64 69 66 66 65 72 65 6e 63 65 20 69 73 0a 2a 2a  difference is.**
2e2a0 20 62 65 74 77 65 65 6e 20 55 54 46 38 20 61 6e   between UTF8 an
2e2b0 64 20 55 54 46 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e  d UTF16..**.** ^
2e2c0 42 75 69 6c 74 2d 69 6e 20 66 75 6e 63 74 69 6f  Built-in functio
2e2d0 6e 73 20 6d 61 79 20 62 65 20 6f 76 65 72 6c 6f  ns may be overlo
2e2e0 61 64 65 64 20 62 79 20 6e 65 77 20 61 70 70 6c  aded by new appl
2e2f0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
2e300 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  functions..**.**
2e310 20 5e 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e   ^An application
2e320 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
2e330 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64 20 74  n is permitted t
2e340 6f 20 63 61 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20  o call other.** 
2e350 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
2e360 73 2e 20 20 48 6f 77 65 76 65 72 2c 20 73 75 63  s.  However, suc
2e370 68 20 63 61 6c 6c 73 20 6d 75 73 74 20 6e 6f 74  h calls must not
2e380 0a 2a 2a 20 63 6c 6f 73 65 20 74 68 65 20 64 61  .** close the da
2e390 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2e3a0 6e 20 6e 6f 72 20 66 69 6e 61 6c 69 7a 65 20 6f  n nor finalize o
2e3b0 72 20 72 65 73 65 74 20 74 68 65 20 70 72 65 70  r reset the prep
2e3c0 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e  ared.** statemen
2e3d0 74 20 69 6e 20 77 68 69 63 68 20 74 68 65 20 66  t in which the f
2e3e0 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69  unction is runni
2e3f0 6e 67 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ng..*/.int sqlit
2e400 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
2e410 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  on(.  sqlite3 *d
2e420 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  b,.  const char 
2e430 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a  *zFunctionName,.
2e440 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e    int nArg,.  in
2e450 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f  t eTextRep,.  vo
2e460 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64  id *pApp,.  void
2e470 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65   (*xFunc)(sqlite
2e480 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73  3_context*,int,s
2e490 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c  qlite3_value**),
2e4a0 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29  .  void (*xStep)
2e4b0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
2e4c0 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61  *,int,sqlite3_va
2e4d0 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28  lue**),.  void (
2e4e0 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33  *xFinal)(sqlite3
2e4f0 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 69 6e  _context*).);.in
2e500 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  t sqlite3_create
2e510 5f 66 75 6e 63 74 69 6f 6e 31 36 28 0a 20 20 73  _function16(.  s
2e520 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f  qlite3 *db,.  co
2e530 6e 73 74 20 76 6f 69 64 20 2a 7a 46 75 6e 63 74  nst void *zFunct
2e540 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e  ionName,.  int n
2e550 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74  Arg,.  int eText
2e560 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70  Rep,.  void *pAp
2e570 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e  p,.  void (*xFun
2e580 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  c)(sqlite3_conte
2e590 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f  xt*,int,sqlite3_
2e5a0 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64  value**),.  void
2e5b0 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65   (*xStep)(sqlite
2e5c0 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73  3_context*,int,s
2e5d0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c  qlite3_value**),
2e5e0 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c  .  void (*xFinal
2e5f0 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
2e600 74 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  t*).);.int sqlit
2e610 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
2e620 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33  on_v2(.  sqlite3
2e630 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68   *db,.  const ch
2e640 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d  ar *zFunctionNam
2e650 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20  e,.  int nArg,. 
2e660 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20   int eTextRep,. 
2e670 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76   void *pApp,.  v
2e680 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c  oid (*xFunc)(sql
2e690 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e  ite3_context*,in
2e6a0 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t,sqlite3_value*
2e6b0 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74  *),.  void (*xSt
2e6c0 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ep)(sqlite3_cont
2e6d0 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33  ext*,int,sqlite3
2e6e0 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69  _value**),.  voi
2e6f0 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69  d (*xFinal)(sqli
2e700 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 2c 0a 20  te3_context*),. 
2e710 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29   void(*xDestroy)
2e720 28 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a  (void*).);../*.*
2e730 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65 78 74  * CAPI3REF: Text
2e740 20 45 6e 63 6f 64 69 6e 67 73 0a 2a 2a 0a 2a 2a   Encodings.**.**
2e750 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 20   These constant 
2e760 64 65 66 69 6e 65 20 69 6e 74 65 67 65 72 20 63  define integer c
2e770 6f 64 65 73 20 74 68 61 74 20 72 65 70 72 65 73  odes that repres
2e780 65 6e 74 20 74 68 65 20 76 61 72 69 6f 75 73 0a  ent the various.
2e790 2a 2a 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67  ** text encoding
2e7a0 73 20 73 75 70 70 6f 72 74 65 64 20 62 79 20 53  s supported by S
2e7b0 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e  QLite..*/.#defin
2e7c0 65 20 53 51 4c 49 54 45 5f 55 54 46 38 20 20 20  e SQLITE_UTF8   
2e7d0 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e          1.#defin
2e7e0 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45  e SQLITE_UTF16LE
2e7f0 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e          2.#defin
2e800 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45  e SQLITE_UTF16BE
2e810 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e          3.#defin
2e820 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 20 20  e SQLITE_UTF16  
2e830 20 20 20 20 20 20 20 20 34 20 20 20 20 2f 2a 20          4    /* 
2e840 55 73 65 20 6e 61 74 69 76 65 20 62 79 74 65 20  Use native byte 
2e850 6f 72 64 65 72 20 2a 2f 0a 23 64 65 66 69 6e 65  order */.#define
2e860 20 53 51 4c 49 54 45 5f 41 4e 59 20 20 20 20 20   SQLITE_ANY     
2e870 20 20 20 20 20 20 20 35 20 20 20 20 2f 2a 20 73         5    /* s
2e880 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
2e890 6e 63 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 23  nction only */.#
2e8a0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54  define SQLITE_UT
2e8b0 46 31 36 5f 41 4c 49 47 4e 45 44 20 20 38 20 20  F16_ALIGNED  8  
2e8c0 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 65    /* sqlite3_cre
2e8d0 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e  ate_collation on
2e8e0 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ly */../*.** CAP
2e8f0 49 33 52 45 46 3a 20 44 65 70 72 65 63 61 74 65  I3REF: Deprecate
2e900 64 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 44  d Functions.** D
2e910 45 50 52 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20  EPRECATED.**.** 
2e920 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  These functions 
2e930 61 72 65 20 5b 64 65 70 72 65 63 61 74 65 64 5d  are [deprecated]
2e940 2e 20 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 6d  .  In order to m
2e950 61 69 6e 74 61 69 6e 0a 2a 2a 20 62 61 63 6b 77  aintain.** backw
2e960 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69  ards compatibili
2e970 74 79 20 77 69 74 68 20 6f 6c 64 65 72 20 63 6f  ty with older co
2e980 64 65 2c 20 74 68 65 73 65 20 66 75 6e 63 74 69  de, these functi
2e990 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20 0a 2a 2a  ons continue .**
2e9a0 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64   to be supported
2e9b0 2e 20 20 48 6f 77 65 76 65 72 2c 20 6e 65 77 20  .  However, new 
2e9c0 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f  applications sho
2e9d0 75 6c 64 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65  uld avoid.** the
2e9e0 20 75 73 65 20 6f 66 20 74 68 65 73 65 20 66 75   use of these fu
2e9f0 6e 63 74 69 6f 6e 73 2e 20 20 54 6f 20 68 65 6c  nctions.  To hel
2ea00 70 20 65 6e 63 6f 75 72 61 67 65 20 70 65 6f 70  p encourage peop
2ea10 6c 65 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 75  le to avoid.** u
2ea20 73 69 6e 67 20 74 68 65 73 65 20 66 75 6e 63 74  sing these funct
2ea30 69 6f 6e 73 2c 20 77 65 20 61 72 65 20 6e 6f 74  ions, we are not
2ea40 20 67 6f 69 6e 67 20 74 6f 20 74 65 6c 6c 20 79   going to tell y
2ea50 6f 75 20 77 68 61 74 20 74 68 65 79 20 64 6f 2e  ou what they do.
2ea60 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49  .*/.#ifndef SQLI
2ea70 54 45 5f 4f 4d 49 54 5f 44 45 50 52 45 43 41 54  TE_OMIT_DEPRECAT
2ea80 45 44 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43  ED.SQLITE_DEPREC
2ea90 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33  ATED int sqlite3
2eaa0 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 75 6e 74  _aggregate_count
2eab0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
2eac0 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45  *);.SQLITE_DEPRE
2ead0 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65  CATED int sqlite
2eae0 33 5f 65 78 70 69 72 65 64 28 73 71 6c 69 74 65  3_expired(sqlite
2eaf0 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45  3_stmt*);.SQLITE
2eb00 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20  _DEPRECATED int 
2eb10 73 71 6c 69 74 65 33 5f 74 72 61 6e 73 66 65 72  sqlite3_transfer
2eb20 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65  _bindings(sqlite
2eb30 33 5f 73 74 6d 74 2a 2c 20 73 71 6c 69 74 65 33  3_stmt*, sqlite3
2eb40 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f  _stmt*);.SQLITE_
2eb50 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73  DEPRECATED int s
2eb60 71 6c 69 74 65 33 5f 67 6c 6f 62 61 6c 5f 72 65  qlite3_global_re
2eb70 63 6f 76 65 72 28 76 6f 69 64 29 3b 0a 53 51 4c  cover(void);.SQL
2eb80 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 76  ITE_DEPRECATED v
2eb90 6f 69 64 20 73 71 6c 69 74 65 33 5f 74 68 72 65  oid sqlite3_thre
2eba0 61 64 5f 63 6c 65 61 6e 75 70 28 76 6f 69 64 29  ad_cleanup(void)
2ebb0 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  ;.SQLITE_DEPRECA
2ebc0 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  TED int sqlite3_
2ebd0 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 76 6f 69  memory_alarm(voi
2ebe0 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74  d(*)(void*,sqlit
2ebf0 65 33 5f 69 6e 74 36 34 2c 69 6e 74 29 2c 76 6f  e3_int64,int),vo
2ec00 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36  id*,sqlite3_int6
2ec10 34 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a  4);.#endif../*.*
2ec20 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61  * CAPI3REF: Obta
2ec30 69 6e 69 6e 67 20 53 51 4c 20 46 75 6e 63 74 69  ining SQL Functi
2ec40 6f 6e 20 50 61 72 61 6d 65 74 65 72 20 56 61 6c  on Parameter Val
2ec50 75 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d  ues.**.** The C-
2ec60 6c 61 6e 67 75 61 67 65 20 69 6d 70 6c 65 6d 65  language impleme
2ec70 6e 74 61 74 69 6f 6e 20 6f 66 20 53 51 4c 20 66  ntation of SQL f
2ec80 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67  unctions and agg
2ec90 72 65 67 61 74 65 73 20 75 73 65 73 0a 2a 2a 20  regates uses.** 
2eca0 74 68 69 73 20 73 65 74 20 6f 66 20 69 6e 74 65  this set of inte
2ecb0 72 66 61 63 65 20 72 6f 75 74 69 6e 65 73 20 74  rface routines t
2ecc0 6f 20 61 63 63 65 73 73 20 74 68 65 20 70 61 72  o access the par
2ecd0 61 6d 65 74 65 72 20 76 61 6c 75 65 73 20 6f 6e  ameter values on
2ece0 0a 2a 2a 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  .** the function
2ecf0 20 6f 72 20 61 67 67 72 65 67 61 74 65 2e 0a 2a   or aggregate..*
2ed00 2a 0a 2a 2a 20 54 68 65 20 78 46 75 6e 63 20 28  *.** The xFunc (
2ed10 66 6f 72 20 73 63 61 6c 61 72 20 66 75 6e 63 74  for scalar funct
2ed20 69 6f 6e 73 29 20 6f 72 20 78 53 74 65 70 20 28  ions) or xStep (
2ed30 66 6f 72 20 61 67 67 72 65 67 61 74 65 73 29 20  for aggregates) 
2ed40 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f  parameters.** to
2ed50 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
2ed60 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64  _function()] and
2ed70 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
2ed80 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a  _function16()].*
2ed90 2a 20 64 65 66 69 6e 65 20 63 61 6c 6c 62 61 63  * define callbac
2eda0 6b 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e  ks that implemen
2edb0 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  t the SQL functi
2edc0 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74  ons and aggregat
2edd0 65 73 2e 0a 2a 2a 20 54 68 65 20 33 72 64 20 70  es..** The 3rd p
2ede0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 73  arameter to thes
2edf0 65 20 63 61 6c 6c 62 61 63 6b 73 20 69 73 20 61  e callbacks is a
2ee00 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74  n array of point
2ee10 65 72 73 20 74 6f 0a 2a 2a 20 5b 70 72 6f 74 65  ers to.** [prote
2ee20 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
2ee30 75 65 5d 20 6f 62 6a 65 63 74 73 2e 20 20 54 68  ue] objects.  Th
2ee40 65 72 65 20 69 73 20 6f 6e 65 20 5b 73 71 6c 69  ere is one [sqli
2ee50 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
2ee60 74 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 70 61  t for.** each pa
2ee70 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 53  rameter to the S
2ee80 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 20 20 54 68  QL function.  Th
2ee90 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
2eea0 20 75 73 65 64 20 74 6f 0a 2a 2a 20 65 78 74 72   used to.** extr
2eeb0 61 63 74 20 76 61 6c 75 65 73 20 66 72 6f 6d 20  act values from 
2eec0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  the [sqlite3_val
2eed0 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a  ue] objects..**.
2eee0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
2eef0 73 20 77 6f 72 6b 20 6f 6e 6c 79 20 77 69 74 68  s work only with
2ef00 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   [protected sqli
2ef10 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
2ef20 74 73 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d  ts..** Any attem
2ef30 70 74 20 74 6f 20 75 73 65 20 74 68 65 73 65 20  pt to use these 
2ef40 72 6f 75 74 69 6e 65 73 20 6f 6e 20 61 6e 20 5b  routines on an [
2ef50 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
2ef60 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62  te3_value].** ob
2ef70 6a 65 63 74 20 72 65 73 75 6c 74 73 20 69 6e 20  ject results in 
2ef80 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 69  undefined behavi
2ef90 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  or..**.** ^These
2efa0 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6a   routines work j
2efb0 75 73 74 20 6c 69 6b 65 20 74 68 65 20 63 6f 72  ust like the cor
2efc0 72 65 73 70 6f 6e 64 69 6e 67 20 5b 63 6f 6c 75  responding [colu
2efd0 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69  mn access functi
2efe0 6f 6e 73 5d 0a 2a 2a 20 65 78 63 65 70 74 20 74  ons].** except t
2eff0 68 61 74 20 20 74 68 65 73 65 20 72 6f 75 74 69  hat  these routi
2f000 6e 65 73 20 74 61 6b 65 20 61 20 73 69 6e 67 6c  nes take a singl
2f010 65 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c  e [protected sql
2f020 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
2f030 63 74 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e  ct.** pointer in
2f040 73 74 65 61 64 20 6f 66 20 61 20 5b 73 71 6c 69  stead of a [sqli
2f050 74 65 33 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e 74  te3_stmt*] point
2f060 65 72 20 61 6e 64 20 61 6e 20 69 6e 74 65 67 65  er and an intege
2f070 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e  r column number.
2f080 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2f090 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
2f0a0 28 29 20 69 6e 74 65 72 66 61 63 65 20 65 78 74  () interface ext
2f0b0 72 61 63 74 73 20 61 20 55 54 46 2d 31 36 20 73  racts a UTF-16 s
2f0c0 74 72 69 6e 67 0a 2a 2a 20 69 6e 20 74 68 65 20  tring.** in the 
2f0d0 6e 61 74 69 76 65 20 62 79 74 65 2d 6f 72 64 65  native byte-orde
2f0e0 72 20 6f 66 20 74 68 65 20 68 6f 73 74 20 6d 61  r of the host ma
2f0f0 63 68 69 6e 65 2e 20 20 5e 54 68 65 0a 2a 2a 20  chine.  ^The.** 
2f100 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
2f110 78 74 31 36 62 65 28 29 20 61 6e 64 20 73 71 6c  xt16be() and sql
2f120 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
2f130 36 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 73  6le() interfaces
2f140 0a 2a 2a 20 65 78 74 72 61 63 74 20 55 54 46 2d  .** extract UTF-
2f150 31 36 20 73 74 72 69 6e 67 73 20 61 73 20 62 69  16 strings as bi
2f160 67 2d 65 6e 64 69 61 6e 20 61 6e 64 20 6c 69 74  g-endian and lit
2f170 74 6c 65 2d 65 6e 64 69 61 6e 20 72 65 73 70 65  tle-endian respe
2f180 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e  ctively..**.** ^
2f190 28 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c  (The sqlite3_val
2f1a0 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28  ue_numeric_type(
2f1b0 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65  ) interface atte
2f1c0 6d 70 74 73 20 74 6f 20 61 70 70 6c 79 0a 2a 2a  mpts to apply.**
2f1d0 20 6e 75 6d 65 72 69 63 20 61 66 66 69 6e 69 74   numeric affinit
2f1e0 79 20 74 6f 20 74 68 65 20 76 61 6c 75 65 2e 20  y to the value. 
2f1f0 20 54 68 69 73 20 6d 65 61 6e 73 20 74 68 61 74   This means that
2f200 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 0a 2a   an attempt is.*
2f210 2a 20 6d 61 64 65 20 74 6f 20 63 6f 6e 76 65 72  * made to conver
2f220 74 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 61  t the value to a
2f230 6e 20 69 6e 74 65 67 65 72 20 6f 72 20 66 6c 6f  n integer or flo
2f240 61 74 69 6e 67 20 70 6f 69 6e 74 2e 20 20 49 66  ating point.  If
2f250 0a 2a 2a 20 73 75 63 68 20 61 20 63 6f 6e 76 65  .** such a conve
2f260 72 73 69 6f 6e 20 69 73 20 70 6f 73 73 69 62 6c  rsion is possibl
2f270 65 20 77 69 74 68 6f 75 74 20 6c 6f 73 73 20 6f  e without loss o
2f280 66 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 28 69  f information (i
2f290 6e 20 6f 74 68 65 72 0a 2a 2a 20 77 6f 72 64 73  n other.** words
2f2a0 2c 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 69  , if the value i
2f2b0 73 20 61 20 73 74 72 69 6e 67 20 74 68 61 74 20  s a string that 
2f2c0 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61 20 6e 75 6d  looks like a num
2f2d0 62 65 72 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ber).** then the
2f2e0 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70   conversion is p
2f2f0 65 72 66 6f 72 6d 65 64 2e 20 20 4f 74 68 65 72  erformed.  Other
2f300 77 69 73 65 20 6e 6f 20 63 6f 6e 76 65 72 73 69  wise no conversi
2f310 6f 6e 20 6f 63 63 75 72 73 2e 0a 2a 2a 20 54 68  on occurs..** Th
2f320 65 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45  e [SQLITE_INTEGE
2f330 52 20 7c 20 64 61 74 61 74 79 70 65 5d 20 61 66  R | datatype] af
2f340 74 65 72 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69  ter conversion i
2f350 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 0a 2a 2a  s returned.)^.**
2f360 0a 2a 2a 20 50 6c 65 61 73 65 20 70 61 79 20 70  .** Please pay p
2f370 61 72 74 69 63 75 6c 61 72 20 61 74 74 65 6e 74  articular attent
2f380 69 6f 6e 20 74 6f 20 74 68 65 20 66 61 63 74 20  ion to the fact 
2f390 74 68 61 74 20 74 68 65 20 70 6f 69 6e 74 65 72  that the pointer
2f3a0 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f   returned.** fro
2f3b0 6d 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  m [sqlite3_value
2f3c0 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74  _blob()], [sqlit
2f3d0 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d  e3_value_text()]
2f3e0 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  , or.** [sqlite3
2f3f0 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d  _value_text16()]
2f400 20 63 61 6e 20 62 65 20 69 6e 76 61 6c 69 64 61   can be invalida
2f410 74 65 64 20 62 79 20 61 20 73 75 62 73 65 71 75  ted by a subsequ
2f420 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b  ent call to.** [
2f430 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
2f440 74 65 73 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  tes()], [sqlite3
2f450 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 29  _value_bytes16()
2f460 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ], [sqlite3_valu
2f470 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72  e_text()],.** or
2f480 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
2f490 74 65 78 74 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a  text16()]..**.**
2f4a0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
2f4b0 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66  must be called f
2f4c0 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72  rom the same thr
2f4d0 65 61 64 20 61 73 0a 2a 2a 20 74 68 65 20 53 51  ead as.** the SQ
2f4e0 4c 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20  L function that 
2f4f0 73 75 70 70 6c 69 65 64 20 74 68 65 20 5b 73 71  supplied the [sq
2f500 6c 69 74 65 33 5f 76 61 6c 75 65 2a 5d 20 70 61  lite3_value*] pa
2f510 72 61 6d 65 74 65 72 73 2e 0a 2a 2f 0a 63 6f 6e  rameters..*/.con
2f520 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
2f530 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 73 71 6c 69  _value_blob(sqli
2f540 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74  te3_value*);.int
2f550 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62   sqlite3_value_b
2f560 79 74 65 73 28 73 71 6c 69 74 65 33 5f 76 61 6c  ytes(sqlite3_val
2f570 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  ue*);.int sqlite
2f580 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28  3_value_bytes16(
2f590 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
2f5a0 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f  .double sqlite3_
2f5b0 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28 73 71 6c  value_double(sql
2f5c0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e  ite3_value*);.in
2f5d0 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  t sqlite3_value_
2f5e0 69 6e 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  int(sqlite3_valu
2f5f0 65 2a 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74  e*);.sqlite3_int
2f600 36 34 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  64 sqlite3_value
2f610 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 76  _int64(sqlite3_v
2f620 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 75 6e  alue*);.const un
2f630 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c  signed char *sql
2f640 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28  ite3_value_text(
2f650 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
2f660 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
2f670 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
2f680 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  6(sqlite3_value*
2f690 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
2f6a0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
2f6b0 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 76 61  t16le(sqlite3_va
2f6c0 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  lue*);.const voi
2f6d0 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  d *sqlite3_value
2f6e0 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69 74 65  _text16be(sqlite
2f6f0 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73  3_value*);.int s
2f700 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70  qlite3_value_typ
2f710 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  e(sqlite3_value*
2f720 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76  );.int sqlite3_v
2f730 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70  alue_numeric_typ
2f740 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  e(sqlite3_value*
2f750 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2f760 45 46 3a 20 4f 62 74 61 69 6e 20 41 67 67 72 65  EF: Obtain Aggre
2f770 67 61 74 65 20 46 75 6e 63 74 69 6f 6e 20 43 6f  gate Function Co
2f780 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 49 6d 70 6c  ntext.**.** Impl
2f790 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 61  ementations of a
2f7a0 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e  ggregate SQL fun
2f7b0 63 74 69 6f 6e 73 20 75 73 65 20 74 68 69 73 0a  ctions use this.
2f7c0 2a 2a 20 72 6f 75 74 69 6e 65 20 74 6f 20 61 6c  ** routine to al
2f7d0 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 66 6f  locate memory fo
2f7e0 72 20 73 74 6f 72 69 6e 67 20 74 68 65 69 72 20  r storing their 
2f7f0 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  state..**.** ^Th
2f800 65 20 66 69 72 73 74 20 74 69 6d 65 20 74 68 65  e first time the
2f810 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
2f820 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20  te_context(C,N) 
2f830 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65  routine is calle
2f840 64 20 0a 2a 2a 20 66 6f 72 20 61 20 70 61 72 74  d .** for a part
2f850 69 63 75 6c 61 72 20 61 67 67 72 65 67 61 74 65  icular aggregate
2f860 20 66 75 6e 63 74 69 6f 6e 2c 20 53 51 4c 69 74   function, SQLit
2f870 65 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 73 20 4e  e.** allocates N
2f880 20 6f 66 20 6d 65 6d 6f 72 79 2c 20 7a 65 72 6f   of memory, zero
2f890 65 73 20 6f 75 74 20 74 68 61 74 20 6d 65 6d 6f  es out that memo
2f8a0 72 79 2c 20 61 6e 64 20 72 65 74 75 72 6e 73 20  ry, and returns 
2f8b0 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20  a pointer.** to 
2f8c0 74 68 65 20 6e 65 77 20 6d 65 6d 6f 72 79 2e 20  the new memory. 
2f8d0 5e 4f 6e 20 73 65 63 6f 6e 64 20 61 6e 64 20 73  ^On second and s
2f8e0 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20  ubsequent calls 
2f8f0 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67  to.** sqlite3_ag
2f900 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
2f910 29 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 61  ) for the same a
2f920 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f  ggregate functio
2f930 6e 20 69 6e 73 74 61 6e 63 65 2c 0a 2a 2a 20 74  n instance,.** t
2f940 68 65 20 73 61 6d 65 20 62 75 66 66 65 72 20 69  he same buffer i
2f950 73 20 72 65 74 75 72 6e 65 64 2e 20 20 53 71 6c  s returned.  Sql
2f960 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
2f970 6f 6e 74 65 78 74 28 29 20 69 73 20 6e 6f 72 6d  ontext() is norm
2f980 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 6f  ally.** called o
2f990 6e 63 65 20 66 6f 72 20 65 61 63 68 20 69 6e 76  nce for each inv
2f9a0 6f 63 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78  ocation of the x
2f9b0 53 74 65 70 20 63 61 6c 6c 62 61 63 6b 20 61 6e  Step callback an
2f9c0 64 20 74 68 65 6e 20 6f 6e 65 0a 2a 2a 20 6c 61  d then one.** la
2f9d0 73 74 20 74 69 6d 65 20 77 68 65 6e 20 74 68 65  st time when the
2f9e0 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b   xFinal callback
2f9f0 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 28   is invoked.  ^(
2fa00 57 68 65 6e 20 6e 6f 20 72 6f 77 73 20 6d 61 74  When no rows mat
2fa10 63 68 0a 2a 2a 20 61 6e 20 61 67 67 72 65 67 61  ch.** an aggrega
2fa20 74 65 20 71 75 65 72 79 2c 20 74 68 65 20 78 53  te query, the xS
2fa30 74 65 70 28 29 20 63 61 6c 6c 62 61 63 6b 20 6f  tep() callback o
2fa40 66 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20  f the aggregate 
2fa50 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 69 6d 70 6c  function.** impl
2fa60 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6e 65  ementation is ne
2fa70 76 65 72 20 63 61 6c 6c 65 64 20 61 6e 64 20 78  ver called and x
2fa80 46 69 6e 61 6c 28 29 20 69 73 20 63 61 6c 6c 65  Final() is calle
2fa90 64 20 65 78 61 63 74 6c 79 20 6f 6e 63 65 2e 0a  d exactly once..
2faa0 2a 2a 20 49 6e 20 74 68 6f 73 65 20 63 61 73 65  ** In those case
2fab0 73 2c 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  s, sqlite3_aggre
2fac0 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 6d  gate_context() m
2fad0 69 67 68 74 20 62 65 20 63 61 6c 6c 65 64 20 66  ight be called f
2fae0 6f 72 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20  or the.** first 
2faf0 74 69 6d 65 20 66 72 6f 6d 20 77 69 74 68 69 6e  time from within
2fb00 20 78 46 69 6e 61 6c 28 29 2e 29 5e 0a 2a 2a 0a   xFinal().)^.**.
2fb10 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2fb20 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
2fb30 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e 65 20 72  t(C,N) routine r
2fb40 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f  eturns a NULL po
2fb50 69 6e 74 65 72 20 69 66 20 4e 20 69 73 0a 2a 2a  inter if N is.**
2fb60 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71   less than or eq
2fb70 75 61 6c 20 74 6f 20 7a 65 72 6f 20 6f 72 20 69  ual to zero or i
2fb80 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  f a memory alloc
2fb90 61 74 65 20 65 72 72 6f 72 20 6f 63 63 75 72 73  ate error occurs
2fba0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 61 6d  ..**.** ^(The am
2fbb0 6f 75 6e 74 20 6f 66 20 73 70 61 63 65 20 61 6c  ount of space al
2fbc0 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69 74  located by sqlit
2fbd0 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
2fbe0 74 65 78 74 28 43 2c 4e 29 20 69 73 0a 2a 2a 20  text(C,N) is.** 
2fbf0 64 65 74 65 72 6d 69 6e 65 64 20 62 79 20 74 68  determined by th
2fc00 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20 6f 6e  e N parameter on
2fc10 20 66 69 72 73 74 20 73 75 63 63 65 73 73 66 75   first successfu
2fc20 6c 20 63 61 6c 6c 2e 20 20 43 68 61 6e 67 69 6e  l call.  Changin
2fc30 67 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f  g the.** value o
2fc40 66 20 4e 20 69 6e 20 73 75 62 73 65 71 75 65 6e  f N in subsequen
2fc50 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  t call to sqlite
2fc60 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
2fc70 65 78 74 28 29 20 77 69 74 68 69 6e 0a 2a 2a 20  ext() within.** 
2fc80 74 68 65 20 73 61 6d 65 20 61 67 67 72 65 67 61  the same aggrega
2fc90 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74  te function inst
2fca0 61 6e 63 65 20 77 69 6c 6c 20 6e 6f 74 20 72 65  ance will not re
2fcb0 73 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 0a  size the memory.
2fcc0 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 2e 29 5e  ** allocation.)^
2fcd0 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 61  .**.** ^SQLite a
2fce0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 66 72 65  utomatically fre
2fcf0 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c  es the memory al
2fd00 6c 6f 63 61 74 65 64 20 62 79 20 0a 2a 2a 20 73  located by .** s
2fd10 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
2fd20 5f 63 6f 6e 74 65 78 74 28 29 20 77 68 65 6e 20  _context() when 
2fd30 74 68 65 20 61 67 67 72 65 67 61 74 65 20 71 75  the aggregate qu
2fd40 65 72 79 20 63 6f 6e 63 6c 75 64 65 73 2e 0a 2a  ery concludes..*
2fd50 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70  *.** The first p
2fd60 61 72 61 6d 65 74 65 72 20 6d 75 73 74 20 62 65  arameter must be
2fd70 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a   a copy of the.*
2fd80 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  * [sqlite3_conte
2fd90 78 74 20 7c 20 53 51 4c 20 66 75 6e 63 74 69 6f  xt | SQL functio
2fda0 6e 20 63 6f 6e 74 65 78 74 5d 20 74 68 61 74 20  n context] that 
2fdb0 69 73 20 74 68 65 20 66 69 72 73 74 20 70 61 72  is the first par
2fdc0 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65  ameter.** to the
2fdd0 20 78 53 74 65 70 20 6f 72 20 78 46 69 6e 61 6c   xStep or xFinal
2fde0 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e   callback routin
2fdf0 65 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74  e that implement
2fe00 73 20 74 68 65 20 61 67 67 72 65 67 61 74 65 0a  s the aggregate.
2fe10 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a  ** function..**.
2fe20 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  ** This routine 
2fe30 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66  must be called f
2fe40 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72  rom the same thr
2fe50 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20  ead in which.** 
2fe60 74 68 65 20 61 67 67 72 65 67 61 74 65 20 53 51  the aggregate SQ
2fe70 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75  L function is ru
2fe80 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a  nning..*/.void *
2fe90 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
2fea0 65 5f 63 6f 6e 74 65 78 74 28 73 71 6c 69 74 65  e_context(sqlite
2feb0 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20  3_context*, int 
2fec0 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20  nBytes);../*.** 
2fed0 43 41 50 49 33 52 45 46 3a 20 55 73 65 72 20 44  CAPI3REF: User D
2fee0 61 74 61 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e  ata For Function
2fef0 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s.**.** ^The sql
2ff00 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29  ite3_user_data()
2ff10 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
2ff20 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20  ns a copy of.** 
2ff30 74 68 65 20 70 6f 69 6e 74 65 72 20 74 68 61 74  the pointer that
2ff40 20 77 61 73 20 74 68 65 20 70 55 73 65 72 44 61   was the pUserDa
2ff50 74 61 20 70 61 72 61 6d 65 74 65 72 20 28 74 68  ta parameter (th
2ff60 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 29  e 5th parameter)
2ff70 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  .** of the [sqli
2ff80 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2ff90 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73  ion()].** and [s
2ffa0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
2ffb0 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74  nction16()] rout
2ffc0 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e  ines that origin
2ffd0 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72  ally.** register
2ffe0 65 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ed the applicati
2fff0 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on defined funct
30000 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ion..**.** This 
30010 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20  routine must be 
30020 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20  called from the 
30030 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77  same thread in w
30040 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 70 70 6c  hich.** the appl
30050 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
30060 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e  function is runn
30070 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71  ing..*/.void *sq
30080 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28  lite3_user_data(
30090 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
300a0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
300b0 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e  EF: Database Con
300c0 6e 65 63 74 69 6f 6e 20 46 6f 72 20 46 75 6e 63  nection For Func
300d0 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  tions.**.** ^The
300e0 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
300f0 5f 64 62 5f 68 61 6e 64 6c 65 28 29 20 69 6e 74  _db_handle() int
30100 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
30110 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20   copy of.** the 
30120 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b  pointer to the [
30130 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
30140 69 6f 6e 5d 20 28 74 68 65 20 31 73 74 20 70 61  ion] (the 1st pa
30150 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74  rameter).** of t
30160 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  he [sqlite3_crea
30170 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a  te_function()].*
30180 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  * and [sqlite3_c
30190 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
301a0 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 61  ()] routines tha
301b0 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20  t originally.** 
301c0 72 65 67 69 73 74 65 72 65 64 20 74 68 65 20 61  registered the a
301d0 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e  pplication defin
301e0 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2f 0a  ed function..*/.
301f0 73 71 6c 69 74 65 33 20 2a 73 71 6c 69 74 65 33  sqlite3 *sqlite3
30200 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64  _context_db_hand
30210 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  le(sqlite3_conte
30220 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  xt*);../*.** CAP
30230 49 33 52 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20  I3REF: Function 
30240 41 75 78 69 6c 69 61 72 79 20 44 61 74 61 0a 2a  Auxiliary Data.*
30250 2a 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69  *.** The followi
30260 6e 67 20 74 77 6f 20 66 75 6e 63 74 69 6f 6e 73  ng two functions
30270 20 6d 61 79 20 62 65 20 75 73 65 64 20 62 79 20   may be used by 
30280 73 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74  scalar SQL funct
30290 69 6f 6e 73 20 74 6f 0a 2a 2a 20 61 73 73 6f 63  ions to.** assoc
302a0 69 61 74 65 20 6d 65 74 61 64 61 74 61 20 77 69  iate metadata wi
302b0 74 68 20 61 72 67 75 6d 65 6e 74 20 76 61 6c 75  th argument valu
302c0 65 73 2e 20 49 66 20 74 68 65 20 73 61 6d 65 20  es. If the same 
302d0 76 61 6c 75 65 20 69 73 20 70 61 73 73 65 64 20  value is passed 
302e0 74 6f 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 69  to.** multiple i
302f0 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68  nvocations of th
30300 65 20 73 61 6d 65 20 53 51 4c 20 66 75 6e 63 74  e same SQL funct
30310 69 6f 6e 20 64 75 72 69 6e 67 20 71 75 65 72 79  ion during query
30320 20 65 78 65 63 75 74 69 6f 6e 2c 20 75 6e 64 65   execution, unde
30330 72 0a 2a 2a 20 73 6f 6d 65 20 63 69 72 63 75 6d  r.** some circum
30340 73 74 61 6e 63 65 73 20 74 68 65 20 61 73 73 6f  stances the asso
30350 63 69 61 74 65 64 20 6d 65 74 61 64 61 74 61 20  ciated metadata 
30360 6d 61 79 20 62 65 20 70 72 65 73 65 72 76 65 64  may be preserved
30370 2e 20 54 68 69 73 20 6d 61 79 0a 2a 2a 20 62 65  . This may.** be
30380 20 75 73 65 64 2c 20 66 6f 72 20 65 78 61 6d 70   used, for examp
30390 6c 65 2c 20 74 6f 20 61 64 64 20 61 20 72 65 67  le, to add a reg
303a0 75 6c 61 72 2d 65 78 70 72 65 73 73 69 6f 6e 20  ular-expression 
303b0 6d 61 74 63 68 69 6e 67 20 73 63 61 6c 61 72 0a  matching scalar.
303c0 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65  ** function. The
303d0 20 63 6f 6d 70 69 6c 65 64 20 76 65 72 73 69 6f   compiled versio
303e0 6e 20 6f 66 20 74 68 65 20 72 65 67 75 6c 61 72  n of the regular
303f0 20 65 78 70 72 65 73 73 69 6f 6e 20 69 73 20 73   expression is s
30400 74 6f 72 65 64 20 61 73 0a 2a 2a 20 6d 65 74 61  tored as.** meta
30410 64 61 74 61 20 61 73 73 6f 63 69 61 74 65 64 20  data associated 
30420 77 69 74 68 20 74 68 65 20 53 51 4c 20 76 61 6c  with the SQL val
30430 75 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  ue passed as the
30440 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73 73   regular express
30450 69 6f 6e 0a 2a 2a 20 70 61 74 74 65 72 6e 2e 20  ion.** pattern. 
30460 20 54 68 65 20 63 6f 6d 70 69 6c 65 64 20 72 65   The compiled re
30470 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e  gular expression
30480 20 63 61 6e 20 62 65 20 72 65 75 73 65 64 20 6f   can be reused o
30490 6e 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e  n multiple.** in
304a0 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65  vocations of the
304b0 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 73   same function s
304c0 6f 20 74 68 61 74 20 74 68 65 20 6f 72 69 67 69  o that the origi
304d0 6e 61 6c 20 70 61 74 74 65 72 6e 20 73 74 72 69  nal pattern stri
304e0 6e 67 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 6e  ng.** does not n
304f0 65 65 64 20 74 6f 20 62 65 20 72 65 63 6f 6d 70  eed to be recomp
30500 69 6c 65 64 20 6f 6e 20 65 61 63 68 20 69 6e 76  iled on each inv
30510 6f 63 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e  ocation..**.** ^
30520 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  The sqlite3_get_
30530 61 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 66  auxdata() interf
30540 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ace returns a po
30550 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65 74  inter to the met
30560 61 64 61 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61  adata.** associa
30570 74 65 64 20 62 79 20 74 68 65 20 73 71 6c 69 74  ted by the sqlit
30580 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29  e3_set_auxdata()
30590 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 74   function with t
305a0 68 65 20 4e 74 68 20 61 72 67 75 6d 65 6e 74 0a  he Nth argument.
305b0 2a 2a 20 76 61 6c 75 65 20 74 6f 20 74 68 65 20  ** value to the 
305c0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
305d0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 5e 49  ned function. ^I
305e0 66 20 6e 6f 20 6d 65 74 61 64 61 74 61 20 68 61  f no metadata ha
305f0 73 20 62 65 65 6e 20 65 76 65 72 0a 2a 2a 20 62  s been ever.** b
30600 65 65 6e 20 73 65 74 20 66 6f 72 20 74 68 65 20  een set for the 
30610 4e 74 68 20 61 72 67 75 6d 65 6e 74 20 6f 66 20  Nth argument of 
30620 74 68 65 20 66 75 6e 63 74 69 6f 6e 2c 20 6f 72  the function, or
30630 20 69 66 20 74 68 65 20 63 6f 72 72 65 73 70 6f   if the correspo
30640 6e 64 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f  nding.** functio
30650 6e 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20  n parameter has 
30660 63 68 61 6e 67 65 64 20 73 69 6e 63 65 20 74 68  changed since th
30670 65 20 6d 65 74 61 2d 64 61 74 61 20 77 61 73 20  e meta-data was 
30680 73 65 74 2c 0a 2a 2a 20 74 68 65 6e 20 73 71 6c  set,.** then sql
30690 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61  ite3_get_auxdata
306a0 28 29 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c  () returns a NUL
306b0 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  L pointer..**.**
306c0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 65   ^The sqlite3_se
306d0 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74 65  t_auxdata() inte
306e0 72 66 61 63 65 20 73 61 76 65 73 20 74 68 65 20  rface saves the 
306f0 6d 65 74 61 64 61 74 61 0a 2a 2a 20 70 6f 69 6e  metadata.** poin
30700 74 65 64 20 74 6f 20 62 79 20 69 74 73 20 33 72  ted to by its 3r
30710 64 20 70 61 72 61 6d 65 74 65 72 20 61 73 20 74  d parameter as t
30720 68 65 20 6d 65 74 61 64 61 74 61 20 66 6f 72 20  he metadata for 
30730 74 68 65 20 4e 2d 74 68 0a 2a 2a 20 61 72 67 75  the N-th.** argu
30740 6d 65 6e 74 20 6f 66 20 74 68 65 20 61 70 70 6c  ment of the appl
30750 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
30760 66 75 6e 63 74 69 6f 6e 2e 20 20 53 75 62 73 65  function.  Subse
30770 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74  quent.** calls t
30780 6f 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75  o sqlite3_get_au
30790 78 64 61 74 61 28 29 20 6d 69 67 68 74 20 72 65  xdata() might re
307a0 74 75 72 6e 20 74 68 69 73 20 64 61 74 61 2c 20  turn this data, 
307b0 69 66 20 69 74 20 68 61 73 0a 2a 2a 20 6e 6f 74  if it has.** not
307c0 20 62 65 65 6e 20 64 65 73 74 72 6f 79 65 64 2e   been destroyed.
307d0 0a 2a 2a 20 5e 49 66 20 69 74 20 69 73 20 6e 6f  .** ^If it is no
307e0 74 20 4e 55 4c 4c 2c 20 53 51 4c 69 74 65 20 77  t NULL, SQLite w
307f0 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20 64  ill invoke the d
30800 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 66 75 6e  estructor.** fun
30810 63 74 69 6f 6e 20 67 69 76 65 6e 20 62 79 20 74  ction given by t
30820 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72  he 4th parameter
30830 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f   to sqlite3_set_
30840 61 75 78 64 61 74 61 28 29 20 6f 6e 0a 2a 2a 20  auxdata() on.** 
30850 74 68 65 20 6d 65 74 61 64 61 74 61 20 77 68 65  the metadata whe
30860 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  n the correspond
30870 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 70 61 72  ing function par
30880 61 6d 65 74 65 72 20 63 68 61 6e 67 65 73 0a 2a  ameter changes.*
30890 2a 20 6f 72 20 77 68 65 6e 20 74 68 65 20 53 51  * or when the SQ
308a0 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70  L statement comp
308b0 6c 65 74 65 73 2c 20 77 68 69 63 68 65 76 65 72  letes, whichever
308c0 20 63 6f 6d 65 73 20 66 69 72 73 74 2e 0a 2a 2a   comes first..**
308d0 0a 2a 2a 20 53 51 4c 69 74 65 20 69 73 20 66 72  .** SQLite is fr
308e0 65 65 20 74 6f 20 63 61 6c 6c 20 74 68 65 20 64  ee to call the d
308f0 65 73 74 72 75 63 74 6f 72 20 61 6e 64 20 64 72  estructor and dr
30900 6f 70 20 6d 65 74 61 64 61 74 61 20 6f 6e 20 61  op metadata on a
30910 6e 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  ny.** parameter 
30920 6f 66 20 61 6e 79 20 66 75 6e 63 74 69 6f 6e 20  of any function 
30930 61 74 20 61 6e 79 20 74 69 6d 65 2e 20 20 5e 54  at any time.  ^T
30940 68 65 20 6f 6e 6c 79 20 67 75 61 72 61 6e 74 65  he only guarante
30950 65 20 69 73 20 74 68 61 74 0a 2a 2a 20 74 68 65  e is that.** the
30960 20 64 65 73 74 72 75 63 74 6f 72 20 77 69 6c 6c   destructor will
30970 20 62 65 20 63 61 6c 6c 65 64 20 62 65 66 6f 72   be called befor
30980 65 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 69  e the metadata i
30990 73 20 64 72 6f 70 70 65 64 2e 0a 2a 2a 0a 2a 2a  s dropped..**.**
309a0 20 5e 28 49 6e 20 70 72 61 63 74 69 63 65 2c 20   ^(In practice, 
309b0 6d 65 74 61 64 61 74 61 20 69 73 20 70 72 65 73  metadata is pres
309c0 65 72 76 65 64 20 62 65 74 77 65 65 6e 20 66 75  erved between fu
309d0 6e 63 74 69 6f 6e 20 63 61 6c 6c 73 20 66 6f 72  nction calls for
309e0 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 73 20  .** expressions 
309f0 74 68 61 74 20 61 72 65 20 63 6f 6e 73 74 61 6e  that are constan
30a00 74 20 61 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d  t at compile tim
30a10 65 2e 20 54 68 69 73 20 69 6e 63 6c 75 64 65 73  e. This includes
30a20 20 6c 69 74 65 72 61 6c 0a 2a 2a 20 76 61 6c 75   literal.** valu
30a30 65 73 20 61 6e 64 20 5b 70 61 72 61 6d 65 74 65  es and [paramete
30a40 72 73 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65  rs].)^.**.** The
30a50 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74  se routines must
30a60 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20   be called from 
30a70 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20  the same thread 
30a80 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20  in which.** the 
30a90 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  SQL function is 
30aa0 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64  running..*/.void
30ab0 20 2a 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75   *sqlite3_get_au
30ac0 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f  xdata(sqlite3_co
30ad0 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a  ntext*, int N);.
30ae0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 73 65 74  void sqlite3_set
30af0 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74 65 33  _auxdata(sqlite3
30b00 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e  _context*, int N
30b10 2c 20 76 6f 69 64 2a 2c 20 76 6f 69 64 20 28 2a  , void*, void (*
30b20 29 28 76 6f 69 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a  )(void*));.../*.
30b30 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e  ** CAPI3REF: Con
30b40 73 74 61 6e 74 73 20 44 65 66 69 6e 69 6e 67 20  stants Defining 
30b50 53 70 65 63 69 61 6c 20 44 65 73 74 72 75 63 74  Special Destruct
30b60 6f 72 20 42 65 68 61 76 69 6f 72 0a 2a 2a 0a 2a  or Behavior.**.*
30b70 2a 20 54 68 65 73 65 20 61 72 65 20 73 70 65 63  * These are spec
30b80 69 61 6c 20 76 61 6c 75 65 73 20 66 6f 72 20 74  ial values for t
30b90 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 74 68  he destructor th
30ba0 61 74 20 69 73 20 70 61 73 73 65 64 20 69 6e 20  at is passed in 
30bb0 61 73 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20  as the.** final 
30bc0 61 72 67 75 6d 65 6e 74 20 74 6f 20 72 6f 75 74  argument to rout
30bd0 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74  ines like [sqlit
30be0 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29  e3_result_blob()
30bf0 5d 2e 20 20 5e 49 66 20 74 68 65 20 64 65 73 74  ].  ^If the dest
30c00 72 75 63 74 6f 72 0a 2a 2a 20 61 72 67 75 6d 65  ructor.** argume
30c10 6e 74 20 69 73 20 53 51 4c 49 54 45 5f 53 54 41  nt is SQLITE_STA
30c20 54 49 43 2c 20 69 74 20 6d 65 61 6e 73 20 74 68  TIC, it means th
30c30 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 70  at the content p
30c40 6f 69 6e 74 65 72 20 69 73 20 63 6f 6e 73 74 61  ointer is consta
30c50 6e 74 0a 2a 2a 20 61 6e 64 20 77 69 6c 6c 20 6e  nt.** and will n
30c60 65 76 65 72 20 63 68 61 6e 67 65 2e 20 20 49 74  ever change.  It
30c70 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74   does not need t
30c80 6f 20 62 65 20 64 65 73 74 72 6f 79 65 64 2e 20  o be destroyed. 
30c90 20 5e 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f   ^The.** SQLITE_
30ca0 54 52 41 4e 53 49 45 4e 54 20 76 61 6c 75 65 20  TRANSIENT value 
30cb0 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 63  means that the c
30cc0 6f 6e 74 65 6e 74 20 77 69 6c 6c 20 6c 69 6b 65  ontent will like
30cd0 6c 79 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20  ly change in.** 
30ce0 74 68 65 20 6e 65 61 72 20 66 75 74 75 72 65 20  the near future 
30cf0 61 6e 64 20 74 68 61 74 20 53 51 4c 69 74 65 20  and that SQLite 
30d00 73 68 6f 75 6c 64 20 6d 61 6b 65 20 69 74 73 20  should make its 
30d10 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79  own private copy
30d20 20 6f 66 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65   of.** the conte
30d30 6e 74 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e  nt before return
30d40 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74  ing..**.** The t
30d50 79 70 65 64 65 66 20 69 73 20 6e 65 63 65 73 73  ypedef is necess
30d60 61 72 79 20 74 6f 20 77 6f 72 6b 20 61 72 6f 75  ary to work arou
30d70 6e 64 20 70 72 6f 62 6c 65 6d 73 20 69 6e 20 63  nd problems in c
30d80 65 72 74 61 69 6e 0a 2a 2a 20 43 2b 2b 20 63 6f  ertain.** C++ co
30d90 6d 70 69 6c 65 72 73 2e 20 20 53 65 65 20 74 69  mpilers.  See ti
30da0 63 6b 65 74 20 23 32 31 39 31 2e 0a 2a 2f 0a 74  cket #2191..*/.t
30db0 79 70 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71  ypedef void (*sq
30dc0 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72  lite3_destructor
30dd0 5f 74 79 70 65 29 28 76 6f 69 64 2a 29 3b 0a 23  _type)(void*);.#
30de0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54  define SQLITE_ST
30df0 41 54 49 43 20 20 20 20 20 20 28 28 73 71 6c 69  ATIC      ((sqli
30e00 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74  te3_destructor_t
30e10 79 70 65 29 30 29 0a 23 64 65 66 69 6e 65 20 53  ype)0).#define S
30e20 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 20  QLITE_TRANSIENT 
30e30 20 20 28 28 73 71 6c 69 74 65 33 5f 64 65 73 74    ((sqlite3_dest
30e40 72 75 63 74 6f 72 5f 74 79 70 65 29 2d 31 29 0a  ructor_type)-1).
30e50 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
30e60 20 53 65 74 74 69 6e 67 20 54 68 65 20 52 65 73   Setting The Res
30e70 75 6c 74 20 4f 66 20 41 6e 20 53 51 4c 20 46 75  ult Of An SQL Fu
30e80 6e 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 54 68 65  nction.**.** The
30e90 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
30ea0 75 73 65 64 20 62 79 20 74 68 65 20 78 46 75 6e  used by the xFun
30eb0 63 20 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c  c or xFinal call
30ec0 62 61 63 6b 73 20 74 68 61 74 0a 2a 2a 20 69 6d  backs that.** im
30ed0 70 6c 65 6d 65 6e 74 20 53 51 4c 20 66 75 6e 63  plement SQL func
30ee0 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67  tions and aggreg
30ef0 61 74 65 73 2e 20 20 53 65 65 0a 2a 2a 20 5b 73  ates.  See.** [s
30f00 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
30f10 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73  nction()] and [s
30f20 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
30f30 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 66  nction16()].** f
30f40 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e  or additional in
30f50 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  formation..**.**
30f60 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   These functions
30f70 20 77 6f 72 6b 20 76 65 72 79 20 6d 75 63 68 20   work very much 
30f80 6c 69 6b 65 20 74 68 65 20 5b 70 61 72 61 6d 65  like the [parame
30f90 74 65 72 20 62 69 6e 64 69 6e 67 5d 20 66 61 6d  ter binding] fam
30fa0 69 6c 79 20 6f 66 0a 2a 2a 20 66 75 6e 63 74 69  ily of.** functi
30fb0 6f 6e 73 20 75 73 65 64 20 74 6f 20 62 69 6e 64  ons used to bind
30fc0 20 76 61 6c 75 65 73 20 74 6f 20 68 6f 73 74 20   values to host 
30fd0 70 61 72 61 6d 65 74 65 72 73 20 69 6e 20 70 72  parameters in pr
30fe0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
30ff0 73 2e 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20 74  s..** Refer to t
31000 68 65 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65  he [SQL paramete
31010 72 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  r] documentation
31020 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20   for additional 
31030 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a  information..**.
31040 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
31050 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 20 69 6e  result_blob() in
31060 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65  terface sets the
31070 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20   result from.** 
31080 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  an application-d
31090 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
310a0 74 6f 20 62 65 20 74 68 65 20 42 4c 4f 42 20 77  to be the BLOB w
310b0 68 6f 73 65 20 63 6f 6e 74 65 6e 74 20 69 73 20  hose content is 
310c0 70 6f 69 6e 74 65 64 0a 2a 2a 20 74 6f 20 62 79  pointed.** to by
310d0 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
310e0 6d 65 74 65 72 20 61 6e 64 20 77 68 69 63 68 20  meter and which 
310f0 69 73 20 4e 20 62 79 74 65 73 20 6c 6f 6e 67 20  is N bytes long 
31100 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 0a 2a  where N is the.*
31110 2a 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  * third paramete
31120 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  r..**.** ^The sq
31130 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72  lite3_result_zer
31140 6f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66 61 63  oblob() interfac
31150 65 73 20 73 65 74 20 74 68 65 20 72 65 73 75 6c  es set the resul
31160 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c  t of.** the appl
31170 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
31180 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61  function to be a
31190 20 42 4c 4f 42 20 63 6f 6e 74 61 69 6e 69 6e 67   BLOB containing
311a0 20 61 6c 6c 20 7a 65 72 6f 0a 2a 2a 20 62 79 74   all zero.** byt
311b0 65 73 20 61 6e 64 20 4e 20 62 79 74 65 73 20 69  es and N bytes i
311c0 6e 20 73 69 7a 65 2c 20 77 68 65 72 65 20 4e 20  n size, where N 
311d0 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  is the value of 
311e0 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
311f0 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  r..**.** ^The sq
31200 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75  lite3_result_dou
31210 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  ble() interface 
31220 73 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 20  sets the result 
31230 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69  from.** an appli
31240 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
31250 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20  unction to be a 
31260 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76  floating point v
31270 61 6c 75 65 20 73 70 65 63 69 66 69 65 64 0a 2a  alue specified.*
31280 2a 20 62 79 20 69 74 73 20 32 6e 64 20 61 72 67  * by its 2nd arg
31290 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ument..**.** ^Th
312a0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
312b0 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71 6c  _error() and sql
312c0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
312d0 72 31 36 28 29 20 66 75 6e 63 74 69 6f 6e 73 0a  r16() functions.
312e0 2a 2a 20 63 61 75 73 65 20 74 68 65 20 69 6d 70  ** cause the imp
312f0 6c 65 6d 65 6e 74 65 64 20 53 51 4c 20 66 75 6e  lemented SQL fun
31300 63 74 69 6f 6e 20 74 6f 20 74 68 72 6f 77 20 61  ction to throw a
31310 6e 20 65 78 63 65 70 74 69 6f 6e 2e 0a 2a 2a 20  n exception..** 
31320 5e 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65  ^SQLite uses the
31330 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 64 20   string pointed 
31340 74 6f 20 62 79 20 74 68 65 0a 2a 2a 20 32 6e 64  to by the.** 2nd
31350 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 73 71   parameter of sq
31360 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
31370 6f 72 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  or() or sqlite3_
31380 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29  result_error16()
31390 0a 2a 2a 20 61 73 20 74 68 65 20 74 65 78 74 20  .** as the text 
313a0 6f 66 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73  of an error mess
313b0 61 67 65 2e 20 20 5e 53 51 4c 69 74 65 20 69 6e  age.  ^SQLite in
313c0 74 65 72 70 72 65 74 73 20 74 68 65 20 65 72 72  terprets the err
313d0 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 73 74  or.** message st
313e0 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74 65  ring from sqlite
313f0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
31400 20 61 73 20 55 54 46 2d 38 2e 20 5e 53 51 4c 69   as UTF-8. ^SQLi
31410 74 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 73  te.** interprets
31420 20 74 68 65 20 73 74 72 69 6e 67 20 66 72 6f 6d   the string from
31430 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
31440 65 72 72 6f 72 31 36 28 29 20 61 73 20 55 54 46  error16() as UTF
31450 2d 31 36 20 69 6e 20 6e 61 74 69 76 65 0a 2a 2a  -16 in native.**
31460 20 62 79 74 65 20 6f 72 64 65 72 2e 20 20 5e 49   byte order.  ^I
31470 66 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  f the third para
31480 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
31490 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a  _result_error().
314a0 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  ** or sqlite3_re
314b0 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 69  sult_error16() i
314c0 73 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20  s negative then 
314d0 53 51 4c 69 74 65 20 74 61 6b 65 73 20 61 73 20  SQLite takes as 
314e0 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73  the error.** mes
314f0 73 61 67 65 20 61 6c 6c 20 74 65 78 74 20 75 70  sage all text up
31500 20 74 68 72 6f 75 67 68 20 74 68 65 20 66 69 72   through the fir
31510 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74 65  st zero characte
31520 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 74 68  r..** ^If the th
31530 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
31540 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
31550 65 72 72 6f 72 28 29 20 6f 72 0a 2a 2a 20 73 71  error() or.** sq
31560 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
31570 6f 72 31 36 28 29 20 69 73 20 6e 6f 6e 2d 6e 65  or16() is non-ne
31580 67 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69  gative then SQLi
31590 74 65 20 74 61 6b 65 73 20 74 68 61 74 20 6d 61  te takes that ma
315a0 6e 79 0a 2a 2a 20 62 79 74 65 73 20 28 6e 6f 74  ny.** bytes (not
315b0 20 63 68 61 72 61 63 74 65 72 73 29 20 66 72 6f   characters) fro
315c0 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65  m the 2nd parame
315d0 74 65 72 20 61 73 20 74 68 65 20 65 72 72 6f 72  ter as the error
315e0 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 20 5e 54 68   message..** ^Th
315f0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
31600 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71 6c  _error() and sql
31610 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
31620 72 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65  r16().** routine
31630 73 20 6d 61 6b 65 20 61 20 70 72 69 76 61 74 65  s make a private
31640 20 63 6f 70 79 20 6f 66 20 74 68 65 20 65 72 72   copy of the err
31650 6f 72 20 6d 65 73 73 61 67 65 20 74 65 78 74 20  or message text 
31660 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 79 20 72  before.** they r
31670 65 74 75 72 6e 2e 20 20 48 65 6e 63 65 2c 20 74  eturn.  Hence, t
31680 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74  he calling funct
31690 69 6f 6e 20 63 61 6e 20 64 65 61 6c 6c 6f 63 61  ion can dealloca
316a0 74 65 20 6f 72 0a 2a 2a 20 6d 6f 64 69 66 79 20  te or.** modify 
316b0 74 68 65 20 74 65 78 74 20 61 66 74 65 72 20 74  the text after t
316c0 68 65 79 20 72 65 74 75 72 6e 20 77 69 74 68 6f  hey return witho
316d0 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e 54 68 65  ut harm..** ^The
316e0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
316f0 65 72 72 6f 72 5f 63 6f 64 65 28 29 20 66 75 6e  error_code() fun
31700 63 74 69 6f 6e 20 63 68 61 6e 67 65 73 20 74 68  ction changes th
31710 65 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20  e error code.** 
31720 72 65 74 75 72 6e 65 64 20 62 79 20 53 51 4c 69  returned by SQLi
31730 74 65 20 61 73 20 61 20 72 65 73 75 6c 74 20 6f  te as a result o
31740 66 20 61 6e 20 65 72 72 6f 72 20 69 6e 20 61 20  f an error in a 
31750 66 75 6e 63 74 69 6f 6e 2e 20 20 5e 42 79 20 64  function.  ^By d
31760 65 66 61 75 6c 74 2c 0a 2a 2a 20 74 68 65 20 65  efault,.** the e
31770 72 72 6f 72 20 63 6f 64 65 20 69 73 20 53 51 4c  rror code is SQL
31780 49 54 45 5f 45 52 52 4f 52 2e 20 20 5e 41 20 73  ITE_ERROR.  ^A s
31790 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74  ubsequent call t
317a0 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  o sqlite3_result
317b0 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73  _error().** or s
317c0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
317d0 72 6f 72 31 36 28 29 20 72 65 73 65 74 73 20 74  ror16() resets t
317e0 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20 74 6f  he error code to
317f0 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 0a 2a   SQLITE_ERROR..*
31800 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
31810 33 5f 72 65 73 75 6c 74 5f 74 6f 6f 62 69 67 28  3_result_toobig(
31820 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73  ) interface caus
31830 65 73 20 53 51 4c 69 74 65 20 74 6f 20 74 68 72  es SQLite to thr
31840 6f 77 20 61 6e 20 65 72 72 6f 72 0a 2a 2a 20 69  ow an error.** i
31850 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74 20 61  ndicating that a
31860 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20   string or BLOB 
31870 69 73 20 74 6f 6f 20 6c 6f 6e 67 20 74 6f 20 72  is too long to r
31880 65 70 72 65 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  epresent..**.** 
31890 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
318a0 75 6c 74 5f 6e 6f 6d 65 6d 28 29 20 69 6e 74 65  ult_nomem() inte
318b0 72 66 61 63 65 20 63 61 75 73 65 73 20 53 51 4c  rface causes SQL
318c0 69 74 65 20 74 6f 20 74 68 72 6f 77 20 61 6e 20  ite to throw an 
318d0 65 72 72 6f 72 0a 2a 2a 20 69 6e 64 69 63 61 74  error.** indicat
318e0 69 6e 67 20 74 68 61 74 20 61 20 6d 65 6d 6f 72  ing that a memor
318f0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69  y allocation fai
31900 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  led..**.** ^The 
31910 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69  sqlite3_result_i
31920 6e 74 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  nt() interface s
31930 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20 76  ets the return v
31940 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61  alue.** of the a
31950 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
31960 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
31970 65 20 74 68 65 20 33 32 2d 62 69 74 20 73 69 67  e the 32-bit sig
31980 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76  ned integer.** v
31990 61 6c 75 65 20 67 69 76 65 6e 20 69 6e 20 74 68  alue given in th
319a0 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a  e 2nd argument..
319b0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
319c0 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 29 20 69  result_int64() i
319d0 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68  nterface sets th
319e0 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a  e return value.*
319f0 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61  * of the applica
31a00 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
31a10 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20  ction to be the 
31a20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e  64-bit signed in
31a30 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67  teger.** value g
31a40 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 20  iven in the 2nd 
31a50 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  argument..**.** 
31a60 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
31a70 75 6c 74 5f 6e 75 6c 6c 28 29 20 69 6e 74 65 72  ult_null() inter
31a80 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65  face sets the re
31a90 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66  turn value.** of
31aa0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
31ab0 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
31ac0 6e 20 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a  n to be NULL..**
31ad0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
31ae0 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 29 2c 20  _result_text(), 
31af0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
31b00 65 78 74 31 36 28 29 2c 0a 2a 2a 20 73 71 6c 69  ext16(),.** sqli
31b10 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
31b20 36 6c 65 28 29 2c 20 61 6e 64 20 73 71 6c 69 74  6le(), and sqlit
31b30 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
31b40 62 65 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a  be() interfaces.
31b50 2a 2a 20 73 65 74 20 74 68 65 20 72 65 74 75 72  ** set the retur
31b60 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 61  n value of the a
31b70 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
31b80 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
31b90 65 0a 2a 2a 20 61 20 74 65 78 74 20 73 74 72 69  e.** a text stri
31ba0 6e 67 20 77 68 69 63 68 20 69 73 20 72 65 70 72  ng which is repr
31bb0 65 73 65 6e 74 65 64 20 61 73 20 55 54 46 2d 38  esented as UTF-8
31bc0 2c 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20  , UTF-16 native 
31bd0 62 79 74 65 20 6f 72 64 65 72 2c 0a 2a 2a 20 55  byte order,.** U
31be0 54 46 2d 31 36 20 6c 69 74 74 6c 65 20 65 6e 64  TF-16 little end
31bf0 69 61 6e 2c 20 6f 72 20 55 54 46 2d 31 36 20 62  ian, or UTF-16 b
31c00 69 67 20 65 6e 64 69 61 6e 2c 20 72 65 73 70 65  ig endian, respe
31c10 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 53 51 4c  ctively..** ^SQL
31c20 69 74 65 20 74 61 6b 65 73 20 74 68 65 20 74 65  ite takes the te
31c30 78 74 20 72 65 73 75 6c 74 20 66 72 6f 6d 20 74  xt result from t
31c40 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 66  he application f
31c50 72 6f 6d 0a 2a 2a 20 74 68 65 20 32 6e 64 20 70  rom.** the 2nd p
31c60 61 72 61 6d 65 74 65 72 20 6f 66 20 74 68 65 20  arameter of the 
31c70 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
31c80 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 2e  ext* interfaces.
31c90 0a 2a 2a 20 5e 49 66 20 74 68 65 20 33 72 64 20  .** ^If the 3rd 
31ca0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
31cb0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
31cc0 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73  text* interfaces
31cd0 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69 76 65 2c  .** is negative,
31ce0 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b   then SQLite tak
31cf0 65 73 20 72 65 73 75 6c 74 20 74 65 78 74 20 66  es result text f
31d00 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61  rom the 2nd para
31d10 6d 65 74 65 72 0a 2a 2a 20 74 68 72 6f 75 67 68  meter.** through
31d20 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20   the first zero 
31d30 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 5e 49  character..** ^I
31d40 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65  f the 3rd parame
31d50 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ter to the sqlit
31d60 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20  e3_result_text* 
31d70 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73  interfaces.** is
31d80 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74   non-negative, t
31d90 68 65 6e 20 61 73 20 6d 61 6e 79 20 62 79 74 65  hen as many byte
31da0 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74 65 72  s (not character
31db0 73 29 20 6f 66 20 74 68 65 20 74 65 78 74 0a 2a  s) of the text.*
31dc0 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20  * pointed to by 
31dd0 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
31de0 72 20 61 72 65 20 74 61 6b 65 6e 20 61 73 20 74  r are taken as t
31df0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
31e00 65 66 69 6e 65 64 0a 2a 2a 20 66 75 6e 63 74 69  efined.** functi
31e10 6f 6e 20 72 65 73 75 6c 74 2e 20 20 49 66 20 74  on result.  If t
31e20 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  he 3rd parameter
31e30 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65   is non-negative
31e40 2c 20 74 68 65 6e 20 69 74 0a 2a 2a 20 6d 75 73  , then it.** mus
31e50 74 20 62 65 20 74 68 65 20 62 79 74 65 20 6f 66  t be the byte of
31e60 66 73 65 74 20 69 6e 74 6f 20 74 68 65 20 73 74  fset into the st
31e70 72 69 6e 67 20 77 68 65 72 65 20 74 68 65 20 4e  ring where the N
31e80 55 4c 20 74 65 72 6d 69 6e 61 74 6f 72 20 77 6f  UL terminator wo
31e90 75 6c 64 0a 2a 2a 20 61 70 70 65 61 72 20 69 66  uld.** appear if
31ea0 20 74 68 65 20 73 74 72 69 6e 67 20 77 68 65 72   the string wher
31eb0 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 65 64  e NUL terminated
31ec0 2e 20 20 49 66 20 61 6e 79 20 4e 55 4c 20 63 68  .  If any NUL ch
31ed0 61 72 61 63 74 65 72 73 20 6f 63 63 75 72 0a 2a  aracters occur.*
31ee0 2a 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67 20  * in the string 
31ef0 61 74 20 61 20 62 79 74 65 20 6f 66 66 73 65 74  at a byte offset
31f00 20 74 68 61 74 20 69 73 20 6c 65 73 73 20 74 68   that is less th
31f10 61 6e 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  an the value of 
31f20 74 68 65 20 33 72 64 0a 2a 2a 20 70 61 72 61 6d  the 3rd.** param
31f30 65 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20 72  eter, then the r
31f40 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 20  esulting string 
31f50 77 69 6c 6c 20 63 6f 6e 74 61 69 6e 20 65 6d 62  will contain emb
31f60 65 64 64 65 64 20 4e 55 4c 73 20 61 6e 64 20 74  edded NULs and t
31f70 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 6f 66 20  he.** result of 
31f80 65 78 70 72 65 73 73 69 6f 6e 73 20 6f 70 65 72  expressions oper
31f90 61 74 69 6e 67 20 6f 6e 20 73 74 72 69 6e 67 73  ating on strings
31fa0 20 77 69 74 68 20 65 6d 62 65 64 64 65 64 20 4e   with embedded N
31fb0 55 4c 73 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ULs is undefined
31fc0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68  ..** ^If the 4th
31fd0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
31fe0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
31ff0 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65  _text* interface
32000 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f  s.** or sqlite3_
32010 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 61  result_blob is a
32020 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65   non-NULL pointe
32030 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 63  r, then SQLite c
32040 61 6c 6c 73 20 74 68 61 74 0a 2a 2a 20 66 75 6e  alls that.** fun
32050 63 74 69 6f 6e 20 61 73 20 74 68 65 20 64 65 73  ction as the des
32060 74 72 75 63 74 6f 72 20 6f 6e 20 74 68 65 20 74  tructor on the t
32070 65 78 74 20 6f 72 20 42 4c 4f 42 20 72 65 73 75  ext or BLOB resu
32080 6c 74 20 77 68 65 6e 20 69 74 20 68 61 73 0a 2a  lt when it has.*
32090 2a 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67  * finished using
320a0 20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a   that result..**
320b0 20 5e 49 66 20 74 68 65 20 34 74 68 20 70 61 72   ^If the 4th par
320c0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71  ameter to the sq
320d0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
320e0 74 2a 20 69 6e 74 65 72 66 61 63 65 73 20 6f 72  t* interfaces or
320f0 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72   to.** sqlite3_r
32100 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68  esult_blob is th
32110 65 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74 61  e special consta
32120 6e 74 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43  nt SQLITE_STATIC
32130 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 0a 2a 2a  , then SQLite.**
32140 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68   assumes that th
32150 65 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 20 72  e text or BLOB r
32160 65 73 75 6c 74 20 69 73 20 69 6e 20 63 6f 6e 73  esult is in cons
32170 74 61 6e 74 20 73 70 61 63 65 20 61 6e 64 20 64  tant space and d
32180 6f 65 73 20 6e 6f 74 0a 2a 2a 20 63 6f 70 79 20  oes not.** copy 
32190 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74  the content of t
321a0 68 65 20 70 61 72 61 6d 65 74 65 72 20 6e 6f 72  he parameter nor
321b0 20 63 61 6c 6c 20 61 20 64 65 73 74 72 75 63 74   call a destruct
321c0 6f 72 20 6f 6e 20 74 68 65 20 63 6f 6e 74 65 6e  or on the conten
321d0 74 0a 2a 2a 20 77 68 65 6e 20 69 74 20 68 61 73  t.** when it has
321e0 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20   finished using 
321f0 74 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20  that result..** 
32200 5e 49 66 20 74 68 65 20 34 74 68 20 70 61 72 61  ^If the 4th para
32210 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c  meter to the sql
32220 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
32230 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  * interfaces.** 
32240 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  or sqlite3_resul
32250 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73 70  t_blob is the sp
32260 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53  ecial constant S
32270 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 0a  QLITE_TRANSIENT.
32280 2a 2a 20 74 68 65 6e 20 53 51 4c 69 74 65 20 6d  ** then SQLite m
32290 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74  akes a copy of t
322a0 68 65 20 72 65 73 75 6c 74 20 69 6e 74 6f 20 73  he result into s
322b0 70 61 63 65 20 6f 62 74 61 69 6e 65 64 20 66 72  pace obtained fr
322c0 6f 6d 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69  om.** from [sqli
322d0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 62 65  te3_malloc()] be
322e0 66 6f 72 65 20 69 74 20 72 65 74 75 72 6e 73 2e  fore it returns.
322f0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
32300 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65  te3_result_value
32310 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74  () interface set
32320 73 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 0a  s the result of.
32330 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ** the applicati
32340 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
32350 69 6f 6e 20 74 6f 20 62 65 20 61 20 63 6f 70 79  ion to be a copy
32360 20 74 68 65 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65   the.** [unprote
32370 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
32380 75 65 5d 20 6f 62 6a 65 63 74 20 73 70 65 63 69  ue] object speci
32390 66 69 65 64 20 62 79 20 74 68 65 20 32 6e 64 20  fied by the 2nd 
323a0 70 61 72 61 6d 65 74 65 72 2e 20 20 5e 54 68 65  parameter.  ^The
323b0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75  .** sqlite3_resu
323c0 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e 74 65 72  lt_value() inter
323d0 66 61 63 65 20 6d 61 6b 65 73 20 61 20 63 6f 70  face makes a cop
323e0 79 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  y of the [sqlite
323f0 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 73 6f 20 74  3_value].** so t
32400 68 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33  hat the [sqlite3
32410 5f 76 61 6c 75 65 5d 20 73 70 65 63 69 66 69 65  _value] specifie
32420 64 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74  d in the paramet
32430 65 72 20 6d 61 79 20 63 68 61 6e 67 65 20 6f 72  er may change or
32440 0a 2a 2a 20 62 65 20 64 65 61 6c 6c 6f 63 61 74  .** be deallocat
32450 65 64 20 61 66 74 65 72 20 73 71 6c 69 74 65 33  ed after sqlite3
32460 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20  _result_value() 
32470 72 65 74 75 72 6e 73 20 77 69 74 68 6f 75 74 20  returns without 
32480 68 61 72 6d 2e 0a 2a 2a 20 5e 41 20 5b 70 72 6f  harm..** ^A [pro
32490 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
324a0 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 6d 61 79  alue] object may
324b0 20 61 6c 77 61 79 73 20 62 65 20 75 73 65 64 20   always be used 
324c0 77 68 65 72 65 20 61 6e 0a 2a 2a 20 5b 75 6e 70  where an.** [unp
324d0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
324e0 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 69  _value] object i
324f0 73 20 72 65 71 75 69 72 65 64 2c 20 73 6f 20 65  s required, so e
32500 69 74 68 65 72 0a 2a 2a 20 6b 69 6e 64 20 6f 66  ither.** kind of
32510 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d   [sqlite3_value]
32520 20 6f 62 6a 65 63 74 20 63 61 6e 20 62 65 20 75   object can be u
32530 73 65 64 20 77 69 74 68 20 74 68 69 73 20 69 6e  sed with this in
32540 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 49  terface..**.** I
32550 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
32560 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d   are called from
32570 20 77 69 74 68 69 6e 20 74 68 65 20 64 69 66 66   within the diff
32580 65 72 65 6e 74 20 74 68 72 65 61 64 0a 2a 2a 20  erent thread.** 
32590 74 68 61 6e 20 74 68 65 20 6f 6e 65 20 63 6f 6e  than the one con
325a0 74 61 69 6e 69 6e 67 20 74 68 65 20 61 70 70 6c  taining the appl
325b0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
325c0 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 72 65  function that re
325d0 63 65 69 76 65 64 0a 2a 2a 20 74 68 65 20 5b 73  ceived.** the [s
325e0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5d 20  qlite3_context] 
325f0 70 6f 69 6e 74 65 72 2c 20 74 68 65 20 72 65 73  pointer, the res
32600 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e  ults are undefin
32610 65 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69  ed..*/.void sqli
32620 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28  te3_result_blob(
32630 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
32640 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
32650 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64  nt, void(*)(void
32660 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  *));.void sqlite
32670 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28  3_result_double(
32680 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
32690 2c 20 64 6f 75 62 6c 65 29 3b 0a 76 6f 69 64 20  , double);.void 
326a0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
326b0 72 72 6f 72 28 73 71 6c 69 74 65 33 5f 63 6f 6e  rror(sqlite3_con
326c0 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61  text*, const cha
326d0 72 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73  r*, int);.void s
326e0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
326f0 72 6f 72 31 36 28 73 71 6c 69 74 65 33 5f 63 6f  ror16(sqlite3_co
32700 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f  ntext*, const vo
32710 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20  id*, int);.void 
32720 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
32730 72 72 6f 72 5f 74 6f 6f 62 69 67 28 73 71 6c 69  rror_toobig(sqli
32740 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76  te3_context*);.v
32750 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
32760 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 73  lt_error_nomem(s
32770 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
32780 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
32790 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65  esult_error_code
327a0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
327b0 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71  *, int);.void sq
327c0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74  lite3_result_int
327d0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
327e0 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71  *, int);.void sq
327f0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74  lite3_result_int
32800 36 34 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  64(sqlite3_conte
32810 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  xt*, sqlite3_int
32820 36 34 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  64);.void sqlite
32830 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 73 71  3_result_null(sq
32840 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b  lite3_context*);
32850 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
32860 73 75 6c 74 5f 74 65 78 74 28 73 71 6c 69 74 65  sult_text(sqlite
32870 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
32880 74 20 63 68 61 72 2a 2c 20 69 6e 74 2c 20 76 6f  t char*, int, vo
32890 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76  id(*)(void*));.v
328a0 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
328b0 6c 74 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65  lt_text16(sqlite
328c0 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
328d0 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f  t void*, int, vo
328e0 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76  id(*)(void*));.v
328f0 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
32900 6c 74 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69  lt_text16le(sqli
32910 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f  te3_context*, co
32920 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76  nst void*, int,v
32930 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
32940 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
32950 75 6c 74 5f 74 65 78 74 31 36 62 65 28 73 71 6c  ult_text16be(sql
32960 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63  ite3_context*, c
32970 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c  onst void*, int,
32980 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
32990 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
329a0 73 75 6c 74 5f 76 61 6c 75 65 28 73 71 6c 69 74  sult_value(sqlit
329b0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c  e3_context*, sql
329c0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 76 6f  ite3_value*);.vo
329d0 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
329e0 74 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74  t_zeroblob(sqlit
329f0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74  e3_context*, int
32a00 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49   n);../*.** CAPI
32a10 33 52 45 46 3a 20 44 65 66 69 6e 65 20 4e 65 77  3REF: Define New
32a20 20 43 6f 6c 6c 61 74 69 6e 67 20 53 65 71 75 65   Collating Seque
32a30 6e 63 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  nces.**.** ^Thes
32a40 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 64 64 2c  e functions add,
32a50 20 72 65 6d 6f 76 65 2c 20 6f 72 20 6d 6f 64 69   remove, or modi
32a60 66 79 20 61 20 5b 63 6f 6c 6c 61 74 69 6f 6e 5d  fy a [collation]
32a70 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77   associated.** w
32a80 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73  ith the [databas
32a90 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70  e connection] sp
32aa0 65 63 69 66 69 65 64 20 61 73 20 74 68 65 20 66  ecified as the f
32ab0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  irst argument..*
32ac0 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f  *.** ^The name o
32ad0 66 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20  f the collation 
32ae0 69 73 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e  is a UTF-8 strin
32af0 67 0a 2a 2a 20 66 6f 72 20 73 71 6c 69 74 65 33  g.** for sqlite3
32b00 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
32b10 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  n() and sqlite3_
32b20 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
32b30 5f 76 32 28 29 0a 2a 2a 20 61 6e 64 20 61 20 55  _v2().** and a U
32b40 54 46 2d 31 36 20 73 74 72 69 6e 67 20 69 6e 20  TF-16 string in 
32b50 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
32b60 72 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72  r for sqlite3_cr
32b70 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36  eate_collation16
32b80 28 29 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6f  ()..** ^Collatio
32b90 6e 20 6e 61 6d 65 73 20 74 68 61 74 20 63 6f 6d  n names that com
32ba0 70 61 72 65 20 65 71 75 61 6c 20 61 63 63 6f 72  pare equal accor
32bb0 64 69 6e 67 20 74 6f 20 5b 73 71 6c 69 74 65 33  ding to [sqlite3
32bc0 5f 73 74 72 6e 69 63 6d 70 28 29 5d 20 61 72 65  _strnicmp()] are
32bd0 0a 2a 2a 20 63 6f 6e 73 69 64 65 72 65 64 20 74  .** considered t
32be0 6f 20 62 65 20 74 68 65 20 73 61 6d 65 20 6e 61  o be the same na
32bf0 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  me..**.** ^(The 
32c00 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 28  third argument (
32c10 65 54 65 78 74 52 65 70 29 20 6d 75 73 74 20 62  eTextRep) must b
32c20 65 20 6f 6e 65 20 6f 66 20 74 68 65 20 63 6f 6e  e one of the con
32c30 73 74 61 6e 74 73 3a 0a 2a 2a 20 3c 75 6c 3e 0a  stants:.** <ul>.
32c40 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
32c50 55 54 46 38 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b  UTF8],.** <li> [
32c60 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c  SQLITE_UTF16LE],
32c70 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
32c80 5f 55 54 46 31 36 42 45 5d 2c 0a 2a 2a 20 3c 6c  _UTF16BE],.** <l
32c90 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  i> [SQLITE_UTF16
32ca0 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  ], or.** <li> [S
32cb0 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47  QLITE_UTF16_ALIG
32cc0 4e 45 44 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e  NED]..** </ul>)^
32cd0 0a 2a 2a 20 5e 54 68 65 20 65 54 65 78 74 52 65  .** ^The eTextRe
32ce0 70 20 61 72 67 75 6d 65 6e 74 20 64 65 74 65 72  p argument deter
32cf0 6d 69 6e 65 73 20 74 68 65 20 65 6e 63 6f 64 69  mines the encodi
32d00 6e 67 20 6f 66 20 73 74 72 69 6e 67 73 20 70 61  ng of strings pa
32d10 73 73 65 64 0a 2a 2a 20 74 6f 20 74 68 65 20 63  ssed.** to the c
32d20 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
32d30 6e 20 63 61 6c 6c 62 61 63 6b 2c 20 78 43 61 6c  n callback, xCal
32d40 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 54 68 65 20 5b  lback..** ^The [
32d50 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 20 61 6e  SQLITE_UTF16] an
32d60 64 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5f  d [SQLITE_UTF16_
32d70 41 4c 49 47 4e 45 44 5d 20 76 61 6c 75 65 73 20  ALIGNED] values 
32d80 66 6f 72 20 65 54 65 78 74 52 65 70 0a 2a 2a 20  for eTextRep.** 
32d90 66 6f 72 63 65 20 73 74 72 69 6e 67 73 20 74 6f  force strings to
32da0 20 62 65 20 55 54 46 31 36 20 77 69 74 68 20 6e   be UTF16 with n
32db0 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
32dc0 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  ..** ^The [SQLIT
32dd0 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d  E_UTF16_ALIGNED]
32de0 20 76 61 6c 75 65 20 66 6f 72 20 65 54 65 78 74   value for eText
32df0 52 65 70 20 66 6f 72 63 65 73 20 73 74 72 69 6e  Rep forces strin
32e00 67 73 20 74 6f 20 62 65 67 69 6e 0a 2a 2a 20 6f  gs to begin.** o
32e10 6e 20 61 6e 20 65 76 65 6e 20 62 79 74 65 20 61  n an even byte a
32e20 64 64 72 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ddress..**.** ^T
32e30 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65  he fourth argume
32e40 6e 74 2c 20 70 41 72 67 2c 20 69 73 20 61 6e 20  nt, pArg, is an 
32e50 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61  application data
32e60 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 69 73   pointer that is
32e70 20 70 61 73 73 65 64 0a 2a 2a 20 74 68 72 6f 75   passed.** throu
32e80 67 68 20 61 73 20 74 68 65 20 66 69 72 73 74 20  gh as the first 
32e90 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
32ea0 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
32eb0 6f 6e 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a  on callback..**.
32ec0 2a 2a 20 5e 54 68 65 20 66 69 66 74 68 20 61 72  ** ^The fifth ar
32ed0 67 75 6d 65 6e 74 2c 20 78 43 61 6c 6c 62 61 63  gument, xCallbac
32ee0 6b 2c 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  k, is a pointer 
32ef0 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67  to the collating
32f00 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 5e 4d   function..** ^M
32f10 75 6c 74 69 70 6c 65 20 63 6f 6c 6c 61 74 69 6e  ultiple collatin
32f20 67 20 66 75 6e 63 74 69 6f 6e 73 20 63 61 6e 20  g functions can 
32f30 62 65 20 72 65 67 69 73 74 65 72 65 64 20 75 73  be registered us
32f40 69 6e 67 20 74 68 65 20 73 61 6d 65 20 6e 61 6d  ing the same nam
32f50 65 20 62 75 74 0a 2a 2a 20 77 69 74 68 20 64 69  e but.** with di
32f60 66 66 65 72 65 6e 74 20 65 54 65 78 74 52 65 70  fferent eTextRep
32f70 20 70 61 72 61 6d 65 74 65 72 73 20 61 6e 64 20   parameters and 
32f80 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20  SQLite will use 
32f90 77 68 69 63 68 65 76 65 72 0a 2a 2a 20 66 75 6e  whichever.** fun
32fa0 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 74  ction requires t
32fb0 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20  he least amount 
32fc0 6f 66 20 64 61 74 61 20 74 72 61 6e 73 66 6f 72  of data transfor
32fd0 6d 61 74 69 6f 6e 2e 0a 2a 2a 20 5e 49 66 20 74  mation..** ^If t
32fe0 68 65 20 78 43 61 6c 6c 62 61 63 6b 20 61 72 67  he xCallback arg
32ff0 75 6d 65 6e 74 20 69 73 20 4e 55 4c 4c 20 74 68  ument is NULL th
33000 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67  en the collating
33010 20 66 75 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a 20   function is.** 
33020 64 65 6c 65 74 65 64 2e 20 20 5e 57 68 65 6e 20  deleted.  ^When 
33030 61 6c 6c 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75  all collating fu
33040 6e 63 74 69 6f 6e 73 20 68 61 76 69 6e 67 20 74  nctions having t
33050 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 61 72 65  he same name are
33060 20 64 65 6c 65 74 65 64 2c 0a 2a 2a 20 74 68 61   deleted,.** tha
33070 74 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 20 6e  t collation is n
33080 6f 20 6c 6f 6e 67 65 72 20 75 73 61 62 6c 65 2e  o longer usable.
33090 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 6f 6c 6c  .**.** ^The coll
330a0 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63  ating function c
330b0 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
330c0 65 64 20 77 69 74 68 20 61 20 63 6f 70 79 20 6f  ed with a copy o
330d0 66 20 74 68 65 20 70 41 72 67 20 0a 2a 2a 20 61  f the pArg .** a
330e0 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20  pplication data 
330f0 70 6f 69 6e 74 65 72 20 61 6e 64 20 77 69 74 68  pointer and with
33100 20 74 77 6f 20 73 74 72 69 6e 67 73 20 69 6e 20   two strings in 
33110 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 73 70 65  the encoding spe
33120 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 74 68 65  cified.** by the
33130 20 65 54 65 78 74 52 65 70 20 61 72 67 75 6d 65   eTextRep argume
33140 6e 74 2e 20 20 54 68 65 20 63 6f 6c 6c 61 74 69  nt.  The collati
33150 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74  ng function must
33160 20 72 65 74 75 72 6e 20 61 6e 0a 2a 2a 20 69 6e   return an.** in
33170 74 65 67 65 72 20 74 68 61 74 20 69 73 20 6e 65  teger that is ne
33180 67 61 74 69 76 65 2c 20 7a 65 72 6f 2c 20 6f 72  gative, zero, or
33190 20 70 6f 73 69 74 69 76 65 0a 2a 2a 20 69 66 20   positive.** if 
331a0 74 68 65 20 66 69 72 73 74 20 73 74 72 69 6e 67  the first string
331b0 20 69 73 20 6c 65 73 73 20 74 68 61 6e 2c 20 65   is less than, e
331c0 71 75 61 6c 20 74 6f 2c 20 6f 72 20 67 72 65 61  qual to, or grea
331d0 74 65 72 20 74 68 61 6e 20 74 68 65 20 73 65 63  ter than the sec
331e0 6f 6e 64 2c 0a 2a 2a 20 72 65 73 70 65 63 74 69  ond,.** respecti
331f0 76 65 6c 79 2e 20 20 41 20 63 6f 6c 6c 61 74 69  vely.  A collati
33200 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74  ng function must
33210 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 20 74   always return t
33220 68 65 20 73 61 6d 65 20 61 6e 73 77 65 72 0a 2a  he same answer.*
33230 2a 20 67 69 76 65 6e 20 74 68 65 20 73 61 6d 65  * given the same
33240 20 69 6e 70 75 74 73 2e 20 20 49 66 20 74 77 6f   inputs.  If two
33250 20 6f 72 20 6d 6f 72 65 20 63 6f 6c 6c 61 74 69   or more collati
33260 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65  ng functions are
33270 20 72 65 67 69 73 74 65 72 65 64 0a 2a 2a 20 74   registered.** t
33280 6f 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 6c 61  o the same colla
33290 74 69 6f 6e 20 6e 61 6d 65 20 28 75 73 69 6e 67  tion name (using
332a0 20 64 69 66 66 65 72 65 6e 74 20 65 54 65 78 74   different eText
332b0 52 65 70 20 76 61 6c 75 65 73 29 20 74 68 65 6e  Rep values) then
332c0 20 61 6c 6c 0a 2a 2a 20 6d 75 73 74 20 67 69 76   all.** must giv
332d0 65 20 61 6e 20 65 71 75 69 76 61 6c 65 6e 74 20  e an equivalent 
332e0 61 6e 73 77 65 72 20 77 68 65 6e 20 69 6e 76 6f  answer when invo
332f0 6b 65 64 20 77 69 74 68 20 65 71 75 69 76 61 6c  ked with equival
33300 65 6e 74 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20  ent strings..** 
33310 54 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75  The collating fu
33320 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6f 62 65 79  nction must obey
33330 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 70   the following p
33340 72 6f 70 65 72 74 69 65 73 20 66 6f 72 20 61 6c  roperties for al
33350 6c 0a 2a 2a 20 73 74 72 69 6e 67 73 20 41 2c 20  l.** strings A, 
33360 42 2c 20 61 6e 64 20 43 3a 0a 2a 2a 0a 2a 2a 20  B, and C:.**.** 
33370 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20  <ol>.** <li> If 
33380 41 3d 3d 42 20 74 68 65 6e 20 42 3d 3d 41 2e 0a  A==B then B==A..
33390 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 3d 3d 42 20  ** <li> If A==B 
333a0 61 6e 64 20 42 3d 3d 43 20 74 68 65 6e 20 41 3d  and B==C then A=
333b0 3d 43 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41  =C..** <li> If A
333c0 26 6c 74 3b 42 20 54 48 45 4e 20 42 26 67 74 3b  &lt;B THEN B&gt;
333d0 41 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 26  A..** <li> If A&
333e0 6c 74 3b 42 20 61 6e 64 20 42 26 6c 74 3b 43 20  lt;B and B&lt;C 
333f0 74 68 65 6e 20 41 26 6c 74 3b 43 2e 0a 2a 2a 20  then A&lt;C..** 
33400 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 61  </ol>.**.** If a
33410 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
33420 69 6f 6e 20 66 61 69 6c 73 20 61 6e 79 20 6f 66  ion fails any of
33430 20 74 68 65 20 61 62 6f 76 65 20 63 6f 6e 73 74   the above const
33440 72 61 69 6e 74 73 20 61 6e 64 20 74 68 61 74 0a  raints and that.
33450 2a 2a 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e  ** collating fun
33460 63 74 69 6f 6e 20 69 73 20 20 72 65 67 69 73 74  ction is  regist
33470 65 72 65 64 20 61 6e 64 20 75 73 65 64 2c 20 74  ered and used, t
33480 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
33490 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 69 73   of SQLite.** is
334a0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
334b0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63  * ^The sqlite3_c
334c0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  reate_collation_
334d0 76 32 28 29 20 77 6f 72 6b 73 20 6c 69 6b 65 20  v2() works like 
334e0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
334f0 6f 6c 6c 61 74 69 6f 6e 28 29 0a 2a 2a 20 77 69  ollation().** wi
33500 74 68 20 74 68 65 20 61 64 64 69 74 69 6f 6e 20  th the addition 
33510 74 68 61 74 20 74 68 65 20 78 44 65 73 74 72 6f  that the xDestro
33520 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  y callback is in
33530 76 6f 6b 65 64 20 6f 6e 20 70 41 72 67 20 77 68  voked on pArg wh
33540 65 6e 0a 2a 2a 20 74 68 65 20 63 6f 6c 6c 61 74  en.** the collat
33550 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  ing function is 
33560 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 5e 43 6f 6c  deleted..** ^Col
33570 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73  lating functions
33580 20 61 72 65 20 64 65 6c 65 74 65 64 20 77 68 65   are deleted whe
33590 6e 20 74 68 65 79 20 61 72 65 20 6f 76 65 72 72  n they are overr
335a0 69 64 64 65 6e 20 62 79 20 6c 61 74 65 72 0a 2a  idden by later.*
335b0 2a 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 63  * calls to the c
335c0 6f 6c 6c 61 74 69 6f 6e 20 63 72 65 61 74 69 6f  ollation creatio
335d0 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 77  n functions or w
335e0 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61  hen the.** [data
335f0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
33600 20 69 73 20 63 6c 6f 73 65 64 20 75 73 69 6e 67   is closed using
33610 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28   [sqlite3_close(
33620 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78  )]..**.** ^The x
33630 44 65 73 74 72 6f 79 20 63 61 6c 6c 62 61 63 6b  Destroy callback
33640 20 69 73 20 3c 75 3e 6e 6f 74 3c 2f 75 3e 20 63   is <u>not</u> c
33650 61 6c 6c 65 64 20 69 66 20 74 68 65 20 0a 2a 2a  alled if the .**
33660 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
33670 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 66  collation_v2() f
33680 75 6e 63 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20  unction fails.  
33690 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  Applications tha
336a0 74 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69  t invoke.** sqli
336b0 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
336c0 74 69 6f 6e 5f 76 32 28 29 20 77 69 74 68 20 61  tion_v2() with a
336d0 20 6e 6f 6e 2d 4e 55 4c 4c 20 78 44 65 73 74 72   non-NULL xDestr
336e0 6f 79 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75  oy argument shou
336f0 6c 64 20 0a 2a 2a 20 63 68 65 63 6b 20 74 68 65  ld .** check the
33700 20 72 65 74 75 72 6e 20 63 6f 64 65 20 61 6e 64   return code and
33710 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20   dispose of the 
33720 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61  application data
33730 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 68 65 6d   pointer.** them
33740 73 65 6c 76 65 73 20 72 61 74 68 65 72 20 74 68  selves rather th
33750 61 6e 20 65 78 70 65 63 74 69 6e 67 20 53 51 4c  an expecting SQL
33760 69 74 65 20 74 6f 20 64 65 61 6c 20 77 69 74 68  ite to deal with
33770 20 69 74 20 66 6f 72 20 74 68 65 6d 2e 0a 2a 2a   it for them..**
33780 20 54 68 69 73 20 69 73 20 64 69 66 66 65 72 65   This is differe
33790 6e 74 20 66 72 6f 6d 20 65 76 65 72 79 20 6f 74  nt from every ot
337a0 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72  her SQLite inter
337b0 66 61 63 65 2e 20 20 54 68 65 20 69 6e 63 6f 6e  face.  The incon
337c0 73 69 73 74 65 6e 63 79 20 0a 2a 2a 20 69 73 20  sistency .** is 
337d0 75 6e 66 6f 72 74 75 6e 61 74 65 20 62 75 74 20  unfortunate but 
337e0 63 61 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67 65  cannot be change
337f0 64 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69  d without breaki
33800 6e 67 20 62 61 63 6b 77 61 72 64 73 20 0a 2a 2a  ng backwards .**
33810 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a   compatibility..
33820 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
33830 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74   [sqlite3_collat
33840 69 6f 6e 5f 6e 65 65 64 65 64 28 29 5d 20 61 6e  ion_needed()] an
33850 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61  d [sqlite3_colla
33860 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 5d  tion_needed16()]
33870 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
33880 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
33890 6e 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a  n(.  sqlite3*, .
338a0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e    const char *zN
338b0 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78  ame, .  int eTex
338c0 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 20 2a 70  tRep, .  void *p
338d0 41 72 67 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d  Arg,.  int(*xCom
338e0 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c  pare)(void*,int,
338f0 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c  const void*,int,
33900 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a  const void*).);.
33910 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61  int sqlite3_crea
33920 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28  te_collation_v2(
33930 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20  .  sqlite3*, .  
33940 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
33950 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52  e, .  int eTextR
33960 65 70 2c 20 0a 20 20 76 6f 69 64 20 2a 70 41 72  ep, .  void *pAr
33970 67 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61  g,.  int(*xCompa
33980 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  re)(void*,int,co
33990 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  nst void*,int,co
339a0 6e 73 74 20 76 6f 69 64 2a 29 2c 0a 20 20 76 6f  nst void*),.  vo
339b0 69 64 28 2a 78 44 65 73 74 72 6f 79 29 28 76 6f  id(*xDestroy)(vo
339c0 69 64 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  id*).);.int sqli
339d0 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
339e0 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65  tion16(.  sqlite
339f0 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 76 6f 69  3*, .  const voi
33a00 64 20 2a 7a 4e 61 6d 65 2c 0a 20 20 69 6e 74 20  d *zName,.  int 
33a10 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69  eTextRep, .  voi
33a20 64 20 2a 70 41 72 67 2c 0a 20 20 69 6e 74 28 2a  d *pArg,.  int(*
33a30 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c  xCompare)(void*,
33a40 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  int,const void*,
33a50 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29  int,const void*)
33a60 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
33a70 52 45 46 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20 4e  REF: Collation N
33a80 65 65 64 65 64 20 43 61 6c 6c 62 61 63 6b 73 0a  eeded Callbacks.
33a90 2a 2a 0a 2a 2a 20 5e 54 6f 20 61 76 6f 69 64 20  **.** ^To avoid 
33aa0 68 61 76 69 6e 67 20 74 6f 20 72 65 67 69 73 74  having to regist
33ab0 65 72 20 61 6c 6c 20 63 6f 6c 6c 61 74 69 6f 6e  er all collation
33ac0 20 73 65 71 75 65 6e 63 65 73 20 62 65 66 6f 72   sequences befor
33ad0 65 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  e a database.** 
33ae0 63 61 6e 20 62 65 20 75 73 65 64 2c 20 61 20 73  can be used, a s
33af0 69 6e 67 6c 65 20 63 61 6c 6c 62 61 63 6b 20 66  ingle callback f
33b00 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 72  unction may be r
33b10 65 67 69 73 74 65 72 65 64 20 77 69 74 68 20 74  egistered with t
33b20 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  he.** [database 
33b30 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 62  connection] to b
33b40 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76  e invoked whenev
33b50 65 72 20 61 6e 20 75 6e 64 65 66 69 6e 65 64 20  er an undefined 
33b60 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71  collation.** seq
33b70 75 65 6e 63 65 20 69 73 20 72 65 71 75 69 72 65  uence is require
33b80 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  d..**.** ^If the
33b90 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 65 67   function is reg
33ba0 69 73 74 65 72 65 64 20 75 73 69 6e 67 20 74 68  istered using th
33bb0 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74  e sqlite3_collat
33bc0 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20 41 50 49  ion_needed() API
33bd0 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20  ,.** then it is 
33be0 70 61 73 73 65 64 20 74 68 65 20 6e 61 6d 65 73  passed the names
33bf0 20 6f 66 20 75 6e 64 65 66 69 6e 65 64 20 63 6f   of undefined co
33c00 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65  llation sequence
33c10 73 20 61 73 20 73 74 72 69 6e 67 73 0a 2a 2a 20  s as strings.** 
33c20 65 6e 63 6f 64 65 64 20 69 6e 20 55 54 46 2d 38  encoded in UTF-8
33c30 2e 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6f  . ^If sqlite3_co
33c40 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36  llation_needed16
33c50 28 29 20 69 73 20 75 73 65 64 2c 0a 2a 2a 20 74  () is used,.** t
33c60 68 65 20 6e 61 6d 65 73 20 61 72 65 20 70 61 73  he names are pas
33c70 73 65 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e  sed as UTF-16 in
33c80 20 6d 61 63 68 69 6e 65 20 6e 61 74 69 76 65 20   machine native 
33c90 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 20 5e  byte order..** ^
33ca0 41 20 63 61 6c 6c 20 74 6f 20 65 69 74 68 65 72  A call to either
33cb0 20 66 75 6e 63 74 69 6f 6e 20 72 65 70 6c 61 63   function replac
33cc0 65 73 20 74 68 65 20 65 78 69 73 74 69 6e 67 20  es the existing 
33cd0 63 6f 6c 6c 61 74 69 6f 6e 2d 6e 65 65 64 65 64  collation-needed
33ce0 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a   callback..**.**
33cf0 20 5e 28 57 68 65 6e 20 74 68 65 20 63 61 6c 6c   ^(When the call
33d00 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2c  back is invoked,
33d10 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
33d20 65 6e 74 20 70 61 73 73 65 64 20 69 73 20 61 20  ent passed is a 
33d30 63 6f 70 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73  copy.** of the s
33d40 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  econd argument t
33d50 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74  o sqlite3_collat
33d60 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20 6f 72 0a  ion_needed() or.
33d70 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61  ** sqlite3_colla
33d80 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 2e  tion_needed16().
33d90 20 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67    The second arg
33da0 75 6d 65 6e 74 20 69 73 20 74 68 65 20 64 61 74  ument is the dat
33db0 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74  abase.** connect
33dc0 69 6f 6e 2e 20 20 54 68 65 20 74 68 69 72 64 20  ion.  The third 
33dd0 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20  argument is one 
33de0 6f 66 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d  of [SQLITE_UTF8]
33df0 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42  , [SQLITE_UTF16B
33e00 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54  E],.** or [SQLIT
33e10 45 5f 55 54 46 31 36 4c 45 5d 2c 20 69 6e 64 69  E_UTF16LE], indi
33e20 63 61 74 69 6e 67 20 74 68 65 20 6d 6f 73 74 20  cating the most 
33e30 64 65 73 69 72 61 62 6c 65 20 66 6f 72 6d 20 6f  desirable form o
33e40 66 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a  f the collation.
33e50 2a 2a 20 73 65 71 75 65 6e 63 65 20 66 75 6e 63  ** sequence func
33e60 74 69 6f 6e 20 72 65 71 75 69 72 65 64 2e 20 20  tion required.  
33e70 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  The fourth param
33e80 65 74 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65  eter is the name
33e90 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 71 75 69   of the.** requi
33ea0 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65  red collation se
33eb0 71 75 65 6e 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20  quence.)^.**.** 
33ec0 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  The callback fun
33ed0 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 72 65 67  ction should reg
33ee0 69 73 74 65 72 20 74 68 65 20 64 65 73 69 72 65  ister the desire
33ef0 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 75 73 69 6e  d collation usin
33f00 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72  g.** [sqlite3_cr
33f10 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29  eate_collation()
33f20 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  ], [sqlite3_crea
33f30 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29  te_collation16()
33f40 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  ], or.** [sqlite
33f50 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
33f60 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 69 6e 74  on_v2()]..*/.int
33f70 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69   sqlite3_collati
33f80 6f 6e 5f 6e 65 65 64 65 64 28 0a 20 20 73 71 6c  on_needed(.  sql
33f90 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c  ite3*, .  void*,
33fa0 20 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64   .  void(*)(void
33fb0 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65  *,sqlite3*,int e
33fc0 54 65 78 74 52 65 70 2c 63 6f 6e 73 74 20 63 68  TextRep,const ch
33fd0 61 72 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  ar*).);.int sqli
33fe0 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
33ff0 65 64 65 64 31 36 28 0a 20 20 73 71 6c 69 74 65  eded16(.  sqlite
34000 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20  3*, .  void*,.  
34010 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71  void(*)(void*,sq
34020 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54 65 78 74  lite3*,int eText
34030 52 65 70 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29  Rep,const void*)
34040 0a 29 3b 0a 0a 23 69 66 64 65 66 20 53 51 4c 49  .);..#ifdef SQLI
34050 54 45 5f 48 41 53 5f 43 4f 44 45 43 0a 2f 2a 0a  TE_HAS_CODEC./*.
34060 2a 2a 20 53 70 65 63 69 66 79 20 74 68 65 20 6b  ** Specify the k
34070 65 79 20 66 6f 72 20 61 6e 20 65 6e 63 72 79 70  ey for an encryp
34080 74 65 64 20 64 61 74 61 62 61 73 65 2e 20 20 54  ted database.  T
34090 68 69 73 20 72 6f 75 74 69 6e 65 20 73 68 6f 75  his routine shou
340a0 6c 64 20 62 65 0a 2a 2a 20 63 61 6c 6c 65 64 20  ld be.** called 
340b0 72 69 67 68 74 20 61 66 74 65 72 20 73 71 6c 69  right after sqli
340c0 74 65 33 5f 6f 70 65 6e 28 29 2e 0a 2a 2a 0a 2a  te3_open()..**.*
340d0 2a 20 54 68 65 20 63 6f 64 65 20 74 6f 20 69 6d  * The code to im
340e0 70 6c 65 6d 65 6e 74 20 74 68 69 73 20 41 50 49  plement this API
340f0 20 69 73 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c   is not availabl
34100 65 20 69 6e 20 74 68 65 20 70 75 62 6c 69 63 20  e in the public 
34110 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51  release.** of SQ
34120 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  Lite..*/.int sql
34130 69 74 65 33 5f 6b 65 79 28 0a 20 20 73 71 6c 69  ite3_key(.  sqli
34140 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
34150 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61             /* Da
34160 74 61 62 61 73 65 20 74 6f 20 62 65 20 72 65 6b  tabase to be rek
34170 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  eyed */.  const 
34180 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20  void *pKey, int 
34190 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 68 65 20  nKey     /* The 
341a0 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  key */.);../*.**
341b0 20 43 68 61 6e 67 65 20 74 68 65 20 6b 65 79 20   Change the key 
341c0 6f 6e 20 61 6e 20 6f 70 65 6e 20 64 61 74 61 62  on an open datab
341d0 61 73 65 2e 20 20 49 66 20 74 68 65 20 63 75 72  ase.  If the cur
341e0 72 65 6e 74 20 64 61 74 61 62 61 73 65 20 69 73  rent database is
341f0 20 6e 6f 74 0a 2a 2a 20 65 6e 63 72 79 70 74 65   not.** encrypte
34200 64 2c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  d, this routine 
34210 77 69 6c 6c 20 65 6e 63 72 79 70 74 20 69 74 2e  will encrypt it.
34220 20 20 49 66 20 70 4e 65 77 3d 3d 30 20 6f 72 20    If pNew==0 or 
34230 6e 4e 65 77 3d 3d 30 2c 20 74 68 65 0a 2a 2a 20  nNew==0, the.** 
34240 64 61 74 61 62 61 73 65 20 69 73 20 64 65 63 72  database is decr
34250 79 70 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ypted..**.** The
34260 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65   code to impleme
34270 6e 74 20 74 68 69 73 20 41 50 49 20 69 73 20 6e  nt this API is n
34280 6f 74 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20  ot available in 
34290 74 68 65 20 70 75 62 6c 69 63 20 72 65 6c 65 61  the public relea
342a0 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e  se.** of SQLite.
342b0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
342c0 72 65 6b 65 79 28 0a 20 20 73 71 6c 69 74 65 33  rekey(.  sqlite3
342d0 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
342e0 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
342f0 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65 79 65  ase to be rekeye
34300 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  d */.  const voi
34310 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65  d *pKey, int nKe
34320 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6e 65 77  y     /* The new
34330 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a   key */.);../*.*
34340 2a 20 53 70 65 63 69 66 79 20 74 68 65 20 61 63  * Specify the ac
34350 74 69 76 61 74 69 6f 6e 20 6b 65 79 20 66 6f 72  tivation key for
34360 20 61 20 53 45 45 20 64 61 74 61 62 61 73 65 2e   a SEE database.
34370 20 20 55 6e 6c 65 73 73 20 0a 2a 2a 20 61 63 74    Unless .** act
34380 69 76 61 74 65 64 2c 20 6e 6f 6e 65 20 6f 66 20  ivated, none of 
34390 74 68 65 20 53 45 45 20 72 6f 75 74 69 6e 65 73  the SEE routines
343a0 20 77 69 6c 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a 76   will work..*/.v
343b0 6f 69 64 20 73 71 6c 69 74 65 33 5f 61 63 74 69  oid sqlite3_acti
343c0 76 61 74 65 5f 73 65 65 28 0a 20 20 63 6f 6e 73  vate_see(.  cons
343d0 74 20 63 68 61 72 20 2a 7a 50 61 73 73 50 68 72  t char *zPassPhr
343e0 61 73 65 20 20 20 20 20 20 20 20 2f 2a 20 41 63  ase        /* Ac
343f0 74 69 76 61 74 69 6f 6e 20 70 68 72 61 73 65 20  tivation phrase 
34400 2a 2f 0a 29 3b 0a 23 65 6e 64 69 66 0a 0a 23 69  */.);.#endif..#i
34410 66 64 65 66 20 53 51 4c 49 54 45 5f 45 4e 41 42  fdef SQLITE_ENAB
34420 4c 45 5f 43 45 52 4f 44 0a 2f 2a 0a 2a 2a 20 53  LE_CEROD./*.** S
34430 70 65 63 69 66 79 20 74 68 65 20 61 63 74 69 76  pecify the activ
34440 61 74 69 6f 6e 20 6b 65 79 20 66 6f 72 20 61 20  ation key for a 
34450 43 45 52 4f 44 20 64 61 74 61 62 61 73 65 2e 20  CEROD database. 
34460 20 55 6e 6c 65 73 73 20 0a 2a 2a 20 61 63 74 69   Unless .** acti
34470 76 61 74 65 64 2c 20 6e 6f 6e 65 20 6f 66 20 74  vated, none of t
34480 68 65 20 43 45 52 4f 44 20 72 6f 75 74 69 6e 65  he CEROD routine
34490 73 20 77 69 6c 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a  s will work..*/.
344a0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 61 63 74  void sqlite3_act
344b0 69 76 61 74 65 5f 63 65 72 6f 64 28 0a 20 20 63  ivate_cerod(.  c
344c0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 73 73  onst char *zPass
344d0 50 68 72 61 73 65 20 20 20 20 20 20 20 20 2f 2a  Phrase        /*
344e0 20 41 63 74 69 76 61 74 69 6f 6e 20 70 68 72 61   Activation phra
344f0 73 65 20 2a 2f 0a 29 3b 0a 23 65 6e 64 69 66 0a  se */.);.#endif.
34500 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
34510 20 53 75 73 70 65 6e 64 20 45 78 65 63 75 74 69   Suspend Executi
34520 6f 6e 20 46 6f 72 20 41 20 53 68 6f 72 74 20 54  on For A Short T
34530 69 6d 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ime.**.** The sq
34540 6c 69 74 65 33 5f 73 6c 65 65 70 28 29 20 66 75  lite3_sleep() fu
34550 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20 74 68  nction causes th
34560 65 20 63 75 72 72 65 6e 74 20 74 68 72 65 61 64  e current thread
34570 20 74 6f 20 73 75 73 70 65 6e 64 20 65 78 65 63   to suspend exec
34580 75 74 69 6f 6e 0a 2a 2a 20 66 6f 72 20 61 74 20  ution.** for at 
34590 6c 65 61 73 74 20 61 20 6e 75 6d 62 65 72 20 6f  least a number o
345a0 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 73  f milliseconds s
345b0 70 65 63 69 66 69 65 64 20 69 6e 20 69 74 73 20  pecified in its 
345c0 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a  parameter..**.**
345d0 20 49 66 20 74 68 65 20 6f 70 65 72 61 74 69 6e   If the operatin
345e0 67 20 73 79 73 74 65 6d 20 64 6f 65 73 20 6e 6f  g system does no
345f0 74 20 73 75 70 70 6f 72 74 20 73 6c 65 65 70 20  t support sleep 
34600 72 65 71 75 65 73 74 73 20 77 69 74 68 0a 2a 2a  requests with.**
34610 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 74 69 6d   millisecond tim
34620 65 20 72 65 73 6f 6c 75 74 69 6f 6e 2c 20 74 68  e resolution, th
34630 65 6e 20 74 68 65 20 74 69 6d 65 20 77 69 6c 6c  en the time will
34640 20 62 65 20 72 6f 75 6e 64 65 64 20 75 70 20 74   be rounded up t
34650 6f 0a 2a 2a 20 74 68 65 20 6e 65 61 72 65 73 74  o.** the nearest
34660 20 73 65 63 6f 6e 64 2e 20 54 68 65 20 6e 75 6d   second. The num
34670 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f  ber of milliseco
34680 6e 64 73 20 6f 66 20 73 6c 65 65 70 20 61 63 74  nds of sleep act
34690 75 61 6c 6c 79 0a 2a 2a 20 72 65 71 75 65 73 74  ually.** request
346a0 65 64 20 66 72 6f 6d 20 74 68 65 20 6f 70 65 72  ed from the oper
346b0 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69 73 20  ating system is 
346c0 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
346d0 5e 53 51 4c 69 74 65 20 69 6d 70 6c 65 6d 65 6e  ^SQLite implemen
346e0 74 73 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  ts this interfac
346f0 65 20 62 79 20 63 61 6c 6c 69 6e 67 20 74 68 65  e by calling the
34700 20 78 53 6c 65 65 70 28 29 0a 2a 2a 20 6d 65 74   xSleep().** met
34710 68 6f 64 20 6f 66 20 74 68 65 20 64 65 66 61 75  hod of the defau
34720 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  lt [sqlite3_vfs]
34730 20 6f 62 6a 65 63 74 2e 20 20 49 66 20 74 68 65   object.  If the
34740 20 78 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64   xSleep() method
34750 0a 2a 2a 20 6f 66 20 74 68 65 20 64 65 66 61 75  .** of the defau
34760 6c 74 20 56 46 53 20 69 73 20 6e 6f 74 20 69 6d  lt VFS is not im
34770 70 6c 65 6d 65 6e 74 65 64 20 63 6f 72 72 65 63  plemented correc
34780 74 6c 79 2c 20 6f 72 20 6e 6f 74 20 69 6d 70 6c  tly, or not impl
34790 65 6d 65 6e 74 65 64 20 61 74 0a 2a 2a 20 61 6c  emented at.** al
347a0 6c 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  l, then the beha
347b0 76 69 6f 72 20 6f 66 20 73 71 6c 69 74 65 33 5f  vior of sqlite3_
347c0 73 6c 65 65 70 28 29 20 6d 61 79 20 64 65 76 69  sleep() may devi
347d0 61 74 65 20 66 72 6f 6d 20 74 68 65 20 64 65 73  ate from the des
347e0 63 72 69 70 74 69 6f 6e 0a 2a 2a 20 69 6e 20 74  cription.** in t
347f0 68 65 20 70 72 65 76 69 6f 75 73 20 70 61 72 61  he previous para
34800 67 72 61 70 68 73 2e 0a 2a 2f 0a 69 6e 74 20 73  graphs..*/.int s
34810 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 69 6e 74  qlite3_sleep(int
34820 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
34830 45 46 3a 20 4e 61 6d 65 20 4f 66 20 54 68 65 20  EF: Name Of The 
34840 46 6f 6c 64 65 72 20 48 6f 6c 64 69 6e 67 20 54  Folder Holding T
34850 65 6d 70 6f 72 61 72 79 20 46 69 6c 65 73 0a 2a  emporary Files.*
34860 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 69 73 20 67  *.** ^(If this g
34870 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 20 69  lobal variable i
34880 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20  s made to point 
34890 74 6f 20 61 20 73 74 72 69 6e 67 20 77 68 69 63  to a string whic
348a0 68 20 69 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65  h is.** the name
348b0 20 6f 66 20 61 20 66 6f 6c 64 65 72 20 28 61 2e   of a folder (a.
348c0 6b 2e 61 2e 20 64 69 72 65 63 74 6f 72 79 29 2c  k.a. directory),
348d0 20 74 68 65 6e 20 61 6c 6c 20 74 65 6d 70 6f 72   then all tempor
348e0 61 72 79 20 66 69 6c 65 73 0a 2a 2a 20 63 72 65  ary files.** cre
348f0 61 74 65 64 20 62 79 20 53 51 4c 69 74 65 20 77  ated by SQLite w
34900 68 65 6e 20 75 73 69 6e 67 20 61 20 62 75 69 6c  hen using a buil
34910 74 2d 69 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66  t-in [sqlite3_vf
34920 73 20 7c 20 56 46 53 5d 0a 2a 2a 20 77 69 6c 6c  s | VFS].** will
34930 20 62 65 20 70 6c 61 63 65 64 20 69 6e 20 74 68   be placed in th
34940 61 74 20 64 69 72 65 63 74 6f 72 79 2e 29 5e 20  at directory.)^ 
34950 20 5e 49 66 20 74 68 69 73 20 76 61 72 69 61 62   ^If this variab
34960 6c 65 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20  le.** is a NULL 
34970 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 53 51  pointer, then SQ
34980 4c 69 74 65 20 70 65 72 66 6f 72 6d 73 20 61 20  Lite performs a 
34990 73 65 61 72 63 68 20 66 6f 72 20 61 6e 20 61 70  search for an ap
349a0 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20 74 65 6d  propriate.** tem
349b0 70 6f 72 61 72 79 20 66 69 6c 65 20 64 69 72 65  porary file dire
349c0 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 49 74 20  ctory..**.** It 
349d0 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 72  is not safe to r
349e0 65 61 64 20 6f 72 20 6d 6f 64 69 66 79 20 74 68  ead or modify th
349f0 69 73 20 76 61 72 69 61 62 6c 65 20 69 6e 20 6d  is variable in m
34a00 6f 72 65 20 74 68 61 6e 20 6f 6e 65 0a 2a 2a 20  ore than one.** 
34a10 74 68 72 65 61 64 20 61 74 20 61 20 74 69 6d 65  thread at a time
34a20 2e 20 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66  .  It is not saf
34a30 65 20 74 6f 20 72 65 61 64 20 6f 72 20 6d 6f 64  e to read or mod
34a40 69 66 79 20 74 68 69 73 20 76 61 72 69 61 62 6c  ify this variabl
34a50 65 0a 2a 2a 20 69 66 20 61 20 5b 64 61 74 61 62  e.** if a [datab
34a60 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
34a70 69 73 20 62 65 69 6e 67 20 75 73 65 64 20 61 74  is being used at
34a80 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 69   the same time i
34a90 6e 20 61 20 73 65 70 61 72 61 74 65 0a 2a 2a 20  n a separate.** 
34aa0 74 68 72 65 61 64 2e 0a 2a 2a 20 49 74 20 69 73  thread..** It is
34ab0 20 69 6e 74 65 6e 64 65 64 20 74 68 61 74 20 74   intended that t
34ac0 68 69 73 20 76 61 72 69 61 62 6c 65 20 62 65 20  his variable be 
34ad0 73 65 74 20 6f 6e 63 65 0a 2a 2a 20 61 73 20 70  set once.** as p
34ae0 61 72 74 20 6f 66 20 70 72 6f 63 65 73 73 20 69  art of process i
34af0 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e  nitialization an
34b00 64 20 62 65 66 6f 72 65 20 61 6e 79 20 53 51 4c  d before any SQL
34b10 69 74 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  ite interface.**
34b20 20 72 6f 75 74 69 6e 65 73 20 68 61 76 65 20 62   routines have b
34b30 65 65 6e 20 63 61 6c 6c 65 64 20 61 6e 64 20 74  een called and t
34b40 68 61 74 20 74 68 69 73 20 76 61 72 69 61 62 6c  hat this variabl
34b50 65 20 72 65 6d 61 69 6e 20 75 6e 63 68 61 6e 67  e remain unchang
34b60 65 64 0a 2a 2a 20 74 68 65 72 65 61 66 74 65 72  ed.** thereafter
34b70 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 74 65  ..**.** ^The [te
34b80 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f  mp_store_directo
34b90 72 79 20 70 72 61 67 6d 61 5d 20 6d 61 79 20 6d  ry pragma] may m
34ba0 6f 64 69 66 79 20 74 68 69 73 20 76 61 72 69 61  odify this varia
34bb0 62 6c 65 20 61 6e 64 20 63 61 75 73 65 0a 2a 2a  ble and cause.**
34bc0 20 69 74 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20   it to point to 
34bd0 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20  memory obtained 
34be0 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61  from [sqlite3_ma
34bf0 6c 6c 6f 63 5d 2e 20 20 5e 46 75 72 74 68 65 72  lloc].  ^Further
34c00 6d 6f 72 65 2c 0a 2a 2a 20 74 68 65 20 5b 74 65  more,.** the [te
34c10 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f  mp_store_directo
34c20 72 79 20 70 72 61 67 6d 61 5d 20 61 6c 77 61 79  ry pragma] alway
34c30 73 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 61  s assumes that a
34c40 6e 79 20 73 74 72 69 6e 67 0a 2a 2a 20 74 68 61  ny string.** tha
34c50 74 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20  t this variable 
34c60 70 6f 69 6e 74 73 20 74 6f 20 69 73 20 68 65 6c  points to is hel
34c70 64 20 69 6e 20 6d 65 6d 6f 72 79 20 6f 62 74 61  d in memory obta
34c80 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73  ined from .** [s
34c90 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 20 61  qlite3_malloc] a
34ca0 6e 64 20 74 68 65 20 70 72 61 67 6d 61 20 6d 61  nd the pragma ma
34cb0 79 20 61 74 74 65 6d 70 74 20 74 6f 20 66 72 65  y attempt to fre
34cc0 65 20 74 68 61 74 20 6d 65 6d 6f 72 79 0a 2a 2a  e that memory.**
34cd0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
34ce0 66 72 65 65 5d 2e 0a 2a 2a 20 48 65 6e 63 65 2c  free]..** Hence,
34cf0 20 69 66 20 74 68 69 73 20 76 61 72 69 61 62 6c   if this variabl
34d00 65 20 69 73 20 6d 6f 64 69 66 69 65 64 20 64 69  e is modified di
34d10 72 65 63 74 6c 79 2c 20 65 69 74 68 65 72 20 69  rectly, either i
34d20 74 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 6d  t should be.** m
34d30 61 64 65 20 4e 55 4c 4c 20 6f 72 20 6d 61 64 65  ade NULL or made
34d40 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 6d 65 6d   to point to mem
34d50 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ory obtained fro
34d60 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
34d70 63 5d 0a 2a 2a 20 6f 72 20 65 6c 73 65 20 74 68  c].** or else th
34d80 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b 74 65  e use of the [te
34d90 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f  mp_store_directo
34da0 72 79 20 70 72 61 67 6d 61 5d 20 73 68 6f 75 6c  ry pragma] shoul
34db0 64 20 62 65 20 61 76 6f 69 64 65 64 2e 0a 2a 2f  d be avoided..*/
34dc0 0a 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 20 63  .SQLITE_EXTERN c
34dd0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 74 65 6d  har *sqlite3_tem
34de0 70 5f 64 69 72 65 63 74 6f 72 79 3b 0a 0a 2f 2a  p_directory;../*
34df0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65  .** CAPI3REF: Te
34e00 73 74 20 46 6f 72 20 41 75 74 6f 2d 43 6f 6d 6d  st For Auto-Comm
34e10 69 74 20 4d 6f 64 65 0a 2a 2a 20 4b 45 59 57 4f  it Mode.** KEYWO
34e20 52 44 53 3a 20 7b 61 75 74 6f 63 6f 6d 6d 69 74  RDS: {autocommit
34e30 20 6d 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68   mode}.**.** ^Th
34e40 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75  e sqlite3_get_au
34e50 74 6f 63 6f 6d 6d 69 74 28 29 20 69 6e 74 65 72  tocommit() inter
34e60 66 61 63 65 20 72 65 74 75 72 6e 73 20 6e 6f 6e  face returns non
34e70 2d 7a 65 72 6f 20 6f 72 0a 2a 2a 20 7a 65 72 6f  -zero or.** zero
34e80 20 69 66 20 74 68 65 20 67 69 76 65 6e 20 64 61   if the given da
34e90 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
34ea0 6e 20 69 73 20 6f 72 20 69 73 20 6e 6f 74 20 69  n is or is not i
34eb0 6e 20 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64  n autocommit mod
34ec0 65 2c 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65  e,.** respective
34ed0 6c 79 2e 20 20 5e 41 75 74 6f 63 6f 6d 6d 69 74  ly.  ^Autocommit
34ee0 20 6d 6f 64 65 20 69 73 20 6f 6e 20 62 79 20 64   mode is on by d
34ef0 65 66 61 75 6c 74 2e 0a 2a 2a 20 5e 41 75 74 6f  efault..** ^Auto
34f00 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 64  commit mode is d
34f10 69 73 61 62 6c 65 64 20 62 79 20 61 20 5b 42 45  isabled by a [BE
34f20 47 49 4e 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a  GIN] statement..
34f30 2a 2a 20 5e 41 75 74 6f 63 6f 6d 6d 69 74 20 6d  ** ^Autocommit m
34f40 6f 64 65 20 69 73 20 72 65 2d 65 6e 61 62 6c 65  ode is re-enable
34f50 64 20 62 79 20 61 20 5b 43 4f 4d 4d 49 54 5d 20  d by a [COMMIT] 
34f60 6f 72 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a  or [ROLLBACK]..*
34f70 2a 0a 2a 2a 20 49 66 20 63 65 72 74 61 69 6e 20  *.** If certain 
34f80 6b 69 6e 64 73 20 6f 66 20 65 72 72 6f 72 73 20  kinds of errors 
34f90 6f 63 63 75 72 20 6f 6e 20 61 20 73 74 61 74 65  occur on a state
34fa0 6d 65 6e 74 20 77 69 74 68 69 6e 20 61 20 6d 75  ment within a mu
34fb0 6c 74 69 2d 73 74 61 74 65 6d 65 6e 74 0a 2a 2a  lti-statement.**
34fc0 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 28 65 72   transaction (er
34fd0 72 6f 72 73 20 69 6e 63 6c 75 64 69 6e 67 20 5b  rors including [
34fe0 53 51 4c 49 54 45 5f 46 55 4c 4c 5d 2c 20 5b 53  SQLITE_FULL], [S
34ff0 51 4c 49 54 45 5f 49 4f 45 52 52 5d 2c 0a 2a 2a  QLITE_IOERR],.**
35000 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2c   [SQLITE_NOMEM],
35010 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 20   [SQLITE_BUSY], 
35020 61 6e 64 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45  and [SQLITE_INTE
35030 52 52 55 50 54 5d 29 20 74 68 65 6e 20 74 68 65  RRUPT]) then the
35040 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  .** transaction 
35050 6d 69 67 68 74 20 62 65 20 72 6f 6c 6c 65 64 20  might be rolled 
35060 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c  back automatical
35070 6c 79 2e 20 20 54 68 65 20 6f 6e 6c 79 20 77 61  ly.  The only wa
35080 79 20 74 6f 0a 2a 2a 20 66 69 6e 64 20 6f 75 74  y to.** find out
35090 20 77 68 65 74 68 65 72 20 53 51 4c 69 74 65 20   whether SQLite 
350a0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f  automatically ro
350b0 6c 6c 65 64 20 62 61 63 6b 20 74 68 65 20 74 72  lled back the tr
350c0 61 6e 73 61 63 74 69 6f 6e 20 61 66 74 65 72 0a  ansaction after.
350d0 2a 2a 20 61 6e 20 65 72 72 6f 72 20 69 73 20 74  ** an error is t
350e0 6f 20 75 73 65 20 74 68 69 73 20 66 75 6e 63 74  o use this funct
350f0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e  ion..**.** If an
35100 6f 74 68 65 72 20 74 68 72 65 61 64 20 63 68 61  other thread cha
35110 6e 67 65 73 20 74 68 65 20 61 75 74 6f 63 6f 6d  nges the autocom
35120 6d 69 74 20 73 74 61 74 75 73 20 6f 66 20 74 68  mit status of th
35130 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f  e database.** co
35140 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74  nnection while t
35150 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 72  his routine is r
35160 75 6e 6e 69 6e 67 2c 20 74 68 65 6e 20 74 68 65  unning, then the
35170 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a   return value.**
35180 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
35190 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 65  /.int sqlite3_ge
351a0 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 73 71 6c  t_autocommit(sql
351b0 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
351c0 41 50 49 33 52 45 46 3a 20 46 69 6e 64 20 54 68  API3REF: Find Th
351d0 65 20 44 61 74 61 62 61 73 65 20 48 61 6e 64 6c  e Database Handl
351e0 65 20 4f 66 20 41 20 50 72 65 70 61 72 65 64 20  e Of A Prepared 
351f0 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20  Statement.**.** 
35200 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f  ^The sqlite3_db_
35210 68 61 6e 64 6c 65 20 69 6e 74 65 72 66 61 63 65  handle interface
35220 20 72 65 74 75 72 6e 73 20 74 68 65 20 5b 64 61   returns the [da
35230 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
35240 6e 5d 20 68 61 6e 64 6c 65 0a 2a 2a 20 74 6f 20  n] handle.** to 
35250 77 68 69 63 68 20 61 20 5b 70 72 65 70 61 72 65  which a [prepare
35260 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 62 65 6c  d statement] bel
35270 6f 6e 67 73 2e 20 20 5e 54 68 65 20 5b 64 61 74  ongs.  ^The [dat
35280 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
35290 5d 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79  ].** returned by
352a0 20 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64   sqlite3_db_hand
352b0 6c 65 20 69 73 20 74 68 65 20 73 61 6d 65 20 5b  le is the same [
352c0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
352d0 69 6f 6e 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73  ion].** that was
352e0 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
352f0 65 6e 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73  ent.** to the [s
35300 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
35310 32 28 29 5d 20 63 61 6c 6c 20 28 6f 72 20 69 74  2()] call (or it
35320 73 20 76 61 72 69 61 6e 74 73 29 20 74 68 61 74  s variants) that
35330 20 77 61 73 20 75 73 65 64 20 74 6f 0a 2a 2a 20   was used to.** 
35340 63 72 65 61 74 65 20 74 68 65 20 73 74 61 74 65  create the state
35350 6d 65 6e 74 20 69 6e 20 74 68 65 20 66 69 72 73  ment in the firs
35360 74 20 70 6c 61 63 65 2e 0a 2a 2f 0a 73 71 6c 69  t place..*/.sqli
35370 74 65 33 20 2a 73 71 6c 69 74 65 33 5f 64 62 5f  te3 *sqlite3_db_
35380 68 61 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f 73  handle(sqlite3_s
35390 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  tmt*);../*.** CA
353a0 50 49 33 52 45 46 3a 20 52 65 74 75 72 6e 20 54  PI3REF: Return T
353b0 68 65 20 46 69 6c 65 6e 61 6d 65 20 46 6f 72 20  he Filename For 
353c0 41 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65  A Database Conne
353d0 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ction.**.** ^The
353e0 20 73 71 6c 69 74 65 33 5f 64 62 5f 66 69 6c 65   sqlite3_db_file
353f0 6e 61 6d 65 28 44 2c 4e 29 20 69 6e 74 65 72 66  name(D,N) interf
35400 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ace returns a po
35410 69 6e 74 65 72 20 74 6f 20 61 20 66 69 6c 65 6e  inter to a filen
35420 61 6d 65 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65  ame.** associate
35430 64 20 77 69 74 68 20 64 61 74 61 62 61 73 65 20  d with database 
35440 4e 20 6f 66 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  N of connection 
35450 44 2e 20 20 5e 54 68 65 20 6d 61 69 6e 20 64 61  D.  ^The main da
35460 74 61 62 61 73 65 20 66 69 6c 65 0a 2a 2a 20 68  tabase file.** h
35470 61 73 20 74 68 65 20 6e 61 6d 65 20 22 6d 61 69  as the name "mai
35480 6e 22 2e 20 20 49 66 20 74 68 65 72 65 20 69 73  n".  If there is
35490 20 6e 6f 20 61 74 74 61 63 68 65 64 20 64 61 74   no attached dat
354a0 61 62 61 73 65 20 4e 20 6f 6e 20 74 68 65 20 64  abase N on the d
354b0 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65  atabase.** conne
354c0 63 74 69 6f 6e 20 44 2c 20 6f 72 20 69 66 20 64  ction D, or if d
354d0 61 74 61 62 61 73 65 20 4e 20 69 73 20 61 20 74  atabase N is a t
354e0 65 6d 70 6f 72 61 72 79 20 6f 72 20 69 6e 2d 6d  emporary or in-m
354f0 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 2c 20  emory database, 
35500 74 68 65 6e 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70  then.** a NULL p
35510 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e  ointer is return
35520 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  ed..**.** ^The f
35530 69 6c 65 6e 61 6d 65 20 72 65 74 75 72 6e 65 64  ilename returned
35540 20 62 79 20 74 68 69 73 20 66 75 6e 63 74 69 6f   by this functio
35550 6e 20 69 73 20 74 68 65 20 6f 75 74 70 75 74 20  n is the output 
35560 6f 66 20 74 68 65 0a 2a 2a 20 78 46 75 6c 6c 50  of the.** xFullP
35570 61 74 68 6e 61 6d 65 20 6d 65 74 68 6f 64 20 6f  athname method o
35580 66 20 74 68 65 20 5b 56 46 53 5d 2e 20 20 5e 49  f the [VFS].  ^I
35590 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74  n other words, t
355a0 68 65 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 77  he filename.** w
355b0 69 6c 6c 20 62 65 20 61 6e 20 61 62 73 6f 6c 75  ill be an absolu
355c0 74 65 20 70 61 74 68 6e 61 6d 65 2c 20 65 76 65  te pathname, eve
355d0 6e 20 69 66 20 74 68 65 20 66 69 6c 65 6e 61 6d  n if the filenam
355e0 65 20 75 73 65 64 0a 2a 2a 20 74 6f 20 6f 70 65  e used.** to ope
355f0 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6f  n the database o
35600 72 69 67 69 6e 61 6c 6c 79 20 77 61 73 20 61 20  riginally was a 
35610 55 52 49 20 6f 72 20 72 65 6c 61 74 69 76 65 20  URI or relative 
35620 70 61 74 68 6e 61 6d 65 2e 0a 2a 2f 0a 63 6f 6e  pathname..*/.con
35630 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
35640 5f 64 62 5f 66 69 6c 65 6e 61 6d 65 28 73 71 6c  _db_filename(sql
35650 69 74 65 33 20 2a 64 62 2c 20 63 6f 6e 73 74 20  ite3 *db, const 
35660 63 68 61 72 20 2a 7a 44 62 4e 61 6d 65 29 3b 0a  char *zDbName);.
35670 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
35680 20 44 65 74 65 72 6d 69 6e 65 20 69 66 20 61 20   Determine if a 
35690 64 61 74 61 62 61 73 65 20 69 73 20 72 65 61 64  database is read
356a0 2d 6f 6e 6c 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  -only.**.** ^The
356b0 20 73 71 6c 69 74 65 33 5f 64 62 5f 72 65 61 64   sqlite3_db_read
356c0 6f 6e 6c 79 28 44 2c 4e 29 20 69 6e 74 65 72 66  only(D,N) interf
356d0 61 63 65 20 72 65 74 75 72 6e 73 20 31 20 69 66  ace returns 1 if
356e0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 4e 0a   the database N.
356f0 2a 2a 20 6f 66 20 63 6f 6e 6e 65 63 74 69 6f 6e  ** of connection
35700 20 44 20 69 73 20 72 65 61 64 2d 6f 6e 6c 79 2c   D is read-only,
35710 20 30 20 69 66 20 69 74 20 69 73 20 72 65 61 64   0 if it is read
35720 2f 77 72 69 74 65 2c 20 6f 72 20 2d 31 20 69 66  /write, or -1 if
35730 20 4e 20 69 73 20 6e 6f 74 0a 2a 2a 20 74 68 65   N is not.** the
35740 20 6e 61 6d 65 20 6f 66 20 61 20 64 61 74 61 62   name of a datab
35750 61 73 65 20 6f 6e 20 63 6f 6e 6e 65 63 74 69 6f  ase on connectio
35760 6e 20 44 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  n D..*/.int sqli
35770 74 65 33 5f 64 62 5f 72 65 61 64 6f 6e 6c 79 28  te3_db_readonly(
35780 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 63 6f 6e  sqlite3 *db, con
35790 73 74 20 63 68 61 72 20 2a 7a 44 62 4e 61 6d 65  st char *zDbName
357a0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
357b0 45 46 3a 20 46 69 6e 64 20 74 68 65 20 6e 65 78  EF: Find the nex
357c0 74 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  t prepared state
357d0 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  ment.**.** ^This
357e0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
357f0 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
35800 74 68 65 20 6e 65 78 74 20 5b 70 72 65 70 61 72  the next [prepar
35810 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 66  ed statement] af
35820 74 65 72 0a 2a 2a 20 70 53 74 6d 74 20 61 73 73  ter.** pStmt ass
35830 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65  ociated with the
35840 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
35850 63 74 69 6f 6e 5d 20 70 44 62 2e 20 20 5e 49 66  ction] pDb.  ^If
35860 20 70 53 74 6d 74 20 69 73 20 4e 55 4c 4c 0a 2a   pStmt is NULL.*
35870 2a 20 74 68 65 6e 20 74 68 69 73 20 69 6e 74 65  * then this inte
35880 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
35890 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 66  pointer to the f
358a0 69 72 73 74 20 70 72 65 70 61 72 65 64 20 73 74  irst prepared st
358b0 61 74 65 6d 65 6e 74 0a 2a 2a 20 61 73 73 6f 63  atement.** assoc
358c0 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 64  iated with the d
358d0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
358e0 6f 6e 20 70 44 62 2e 20 20 5e 49 66 20 6e 6f 20  on pDb.  ^If no 
358f0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
35900 6e 74 0a 2a 2a 20 73 61 74 69 73 66 69 65 73 20  nt.** satisfies 
35910 74 68 65 20 63 6f 6e 64 69 74 69 6f 6e 73 20 6f  the conditions o
35920 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20  f this routine, 
35930 69 74 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2e  it returns NULL.
35940 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 64 61 74 61  .**.** The [data
35950 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
35960 20 70 6f 69 6e 74 65 72 20 44 20 69 6e 20 61 20   pointer D in a 
35970 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  call to.** [sqli
35980 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 44 2c  te3_next_stmt(D,
35990 53 29 5d 20 6d 75 73 74 20 72 65 66 65 72 20 74  S)] must refer t
359a0 6f 20 61 6e 20 6f 70 65 6e 20 64 61 74 61 62 61  o an open databa
359b0 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  se.** connection
359c0 20 61 6e 64 20 69 6e 20 70 61 72 74 69 63 75 6c   and in particul
359d0 61 72 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 61  ar must not be a
359e0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
359f0 2f 0a 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  /.sqlite3_stmt *
35a00 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d  sqlite3_next_stm
35a10 74 28 73 71 6c 69 74 65 33 20 2a 70 44 62 2c 20  t(sqlite3 *pDb, 
35a20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
35a30 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
35a40 49 33 52 45 46 3a 20 43 6f 6d 6d 69 74 20 41 6e  I3REF: Commit An
35a50 64 20 52 6f 6c 6c 62 61 63 6b 20 4e 6f 74 69 66  d Rollback Notif
35a60 69 63 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b  ication Callback
35a70 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s.**.** ^The sql
35a80 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b  ite3_commit_hook
35a90 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 67  () interface reg
35aa0 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63  isters a callbac
35ab0 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 6f  k.** function to
35ac0 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e   be invoked when
35ad0 65 76 65 72 20 61 20 74 72 61 6e 73 61 63 74 69  ever a transacti
35ae0 6f 6e 20 69 73 20 5b 43 4f 4d 4d 49 54 20 7c 20  on is [COMMIT | 
35af0 63 6f 6d 6d 69 74 74 65 64 5d 2e 0a 2a 2a 20 5e  committed]..** ^
35b00 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74  Any callback set
35b10 20 62 79 20 61 20 70 72 65 76 69 6f 75 73 20 63   by a previous c
35b20 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  all to sqlite3_c
35b30 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 0a 2a 2a 20  ommit_hook().** 
35b40 66 6f 72 20 74 68 65 20 73 61 6d 65 20 64 61 74  for the same dat
35b50 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
35b60 20 69 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a   is overridden..
35b70 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
35b80 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 20  rollback_hook() 
35b90 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74  interface regist
35ba0 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 0a 2a  ers a callback.*
35bb0 2a 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  * function to be
35bc0 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65   invoked wheneve
35bd0 72 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  r a transaction 
35be0 69 73 20 5b 52 4f 4c 4c 42 41 43 4b 20 7c 20 72  is [ROLLBACK | r
35bf0 6f 6c 6c 65 64 20 62 61 63 6b 5d 2e 0a 2a 2a 20  olled back]..** 
35c00 5e 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73 65  ^Any callback se
35c10 74 20 62 79 20 61 20 70 72 65 76 69 6f 75 73 20  t by a previous 
35c20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
35c30 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 0a  rollback_hook().
35c40 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20  ** for the same 
35c50 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
35c60 69 6f 6e 20 69 73 20 6f 76 65 72 72 69 64 64 65  ion is overridde
35c70 6e 2e 0a 2a 2a 20 5e 54 68 65 20 70 41 72 67 20  n..** ^The pArg 
35c80 61 72 67 75 6d 65 6e 74 20 69 73 20 70 61 73 73  argument is pass
35c90 65 64 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68  ed through to th
35ca0 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e  e callback..** ^
35cb0 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  If the callback 
35cc0 6f 6e 20 61 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b  on a commit hook
35cd0 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
35ce0 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 0a 2a 2a 20 74  s non-zero,.** t
35cf0 68 65 6e 20 74 68 65 20 63 6f 6d 6d 69 74 20 69  hen the commit i
35d00 73 20 63 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f  s converted into
35d10 20 61 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a   a rollback..**.
35d20 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
35d30 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 44 2c 43 2c  commit_hook(D,C,
35d40 50 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72  P) and sqlite3_r
35d50 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 44 2c 43  ollback_hook(D,C
35d60 2c 50 29 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a  ,P) functions.**
35d70 20 72 65 74 75 72 6e 20 74 68 65 20 50 20 61 72   return the P ar
35d80 67 75 6d 65 6e 74 20 66 72 6f 6d 20 74 68 65 20  gument from the 
35d90 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 6f 66  previous call of
35da0 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69   the same functi
35db0 6f 6e 0a 2a 2a 20 6f 6e 20 74 68 65 20 73 61 6d  on.** on the sam
35dc0 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
35dd0 65 63 74 69 6f 6e 5d 20 44 2c 20 6f 72 20 4e 55  ection] D, or NU
35de0 4c 4c 20 66 6f 72 0a 2a 2a 20 74 68 65 20 66 69  LL for.** the fi
35df0 72 73 74 20 63 61 6c 6c 20 66 6f 72 20 65 61 63  rst call for eac
35e00 68 20 66 75 6e 63 74 69 6f 6e 20 6f 6e 20 44 2e  h function on D.
35e10 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6d 6d 69  .**.** The commi
35e20 74 20 61 6e 64 20 72 6f 6c 6c 62 61 63 6b 20 68  t and rollback h
35e30 6f 6f 6b 20 63 61 6c 6c 62 61 63 6b 73 20 61 72  ook callbacks ar
35e40 65 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74 2e  e not reentrant.
35e50 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b  .** The callback
35e60 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
35e70 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74  must not do anyt
35e80 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d  hing that will m
35e90 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74  odify.** the dat
35ea0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
35eb0 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68   that invoked th
35ec0 65 20 63 61 6c 6c 62 61 63 6b 2e 20 20 41 6e 79  e callback.  Any
35ed0 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 74 6f 20 6d   actions.** to m
35ee0 6f 64 69 66 79 20 74 68 65 20 64 61 74 61 62 61  odify the databa
35ef0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75  se connection mu
35f00 73 74 20 62 65 20 64 65 66 65 72 72 65 64 20 75  st be deferred u
35f10 6e 74 69 6c 20 61 66 74 65 72 20 74 68 65 0a 2a  ntil after the.*
35f20 2a 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 6f 66 20  * completion of 
35f30 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  the [sqlite3_ste
35f40 70 28 29 5d 20 63 61 6c 6c 20 74 68 61 74 20 74  p()] call that t
35f50 72 69 67 67 65 72 65 64 20 74 68 65 20 63 6f 6d  riggered the com
35f60 6d 69 74 0a 2a 2a 20 6f 72 20 72 6f 6c 6c 62 61  mit.** or rollba
35f70 63 6b 20 68 6f 6f 6b 20 69 6e 20 74 68 65 20 66  ck hook in the f
35f80 69 72 73 74 20 70 6c 61 63 65 2e 0a 2a 2a 20 4e  irst place..** N
35f90 6f 74 65 20 74 68 61 74 20 72 75 6e 6e 69 6e 67  ote that running
35fa0 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 20 73   any other SQL s
35fb0 74 61 74 65 6d 65 6e 74 73 2c 20 69 6e 63 6c 75  tatements, inclu
35fc0 64 69 6e 67 20 53 45 4c 45 43 54 20 73 74 61 74  ding SELECT stat
35fd0 65 6d 65 6e 74 73 2c 0a 2a 2a 20 6f 72 20 6d 65  ements,.** or me
35fe0 72 65 6c 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71  rely calling [sq
35ff0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
36000 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
36010 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 6d 6f  _step()] will mo
36020 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61  dify.** the data
36030 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
36040 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67   for the meaning
36050 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20   of "modify" in 
36060 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a  this paragraph..
36070 2a 2a 0a 2a 2a 20 5e 52 65 67 69 73 74 65 72 69  **.** ^Registeri
36080 6e 67 20 61 20 4e 55 4c 4c 20 66 75 6e 63 74 69  ng a NULL functi
36090 6f 6e 20 64 69 73 61 62 6c 65 73 20 74 68 65 20  on disables the 
360a0 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20  callback..**.** 
360b0 5e 57 68 65 6e 20 74 68 65 20 63 6f 6d 6d 69 74  ^When the commit
360c0 20 68 6f 6f 6b 20 63 61 6c 6c 62 61 63 6b 20 72   hook callback r
360d0 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 7a  outine returns z
360e0 65 72 6f 2c 20 74 68 65 20 5b 43 4f 4d 4d 49 54  ero, the [COMMIT
360f0 5d 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 20 69  ].** operation i
36100 73 20 61 6c 6c 6f 77 65 64 20 74 6f 20 63 6f 6e  s allowed to con
36110 74 69 6e 75 65 20 6e 6f 72 6d 61 6c 6c 79 2e 20  tinue normally. 
36120 20 5e 49 66 20 74 68 65 20 63 6f 6d 6d 69 74 20   ^If the commit 
36130 68 6f 6f 6b 0a 2a 2a 20 72 65 74 75 72 6e 73 20  hook.** returns 
36140 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 74  non-zero, then t
36150 68 65 20 5b 43 4f 4d 4d 49 54 5d 20 69 73 20 63  he [COMMIT] is c
36160 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 61 20  onverted into a 
36170 5b 52 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a 20 5e  [ROLLBACK]..** ^
36180 54 68 65 20 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f  The rollback hoo
36190 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 20  k is invoked on 
361a0 61 20 72 6f 6c 6c 62 61 63 6b 20 74 68 61 74 20  a rollback that 
361b0 72 65 73 75 6c 74 73 20 66 72 6f 6d 20 61 20 63  results from a c
361c0 6f 6d 6d 69 74 0a 2a 2a 20 68 6f 6f 6b 20 72 65  ommit.** hook re
361d0 74 75 72 6e 69 6e 67 20 6e 6f 6e 2d 7a 65 72 6f  turning non-zero
361e0 2c 20 6a 75 73 74 20 61 73 20 69 74 20 77 6f 75  , just as it wou
361f0 6c 64 20 62 65 20 77 69 74 68 20 61 6e 79 20 6f  ld be with any o
36200 74 68 65 72 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a  ther rollback..*
36210 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20 70 75  *.** ^For the pu
36220 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20 41  rposes of this A
36230 50 49 2c 20 61 20 74 72 61 6e 73 61 63 74 69 6f  PI, a transactio
36240 6e 20 69 73 20 73 61 69 64 20 74 6f 20 68 61 76  n is said to hav
36250 65 20 62 65 65 6e 0a 2a 2a 20 72 6f 6c 6c 65 64  e been.** rolled
36260 20 62 61 63 6b 20 69 66 20 61 6e 20 65 78 70 6c   back if an expl
36270 69 63 69 74 20 22 52 4f 4c 4c 42 41 43 4b 22 20  icit "ROLLBACK" 
36280 73 74 61 74 65 6d 65 6e 74 20 69 73 20 65 78 65  statement is exe
36290 63 75 74 65 64 2c 20 6f 72 0a 2a 2a 20 61 6e 20  cuted, or.** an 
362a0 65 72 72 6f 72 20 6f 72 20 63 6f 6e 73 74 72 61  error or constra
362b0 69 6e 74 20 63 61 75 73 65 73 20 61 6e 20 69 6d  int causes an im
362c0 70 6c 69 63 69 74 20 72 6f 6c 6c 62 61 63 6b 20  plicit rollback 
362d0 74 6f 20 6f 63 63 75 72 2e 0a 2a 2a 20 5e 54 68  to occur..** ^Th
362e0 65 20 72 6f 6c 6c 62 61 63 6b 20 63 61 6c 6c 62  e rollback callb
362f0 61 63 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b  ack is not invok
36300 65 64 20 69 66 20 61 20 74 72 61 6e 73 61 63 74  ed if a transact
36310 69 6f 6e 20 69 73 0a 2a 2a 20 61 75 74 6f 6d 61  ion is.** automa
36320 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62  tically rolled b
36330 61 63 6b 20 62 65 63 61 75 73 65 20 74 68 65 20  ack because the 
36340 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
36350 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a  ion is closed..*
36360 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68  *.** See also th
36370 65 20 5b 73 71 6c 69 74 65 33 5f 75 70 64 61 74  e [sqlite3_updat
36380 65 5f 68 6f 6f 6b 28 29 5d 20 69 6e 74 65 72 66  e_hook()] interf
36390 61 63 65 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71  ace..*/.void *sq
363a0 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f  lite3_commit_hoo
363b0 6b 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28  k(sqlite3*, int(
363c0 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a  *)(void*), void*
363d0 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  );.void *sqlite3
363e0 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 73  _rollback_hook(s
363f0 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a 29  qlite3*, void(*)
36400 28 76 6f 69 64 20 2a 29 2c 20 76 6f 69 64 2a 29  (void *), void*)
36410 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
36420 46 3a 20 44 61 74 61 20 43 68 61 6e 67 65 20 4e  F: Data Change N
36430 6f 74 69 66 69 63 61 74 69 6f 6e 20 43 61 6c 6c  otification Call
36440 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  backs.**.** ^The
36450 20 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f   sqlite3_update_
36460 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 65  hook() interface
36470 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c   registers a cal
36480 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a  lback function.*
36490 2a 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61  * with the [data
364a0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
364b0 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 74   identified by t
364c0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
364d0 74 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 76 6f 6b  t.** to be invok
364e0 65 64 20 77 68 65 6e 65 76 65 72 20 61 20 72 6f  ed whenever a ro
364f0 77 20 69 73 20 75 70 64 61 74 65 64 2c 20 69 6e  w is updated, in
36500 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65  serted or delete
36510 64 2e 0a 2a 2a 20 5e 41 6e 79 20 63 61 6c 6c 62  d..** ^Any callb
36520 61 63 6b 20 73 65 74 20 62 79 20 61 20 70 72 65  ack set by a pre
36530 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 74 68  vious call to th
36540 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 66  is function.** f
36550 6f 72 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  or the same data
36560 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
36570 69 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a  is overridden..*
36580 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64  *.** ^The second
36590 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70   argument is a p
365a0 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 66 75  ointer to the fu
365b0 6e 63 74 69 6f 6e 20 74 6f 20 69 6e 76 6f 6b 65  nction to invoke
365c0 20 77 68 65 6e 20 61 0a 2a 2a 20 72 6f 77 20 69   when a.** row i
365d0 73 20 75 70 64 61 74 65 64 2c 20 69 6e 73 65 72  s updated, inser
365e0 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64 2e 0a  ted or deleted..
365f0 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72  ** ^The first ar
36600 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 63 61  gument to the ca
36610 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79  llback is a copy
36620 20 6f 66 20 74 68 65 20 74 68 69 72 64 20 61 72   of the third ar
36630 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 73 71 6c  gument.** to sql
36640 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b  ite3_update_hook
36650 28 29 2e 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f  ()..** ^The seco
36660 6e 64 20 63 61 6c 6c 62 61 63 6b 20 61 72 67 75  nd callback argu
36670 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 5b  ment is one of [
36680 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 5d 2c 20  SQLITE_INSERT], 
36690 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 2c  [SQLITE_DELETE],
366a0 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55  .** or [SQLITE_U
366b0 50 44 41 54 45 5d 2c 20 64 65 70 65 6e 64 69 6e  PDATE], dependin
366c0 67 20 6f 6e 20 74 68 65 20 6f 70 65 72 61 74 69  g on the operati
366d0 6f 6e 20 74 68 61 74 20 63 61 75 73 65 64 20 74  on that caused t
366e0 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74  he callback.** t
366f0 6f 20 62 65 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a  o be invoked..**
36700 20 5e 54 68 65 20 74 68 69 72 64 20 61 6e 64 20   ^The third and 
36710 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 73  fourth arguments
36720 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
36730 20 63 6f 6e 74 61 69 6e 20 70 6f 69 6e 74 65 72   contain pointer
36740 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61  s to the.** data
36750 62 61 73 65 20 61 6e 64 20 74 61 62 6c 65 20 6e  base and table n
36760 61 6d 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  ame containing t
36770 68 65 20 61 66 66 65 63 74 65 64 20 72 6f 77 2e  he affected row.
36780 0a 2a 2a 20 5e 54 68 65 20 66 69 6e 61 6c 20 63  .** ^The final c
36790 61 6c 6c 62 61 63 6b 20 70 61 72 61 6d 65 74 65  allback paramete
367a0 72 20 69 73 20 74 68 65 20 5b 72 6f 77 69 64 5d  r is the [rowid]
367b0 20 6f 66 20 74 68 65 20 72 6f 77 2e 0a 2a 2a 20   of the row..** 
367c0 5e 49 6e 20 74 68 65 20 63 61 73 65 20 6f 66 20  ^In the case of 
367d0 61 6e 20 75 70 64 61 74 65 2c 20 74 68 69 73 20  an update, this 
367e0 69 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 61  is the [rowid] a
367f0 66 74 65 72 20 74 68 65 20 75 70 64 61 74 65 20  fter the update 
36800 74 61 6b 65 73 20 70 6c 61 63 65 2e 0a 2a 2a 0a  takes place..**.
36810 2a 2a 20 5e 28 54 68 65 20 75 70 64 61 74 65 20  ** ^(The update 
36820 68 6f 6f 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f  hook is not invo
36830 6b 65 64 20 77 68 65 6e 20 69 6e 74 65 72 6e 61  ked when interna
36840 6c 20 73 79 73 74 65 6d 20 74 61 62 6c 65 73 20  l system tables 
36850 61 72 65 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 20  are.** modified 
36860 28 69 2e 65 2e 20 73 71 6c 69 74 65 5f 6d 61 73  (i.e. sqlite_mas
36870 74 65 72 20 61 6e 64 20 73 71 6c 69 74 65 5f 73  ter and sqlite_s
36880 65 71 75 65 6e 63 65 29 2e 29 5e 0a 2a 2a 0a 2a  equence).)^.**.*
36890 2a 20 5e 49 6e 20 74 68 65 20 63 75 72 72 65 6e  * ^In the curren
368a0 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  t implementation
368b0 2c 20 74 68 65 20 75 70 64 61 74 65 20 68 6f 6f  , the update hoo
368c0 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 69 6e 76 6f  k.** is not invo
368d0 6b 65 64 20 77 68 65 6e 20 64 75 70 6c 69 63 61  ked when duplica
368e0 74 69 6f 6e 20 72 6f 77 73 20 61 72 65 20 64 65  tion rows are de
368f0 6c 65 74 65 64 20 62 65 63 61 75 73 65 20 6f 66  leted because of
36900 20 61 6e 0a 2a 2a 20 5b 4f 4e 20 43 4f 4e 46 4c   an.** [ON CONFL
36910 49 43 54 20 7c 20 4f 4e 20 43 4f 4e 46 4c 49 43  ICT | ON CONFLIC
36920 54 20 52 45 50 4c 41 43 45 5d 20 63 6c 61 75 73  T REPLACE] claus
36930 65 2e 20 20 5e 4e 6f 72 20 69 73 20 74 68 65 20  e.  ^Nor is the 
36940 75 70 64 61 74 65 20 68 6f 6f 6b 0a 2a 2a 20 69  update hook.** i
36950 6e 76 6f 6b 65 64 20 77 68 65 6e 20 72 6f 77 73  nvoked when rows
36960 20 61 72 65 20 64 65 6c 65 74 65 64 20 75 73 69   are deleted usi
36970 6e 67 20 74 68 65 20 5b 74 72 75 6e 63 61 74 65  ng the [truncate
36980 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 2e 0a   optimization]..
36990 2a 2a 20 54 68 65 20 65 78 63 65 70 74 69 6f 6e  ** The exception
369a0 73 20 64 65 66 69 6e 65 64 20 69 6e 20 74 68 69  s defined in thi
369b0 73 20 70 61 72 61 67 72 61 70 68 20 6d 69 67 68  s paragraph migh
369c0 74 20 63 68 61 6e 67 65 20 69 6e 20 61 20 66 75  t change in a fu
369d0 74 75 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65 20  ture.** release 
369e0 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a  of SQLite..**.**
369f0 20 54 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b   The update hook
36a00 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
36a10 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74  must not do anyt
36a20 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d  hing that will m
36a30 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74  odify.** the dat
36a40 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
36a50 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68   that invoked th
36a60 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 2e 20 20  e update hook.  
36a70 41 6e 79 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 74  Any actions.** t
36a80 6f 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74  o modify the dat
36a90 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
36aa0 20 6d 75 73 74 20 62 65 20 64 65 66 65 72 72 65   must be deferre
36ab0 64 20 75 6e 74 69 6c 20 61 66 74 65 72 20 74 68  d until after th
36ac0 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 69 6f 6e 20  e.** completion 
36ad0 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
36ae0 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 74 68 61  step()] call tha
36af0 74 20 74 72 69 67 67 65 72 65 64 20 74 68 65 20  t triggered the 
36b00 75 70 64 61 74 65 20 68 6f 6f 6b 2e 0a 2a 2a 20  update hook..** 
36b10 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74  Note that [sqlit
36b20 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
36b30 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74   and [sqlite3_st
36b40 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66  ep()] both modif
36b50 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62  y their.** datab
36b60 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20  ase connections 
36b70 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20  for the meaning 
36b80 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74  of "modify" in t
36b90 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a  his paragraph..*
36ba0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
36bb0 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 44 2c  3_update_hook(D,
36bc0 43 2c 50 29 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  C,P) function.**
36bd0 20 72 65 74 75 72 6e 73 20 74 68 65 20 50 20 61   returns the P a
36be0 72 67 75 6d 65 6e 74 20 66 72 6f 6d 20 74 68 65  rgument from the
36bf0 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 0a 2a   previous call.*
36c00 2a 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 64  * on the same [d
36c10 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
36c20 6f 6e 5d 20 44 2c 20 6f 72 20 4e 55 4c 4c 20 66  on] D, or NULL f
36c30 6f 72 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20  or.** the first 
36c40 63 61 6c 6c 20 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a  call on D..**.**
36c50 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73   See also the [s
36c60 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f  qlite3_commit_ho
36c70 6f 6b 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  ok()] and [sqlit
36c80 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b  e3_rollback_hook
36c90 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  ()].** interface
36ca0 73 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69  s..*/.void *sqli
36cb0 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28  te3_update_hook(
36cc0 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20  .  sqlite3*, .  
36cd0 76 6f 69 64 28 2a 29 28 76 6f 69 64 20 2a 2c 69  void(*)(void *,i
36ce0 6e 74 20 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a  nt ,char const *
36cf0 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a 2c 73 71  ,char const *,sq
36d00 6c 69 74 65 33 5f 69 6e 74 36 34 29 2c 0a 20 20  lite3_int64),.  
36d10 76 6f 69 64 2a 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  void*.);../*.** 
36d20 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65  CAPI3REF: Enable
36d30 20 4f 72 20 44 69 73 61 62 6c 65 20 53 68 61 72   Or Disable Shar
36d40 65 64 20 50 61 67 65 72 20 43 61 63 68 65 0a 2a  ed Pager Cache.*
36d50 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f 75 74  *.** ^(This rout
36d60 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72 20 64  ine enables or d
36d70 69 73 61 62 6c 65 73 20 74 68 65 20 73 68 61 72  isables the shar
36d80 69 6e 67 20 6f 66 20 74 68 65 20 64 61 74 61 62  ing of the datab
36d90 61 73 65 20 63 61 63 68 65 0a 2a 2a 20 61 6e 64  ase cache.** and
36da0 20 73 63 68 65 6d 61 20 64 61 74 61 20 73 74 72   schema data str
36db0 75 63 74 75 72 65 73 20 62 65 74 77 65 65 6e 20  uctures between 
36dc0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
36dd0 74 69 6f 6e 20 7c 20 63 6f 6e 6e 65 63 74 69 6f  tion | connectio
36de0 6e 73 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 73 61  ns].** to the sa
36df0 6d 65 20 64 61 74 61 62 61 73 65 2e 20 53 68 61  me database. Sha
36e00 72 69 6e 67 20 69 73 20 65 6e 61 62 6c 65 64 20  ring is enabled 
36e10 69 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20  if the argument 
36e20 69 73 20 74 72 75 65 0a 2a 2a 20 61 6e 64 20 64  is true.** and d
36e30 69 73 61 62 6c 65 64 20 69 66 20 74 68 65 20 61  isabled if the a
36e40 72 67 75 6d 65 6e 74 20 69 73 20 66 61 6c 73 65  rgument is false
36e50 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 43 61 63 68 65  .)^.**.** ^Cache
36e60 20 73 68 61 72 69 6e 67 20 69 73 20 65 6e 61 62   sharing is enab
36e70 6c 65 64 20 61 6e 64 20 64 69 73 61 62 6c 65 64  led and disabled
36e80 20 66 6f 72 20 61 6e 20 65 6e 74 69 72 65 20 70   for an entire p
36e90 72 6f 63 65 73 73 2e 0a 2a 2a 20 54 68 69 73 20  rocess..** This 
36ea0 69 73 20 61 20 63 68 61 6e 67 65 20 61 73 20 6f  is a change as o
36eb0 66 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  f SQLite version
36ec0 20 33 2e 35 2e 30 2e 20 49 6e 20 70 72 69 6f 72   3.5.0. In prior
36ed0 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
36ee0 69 74 65 2c 0a 2a 2a 20 73 68 61 72 69 6e 67 20  ite,.** sharing 
36ef0 77 61 73 20 65 6e 61 62 6c 65 64 20 6f 72 20 64  was enabled or d
36f00 69 73 61 62 6c 65 64 20 66 6f 72 20 65 61 63 68  isabled for each
36f10 20 74 68 72 65 61 64 20 73 65 70 61 72 61 74 65   thread separate
36f20 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  ly..**.** ^(The 
36f30 63 61 63 68 65 20 73 68 61 72 69 6e 67 20 6d 6f  cache sharing mo
36f40 64 65 20 73 65 74 20 62 79 20 74 68 69 73 20 69  de set by this i
36f50 6e 74 65 72 66 61 63 65 20 65 66 66 65 63 74 73  nterface effects
36f60 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 0a   all subsequent.
36f70 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  ** calls to [sql
36f80 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73  ite3_open()], [s
36f90 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
36fa0 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ], and [sqlite3_
36fb0 6f 70 65 6e 31 36 28 29 5d 2e 0a 2a 2a 20 45 78  open16()]..** Ex
36fc0 69 73 74 69 6e 67 20 64 61 74 61 62 61 73 65 20  isting database 
36fd0 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 63 6f 6e 74  connections cont
36fe0 69 6e 75 65 20 75 73 65 20 74 68 65 20 73 68 61  inue use the sha
36ff0 72 69 6e 67 20 6d 6f 64 65 0a 2a 2a 20 74 68 61  ring mode.** tha
37000 74 20 77 61 73 20 69 6e 20 65 66 66 65 63 74 20  t was in effect 
37010 61 74 20 74 68 65 20 74 69 6d 65 20 74 68 65 79  at the time they
37020 20 77 65 72 65 20 6f 70 65 6e 65 64 2e 29 5e 0a   were opened.)^.
37030 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f 75  **.** ^(This rou
37040 74 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 51  tine returns [SQ
37050 4c 49 54 45 5f 4f 4b 5d 20 69 66 20 73 68 61 72  LITE_OK] if shar
37060 65 64 20 63 61 63 68 65 20 77 61 73 20 65 6e 61  ed cache was ena
37070 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64  bled or disabled
37080 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79  .** successfully
37090 2e 20 20 41 6e 20 5b 65 72 72 6f 72 20 63 6f 64  .  An [error cod
370a0 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 6f  e] is returned o
370b0 74 68 65 72 77 69 73 65 2e 29 5e 0a 2a 2a 0a 2a  therwise.)^.**.*
370c0 2a 20 5e 53 68 61 72 65 64 20 63 61 63 68 65 20  * ^Shared cache 
370d0 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 20 64  is disabled by d
370e0 65 66 61 75 6c 74 2e 20 42 75 74 20 74 68 69 73  efault. But this
370f0 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20 69 6e   might change in
37100 0a 2a 2a 20 66 75 74 75 72 65 20 72 65 6c 65 61  .** future relea
37110 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20  ses of SQLite.  
37120 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  Applications tha
37130 74 20 63 61 72 65 20 61 62 6f 75 74 20 73 68 61  t care about sha
37140 72 65 64 0a 2a 2a 20 63 61 63 68 65 20 73 65 74  red.** cache set
37150 74 69 6e 67 20 73 68 6f 75 6c 64 20 73 65 74 20  ting should set 
37160 69 74 20 65 78 70 6c 69 63 69 74 6c 79 2e 0a 2a  it explicitly..*
37170 2a 0a 2a 2a 20 53 65 65 20 41 6c 73 6f 3a 20 20  *.** See Also:  
37180 5b 53 51 4c 69 74 65 20 53 68 61 72 65 64 2d 43  [SQLite Shared-C
37190 61 63 68 65 20 4d 6f 64 65 5d 0a 2a 2f 0a 69 6e  ache Mode].*/.in
371a0 74 20 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65  t sqlite3_enable
371b0 5f 73 68 61 72 65 64 5f 63 61 63 68 65 28 69 6e  _shared_cache(in
371c0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
371d0 52 45 46 3a 20 41 74 74 65 6d 70 74 20 54 6f 20  REF: Attempt To 
371e0 46 72 65 65 20 48 65 61 70 20 4d 65 6d 6f 72 79  Free Heap Memory
371f0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
37200 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f  te3_release_memo
37210 72 79 28 29 20 69 6e 74 65 72 66 61 63 65 20 61  ry() interface a
37220 74 74 65 6d 70 74 73 20 74 6f 20 66 72 65 65 20  ttempts to free 
37230 4e 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 68 65  N bytes.** of he
37240 61 70 20 6d 65 6d 6f 72 79 20 62 79 20 64 65 61  ap memory by dea
37250 6c 6c 6f 63 61 74 69 6e 67 20 6e 6f 6e 2d 65 73  llocating non-es
37260 73 65 6e 74 69 61 6c 20 6d 65 6d 6f 72 79 20 61  sential memory a
37270 6c 6c 6f 63 61 74 69 6f 6e 73 0a 2a 2a 20 68 65  llocations.** he
37280 6c 64 20 62 79 20 74 68 65 20 64 61 74 61 62 61  ld by the databa
37290 73 65 20 6c 69 62 72 61 72 79 2e 20 20 20 4d 65  se library.   Me
372a0 6d 6f 72 79 20 75 73 65 64 20 74 6f 20 63 61 63  mory used to cac
372b0 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 70  he database.** p
372c0 61 67 65 73 20 74 6f 20 69 6d 70 72 6f 76 65 20  ages to improve 
372d0 70 65 72 66 6f 72 6d 61 6e 63 65 20 69 73 20 61  performance is a
372e0 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 6e 6f 6e  n example of non
372f0 2d 65 73 73 65 6e 74 69 61 6c 20 6d 65 6d 6f 72  -essential memor
37300 79 2e 0a 2a 2a 20 5e 73 71 6c 69 74 65 33 5f 72  y..** ^sqlite3_r
37310 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 20  elease_memory() 
37320 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
37330 65 72 20 6f 66 20 62 79 74 65 73 20 61 63 74 75  er of bytes actu
37340 61 6c 6c 79 20 66 72 65 65 64 2c 0a 2a 2a 20 77  ally freed,.** w
37350 68 69 63 68 20 6d 69 67 68 74 20 62 65 20 6d 6f  hich might be mo
37360 72 65 20 6f 72 20 6c 65 73 73 20 74 68 61 6e 20  re or less than 
37370 74 68 65 20 61 6d 6f 75 6e 74 20 72 65 71 75 65  the amount reque
37380 73 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  sted..** ^The sq
37390 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65  lite3_release_me
373a0 6d 6f 72 79 28 29 20 72 6f 75 74 69 6e 65 20 69  mory() routine i
373b0 73 20 61 20 6e 6f 2d 6f 70 20 72 65 74 75 72 6e  s a no-op return
373c0 69 6e 67 20 7a 65 72 6f 0a 2a 2a 20 69 66 20 53  ing zero.** if S
373d0 51 4c 69 74 65 20 69 73 20 6e 6f 74 20 63 6f 6d  QLite is not com
373e0 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c 49  piled with [SQLI
373f0 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 4f 52 59  TE_ENABLE_MEMORY
37400 5f 4d 41 4e 41 47 45 4d 45 4e 54 5d 2e 0a 2a 2a  _MANAGEMENT]..**
37410 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
37420 71 6c 69 74 65 33 5f 64 62 5f 72 65 6c 65 61 73  qlite3_db_releas
37430 65 5f 6d 65 6d 6f 72 79 28 29 5d 0a 2a 2f 0a 69  e_memory()].*/.i
37440 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 6c 65 61  nt sqlite3_relea
37450 73 65 5f 6d 65 6d 6f 72 79 28 69 6e 74 29 3b 0a  se_memory(int);.
37460 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
37470 20 46 72 65 65 20 4d 65 6d 6f 72 79 20 55 73 65   Free Memory Use
37480 64 20 42 79 20 41 20 44 61 74 61 62 61 73 65 20  d By A Database 
37490 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a  Connection.**.**
374a0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62   ^The sqlite3_db
374b0 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28  _release_memory(
374c0 44 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 74  D) interface att
374d0 65 6d 70 74 73 20 74 6f 20 66 72 65 65 20 61 73  empts to free as
374e0 20 6d 75 63 68 20 68 65 61 70 0a 2a 2a 20 6d 65   much heap.** me
374f0 6d 6f 72 79 20 61 73 20 70 6f 73 73 69 62 6c 65  mory as possible
37500 20 66 72 6f 6d 20 64 61 74 61 62 61 73 65 20 63   from database c
37510 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 55 6e 6c  onnection D. Unl
37520 69 6b 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  ike the.** [sqli
37530 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f  te3_release_memo
37540 72 79 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2c  ry()] interface,
37550 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   this interface 
37560 69 73 20 65 66 66 65 63 74 20 65 76 65 6e 0a 2a  is effect even.*
37570 2a 20 77 68 65 6e 20 74 68 65 6e 20 5b 53 51 4c  * when then [SQL
37580 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 4f 52  ITE_ENABLE_MEMOR
37590 59 5f 4d 41 4e 41 47 45 4d 45 4e 54 5d 20 63 6f  Y_MANAGEMENT] co
375a0 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
375b0 6e 20 69 73 0a 2a 2a 20 6f 6d 69 74 74 65 64 2e  n is.** omitted.
375c0 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
375d0 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73   [sqlite3_releas
375e0 65 5f 6d 65 6d 6f 72 79 28 29 5d 0a 2a 2f 0a 69  e_memory()].*/.i
375f0 6e 74 20 73 71 6c 69 74 65 33 5f 64 62 5f 72 65  nt sqlite3_db_re
37600 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 73 71 6c  lease_memory(sql
37610 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
37620 41 50 49 33 52 45 46 3a 20 49 6d 70 6f 73 65 20  API3REF: Impose 
37630 41 20 4c 69 6d 69 74 20 4f 6e 20 48 65 61 70 20  A Limit On Heap 
37640 53 69 7a 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  Size.**.** ^The 
37650 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61  sqlite3_soft_hea
37660 70 5f 6c 69 6d 69 74 36 34 28 29 20 69 6e 74 65  p_limit64() inte
37670 72 66 61 63 65 20 73 65 74 73 20 61 6e 64 2f 6f  rface sets and/o
37680 72 20 71 75 65 72 69 65 73 20 74 68 65 0a 2a 2a  r queries the.**
37690 20 73 6f 66 74 20 6c 69 6d 69 74 20 6f 6e 20 74   soft limit on t
376a0 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 68 65 61  he amount of hea
376b0 70 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 6d 61  p memory that ma
376c0 79 20 62 65 20 61 6c 6c 6f 63 61 74 65 64 20 62  y be allocated b
376d0 79 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 5e 53 51  y SQLite..** ^SQ
376e0 4c 69 74 65 20 73 74 72 69 76 65 73 20 74 6f 20  Lite strives to 
376f0 6b 65 65 70 20 68 65 61 70 20 6d 65 6d 6f 72 79  keep heap memory
37700 20 75 74 69 6c 69 7a 61 74 69 6f 6e 20 62 65 6c   utilization bel
37710 6f 77 20 74 68 65 20 73 6f 66 74 20 68 65 61 70  ow the soft heap
37720 0a 2a 2a 20 6c 69 6d 69 74 20 62 79 20 72 65 64  .** limit by red
37730 75 63 69 6e 67 20 74 68 65 20 6e 75 6d 62 65 72  ucing the number
37740 20 6f 66 20 70 61 67 65 73 20 68 65 6c 64 20 69   of pages held i
37750 6e 20 74 68 65 20 70 61 67 65 20 63 61 63 68 65  n the page cache
37760 0a 2a 2a 20 61 73 20 68 65 61 70 20 6d 65 6d 6f  .** as heap memo
37770 72 79 20 75 73 61 67 65 73 20 61 70 70 72 6f 61  ry usages approa
37780 63 68 65 73 20 74 68 65 20 6c 69 6d 69 74 2e 0a  ches the limit..
37790 2a 2a 20 5e 54 68 65 20 73 6f 66 74 20 68 65 61  ** ^The soft hea
377a0 70 20 6c 69 6d 69 74 20 69 73 20 22 73 6f 66 74  p limit is "soft
377b0 22 20 62 65 63 61 75 73 65 20 65 76 65 6e 20 74  " because even t
377c0 68 6f 75 67 68 20 53 51 4c 69 74 65 20 73 74 72  hough SQLite str
377d0 69 76 65 73 20 74 6f 20 73 74 61 79 0a 2a 2a 20  ives to stay.** 
377e0 62 65 6c 6f 77 20 74 68 65 20 6c 69 6d 69 74 2c  below the limit,
377f0 20 69 74 20 77 69 6c 6c 20 65 78 63 65 65 64 20   it will exceed 
37800 74 68 65 20 6c 69 6d 69 74 20 72 61 74 68 65 72  the limit rather
37810 20 74 68 61 6e 20 67 65 6e 65 72 61 74 65 0a 2a   than generate.*
37820 2a 20 61 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d  * an [SQLITE_NOM
37830 45 4d 5d 20 65 72 72 6f 72 2e 20 20 49 6e 20 6f  EM] error.  In o
37840 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20  ther words, the 
37850 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20  soft heap limit 
37860 0a 2a 2a 20 69 73 20 61 64 76 69 73 6f 72 79 20  .** is advisory 
37870 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  only..**.** ^The
37880 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72   return value fr
37890 6f 6d 20 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f  om sqlite3_soft_
378a0 68 65 61 70 5f 6c 69 6d 69 74 36 34 28 29 20 69  heap_limit64() i
378b0 73 20 74 68 65 20 73 69 7a 65 20 6f 66 0a 2a 2a  s the size of.**
378c0 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c   the soft heap l
378d0 69 6d 69 74 20 70 72 69 6f 72 20 74 6f 20 74 68  imit prior to th
378e0 65 20 63 61 6c 6c 2c 20 6f 72 20 6e 65 67 61 74  e call, or negat
378f0 69 76 65 20 69 6e 20 74 68 65 20 63 61 73 65 20  ive in the case 
37900 6f 66 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 2e 20  of an.** error. 
37910 20 5e 49 66 20 74 68 65 20 61 72 67 75 6d 65 6e   ^If the argumen
37920 74 20 4e 20 69 73 20 6e 65 67 61 74 69 76 65 0a  t N is negative.
37930 2a 2a 20 74 68 65 6e 20 6e 6f 20 63 68 61 6e 67  ** then no chang
37940 65 20 69 73 20 6d 61 64 65 20 74 6f 20 74 68 65  e is made to the
37950 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74   soft heap limit
37960 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20 63 75  .  Hence, the cu
37970 72 72 65 6e 74 0a 2a 2a 20 73 69 7a 65 20 6f 66  rrent.** size of
37980 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c   the soft heap l
37990 69 6d 69 74 20 63 61 6e 20 62 65 20 64 65 74 65  imit can be dete
379a0 72 6d 69 6e 65 64 20 62 79 20 69 6e 76 6f 6b 69  rmined by invoki
379b0 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 6f  ng.** sqlite3_so
379c0 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28  ft_heap_limit64(
379d0 29 20 77 69 74 68 20 61 20 6e 65 67 61 74 69 76  ) with a negativ
379e0 65 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a  e argument..**.*
379f0 2a 20 5e 49 66 20 74 68 65 20 61 72 67 75 6d 65  * ^If the argume
37a00 6e 74 20 4e 20 69 73 20 7a 65 72 6f 20 74 68 65  nt N is zero the
37a10 6e 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20  n the soft heap 
37a20 6c 69 6d 69 74 20 69 73 20 64 69 73 61 62 6c 65  limit is disable
37a30 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73  d..**.** ^(The s
37a40 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69  oft heap limit i
37a50 73 20 6e 6f 74 20 65 6e 66 6f 72 63 65 64 20 69  s not enforced i
37a60 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 69 6d  n the current im
37a70 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20  plementation.** 
37a80 69 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f  if one or more o
37a90 66 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 6f 6e 64  f following cond
37aa0 69 74 69 6f 6e 73 20 61 72 65 20 74 72 75 65 3a  itions are true:
37ab0 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
37ac0 6c 69 3e 20 54 68 65 20 73 6f 66 74 20 68 65 61  li> The soft hea
37ad0 70 20 6c 69 6d 69 74 20 69 73 20 73 65 74 20 74  p limit is set t
37ae0 6f 20 7a 65 72 6f 2e 0a 2a 2a 20 3c 6c 69 3e 20  o zero..** <li> 
37af0 4d 65 6d 6f 72 79 20 61 63 63 6f 75 6e 74 69 6e  Memory accountin
37b00 67 20 69 73 20 64 69 73 61 62 6c 65 64 20 75 73  g is disabled us
37b10 69 6e 67 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f  ing a combinatio
37b20 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20  n of the.**     
37b30 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
37b40 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ]([SQLITE_CONFIG
37b50 5f 4d 45 4d 53 54 41 54 55 53 5d 2c 2e 2e 2e 29  _MEMSTATUS],...)
37b60 20 73 74 61 72 74 2d 74 69 6d 65 20 6f 70 74 69   start-time opti
37b70 6f 6e 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 74  on and.**      t
37b80 68 65 20 5b 53 51 4c 49 54 45 5f 44 45 46 41 55  he [SQLITE_DEFAU
37b90 4c 54 5f 4d 45 4d 53 54 41 54 55 53 5d 20 63 6f  LT_MEMSTATUS] co
37ba0 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
37bb0 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20 41 6e 20 61 6c  n..** <li> An al
37bc0 74 65 72 6e 61 74 69 76 65 20 70 61 67 65 20 63  ternative page c
37bd0 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  ache implementat
37be0 69 6f 6e 20 69 73 20 73 70 65 63 69 66 69 65 64  ion is specified
37bf0 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20 5b   using.**      [
37c00 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28  sqlite3_config](
37c10 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  [SQLITE_CONFIG_P
37c20 43 41 43 48 45 32 5d 2c 2e 2e 2e 29 2e 0a 2a 2a  CACHE2],...)..**
37c30 20 3c 6c 69 3e 20 54 68 65 20 70 61 67 65 20 63   <li> The page c
37c40 61 63 68 65 20 61 6c 6c 6f 63 61 74 65 73 20 66  ache allocates f
37c50 72 6f 6d 20 69 74 73 20 6f 77 6e 20 6d 65 6d 6f  rom its own memo
37c60 72 79 20 70 6f 6f 6c 20 73 75 70 70 6c 69 65 64  ry pool supplied
37c70 0a 2a 2a 20 20 20 20 20 20 62 79 20 5b 73 71 6c  .**      by [sql
37c80 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51  ite3_config]([SQ
37c90 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45  LITE_CONFIG_PAGE
37ca0 43 41 43 48 45 5d 2c 2e 2e 2e 29 20 72 61 74 68  CACHE],...) rath
37cb0 65 72 20 74 68 61 6e 0a 2a 2a 20 20 20 20 20 20  er than.**      
37cc0 66 72 6f 6d 20 74 68 65 20 68 65 61 70 2e 0a 2a  from the heap..*
37cd0 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20  * </ul>)^.**.** 
37ce0 42 65 67 69 6e 6e 69 6e 67 20 77 69 74 68 20 53  Beginning with S
37cf0 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e  QLite version 3.
37d00 37 2e 33 2c 20 74 68 65 20 73 6f 66 74 20 68 65  7.3, the soft he
37d10 61 70 20 6c 69 6d 69 74 20 69 73 20 65 6e 66 6f  ap limit is enfo
37d20 72 63 65 64 0a 2a 2a 20 72 65 67 61 72 64 6c 65  rced.** regardle
37d30 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72  ss of whether or
37d40 20 6e 6f 74 20 74 68 65 20 5b 53 51 4c 49 54 45   not the [SQLITE
37d50 5f 45 4e 41 42 4c 45 5f 4d 45 4d 4f 52 59 5f 4d  _ENABLE_MEMORY_M
37d60 41 4e 41 47 45 4d 45 4e 54 5d 0a 2a 2a 20 63 6f  ANAGEMENT].** co
37d70 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
37d80 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 57  n is invoked.  W
37d90 69 74 68 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42  ith [SQLITE_ENAB
37da0 4c 45 5f 4d 45 4d 4f 52 59 5f 4d 41 4e 41 47 45  LE_MEMORY_MANAGE
37db0 4d 45 4e 54 5d 2c 0a 2a 2a 20 74 68 65 20 73 6f  MENT],.** the so
37dc0 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69 73  ft heap limit is
37dd0 20 65 6e 66 6f 72 63 65 64 20 6f 6e 20 65 76 65   enforced on eve
37de0 72 79 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ry memory alloca
37df0 74 69 6f 6e 2e 20 20 57 69 74 68 6f 75 74 0a 2a  tion.  Without.*
37e00 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  * [SQLITE_ENABLE
37e10 5f 4d 45 4d 4f 52 59 5f 4d 41 4e 41 47 45 4d 45  _MEMORY_MANAGEME
37e20 4e 54 5d 2c 20 74 68 65 20 73 6f 66 74 20 68 65  NT], the soft he
37e30 61 70 20 6c 69 6d 69 74 20 69 73 20 6f 6e 6c 79  ap limit is only
37e40 20 65 6e 66 6f 72 63 65 64 0a 2a 2a 20 77 68 65   enforced.** whe
37e50 6e 20 6d 65 6d 6f 72 79 20 69 73 20 61 6c 6c 6f  n memory is allo
37e60 63 61 74 65 64 20 62 79 20 74 68 65 20 70 61 67  cated by the pag
37e70 65 20 63 61 63 68 65 2e 20 20 54 65 73 74 69 6e  e cache.  Testin
37e80 67 20 73 75 67 67 65 73 74 73 20 74 68 61 74 20  g suggests that 
37e90 62 65 63 61 75 73 65 0a 2a 2a 20 74 68 65 20 70  because.** the p
37ea0 61 67 65 20 63 61 63 68 65 20 69 73 20 74 68 65  age cache is the
37eb0 20 70 72 65 64 6f 6d 69 6e 61 74 65 20 6d 65 6d   predominate mem
37ec0 6f 72 79 20 75 73 65 72 20 69 6e 20 53 51 4c 69  ory user in SQLi
37ed0 74 65 2c 20 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c  te, most.** appl
37ee0 69 63 61 74 69 6f 6e 73 20 77 69 6c 6c 20 61 63  ications will ac
37ef0 68 69 65 76 65 20 61 64 65 71 75 61 74 65 20 73  hieve adequate s
37f00 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 65  oft heap limit e
37f10 6e 66 6f 72 63 65 6d 65 6e 74 20 77 69 74 68 6f  nforcement witho
37f20 75 74 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f 66  ut.** the use of
37f30 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f   [SQLITE_ENABLE_
37f40 4d 45 4d 4f 52 59 5f 4d 41 4e 41 47 45 4d 45 4e  MEMORY_MANAGEMEN
37f50 54 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 69  T]..**.** The ci
37f60 72 63 75 6d 73 74 61 6e 63 65 73 20 75 6e 64 65  rcumstances unde
37f70 72 20 77 68 69 63 68 20 53 51 4c 69 74 65 20 77  r which SQLite w
37f80 69 6c 6c 20 65 6e 66 6f 72 63 65 20 74 68 65 20  ill enforce the 
37f90 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20  soft heap limit 
37fa0 6d 61 79 0a 2a 2a 20 63 68 61 6e 67 65 73 20 69  may.** changes i
37fb0 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  n future release
37fc0 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a  s of SQLite..*/.
37fd0 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71  sqlite3_int64 sq
37fe0 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f  lite3_soft_heap_
37ff0 6c 69 6d 69 74 36 34 28 73 71 6c 69 74 65 33 5f  limit64(sqlite3_
38000 69 6e 74 36 34 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a  int64 N);../*.**
38010 20 43 41 50 49 33 52 45 46 3a 20 44 65 70 72 65   CAPI3REF: Depre
38020 63 61 74 65 64 20 53 6f 66 74 20 48 65 61 70 20  cated Soft Heap 
38030 4c 69 6d 69 74 20 49 6e 74 65 72 66 61 63 65 0a  Limit Interface.
38040 2a 2a 20 44 45 50 52 45 43 41 54 45 44 0a 2a 2a  ** DEPRECATED.**
38050 0a 2a 2a 20 54 68 69 73 20 69 73 20 61 20 64 65  .** This is a de
38060 70 72 65 63 61 74 65 64 20 76 65 72 73 69 6f 6e  precated version
38070 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
38080 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74  _soft_heap_limit
38090 36 34 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61  64()].** interfa
380a0 63 65 2e 20 20 54 68 69 73 20 72 6f 75 74 69 6e  ce.  This routin
380b0 65 20 69 73 20 70 72 6f 76 69 64 65 64 20 66 6f  e is provided fo
380c0 72 20 68 69 73 74 6f 72 69 63 61 6c 20 63 6f 6d  r historical com
380d0 70 61 74 69 62 69 6c 69 74 79 0a 2a 2a 20 6f 6e  patibility.** on
380e0 6c 79 2e 20 20 41 6c 6c 20 6e 65 77 20 61 70 70  ly.  All new app
380f0 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64  lications should
38100 20 75 73 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c   use the.** [sql
38110 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c  ite3_soft_heap_l
38120 69 6d 69 74 36 34 28 29 5d 20 69 6e 74 65 72 66  imit64()] interf
38130 61 63 65 20 72 61 74 68 65 72 20 74 68 61 6e 20  ace rather than 
38140 74 68 69 73 20 6f 6e 65 2e 0a 2a 2f 0a 53 51 4c  this one..*/.SQL
38150 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 76  ITE_DEPRECATED v
38160 6f 69 64 20 73 71 6c 69 74 65 33 5f 73 6f 66 74  oid sqlite3_soft
38170 5f 68 65 61 70 5f 6c 69 6d 69 74 28 69 6e 74 20  _heap_limit(int 
38180 4e 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  N);.../*.** CAPI
38190 33 52 45 46 3a 20 45 78 74 72 61 63 74 20 4d 65  3REF: Extract Me
381a0 74 61 64 61 74 61 20 41 62 6f 75 74 20 41 20 43  tadata About A C
381b0 6f 6c 75 6d 6e 20 4f 66 20 41 20 54 61 62 6c 65  olumn Of A Table
381c0 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75  .**.** ^This rou
381d0 74 69 6e 65 20 72 65 74 75 72 6e 73 20 6d 65 74  tine returns met
381e0 61 64 61 74 61 20 61 62 6f 75 74 20 61 20 73 70  adata about a sp
381f0 65 63 69 66 69 63 20 63 6f 6c 75 6d 6e 20 6f 66  ecific column of
38200 20 61 20 73 70 65 63 69 66 69 63 0a 2a 2a 20 64   a specific.** d
38210 61 74 61 62 61 73 65 20 74 61 62 6c 65 20 61 63  atabase table ac
38220 63 65 73 73 69 62 6c 65 20 75 73 69 6e 67 20 74  cessible using t
38230 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
38240 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 0a  nection] handle.
38250 2a 2a 20 70 61 73 73 65 64 20 61 73 20 74 68 65  ** passed as the
38260 20 66 69 72 73 74 20 66 75 6e 63 74 69 6f 6e 20   first function 
38270 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  argument..**.** 
38280 5e 54 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 69  ^The column is i
38290 64 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 65  dentified by the
382a0 20 73 65 63 6f 6e 64 2c 20 74 68 69 72 64 20 61   second, third a
382b0 6e 64 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  nd fourth parame
382c0 74 65 72 73 20 74 6f 0a 2a 2a 20 74 68 69 73 20  ters to.** this 
382d0 66 75 6e 63 74 69 6f 6e 2e 20 5e 54 68 65 20 73  function. ^The s
382e0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
382f0 69 73 20 65 69 74 68 65 72 20 74 68 65 20 6e 61  is either the na
38300 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  me of the databa
38310 73 65 0a 2a 2a 20 28 69 2e 65 2e 20 22 6d 61 69  se.** (i.e. "mai
38320 6e 22 2c 20 22 74 65 6d 70 22 2c 20 6f 72 20 61  n", "temp", or a
38330 6e 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62  n attached datab
38340 61 73 65 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20  ase) containing 
38350 74 68 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a  the specified.**
38360 20 74 61 62 6c 65 20 6f 72 20 4e 55 4c 4c 2e 20   table or NULL. 
38370 5e 49 66 20 69 74 20 69 73 20 4e 55 4c 4c 2c 20  ^If it is NULL, 
38380 74 68 65 6e 20 61 6c 6c 20 61 74 74 61 63 68 65  then all attache
38390 64 20 64 61 74 61 62 61 73 65 73 20 61 72 65 20  d databases are 
383a0 73 65 61 72 63 68 65 64 0a 2a 2a 20 66 6f 72 20  searched.** for 
383b0 74 68 65 20 74 61 62 6c 65 20 75 73 69 6e 67 20  the table using 
383c0 74 68 65 20 73 61 6d 65 20 61 6c 67 6f 72 69 74  the same algorit
383d0 68 6d 20 75 73 65 64 20 62 79 20 74 68 65 20 64  hm used by the d
383e0 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65 20 74  atabase engine t
383f0 6f 0a 2a 2a 20 72 65 73 6f 6c 76 65 20 75 6e 71  o.** resolve unq
38400 75 61 6c 69 66 69 65 64 20 74 61 62 6c 65 20 72  ualified table r
38410 65 66 65 72 65 6e 63 65 73 2e 0a 2a 2a 0a 2a 2a  eferences..**.**
38420 20 5e 54 68 65 20 74 68 69 72 64 20 61 6e 64 20   ^The third and 
38430 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
38440 73 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69  s to this functi
38450 6f 6e 20 61 72 65 20 74 68 65 20 74 61 62 6c 65  on are the table
38460 20 61 6e 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 6e   and column.** n
38470 61 6d 65 20 6f 66 20 74 68 65 20 64 65 73 69 72  ame of the desir
38480 65 64 20 63 6f 6c 75 6d 6e 2c 20 72 65 73 70 65  ed column, respe
38490 63 74 69 76 65 6c 79 2e 20 4e 65 69 74 68 65 72  ctively. Neither
384a0 20 6f 66 20 74 68 65 73 65 20 70 61 72 61 6d 65   of these parame
384b0 74 65 72 73 0a 2a 2a 20 6d 61 79 20 62 65 20 4e  ters.** may be N
384c0 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4d 65 74 61  ULL..**.** ^Meta
384d0 64 61 74 61 20 69 73 20 72 65 74 75 72 6e 65 64  data is returned
384e0 20 62 79 20 77 72 69 74 69 6e 67 20 74 6f 20 74   by writing to t
384f0 68 65 20 6d 65 6d 6f 72 79 20 6c 6f 63 61 74 69  he memory locati
38500 6f 6e 73 20 70 61 73 73 65 64 20 61 73 20 74 68  ons passed as th
38510 65 20 35 74 68 0a 2a 2a 20 61 6e 64 20 73 75 62  e 5th.** and sub
38520 73 65 71 75 65 6e 74 20 70 61 72 61 6d 65 74 65  sequent paramete
38530 72 73 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74  rs to this funct
38540 69 6f 6e 2e 20 5e 41 6e 79 20 6f 66 20 74 68 65  ion. ^Any of the
38550 73 65 20 61 72 67 75 6d 65 6e 74 73 20 6d 61 79  se arguments may
38560 20 62 65 0a 2a 2a 20 4e 55 4c 4c 2c 20 69 6e 20   be.** NULL, in 
38570 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20 63  which case the c
38580 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 65 6c 65  orresponding ele
38590 6d 65 6e 74 20 6f 66 20 6d 65 74 61 64 61 74 61  ment of metadata
385a0 20 69 73 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a 0a   is omitted..**.
385b0 2a 2a 20 5e 28 3c 62 6c 6f 63 6b 71 75 6f 74 65  ** ^(<blockquote
385c0 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64  >.** <table bord
385d0 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c  er="1">.** <tr><
385e0 74 68 3e 20 50 61 72 61 6d 65 74 65 72 20 3c 74  th> Parameter <t
385f0 68 3e 20 4f 75 74 70 75 74 3c 62 72 3e 54 79 70  h> Output<br>Typ
38600 65 20 3c 74 68 3e 20 20 44 65 73 63 72 69 70 74  e <th>  Descript
38610 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74  ion.**.** <tr><t
38620 64 3e 20 35 74 68 20 3c 74 64 3e 20 63 6f 6e 73  d> 5th <td> cons
38630 74 20 63 68 61 72 2a 20 3c 74 64 3e 20 44 61 74  t char* <td> Dat
38640 61 20 74 79 70 65 0a 2a 2a 20 3c 74 72 3e 3c 74  a type.** <tr><t
38650 64 3e 20 36 74 68 20 3c 74 64 3e 20 63 6f 6e 73  d> 6th <td> cons
38660 74 20 63 68 61 72 2a 20 3c 74 64 3e 20 4e 61 6d  t char* <td> Nam
38670 65 20 6f 66 20 64 65 66 61 75 6c 74 20 63 6f 6c  e of default col
38680 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 0a  lation sequence.
38690 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 37 74 68 20  ** <tr><td> 7th 
386a0 3c 74 64 3e 20 69 6e 74 20 20 20 20 20 20 20 20  <td> int        
386b0 20 3c 74 64 3e 20 54 72 75 65 20 69 66 20 63 6f   <td> True if co
386c0 6c 75 6d 6e 20 68 61 73 20 61 20 4e 4f 54 20 4e  lumn has a NOT N
386d0 55 4c 4c 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a  ULL constraint.*
386e0 2a 20 3c 74 72 3e 3c 74 64 3e 20 38 74 68 20 3c  * <tr><td> 8th <
386f0 74 64 3e 20 69 6e 74 20 20 20 20 20 20 20 20 20  td> int         
38700 3c 74 64 3e 20 54 72 75 65 20 69 66 20 63 6f 6c  <td> True if col
38710 75 6d 6e 20 69 73 20 70 61 72 74 20 6f 66 20 74  umn is part of t
38720 68 65 20 50 52 49 4d 41 52 59 20 4b 45 59 0a 2a  he PRIMARY KEY.*
38730 2a 20 3c 74 72 3e 3c 74 64 3e 20 39 74 68 20 3c  * <tr><td> 9th <
38740 74 64 3e 20 69 6e 74 20 20 20 20 20 20 20 20 20  td> int         
38750 3c 74 64 3e 20 54 72 75 65 20 69 66 20 63 6f 6c  <td> True if col
38760 75 6d 6e 20 69 73 20 5b 41 55 54 4f 49 4e 43 52  umn is [AUTOINCR
38770 45 4d 45 4e 54 5d 0a 2a 2a 20 3c 2f 74 61 62 6c  EMENT].** </tabl
38780 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f  e>.** </blockquo
38790 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  te>)^.**.** ^The
387a0 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 64 20   memory pointed 
387b0 74 6f 20 62 79 20 74 68 65 20 63 68 61 72 61 63  to by the charac
387c0 74 65 72 20 70 6f 69 6e 74 65 72 73 20 72 65 74  ter pointers ret
387d0 75 72 6e 65 64 20 66 6f 72 20 74 68 65 0a 2a 2a  urned for the.**
387e0 20 64 65 63 6c 61 72 61 74 69 6f 6e 20 74 79 70   declaration typ
387f0 65 20 61 6e 64 20 63 6f 6c 6c 61 74 69 6f 6e 20  e and collation 
38800 73 65 71 75 65 6e 63 65 20 69 73 20 76 61 6c 69  sequence is vali
38810 64 20 6f 6e 6c 79 20 75 6e 74 69 6c 20 74 68 65  d only until the
38820 20 6e 65 78 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f   next.** call to
38830 20 61 6e 79 20 53 51 4c 69 74 65 20 41 50 49 20   any SQLite API 
38840 66 75 6e 63 74 69 6f 6e 2e 0a 2a